@servicetitan/anvil2 3.0.7 → 3.0.9

package/dist/src/beta/components/TreeSelectField/internal/VirtualizedTreePanel.d.ts

@@ -0,0 +1,57 @@
+import { TreeSelectFieldNode } from '../types';
+import { VisibleNode } from './types';
+/**
+ * Props for the VirtualizedTreePanel component.
+ * @property visibleNodes - Flat list of currently visible tree nodes.
+ * @property getCheckState - Returns the visual check state for a node ID.
+ * @property toggleNode - Toggles selection for the given node ID.
+ * @property toggleExpand - Expands or collapses the given branch node ID.
+ * @property getTreeItemProps - Returns ARIA props for a given node ID.
+ * @property treeProps - ARIA props for the tree container element.
+ * @property activeDescendantId - The id attribute of the focused treeitem, for aria-activedescendant.
+ * @property branchesSelectable - When true, branch nodes can be selected.
+ * @property leavesSelectable - When true, leaf nodes can be selected.
+ * @property onLoadChildren - Callback to lazily load children for a node with children===null.
+ */
+export type VirtualizedTreePanelProps = {
+    visibleNodes: VisibleNode[];
+    getCheckState: (id: string | number) => "checked" | "unchecked" | "indeterminate" | "loading";
+    toggleNode: (id: string | number) => void;
+    toggleExpand: (id: string | number) => void;
+    getTreeItemProps: (id: string | number) => Record<string, unknown>;
+    treeProps: Record<string, unknown>;
+    activeDescendantId: string | undefined;
+    branchesSelectable?: boolean;
+    leavesSelectable?: boolean;
+    emptyBranchesSelectable?: boolean;
+    readOnly?: boolean;
+    onHover?: (id: string | number) => void;
+    onLoadChildren?: (node: TreeSelectFieldNode) => void;
+};
+/**
+ * VirtualizedTreePanel renders a virtualized tree list using @tanstack/react-virtual,
+ * only mounting DOM nodes for visible rows. Intended for large tree datasets.
+ *
+ * Features:
+ * - Only renders visible rows via @tanstack/react-virtual for performance
+ * - Same visual output and interaction model as a non-virtualized tree panel
+ * - Supports multi-select checkboxes and single-select modes
+ * - Expand/collapse branch nodes with optional lazy loading
+ * - Keyboard navigation via onKeyDown handler
+ * - Full ARIA tree semantics (role, aria-level, aria-expanded, etc.)
+ * - Optional child count display on branch nodes
+ * - Breadcrumb display for flattened search results
+ *
+ * @example
+ * <VirtualizedTreePanel
+ *   visibleNodes={visibleNodes}
+ *   getCheckState={getCheckState}
+ *   toggleNode={toggleNode}
+ *   toggleExpand={toggleExpand}
+ *   getTreeItemProps={getTreeItemProps}
+ *   treeProps={treeProps}
+ *   onKeyDown={onKeyDown}
+ *   activeDescendantId={activeDescendantId}
+ * />
+ */
+export declare const VirtualizedTreePanel: import('react').ForwardRefExoticComponent<VirtualizedTreePanelProps & import('react').RefAttributes<HTMLDivElement>>;

package/dist/src/beta/components/TreeSelectField/internal/treeSync.d.ts

@@ -0,0 +1,33 @@
+import { MatchSorterOptions } from 'match-sorter';
+import { TreeSelectFieldNode } from '../types';
+/**
+ * Filter function for narrowing tree options against a search value.
+ * Receives the full options tree and returns the (possibly pruned) tree to display.
+ */
+export type TreeSyncFilterFn = (options: TreeSelectFieldNode[], searchValue: string) => TreeSelectFieldNode[];
+/**
+ * Recursively populates `childCount` (number of immediate children) on every
+ * loaded branch that doesn't already declare one, returning a new tree.
+ *
+ * This is computed from the full static `options` *before* any search filter
+ * runs, so the count reflects the real child set rather than the filtered
+ * subset. `computeCheckStates` relies on `childCount` to detect that a branch
+ * is only partially represented (e.g. during search) and avoid showing a
+ * partially-selected branch as fully checked.
+ *
+ * @param nodes - The tree nodes to process.
+ * @returns A new array of nodes with childCount set on branch nodes.
+ */
+export declare function applyChildCounts(nodes: TreeSelectFieldNode[]): TreeSelectFieldNode[];
+/**
+ * Default tree-aware filter. Matches on label and searchText, preserving
+ * ancestors of matched nodes.
+ */
+export declare function defaultTreeSyncFilter(nodes: TreeSelectFieldNode[], searchValue: string): TreeSelectFieldNode[];
+/**
+ * Coerces a `TreeSyncFilterFn` or `MatchSorterOptions` into a
+ * `TreeSyncFilterFn`. When given options, the resulting filter flattens the
+ * tree, runs match-sorter, and prunes the original tree to keep ancestors of
+ * matched nodes.
+ */
+export declare function toTreeSyncFilterFn(filter: TreeSyncFilterFn | MatchSorterOptions<TreeSelectFieldNode>): TreeSyncFilterFn;

