@xh/hoist 79.0.0-SNAPSHOT.1766020485210 → 79.0.0-SNAPSHOT.1766094533168

package/CHANGELOG.md

@@ -5,12 +5,20 @@
 ### 🎁 New Features
 
 * Enhance `LocalDate` with `addWeekdays` and `subtractWeekdays` methods.
+* Added new `DynamicTabSwitcher` component, a more user-customizable version of `TabSwitcher` that
+  allows for dynamic addition, removal, and drag-and-drop reordering of tabs with the ability to
+  persist "favorited" tab state across sessions. Additionally, existing static `TabSwitcher` now
+  supports context-menu items. See `TabContainerConfig.switcher`.
 
 ### 💥 Breaking Changes
 
 * Renamed `GridModel.applyColumnStateChanges()` to `updateColumnState()` for clarity and better
   symmetry with `setColumnState()`. The prior method remains as an alias but is now deprecated and
   scheduled for removal in v82.
+* `TabSwitcherProps` has moved to `cmp/tab/Types.ts` but is still exported from `cmp/tab/index.ts`.
+  Some apps may need to update their imports.
+* `TabContainerConfig.switcher` has been repurposed to accept a `TabSwitcherConfig`. To pass
+  `TabSwitcherProps` via a parent `TabContainer`, use `TabContainerProps.switcher`.
 
 ### 🐞 Bug Fixes
 

package/admin/AppComponent.ts

@@ -22,7 +22,15 @@ export const AppComponent = hoistCmp({
         return panel({
             tbar: tbar(),
             className: 'xh-admin-app',
-            item: tabContainer()
+            item: tabContainer({
+                switcher: false,
+                childContainerProps: ({tabId}) => ({
+                    switcher: {
+                        orientation: 'left',
+                        testId: `${tabId}-tab-switcher`
+                    }
+                })
+            })
         });
     }
 });

package/admin/AppModel.ts

