@sassoftware/vi-api 1.40.3 → 1.42.0

package/README.md

@@ -1,9 +1,40 @@
-# SAS Visual Investigator API
+# Visual Investigator API
 
-## Overview
-
-A package containing TypeScript type definitions to be used with the Visual Investigator Client API.
+The [SAS Visual Investigator](https://www.sas.com/en_us/software/intelligence-analytics-visual-investigator.html) API provides a set of components and service methods that enable developers to create customized solutions within the application.
 
 ## Getting Started
 
-For documentation and examples please see our [Solution Extension GitHub](https://github.com/sassoftware/vi-solution-extensions)
+For documentation and examples please see our [Solution Extension GitHub](https://github.com/sassoftware/vi-solution-extensions).
+
+### Installation
+To use the API, install the NPM package [@sassoftware/vi-api](https://www.npmjs.com/package/@sassoftware/vi-api):
+```bash
+npm install @sassoftware/vi-api
+```
+
+### API
+
+The SVI API is available through the JavaScript window object: 
+```javascript
+window.sas.vi.metadata.getEntity("person");
+```
+### Typings
+
+To complement the API, solution developers can download the API typings package.
+Run the following command in your project:
+```
+npm install @sassoftware/vi-api
+```
+The types can be used to help with autocompletion of API spaces, methods, and expected return types.
+```typescript
+import { SviWindow } from "@sassoftware/vi-api";
+import { StoredObjectDTO } from "@sassoftware/vi-api/svi-datahub";
+
+const sviWindow = window as SviWindow;
+sviWindow.sas.vi.metadata.getEntity("person").then((entity: StoredObjectDTO | undefined) => {
+    if (entity) {
+        console.log("Retrieved entity:", entity.label);
+    }
+});
+```
+

package/component/index.d.ts

@@ -16,7 +16,11 @@ export interface ComponentCreationResult<T> {
 }
 /**
  * Functionality related to dynamically creating SAS Visual Investigator user interface components.
- * Accessed from the window at window.sas.vi.component.
+ *
+ * Accessed from the window at `window.sas.vi.component`.
+ *
+ * @example window.sas.vi.component.create(SviComponent.Page, targetElement, bindings);
+ * @category API
  */
 export interface ComponentApi {
     create(component: SviComponent.ControlCollection, target: HTMLElement, bindings?: ControlCollectionBindings): Promise<ComponentCreationResult<ControlCollectionBindings>>;

package/component/package.json

@@ -4,6 +4,6 @@
         "**/*.d.ts",
         "**/*.js"
     ],
-    "main": "public-api.js",
-    "types": "public-api.d.ts"
+    "main": "index.js",
+    "types": "index.d.ts"
 }

package/config/config-api.d.ts

@@ -109,7 +109,11 @@ export interface VersionSummary {
 }
 /**
  * Configuration-related functionality.
- * Accessed from the window at window.sas.vi.config.
+ *
+ * Accessed from the window at `window.sas.vi.config`.
+ *
+ * @example window.sas.vi.config.getSolutions();
+ * @category API
  */
 export interface ConfigApi {
     /**

package/config/package.json

@@ -4,6 +4,6 @@
         "**/*.d.ts",
         "**/*.js"
     ],
-    "main": "public-api.js",
-    "types": "public-api.d.ts"
+    "main": "index.js",
+    "types": "index.d.ts"
 }

package/control/control-api.d.ts

@@ -21,6 +21,7 @@ export interface ControlMemberApiBase<ControlTypeAttributes extends TypeAttribut
 /**
  * {@link ControlMemberApiBase} extension that provides more functionality.
  * @extends ControlMemberApiBase
+ * @category API
  */
 export interface ControlMemberApi<ControlTypeAttributes extends TypeAttributes = TypeAttributes, ControlFieldType extends FieldType = any> extends ControlMemberApiBase<ControlTypeAttributes, ControlFieldType> {
     /**
@@ -87,6 +88,8 @@ export interface ControlApiBase<ControlTypeAttributes extends TypeAttributes = T
 }
 /**
  * This API pertains to administration functionality for controls, for example registering resources.
+ *
+ * @category API
  */
 export interface ControlAdminApi {
     /**
@@ -100,6 +103,7 @@ export interface ControlAdminApi {
 /**
  * Extension of {@link ControlApiBase} supplied by SAS Visual Investigator to provide more functionality.
  * @extends ControlApiBase
+ * @category API
  */
 export interface ControlApi<ControlTypeAttributes extends TypeAttributes = TypeAttributes, ControlFieldType extends FieldType = never> extends ControlApiBase<ControlTypeAttributes, ControlFieldType> {
     /**
@@ -138,6 +142,8 @@ export interface ControlApi<ControlTypeAttributes extends TypeAttributes = TypeA
 }
 /**
  * Methods and properties related to the state of the control.
+ *
+ * @category API
  */
 export interface ControlStateApi {
     /**
@@ -197,6 +203,8 @@ export interface ControlStateApi {
 }
 /**
  * API methods related to object fields associated with a page.
+ *
+ * @category API
  */
 export interface ControlPageFieldApi {
     /**
@@ -277,6 +285,7 @@ export interface ControlPageApiBase {
 /**
  * {@link ControlPageApiBase} extension that provides more functionality.
  * @extends ControlPageApiBase
+ * @category API
  */
 export interface ControlPageApi extends ControlPageApiBase {
     /**
@@ -309,7 +318,8 @@ export interface ControlPageApi extends ControlPageApiBase {
     isToolbarDisabled(): boolean;
     /**
      * Sets the toolbar control to be disabled.
-     * @param control {Control} The control to be disabled.
+     * @param {string} actionName the toolbar action name.
+     * @param {boolean} setDisabled disable the toolbar item.
      * @method
      */
     setToolbarItemDisabled(actionName: string, setDisabled: boolean): void;
@@ -429,6 +439,7 @@ export interface ControlFileApiBase {
 /**
  * {@link ControlFileApiBase} extension that provides more functionality.
  * @extends ControlFileApiBase
+ * @category API
  */
 export interface ControlFileApi extends ControlFileApiBase {
     /**

package/control/package.json

@@ -4,6 +4,6 @@
         "**/*.d.ts",
         "**/*.js"
     ],
-    "main": "public-api.js",
-    "types": "public-api.d.ts"
+    "main": "index.js",
+    "types": "index.d.ts"
 }

package/control/page.d.ts

@@ -14,6 +14,15 @@ export interface Control<ControlTypeAttributes extends TypeAttributes = TypeAttr
     attrs: ControlAttrs;
     childNodes?: Control[];
 }
+export type ToolbarControl<T extends Record<any, any> = {}> = Control<{}> & {
+    attrs: {
+        attributes: {
+            disabled: boolean;
+            state?: ActionState;
+        } & T;
+    };
+    typeAttributes: never;
+};
 export interface ControlAttrs {
     attributes?: {
         disabled: boolean;

package/current-user/currentUser-api.d.ts

@@ -28,7 +28,11 @@ export interface SessionDetails {
 }
 /**
  * This API is used to get the details and functionality associated with the current user.
- * Accessed from the window at window.sas.vi.currentUser.
+ *
+ * Accessed from the window at `window.sas.vi.currentUser`.
+ *
+ * @example window.sas.vi.currentUser.getSessionDetails();
+ * @category API
  */
 export interface CurrentUserApi {
     /**

package/current-user/package.json

@@ -4,6 +4,6 @@
         "**/*.d.ts",
         "**/*.js"
     ],
-    "main": "public-api.js",
-    "types": "public-api.d.ts"
+    "main": "index.js",
+    "types": "index.d.ts"
 }

package/elements/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * SAS Visual Investigator exposes a number of controls within the DOM as Custom Elements.
+ *
+ * See {@link SVICustomElement} for the list of available SVI Custom Elements.
+ *
+ * @module
+ */
+/**
+ * This enumeration list contains the tag names of all SVI custom elements.
+ *
+ * @category CustomElement
+ */
+export declare enum SVICustomElement {
+    /**
+     * Wrap a given control in an SVI control label.
+     *
+     * By default, the label will include a {@link MaskToggleButton | mask-toggle-button}
+     * for toggling the masked state of the control's dataSource, if configured for masking.
+     *
+     * See {@link LabelledControlProperties} for supported input bindings.
+     */
+    LabelledControl = "svi-labelled-control",
+    /**
+     * Toggle a given dataSource between it's masked and unmasked state, if configured for masking.
+     *
+     * See {@link MaskToggleButtonProperties} for supported input bindings.
+     */
+    MaskToggleButton = "svi-mask-toggle-button"
+}
+export * from "./properties";

package/elements/index.js

@@ -0,0 +1,31 @@
+/**
+ * SAS Visual Investigator exposes a number of controls within the DOM as Custom Elements.
+ *
+ * See {@link SVICustomElement} for the list of available SVI Custom Elements.
+ *
+ * @module
+ */
+/**
+ * This enumeration list contains the tag names of all SVI custom elements.
+ *
+ * @category CustomElement
+ */
+export var SVICustomElement;
+(function (SVICustomElement) {
+    /**
+     * Wrap a given control in an SVI control label.
+     *
+     * By default, the label will include a {@link MaskToggleButton | mask-toggle-button}
+     * for toggling the masked state of the control's dataSource, if configured for masking.
+     *
+     * See {@link LabelledControlProperties} for supported input bindings.
+     */
+    SVICustomElement["LabelledControl"] = "svi-labelled-control";
+    /**
+     * Toggle a given dataSource between it's masked and unmasked state, if configured for masking.
+     *
+     * See {@link MaskToggleButtonProperties} for supported input bindings.
+     */
+    SVICustomElement["MaskToggleButton"] = "svi-mask-toggle-button";
+})(SVICustomElement || (SVICustomElement = {}));
+export * from "./properties";

package/elements/package.json

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

package/elements/properties.d.ts

@@ -0,0 +1,89 @@
+import { PageModel } from "../page-model";
+import { Control } from "../control";
+/** Page Controls require a valid {@link Control | childNode} and {@link PageModel | pageModel}.</strong> */
+export interface PageControlBindings {
+    childNode: Control;
+    pageModel: PageModel;
+}
+/**
+ * Properties for {@link SVICustomElement.LabelledControl}.
+ *
+ * @category CustomElement
+ *
+ * @example HTML Example:
+ * ```html
+ * <svi-labelled-control
+ *   [childNode]="childNode"
+ *   [pageModel]="pageModel"
+ * >
+ *   <!-- my control -->
+ * </svi-labelled-control>
+ * ```
+ *
+ * @example Create the element via document.createElement:
+ * ```ts
+ * const labelledControl = document.createElement(SVICustomElement.LabelledControl);
+ * labelledControl.pageModel = this.pageModel;
+ * labelledControl.childNode = this.childNode;
+ * labelledControl.appendChild(myControlElement)
+ * ```
+ */
+export interface LabelledControlProperties extends PageControlBindings {
+    /** Set the label as required. */
+    isRequired?: boolean;
+    /** Set the label as disabled. */
+    isDisabled?: boolean;
+    /** Override the text displayed in the label. */
+    overrideLabel?: string;
+    /** Add css classes to the label element. */
+    labelClass?: string;
+    /**
+     * Specify which dataSource the label's mask-toggle-button will toggle.
+     *
+     * If no {@link MaskToggleButtonProperties.dataSource | dataSource} is specified,
+     * the mask-toggle-button will toggle the dataSource(s) defined in the childNode's {@link Control.typeAttributes | typeAttributes}.
+     */
+    dataSource?: string;
+    /** Disable the label's mask toggle button. */
+    disableMaskToggle?: boolean;
+    /** Hide the label's mask toggle button. */
+    hideMaskToggle?: boolean;
+    /** Set the label's `for` attribute. */
+    for?: string;
+}
+/**
+ * Properties for {@link SVICustomElement.MaskToggleButton}.
+ *
+ * @category CustomElement
+ *
+ * @example HTML Example
+ * ```html
+ * <svi-mask-toggle-button
+ *   [childNode]="childNode"
+ *   [pageModel]="pageModel"
+ * >
+ * </svi-mask-toggle-button>
+ * ```
+ *
+ * @example Create element via document.createElement:
+ * ```ts
+ * const maskToggleBtn = document.createElement(SVICustomElement.MaskToggleButton);
+ * maskToggleBtn.pageModel = this.pageModel;
+ * maskToggleBtn.childNode = this.childNode;
+ * ```
+ */
+export interface MaskToggleButtonProperties extends PageControlBindings {
+    /**
+     * Specify which dataSource will be toggled.
+     *
+     * If no {@link MaskToggleButtonProperties.dataSource | dataSource} is specified,
+     * the mask-toggle-button will toggle the dataSource(s) defined in the childNode's {@link Control.typeAttributes | typeAttributes}.
+     */
+    dataSource?: string;
+    /** Disable the mask toggle button. */
+    disabled?: boolean;
+    /** Hide the mask toggle button. */
+    hidden?: boolean;
+    /** Override the control name displayed in the authorization dialog. */
+    controlName?: string;
+}

package/event/event-api.d.ts

@@ -18,7 +18,8 @@ export declare enum PageEvents {
     TabSelectedEvent = "spb::tabSelected",
     VisitAllTabs = "spb::mark-all-tabs-visited",
     MaskToggleEvent = "spb::mask-toggle",
-    MaskAllEvent = "spb::mask-all"
+    MaskAllEvent = "spb::mask-all",
+    ClearDateFieldEvent = "spb::clear-date-field"
 }
 export declare enum DocumentGeneratorEvents {
     AfterDocumentGenerated = "docgen::after-document-generated"
@@ -28,7 +29,11 @@ export interface Subscription {
 }
 /**
  * This API provides the  details and functionality associated with publishing and subscribing to events.
- * Accessed from the window at window.sas.vi.event.
+ *
+ * Accessed from the window at `window.sas.vi.event`.
+ *
+ * @example window.sas.vi.event.publish("eventName", payload);
+ * @category API
  */
 export interface EventApi {
     /**
@@ -42,8 +47,8 @@ export interface EventApi {
      * @method
      * @description Subscribes to an event and registers a function to be called on any future published events.
      * If the eventName does not exist, it is created.
-     * @param eventName {string} Name of the event to subscribe to.
-     * @param {EventApi~subscriptionCallback} Function Invoked when the subscription is triggered by an event.
+     * @param {string} eventName Name of the event to subscribe to.
+     * @param {EventApi~subscriptionCallback} observer Invoked when the subscription is triggered by an event.
      * Has access to the event's payload.
      * @returns The subscription being made to the event.
      */

package/event/event-api.js

@@ -20,6 +20,7 @@ export var PageEvents;
     PageEvents["VisitAllTabs"] = "spb::mark-all-tabs-visited";
     PageEvents["MaskToggleEvent"] = "spb::mask-toggle";
     PageEvents["MaskAllEvent"] = "spb::mask-all";
+    PageEvents["ClearDateFieldEvent"] = "spb::clear-date-field";
 })(PageEvents || (PageEvents = {}));
 export var DocumentGeneratorEvents;
 (function (DocumentGeneratorEvents) {

package/event/package.json

@@ -4,6 +4,6 @@
         "**/*.d.ts",
         "**/*.js"
     ],
-    "main": "public-api.js",
-    "types": "public-api.d.ts"
+    "main": "index.js",
+    "types": "index.d.ts"
 }

package/file/file-api.d.ts

@@ -30,7 +30,11 @@ export interface FileOperation {
 }
 /**
  * This API provides functionality related to uploading files.
- * Accessed from the window at window.sas.vi.file.
+ *
+ * Accessed from the window at `window.sas.vi.file`.
+ *
+ * @example window.sas.vi.file.uploadToVIFolder(file, "fileName")
+ * @category API
  */
 export interface FileApi {
     /**

package/file/package.json

@@ -4,6 +4,6 @@
         "**/*.d.ts",
         "**/*.js"
     ],
-    "main": "public-api.js",
-    "types": "public-api.d.ts"
+    "main": "index.js",
+    "types": "index.d.ts"
 }

package/http/index.d.ts

@@ -7,7 +7,11 @@ export interface HttpResponse<R> {
 }
 /**
  * This API provides functionality for making REST requests.
- * Accessed from the window at window.sas.vi.http.
+ *
+ * Accessed from the window at `window.sas.vi.http`
+ *
+ * @example window.sas.vi.http.get("example_url", {...})
+ * @category API
  */
 export interface HttpApi {
     /**

package/http/package.json

@@ -4,6 +4,6 @@
         "**/*.d.ts",
         "**/*.js"
     ],
-    "main": "public-api.js",
-    "types": "public-api.d.ts"
+    "main": "index.js",
+    "types": "index.d.ts"
 }

package/index.d.ts

@@ -24,7 +24,9 @@ import { ShellTabsApi } from "./shell-tabs/shell-tabs-api";
 import { PageTemplateApi } from "./page-template/page-template-api";
 import { InitApi } from "./init";
 /**
- * Common API Functions.
+ * The SVI API contains common API functions and can be accessed directly from the window via `window.sas.vi`
+ *
+ * @module
  */
 export interface SviCommonApi {
     component: ComponentApi;

package/init/index.d.ts

@@ -3,21 +3,25 @@ export declare const ERR_EXISTING_APP_DECLARED: (appName: string) => string;
 export declare const ERR_EXISTING_RESOURCE_BUNDLE_DECLARED: (appName: string) => string;
 export declare const ERR_INIT_TIMEOUT: (name: string, timeout?: number) => string;
 /**
- * An API to manage the asynchronous initialisation of solution applications
- * before the Visual Investigator application is fully initialised.
+ * An API to manage the asynchronous initialization of solution applications before the
+ * Visual Investigator application is fully initialized.
+ *
+ * Accessed from the window at `window.sas.viInit`
+ * @example window.sas.viInit.registerResourceBundle(bundleName, resources);
+ * @category API
  */
 export interface InitApi {
     /**
      * Declare an application.
-     * Visual Investigator will await whenReady for each before continuing its own app initialisation.
-     * notifyAppReady should be called to indicate when the app initialisation is complete.
+     * Visual Investigator will await whenReady for each before continuing its own app initialization.
+     * notifyAppReady should be called to indicate when the app initialization is complete.
      * if provided, registerResourceBundle should be called to indicate when the I18n resource bundle is ready.
      * @param appName appName of the app configuration.
      * @param i18nResourceBundleName I18n resource bundle name of the app configuration.
      */
     declareApp(appName: string, i18nResourceBundleName?: string): void;
     /**
-     * Notify listeners that the app has been initialised.
+     * Notify listeners that the app has been initialized.
      * @param appName appName of the app configuration.
      */
     notifyAppReady(appName: string): void;
@@ -38,8 +42,9 @@ export interface InitApi {
     registerResourceBundle(bundleName: string, resources: I18nResources): void;
 }
 /**
- * Initialisation events for the Visual Investigator application.
- * These can be awaited using window.sas.viInit.whenReady
+ * Initialization events for the Visual Investigator application.
+ *
+ * These can be awaited using `window.sas.viInit.whenReady`
  */
 export declare enum SviInitEvent {
     /** all apps which were declared through window.sas.viInit */

package/init/index.js

@@ -3,8 +3,9 @@ export const ERR_EXISTING_APP_DECLARED = (appName) => `App: '${appName}' has alr
 export const ERR_EXISTING_RESOURCE_BUNDLE_DECLARED = (appName) => `I18n resource bundle: '${appName}' has already been declared.`;
 export const ERR_INIT_TIMEOUT = (name, timeout) => `Ready check for '${name}' timed out after ${timeout ?? APP_INIT_TIMEOUT_MS}ms.`;
 /**
- * Initialisation events for the Visual Investigator application.
- * These can be awaited using window.sas.viInit.whenReady
+ * Initialization events for the Visual Investigator application.
+ *
+ * These can be awaited using `window.sas.viInit.whenReady`
  */
 export var SviInitEvent;
 (function (SviInitEvent) {

package/init/package.json

@@ -4,6 +4,6 @@
         "**/*.d.ts",
         "**/*.js"
     ],
-    "main": "public-api.js",
-    "types": "public-api.d.ts"
+    "main": "index.js",
+    "types": "index.d.ts"
 }

package/localization/localization-api.d.ts

@@ -1,6 +1,10 @@
 /**
  * This API is used for the localization methods.
- * Accessed from the window at window.sas.vi.localization.
+ *
+ * Accessed from the window at `window.sas.vi.localization`.
+ *
+ * @example window.sas.vi.localization.getLocale();
+ * @category API
  */
 export interface LocalizationApi {
     /**
@@ -16,6 +20,13 @@ export interface LocalizationApi {
      * @returns The current application locale.
      */
     getLocale(): string;
+    /**
+     * @method
+     * @description Gets user's preferred locale format in BCP 47 format. This should be used
+     * to format dates\numbers in VI extensions but not to drive the language.
+     * @returns The user's preferred locale format.
+     */
+    getFormatLocale(): string;
     /**
      * @method
      * @description Gets the application display direction.
@@ -30,7 +41,11 @@ export interface LocalizationApi {
 }
 /**
  * This API is used for solution content localization.
- * Accessed from the window at window.sas.vi.localization.solution.
+ *
+ * Accessed from the window at `window.sas.vi.localization.solution`.
+ *
+ * @example window.sas.vi.metadata.getLocalizationBundle();
+ * @category API
  */
 export interface SolutionLocalizationApi {
     /**
@@ -52,7 +67,7 @@ export interface SolutionLocalizationApi {
      * @returns The localized value for the given resource key, else undefined.
      * @param resourceKey {string} A resource key used to lookup the localized value.
      * @example
-     * getLocalizedResource("colours.red.txt") === "rouge"
+     * getLocalizedResource("colors.red.txt") === "rouge"
      */
     getLocalizedResource(resourceKey: string): string | undefined;
     /**
@@ -64,7 +79,7 @@ export interface SolutionLocalizationApi {
      * @param resourceKey {string} A resource key used to lookup the localized value.
      * @returns The localized string.
      * @example
-     * localize("red", "colours.red.txt") === "rouge"
+     * localize("red", "colors.red.txt") === "rouge"
      */
     localize(str: string, resourceKey?: string): string;
     /**
@@ -76,7 +91,7 @@ export interface SolutionLocalizationApi {
      * @param props {Record<string, string | undefined>} The properties to localize and their resource keys.
      * @returns The localized object.
      * @example
-     * localizeObject({ label: "red" }, { "label": "colours.red.txt" }) === { label: "rouge" }
+     * localizeObject({ label: "red" }, { "label": "colors.red.txt" }) === { label: "rouge" }
      */
     localizeObject<T extends object>(obj: T, props: Record<string, string | undefined>): T;
     /**
@@ -89,7 +104,7 @@ export interface SolutionLocalizationApi {
      * @example
      *  localizeList(
      *      [{ id: "red", label: "Red" }, { id: "blue", label: "Blue"} ],
-     *      (item) => ({ "label": `colours.${item.id}.title` })
+     *      (item) => ({ "label": `colors.${item.id}.title` })
      *  ) === [{ id: "red", label: "Rouge" }, { id: "blue", label: "Bleu"} ]
      */
     localizeList<T extends object>(list: T[], getProps: (obj: T) => Record<string, string | undefined>): T[];
@@ -98,9 +113,9 @@ export interface SolutionLocalizationApi {
  * Stores localized strings by key and value.
  * @example
  *  {
- *      bykey: {
- *          "colours.red.label": "rouge",
- *          "colours.blue.label": "bleu"
+ *      byKey: {
+ *          "colors.red.label": "rouge",
+ *          "colors.blue.label": "bleu"
  *      },
  *      byValue: {
  *          "red": "rouge",

package/localization/package.json

@@ -4,6 +4,6 @@
         "**/*.d.ts",
         "**/*.js"
     ],
-    "main": "public-api.js",
-    "types": "public-api.d.ts"
+    "main": "index.js",
+    "types": "index.d.ts"
 }