package/dist/src/beta/components/TreeSelectField/internal/treeUtils.d.ts

@@ -0,0 +1,25 @@
+import { TreeSelectFieldNode } from '../types';
+/**
+ * Recursively finds the first node in the tree matching the given id.
+ *
+ * @param nodes - The tree nodes to search.
+ * @param id - The id of the node to find.
+ * @returns The matching node, or undefined if no node has the given id.
+ */
+export declare function findNode(nodes: TreeSelectFieldNode[], id: string | number): TreeSelectFieldNode | undefined;
+/**
+ * Returns true when the given node or any of its descendants still need to
+ * be lazy-loaded (i.e. has `children: null`).
+ *
+ * @param node - The node to inspect.
+ * @returns Whether any descendant branch is still unloaded.
+ */
+export declare function hasUnloadedDescendants(node: TreeSelectFieldNode): boolean;
+/**
+ * Returns all descendant branches of the given node whose children have not
+ * yet been loaded (i.e. `children: null`). The node itself is not included.
+ *
+ * @param node - The ancestor node to walk.
+ * @returns Every descendant branch that still requires lazy loading.
+ */
+export declare function findUnloadedDescendants(node: TreeSelectFieldNode): TreeSelectFieldNode[];

package/dist/src/beta/components/TreeSelectField/internal/types.d.ts

@@ -0,0 +1,12 @@
+import { TreeSelectFieldNode } from '../types';
+/**
+ * Internal representation of a visible node in the flattened tree.
+ */
+export type VisibleNode = {
+    node: TreeSelectFieldNode;
+    depth: number;
+    isExpanded: boolean;
+    isBranch: boolean;
+    isLoading: boolean;
+    isEmptyPlaceholder?: boolean;
+};

package/dist/src/beta/components/TreeSelectField/internal/useTree.d.ts

