@sassoftware/vi-api 1.5.0 → 1.9.0

package/sheet/package.json

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

package/sheet/sheet-api.d.ts

@@ -1,7 +1,7 @@
 import { ObjectIdentifier, ObjectSheetSettings, VIObject } from "../object/object-api";
 import { NetworkData, ResolvedObjectIdentifier, Visualization } from "../search/client/client-search-api";
 /**
- * This API pertains to functionality related to SAS Visual Investigators sheet capabilities.
+ * This API pertains to functionality related to SAS Visual Investigator's sheet capabilities.
  * Accessed from the window at window.sas.vi.sheet.
  */
 export interface SheetApi {
@@ -35,7 +35,7 @@ export interface SheetApi {
      * Creates and returns the list containing all Context Menu Items for a right-click on a network diagram node.
      * The menu is not rendered on the network diagram.
      * @param workspace {ClientSheet} Workspace containing the network. The workspace should not be manually constructed.
-     * @param handleAddToWorkspaceFn {function} A callback to handle adding the selected nodes to a Workspace.
+     * @param handleAddToWorkspaceFn {function} A callback to handle adding the selected nodes to a workspace.
      * @param handleAddToInsightsFn {function} A callback to handle adding the NLD to an Insight.
      * @returns Promise resolving to the list containing all Context Menu Items.
      */
@@ -88,22 +88,22 @@ export interface SheetApi {
      * @param targetObject {VIObject} Object containing the existing workspace.
      * @param workspaceClientId {string} Client ID of the workspace to add to.
      * @param objectsToAdd {Array<ObjectIdentifier | ResolvedObjectIdentifier>} Objects to add. It is safe to pass objects that are already in the workspace.
-     * @param [networkData] {NetworkData} If provided, network data that shall be merged into any existing network data on the workspace.
+     * @param [networkData] {NetworkData} If provided, network data that will be merged into any existing network data on the workspace.
      * @param [isUndoRedo] {boolean} Specifies if the function was called as part of an undo/redo operation.
      */
     addToExistingWorkspace(targetObject: VIObject, workspaceClientId: string, objectsToAdd: Array<ObjectIdentifier | ResolvedObjectIdentifier>, networkData?: NetworkData, isUndoRedo?: boolean): Promise<void>;
 }
 export interface AddAllObjectsToWorkspaceDialogOptions {
     /**
-     * The visualization to initially display once the objects have been added
+     * The visualization to initially display after the objects have been added.
      */
     visualizationName?: Visualization;
     /**
-     * The object the user is currently viewing. This is used as a visual aid in the dialog
+     * The object the user is currently viewing. This is used as a visual aid in the dialog.
      */
     currentObject?: ObjectIdentifier;
     /**
-     * Network visualization data to be copied to the workspace
+     * Network visualization data to be copied to the workspace.
      */
     networkData?: NetworkData;
 }

package/shell-tabs/package.json

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

package/shell-tabs/public-api.d.ts

@@ -0,0 +1,2 @@
+export * from "./shell-tabs-api";
+export * from "./shell-tabs-lifecycle-api";

package/shell-tabs/public-api.js

@@ -0,0 +1,2 @@
+export * from "./shell-tabs-api";
+export * from "./shell-tabs-lifecycle-api";

package/shell-tabs/shell-tabs-api.d.ts

@@ -0,0 +1,199 @@
+import { Observable } from "rxjs";
+import { INavigationBarTabSaveOptions } from "./shell-tabs-lifecycle-api";
+export interface WebElementData {
+    elementName: string;
+    doNotReuse?: boolean;
+}
+export interface INavigationBarTabs<D1 = any, D2 = D1> {
+    primary: INavigationBarTab<D1>;
+    secondary?: INavigationBarTab<D2>;
+}
+export interface INavigationBarTab<D = {
+    [key: string]: any;
+}, SecondaryData = D> {
+    /** unique tab id */
+    id: string;
+    /** url relative to shell root e.g. /user/123 - this must start with a / */
+    routeUrl: string;
+    /** label for the tab, can be String or the resource.key (if .isLabelResourceKey:true) */
+    label: string;
+    /** a weight used during .sort to order the tabs; will default to the order the tabs came as
+     * doesnt mean their array index, as many can be the same, negatives, fractions
+     * */
+    sortIndex?: number;
+    /** when true, will use resourceService.get to resolve INavigationBarTab.label */
+    isLabelResourceKey?: boolean;
+    /** font icon */
+    icon?: string;
+    /**  image url */
+    img?: string;
+    /** aria-controls id */
+    controlsId?: string;
+    /** list  of secondary tabs which will be displayed under the top-level tab */
+    secondaryTabs?: Array<ISecondaryNavigationBarTab<SecondaryData>>;
+    /** keep track of the currently selected secondary tab */
+    selectedSecondaryTab?: ISecondaryNavigationBarTab<SecondaryData>;
+    /** callback to configure save confirm actions on close. */
+    getSaveOptions?(tab: INavigationBarTab): INavigationBarTabSaveOptions | undefined;
+    /** callback when tab is removed */
+    onClose?(tab: INavigationBarTab): Promise<boolean> | Observable<boolean> | boolean;
+    /** mark tab as dirty */
+    dirty?: boolean;
+    /** visually disable and make tab unselectable */
+    disabled?: boolean;
+    /** visually hide tab and make unselectable */
+    hidden?: boolean;
+    /** exclude tab from appearing in the navigation bar system tab menu */
+    excludedFromSystemMenu?: boolean;
+    /** visually hide secondary tabs bar for a tab */
+    hideSecondaryTabs?: boolean;
+    /** indicate that the tab is associated with some new object being created. */
+    creating?: boolean;
+    /** any extra data to be associated with the tab */
+    data?: D;
+}
+export declare type ISecondaryNavigationBarTab<D = {
+    [key: string]: any;
+}> = Omit<INavigationBarTab<D>, "secondaryTabs" | "selectedSecondaryTab">;
+export interface ExternalTabConfig<T = any, P = any> {
+    /**
+     * will try to place at this index, can be negative, fraction, etc to put before/between existing tabs
+     */
+    sortIndex?: number;
+    /**
+     * finds TabId, and adds this as a secondaryTab to that tab
+     */
+    mainTabId?: string;
+    /**
+     * this is the element/tag name that will get presented
+     */
+    elementName: string;
+    /**
+     * this is the URL that the tab will be registered under,
+     * technically it's just a unique ID as this will be used to unregister a route and close any related tab(s)
+     */
+    configUrl: string;
+    /**
+     * function to return {@link INavigationBarTab} , remember routeUrl is from baseURL with a leading /
+     * fullUrl is the full URL that relates to the tab, useful when catching wildcards
+     * params is constructed as of /:param1/:param2, so {param1: string, param2: string}
+     * be aware fullUrl/params will be undefined if buildOnRegister true
+     */
+    buildTab: (fullUrl?: string, params?: P) => INavigationBarTab<T>;
+    /**
+     * add as a systemTab?, if left out will default to applicationTab, ignored if mainTabId is defined
+     */
+    systemTab?: boolean;
+    /**
+     * set this to true if you want the component to reset every time you navigate away
+     */
+    doNotReuse?: boolean;
+    /**
+     * set this to true if you want buildTab to run when registered (e.g. for a system tab that's always there)
+     * if your buildTab takes params, this can not be provided and must be assumed undefined
+     * a secondaryTab (one that has mainTabId) will be created regardless of this flag.
+     */
+    buildOnRegister?: boolean;
+}
+export declare type ShellTabsApi = {
+    /**
+     * this is used to expose any {@link PotentialTabItem} hooks on a component up to the Tab Service
+     * @param context pass "this"
+     * @param elRef pass the ElementRef for the component
+     *
+     *  onTabClose {@link OnTabClose}, optional, can be used to prevent closing of a tab or close async
+     *  onAttachTab {@link OnAttachTab}, will always trigger when currentNavigationBarTab has set
+     *  onAttachToolbar {@link TabWithToolbar}, optional, will set currentToolbar if there was a toolbar in the VI Router
+     *  onTabEnter {@link OnTabEnter}, optional, will trigger when tab is entered
+     *  onTabLeave {@link OnTabLeave}, optional, will trigger when tab is left
+     *  onTabSaveConfirm {@link OnTabSaveConfirm}, optional, basic dialog can be created whe closing a dirty tab
+     */
+    createTabApiForElement: (context: any, nativeElement: HTMLElement) => void;
+    /**
+     * Use this function to register new routes for tabs
+     * @param tabsToAdd - see {@link ExternalTabConfig}
+     */
+    registerExternalTabs: (tab: ExternalTabConfig[]) => void;
+    /**
+     * Use this function to remove routes added via registerTabFn
+     * @param tabsToAdd - see {@link ExternalTabConfig}
+     */
+    unregisterExternalTabs: (tabsToRemove: ExternalTabConfig[]) => void;
+    /**
+     * this will return the current primary and secondary tabs
+     */
+    getSelectedTab: () => {
+        primaryTab: INavigationBarTab;
+        secondaryTab?: INavigationBarTab;
+    };
+    /**
+     * this stream will track the current top level tab
+     */
+    selectedPrimaryTabChanged$: Observable<INavigationBarTab>;
+    /**
+     * this stream will track the current second level tab
+     */
+    selectedSecondaryTabChanged$: Observable<INavigationBarTab | undefined>;
+    /**
+     * this stream will update after any additions/removals to either system or application tabs
+     */
+    openTabsChanged$: Observable<{
+        systemTabs: INavigationBarTab[];
+        applicationTabs: INavigationBarTab[];
+    }>;
+    /**
+     * this stream will emit any removed tabs
+     */
+    tabRemoved$: Observable<INavigationBarTab>;
+    /**
+     * @param tabId will be ID of an existing tab
+     */
+    getTabById: (tabId: string) => INavigationBarTab | undefined;
+    /**
+     * will return a slice of the current system and application tabs
+     */
+    getAllTabs: () => {
+        system: INavigationBarTab[];
+        application: INavigationBarTab[];
+    };
+    /**
+     * will move user to the default tab
+     */
+    selectDefaultTab: () => Promise<boolean>;
+    /**
+     * will attempt to open+select a matching INavigationBarTab and optional secondaryTab, returning false on failure
+     * in the event the tab doesn't exist already, it will add the tab assuming an appropriate route has been registered for it
+     * @param tabToSelect {@link INavigationBarTab}
+     * @param secondaryTab {@link INavigationBarTab} if left undefined, this will select the previously
+     * selected secondary tab of the primary tab or it's first index secondary tab
+     */
+    openTab: (tabToSelect: INavigationBarTab, secondaryTab?: INavigationBarTab) => Promise<boolean>;
+    /**
+     * will attempt to select a tab by its id, returning false on failure
+     * @param tabId will be ID of an existing tab
+     */
+    selectTabById: (tabId: string) => Promise<boolean>;
+    /**
+     * will remove an application tab, if allowed, and will trigger any closing and saving logic beforehand
+     * @param tabIdToRemove will be ID of an existing tab
+     * @param suppressNavigation if you are closing a tab that isn't open, you want to supressNavigation=true
+     */
+    removeApplicationTabById: (tabIdToRemove: string, suppressNavigation?: boolean) => Promise<boolean>;
+    /**
+     * will remove an existing application tab then replace with another, if {@link removeApplicationTabById} is unsuccessful this will fail
+     * use case can be saving a tab which has a temporary ID, and reopening it with a saved payload.
+     * @param tabId will be ID of an existing tab
+     * @param newTab {@link INavigationBarTab}
+     *
+     */
+    replaceApplicationTab: (tabId: string, newTab: INavigationBarTab) => Promise<boolean>;
+    /**
+     * will run {@link removeApplicationTabById} on all tabs, will stop if any fail to close, will wait for each close to complete
+     */
+    removeAllApplicationTabs: () => Promise<boolean>;
+    /**
+     * will run same as {@link removeAllApplicationTabs}, but not on the provided tabIdToKeep
+     * @param tabIdToKeep
+     */
+    removeOtherApplicationTabs: (tabIdToKeep?: string) => Promise<boolean>;
+};

package/shell-tabs/shell-tabs-api.js

@@ -0,0 +1,6 @@
+import { expectType } from "../../shared/util/helper-functions";
+expectType(true);
+expectType(true);
+expectType(true);
+expectType(true);
+expectType(true);

package/shell-tabs/shell-tabs-lifecycle-api.d.ts

@@ -0,0 +1,69 @@
+import { OnDestroy } from "@angular/core";
+import { INavigationBarTab, INavigationBarTabs } from "./shell-tabs-api";
+import { Observable } from "rxjs";
+export declare type PotentialTabItem<T = any, U = any> = Partial<OnAttachTab<T> & OnTabEnter & OnTabLeave & OnTabSaveConfirm & OnTabClose & TabWithToolbar<U> & OnDestroy>;
+export interface OnAttachTab<T = any> {
+    currentNavigationBarTab?: INavigationBarTab<T>;
+    /**
+     * Runs when a navigation bar tab is first attached to the implementing component.
+     * If the tab is recycled, it will only run once.
+     */
+    onAttachTab?(): void;
+}
+export interface OnTabEnterParams {
+    from?: INavigationBarTab;
+    fromSecondary?: INavigationBarTab;
+    to: INavigationBarTab;
+    toSecondary?: INavigationBarTab;
+    recycled: boolean;
+}
+export declare type OnTabLeaveParams = Omit<OnTabEnterParams, "recycled">;
+export interface OnTabEnter {
+    /**
+     * Function to run when the Tab is entered, this happens on first load as well
+     * @param params - from is previous tab (possibly undefined on first load), to is always this tab;
+     *                 type {@link INavigationBarTab}, recycled is whether the component was recycled or not
+     */
+    onTabEnter(params: OnTabEnterParams): void;
+}
+export interface OnTabLeave {
+    /**
+     * Function to run when the Tab is left
+     * @param params - from is always this tab, to is where the user is going; type {@link INavigationBarTab}
+     */
+    onTabLeave(params: OnTabLeaveParams): void;
+}
+export interface TabToolbarFor<T = any> {
+    currentComponentAndTab?: {
+        tab: INavigationBarTabs;
+        component: T;
+    };
+    onAttachComponent?(): void;
+}
+export interface TabWithToolbar<T> {
+    currentToolbar?: T;
+    onAttachToolbar?(): void;
+}
+export interface OnTabClose {
+    /**
+     * @param tab the current tab model that is closing.
+     */
+    onTabClose(tab: INavigationBarTab): boolean | Promise<boolean> | Observable<boolean>;
+}
+export interface OnTabSaveConfirm {
+    /**
+     * @param tab the current tab model that is closing.
+     */
+    onTabSaveConfirm(tab: INavigationBarTab): INavigationBarTabSaveOptions | undefined;
+}
+export interface INavigationBarTabSaveOptions {
+    dialogTitle: string;
+    dialogMessage: string;
+    saveFunction(): Promise<boolean> | Observable<boolean> | boolean;
+}
+export declare type WebElementTabApi<NavBarDataType = any, ComponentType = any> = Omit<PotentialTabItem<NavBarDataType, ComponentType>, "onAttachTab" | keyof TabWithToolbar<ComponentType>> & {
+    onAttachTab?(tab: INavigationBarTab<NavBarDataType>): void;
+};
+export declare type WebTabApiElement = HTMLElement & {
+    tabApi?: WebElementTabApi;
+};

package/shell-tabs/shell-tabs-lifecycle-api.js

@@ -0,0 +1,14 @@
+import { expectType } from "../../shared/util/helper-functions";
+expectType(true);
+expectType(true);
+expectType(true);
+expectType(true);
+expectType(true);
+expectType(true);
+expectType(true);
+expectType(true);
+expectType(true);
+expectType(true);
+expectType(true);
+expectType(true);
+expectType(true);