@servicetitan/anvil2 3.15.0 → 3.15.1

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

@@ -1,32 +1,6 @@
 import { ReactElement, RefObject } from 'react';
 import { TreeSelectFieldValue } from '../types';
 import { MultiSelectFieldChipProps } from '../../../../components/MultiSelectField/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 {(value: TreeSelectFieldValue) => MultiSelectFieldChipProps} [getChipProps] - Callback to customize chip props per selected option
- * @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;
@@ -54,30 +28,8 @@ export type TreeSelectFieldInputProps = {
     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)}
- * />
+ * Renders the field trigger and toggle button. Multi-select search uses an
+ * editable combobox; single-select or disabled search uses a read-only one.
  */
 export declare const TreeSelectFieldInput: {
     ({ id, placeholder, size, disabled, readOnly, error, single, singleRow, maxChips, prefix, suffix, selectedOptions, onRemoveOption, getChipProps, inputRef, inputWrapperRef, searchValue, onSearchChange, onInputKeyDown, onWrapperClick, isOpen, ariaControls, disableSearch, comboboxProps, }: TreeSelectFieldInputProps): import("react/jsx-runtime").JSX.Element;

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

@@ -1,18 +1,6 @@
 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.
- */
+/** Tree-panel props consumed by the windowed renderer. */
 export type VirtualizedTreePanelProps = {
     visibleNodes: VisibleNode[];
     getCheckState: (id: string | number) => "checked" | "unchecked" | "indeterminate" | "loading";
@@ -28,30 +16,5 @@ export type VirtualizedTreePanelProps = {
     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}
- * />
- */
+/** Windowed tree panel that mounts only the rows near the viewport. */
 export declare const VirtualizedTreePanel: import('react').ForwardRefExoticComponent<VirtualizedTreePanelProps & import('react').RefAttributes<HTMLDivElement>>;

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

@@ -1,33 +1,18 @@
 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.
+ * Maps the complete static tree and search text to the tree passed to the field.
  */
 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.
+ * Adds missing immediate-child counts before filtering so a partial result
+ * cannot make a branch appear fully selected.
  */
 export declare function applyChildCounts(nodes: TreeSelectFieldNode[]): TreeSelectFieldNode[];
-/**
- * Default tree-aware filter. Matches on label and searchText, preserving
- * ancestors of matched nodes.
- */
+/** Matches `label` and `searchText` while preserving ancestors of matches. */
 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.
+ * Normalizes a custom filter or match-sorter options to {@link TreeSyncFilterFn}.
+ * Option-object filters preserve ancestors; custom functions own their result.
  */
 export declare function toTreeSyncFilterFn(filter: TreeSyncFilterFn | MatchSorterOptions<TreeSelectFieldNode>): TreeSyncFilterFn;

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

@@ -1,25 +1,9 @@
 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.
- */
+/** Finds the first node whose id strictly equals `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.
- */
+/** Whether this node or any descendant has `children: null`. */
 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.
+ * Collects descendant branches with `children: null`, excluding `node` itself.
  */
 export declare function findUnloadedDescendants(node: TreeSelectFieldNode): TreeSelectFieldNode[];

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

@@ -2,37 +2,23 @@ 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;
+    /** Selection and parent-child cascade policy. Defaults to `"linked"`. */
     selectionMode?: "single" | "independent" | "linked";
     valueConsistsOf?: TreeSelectFieldValueConsistsOf;
+    /** Initial uncontrolled expansion depth. Defaults to `0`. */
     defaultExpandLevel?: number;
     expandedIds?: Set<string | number>;
     onExpandedIdsChange?: (ids: Set<string | number>) => void;
     searchValue?: string;
+    /** Lazy-load child-to-parent relationships retained across tree replacements. */
     ancestry?: Map<string | number, string | number>;
     loadingChildrenIds?: Set<string | number>;
 };
-/**
- * ARIA props returned per tree item.
- */
+/** ARIA attributes generated for one visible tree item. */
 export type TreeItemProps = {
     id: string;
     role: "treeitem";
@@ -42,30 +28,15 @@ export type TreeItemProps = {
     "aria-expanded"?: boolean;
     "aria-selected": boolean;
 };
-/**
- * ARIA props for the tree container.
- */
+/** ARIA attributes generated 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[];
+    /** Depth-first rows after expansion and search filtering. */
     visibleNodes: VisibleNode[];
     getCheckState: (id: string | number) => CheckState;
     toggleNode: (id: string | number) => void;
@@ -73,6 +44,7 @@ export type UseTreeReturn = {
     toggleExpand: (id: string | number) => void;
     expandAll: () => void;
     collapseAll: () => void;
+    /** DOM id of the keyboard-active tree item. */
     activeDescendantId: string | undefined;
     setActiveNodeId: (id: string | number) => void;
     onKeyDown: (e: KeyboardEvent) => void;
@@ -80,20 +52,7 @@ export type UseTreeReturn = {
     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.
+ * Manages expansion, selection, search visibility, keyboard navigation, and
+ * ARIA state for a tree widget.
  */
 export declare function useTree(options: UseTreeOptions): UseTreeReturn;

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

@@ -4,90 +4,19 @@ 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.
+ * Linked branches aggregate their non-disabled children. Lazy or filtered
+ * branches cannot prove a fully checked state from incomplete children, so
+ * they use their own selection and known orphan-ancestor paths. Accurate
+ * partial filtering requires `childCount`.
  */
 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.
+ * Converts checked ids to controlled values according to the node-retention
+ * strategy, including ancestry paths for restored lazy selections.
  */
 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.
+ * Toggles one node under the single, independent, or linked selection policy.
+ * Linked toggles cascade through non-disabled descendants.
  */
 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

@@ -1,14 +1,5 @@
 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;
@@ -18,25 +9,8 @@ export type UseTreeKeyboardOptions = {
     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.
+ * Applies the WAI-ARIA tree keyboard pattern through `aria-activedescendant`.
+ * Returns `false` when the input should retain an unhandled key, including
+ * ArrowLeft or ArrowRight with no available tree action.
  */
 export declare function handleTreeKeyDown(e: KeyboardEvent, options: UseTreeKeyboardOptions): boolean;

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

@@ -1,56 +1,28 @@
 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;
+    /** Calls `onCloseAfterSingleSelect` after a successful toggle when `true`. */
     isSingleSelect: boolean;
     branchesSelectable: boolean;
     leavesSelectable: boolean;
     emptyBranchesSelectable: boolean;
+    /** Makes every selection attempt a no-op. */
     readOnly?: boolean;
+    /** Runs after a successful single selection, including after lazy loading. */
     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 = {
+    /** Applies selectability and loads incomplete subtrees before toggling. */
     handleToggleNode: (nodeId: string | number) => void;
+    /** Original node awaiting lazy descendants, or `null`. */
     pendingToggleNodeId: string | number | null;
+    /** Abandons an in-flight toggle without cancelling its network requests. */
     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.
+ * Defers a cascading toggle until every lazy descendant is loaded.
+ * Non-selectable branches expand; non-selectable leaves do nothing.
  */
 export declare function useTreeLazyCascade(options: UseTreeLazyCascadeOptions): UseTreeLazyCascadeReturn;

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

@@ -1,58 +1,34 @@
 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 = {
+    /** Loads roots/search results, or children when `parentNode` is supplied. */
     loadOptions: (searchValue: string, parentNode?: TreeSelectFieldNode) => TreeSelectFieldNode[] | Promise<TreeSelectFieldNode[]>;
+    /** Configures both LRUs; each is enabled with at most 15 entries by default. */
     cache?: {
         enabled?: boolean;
         maxSize?: number;
     };
+    /** `"auto"` and `"immediate"` load on mount; `"open"` waits for first open. */
     initialLoad?: "auto" | "immediate" | "open";
+    /** Search delay in milliseconds. Defaults to `200`. */
     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[];
+    /** Lazy-load ancestry retained across root/search replacements. */
     ancestry: Map<string | number, string | number>;
     isLoading: boolean;
     isLoadingChildren: Set<string | number>;
     loadChildren: (parentNode: TreeSelectFieldNode) => Promise<TreeSelectFieldNode[]>;
+    /** Schedules a root/search load; `debounceMs={0}` runs immediately. */
     search: (searchValue: string) => void;
     clearCache: () => void;
+    /** Clears both caches and reloads the current search without repopulating cache. */
     invalidate: () => void;
+    /** Starts the deferred initial load, at most once. */
     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.
+ * Loads and caches tree roots, search results, and lazy children.
+ * Separate LRUs prevent search entries from evicting branch children.
  */
 export declare function useTreeLoader(options: UseTreeLoaderOptions): UseTreeLoaderReturn;

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

@@ -1,15 +1,9 @@
 /**
  * `data-anv-part` names for TreeSelectField's interactive sub-elements.
  *
- * Scope a query by the consumer's `data-cy` on the field root
- * (`[data-cy="x"] [data-anv-part="input"]`). Portaled tree parts
- * (`menu`, `option`, `popover`, `dialog`) render in the top layer — target
- * them by part attribute or the field's `#{id}-popover` / `#{id}-dialog`.
- * Repeated options also carry `data-id={node.id}`.
- *
- * Tree rows are not SelectOption — `option` / `menu` / `expand-toggle` are
- * stamped on TreePanel / TreeRow. Shared OptionsPopover / OptionsDialog
- * already provide `popover` / `dialog`.
+ * Tree panels and rows own the tree-specific parts; shared option shells own
+ * popover and dialog parts. Portaled parts cannot be scoped through the field
+ * root, and repeated options also expose their node id through `data-id`.
  */
 export declare const PARTS: {
     readonly input: "input";