@@ -0,0 +1,99 @@
+import { KeyboardEvent } from 'react';
+import { TreeSelectFieldNode, TreeSelectFieldValue, TreeSelectFieldValueConsistsOf } from '../types';
+import { VisibleNode } from './types';
+import { CheckState } from './useTreeCascade';
+/**
+ * Options for the useTree hook.
+ * @property nodes - The full tree data.
+ * @property value - Controlled selected values.
+ * @property onSelectedOptionsChange - Callback when selection changes.
+ * @property selectionMode - "single", "independent", or "linked" (default).
+ * @property valueConsistsOf - Controls which nodes are selectable and how the value is shaped.
+ * @property defaultExpandLevel - Initial expand depth. 0 = collapsed, Infinity = all.
+ * @property expandedIds - Controlled set of expanded node IDs.
+ * @property onExpandedIdsChange - Callback when expanded IDs change (controlled mode).
+ * @property searchValue - Filter string applied to the tree.
+ * @property ancestry - childId → parentId map from the loader, used to attribute
+ *   off-screen ("orphan") selections to their ancestor branches.
+ * @property loadingChildrenIds - Set of node IDs whose children are currently being fetched.
+ */
+export type UseTreeOptions = {
+    nodes: TreeSelectFieldNode[];
+    value: TreeSelectFieldValue[];
+    onSelectedOptionsChange: (nodes: TreeSelectFieldValue[]) => void;
+    selectionMode?: "single" | "independent" | "linked";
+    valueConsistsOf?: TreeSelectFieldValueConsistsOf;
+    defaultExpandLevel?: number;
+    expandedIds?: Set<string | number>;
+    onExpandedIdsChange?: (ids: Set<string | number>) => void;
+    searchValue?: string;
+    ancestry?: Map<string | number, string | number>;
+    loadingChildrenIds?: Set<string | number>;
+};
+/**
+ * ARIA props returned per tree item.
+ */
+export type TreeItemProps = {
+    id: string;
+    role: "treeitem";
+    "aria-level": number;
+    "aria-setsize": number;
+    "aria-posinset": number;
+    "aria-expanded"?: boolean;
+    "aria-selected": boolean;
+};
+/**
+ * ARIA props for the tree container.
+ */
+export type TreeContainerProps = {
+    role: "tree";
+    "aria-activedescendant": string | undefined;
+    "aria-multiselectable": boolean;
+};
+/**
+ * Return value from the useTree hook.
+ * @property visibleNodes - Flat list of currently visible nodes.
+ * @property getCheckState - Returns the visual check state for a node ID.
+ * @property toggleNode - Toggles selection for the given node ID.
+ * @property isExpanded - Returns whether the given node ID is expanded.
+ * @property toggleExpand - Expands or collapses the given branch node ID.
+ * @property expandAll - Expands all branch nodes.
+ * @property collapseAll - Collapses all branch nodes.
+ * @property activeDescendantId - The id attribute of the focused treeitem, for aria-activedescendant.
+ * @property onKeyDown - Keyboard event handler for the tree container.
+ * @property getTreeItemProps - Returns ARIA props for a given node ID.
+ * @property treeProps - ARIA props for the tree container element.
+ */
+export type UseTreeReturn = {
+    nodes: TreeSelectFieldNode[];
+    visibleNodes: VisibleNode[];
+    getCheckState: (id: string | number) => CheckState;
+    toggleNode: (id: string | number) => void;
+    isExpanded: (id: string | number) => boolean;
+    toggleExpand: (id: string | number) => void;
+    expandAll: () => void;
+    collapseAll: () => void;
+    activeDescendantId: string | undefined;
+    setActiveNodeId: (id: string | number) => void;
+    onKeyDown: (e: KeyboardEvent) => void;
+    getTreeItemProps: (id: string | number) => TreeItemProps;
+    treeProps: TreeContainerProps;
+};
+/**
+ * Core tree state hook that manages expansion, selection, keyboard navigation,
+ * search filtering, and ARIA attributes for a tree widget.
+ *
+ * Features:
+ * - Uncontrolled expansion state by default; fully controlled via expandedIds/onExpandedIdsChange
+ * - defaultExpandLevel for initial expansion depth
+ * - expandAll / collapseAll helpers
+ * - Delegates selection logic to computeCheckStates and toggleNodeSelection from useTreeCascade
+ * - valueConsistsOf determines which nodes are selectable
+ * - Search filtering that preserves tree structure
+ * - Full keyboard navigation (WAI-ARIA tree pattern)
+ * - ARIA attribute generation for tree container and tree items
+ *
+ * @param options - Configuration options for the tree state.
+ * @returns Tree state and handlers.
+ */
+export declare function useTree(options: UseTreeOptions): UseTreeReturn;

package/dist/src/beta/components/TreeSelectField/internal/useTreeCascade.d.ts

