@servicetitan/anvil2 3.0.7 → 3.0.8

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

@@ -0,0 +1,31 @@
+import { TreePanelProps } from './TreePanel';
+/**
+ * Props for the TreeContent component.
+ *
+ * @property loading - Whether the tree is currently loading data; renders a spinner while true.
+ * @property hasNoVisibleNodes - True when there are no nodes to render (e.g. a search returned no matches); renders an empty-state message.
+ * @property virtualize - When true, renders the virtualized panel; otherwise renders the standard panel.
+ * @property panelProps - Props forwarded to the underlying TreePanel or VirtualizedTreePanel.
+ */
+export type TreeContentProps = {
+    loading: boolean;
+    hasNoVisibleNodes: boolean;
+    virtualize?: boolean;
+    panelProps: TreePanelProps;
+};
+/**
+ * Renders the body of a tree select popover or dialog: a centered spinner
+ * while loading, a "No match found" message when there are no visible
+ * nodes, or the (optionally virtualized) tree panel.
+ *
+ * Used by both TreeSelectField and TreeSelectMenu to keep the three
+ * states consistent across the field's dialog and popover branches and
+ * the menu's render path.
+ *
+ * Features:
+ * - Centered medium Spinner while loading
+ * - "No match found" empty state (small, subdued text)
+ * - Switches between TreePanel and VirtualizedTreePanel via the `virtualize` flag
+ * - Forwards a ref to the underlying tree panel for focus management
+ */
+export declare const TreeContent: import('react').ForwardRefExoticComponent<TreeContentProps & import('react').RefAttributes<HTMLDivElement>>;

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

@@ -0,0 +1,56 @@
+import { TreeSelectFieldNode } from '../types';
+import { VisibleNode } from './types';
+/**
+ * Props for the TreePanel component.
+ * @property {VisibleNode[]} visibleNodes - Flat list of nodes currently visible in the tree.
+ * @property {(id: string | number) => "checked" | "unchecked" | "indeterminate" | "loading"} getCheckState - Returns the check state for a given node id.
+ * @property {(id: string | number) => void} toggleNode - Toggles the selection state of a node.
+ * @property {(id: string | number) => void} toggleExpand - Toggles the expanded state of a branch node.
+ * @property {(id: string | number) => Record<string, unknown>} getTreeItemProps - Returns ARIA/accessibility props for a tree item.
+ * @property {Record<string, unknown>} treeProps - Props to spread onto the tree container element.
+ * @property {string | undefined} activeDescendantId - The id of the currently active/focused tree item.
+ * @property {boolean} [branchesSelectable] - When true, branch nodes can be selected.
+ * @property {boolean} [leavesSelectable] - When true, leaf nodes can be selected.
+ * @property {boolean} [emptyBranchesSelectable] - When true, empty branches can be selected.
+ * @property {(node: TreeSelectFieldNode) => void} [onLoadChildren] - Callback to trigger lazy loading of children.
+ */
+export type TreePanelProps = {
+    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;
+};
+/**
+ * TreePanel component that renders the tree dropdown content.
+ *
+ * Features:
+ * - Renders a flat list of visible nodes with depth-based indentation
+ * - Supports expand/collapse controls for branch nodes
+ * - Shows loading indicator for lazily-loaded branches
+ * - Checkboxes for multi-select mode (hidden in single-select mode)
+ * - Optional breadcrumb display for flattened search results
+ * - Optional child count display for branch nodes
+ * - Full accessibility support with ARIA tree/treeitem roles
+ * - Focusable container via forwardRef
+ *
+ * @example
+ * <TreePanel
+ *   visibleNodes={visibleNodes}
+ *   getCheckState={getCheckState}
+ *   toggleNode={toggleNode}
+ *   toggleExpand={toggleExpand}
+ *   getTreeItemProps={getTreeItemProps}
+ *   treeProps={treeProps}
+ *   activeDescendantId={activeDescendantId}
+ * />
+ */
+export declare const TreePanel: import('react').ForwardRefExoticComponent<TreePanelProps & import('react').RefAttributes<HTMLDivElement>>;

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

