@sassoftware/vi-api 0.0.29

package/control/control-api.d.ts

@@ -0,0 +1,450 @@
+import { FileChange, SASObjectAttachedFile, SASUploadedFile } from "../file/file-api";
+import { PageMode, PageModel } from "../page-model/page-model-api";
+import { FieldType, FieldTypeToValue } from "./data-types";
+import { PageDataChange, PageModeChange, StateChange } from "./events";
+import { Control, RefreshablePageControlOptions, SlidingPanelProperties, TypeAttributes } from "./page";
+import { FieldTypeToRestrictions, FileRestrictions } from "./restrictions";
+import { AttachmentFormData } from "./file";
+/**
+ * The minimum API that should be supported on control members across solutions.
+ */
+export interface ControlMemberApiBase<ControlTypeAttributes extends TypeAttributes = TypeAttributes, ControlFieldType extends FieldType = never> {
+    /**
+     * Methods related to this control.
+     */
+    readonly control: ControlApiBase<ControlTypeAttributes, ControlFieldType>;
+    /**
+     * Methods related to the entire page.
+     */
+    readonly page: ControlPageApiBase;
+}
+/**
+ * {@link ControlMemberApiBase} extension that provides more functionality.
+ * @extends ControlMemberApiBase
+ */
+export interface ControlMemberApi<ControlTypeAttributes extends TypeAttributes = TypeAttributes, ControlFieldType extends FieldType = any> extends ControlMemberApiBase<ControlTypeAttributes, ControlFieldType> {
+    /**
+     * Methods related to this control
+     */
+    readonly control: ControlApi<ControlTypeAttributes, ControlFieldType>;
+    /**
+     * Methods related to the entire page the control is on.
+     */
+    readonly page: ControlPageApi;
+    /**
+     * Methods available when administering this control.
+     */
+    readonly admin: ControlAdminApi;
+}
+/**
+ * This Control API pertains functionality that checks the state, registers event handlers and so on.
+ */
+export interface ControlApiBase<ControlTypeAttributes extends TypeAttributes = TypeAttributes, ControlFieldType extends FieldType = never> {
+    /**
+     * Methods related to the state of the control.
+     */
+    readonly state: ControlStateApi;
+    /** Control type. */
+    readonly type: string;
+    /**
+     * Sets the value of the control's field.
+     * Field must be configured as dataSource in the control's typeAttributes.
+     * @method
+     * @param value {FieldTypeToValue<ControlFieldType>} New field value.
+     */
+    setFieldValue(value: FieldTypeToValue<ControlFieldType>): void;
+    /**
+     * Gives the value of the control's field.
+     * Field must be configured as dataSource in the control's typeAttributes.
+     * @method
+     * @returns The value of the control's field.
+     */
+    getFieldValue(): FieldTypeToValue<ControlFieldType>;
+    /**
+     * Returns the field restrictions that are associated with the calling control.
+     * Field must be configured as dataSource in the control's typeAttributes.
+     * @method
+     * @returns The field restrictions that should be applied.
+     */
+    getFieldRestrictions(): FieldTypeToRestrictions<ControlFieldType>;
+    /**
+     * Returns the restrictions of the control's file category.
+     * File category must be configured as fileCategory in the control's typeAttributes.
+     * @method
+     * @returns The file restrictions that should be applied.
+     */
+    getFileRestrictions(): FileRestrictions;
+    /**
+     * Returns the calling control object.
+     * @method
+     * @returns Object representing the calling control.
+     */
+    getControl(): Control<ControlTypeAttributes>;
+}
+/**
+ * This API pertains to administration functionality for controls, for example registering resources.
+ */
+export interface ControlAdminApi {
+    /**
+     * Registers a function to be invoked when retrieving this control's internationalization resources.
+     * @method
+     * @param fn {function} a function that returns each internationalization resource's key and value.
+     * No parameters. Return type: Record<string, string>
+     */
+    registerGetI18nResourcesFn(fn: () => Record<string, string>): void;
+}
+/**
+ * Extension of {@link ControlApiBase} supplied by SAS Visual Investigator to provide more functionality.
+ * @extends ControlApiBase
+ */
+export interface ControlApi<ControlTypeAttributes extends TypeAttributes = TypeAttributes, ControlFieldType extends FieldType = never> extends ControlApiBase<ControlTypeAttributes, ControlFieldType> {
+    /**
+     * Methods related to the state of the control.
+     */
+    readonly state: ControlStateApi;
+    /**
+     * Space for component specific API functions.
+     */
+    readonly component?: any;
+    /**
+     * Returns the calling control's parent object.
+     * @method
+     * @returns Object representing the calling control's parent.
+     */
+    getParentControl(): Control | undefined;
+    /**
+     * Returns the parent ancestor with the given type for this control.
+     * @method
+     * @param ofType {string} Type of ancestor to be returned.
+     * @returns Object representing the calling control's ancestor, or undefined if no match.
+     */
+    getAncestorControl(ofType: string): Control | undefined;
+    /**
+     * Returns a string that can be used as an aria label for the field, which includes its required state.
+     * Uses the typeAttributes.title.text field for the label.
+     * @method
+     * @returns The aria label that should be applied.
+     */
+    getAriaLabel: () => string;
+}
+/**
+ * Methods and properties related to the state of the control.
+ */
+export interface ControlStateApi {
+    /**
+     * Returns the read-only state of the calling control.
+     * True if the control is read-only, otherwise false.
+     */
+    readonly readOnly: boolean;
+    /**
+     * Returns the required state of the calling control.
+     * True if control is required, otherwise false.
+     */
+    readonly required: boolean;
+    /**
+     * Checks if the current controls should allow input.
+     * Returns True if the control allows input, otherwise false.
+     */
+    readonly allowInput: boolean;
+    /**
+     * Returns if this control could be read-only based on a condition.
+     * True if the control could be read-only, otherwise false.
+     */
+    readonly couldBeReadOnly: boolean;
+    /**
+     * Returns if this control could be required based on a condition.
+     * True if the control could be required, otherwise false.
+     */
+    readonly couldBeRequired: boolean;
+    /**
+     * Returns the hidden state of the calling control.
+     * True if the control is hidden, otherwise false.
+     */
+    readonly hidden: boolean;
+    /**
+     * Registers a function to be invoked whenever a state change event occurs.
+     * This function receives an object that contains information about the change event.
+     *
+     * @method
+     * @param handler {function} Function to be invoked when a state is changed.
+     * Parameter (change: StateChange). Returns void.
+     */
+    onChange(handler: (change: StateChange) => void): void;
+    /**
+     * Re-evaluates the status of all control states.
+     * @method
+     */
+    update(): void;
+}
+/**
+ * API methods related to object fields associated with a page.
+ */
+export interface ControlPageFieldApi {
+    /**
+     * Sets the value of the supplied field.
+     * This works only with fields for the current object for which the control is associated.
+     * For example, if the control is on a parent object, you cannot set a child's field.
+     * @method
+     * @param value {FieldTypeToValue<Type>} New field value.
+     * @param field {string} Field name.
+     */
+    setFieldValue<Type extends FieldType>(value: FieldTypeToValue<Type>, field: string): void;
+    /**
+     * Returns the value of the supplied field.
+     * This works only with fields for the current object for which the control is associated with.
+     * For example, if the control is on a parent object, you cannot get a child's field.
+     * @method
+     * @template {FieldType} File type.
+     * @param field {string} Field name.
+     */
+    getFieldValue<Type extends FieldType>(field: string): FieldTypeToValue<Type>;
+    /**
+     * Returns the field restrictions that are associated with the calling control.
+     * @method
+     * @template {FieldType} Field type.
+     * @param field {string} Field name to get restrictions for.
+     * @returns Applied field restrictions.
+     */
+    getFieldRestrictions<Type extends FieldType>(field: string): FieldTypeToRestrictions<Type>;
+}
+/**
+ * Methods related to the page to which a control belongs.
+ * @class
+ */
+export interface ControlPageApiBase {
+    /**
+     * Methods related to files associated with the page.
+     */
+    readonly file: ControlFileApiBase;
+    /**
+     * The object ID, if applicable. Otherwise "".
+     */
+    readonly objectId: string;
+    /**
+     * The object name, if applicable. Otherwise "".
+     */
+    readonly objectName: string;
+    /**
+     * Checks if the object is external.
+     */
+    readonly isExternalObject: boolean;
+    /**
+     * Checks if the page is a home page.
+     */
+    readonly isHomepage: boolean;
+    /**
+     * Returns the mode of the page on which the calling control resides.
+     * @method
+     * @returns The current PageMode.
+     */
+    getMode(): PageMode;
+    /**
+     * Methods that relate to object fields associated with the page.
+     */
+    readonly field: ControlPageFieldApi;
+    /**
+     * Registers a function to be invoked whenever a relevant change happens.
+     * The handler receives an object that gives information about the change event.
+     * There are two types of changes -
+     *    PageDataChange when the data in the page model changes,
+     *    and PageModeChange when the page mode changes.
+     * @method
+     * @param handler {function} Function to be invoked when there is a change.
+     * Parameter (change) is of type PageDataChange or PageModeChange.
+     * Returns void.
+     */
+    onChange(handler: (change: PageDataChange | PageModeChange) => void): void;
+}
+/**
+ * {@link ControlPageApiBase} extension that provides more functionality.
+ * @extends ControlPageApiBase
+ */
+export interface ControlPageApi extends ControlPageApiBase {
+    /**
+     * Methods related to the files associated with the page.
+     */
+    file: ControlFileApi;
+    /**
+     * Returns the model of the page in which the calling control resides.
+     * @method
+     * @returns The current page model object.
+     */
+    getPageModel(): PageModel;
+    /**
+     * Registers a function to be invoked whenever one of the calling control's properties change.
+     * @method
+     * @param handler {function} Function to be invoked on property change.
+     * Parameters are (category: string, property: string, currentValue: any, previousValue: any).
+     * Returns void.
+     */
+    onPropertyChange(handler: (category: string, property: string, currentValue: any, previousValue: any) => void): void;
+    /**
+     * Returns the disabled status of the page toolbar.
+     * @method
+     * @returns True, if the toolbar is disabled. Otherwise false.
+     */
+    isToolbarDisabled(): boolean;
+    /**
+     * Triggers a certain type of notification for users.
+     * For example, a type EDIT_FAIL notification if a sheet has failed to be added to a workspace.
+     * @method
+     * @param notification {string} Message to be displayed on the notification.
+     * @param type {string} Type of notification. For example LOCK, EDIT_FAIL, VERSION_MISMATCH.
+     * @param [autoDismissDuration] {number} Length of time before the notification should be dismissed.
+     */
+    raiseNotification(notification: string, type: string, autoDismissDuration?: number): void;
+    /**
+     * Adds a refreshable control to the page.
+     * @method
+     * @param control {Control} Control to add.
+     * @param refreshFn {function} Function to be called when the control is refreshed. There are no parameters. Returns void.
+     * @param [options] {RefreshablePageControlOptions} Options to be added to the refreshable control.
+     */
+    addRefreshableControl(control: Control, refreshFn: () => void, options?: RefreshablePageControlOptions): void;
+    /**
+     * Removes a refreshable control from the page.
+     * @method
+     * @param controlToRemove {Control} Control to be removed.
+     */
+    removeRefreshableControl(controlToRemove: Control): void;
+    /**
+     * Refreshes a control when updated data is displayed.
+     * By default, attempts to refresh all controls.
+     * Specify categoryToRefresh or controlToRefresh to restrict what is refreshed.
+     * @method
+     * @param categoryToRefresh {(string|undefined)} Name of the category to be refreshed.
+     * @param [controlToRefresh] {Control} Individual control to be refreshed.
+     */
+    reloadRefreshableControls(categoryToRefresh: string | undefined, controlToRefresh: Control): void;
+    /**
+     * Sets a page to be dirty, that is, when it has been edited and not saved.
+     * @method
+     */
+    setPageDirty(): void;
+    /**
+     * Toggle the page-level sliding panel. This panel should be used to contain information that is
+     * supplementary to the document, for example attachments or workflow tasks.
+     * @method
+     * @param sectionLabel {string} Describes the section, this should be internationalised.
+     * @param contentUrl {string} Contains the template URL of the contents to be ng-included.
+     * @param [panelProperties] {SlidingPanelProperties} Properties that are exposed to the template from the caller.
+     * @param [onClose] {function} A callback function invoked when the panel is dismissed. There are no parameters. Returns void.
+     */
+    toggleSlidingPanel(sectionLabel: string, contentUrl: string, panelProperties?: SlidingPanelProperties, onClose?: () => void): void;
+    /**
+     * Checks if a page is in edit mode.
+     * @method
+     * @returns A boolean value that checks whether or not a page is in edit mode. Undefined if there is no page model.
+     */
+    isInEditMode(): boolean | undefined;
+    /**
+     * Takes a page out of edit mode. Promise resolves with a boolean value to determine if the user has saved or not.
+     * If the user has not saved, the user is prompted to do so.
+     * @method
+     * @param closeTab {boolean} Checks if the tab should close after edit mode is cancelled.
+     * @returns A promise that resolves once the edit has been cancelled.
+     */
+    cancelEdit(closeTab: boolean): Promise<{
+        userSaved: boolean;
+    }>;
+    /**
+     * Sets the page to be in edit mode. Used when clicking the Edit button.
+     * @method
+     * @returns A promise that resolves when the page is put in edit mode.
+     */
+    edit(): Promise<any>;
+    /**
+     * Refreshes the attachments grid to display new attachments when new attachment is uploaded.
+     * @method
+     */
+    refreshAttachments(): void;
+    /**
+     * Reloads an instance of a page.
+     * @method
+     * @returns A promise that resolves when the page is reloaded.
+     */
+    reloadPage(): Promise<void>;
+    /**
+     * Saves a page after editing.
+     * @method
+     * @param stopEditing {boolean} Checks if the page should leave edit mode after it is saved.
+     * @param closeObject {boolean} Checks if the page should be closed after it is saved.
+     * @returns A promise which resolves when the page has been saved.
+     */
+    save(stopEditing: boolean, closeObject: boolean): Promise<void>;
+}
+/**
+ * Methods related to files
+ */
+export interface ControlFileApiBase {
+    /**
+     * Returns the restrictions of the control's file category.
+     * @method
+     * @param [category] {string} Get restrictions for the file category name.
+     * @returns The file restrictions that should be applied.
+     */
+    getFileRestrictions(category: string): FileRestrictions;
+}
+/**
+ * {@link ControlFileApiBase} extension that provides more functionality.
+ * @extends ControlFileApiBase
+ */
+export interface ControlFileApi extends ControlFileApiBase {
+    /**
+     * Opens the file upload dialog.
+     *
+     * @method
+     * @param {IAttachmentFormData} options Additional options to pass to the file upload dialog.
+     * @returns {Promise<SASObjectAttachedFile[]>} Promise which resolves to an array of uploaded files.
+     */
+    openFileUploadDialog(options: AttachmentFormData): Promise<SASObjectAttachedFile[]>;
+    /**
+     * Opens the image upload dialog.
+     *
+     * @method
+     * @param {boolean} allowMultiple Determines if multiple files can be uploaded at once.
+     * @param {number} [maxSize=] Maximum size of the image to be uploaded, in bytes.
+     * @returns {Promise<SASObjectAttachedFile[]>} A Promise which resolves to an array of uploaded files.
+     */
+    openImageUploadDialog(allowMultiple: boolean, maxSize?: number): Promise<SASObjectAttachedFile[]>;
+    /**
+     * Returns all saved and unsaved files associated with the current object.
+     *
+     * @method
+     * @param {string} [category=] An optional file category to filter by.
+     * @returns {Promise<SASObjectAttachedFile[]>} A Promise which resolves to an array of files.
+     */
+    getFiles(category?: string): Promise<SASObjectAttachedFile[]>;
+    /**
+     * Creates a file operation to upload a new file.
+     *
+     * @method
+     * @param {SASUploadedFile} file The new file to upload.
+     * @returns {Promise<void>} A Promise that resolves when the file operation has been created.
+     */
+    addFile(file: SASUploadedFile): Promise<void>;
+    /**
+     * Creates a file operation to update a given file.
+     *
+     * @method
+     * @param {SASUploadedFile} updatedFile The updated file.
+     * @returns {Promise<void>} A Promise that resolves when the file operation has been created.
+     */
+    updateFile(updatedFile: SASUploadedFile): Promise<void>;
+    /**
+     * Create a file operation to remove a file with a given ID.
+     *
+     * @method
+     * @param {string} id The ID of the file to remove.
+     * @returns {Promise<void>} A Promise that resolves when the file operation has been created.
+     */
+    removeFile(id: string): Promise<void>;
+    /**
+     * Registers a function to be invoked whenever a file change event occurs.
+     * This function receives an object that contains information about the change event.
+     *
+     * @method
+     * @param {Function} handler A function to be invoked when a file change event occurs.
+     */
+    onChange(handler: (change: FileChange) => void): void;
+}