@@ -0,0 +1,93 @@
+import { TreeSelectFieldNode, TreeSelectFieldValue, TreeSelectFieldValueConsistsOf } from '../types';
+import { CheckState } from '../../../../types';
+export type { CheckState };
+/**
+ * Computes the visual check state for every node in the tree.
+ *
+ * In "linked" mode parents reflect the aggregate state of their children:
+ * - checked — all non-disabled children are checked
+ * - indeterminate — some but not all non-disabled children are checked
+ * - unchecked — no children are checked
+ *
+ * In "independent" / "single" mode (and for BRANCH_ONLY) each node is checked
+ * only when its id appears in the value array; no cascade is applied. A node's
+ * own selection lives in `value` regardless of what is loaded, so these modes
+ * are unaffected by lazy/filtered loading.
+ *
+ * ## Under-represented branches (lazy / filtered)
+ *
+ * In linked mode a branch's aggregate state is derived from its children. But
+ * the tree passed in is only ever what is currently *loaded* — during search it
+ * is the filtered subset, and lazy branches (`children === null`) or partially
+ * loaded branches don't expose their full child set. A branch is
+ * "under-represented" when its loaded children are known to be fewer than its
+ * real children (`children === null`, or `loadedCount < childCount`). For these
+ * we infer rather than aggregate:
+ * - the branch's own id is checked → `checked`
+ * - any *loaded* descendant is checked/indeterminate → `indeterminate`
+ *   (it can't be fully checked because unknown children exist)
+ * - otherwise, if the branch is a known ancestor of an "orphan" selection (a
+ *   checked id that isn't in the currently-loaded tree — e.g. a descendant of a
+ *   collapsed lazy branch), via `orphanAncestorIds` → `indeterminate`
+ * - otherwise → `unchecked`
+ *
+ * Orphan attribution is *path-scoped*: only branches on the resolved ancestor
+ * path of an orphaned selection are marked, so unrelated collapsed siblings stay
+ * `unchecked`. The caller resolves those ancestors (from a value's `path` or the
+ * loader's ancestry map) and passes them in `orphanAncestorIds`. An orphan whose
+ * ancestry is unknown contributes nothing (its branch shows `unchecked` until
+ * its parent loads, then self-corrects).
+ *
+ * One limitation remains: accurate filtered-branch state requires
+ * server-/consumer-provided `childCount` — a partially-loaded branch without a
+ * `childCount` falls back to aggregating only its visible children.
+ *
+ * @param nodes - The currently loaded (possibly filtered) tree.
+ * @param value - The current value array.
+ * @param selectionMode - "single", "independent", or "linked".
+ * @param valueConsistsOf - Strategy used when computing check states.
+ * @param orphanAncestorIds - Branch ids that lie on the resolved ancestor path
+ *   of an orphaned selection. Such under-represented branches render
+ *   `indeterminate`. Defaults to empty (no orphan inference).
+ * @returns A Map from node id to CheckState.
+ */
+export declare function computeCheckStates(nodes: TreeSelectFieldNode[], value: TreeSelectFieldValue[], selectionMode: "single" | "independent" | "linked", valueConsistsOf: TreeSelectFieldValueConsistsOf, orphanAncestorIds?: Set<string | number>): Map<string | number, CheckState>;
+/**
+ * Given a set of checked node IDs and a value strategy, returns the value
+ * array according to the strategy.
+ *
+ * - "ALL" — every checked node
+ * - "BRANCH_PRIORITY" — branch replaces its leaves when all non-disabled
+ *     children are checked; otherwise individual leaves
+ * - "LEAF_PRIORITY" — leaves only, unless the node is a branch with an empty
+ *     or null children list (leaf-less branch)
+ * - "LEAF_ONLY" — strictly leaves; branches are never included
+ *
+ * @param nodes - The full tree.
+ * @param checkedIds - Set of IDs that are checked.
+ * @param valueConsistsOf - Strategy to apply.
+ * @returns The value array.
+ */
+export declare function computeValue(nodes: TreeSelectFieldNode[], checkedIds: Set<string | number>, valueConsistsOf: TreeSelectFieldValueConsistsOf): TreeSelectFieldValue[];
+/**
+ * Toggles a node's selection and returns the new value array.
+ *
+ * In "single" mode:
+ * - Replaces the entire selection with the clicked node (or empties if already selected).
+ *
+ * In "independent" mode:
+ * - Only the clicked node is toggled; no cascade.
+ *
+ * In "linked" mode:
+ * - Selecting a branch selects all non-disabled descendants recursively.
+ * - Deselecting a branch deselects all non-disabled descendants recursively.
+ * - Disabled nodes are never modified.
+ *
+ * @param nodes - The full tree.
+ * @param currentValue - The current value array.
+ * @param nodeId - The id of the node to toggle.
+ * @param selectionMode - "single", "independent", or "linked".
+ * @param valueConsistsOf - Strategy to apply when computing the returned value.
+ * @returns The new value array.
+ */
+export declare function toggleNodeSelection(nodes: TreeSelectFieldNode[], currentValue: TreeSelectFieldValue[], nodeId: string | number, selectionMode: "single" | "independent" | "linked", valueConsistsOf: TreeSelectFieldValueConsistsOf): TreeSelectFieldValue[];

package/dist/src/beta/components/TreeSelectField/internal/useTreeKeyboard.d.ts

