@primitiv-ui/react 0.1.37 → 0.1.39

package/dist/Tree/hooks/useTreePath.d.ts

@@ -0,0 +1,88 @@
+import type { TreePathSegment } from "../types.js";
+/**
+ * Returns the root-to-leaf ancestor chain of a tree value as an array
+ * of {@link TreePathSegment}s, or an empty array if the value has
+ * never been registered in the tree.
+ *
+ * Must be called from a component rendered inside `Tree.Root`.
+ *
+ * The segments are ordered **root → leaf** so the last entry is the
+ * queried value itself. Each segment exposes its `label` (the `label`
+ * prop passed to `Tree.Item` / `Tree.Branch`, or `null` when omitted),
+ * `isBranch`, `disabled` and `depth` — enough to render breadcrumbs,
+ * outline trails, or location indicators without a parallel data
+ * lookup.
+ *
+ * Paths survive a branch collapsing without `forceMount`: the tree
+ * keeps a durable copy of every node's metadata so ancestry remains
+ * resolvable even after descendants unmount. A value never mounted
+ * (e.g. a pre-selected item whose branch has not yet opened) returns
+ * an empty array.
+ *
+ * @example
+ * ```tsx
+ * function CurrentPath({ value }: { value: string }) {
+ *   const path = useTreePath(value);
+ *   return <>{path.map((s) => s.label ?? s.value).join(" / ")}</>;
+ * }
+ * ```
+ */
+export declare function useTreePath(value: string): TreePathSegment[];
+/**
+ * Returns one path per currently-selected value, in selection order.
+ * In single-selection mode the array has zero or one entry; in
+ * multiple-selection mode it has one entry per selected value.
+ *
+ * Each inner array is the same shape as the return of
+ * {@link useTreePath} — root → leaf segments with labels carried from
+ * the `label` prop.
+ *
+ * Used by `Tree.SelectionPath` for its default rendering, and
+ * available directly for fully-custom breadcrumb UIs.
+ *
+ * @example
+ * ```tsx
+ * function Crumbs() {
+ *   const paths = useTreeSelectionPaths();
+ *   if (paths.length === 0) return <span>Nothing selected</span>;
+ *   return (
+ *     <ul>
+ *       {paths.map((path, i) => (
+ *         <li key={i}>{path.map((s) => s.label ?? s.value).join(" / ")}</li>
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ */
+export declare function useTreeSelectionPaths(): TreePathSegment[][];
+/**
+ * Read the current nesting depth inside a `Tree` — `0` for a node directly
+ * under {@link TreeRoot | `Tree.Root`}, one deeper per enclosing
+ * {@link TreeBranchContent | `Tree.BranchContent`}.
+ *
+ * A styling layer needs the depth as a *number* to compute a row's indent, and
+ * so to make the row span the tree's full width (a hover or selected band that
+ * runs edge to edge, as VS Code and most file trees do). Reading it back off
+ * the `data-depth` attribute in CSS requires `attr(data-depth type(<integer>))`,
+ * which Firefox does not support — hence this hook.
+ *
+ * @throws If called outside a `Tree.Root`.
+ *
+ * @example Indenting a row so its background still spans the full width
+ * ```tsx
+ * function StyledItem(props: TreeItemProps) {
+ *   const { depth } = useTreeLevel();
+ *   return (
+ *     <Tree.Item
+ *       {...props}
+ *       style={{ "--depth": depth } as CSSProperties}
+ *       className="row"
+ *     />
+ *   );
+ * }
+ * ```
+ */
+export declare function useTreeLevel(): {
+    depth: number;
+};

package/dist/Tree/hooks/useTreePath.js