package/control/control-api.js

@@ -0,0 +1 @@
+export {};

package/control/data-types.d.ts

@@ -0,0 +1,9 @@
+export declare type FieldType = "STRING" | "BOOLEAN" | "REFERENCEDATA" | "USER_GROUP" | "JSON" | DateDataType | NumberDataType;
+export declare type NumberDataType = "SMALLINT" | "INTEGER" | "LONG" | "FLOAT" | "DOUBLE" | "NUMERIC";
+export declare type DateDataType = "DATE" | "TIMESTAMP" | "TIMESTAMP_WITH_TIME_ZONE";
+export interface UserGroup {
+    id: string;
+    type: "user" | "group";
+}
+export declare type FieldTypeToValue<Type extends FieldType> = Type extends "BOOLEAN" ? boolean : Type extends "STRING" | DateDataType | "REFERENCEDATA" ? string : Type extends NumberDataType ? number : Type extends "JSON" ? object : Type extends "USER_GROUP" ? UserGroup[] : never;
+export declare type FieldValue = undefined | string | number | boolean | object | UserGroup;

package/control/data-types.js

@@ -0,0 +1 @@
+export {};

package/control/events.d.ts

@@ -0,0 +1,75 @@
+import { PageMode } from "../page-model/page-model-api";
+import { FieldValue } from "./data-types";
+import { TypeAttributes } from "./page";
+export interface ModeChange {
+    type: "mode";
+    value: {
+        new: PageMode;
+        old: PageMode;
+    };
+}
+export interface FieldChange<Value extends FieldValue> {
+    type: "field";
+    value: {
+        new: Value | undefined;
+        old: Value | undefined;
+    };
+    field: string;
+    /**
+     * The object name, if applicable. Otherwise, "".
+     */
+    objectName: string;
+    /**
+     * The object position, for child objects only.
+     */
+    objectPosition?: number;
+}
+export interface ControlConfigChange<ControlTypeAttributes extends TypeAttributes> {
+    type: "controlConfig";
+    config: TypeAttributesChange<ControlTypeAttributes> | ConfigStateChange;
+}
+export declare type TypeAttributesChange<ControlTypeAttributes extends TypeAttributes, Property extends keyof ControlTypeAttributes = keyof ControlTypeAttributes> = Property extends any ? {
+    type: "typeAttributes";
+    value: {
+        new: ControlTypeAttributes[Property];
+        old: ControlTypeAttributes[Property];
+    };
+    property: Property;
+} : never;
+export interface ConfigStateChange {
+    type: "configState";
+    value: {
+        new: boolean;
+        old: boolean;
+    };
+    property: "readOnly" | "hidden" | "required";
+}
+export interface PageModelData {
+    [property: string]: any;
+}
+export declare enum ChangeType {
+    PAGE_MODE = "mode",
+    PAGE_DATA = "pageData"
+}
+export interface PageDataChange {
+    readonly type: ChangeType.PAGE_DATA;
+    value: {
+        new: PageModelData;
+        old?: PageModelData;
+    };
+}
+export interface PageModeChange {
+    readonly type: ChangeType.PAGE_MODE;
+    value: {
+        new: PageMode;
+        old?: PageMode;
+    };
+}
+export interface StateChange {
+    readOnly?: boolean;
+    hidden?: boolean;
+    required?: boolean;
+    allowInput?: boolean;
+    couldBeReadOnly?: boolean;
+    couldBeRequired?: boolean;
+}