@@ -0,0 +1,56 @@
+import { TreeSelectFieldNode } from '../types';
+import { VisibleNode } from './types';
+/**
+ * Props for the TreeRow component.
+ * @property {VisibleNode} visible - The visible node data including depth, expand state, and branch info.
+ * @property {"checked" | "unchecked" | "indeterminate"} checkState - The checkbox state for this row.
+ * @property {Record<string, unknown>} itemProps - ARIA/accessibility props from getTreeItemProps.
+ * @property {boolean} [branchesSelectable] - When true, branch nodes can be selected. Defaults to true.
+ * @property {boolean} [leavesSelectable] - When true, leaf nodes can be selected. Defaults to true.
+ * @property {boolean} [emptyBranchesSelectable] - When true, empty branches (children: []) can be selected. Defaults to true.
+ * @property {boolean} [isActive] - When true, applies a highlight background for keyboard focus.
+ * @property {(id: string | number) => void} onToggleNode - Callback to toggle selection of the node.
+ * @property {(id: string | number) => void} onToggleExpand - Callback to toggle expansion of a branch node.
+ * @property {(node: TreeSelectFieldNode) => void} [onLoadChildren] - Callback to trigger lazy loading of children.
+ * @property {number} depth - Depth of the node in the tree, used to calculate indentation.
+ */
+export type TreeRowProps = {
+    visible: VisibleNode;
+    checkState: "checked" | "unchecked" | "indeterminate" | "loading";
+    itemProps: Record<string, unknown>;
+    branchesSelectable?: boolean;
+    leavesSelectable?: boolean;
+    emptyBranchesSelectable?: boolean;
+    readOnly?: boolean;
+    isActive?: boolean;
+    onToggleNode: (id: string | number) => void;
+    onToggleExpand: (id: string | number) => void;
+    onHover?: (id: string | number) => void;
+    onLoadChildren?: (node: TreeSelectFieldNode) => void;
+    depth: number;
+};
+/**
+ * TreeRow renders a single row in the tree dropdown.
+ *
+ * Features:
+ * - Depth-based indentation via inline paddingInlineStart
+ * - Expand/collapse icon using Icon component with keyboard_arrow_right/down icons
+ * - Spinning icon animation for lazy-loading branch nodes
+ * - Checkbox in multi-select mode, hidden in single-select mode
+ * - Rich content support via node.content (title, description, chips, avatar, icon)
+ * - Label text with overflow ellipsis
+ * - Disabled state with reduced opacity and default cursor
+ * - Active (keyboard focus) state with highlight background
+ * - Full ARIA semantics via spread itemProps
+ *
+ * @example
+ * <TreeRow
+ *   visible={visibleNode}
+ *   checkState={getCheckState(visibleNode.node.id)}
+ *   itemProps={getTreeItemProps(visibleNode.node.id)}
+ *   onToggleNode={toggleNode}
+ *   onToggleExpand={toggleExpand}
+ *   depth={visibleNode.depth}
+ * />
+ */
+export declare function TreeRow({ visible, checkState, itemProps, branchesSelectable, leavesSelectable, emptyBranchesSelectable, readOnly, isActive, onToggleNode, onToggleExpand, onHover, onLoadChildren, depth, }: TreeRowProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,82 @@
+import { ReactElement, RefObject } from 'react';
+import { TreeSelectFieldValue } from '../types';
+/**
+ * Props for the TreeSelectFieldInput component.
+ * @property {string} [id] - HTML id attribute for the input element
+ * @property {string} [placeholder] - Placeholder text displayed when no options are selected
+ * @property {"small" | "medium" | "large"} [size] - Size variant of the input
+ * @property {boolean} [disabled] - Disables the input entirely
+ * @property {boolean} [readOnly] - Cannot be modified but remains interactive
+ * @property {boolean} [error] - Shows error styling on the input when true
+ * @property {boolean} [single] - When true, renders single-select text display instead of chips
+ * @property {boolean} [singleRow] - When true, restricts chip display to a single row
+ * @property {number} [maxChips] - Maximum number of chips to display before showing +N indicator
+ * @property {string | ReactElement} [prefix] - Content to display before the input area
+ * @property {string | ReactElement} [suffix] - Content to display after the input area
+ * @property {TreeSelectFieldValue[]} selectedOptions - Array of currently selected options
+ * @property {(option: TreeSelectFieldValue) => void} onRemoveOption - Callback fired when a chip is removed
+ * @property {RefObject<HTMLInputElement>} [inputRef] - Ref for the input element
+ * @property {RefObject<HTMLDivElement>} [inputWrapperRef] - Ref for the input wrapper div element
+ * @property {string} [searchValue] - Current search input value
+ * @property {(e: React.ChangeEvent<HTMLInputElement>) => void} [onSearchChange] - Callback fired when search input changes
+ * @property {(e: React.KeyboardEvent) => void} [onInputKeyDown] - Callback fired on key down in the search input
+ * @property {() => void} [onWrapperClick] - Callback fired when the input wrapper is clicked
+ * @property {boolean} [isOpen] - Whether the dropdown is currently open
+ * @property {boolean} [disableSearch] - When true, hides the search input
+ * @property {Record<string, unknown>} [comboboxProps] - Additional ARIA props for the combobox input role
+ */
+export type TreeSelectFieldInputProps = {
+    id?: string;
+    placeholder?: string;
+    size?: "small" | "medium" | "large";
+    disabled?: boolean;
+    readOnly?: boolean;
+    error?: boolean;
+    single?: boolean;
+    singleRow?: boolean;
+    maxChips?: number;
+    prefix?: string | ReactElement;
+    suffix?: string | ReactElement;
+    selectedOptions: TreeSelectFieldValue[];
+    onRemoveOption: (option: TreeSelectFieldValue) => void;
+    inputRef?: RefObject<HTMLInputElement>;
+    inputWrapperRef?: RefObject<HTMLDivElement>;
+    searchValue?: string;
+    onSearchChange?: (e: React.ChangeEvent<HTMLInputElement>) => void;
+    onInputKeyDown?: (e: React.KeyboardEvent) => void;
+    onWrapperClick?: () => void;
+    isOpen?: boolean;
+    ariaControls?: string;
+    disableSearch?: boolean;
+    comboboxProps?: Record<string, unknown>;
+};
+/**
+ * Internal input component for the TreeSelectField that renders the trigger area
+ * with chips, search input, single-select text, and the toggle button.
+ *
+ * Features:
+ * - Chip display for selected options in multi-select mode with remove functionality
+ * - Single-row chip overflow detection with +N hidden chip indicator
+ * - Text input for filtering tree options when search is enabled
+ * - Plain text display for single-select mode
+ * - Chevron toggle button to open/close the dropdown
+ * - Optional prefix and suffix content slots
+ * - Supports small, medium, and large size variants
+ * - Error state styling
+ * - Disabled and read-only state styling
+ * - Accessible combobox role with aria-expanded and aria-haspopup
+ *
+ * @example
+ * <TreeSelectFieldInput
+ *   placeholder="Select categories..."
+ *   size="medium"
+ *   selectedOptions={[{ id: 1, label: "Category A" }]}
+ *   onRemoveOption={(option) => handleRemove(option)}
+ *   isOpen={isOpen}
+ *   onWrapperClick={() => setIsOpen(true)}
+ * />
+ */
+export declare const TreeSelectFieldInput: {
+    ({ id, placeholder, size, disabled, readOnly, error, single, singleRow, maxChips, prefix, suffix, selectedOptions, onRemoveOption, inputRef, inputWrapperRef, searchValue, onSearchChange, onInputKeyDown, onWrapperClick, isOpen, ariaControls, disableSearch, comboboxProps, }: TreeSelectFieldInputProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};

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;