@sassoftware/vi-api/property/property-api.d.ts

Types used in the SAS Visual Investigator API

import { ControlAttributeMap, IBaseControlAttribute, IGenericControlAttribute } from "../config/control-attribute-types";
import { Control } from "../control/page";
import { ChildNode, TypeAttributes } from "../object/object-api";
import { PageTemplateMetadata } from "../page-model/page-model-api";
export interface ToolbarPropertyControl {
    typeAttributes: TypeAttributes;
}
export interface EntityToolbarItem {
    actionName: string;
    attributes: {
        [attr: string]: any;
    };
}
export type PropertyConfig<T = any> = ControlAttributeMap<T>[keyof ControlAttributeMap<T>] | IBaseControlAttribute | IGenericControlAttribute;
export interface SelectedNode {
    id: number;
    node: ChildNode;
    parentNode?: ChildNode;
    parentSubDocument: string;
    dataSources?: {
        [property: string]: any;
    };
}
export type LocalizerType = "page" | "toolbar";
export type ControlPropertyLocalizer = ToolbarControlPropertyLocalizer | PageControlPropertyLocalizer;
export interface ToolbarControlPropertyLocalizer extends PropertyLocalizer<EntityToolbarItem> {
    localizerType: "toolbar";
    /**
     * Generate resources to be included when the toolbar item is saved.
     *
     * @param propertyKey the control attribute
     * @param control the toolbar item
     * @returns the resource keys and values for the given toolbar item property
     */
    createResources: (propertyKey: string, control: EntityToolbarItem) => Record<string, string>;
    /**
     * Use generated resource keys & values to localize the given control property.
     *
     * @param propertyKey the control attribute to be localized
     * @param control the toolbar item
     * @param resources toolbar item resources
     */
    localizeControlAttribute: (propertyKey: string, control: EntityToolbarItem, resources: Record<string, string>) => void;
}
export interface PageControlPropertyLocalizer extends PropertyLocalizer<Control> {
    localizerType: "page";
    /**
     * Generate resources to be included when the page control is saved.
     * Page control resources are stored on the page template metadata
     * and so resource keys should be made to be unique per control.
     *
     * @param propertyKey the control attribute
     * @param control the page control
     * @returns the resource keys and values for the given control property
     */
    createResources: (propertyKey: string, control: Control) => Record<string, string>;
    /**
     * Use generated resource keys & values to localize the given control property.
     *
     * @param propertyKey the control attribute to be localized
     * @param control the page control
     * @param resources page template resources
     */
    localizeControlAttribute: (propertyKey: string, control: Control, resources: Record<string, string>) => void;
}
/**
 * Handle the localization of control properties for a given property type.
 */
export interface PropertyLocalizer<T> {
    /**
     * Control type to be localized,
     */
    localizerType: LocalizerType;
    /**
     * Property type to be localized.
     * (the type that the property editor is registered against)
     */
    propertyType: string;
    createResources: (propertyKey: string, control: T) => Record<string, string>;
    localizeControlAttribute: (propertyKey: string, control: T, resources: Record<string, string>) => void;
}
/**
 * This API is available on property editors.
 */
export interface EditorApi {
    /**
     * Registers a function to be invoked whenever one of the editor's properties changes.
     * @method
     * @param handler The function to be invoked.
     * @returns A function that stops the handler from being invoked.
     */
    onPropertyChange(handler: (category: string, property: string, currentValue: any, previousValue: any) => void): () => void;
}
/**
 * This API pertains to page/toolbar control properties in SAS Visual Investigator.
 *
 * Accessed from the window at `window.sas.vi.property`.
 *
 * @example window.sas.vi.property.registerPropertyLocalizer(localizer);
 * @category API
 */
export interface PropertyApi {
    /**
     * @method
     * @description Registers a custom element to be rendered as the property editor.
     * The element is rendered as a custom web component.
     * The element is passed selectedNode, property, propertyKey, and categoryKey as attributes.
     * Throws a console error if the type is already used by another registered editor.
     * @param elementName {string} Element to be rendered. For example, "custom-editor" renders an element with the tag name "custom-editor".
     * @param type {string} A custom type that is expected to be unique among registered editors.
     * @param [validatorFn] {PropertyApi~isPropertyEditorValid} Function to provide custom logic for determining if the editor is valid.
     * @param [metadataFn] {PropertyApi~getPropertyEditorMetadata} Function to provide custom metadata.
     */
    registerCustomEditor(elementName: string, type: string, validatorFn?: (propertyConfig: PropertyConfig, propertyKey: string, control: Control | ToolbarPropertyControl) => boolean, metadataFn?: (propertyConfig: PropertyConfig, propertyKey: string, control: Control | ToolbarPropertyControl) => PageTemplateMetadata): void;
    /**
     * Register a localizer to manage internationalization resources for control properties of a given type.
     * Properties will be localized unless they they are explicitly configured with localizable=false (see {@link PropertyConfig})
     * @param localizer property localizer which defines resource keys to be saved, and parses the same keys to localize the properties.
     */
    registerPropertyLocalizer(localizer: ControlPropertyLocalizer): void;
    /**
     * @method
     * @description Determines whether the child object data source property editor is valid.
     * Typically passed as a function reference to registerCustomEditor() instead of being called directly.
     * @param {PropertyConfig} propertyConfig Configuration details relating to the property type. For example, required, type, and so on.
     * @param {string} propertyKey Key where this property's value is stored.
     * @param {Control | ToolbarPropertyControl} control The control.
     * @example
     * window.sas.vi.property.registerCustomEditor(
     *     name,
     *     type,
     *     window.sas.vi.property.validateChildObjectDataSource,
     *     window.sas.vi.property.getChildObjectMetadata)
     */
    validateChildObjectDataSource(propertyConfig: PropertyConfig, propertyKey: string, control: Control): boolean | undefined;
    /**
     * @method
     * @description Get metadata for the child object data source property editor.
     * Typically passed as a function reference to registerCustomEditor() instead of being called directly.
     * @param {PropertyConfig} propertyConfig Configuration details relating to the property type. For example, required, type, and so on.
     * @param {string} propertyKey Key where this property's value is stored.
     * @param {Control | ToolbarPropertyControl} control The control.
     * @example
     * window.sas.vi.property.registerCustomEditor(
     *     name,
     *     type,
     *     window.sas.vi.property.validateChildObjectDataSource,
     *     window.sas.vi.property.getChildObjectMetadata)
     */
    getChildObjectMetadata(propertyConfig: PropertyConfig, propertyKey: string, control: Control): PageTemplateMetadata | undefined;
}
/**
 * Determines whether the property editor is valid.
 * @callback PropertyApi~isPropertyEditorValid
 * @param {PropertyConfig} propertyConfig Configuration details relating to the custom property type. For example, required, type, and so on.
 * @param {string} propertyKey Key where this property's value is stored.
 * @param {Control | ToolbarPropertyControl} control The control.
 * @returns {boolean} true if valid, false if not.
 */
/**
 * Get metadata for the property editor.
 * @callback PropertyApi~getPropertyEditorMetadata
 * @param {PropertyConfig} propertyConfig Configuration details relating to the custom property type. For example, required, type, and so on.
 * @param {string} propertyKey Key where this property's value is stored.
 * @param {Control | ToolbarPropertyControl} control The control.
 * @returns {PageTemplateMetadata}
 */