@sassoftware/vi-api 1.51.1 → 1.53.0

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

@@ -12,45 +12,45 @@ export interface INavigationBarTabs<D1 = any, D2 = D1> {
 export interface INavigationBarTab<D = {
     [key: string]: any;
 }, SecondaryData = D> {
-    /** unique tab id */
+    /** Unique tab identifier */
     id: string;
-    /** url relative to shell root e.g. /user/123 - this must start with a / */
+    /** URL relative to shell root (e.g., /user/123) - must start with a forward slash */
     routeUrl: string;
-    /** label for the tab, can be String or the resource.key (if .isLabelResourceKey:true) */
+    /** Label for the tab, can be a string or resource key (if isLabelResourceKey is true) */
     label: string;
-    /** a weight used during .sort to order the tabs; will default to the order the tabs came as
-     * doesn't mean their array index, as many can be the same, negatives, fractions
-     * */
+    /** Weight used during sorting to order the tabs; defaults to the order in which tabs were added.
+     * This doesn't refer to array index, as many tabs can have the same value, including negatives and fractions.
+     */
     sortIndex?: number;
-    /** when true, will use resourceService.get to resolve INavigationBarTab.label */
+    /** When true, uses resourceService.get to resolve INavigationBarTab.label */
     isLabelResourceKey?: boolean;
-    /** font icon */
+    /** Font icon */
     icon?: string;
-    /**  image url */
+    /** Image URL */
     img?: string;
-    /** aria-controls id */
+    /** aria-controls ID */
     controlsId?: string;
-    /** list  of secondary tabs which will be displayed under the top-level tab */
+    /** List of secondary tabs displayed under the top-level tab */
     secondaryTabs?: Array<ISecondaryNavigationBarTab<SecondaryData>>;
-    /** keep track of the currently selected secondary tab */
+    /** Currently selected secondary tab */
     selectedSecondaryTab?: ISecondaryNavigationBarTab<SecondaryData>;
-    /** callback to configure save confirm actions on close. */
+    /** Callback to configure save confirmation actions on close */
     getSaveOptions?(tab: INavigationBarTab): INavigationBarTabSaveOptions | undefined;
-    /** callback when tab is removed */
+    /** Callback executed when tab is removed */
     onClose?(tab: INavigationBarTab): Promise<boolean> | Observable<boolean> | boolean;
-    /** mark tab as dirty */
+    /** Mark tab as having unsaved changes */
     dirty?: boolean;
-    /** visually disable and make tab unselectable */
+    /** Visually disable and make tab unselectable */
     disabled?: boolean;
-    /** visually hide tab and make unselectable */
+    /** Visually hide tab and make it unselectable */
     hidden?: boolean;
-    /** exclude tab from appearing in the navigation bar system tab menu */
+    /** Exclude tab from appearing in the navigation bar system tab menu */
     excludedFromSystemMenu?: boolean;
-    /** visually hide secondary tabs bar for a tab */
+    /** Visually hide secondary tabs bar for this tab */
     hideSecondaryTabs?: boolean;
-    /** indicate that the tab is associated with some new object being created. */
+    /** Indicate that the tab is associated with a new object being created */
     creating?: boolean;
-    /** any extra data to be associated with the tab */
+    /** Any additional data to be associated with the tab */
     data?: D;
 }
 export type ISecondaryNavigationBarTab<D = {
@@ -58,15 +58,15 @@ export type ISecondaryNavigationBarTab<D = {
 }> = Omit<INavigationBarTab<D>, "secondaryTabs" | "selectedSecondaryTab">;
 export interface SviShellTabData {
     /**
-     * required user capabilities for the tab.
-     * if unmet, the tab is hidden and cannot be navigated to.
+     * Required user capabilities for the tab.
+     * If unmet, the tab is hidden and cannot be navigated to.
      * @example
      * { or: ["svi.administration.alerts", "svi.vsd.flow.view"] }
      */
     requiredCapabilities?: RequiredResourcesExpression;
     /**
      * REST APIs required by the tab's content.
-     * if unavailable, the tab is hidden and cannot be navigated to.
+     * If unavailable, the tab is hidden and cannot be navigated to.
      * @example
      * { and: ["svi-alert", "documentGeneratorAdapter"] }
      */
@@ -82,41 +82,41 @@ export interface SviShellTabData {
 }
 export interface ExternalTabConfig<T = SviShellTabData, P = any> {
     /**
-     * will try to place at this index, can be negative, fraction, etc to put before/between existing tabs
+     * 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
+     * Finds TabId, and adds this as a secondaryTab to that tab.
      */
     mainTabId?: string;
     /**
-     * this is the element/tag name that will get presented
+     * This is the element/tag name that will be 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)
+     * 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
+     * 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 is true.
      */
     buildTab: (fullUrl?: string, params?: P) => INavigationBarTab<T>;
     /**
-     * add as a systemTab?, if left out will default to applicationTab, ignored if mainTabId is defined
+     * Add as a system tab. If left out will default to application tab, ignored if mainTabId is defined.
      */
     systemTab?: boolean;
     /**
-     * set this to true if you want the component to reset every time you navigate away
+     * 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.
+     * 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 cannot be provided and must be assumed undefined.
+     * A secondaryTab (one that has mainTabId) will be created regardless of this flag.
      */
     buildOnRegister?: boolean;
 }
@@ -132,27 +132,27 @@ export interface ShellTabsApi<T = SviShellTabData> {
     /**
      * @method
      * @description This is used to expose any {@link PotentialTabItem} hooks on a component up to the Tab Service.
-     * @param {any} context pass "this"
-     * @param {HTMLElement} nativeElement This will pass the ElementRef for the component
+     * @param {any} context Pass "this".
+     * @param {HTMLElement} nativeElement This will 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 box can be created whe closing a dirty tab.
+     *  onTabClose {@link OnTabClose}, optional, can be used to prevent closing of a tab or close async.
+     *  onAttachTab {@link OnAttachTab}, will always trigger when currentNavigationBarTab is 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 box can be created when closing a dirty tab.
      */
     createTabApiForElement: (context: any, nativeElement: HTMLElement) => void;
     /**
      * @method
      * @description Use this function to register new routes for tabs.
-     * @param {ExternalTabConfig[]} tab See {@link ExternalTabConfig}
+     * @param {ExternalTabConfig[]} tab See {@link ExternalTabConfig}.
      */
     registerExternalTabs: (tab: Array<ExternalTabConfig<T>>) => void;
     /**
      * @method
      * @description Use this function to remove routes added via registerTabFn.
-     * @param {ExternalTabConfig[]} tabsToRemove See {@link ExternalTabConfig}
+     * @param {ExternalTabConfig[]} tabsToRemove See {@link ExternalTabConfig}.
      */
     unregisterExternalTabs: (tabsToRemove: Array<ExternalTabConfig<T>>) => void;
     /**
@@ -165,12 +165,12 @@ export interface ShellTabsApi<T = SviShellTabData> {
     };
     /**
      * @method
-     * @description This stream will track the current top level tab.
+     * @description This stream will track the current top-level tab.
      */
     selectedPrimaryTabChanged$: Observable<INavigationBarTab>;
     /**
      * @method
-     * @description This stream will track the current second level tab.
+     * @description This stream will track the current second-level tab.
      */
     selectedSecondaryTabChanged$: Observable<INavigationBarTab | undefined>;
     /**
@@ -188,7 +188,7 @@ export interface ShellTabsApi<T = SviShellTabData> {
     tabRemoved$: Observable<INavigationBarTab>;
     /**
      * @method
-     * @description get Tab by ID
+     * @description Get Tab by ID.
      * @param [tabId] {string} This will be ID of an existing tab.
      */
     getTabById: (tabId: string) => INavigationBarTab | undefined;
@@ -207,10 +207,10 @@ export interface ShellTabsApi<T = SviShellTabData> {
     selectDefaultTab: () => Promise<boolean>;
     /**
      * @method
-     * @description This 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] {INavigationBarTab} See {@link INavigationBarTab}
-     * @param [secondaryTab] {INavigationBarTab} See {@link INavigationBarTab} if left undefined, this will select the previously
+     * @description This 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] {INavigationBarTab} See {@link INavigationBarTab}.
+     * @param [secondaryTab] {INavigationBarTab} See {@link INavigationBarTab}. If left undefined, this will select the previously
      * selected secondary tab of the primary tab or its first index secondary tab.
      */
     openTab: (tabToSelect: INavigationBarTab, secondaryTab?: INavigationBarTab) => Promise<boolean>;
@@ -229,10 +229,10 @@ export interface ShellTabsApi<T = SviShellTabData> {
     removeApplicationTabById: (tabIdToRemove: string, suppressNavigation?: boolean) => Promise<boolean>;
     /**
      * @method
-     * @description This 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.
+     * @description This 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] {string} This will be ID of an existing tab.
-     * @param [newTab] {INavigationBarTab} See {@link INavigationBarTab}
+     * @param [newTab] {INavigationBarTab} See {@link INavigationBarTab}.
      *
      */
     replaceApplicationTab: (tabId: string, newTab: INavigationBarTab) => Promise<boolean>;

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

@@ -1,3 +1,4 @@
+// eslint-disable-next-line no-restricted-imports -- these get tree shaken out
 import { expectType } from "../../shared/util/helper-functions";
 expectType(true);
 expectType(true);

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

@@ -20,16 +20,16 @@ export interface OnTabEnterParams {
 export 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
+     * Function to run when the tab is entered. This happens on first load as well.
+     * @param params - from is the previous tab (possibly undefined on first load), to is always this tab;
+     *                 type {@link INavigationBarTab}, recycled indicates 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}
+     * 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;
 }
@@ -46,13 +46,13 @@ export interface TabWithToolbar<T> {
 }
 export interface OnTabClose {
     /**
-     * @param tab the current tab model that is closing.
+     * @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.
+     * @param tab The current tab model that is closing.
      */
     onTabSaveConfirm(tab: INavigationBarTab): INavigationBarTabSaveOptions | undefined;
 }

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

@@ -1,3 +1,4 @@
+// eslint-disable-next-line no-restricted-imports -- these get tree shaken out
 import { expectType } from "../../shared/util/helper-functions";
 expectType(true);
 expectType(true);