@@ -0,0 +1,42 @@
+import { KeyboardEvent } from 'react';
+import { VisibleNode } from './types';
+/**
+ * Options for the keyboard event handler.
+ * @property visibleNodes - The current flat list of visible nodes.
+ * @property activeIndex - Index into visibleNodes of the currently focused node, or -1.
+ * @property setActiveIndex - Setter for the active index.
+ * @property isExpanded - Returns whether a node is expanded.
+ * @property toggleExpand - Expands or collapses a branch node.
+ * @property toggleNode - Toggles selection for a node.
+ */
+export type UseTreeKeyboardOptions = {
+    visibleNodes: VisibleNode[];
+    activeIndex: number;
+    setActiveIndex: (index: number) => void;
+    isExpanded: (id: string | number) => boolean;
+    toggleExpand: (id: string | number) => void;
+    toggleNode: (id: string | number) => void;
+};
+/**
+ * Handles keyboard navigation for a tree widget rooted on a combobox input.
+ *
+ * Focus stays on the input at all times; the tree uses aria-activedescendant
+ * to convey the focused node. Returns `true` when the key was handled so the
+ * caller can decide whether to let the event propagate (e.g. ArrowLeft/Right
+ * falling through to cursor movement inside the input).
+ *
+ * - ArrowDown: move to next visible node
+ * - ArrowUp: move to previous visible node
+ * - ArrowRight: expand collapsed branch or move to first child; returns false
+ *   when there is nothing to do so the cursor can move inside the input
+ * - ArrowLeft: collapse expanded branch or move to parent; returns false when
+ *   there is nothing to do so the cursor can move inside the input
+ * - Home: move to first visible node
+ * - End: move to last visible node
+ * - Enter: toggle selection of focused node
+ *
+ * @param e - The keyboard event.
+ * @param options - The current tree state and callbacks.
+ * @returns Whether the key was handled by tree navigation.
+ */
+export declare function handleTreeKeyDown(e: KeyboardEvent, options: UseTreeKeyboardOptions): boolean;

package/dist/src/beta/components/TreeSelectField/internal/useTreeLazyCascade.d.ts

@@ -0,0 +1,56 @@
+import { UseTreeReturn } from './useTree';
+import { UseTreeLoaderReturn } from './useTreeLoader';
+/**
+ * Options for {@link useTreeLazyCascade}.
+ *
+ * @property tree - Tree state from useTree, used to read nodes and run toggles.
+ * @property loader - Tree loader, used to lazy-load unloaded descendants.
+ * @property isSingleSelect - Whether the consumer is in single-select mode; controls auto-close after a successful toggle.
+ * @property branchesSelectable - Whether branch nodes can be selected (vs only expanded).
+ * @property leavesSelectable - Whether leaf nodes can be selected.
+ * @property emptyBranchesSelectable - Whether branches with an empty children array can be selected.
+ * @property readOnly - When true, all toggle attempts no-op.
+ * @property onCloseAfterSingleSelect - Called after a successful single-select toggle so the consumer can close its menu and restore focus.
+ */
+export type UseTreeLazyCascadeOptions = {
+    tree: UseTreeReturn;
+    loader: UseTreeLoaderReturn;
+    isSingleSelect: boolean;
+    branchesSelectable: boolean;
+    leavesSelectable: boolean;
+    emptyBranchesSelectable: boolean;
+    readOnly?: boolean;
+    onCloseAfterSingleSelect?: () => void;
+};
+/**
+ * Return value of {@link useTreeLazyCascade}.
+ *
+ * @property handleToggleNode - Click/Space handler for a tree row that respects selectability and loads any unloaded descendants before cascading.
+ * @property pendingToggleNodeId - The id of the node currently waiting on lazy loads to complete (used to render a loading checkbox), or null.
+ * @property reset - Clears any in-flight pending toggle. Call from the consumer's closeMenu so reopening starts clean.
+ */
+export type UseTreeLazyCascadeReturn = {
+    handleToggleNode: (nodeId: string | number) => void;
+    pendingToggleNodeId: string | number | null;
+    reset: () => void;
+};
+/**
+ * Coordinates "toggle a tree node, but lazy-load any unloaded descendants
+ * first" — the bit of orchestration that sits between useTree and
+ * useTreeLoader and is shared between TreeSelectField and TreeSelectMenu.
+ *
+ * When the consumer clicks a branch whose subtree isn't fully loaded, the
+ * hook records the pending toggle, kicks off loadChildren for every
+ * unloaded descendant, and then — once all loads are complete — fires
+ * tree.toggleNode so cascade selection can run against the now-complete
+ * subtree. While loads are in flight, pendingToggleNodeId points at the
+ * originally-clicked node so the consumer can render a loading state on
+ * its checkbox.
+ *
+ * Non-selectable branches expand instead of toggling; non-selectable
+ * leaves no-op. Read-only consumers can pass readOnly to short-circuit.
+ *
+ * @param options - See {@link UseTreeLazyCascadeOptions}.
+ * @returns Toggle handler, current pending node id, and a reset function.
+ */
+export declare function useTreeLazyCascade(options: UseTreeLazyCascadeOptions): UseTreeLazyCascadeReturn;

