@voxel51/voodo 0.0.29 → 0.0.31

package/dist/util/useTree.d.ts

@@ -0,0 +1,126 @@
+import { KeyboardEvent } from 'react';
+import { ResolvedNode } from '../components/TreeSelect/types';
+export interface UseTreeOptions {
+    /** Pre-resolved (and optionally pre-filtered) tree. */
+    tree: ResolvedNode;
+    /**
+     * Set of currently selected paths, used for `aria-selected` and `isSelected`.
+     * For single-select, pass a Set with one element. For multi-select, pass
+     * all selected paths. The hook is mode-agnostic.
+     */
+    selection?: Set<string>;
+    /**
+     * Paths that must be treated as expanded regardless of user expansion state
+     * (e.g. ancestors of a search match).
+     */
+    forceOpenPaths?: Set<string>;
+    /** Optional id prefix override; defaults to a `useId()` value. */
+    idPrefix?: string;
+    /** Scroll the active row into view on change. @default true */
+    scrollActiveIntoView?: boolean;
+    /** Fires on selectable row click and Enter on active selectable row. */
+    onSelect?: (path: string) => void;
+    /** Fires on Escape key. */
+    onEscape?: () => void;
+    /**
+     * Fires when a branch is newly opened by user interaction
+     * (`toggleExpand`, `expand`, or ArrowRight). Does **not** fire for paths
+     * opened solely via `forceOpenPaths` (search auto-expand), and fires at
+     * most once per path transition from closed → open.
+     */
+    onExpand?: (path: string) => void;
+    /**
+     * Async load state for lazy branches. Exposed via `getLoadState` so
+     * renderers can show spinners / error icons without direct access to the
+     * map.
+     */
+    loadState?: Map<string, "loading" | "error">;
+    /**
+     * Branches to expand initially. User can still collapse them.
+     * `resetExpansion()` restores this set rather than clearing to empty.
+     *
+     * - `Set<string>` — explicit branch paths.
+     * - `true` — expand every branch in `tree`.
+     * - `false` / `undefined` — expand nothing.
+     */
+    defaultExpanded?: Set<string> | boolean;
+}
+export interface TreeItemProps {
+    id: string;
+    role: "treeitem";
+    "aria-selected": boolean | undefined;
+    "aria-expanded": boolean | undefined;
+    "aria-posinset": number;
+    "aria-setsize": number;
+    tabIndex: -1;
+    "data-active": true | undefined;
+    onClick: () => void;
+    onMouseDown: (e: {
+        preventDefault: () => void;
+    }) => void;
+    onMouseEnter: () => void;
+}
+export interface TreeChevronProps {
+    "aria-expanded": boolean;
+    "aria-label": string;
+    onClick: (e: {
+        stopPropagation: () => void;
+        preventDefault: () => void;
+    }) => void;
+    onPointerDown: (e: {
+        stopPropagation: () => void;
+        preventDefault: () => void;
+    }) => void;
+    onPointerUp: (e: {
+        stopPropagation: () => void;
+        preventDefault: () => void;
+    }) => void;
+}
+export interface UseTreeReturn {
+    /** Flat list of visible nodes in DOM render order. */
+    visibleNodes: ResolvedNode[];
+    /** Set of explicitly expanded paths (excludes forceOpenPaths). */
+    expandedPaths: Set<string>;
+    /** Path of the keyboard-active row, or `null`. */
+    activePath: string | null;
+    /** DOM id of the active row, for `aria-activedescendant`. */
+    activeDescendantId: string | undefined;
+    /** Toggle a branch open/closed. */
+    toggleExpand: (path: string) => void;
+    /** Expand a branch (no-op if already open). */
+    expand: (path: string) => void;
+    /** Collapse a branch (no-op if already closed). */
+    collapse: (path: string) => void;
+    /** Clear all user-expanded paths. */
+    resetExpansion: () => void;
+    /** Set the active (keyboard-highlighted) path. */
+    setActivePath: (path: string | null) => void;
+    /** Spread onto the outer `<div role="treeitem">` wrapper. */
+    getItemProps: (node: ResolvedNode) => TreeItemProps;
+    /** Spread onto the chevron `<button>`. */
+    getChevronProps: (node: ResolvedNode) => TreeChevronProps;
+    /** `onKeyDown` handler for the element that holds virtual focus (e.g. search input). */
+    handleKeyDown: (e: KeyboardEvent) => void;
+    /** Get the DOM id for a given path. */
+    rowId: (path: string) => string;
+    /** Whether a path is effectively open (expanded or force-open). */
+    isOpen: (path: string) => boolean;
+    /** Whether a path is the keyboard-active row. */
+    isActive: (path: string) => boolean;
+    /** Whether a node is the selected value. */
+    isSelected: (node: ResolvedNode) => boolean;
+    /** Whether any descendant of a node is in the current selection. */
+    hasSelectedDescendant: (node: ResolvedNode) => boolean;
+    /** Async load state for a path: `"loading"`, `"error"`, or `undefined`. */
+    getLoadState: (path: string) => "loading" | "error" | undefined;
+}
+/**
+ * Headless hook that manages tree state: expansion, active (keyboard) path,
+ * keyboard navigation per WAI-ARIA treeview semantics, ARIA prop generation,
+ * and scroll-into-view. Owns no rendering or styling.
+ *
+ * Designed to be consumed by `TreeSelect` and `TreeSelectNode` but generic
+ * enough for any component that renders a tree of `ResolvedNode`s.
+ */
+export declare function useTree(options: UseTreeOptions): UseTreeReturn;
+//# sourceMappingURL=useTree.d.ts.map

package/dist/util/useTree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useTree.d.ts","sourceRoot":"","sources":["../../src/util/useTree.ts"],"names":[],"mappings":"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"}