package/control/events.js

@@ -0,0 +1,5 @@
+export var ChangeType;
+(function (ChangeType) {
+    ChangeType["PAGE_MODE"] = "mode";
+    ChangeType["PAGE_DATA"] = "pageData";
+})(ChangeType || (ChangeType = {}));

package/control/file.d.ts

@@ -0,0 +1,14 @@
+export interface AttachmentFormData {
+    title: string;
+    label: string;
+    options: AttachmentDialogOptions;
+    pageModel?: {
+        id?: string;
+        type: string;
+    };
+}
+export interface AttachmentDialogOptions {
+    maxSize?: number;
+    allowMultiple?: boolean;
+    fileExtensions?: string;
+}

package/control/file.js

@@ -0,0 +1 @@
+export {};

package/control/image.d.ts

@@ -0,0 +1,14 @@
+export interface SASMenuItem {
+    label?: string;
+    showLabel?: boolean;
+    iconClass?: string;
+    items?: SASMenuItem[];
+    separator?: boolean;
+    disabled?: (() => boolean) | boolean;
+    onClick?(): void;
+}
+export interface ImageDialogOptions {
+    maxSize?: number;
+    allowMultiple?: boolean;
+    fileExtensions?: string;
+}

package/control/image.js

@@ -0,0 +1 @@
+export {};