@@ -0,0 +1,96 @@
+"use client";
+import { useTreeContext, useTreeLevelContext } from "../TreeContext.js";
+/**
+ * Returns the root-to-leaf ancestor chain of a tree value as an array
+ * of {@link TreePathSegment}s, or an empty array if the value has
+ * never been registered in the tree.
+ *
+ * Must be called from a component rendered inside `Tree.Root`.
+ *
+ * The segments are ordered **root → leaf** so the last entry is the
+ * queried value itself. Each segment exposes its `label` (the `label`
+ * prop passed to `Tree.Item` / `Tree.Branch`, or `null` when omitted),
+ * `isBranch`, `disabled` and `depth` — enough to render breadcrumbs,
+ * outline trails, or location indicators without a parallel data
+ * lookup.
+ *
+ * Paths survive a branch collapsing without `forceMount`: the tree
+ * keeps a durable copy of every node's metadata so ancestry remains
+ * resolvable even after descendants unmount. A value never mounted
+ * (e.g. a pre-selected item whose branch has not yet opened) returns
+ * an empty array.
+ *
+ * @example
+ * ```tsx
+ * function CurrentPath({ value }: { value: string }) {
+ *   const path = useTreePath(value);
+ *   return <>{path.map((s) => s.label ?? s.value).join(" / ")}</>;
+ * }
+ * ```
+ */
+export function useTreePath(value) {
+    const { getPath } = useTreeContext();
+    return getPath(value);
+}
+/**
+ * Returns one path per currently-selected value, in selection order.
+ * In single-selection mode the array has zero or one entry; in
+ * multiple-selection mode it has one entry per selected value.
+ *
+ * Each inner array is the same shape as the return of
+ * {@link useTreePath} — root → leaf segments with labels carried from
+ * the `label` prop.
+ *
+ * Used by `Tree.SelectionPath` for its default rendering, and
+ * available directly for fully-custom breadcrumb UIs.
+ *
+ * @example
+ * ```tsx
+ * function Crumbs() {
+ *   const paths = useTreeSelectionPaths();
+ *   if (paths.length === 0) return <span>Nothing selected</span>;
+ *   return (
+ *     <ul>
+ *       {paths.map((path, i) => (
+ *         <li key={i}>{path.map((s) => s.label ?? s.value).join(" / ")}</li>
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ */
+export function useTreeSelectionPaths() {
+    const { selectedOrder, getPath } = useTreeContext();
+    return selectedOrder.map((value) => getPath(value));
+}
+/**
+ * Read the current nesting depth inside a `Tree` — `0` for a node directly
+ * under {@link TreeRoot | `Tree.Root`}, one deeper per enclosing
+ * {@link TreeBranchContent | `Tree.BranchContent`}.
+ *
+ * A styling layer needs the depth as a *number* to compute a row's indent, and
+ * so to make the row span the tree's full width (a hover or selected band that
+ * runs edge to edge, as VS Code and most file trees do). Reading it back off
+ * the `data-depth` attribute in CSS requires `attr(data-depth type(<integer>))`,
+ * which Firefox does not support — hence this hook.
+ *
+ * @throws If called outside a `Tree.Root`.
+ *
+ * @example Indenting a row so its background still spans the full width
+ * ```tsx
+ * function StyledItem(props: TreeItemProps) {
+ *   const { depth } = useTreeLevel();
+ *   return (
+ *     <Tree.Item
+ *       {...props}
+ *       style={{ "--depth": depth } as CSSProperties}
+ *       className="row"
+ *     />
+ *   );
+ * }
+ * ```
+ */
+export function useTreeLevel() {
+    const { depth } = useTreeLevelContext();
+    return { depth };
+}

package/dist/Tree/hooks/useTreeRoot.d.ts

@@ -0,0 +1,19 @@
+import type { SelectionMode, TreeContextValue } from "../types.js";
+export type UseTreeRootOptions = {
+    expandedValues: string[] | undefined;
+    defaultExpandedValues: string[] | undefined;
+    onExpandedChange: ((values: string[]) => void) | undefined;
+    selectionMode: SelectionMode;
+    selectedValue: string | null | undefined;
+    defaultSelectedValue: string | null | undefined;
+    onSelectedValueChange: ((value: string | null) => void) | undefined;
+    selectedValues: string[] | undefined;
+    defaultSelectedValues: string[] | undefined;
+    onSelectedValuesChange: ((values: string[]) => void) | undefined;
+};
+/**
+ * Owns the Tree's expansion and selection state, the item collection
+ * used to compute the visible DFS order, and the anchor that pins
+ * Shift+click range selection.
+ */
+export declare function useTreeRoot(options: UseTreeRootOptions): TreeContextValue;

