@sassoftware/vi-api 1.7.1 → 1.15.2

package/init/init-api.js

@@ -0,0 +1,83 @@
+import { ReplaySubject, throwError } from "rxjs";
+import { take, timeoutWith } from "rxjs/operators";
+import { APP_INIT_TIMEOUT_MS, ERR_INIT_TIMEOUT, SviInitEvent, ERR_EXISTING_APP_DECLARED, ERR_EXISTING_RESOURCE_BUNDLE_DECLARED } from ".";
+export class SviInitApi {
+    constructor(globalI18nResources) {
+        this.globalI18nResources = globalI18nResources;
+        this.appReadyStates = new Map();
+        this.resourceReadyStates = new Map();
+        this.resourceServiceSubject = new ReplaySubject();
+        this.resourceService$ = this.resourceServiceSubject.pipe(take(1));
+        this.defaultTimeout = APP_INIT_TIMEOUT_MS;
+    }
+    declareApp(appName, i18nResourceBundleName) {
+        if (this.isAppDeclared(appName)) {
+            throw ERR_EXISTING_APP_DECLARED(appName);
+        }
+        this.initReadyState(this.appReadyStates, appName, true);
+        if (!i18nResourceBundleName) {
+            return;
+        }
+        if (this.isResourceBundleDeclared(i18nResourceBundleName)) {
+            throw ERR_EXISTING_RESOURCE_BUNDLE_DECLARED(i18nResourceBundleName);
+        }
+        this.initReadyState(this.resourceReadyStates, i18nResourceBundleName, true);
+    }
+    async whenAppReady(appName, timeout) {
+        return this.whenReady(this.appReadyStates, appName, timeout);
+    }
+    notifyAppReady(appName) {
+        this.notifyReady(this.appReadyStates, appName);
+    }
+    registerResourceBundle(bundleName, resources) {
+        // register bundle with the global i18nResources object which will be picked up by our resource services on construction.
+        this.globalI18nResources[bundleName] = resources;
+        this.notifyReady(this.resourceReadyStates, bundleName);
+        // also register the bundle to be added when the resource service is ready.
+        // this supports any consumers which may call this after init
+        this.resourceService$.subscribe(resourceService => {
+            resourceService.registerResourceBundle(bundleName, resources);
+        });
+    }
+    checkAllDeclaredAppsReady() {
+        this.whenAllDeclaredReady(this.appReadyStates).then(() => this.notifyAppReady(SviInitEvent.AllDeclaredApps));
+    }
+    checkAllDeclaredResourcesReady() {
+        this.whenAllDeclaredReady(this.resourceReadyStates).then(() => this.notifyAppReady(SviInitEvent.AllDeclaredI18nResourceBundles));
+    }
+    setResourceApi(resourceService) {
+        this.resourceServiceSubject.next(resourceService);
+        this.resourceServiceSubject.complete();
+    }
+    isAppDeclared(appName) {
+        return !!this.appReadyStates.get(appName)?.isDeclared;
+    }
+    isResourceBundleDeclared(bundleName) {
+        return !!this.resourceReadyStates.get(bundleName)?.isDeclared;
+    }
+    notifyReady(map, name) {
+        const readyState = this.initReadyState(map, name);
+        readyState.subject.next(undefined);
+        readyState.subject.complete();
+    }
+    async whenReady(map, name, timeout) {
+        const readySubject = this.initReadyState(map, name).subject;
+        const timeoutMs = timeout ?? this.defaultTimeout;
+        await readySubject.pipe(timeoutWith(timeoutMs, throwError(ERR_INIT_TIMEOUT(name, timeoutMs)))).toPromise();
+    }
+    async whenAllDeclaredReady(map) {
+        const toWaitFor = [];
+        for (const [name, readyState] of map.entries()) {
+            if (readyState.isDeclared) {
+                toWaitFor.push(this.whenReady(map, name).catch(console.error));
+            }
+        }
+        await Promise.all(toWaitFor);
+    }
+    initReadyState(map, name, declare) {
+        const state = map.get(name) ?? { subject: new ReplaySubject() };
+        state.isDeclared = declare ?? state.isDeclared;
+        map.set(name, state);
+        return state;
+    }
+}

package/init/package.json

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

package/init/public-api.d.ts

@@ -0,0 +1 @@
+export * from "./index";

package/init/public-api.js