package/control/package.json

@@ -0,0 +1,9 @@
+{
+    "name": "@sassoftware/vi-api/control",
+    "files": [
+        "**/*.d.ts",
+        "**/*.js"
+    ],
+    "main": "public-api.js",
+    "types": "public-api.d.ts"
+}

package/control/page.d.ts

@@ -0,0 +1,55 @@
+export declare const enum PageModeEvent {
+    CREATE = "create",
+    EDIT = "edit",
+    OPEN = "open",
+    INSPECT = "inspect",
+    SUMMARY = "summary"
+}
+export interface Control<ControlTypeAttributes extends TypeAttributes = TypeAttributes> {
+    id?: string;
+    attributes?: ControlAttributes;
+    typeAttributes: ControlTypeAttributes;
+    attrs: ControlAttrs;
+    childNodes?: Control[];
+}
+export interface ControlAttrs {
+    attributes?: {
+        disabled: boolean;
+        showActionHistory: boolean;
+        showVersionHistory: boolean;
+    };
+    id: string;
+    category: string;
+    type: string;
+    states?: ControlStates;
+}
+export interface TypeAttributes {
+    [property: string]: any;
+}
+export interface ControlAttributes extends TypeAttributes {
+    global?: {
+        state?: GlobalControlStates;
+        groupRestrictions?: Array<{
+            id: string;
+            name: string;
+        }>;
+    };
+}
+export interface ControlStates {
+    readOnly?: boolean;
+    required?: boolean;
+    hidden?: boolean;
+}
+export interface GlobalControlStates {
+    conditions?: any[];
+    readOnly?: boolean;
+    required?: boolean;
+    hidden?: boolean;
+}
+export interface SlidingPanelProperties {
+    [property: string]: any;
+}
+export interface RefreshablePageControlOptions {
+    refreshCategory?: string;
+    requiresIndex?: boolean;
+}

package/control/page.js

@@ -0,0 +1 @@
+export {};

package/control/public-api.d.ts

@@ -0,0 +1,8 @@
+export * from "./control-api";
+export * from "./data-types";
+export * from "./events";
+export * from "./file";
+export * from "./image";
+export * from "./page";
+export * from "./restrictions";
+export * from "./toolbar-property-api";

package/control/public-api.js

@@ -0,0 +1,8 @@
+export * from "./control-api";
+export * from "./data-types";
+export * from "./events";
+export * from "./file";
+export * from "./image";
+export * from "./page";
+export * from "./restrictions";
+export * from "./toolbar-property-api";