package/dist/Tree/hooks/useTreeRoot.js

@@ -0,0 +1,185 @@
+"use client";
+import { useCallback, useId, useRef, useState } from "react";
+import { useCollection, useControllableState } from "../../hooks/index.js";
+/** Defensive cap to short-circuit a cycle in `parentValue` pointers. */
+const MAX_PATH_DEPTH = 64;
+function singleToArray(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    return value === null ? [] : [value];
+}
+/**
+ * Owns the Tree's expansion and selection state, the item collection
+ * used to compute the visible DFS order, and the anchor that pins
+ * Shift+click range selection.
+ */
+export function useTreeRoot(options) {
+    const rootId = useId();
+    const [expandedValues, setExpandedValues] = useControllableState(options.expandedValues, options.defaultExpandedValues ?? [], options.onExpandedChange);
+    const normalisedSelectedValues = options.selectionMode === "multiple"
+        ? options.selectedValues
+        : singleToArray(options.selectedValue);
+    const normalisedDefaultSelectedValues = options.selectionMode === "multiple"
+        ? (options.defaultSelectedValues ?? [])
+        : (singleToArray(options.defaultSelectedValue) ?? []);
+    const handleSelectedValuesChange = useCallback((next) => {
+        if (options.selectionMode === "multiple") {
+            options.onSelectedValuesChange?.(next);
+        }
+        else {
+            options.onSelectedValueChange?.(next[0]);
+        }
+    }, [
+        options.selectionMode,
+        options.onSelectedValueChange,
+        options.onSelectedValuesChange,
+    ]);
+    const [selectedValues, setSelectedValues] = useControllableState(normalisedSelectedValues, normalisedDefaultSelectedValues, handleSelectedValuesChange);
+    const { register: registerCollectionNode, itemsRef, keys, } = useCollection();
+    // Durable copy of every node meta ever registered. Unlike the
+    // collection above (which deletes on unmount so visible-order /
+    // focus reflect mounted state) this map keeps the last-seen entry
+    // for each value so `getPath` resolves ancestry even when an
+    // ancestor branch has collapsed without `forceMount` and its
+    // descendants have unmounted.
+    const pathMetaRef = useRef(new Map());
+    const [pathMetaVersion, setPathMetaVersion] = useState(0);
+    const registerNode = useCallback((value, meta) => {
+        if (meta !== null) {
+            pathMetaRef.current.set(value, meta);
+            setPathMetaVersion((current) => current + 1);
+        }
+        registerCollectionNode(value, meta);
+    }, [registerCollectionNode]);
+    const getPath = useCallback((value) => {
+        const segments = [];
+        let cursor = value;
+        let hops = 0;
+        while (cursor !== null && hops < MAX_PATH_DEPTH) {
+            const meta = pathMetaRef.current.get(cursor);
+            if (meta === undefined) {
+                return [];
+            }
+            segments.unshift({
+                value: meta.value,
+                label: meta.label,
+                isBranch: meta.isBranch,
+                disabled: meta.disabled,
+                depth: meta.depth,
+            });
+            cursor = meta.parentValue;
+            hops += 1;
+        }
+        return segments;
+    }, 
+    // `pathMetaVersion` bumps whenever the persistent map mutates,
+    // forcing context-value identity to change so consumers re-render
+    // and re-evaluate `getPath`.
+    [pathMetaVersion]);
+    const anchorRef = useRef(null);
+    const [activeValue, setActiveValue] = useState(null);
+    const focusItem = useCallback((value) => {
+        itemsRef.current.get(value)?.element.focus();
+    }, [itemsRef]);
+    const isNodeDisabled = useCallback((value) => itemsRef.current.get(value)?.disabled === true, [itemsRef]);
+    const isExpanded = useCallback((value) => expandedValues.includes(value), [expandedValues]);
+    const toggleExpanded = useCallback((value) => {
+        const open = expandedValues.includes(value);
+        setExpandedValues(open
+            ? expandedValues.filter((current) => current !== value)
+            : [...expandedValues, value]);
+    }, [expandedValues, setExpandedValues]);
+    const isSelected = useCallback((value) => selectedValues.includes(value), [selectedValues]);
+    const getVisibleOrder = useCallback(() => {
+        const childrenByParent = new Map();
+        for (const key of keys) {
+            const meta = itemsRef.current.get(key);
+            const bucket = childrenByParent.get(meta.parentValue) ?? [];
+            bucket.push(meta.value);
+            childrenByParent.set(meta.parentValue, bucket);
+        }
+        const result = [];
+        const visit = (parent) => {
+            for (const value of childrenByParent.get(parent) ?? []) {
+                result.push(value);
+                const meta = itemsRef.current.get(value);
+                if (meta?.isBranch && expandedValues.includes(value)) {
+                    visit(value);
+                }
+            }
+        };
+        visit(null);
+        return result;
+    }, [keys, itemsRef, expandedValues]);
+    const select = useCallback((value, modifiers) => {
+        if (options.selectionMode === "single") {
+            if (selectedValues[0] === value) {
+                return;
+            }
+            setSelectedValues([value]);
+            anchorRef.current = value;
+            return;
+        }
+        const shift = modifiers?.shift === true;
+        const additive = modifiers?.meta === true || modifiers?.ctrl === true;
+        const alreadySelected = selectedValues.includes(value);
+        if (shift) {
+            const anchor = anchorRef.current ?? value;
+            const order = getVisibleOrder();
+            const anchorIndex = order.indexOf(anchor);
+            const valueIndex = order.indexOf(value);
+            if (anchorIndex === -1 || valueIndex === -1) {
+                setSelectedValues([value]);
+                return;
+            }
+            const [start, end] = anchorIndex <= valueIndex
+                ? [anchorIndex, valueIndex]
+                : [valueIndex, anchorIndex];
+            const range = order
+                .slice(start, end + 1)
+                .filter((candidate) => !isNodeDisabled(candidate));
+            setSelectedValues(range);
+            return;
+        }
+        if (additive) {
+            setSelectedValues(alreadySelected
+                ? selectedValues.filter((current) => current !== value)
+                : [...selectedValues, value]);
+            anchorRef.current = value;
+            return;
+        }
+        if (selectedValues.length === 1 && alreadySelected) {
+            return;
+        }
+        setSelectedValues([value]);
+        anchorRef.current = value;
+    }, [
+        options.selectionMode,
+        selectedValues,
+        setSelectedValues,
+        getVisibleOrder,
+        isNodeDisabled,
+    ]);
+    const visibleOrder = getVisibleOrder();
+    const defaultTabStop = visibleOrder.find((candidate) => !isNodeDisabled(candidate)) ?? null;
+    const tabStop = activeValue !== null && visibleOrder.includes(activeValue)
+        ? activeValue
+        : defaultTabStop;
+    return {
+        rootId,
+        selectionMode: options.selectionMode,
+        isExpanded,
+        toggleExpanded,
+        isSelected,
+        select,
+        registerNode,
+        getVisibleOrder,
+        isNodeDisabled,
+        tabStop,
+        setActiveValue,
+        focusItem,
+        getPath,
+        selectedOrder: selectedValues,
+    };
+}