@@ -0,0 +1 @@
+export * from "./index";

package/localization/localization-api.d.ts

@@ -23,4 +23,79 @@ export interface LocalizationApi {
      * @returns The current application display direction.
      */
     getDirection(): "ltr" | "rtl";
+    /**
+     * Methods related to Solution content localization.
+     */
+    solution: SolutionLocalizationApi;
+}
+export interface SolutionLocalizationApi {
+    /**
+     * if {@link isEnabled}, returns the {@link SolutionLocalizationBundle} used to lookup translations.
+     */
+    getLocalizationBundle(): SolutionLocalizationBundle | undefined;
+    /**
+     * returns true if solution localization is enabled.
+     * methods will return unmodified inputs if not enabled.
+     * note that solution localization is disabled in the administration application.
+     */
+    isEnabled(): boolean;
+    /**
+     * returns the localized value for the given resource key, else, undefined.
+     * @param resourceKey
+     */
+    getLocalizedResource(resourceKey: string): string | undefined;
+    /**
+     * localize a string using a resourceKey.
+     * fallback to lookup by value if the resourceKey is not supplied/found.
+     * mappings are defined by the contents of {@link getLocalizationBundle}
+     * @param str string to localize
+     * @param resourceKey a resource key used to lookup the localized value
+     * @returns the localized string
+     * @example
+     * localize("red", "colours.red.txt") === "rouge"
+     */
+    localize(str: string, resourceKey?: string): string;
+    /**
+     * localize string properties of an object
+     * properties are provided as a map of <propertyKey, resourceKey>, deep property keys are accepted.
+     * {@link localize} is applied to each property with its given resourceKey.
+     * @param obj source object to localize
+     * @param props properties to localize and their resource keys
+     * @returns the localized object
+     * @example
+     * localizeObject({ label: "red" }, { "label": "colours.red.txt" }) === { label: "rouge" }
+     */
+    localizeObject<T extends object>(obj: T, props: Record<string, string | undefined>): T;
+    /**
+     * localize a list of objects.
+     * {@link localizeObject} is applied to each element in the list.
+     * @param list objects to translate
+     * @param getProps callback to return a map of properties and resource keys for the given list element
+     * @returns the localized list
+     * @example
+     *  localizeList(
+     *      [{ id: "red", label: "Red" }, { id: "blue", label: "Blue"} ],
+     *      (item) => ({ "label": `colours.${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[];
+}
+/**
+ * Stores localized strings by key and value.
+ * @example
+ *  {
+ *      bykey: {
+ *          "colours.red.label": "rouge",
+ *          "colours.blue.label": "bleu"
+ *      },
+ *      byValue: {
+ *          "red": "rouge",
+ *          "blue": "bleu"
+ *      }
+ *  }
+ */
+interface SolutionLocalizationBundle {
+    byKey: Record<string, string>;
+    byValue: Record<string, string>;
 }
+export {};

package/metadata/metadata-api.d.ts

@@ -1,4 +1,9 @@
 import { CoreStoredObjectField, Entity, Relationship, RelationshipDTO, StoredObjectDTO } from "../svi-datahub";
+import { IdentitySummary } from "../current-user/currentUser-api";
+export interface IdentityOption extends IdentitySummary {
+    label?: string;
+    icon?: string;
+}
 export interface NodeShapeMultipliers {
     square: number;
     circle: number;
@@ -28,8 +33,8 @@ export interface SandDataObject extends DataObject {
 }
 export interface DataObject extends PersistableObject {
     name: string;
-    dataStoreName: string;
-    tableName: string;
+    dataStoreName?: string;
+    tableName?: string;
     deleteTableName?: string;
     readOnly: boolean;
     archived: boolean;
@@ -78,6 +83,8 @@ export interface DataObjectField extends PersistableObject, LocalizableObject {
     cascadingReferenceDataName?: string;
     cascadingReferenceDataFilterByCode?: string;
     cascadingReferenceDataFilterByField?: string;
+    masked?: boolean;
+    authorizedToRevealMasked?: IdentityOption[];
     [index: string]: any;
 }
 export interface LocalizableObject {
@@ -116,6 +123,15 @@ export interface EntityAccessRules {
     read: Promise<boolean>;
     update: Promise<boolean>;
 }
+export interface EntityAccessRule {
+    documentType: string;
+    access?: boolean;
+}
+export interface EntitiesAccessRules {
+    create: Promise<EntityAccessRule[]>;
+    read: Promise<EntityAccessRule[]>;
+    update: Promise<EntityAccessRule[]>;
+}
 export interface ReferenceDataItem {
     group?: string;
     displayText: string;
@@ -141,6 +157,13 @@ export interface MetadataApi {
      * @returns Object with a Promise of type boolean for each rule.
      */
     getEntityAccessRules(objectType: string): EntityAccessRules;
+    /**
+     * @method
+     * @description Gets create, read, and update access rights for the provided entities via Batch call.
+     * @param objectType {string[]} Entity name(s).
+     * @returns Object with a Promise of type EntityAccessRule[] for each rule, where EntityAccessRule maps to the access rule of a given entity name.
+     */
+    getEntitiesAccessRules(objectTypes: string[]): EntitiesAccessRules;
     /**
      * @method
      * @description Checks access rights and gets metadata for an entity. Returns undefined if the entity does not exist.
@@ -183,10 +206,11 @@ export interface MetadataApi {
      * @param objectType {string} Finds relationships for the entity.
      * @param [relationshipObjectType] {string} Used for filtering the name of an expected related entity.
      * @param [relationshipName] {string} Used for filtering the name of an expected relationship.
+     * @param flattenMultiLinkIntoSingles whether Relationships with a One->(multiple) links will get flattened into many One->Single relationships
      * @returns A Promise resolving to an object containing relationship type metadata.
      * The object is empty if no relationship types exist.
      */
-    getAllValidRelationshipTypes(objectType: string, relationshipObjectType?: string, relationshipName?: string): Promise<ValidRelationshipTypes>;
+    getAllValidRelationshipTypes(objectType: string, relationshipObjectType?: string, relationshipName?: string, flattenMultiLinkIntoSingles?: boolean): Promise<ValidRelationshipTypes>;
     /**
      * @method
      * @description Gets metadata for all resolved entities.
@@ -230,6 +254,7 @@ export interface MetadataApi {
         parentCode?: string;
     }): Promise<Picklist | undefined>;
     /**
+     * @deprecated
      * @method
      * @description Gets relationships with a specified end type.
      * @param endType {string} End type entity name.
@@ -237,4 +262,16 @@ export interface MetadataApi {
      * @returns A Promise resolving to a list of relationships, or an empty list if none are found.
      */
     getRelationshipsFilteredByEndType(endType: string, includeHeterogeneous?: boolean): Promise<RelationshipWithLabel[]>;
+    /**
+     * @method
+     * @description Gets relationships with a specified end type.
+     * @param endType endType {string} End type entity name.
+     * @param options see {@link OptionsForGetRelationshipsForObjectType}
+     */
+    getRelationshipsForObjectType(endType: string, options: OptionsForGetRelationshipsForObjectType): Promise<RelationshipWithLabel[]>;
+}
+export interface OptionsForGetRelationshipsForObjectType {
+    includeHeterogeneous?: boolean;
+    includeMultipleTypeRelationships?: boolean;
+    expandMultipleRelationshipsToSingle?: boolean;
 }

package/object/object-api.d.ts

@@ -1,4 +1,4 @@
-import { Relationship, StoredObjectFieldDTO, Comment } from "../svi-datahub";
+import { Comment, Relationship, StoredObjectFieldDTO } from "../svi-datahub";
 import { FileOperation } from "../file/file-api";
 import { PageModel } from "../page-model/page-model-api";
 import { ClientSheet, Sheet } from "../sheet/sheet-api";
@@ -84,6 +84,19 @@ export interface ObjectApi {
      * @return A Promise that resolves to the updated object when the object has successfully been updated.
      */
     updateObject(objectType: string, objectId: string, objectTypeId: number, objectTypeVersion: number, fieldValues: FieldValues, options?: UpdateObjectOptions): Promise<VIObject>;
+    /**
+     * @method
+     * @description Updates an existing object with the provided data.
+     * @param objectType {string} Object type.
+     * @param objectId {string} Object ID.
+     * @param objectTypeId {number} Object type ID.
+     * @param objectTypeVersion {number} Object type version.
+     * @param originalFieldValues {FieldValues} Field values before the object was edited
+     * @param newFieldValues {FieldValues} Field values after the object was edited
+     * @param [options] {UpdateObjectOptions} Optional extra parameters.
+     * @return A Promise that resolves to the updated object when the object has successfully been updated.
+     */
+    patchObject(objectType: string, objectId: string, objectTypeId: number, objectTypeVersion: number, originalFieldValues: FieldValues, newFieldValues: FieldValues, options?: UpdateObjectOptions): Promise<VIObject>;
     /**
      * @method
      * @description Deletes an object.
@@ -117,6 +130,15 @@ export interface ObjectApi {
      * @return A Promise that resolves to a relationship.
      */
     updateObjectRelationship(relationshipId: string, payload: any): Promise<ObjectRelationship>;
+    /**
+     * @method
+     * @description Updates an existing relationship in SAS Visual Investigator.
+     * @param relationshipId {string} Relationship ID.
+     * @param originalFieldValues {FieldValues} Field values before the relationship was edited
+     * @param newFieldValues {FieldValues} Field values after the relationship was edited
+     * @return A Promise that resolves to a relationship.
+     */
+    patchObjectRelationship(relationshipId: string, originalFieldValues: FieldValues, newFieldValues: FieldValues): Promise<ObjectRelationship>;
     /**
      * @method
      * @description Deletes relationship with the specified ID.
@@ -127,12 +149,12 @@ export interface ObjectApi {
     /**
      * @method
      * @description Creates a relationship between two objects.
-     * @param from {VIObject} Object that relationship is from.
-     * @param to {VIObject} Object that relationship is to.
+     * @param from {LinkObject} Object that relationship is from.
+     * @param to {LinkObject} Object that relationship is to.
      * @param relationship {ObjectRelationship} The relationship.
      * @return A Promise that resolves to an object.
      */
-    relateObject(from: VIObject, to: VIObject, relationship: ObjectRelationship): Promise<ObjectRelationship>;
+    relateObject(from: LinkObject, to: LinkObject, relationship: ObjectRelationship): Promise<ObjectRelationship>;
     /**
      * @method
      * @description Gets object summary label.
@@ -144,12 +166,12 @@ export interface ObjectApi {
     /**
      * @method
      * @description Creates a new object and relates it with an existing one.
-     * @param from {VIObject} Object that the relationship is from.
-     * @param to {VIObject} Object that the relationship is to.
+     * @param from {LinkObject} existing Object that the relationship is from.
+     * @param to {NewLinkObject} new Object to be created and related to.
      * @param relationship {ObjectRelationship} The relationship.
      * @return A Promise that resolves to a newly created relationship.
      */
-    createAndRelateObject(from: VIObject, to: VIObject, relationship: ObjectRelationship): Promise<ObjectRelationship>;
+    createAndRelateObject(from: LinkObject, to: NewLinkObject, relationship: ObjectRelationship): Promise<ObjectRelationship>;
     /**
      * @method
      * @description Processes an array of objects and formats them for display.
@@ -225,6 +247,8 @@ export interface VIObject {
     id: string;
     title?: string;
 }
+export declare type LinkObject = Pick<VIObject, "id" | "objectTypeName">;
+export declare type NewLinkObject = Pick<VIObject, "objectTypeName" | "fieldValues" | "fileOperations">;
 export interface ValidationResult {
     isValid: boolean;
     message?: string;
@@ -295,11 +319,14 @@ export interface NodeAttributes extends TypeAttributes {
         }>;
     };
 }
+export declare enum ActionState {
+    Disabled = "disabled",
+    Hidden = "hidden"
+}
 export interface ChildNodeAttrs {
     attributes?: {
         disabled: boolean;
-        showActionHistory: boolean;
-        showVersionHistory: boolean;
+        state?: ActionState;
     };
     id: string;
     category: string;

package/object/object-api.js

@@ -1,3 +1,8 @@
+export var ActionState;
+(function (ActionState) {
+    ActionState["Disabled"] = "disabled";
+    ActionState["Hidden"] = "hidden";
+})(ActionState || (ActionState = {}));
 export var ConditionReferenceType;
 (function (ConditionReferenceType) {
     ConditionReferenceType["TemplateControl"] = "TEMPLATE_CONTROL";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sassoftware/vi-api",
-  "version": "1.7.1",
+  "version": "1.15.2",
   "description": "Types used in the SAS Visual Investigator API",
   "keywords": [
     "SAS",

package/page-state/page-state-api.d.ts

@@ -1,31 +1,4 @@
-import { Template, StoredObjectDTO } from "../svi-datahub";
-/**
- * SAS Visual Investigator API's representation of a UI-Router state.
- * Accessed from the window at window.sas.vi.pageState.
- */
-export interface StateObject {
-    /** The parent StateObject. */
-    parent: StateObject;
-    /** Name used to register the state. */
-    name: string;
-    /** Parent StateObject array from this state up to the root. */
-    path: StateObject[];
-    data: any;
-    /**
-     * An object containing the parent States' names as keys and
-     * true as their values.
-     */
-    includes: {
-        [name: string]: boolean;
-    };
-    /**
-     * Function to return the root node of this state's tree.
-     *
-     * @returns The root of this state's tree.
-     */
-    root(): StateObject;
-    toString(): string;
-}
+import { StoredObjectDTO, Template } from "../svi-datahub";
 export interface HomepageDesignerState {
     isNew: boolean;
     page: Template;
@@ -48,21 +21,21 @@ export interface PageStateApi {
      * @description Returns the state of the current page.
      * @returns An object containing the page state data or undefined if no page exists.
      */
-    getCurrent(): StateObject | undefined;
+    getCurrent(): HomepageDesignerState | ObjectPageDesignerState | undefined;
     /**
      * @method
      * @description Returns the state of the page matching the ID.
      * @param id {string | number} Page ID for which the state will be returned.
      * @returns An object containing the page state data or undefined if the ID doesn't exist.
      */
-    get(id: string | number): StateObject | undefined;
+    get(id: string | number): HomepageDesignerState | ObjectPageDesignerState | undefined;
     /**
      * @method
      * @description Creates a page state.
      * @param id {string | number} Page ID to be created.
-     * @param state {StateObject} Object containing the state data required to create the page.
+     * @param state {HomepageDesignerState | ObjectPageDesignerState} Object containing the state data required to create the page.
      */
-    add(id: string | number, state: StateObject): void;
+    add(id: string | number, state: HomepageDesignerState | ObjectPageDesignerState): void;
     /**
      * @method
      * @description Deletes a page state.

package/property/property-api.d.ts

@@ -5,6 +5,12 @@ import { PageTemplateMetadata } from "../page-model/page-model-api";
 export interface ToolbarPropertyControl {
     typeAttributes: TypeAttributes;
 }
+export interface EntityToolbarItem {
+    actionName: string;
+    attributes: {
+        [attr: string]: any;
+    };
+}
 export interface PropertyConfig {
     [property: string]: any;
     order?: number;
@@ -28,6 +34,64 @@ export interface SelectedNode {
         [property: string]: any;
     };
 }
+export declare type LocalizerType = "page" | "toolbar";
+export declare type ControlPropertyLocalizer = ToolbarControlPropertyLocalizer | PageControlPropertyLocalizer;
+export interface ToolbarControlPropertyLocalizer extends PropertyLocalizer<EntityToolbarItem> {
+    localizerType: "toolbar";
+    /**
+     * Generate resources to be inluded 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.
  */
@@ -41,7 +105,7 @@ export interface EditorApi {
     onPropertyChange(handler: (category: string, property: string, currentValue: any, previousValue: any) => void): () => void;
 }
 /**
- * This API provides the  utility or miscellaneous functionality in SAS Visual Investigator.
+ * This API pertains to page/toolbar control properties in SAS Visual Investigator.
  * Accessed from the window at window.sas.vi.property.
  */
 export interface PropertyApi {
@@ -57,6 +121,12 @@ export interface PropertyApi {
      * @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 or not the child object data source property editor is valid.

package/public-api.d.ts

@@ -1 +1 @@
-export { SviClientApi, SviAdminApi, SviWindow } from "./index";
+export { SviClientApi, SviAdminApi, SviWindow, SviApi } from "./index";

package/public-api.js

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

package/resource/resource-api.d.ts

@@ -2,6 +2,7 @@ export interface I18nResources {
     [key: string]: string | I18nResources;
 }
 /**
+ * @deprecated Use window.sas.viInit.registerResourceBundle to register resources before the rest of the Visual Investigator API is ready.
  * This API provides the resource functionality in SAS Visual Investigator.
  * Accessed from the window at window.sas.vi.resource.
  */