@@ -37,7 +37,6 @@ export class AppModel extends HoistAppModel {
 
         this.tabModel = new TabContainerModel({
             route: 'default',
-            switcher: false,
             tabs: this.createTabs()
         });
 
@@ -130,7 +129,6 @@ export class AppModel extends HoistAppModel {
                 id: 'general',
                 icon: Icon.info(),
                 content: {
-                    switcher: {orientation: 'left', testId: 'general-tab-switcher'},
                     tabs: [
                         {id: 'about', icon: Icon.info(), content: aboutPanel},
                         {id: 'config', icon: Icon.settings(), content: configPanel},
@@ -142,7 +140,6 @@ export class AppModel extends HoistAppModel {
                 id: 'servers',
                 icon: Icon.server(),
                 content: {
-                    switcher: {orientation: 'left', testId: 'cluster-tab-switcher'},
                     tabs: [
                         {id: 'instances', icon: Icon.server(), content: instancesTab},
                         {id: 'objects', icon: Icon.boxFull(), content: clusterObjectsPanel}
@@ -163,7 +160,6 @@ export class AppModel extends HoistAppModel {
                 id: 'userData',
                 icon: Icon.users(),
                 content: {
-                    switcher: {orientation: 'left', testId: 'user-data-tab-switcher'},
                     refreshMode: 'onShowAlways',
                     tabs: [
                         {

package/admin/tabs/cluster/instances/InstancesTab.ts

@@ -53,7 +53,7 @@ export const detailPanel = hoistCmp.factory<InstancesTabModel>({
                 tabSwitcher()
             ],
             flex: 1,
-            item: tabContainer()
+            item: tabContainer({switcher: false})
         });
     }
 });

package/admin/tabs/cluster/instances/InstancesTabModel.ts

@@ -193,7 +193,6 @@ export class InstancesTabModel extends HoistModel {
     private createTabContainerModel() {
         return new TabContainerModel({
             route: 'default.servers.instances',
-            switcher: false,
             tabs: [
                 {id: 'logs', icon: Icon.fileText(), content: logViewer},
                 {id: 'memory', icon: Icon.memory(), content: memoryMonitorPanel},

package/admin/tabs/userData/roles/details/RoleDetailsModel.ts

@@ -69,7 +69,6 @@ export class RoleDetailsModel extends HoistModel {
 
     private createTabContainerModel(): TabContainerModel {
         return new TabContainerModel({
-            switcher: true,
             tabs: [
                 {
                     id: 'users',

package/build/types/cmp/tab/TabContainer.d.ts

@@ -1,12 +1,27 @@
+import { TabSwitcherProps } from '@xh/hoist/cmp/tab/Types';
 import { BoxProps, HoistProps } from '@xh/hoist/core';
 import { TabContainerModel } from './TabContainerModel';
-export type TabContainerProps = HoistProps<TabContainerModel> & BoxProps;
+export interface TabContainerProps extends HoistProps<TabContainerModel>, BoxProps {
+    /**
+     * Indicates whether to include a default switcher docked within this component. Specify as a
+     * boolean or props for a TabSwitcher component. False to not include a switcher. Default true.
+     */
+    switcher?: boolean | TabSwitcherProps;
+    /**
+     * Props to apply to child TabContainers, if any. Specify as an object or a function
+     * that returns props based on the tabId and depth of the child container.
+     */
+    childContainerProps?: TabContainerProps | ((ctx: {
+        tabId: string;
+        depth: number;
+    }) => TabContainerProps);
+}
 /**
  * Display a set of child Tabs and (optionally) a switcher control.
  *
- * By default this TabContainer will install a TabSwitcher above the Tabs to control the currently
- * displayed Tab. The 'TabContainerModel.switcher' property can be adjusted to place the switcher
- * control on alternative edges of the container.
+ * By default, this TabContainer will install a TabSwitcher above the Tabs to control the currently
+ * displayed Tab. The 'switcher' prop can be adjusted to place the switcher control on alternative
+ * edges of the container.
  *
  * If `switcher` is set to false then no TabSwitcher will be installed.  This setting
  * is useful for applications that wish to place an associated TabSwitcher elsewhere in the

package/build/types/cmp/tab/TabContainerModel.d.ts

@@ -1,7 +1,7 @@
-import { HoistModel, Persistable, PersistableState, PersistOptions, RefreshContextModel, RefreshMode, RenderMode } from '@xh/hoist/core';
+import { TabSwitcherConfig, IDynamicTabSwitcherModel } from '@xh/hoist/cmp/tab/Types';
+import { HoistModel, PersistOptions, RefreshContextModel, RefreshMode, RenderMode } from '@xh/hoist/core';
 import { ReactNode } from 'react';
 import { TabConfig, TabModel } from './TabModel';
-import { TabSwitcherProps } from './TabSwitcherProps';
 export interface TabContainerConfig {
     /** Tabs to be displayed. */
     tabs: TabConfig[];
@@ -16,11 +16,10 @@ export interface TabContainerConfig {
      */
     route?: string;
     /**
-     * Indicates whether to include a default switcher docked within this component. Specify as a
-     * boolean or an object containing props for a TabSwitcher component. Set to false to not
-     * include a switcher. Defaults to true.
+     * Specification for type of switcher. Specify `dynamic` or config for user-configurable tabs.
+     * Default `{mode: 'static'}` for simple, static switcher.
      */
-    switcher?: boolean | TabSwitcherProps;
+    switcher?: TabSwitcherConfig;
     /**
      * True to enable activity tracking of tab views (default false).  Viewing of each tab will
      * be tracked with the `oncePerSession` flag, to avoid duplication.
@@ -54,22 +53,26 @@ export interface TabContainerConfig {
  *
  * Note: Routing is currently enabled for desktop applications only.
  */
-export declare class TabContainerModel extends HoistModel implements Persistable<{
-    activeTabId: string;
-}> {
+export declare class TabContainerModel extends HoistModel {
     config: TabContainerConfig;
     tabs: TabModel[];
     activeTabId: string;
+    depth: number;
     route: string;
     defaultTabId: string;
-    switcher: TabSwitcherProps;
     track: boolean;
     renderMode: RenderMode;
     refreshMode: RefreshMode;
     emptyText: ReactNode;
+    switcherConfig: TabSwitcherConfig;
     refreshContextModel: RefreshContextModel;
+    dynamicTabSwitcherModel: IDynamicTabSwitcherModel;
     protected lastActiveTabId: string;
-    constructor({ tabs, defaultTabId, route, switcher, track, renderMode, refreshMode, persistWith, emptyText, xhImpl }: TabContainerConfig);
+    /**
+     * @param config - TabContainer configuration.
+     * @param [depth] - Depth in hierarchy of nested TabContainerModels. Not for application use.
+     */
+    constructor({ tabs, defaultTabId, route, track, renderMode, refreshMode, persistWith, emptyText, xhImpl, switcher }: TabContainerConfig, depth?: number);
     /** Set/replace all tabs within the container. */
     setTabs(tabs: Array<TabModel | TabConfig>): void;
     /** Add a single tab to the container. */
@@ -88,9 +91,9 @@ export declare class TabContainerModel extends HoistModel implements Persistable
     /** Find a tab that is an immediate child of this container. */
     findTab(id: string): TabModel;
     get activeTab(): TabModel;
-    /** The tab immediately before the active tab in the model's tab list. */
+    /** The visitable tab immediately before the active tab in the model's tab list. */
     get prevTab(): TabModel;
-    /** The tab immediately after the active tab in the model's tab list. */
+    /** The visitable tab immediately after the active tab in the model's tab list. */
     get nextTab(): TabModel;
     /**
      * Set the currently active Tab.
@@ -114,16 +117,12 @@ export declare class TabContainerModel extends HoistModel implements Persistable
      * @param cycle - true to loop back to first tab if necessary.
      */
     activateNextTab(cycle?: boolean): void;
-    getPersistableState(): PersistableState<{
-        activeTabId: string;
-    }>;
-    setPersistableState(state: PersistableState<{
-        activeTabId: string;
-    }>): void;
     protected setActiveTabIdInternal(id: any): void;
     protected syncWithRouter(): void;
     protected forwardRouterToTab(id: any): void;
     protected calculateActiveTabId(tabs: any): any;
+    private parseSwitcher;
+    private initPersist;
 }
 export interface AddTabOptions {
     /** Index in tab collection where tab is to be added. */

package/build/types/cmp/tab/Types.d.ts

@@ -0,0 +1,61 @@
+import { TabContainerModel } from '@xh/hoist/cmp/tab/TabContainerModel';
+import { TabModel } from '@xh/hoist/cmp/tab/TabModel';
+import { BoxProps, HoistModel, HoistProps, MenuContext, MenuItemLike, MenuToken, PersistOptions, Side } from '@xh/hoist/core';
+export interface TabSwitcherProps extends HoistProps<TabContainerModel>, BoxProps {
+    /** Relative position within the parent TabContainer. Defaults to 'top'. */
+    orientation?: Side;
+    /**
+     * True to animate the indicator when switching tabs. False (default) to change instantly.
+     * Not supported by DynamicTabSwitcher.
+     */
+    animate?: boolean;
+    /**
+     * Enable scrolling and place tabs that overflow into a menu. Default to false.
+     * Not supported by DynamicTabSwitcher.
+     */
+    enableOverflow?: boolean;
+    /** Width (in px) to render tabs. Only applies to horizontal orientations */
+    tabWidth?: number;
+    /** Minimum width (in px) to render tabs. Only applies to horizontal orientations */
+    tabMinWidth?: number;
+    /** Maximum width (in px) to render tabs. Only applies to horizontal orientations */
+    tabMaxWidth?: number;
+}
+export interface TabSwitcherConfig {
+    /** Specification for type of switcher. Specify `dynamic`for user-configurable tabs */
+    mode: 'static' | 'dynamic';
+    /** Additional menu items to include in tab context menus. Only supported on desktop */
+    extraMenuItems?: Array<MenuItemLike<MenuToken, TabSwitcherMenuContext>>;
+    /** IDs of favorite tabs to display by default (in order). Only for `dynamic` switchers */
+    initialFavorites?: string[];
+}
+export interface TabContainerModelPersistOptions extends PersistOptions {
+    /** True (default) to persist the active tab ID or provide custom PersistOptions. */
+    persistActiveTabId?: boolean;
+    /** True (default) to persist favorite tab IDs or provide custom PersistOptions. */
+    persistFavoriteTabIds?: boolean;
+}
+export interface TabSwitcherMenuContext extends MenuContext {
+    tab: TabModel;
+}
+/** Cross-platform interface for desktop and mobile (TBA) DynamicTabSwitcherModels. */
+export interface IDynamicTabSwitcherModel extends HoistModel {
+    /** IDs of favorite tabs, in order. */
+    get favoriteTabIds(): string[];
+    /** Tabs displayed in switcher, in order. */
+    get visibleTabs(): TabModel[];
+    /** Enabled tabs displayed in switcher, in order. */
+    get enabledVisibleTabs(): TabModel[];
+    /** Whether the specified tab is currently active in the TabContainer. */
+    isTabActive(tabId: string): boolean;
+    /** Whether the specified tab is currently marked as a favorite. */
+    isTabFavorite(tabId: string): boolean;
+    /** Toggle the favorite status of the specified tab. */
+    toggleTabFavorite(tabId: string): void;
+    /** Activate the specified tab in the TabContainer. */
+    activate(tabId: string): void;
+    /** Remove the specified tab from the switcher. */
+    hide(tabId: string): void;
+    /** Set the IDs of all favorite tabs, in order. */
+    setFavoriteTabIds(tabIds: string[]): void;
+}

package/build/types/cmp/tab/index.d.ts

@@ -1,4 +1,4 @@
 export * from './TabModel';
 export * from './TabContainer';
 export * from './TabContainerModel';
-export * from './TabSwitcherProps';
+export * from './Types';

package/build/types/data/RecordAction.d.ts

@@ -17,7 +17,10 @@ export interface RecordActionSpec extends TestSupportProps {
     tooltip?: string;
     /** Function called on action execution. */
     actionFn?: (data: ActionFnData) => void;
-    /** Function called prior to showing this item. */
+    /**
+     * Function called to append / override display properties prior to each render. This function
+     * allows dynamic control over display properties.
+     * */
     displayFn?: (data: ActionFnData) => RecordActionSpec;
     /** Sub-actions for this action. */
     items?: RecordActionLike[];

package/build/types/desktop/cmp/tab/TabSwitcher.d.ts

@@ -1,4 +1,4 @@
-import { TabSwitcherProps } from '@xh/hoist/cmp/tab';
+import { TabSwitcherProps } from '@xh/hoist/cmp/tab/Types';
 import '@xh/hoist/desktop/register';
 /**
  * Component to indicate and control the active tab of a TabContainer.

package/build/types/desktop/cmp/tab/dynamic/DynamicTabSwitcher.d.ts

@@ -0,0 +1,7 @@
+import { TabSwitcherProps } from '@xh/hoist/cmp/tab/Types';
+import './DynamicTabSwitcher.scss';
+/**
+ * A tab switcher that displays tabs as draggable items in a horizontal list.
+ * Tabs can be added, removed, reordered and favorited with persistence.
+ */
+export declare const DynamicTabSwitcher: import("react").FC<TabSwitcherProps>, dynamicTabSwitcher: import("@xh/hoist/core").ElementFactory<TabSwitcherProps>;

package/build/types/desktop/cmp/tab/dynamic/DynamicTabSwitcherModel.d.ts

@@ -0,0 +1,30 @@
+import { TabContainerModel, TabModel } from '@xh/hoist/cmp/tab';
+import { IDynamicTabSwitcherModel, TabSwitcherConfig, TabSwitcherMenuContext } from '@xh/hoist/cmp/tab/Types';
+import { HoistModel, MenuItemLike, MenuToken } from '@xh/hoist/core';
+import React from 'react';
+/**
+ * State management for the DynamicTabSwitcher component.
+ * @internal
+ */
+export declare class DynamicTabSwitcherModel extends HoistModel implements IDynamicTabSwitcherModel {
+    config: TabSwitcherConfig;
+    private readonly extraMenuItems;
+    private readonly tabContainerModel;
+    private visibleTabState;
+    get favoriteTabIds(): string[];
+    get visibleTabs(): TabModel[];
+    get enabledVisibleTabs(): TabModel[];
+    constructor({ extraMenuItems, initialFavorites }: TabSwitcherConfig, tabContainerModel: TabContainerModel);
+    isTabActive(tabId: string): boolean;
+    isTabFavorite(tabId: string): boolean;
+    toggleTabFavorite(tabId: string): void;
+    activate(tabId: string): void;
+    hide(tabId: string): void;
+    getContextMenuItems(e: React.MouseEvent<HTMLDivElement, MouseEvent>, tab: TabModel): Array<MenuItemLike<MenuToken, TabSwitcherMenuContext>>;
+    setFavoriteTabIds(tabIds: string[]): void;
+    onDragEnd(result: any): void;
+    private activeTabReaction;
+    private getValidTabIds;
+    private isValidTabId;
+    private isTabVisible;
+}

package/build/types/desktop/cmp/tab/dynamic/scroller/Scroller.d.ts

@@ -0,0 +1,19 @@
+import { BoxProps, HoistProps } from '@xh/hoist/core';
+import { ScrollerModel } from '@xh/hoist/desktop/cmp/tab/dynamic/scroller/ScrollerModel';
+import React, { Ref } from 'react';
+/**
+ * A scroller component that displays a content component with directional scroll buttons when the
+ * content overflows the viewport.
+ * @internal
+ */
+export interface ScrollerProps extends HoistProps<ScrollerModel>, Omit<BoxProps, 'content'> {
+    /** The content to be displayed within the scroller. */
+    content: React.FC<{
+        ref: Ref<HTMLDivElement>;
+    }>;
+    /** Props to be passed to the content component. */
+    contentProps?: Record<string, any>;
+    /** Orientation of the scroller - horizontal (default) or vertical. */
+    orientation?: 'horizontal' | 'vertical';
+}
+export declare const Scroller: React.FC<ScrollerProps>, scroller: import("@xh/hoist/core").ElementFactory<ScrollerProps>;

package/build/types/desktop/cmp/tab/dynamic/scroller/ScrollerModel.d.ts

@@ -0,0 +1,23 @@
+import { HoistModel } from '@xh/hoist/core';
+/**
+ * Internal model for the Scroller component. Used to manage the scroll state and provide
+ * scroll functionality. Uses animation frames to ensure smooth scrolling.
+ * @internal
+ */
+export declare class ScrollerModel extends HoistModel {
+    contentRef: import("react").RefObject<HTMLDivElement>;
+    private scrollStart;
+    private scrollSize;
+    private clientSize;
+    private animationFrameId;
+    get showScrollButtons(): boolean;
+    get isScrolledToStart(): boolean;
+    get isScrolledToEnd(): boolean;
+    get isHorizontal(): boolean;
+    constructor();
+    afterLinked(): void;
+    scroll(direction: 'forward' | 'backward'): void;
+    stopScrolling(): void;
+    onViewportEvent(): void;
+    destroy(): void;
+}

package/build/types/desktop/cmp/tab/impl/Tab.d.ts

@@ -1,4 +1,5 @@
-import { TabModel } from '@xh/hoist/cmp/tab';
+import { TabContainerProps, TabModel } from '@xh/hoist/cmp/tab';
+import { HoistProps, TestSupportProps } from '@xh/hoist/core';
 /**
  * Wrapper for contents to be shown within a TabContainer. This Component is used by TabContainer's
  * internal implementation to:
@@ -9,4 +10,8 @@ import { TabModel } from '@xh/hoist/cmp/tab';
  *
  * @internal
  */
-export declare const tab: import("@xh/hoist/core").ElementFactory<import("@xh/hoist/core").DefaultHoistProps<TabModel>>;
+interface TabProps extends HoistProps<TabModel>, TestSupportProps {
+    childContainerProps?: TabContainerProps['childContainerProps'];
+}
+export declare const tab: import("@xh/hoist/core").ElementFactory<TabProps>;
+export {};

package/build/types/desktop/cmp/tab/impl/TabContainer.d.ts

@@ -4,4 +4,4 @@ import '../Tabs.scss';
  * Desktop implementation of TabContainer.
  * @internal
  */
-export declare function tabContainerImpl({ model, className, testId, ...props }: TabContainerProps): import("react").ReactElement<import("@xh/hoist/cmp/layout").BoxComponentProps, any>;
+export declare function tabContainerImpl({ model, childContainerProps, className, testId, ...props }: TabContainerProps): import("react").ReactElement<import("@xh/hoist/cmp/layout").BoxComponentProps, any>;

package/build/types/desktop/cmp/tab/impl/TabContextMenuItems.d.ts

@@ -0,0 +1,4 @@
+import { TabSwitcherMenuContext } from '@xh/hoist/cmp/tab';
+import { type MenuItemLike, MenuToken } from '@xh/hoist/core';
+/** @internal */
+export declare function getContextMenuItem(item: MenuItemLike<MenuToken, TabSwitcherMenuContext>, context: TabSwitcherMenuContext): MenuItemLike<MenuToken, TabSwitcherMenuContext>;

package/build/types/desktop/cmp/tab/index.d.ts

@@ -1 +1,2 @@
 export * from './TabSwitcher';
+export * from './dynamic/DynamicTabSwitcher';

package/build/types/dynamics/desktop.d.ts

@@ -22,6 +22,7 @@ export declare let tabContainerImpl: any;
 export declare let useContextMenu: any;
 export declare let errorMessageImpl: any;
 export declare let maskImpl: any;
+export declare let DynamicTabSwitcherModel: any;
 /**
  * Provide implementations of functions and classes exported in this file.
  *

package/build/types/mobile/cmp/tab/impl/TabContainer.d.ts

@@ -6,4 +6,4 @@ import { TabContainerProps } from '@xh/hoist/cmp/tab';
  *
  * @internal
  */
-export declare function tabContainerImpl({ model, className }: TabContainerProps): import("react").ReactElement<any, any>;
+export declare function tabContainerImpl({ model, className, ...props }: TabContainerProps): import("react").ReactElement<any, any>;

package/cmp/tab/TabContainer.ts

@@ -4,19 +4,34 @@
  *
  * Copyright © 2025 Extremely Heavy Industries Inc.
  */
+import {TabSwitcherProps} from '@xh/hoist/cmp/tab/Types';
 import {BoxProps, hoistCmp, HoistProps, refreshContextView, uses, XH} from '@xh/hoist/core';
 import {tabContainerImpl as desktopTabContainerImpl} from '@xh/hoist/dynamics/desktop';
 import {tabContainerImpl as mobileTabContainerImpl} from '@xh/hoist/dynamics/mobile';
 import {TabContainerModel} from './TabContainerModel';
 
-export type TabContainerProps = HoistProps<TabContainerModel> & BoxProps;
+export interface TabContainerProps extends HoistProps<TabContainerModel>, BoxProps {
+    /**
+     * Indicates whether to include a default switcher docked within this component. Specify as a
+     * boolean or props for a TabSwitcher component. False to not include a switcher. Default true.
+     */
+    switcher?: boolean | TabSwitcherProps;
+
+    /**
+     * Props to apply to child TabContainers, if any. Specify as an object or a function
+     * that returns props based on the tabId and depth of the child container.
+     */
+    childContainerProps?:
+        | TabContainerProps
+        | ((ctx: {tabId: string; depth: number}) => TabContainerProps);
+}
 
 /**
  * Display a set of child Tabs and (optionally) a switcher control.
  *
- * By default this TabContainer will install a TabSwitcher above the Tabs to control the currently
- * displayed Tab. The 'TabContainerModel.switcher' property can be adjusted to place the switcher
- * control on alternative edges of the container.
+ * By default, this TabContainer will install a TabSwitcher above the Tabs to control the currently
+ * displayed Tab. The 'switcher' prop can be adjusted to place the switcher control on alternative
+ * edges of the container.
  *
  * If `switcher` is set to false then no TabSwitcher will be installed.  This setting
  * is useful for applications that wish to place an associated TabSwitcher elsewhere in the