package/dist/src/beta/components/TreeSelectField/internal/useTreeLoader.d.ts

@@ -0,0 +1,58 @@
+import { TreeSelectFieldNode } from '../types';
+/**
+ * Options for the useTreeLoader hook.
+ * @property loadOptions - Async function to load tree nodes. Called with searchValue and optional parentNode.
+ * @property cache - Cache configuration. Enabled by default with maxSize of 15.
+ * @property initialLoad - Controls when the initial load occurs. "auto" and "immediate" load on mount, "open" loads on first onOpen() call.
+ * @property debounceMs - Debounce delay in milliseconds for search calls. Defaults to 200.
+ */
+export type UseTreeLoaderOptions = {
+    loadOptions: (searchValue: string, parentNode?: TreeSelectFieldNode) => TreeSelectFieldNode[] | Promise<TreeSelectFieldNode[]>;
+    cache?: {
+        enabled?: boolean;
+        maxSize?: number;
+    };
+    initialLoad?: "auto" | "immediate" | "open";
+    debounceMs?: number;
+};
+/**
+ * Return value from the useTreeLoader hook.
+ * @property nodes - The currently loaded tree nodes.
+ * @property ancestry - Durable childId → parentId map accumulated from lazy
+ *   children loads; survives tree resets so off-screen selections can be
+ *   attributed to their ancestors.
+ * @property isLoading - Whether a root/search load is in progress.
+ * @property isLoadingChildren - Set of node IDs whose children are currently loading.
+ * @property loadChildren - Loads children for the given branch node (lazy expansion).
+ * @property search - Triggers a search load with the given search value (debounced).
+ * @property clearCache - Clears both the search and children caches.
+ * @property invalidate - Clears both caches and triggers a fresh load.
+ * @property onOpen - Triggers the initial load when initialLoad="open". No-op otherwise or after first open.
+ */
+export type UseTreeLoaderReturn = {
+    nodes: TreeSelectFieldNode[];
+    ancestry: Map<string | number, string | number>;
+    isLoading: boolean;
+    isLoadingChildren: Set<string | number>;
+    loadChildren: (parentNode: TreeSelectFieldNode) => Promise<TreeSelectFieldNode[]>;
+    search: (searchValue: string) => void;
+    clearCache: () => void;
+    invalidate: () => void;
+    onOpen: () => void;
+};
+/**
+ * Hook that manages async loading and caching for tree data.
+ *
+ * Features:
+ * - Handles root/search loading and lazy branch expansion via a single loadOptions callback
+ * - Two separate LRU caches: one for search results, one for lazy-loaded children
+ * - Configurable cache size and opt-out support
+ * - Debounced search to reduce unnecessary loadOptions calls
+ * - initialLoad modes: "immediate"/"auto" load on mount, "open" defers until onOpen() is called
+ * - Children are merged into the node tree after loading, updating children: null to the loaded array
+ * - invalidate() clears caches and triggers a fresh load of the current view
+ *
+ * @param options - Configuration options for the tree loader.
+ * @returns Current nodes, loading states, and loader control functions.
+ */
+export declare function useTreeLoader(options: UseTreeLoaderOptions): UseTreeLoaderReturn;

package/dist/src/beta/components/TreeSelectField/stories/TreeSelectField.stories.data.d.ts