package/dist/Tree/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./Tree.js";
+export * from "./types.js";
+export { TREE_PART, type TreePartName } from "./utils.js";
+export { useTreeLevel, useTreePath, useTreeSelectionPaths, } from "./hooks/useTreePath.js";

package/dist/Tree/index.js

@@ -0,0 +1,4 @@
+export * from "./Tree.js";
+export * from "./types.js";
+export { TREE_PART } from "./utils.js";
+export { useTreeLevel, useTreePath, useTreeSelectionPaths, } from "./hooks/useTreePath.js";

package/dist/Tree/types.d.ts

@@ -0,0 +1,269 @@
+import type { ComponentProps, ReactNode } from "react";
+/** Mode-independent props shared by every `Tree.Root` variant. */
+export type TreeRootBaseProps = ComponentProps<"div"> & {
+    children: ReactNode;
+};
+/** Uncontrolled expansion — initial expanded branches via `defaultExpandedValues`. */
+export type TreeRootUncontrolledExpansionProps = {
+    /** Branch values expanded on first render when uncontrolled. Omit for a
+     * fully-collapsed tree. */
+    defaultExpandedValues?: string[];
+    expandedValues?: never;
+    /** Called with the full set of expanded branch values whenever a branch
+     * is toggled. Optional in uncontrolled mode. */
+    onExpandedChange?: (values: string[]) => void;
+};
+/** Controlled expansion — the expanded set is owned by the consumer. */
+export type TreeRootControlledExpansionProps = {
+    defaultExpandedValues?: never;
+    /** The set of expanded branch values, owned by the consumer. Keep in
+     * sync via `onExpandedChange`. */
+    expandedValues: string[];
+    /** Called with the full set of expanded branch values the user requested
+     * on each toggle. Required in controlled mode. */
+    onExpandedChange: (values: string[]) => void;
+};
+/** Single-selection mode, uncontrolled — initial value via `defaultSelectedValue`. */
+export type TreeRootSingleUncontrolledSelectionProps = {
+    /** At most one node may be selected; see {@link SelectionMode}.
+     * @default "single" */
+    selectionMode?: "single";
+    /** The value selected on first render when uncontrolled. `null` selects
+     * nothing. */
+    defaultSelectedValue?: string | null;
+    selectedValue?: never;
+    /** Called with the newly-selected value (or `null` when cleared) on each
+     * user selection. Optional in uncontrolled mode. */
+    onSelectedValueChange?: (value: string | null) => void;
+    defaultSelectedValues?: never;
+    selectedValues?: never;
+    onSelectedValuesChange?: never;
+};
+/** Single-selection mode, controlled — the selected value is owned by the consumer. */
+export type TreeRootSingleControlledSelectionProps = {
+    /** At most one node may be selected; see {@link SelectionMode}.
+     * @default "single" */
+    selectionMode?: "single";
+    defaultSelectedValue?: never;
+    /** The selected value, owned by the consumer (or `null` for no
+     * selection). Keep it in sync via `onSelectedValueChange`. */
+    selectedValue: string | null;
+    /** Called with the value the user requested to select (or `null` when
+     * cleared). Required in controlled mode. */
+    onSelectedValueChange: (value: string | null) => void;
+    defaultSelectedValues?: never;
+    selectedValues?: never;
+    onSelectedValuesChange?: never;
+};
+/** Multiple-selection mode, uncontrolled — initial values via `defaultSelectedValues`. */
+export type TreeRootMultipleUncontrolledSelectionProps = {
+    /** Many nodes may be selected via `Ctrl`/`Cmd`+click and `Shift`+click
+     * ranges; see {@link SelectionMode}. */
+    selectionMode: "multiple";
+    /** The values selected on first render when uncontrolled. */
+    defaultSelectedValues?: string[];
+    selectedValues?: never;
+    /** Called with the full selected set (in selection order) on each
+     * change. Optional in uncontrolled mode. */
+    onSelectedValuesChange?: (values: string[]) => void;
+    defaultSelectedValue?: never;
+    selectedValue?: never;
+    onSelectedValueChange?: never;
+};
+/** Multiple-selection mode, controlled — the selected values are owned by the consumer. */
+export type TreeRootMultipleControlledSelectionProps = {
+    /** Many nodes may be selected via `Ctrl`/`Cmd`+click and `Shift`+click
+     * ranges; see {@link SelectionMode}. */
+    selectionMode: "multiple";
+    defaultSelectedValues?: never;
+    /** The selected values, owned by the consumer. Keep in sync via
+     * `onSelectedValuesChange`. */
+    selectedValues: string[];
+    /** Called with the full selected set (in selection order) the user
+     * requested. Required in controlled mode. */
+    onSelectedValuesChange: (values: string[]) => void;
+    defaultSelectedValue?: never;
+    selectedValue?: never;
+    onSelectedValueChange?: never;
+};
+/**
+ * Props for `Tree.Root`. Combines the shared {@link TreeRootBaseProps} with
+ * one expansion arm (controlled / uncontrolled) and one selection arm
+ * (single / multiple, controlled / uncontrolled), so the relevant
+ * `value` / `defaultValue` / `onChange` shape is enforced per mode.
+ */
+export type TreeRootProps = TreeRootBaseProps & (TreeRootUncontrolledExpansionProps | TreeRootControlledExpansionProps) & (TreeRootSingleUncontrolledSelectionProps | TreeRootSingleControlledSelectionProps | TreeRootMultipleUncontrolledSelectionProps | TreeRootMultipleControlledSelectionProps);
+/** Props for `Tree.Item` — a selectable, focusable leaf treeitem. */
+export type TreeItemProps = ComponentProps<"div"> & {
+    /** Stable identifier for this item, unique within the tree. Links the
+     * item to selection / expansion state and to its
+     * {@link TreePathSegment} in a resolved path. */
+    value: string;
+    /**
+     * Optional display label for this item. Stored alongside the value
+     * in the tree's node registry so {@link useTreePath} and
+     * `Tree.SelectionPath` can surface it without an external lookup.
+     * Has no effect on what `Tree.Item` renders.
+     */
+    label?: string;
+    /** Disable selection and remove the item from roving navigation
+     * (`Home`/`End` still skip past it to a non-disabled neighbour).
+     * @default false */
+    disabled?: boolean;
+    /** Render the item as the supplied child element instead of `<div>`,
+     * merging the treeitem behaviour onto it via the {@link Slot} pattern.
+     * The child must accept a `ref`.
+     * @default false */
+    asChild?: boolean;
+    children: ReactNode;
+};
+/** Props for `Tree.Branch` — an expandable treeitem with nested children. */
+export type TreeBranchProps = Omit<ComponentProps<"div">, "ref"> & {
+    /** Stable identifier for this branch, unique within the tree. Also seeds
+     * the `parentValue` of its {@link TreeBranchContent}'s children and the
+     * derived `aria-labelledby` control id. */
+    value: string;
+    /**
+     * Optional display label for this branch. Stored alongside the value
+     * in the tree's node registry so {@link useTreePath} and
+     * `Tree.SelectionPath` can surface it without an external lookup.
+     * Has no effect on what `Tree.Branch` renders.
+     */
+    label?: string;
+    /**
+     * Disable selection, expansion-toggling, and roving navigation for
+     * this branch. The branch and its current content remain rendered.
+     * @default false
+     */
+    disabled?: boolean;
+    children: ReactNode;
+};
+/** Props for `Tree.BranchControl` — the branch's selectable, toggling control row. */
+export type TreeBranchControlProps = ComponentProps<"div"> & {
+    /** Render the control as the supplied child element instead of `<div>`,
+     * merging its props (including the `aria-labelledby` id) onto the child
+     * via the {@link Slot} pattern. The child must accept a `ref`.
+     * @default false */
+    asChild?: boolean;
+    children: ReactNode;
+};
+/** Props for `Tree.BranchContent` — the collapsible group of a branch's child nodes. */
+export type TreeBranchContentProps = ComponentProps<"div"> & {
+    children: ReactNode;
+    /**
+     * Keep the content mounted while the branch is collapsed so CSS can
+     * animate it in and out. When collapsed it is hidden from assistive
+     * technology with `aria-hidden` and carries `data-state="closed"`.
+     * @default false
+     */
+    forceMount?: boolean;
+};
+/** Props for `Tree.BranchIndicator` — the expand/collapse affordance. */
+export type TreeBranchIndicatorProps = ComponentProps<"span"> & {
+    /** Render as the supplied child element instead of `<span>`, merging
+     * `aria-hidden` and `data-state` onto it via the {@link Slot} pattern
+     * (e.g. an icon that rotates on `data-state="open"`).
+     * @default false */
+    asChild?: boolean;
+};
+/** Arguments passed to the `Tree.SelectionPath` render-prop form. */
+export type TreeSelectionPathRenderProps = {
+    /** One root-to-leaf chain per currently-selected value, in selection order. */
+    paths: TreePathSegment[][];
+};
+/**
+ * Props for `Tree.SelectionPath` — a breadcrumb of the selected node's
+ * root-to-leaf ancestry, with an optional render-prop for custom layout.
+ */
+export type TreeSelectionPathProps = Omit<ComponentProps<"div">, "children"> & {
+    /**
+     * Either standard React children (ignored — the subcomponent does its
+     * own rendering) or a render-prop receiving the resolved selection
+     * paths so consumers can lay out custom markup.
+     */
+    children?: ReactNode | ((args: TreeSelectionPathRenderProps) => ReactNode);
+    /**
+     * Node passed to each `Breadcrumb.Separator` in the default rendering.
+     * Defaults to Breadcrumb's built-in `"/"` glyph.
+     */
+    separator?: ReactNode;
+};
+/** Per-level context — the nesting depth and enclosing branch value, shared down each subtree. */
+export type TreeLevelContextValue = {
+    /** Zero-based nesting depth — `0` for items directly inside `Tree.Root`. */
+    depth: number;
+    /** The value of the enclosing branch, or `null` at the tree root. */
+    parentValue: string | null;
+};
+/** Registry entry for one tree node — its value, element, and structural metadata. */
+export type TreeNodeMeta = {
+    value: string;
+    element: HTMLElement;
+    isBranch: boolean;
+    disabled: boolean;
+    depth: number;
+    parentValue: string | null;
+    label: string | null;
+};
+/**
+ * One segment of an ancestor chain returned by {@link useTreePath} or
+ * `TreeContextValue.getPath`. The array is ordered **root → leaf**, so
+ * the last segment is the queried item itself.
+ */
+export type TreePathSegment = {
+    value: string;
+    label: string | null;
+    isBranch: boolean;
+    disabled: boolean;
+    depth: number;
+};
+/** Whether the tree allows one selected node (`"single"`) or many (`"multiple"`). */
+export type SelectionMode = "single" | "multiple";
+/** Keyboard/pointer modifiers that influence a selection gesture. */
+export type TreeSelectModifiers = {
+    meta: boolean;
+    ctrl: boolean;
+    shift: boolean;
+};
+/**
+ * Context shared from `Tree.Root` to every descendant — selection and
+ * expansion state, the node registry, roving-tabindex bookkeeping, and the
+ * path resolver.
+ */
+export type TreeContextValue = {
+    /** Stable id shared across the tree, used to derive ARIA wiring ids. */
+    rootId: string;
+    selectionMode: SelectionMode;
+    isExpanded: (value: string) => boolean;
+    toggleExpanded: (value: string) => void;
+    isSelected: (value: string) => boolean;
+    select: (value: string, modifiers?: TreeSelectModifiers) => void;
+    registerNode: (value: string, meta: TreeNodeMeta | null) => void;
+    getVisibleOrder: () => string[];
+    isNodeDisabled: (value: string) => boolean;
+    /** Value of the treeitem currently holding the single roving tabstop. */
+    tabStop: string | null;
+    setActiveValue: (value: string) => void;
+    focusItem: (value: string) => void;
+    /**
+     * Returns the root-to-leaf chain of segments for the given value, or
+     * an empty array if the value has never been registered. Walks the
+     * persistent node registry so paths remain resolvable even when an
+     * ancestor branch has collapsed and its descendants unmounted.
+     */
+    getPath: (value: string) => TreePathSegment[];
+    /**
+     * The currently-selected values in selection order. Mirrors
+     * `selectedValues` in multiple mode and `[selectedValue]` (or `[]`)
+     * in single mode.
+     */
+    selectedOrder: readonly string[];
+};
+/** Context a branch shares with its own control and content — its value, expanded/disabled state, and control id. */
+export type TreeItemContextValue = {
+    value: string;
+    expanded: boolean;
+    disabled: boolean;
+    /** DOM `id` of the branch's `BranchControl`, for `aria-labelledby`. */
+    controlId: string;
+};

package/dist/Tree/types.js

@@ -0,0 +1 @@
+export {};