@@ -0,0 +1,21 @@
+import { TreeSelectFieldNode } from '../types';
+/**
+ * Realistic multi-level org chart for stories and tests.
+ * 4 levels deep: Company divisions > Departments > Teams > Individuals
+ */
+export declare const orgChart: TreeSelectFieldNode[];
+/**
+ * Async version: root nodes with children: null (lazy-loaded).
+ */
+export declare const asyncOrgChartRoots: TreeSelectFieldNode[];
+/**
+ * Simulates an async loadOptions for stories.
+ * Supports search filtering on roots and lazy child loading.
+ */
+export declare function simulatedLoadOptions(searchValue: string, parentNode?: TreeSelectFieldNode): Promise<TreeSelectFieldNode[]>;
+/**
+ * Simulates multi-level lazy loading. Each expansion returns immediate
+ * children with branches having children: null (requiring another load).
+ * Every level shows a spinner while loading.
+ */
+export declare function multiLevelLoadOptions(searchValue: string, parentNode?: TreeSelectFieldNode): Promise<TreeSelectFieldNode[]>;

package/dist/src/beta/components/TreeSelectField/types.d.ts

@@ -0,0 +1,124 @@
+import { CSSProperties, ReactElement, ReactNode } from 'react';
+import { AiMarkWithTooltipOrPopoverProps, LayoutUtilProps, Size } from '../../../types';
+import { OptionContent } from '../../../internal/types/optionContent';
+/**
+ * Rich content configuration for a TreeSelectField option row.
+ * Controls the avatar, icon, description, and chip display within an option.
+ */
+export type TreeSelectFieldOptionContent = OptionContent;
+/**
+ * A node in the tree structure.
+ * @property id - Unique identifier for the node.
+ * @property label - Display text for the node.
+ * @property searchText - Additional text to match during search, beyond label.
+ * @property disabled - Whether the node is disabled for selection.
+ * @property extra - Pass-through data for consumer convenience.
+ * @property children - Child nodes. undefined=leaf, []=empty branch, [...]=branch, null=unloaded (lazy).
+ * @property childCount - Server-provided count, optionally displayed on branch nodes.
+ * @property path - Optional ancestor ids, root→parent. Selection-ancestry
+ *   metadata, primarily meaningful on value objects: when a selected node lives
+ *   under branches that aren't currently loaded, `path` lets the field show the
+ *   correct ancestor check states without a parent-of lookup. The field emits
+ *   it on selections whose ancestry it knows, and reads it from incoming value
+ *   so a persisted-then-restored selection resolves exactly. Not a structural
+ *   tree attribute — omit it on `loadOptions` results.
+ */
+export type TreeSelectFieldNode = {
+    id: string | number;
+    label: string;
+    searchText?: string;
+    disabled?: boolean;
+    extra?: Record<string, unknown>;
+    content?: TreeSelectFieldOptionContent;
+    children?: TreeSelectFieldNode[] | null;
+    childCount?: number;
+    path?: (string | number)[];
+};
+/**
+ * The value shape stored in the value array. Intentionally slim — just enough to render chips and identify the node.
+ * @property id - The node's unique identifier.
+ * @property label - The node's display text.
+ * @property extra - Pass-through data from the node.
+ * @property path - Optional ancestor ids, root→parent. See {@link TreeSelectFieldNode.path}.
+ */
+export type TreeSelectFieldValue = Pick<TreeSelectFieldNode, "id" | "label" | "extra" | "path">;
+/**
+ * Controls which nodes are selectable and how the value array is shaped.
+ * - "ALL" — any node selectable, all checked nodes in value
+ * - "BRANCH_PRIORITY" — any node selectable, branches replace leaves when fully checked
+ * - "BRANCH_ONLY" — only branches selectable, leaves visible but inert
+ * - "LEAF_PRIORITY" — only leaves selectable (branches expand), leaves + childless branches in value
+ * - "LEAF_ONLY" — only leaves selectable (branches expand), strictly leaves in value
+ */
+export type TreeSelectFieldValueConsistsOf = "ALL" | "BRANCH_PRIORITY" | "BRANCH_ONLY" | "LEAF_PRIORITY" | "LEAF_ONLY";
+/**
+ * Imperative handle for the TreeSelectField component.
+ * @property clearCache - Clears the options cache.
+ * @property invalidate - Clears the cache and triggers a fresh options load.
+ * @property expandAll - Expands all tree nodes.
+ * @property collapseAll - Collapses all tree nodes.
+ */
+export type TreeSelectFieldHandle = {
+    clearCache: () => void;
+    invalidate: () => void;
+    expandAll: () => void;
+    collapseAll: () => void;
+};
+/**
+ * Props for the TreeSelectField component.
+ * @property label - Required label for accessibility.
+ * @property value - Controlled value array. Always an array, even in single-select mode.
+ * @property onSelectedOptionsChange - Callback when selection changes.
+ * @property loadOptions - Async function to load tree nodes. Called with parentNode for lazy branch loading.
+ * @property selectionMode - "single": one node at a time. "independent": no cascade. "linked" (default): parent-child cascade.
+ * @property valueConsistsOf - Controls which nodes are selectable and how the value is shaped.
+ * @property defaultExpandLevel - Initial expand depth. 0=collapsed, Infinity=all.
+ * @extends LayoutUtilProps
+ */
+export type TreeSelectFieldProps = {
+    id?: string;
+    label: string;
+    labelNode?: ReactNode;
+    hideLabel?: boolean;
+    placeholder?: string;
+    size?: Extract<Size, "small" | "medium" | "large">;
+    displayMenuAs?: "auto" | "popover" | "dialog";
+    error?: boolean | string | string[] | ReactElement;
+    hint?: ReactElement | string;
+    /** Additional information to display in a tooltip next to the label. */
+    moreInfo?: ReactNode;
+    /**
+     * AI mark configuration to display next to the label.
+     * Can be a boolean to show a simple AI mark, or an object with tooltip/popover configuration.
+     */
+    labelAiMark?: AiMarkWithTooltipOrPopoverProps["aiMark"];
+    description?: ReactElement | string;
+    warning?: string | string[];
+    required?: boolean;
+    disabled?: boolean;
+    readOnly?: boolean;
+    prefix?: string | ReactElement;
+    suffix?: string | ReactElement;
+    className?: string;
+    style?: CSSProperties;
+    disableSearch?: boolean;
+    debounceMs?: number;
+    searchValue?: string;
+    onSearchChange?: (v: string) => void;
+    singleRow?: boolean;
+    maxChips?: number;
+    virtualize?: boolean;
+    value: TreeSelectFieldValue[];
+    onSelectedOptionsChange: (nodes: TreeSelectFieldValue[]) => void;
+    selectionMode?: "single" | "independent" | "linked";
+    valueConsistsOf?: TreeSelectFieldValueConsistsOf;
+    defaultExpandLevel?: number;
+    expandedIds?: Set<string | number>;
+    onExpandedIdsChange?: (ids: Set<string | number>) => void;
+    loadOptions: (searchValue: string, parentNode?: TreeSelectFieldNode) => TreeSelectFieldNode[] | Promise<TreeSelectFieldNode[]>;
+    cache?: {
+        enabled?: boolean;
+        maxSize?: number;
+    };
+    initialLoad?: "auto" | "immediate" | "open";
+} & LayoutUtilProps;

package/dist/src/beta/components/TreeSelectMenu/TreeSelectMenu.d.ts

@@ -0,0 +1,29 @@
+import { TreeSelectMenuProps } from './types';
+/**
+ * TreeSelectMenu component for selecting tree nodes from a dropdown triggered by any element.
+ *
+ * Features:
+ * - Attaches to any trigger element via a render prop
+ * - Async tree data loading via loadOptions callback with optional LRU caching
+ * - Single-select and multi-select modes with linked/independent cascade
+ * - Cascading parent/child selection in linked mode
+ * - Search filtering across visible nodes
+ * - Lazy branch expansion with on-demand children loading
+ * - Virtualized rendering for large trees via the virtualize prop
+ * - Full keyboard navigation (ArrowDown/Up, ArrowRight/Left, Enter, Home/End, Escape)
+ * - Supports both popover and dialog display modes
+ * - Adaptive display based on device (mobile uses dialog)
+ * - Configurable popover width
+ * - Imperative handle for clearCache, invalidate, expandAll, collapseAll
+ * - Full accessibility support with ARIA tree attributes
+ *
+ * @example
+ * <TreeSelectMenu
+ *   trigger={(props) => <Button {...props}>Select Categories</Button>}
+ *   label="Categories"
+ *   value={selected}
+ *   onSelectedOptionsChange={setSelected}
+ *   loadOptions={async (search) => fetchCategories(search)}
+ * />
+ */
+export declare const TreeSelectMenu: import('react').ForwardRefExoticComponent<TreeSelectMenuProps & import('react').RefAttributes<import('..').TreeSelectFieldHandle>>;