@primitiv-ui/react 0.1.28 → 0.1.30

package/src/Tree/Tree.tsx

@@ -36,11 +36,39 @@ import type {
  * `<div role="tree">` and provides every descendant with the expansion
  * set, selection set, and roving-tabstop coordination.
  *
- * Expansion is controlled/uncontrolled via the `expandedValues` /
- * `defaultExpandedValues` pair (with `onExpandedChange`). Selection
- * follows the same shape under `selectionMode="single"` (default) or
- * `"multiple"`, the two modes statically discriminated so passing the
- * wrong prop pair is a type error.
+ * **State ownership.** Root owns two independent axes, each controllable
+ * or uncontrolled:
+ *
+ * - **Expansion** — which branches are open. Controlled via
+ *   {@link TreeRootControlledExpansionProps.expandedValues | `expandedValues`}
+ *   + {@link TreeRootControlledExpansionProps.onExpandedChange | `onExpandedChange`};
+ *   uncontrolled via
+ *   {@link TreeRootUncontrolledExpansionProps.defaultExpandedValues | `defaultExpandedValues`}.
+ * - **Selection** — which node(s) are selected, gated by
+ *   {@link SelectionMode | `selectionMode`} (`"single"` default, or
+ *   `"multiple"`). Each mode has its own controlled / uncontrolled
+ *   `value` / `defaultValue` / `onChange` prop trio, statically
+ *   discriminated so passing the wrong prop pair for the active mode is
+ *   a type error.
+ *
+ * **Roving tabindex.** The whole tree exposes a **single tab stop** — at
+ * most one `treeitem` carries `tabIndex={0}` (the last-focused visible
+ * item, else the first non-disabled item in visible depth-first order);
+ * every other item is `tabIndex={-1}`. `Tab` therefore enters and leaves
+ * the tree once, and the arrow keys move focus *within* it. See
+ * {@link TreeItem} / {@link TreeBranch} for the full key table.
+ *
+ * **Context.** Root provides the `TreeContext` (expansion/selection
+ * state, the node registry, roving bookkeeping, path resolver) and seeds
+ * the `TreeLevelContext` at `{ depth: 0, parentValue: null }`, which each
+ * {@link TreeBranchContent} deepens for its children.
+ *
+ * **Styling hooks.**
+ * - `role="tree"` on the rendered container.
+ * - `aria-multiselectable="true"` only when `selectionMode="multiple"`.
+ * - `data-selection-mode="single" | "multiple"`.
+ *
+ * @extends HTMLDivElement
  *
  * @example Uncontrolled, single selection
  * ```tsx
@@ -60,7 +88,7 @@ import type {
  *   selectionMode="multiple"
  *   onSelectedValuesChange={(values) => console.log(values)}
  * >
- *   {…}
+ *   {...}
  * </Tree.Root>
  * ```
  */
@@ -120,18 +148,57 @@ export function TreeRoot(props: TreeRootProps): ReactElement {
 TreeRoot.displayName = "TreeRoot";
 
 /**
- * A leaf treeitem — a selectable, focusable node that has no children.
- * Renders a `<div role="treeitem">` by default; pass `asChild` to merge
- * Tree behaviour onto a consumer element (e.g. `<a>`).
+ * A leaf treeitem — a selectable, focusable node with no children.
+ * Renders a `<div role="treeitem">` by default; pass
+ * {@link TreeItemProps.asChild | `asChild`} to merge the tree behaviour
+ * onto a consumer element instead (e.g. an `<a>` for a navigable file).
+ *
+ * **Selection.** Clicking the item *replaces* the selection in single
+ * mode. In multiple mode, `Ctrl`/`Cmd`+click toggles it into or out of
+ * the set, and `Shift`+click selects the contiguous range (in visible
+ * depth-first order, disabled nodes excluded) between the previous
+ * selection anchor and this item.
+ *
+ * **Depth & registry.** The item reads its nesting depth and enclosing
+ * branch from `TreeLevelContext`, emits `aria-level={depth + 1}`, and
+ * registers itself (value, {@link TreeItemProps.label | `label`}, depth,
+ * parent) in the tree's node registry. The registry keeps the last-seen
+ * entry per value even after unmount, so `Tree.SelectionPath` and
+ * {@link useTreePath} can resolve ancestry through a collapsed branch.
+ *
+ * **Keyboard** (while focused; movement is over *visible* items in
+ * depth-first order, skipping collapsed subtrees and disabled nodes):
  *
- * Clicking the item replaces the selection in single mode and toggles
- * it under `Ctrl`/`Cmd` in multiple mode; `Shift+click` selects the
- * range between the previous click and this one.
+ * | Key                     | Behaviour                                     |
+ * | ----------------------- | --------------------------------------------- |
+ * | `ArrowDown` / `ArrowUp` | Move focus to the next / previous visible item |
+ * | `ArrowLeft`             | Move focus to the parent branch (no-op at root)|
+ * | `Home` / `End`          | Focus the first / last visible item            |
+ * | `Enter` / `Space`       | Select the item                                |
+ *
+ * A `disabled` item is removed from the roving order and ignores
+ * selection, but `Home`/`End` still land on non-disabled neighbours.
+ *
+ * **Styling hooks.**
+ * - `role="treeitem"`, `aria-level`, `aria-selected`, and `aria-disabled`
+ *   (omitted when not disabled).
+ * - `data-leaf=""` (always), `data-depth="{n}"`.
+ * - `data-selected=""` when selected, `data-disabled=""` when disabled
+ *   (both omitted otherwise).
+ *
+ * @extends HTMLDivElement
  *
  * @example
  * ```tsx
  * <Tree.Item value="readme">readme</Tree.Item>
  * ```
+ *
+ * @example asChild — a navigable leaf
+ * ```tsx
+ * <Tree.Item asChild value="readme">
+ *   <a href="/readme">readme</a>
+ * </Tree.Item>
+ * ```
  */
 export function TreeItem({
   value,
@@ -212,10 +279,43 @@ TreeItem.displayName = "TreeItem";
  * with `partitionBranchChildren`.
  *
  * The branch carries `aria-expanded`, `aria-selected`, `aria-level`,
- * and is labelled by its control row via `aria-labelledby` so its
- * accessible name is not polluted by descendant text. Content is
- * unmounted while collapsed unless the inner `Tree.BranchContent`
- * opts in to `forceMount`.
+ * and is labelled by its control row via `aria-labelledby` (an id
+ * derived from the root id + this branch's `value`), so its accessible
+ * name is the control text alone and not polluted by descendant text.
+ * Content is unmounted while collapsed unless the inner
+ * {@link TreeBranchContent} opts in to
+ * {@link TreeBranchContentProps.forceMount | `forceMount`}.
+ *
+ * **Composition.** A `Tree.Branch` must contain exactly one
+ * {@link TreeBranchControl} and at most one {@link TreeBranchContent};
+ * both are matched however deeply they are wrapped in fragments (so
+ * `{open && <BranchContent/>}` partitions the same as a bare element).
+ * Violating that throws a descriptive error during render. The branch
+ * provides `TreeItemContext` (its value, expanded/disabled state, and
+ * control id) to those two sub-components.
+ *
+ * **Keyboard** (adds branch semantics on top of the roving keys shared
+ * with {@link TreeItem}):
+ *
+ * | Key          | Behaviour                                                     |
+ * | ------------ | ------------------------------------------------------------- |
+ * | `ArrowRight` | Expand if collapsed; if already open, move focus to first child|
+ * | `ArrowLeft`  | Collapse if open; otherwise move focus to the parent branch    |
+ * | `Enter` / `Space` | Toggle expansion **and** select the branch in one gesture |
+ *
+ * A `disabled` branch keeps its row and current content rendered but
+ * ignores expansion, selection, and the branch arrow keys, and is
+ * skipped by roving navigation.
+ *
+ * **Styling hooks.**
+ * - `role="treeitem"`, `aria-level`, `aria-expanded`, `aria-selected`,
+ *   `aria-labelledby`, and `aria-disabled` (omitted when not disabled).
+ * - `data-branch=""` (always), `data-depth="{n}"`,
+ *   `data-state="open" | "closed"`.
+ * - `data-selected=""` / `data-disabled=""` when applicable (omitted
+ *   otherwise).
+ *
+ * @extends HTMLDivElement
  *
  * @example
  * ```tsx
@@ -307,11 +407,21 @@ export function TreeBranch({
 TreeBranch.displayName = "TreeBranch";
 
 /**
- * The clickable row of a `Tree.Branch`. Renders a `<div>` by default
- * (or any element via `asChild`) and is identified by the id the
- * surrounding branch points `aria-labelledby` at. Clicking the row
- * toggles the branch's expansion and selects it in a single gesture;
- * the inner `Tree.BranchIndicator` is decorative.
+ * The clickable row of a {@link TreeBranch | `Tree.Branch`}. Renders a
+ * `<div>` by default, or any element via
+ * {@link TreeBranchControlProps.asChild | `asChild`}. It carries the
+ * `id` that the surrounding branch points `aria-labelledby` at, so its
+ * text becomes the branch's accessible name — keep the label content
+ * here rather than on the branch.
+ *
+ * Clicking the row toggles the branch's expansion **and** selects it in
+ * a single gesture (with the same `Ctrl`/`Cmd` / `Shift` modifier rules
+ * as {@link TreeItem}); the inner {@link TreeBranchIndicator} is purely
+ * decorative. A disabled branch's control ignores the click. Reads its
+ * value / disabled state / id from the branch's `TreeItemContext`, so it
+ * must be rendered inside a `Tree.Branch`.
+ *
+ * @extends HTMLDivElement
  *
  * @example
  * ```tsx
@@ -356,13 +466,30 @@ export function TreeBranchControl({
 TreeBranchControl.displayName = "TreeBranchControl";
 
 /**
- * The nested group of items inside a `Tree.Branch`. Renders a
- * `<div role="group">` whose children sit at one deeper nesting level.
+ * The nested group of items inside a {@link TreeBranch | `Tree.Branch`}.
+ * Renders a `<div role="group">` and deepens the `TreeLevelContext` for
+ * its children (`depth + 1`, `parentValue` = the enclosing branch), so
+ * they emit the correct `aria-level` and register under the right parent.
+ *
+ * By default the content is **unmounted** while the branch is collapsed —
+ * the lean-DOM strategy. Pass
+ * {@link TreeBranchContentProps.forceMount | `forceMount`} to keep it
+ * mounted while collapsed with `aria-hidden="true"` and
+ * `data-state="closed"`, so CSS can animate it in and out without the
+ * browser tearing the subtree down.
+ *
+ * **Styling hooks.**
+ * - `role="group"`, `data-depth="{n}"`, `data-state="open" | "closed"`.
+ * - `aria-hidden="true"` only while force-mounted and collapsed.
  *
- * By default the content is unmounted while the branch is collapsed —
- * the lean DOM strategy. Pass `forceMount` to keep it mounted with
- * `aria-hidden="true"` and `data-state="closed"`, so CSS can animate
- * it in and out without the browser tearing the subtree down.
+ * @extends HTMLDivElement
+ *
+ * @example forceMount for CSS transitions
+ * ```tsx
+ * <Tree.BranchContent forceMount>
+ *   <Tree.Item value="index">index.ts</Tree.Item>
+ * </Tree.BranchContent>
+ * ```
  */
 export function TreeBranchContent({
   children,
@@ -398,10 +525,15 @@ TreeBranchContent.displayName = "TreeBranchContent";
  * `"closed"` so a consumer's CSS can rotate or swap the glyph. Only
  * meaningful inside a `Tree.BranchControl`.
  *
- * Pass `asChild` to merge the indicator's props — including
- * `aria-hidden` and `data-state` — onto the supplied child element.
- * This is useful when passing an icon component that must receive
- * `data-state` directly rather than inheriting it from a wrapper:
+ * Pass {@link TreeBranchIndicatorProps.asChild | `asChild`} to merge the
+ * indicator's props — including `aria-hidden` and `data-state` — onto the
+ * supplied child element. This is useful when passing an icon component
+ * that must receive `data-state` directly rather than inheriting it from
+ * a wrapper. Reads its `expanded` state from the branch's
+ * `TreeItemContext`, so it must be rendered inside a
+ * {@link TreeBranchControl}.
+ *
+ * @extends HTMLSpanElement
  *
  * @example Default (wraps children in a `<span>`)
  * ```tsx
@@ -456,9 +588,24 @@ TreeBranchIndicator.displayName = "TreeBranchIndicator";
  *
  * Pass `separator` to customise the divider glyph between segments.
  *
- * Pass a function as `children` to take full control of rendering
- * (e.g. wire up router links). The function receives the resolved
- * paths and replaces the default markup entirely.
+ * Pass {@link TreeSelectionPathProps.separator | `separator`} to
+ * customise the divider glyph between segments, or a function as
+ * `children` to take full control of rendering (e.g. wire up router
+ * links). The function receives the resolved
+ * {@link TreeSelectionPathRenderProps.paths | `paths`} and replaces the
+ * default markup entirely.
+ *
+ * Backed by {@link useTreeSelectionPaths}, which reads ancestry from the
+ * persistent node registry — so trails stay resolvable even when an
+ * ancestor branch has collapsed and its descendants have unmounted.
+ *
+ * **Styling hooks.**
+ * - `data-tree-selection-path=""` on the wrapper (always).
+ * - `data-empty=""` on the wrapper when nothing is selected.
+ * - `data-tree-selection-segment=""` + `data-value` (and `data-disabled`
+ *   when the node is disabled) on each rendered segment.
+ *
+ * @extends HTMLDivElement
  *
  * @example Default rendering
  * ```tsx
@@ -600,6 +747,13 @@ export type TreeCompound = typeof TreeRoot & {
  *   </Tree.Branch>
  * </Tree.Root>;
  * ```
+ *
+ * @see {@link TreeRoot} for the expansion / selection state modes and the
+ *   single tree-wide roving tab stop.
+ * @see {@link TreeItem} and {@link TreeBranch} for the keyboard tables and
+ *   selection modifiers.
+ * @see {@link useTreePath} / {@link useTreeSelectionPaths} for reading a
+ *   node's ancestry outside `Tree.SelectionPath`.
  */
 const TreeCompound: TreeCompound = Object.assign(TreeRoot, {
   Root: TreeRoot,

package/src/Tree/__tests__/Tree.styled-wrapper.test.tsx

@@ -0,0 +1,159 @@
+import { render, screen } from "@testing-library/react";
+import type { ComponentPropsWithRef } from "react";
+import { describe, expect, it } from "vitest";
+
+import { Tree, TREE_PART, useTreeLevel } from "../index";
+
+/**
+ * A styled layer wraps every part in its own component to attach classes — the
+ * shape `primitiv add tree` copies into a consumer repo. `Tree.Branch` finds its
+ * control and content by inspecting its children, so those wrappers have to be
+ * recognisable as the parts they render; without that, Tree is the one primitive
+ * in the library that cannot be wrapped at all.
+ */
+function StyledBranchControl(props: ComponentPropsWithRef<typeof Tree.BranchControl>) {
+  return <Tree.BranchControl {...props} className="styled-control" />;
+}
+StyledBranchControl[TREE_PART] = "branch-control";
+
+function StyledBranchContent(props: ComponentPropsWithRef<typeof Tree.BranchContent>) {
+  return <Tree.BranchContent {...props} className="styled-content" />;
+}
+StyledBranchContent[TREE_PART] = "branch-content";
+
+describe("Tree — styled wrappers", () => {
+  it("accepts a wrapper component in place of Tree.BranchControl", () => {
+    // Arrange / Act
+    render(
+      <Tree.Root defaultExpandedValues={["src"]}>
+        <Tree.Branch value="src">
+          <StyledBranchControl>src</StyledBranchControl>
+          <StyledBranchContent>
+            <Tree.Item value="index.ts">index.ts</Tree.Item>
+          </StyledBranchContent>
+        </Tree.Branch>
+      </Tree.Root>,
+    );
+
+    // Assert
+    expect(screen.getByText("src")).toHaveClass("styled-control");
+    expect(screen.getByRole("group")).toHaveClass("styled-content");
+  });
+
+  it("labels the branch by its wrapped control, so the name is just the row", () => {
+    // Arrange / Act
+    render(
+      <Tree.Root defaultExpandedValues={["src"]}>
+        <Tree.Branch value="src">
+          <StyledBranchControl>src</StyledBranchControl>
+          <StyledBranchContent>
+            <Tree.Item value="index.ts">index.ts</Tree.Item>
+          </StyledBranchContent>
+        </Tree.Branch>
+      </Tree.Root>,
+    );
+
+    // Assert — the branch treeitem takes its accessible name from the control
+    // row alone, not from the whole subtree.
+    expect(screen.getByRole("treeitem", { name: "src" })).toHaveAttribute(
+      "aria-expanded",
+      "true",
+    );
+  });
+
+  it("reads forceMount from the wrapper element, not from what it renders", () => {
+    // A styled layer animates the open/close transition, which needs the group
+    // to stay mounted while closed. Tree.Branch reads `forceMount` off the
+    // element it is handed, so setting it *inside* the wrapper is invisible —
+    // the subtree unmounts and there is nothing left to animate. This is the
+    // contract the registry surface depends on.
+
+    // Arrange / Act — closed, with forceMount on the wrapper element
+    const { rerender } = render(
+      <Tree.Root>
+        <Tree.Branch value="src">
+          <StyledBranchControl>src</StyledBranchControl>
+          <StyledBranchContent forceMount>
+            <Tree.Item value="index.ts">index.ts</Tree.Item>
+          </StyledBranchContent>
+        </Tree.Branch>
+      </Tree.Root>,
+    );
+
+    // Assert — still in the DOM, marked closed and hidden from AT
+    const group = document.querySelector('[role="group"]');
+    expect(group).toHaveAttribute("data-state", "closed");
+    expect(group).toHaveAttribute("aria-hidden", "true");
+
+    // Act — without it, the branch drops the subtree entirely
+    rerender(
+      <Tree.Root>
+        <Tree.Branch value="src">
+          <StyledBranchControl>src</StyledBranchControl>
+          <StyledBranchContent>
+            <Tree.Item value="index.ts">index.ts</Tree.Item>
+          </StyledBranchContent>
+        </Tree.Branch>
+      </Tree.Root>,
+    );
+
+    // Assert
+    expect(document.querySelector('[role="group"]')).toBeNull();
+  });
+
+  it("still rejects two controls when both are wrappers", () => {
+    // Arrange / Act / Assert
+    expect(() =>
+      render(
+        <Tree.Root>
+          <Tree.Branch value="src">
+            <StyledBranchControl>one</StyledBranchControl>
+            <StyledBranchControl>two</StyledBranchControl>
+          </Tree.Branch>
+        </Tree.Root>,
+      ),
+    ).toThrow("A Tree.Branch may contain at most one <Tree.BranchControl>.");
+  });
+});
+
+describe("useTreeLevel", () => {
+  function Depth() {
+    const { depth } = useTreeLevel();
+    return <span data-testid={`depth-${depth}`}>{depth}</span>;
+  }
+
+  it("reports the nesting depth so a styled layer can indent without attr()", () => {
+    // A styled layer needs the depth as a NUMBER to compute a row's indent.
+    // Reading it back off `data-depth` in CSS needs `attr(... type(<integer>))`,
+    // which Firefox does not support — so the depth is exposed here instead.
+
+    // Arrange / Act
+    render(
+      <Tree.Root defaultExpandedValues={["a", "b"]}>
+        <Depth />
+        <Tree.Branch value="a">
+          <StyledBranchControl>a</StyledBranchControl>
+          <StyledBranchContent>
+            <Depth />
+            <Tree.Branch value="b">
+              <StyledBranchControl>b</StyledBranchControl>
+              <StyledBranchContent>
+                <Depth />
+              </StyledBranchContent>
+            </Tree.Branch>
+          </StyledBranchContent>
+        </Tree.Branch>
+      </Tree.Root>,
+    );
+
+    // Assert — 0 at the root, one deeper per BranchContent
+    expect(screen.getByTestId("depth-0")).toBeInTheDocument();
+    expect(screen.getByTestId("depth-1")).toBeInTheDocument();
+    expect(screen.getByTestId("depth-2")).toBeInTheDocument();
+  });
+
+  it("throws outside a Tree", () => {
+    // Arrange / Act / Assert
+    expect(() => render(<Depth />)).toThrow();
+  });
+});

package/src/Tree/hooks/useTreePath.ts

@@ -1,4 +1,4 @@
-import { useTreeContext } from "../TreeContext";
+import { useTreeContext, useTreeLevelContext } from "../TreeContext";
 
 import type { TreePathSegment } from "../types";
 
@@ -66,3 +66,35 @@ export function useTreeSelectionPaths(): TreePathSegment[][] {
   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(): { depth: number } {
+  const { depth } = useTreeLevelContext();
+  return { depth };
+}

package/src/Tree/index.ts

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

package/src/Tree/types.ts

@@ -7,26 +7,37 @@ export type TreeRootBaseProps = ComponentProps<"div"> & {
 
 /** Uncontrolled expansion — initial expanded branches via `defaultExpandedValues`. */
 export type TreeRootUncontrolledExpansionProps = {
-  /** Branch values expanded on first render when uncontrolled. */
+  /** 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. */
+  /** 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. */
+  /** 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;
@@ -35,10 +46,15 @@ export type TreeRootSingleUncontrolledSelectionProps = {
 
 /** 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. */
+  /** 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;
@@ -47,10 +63,14 @@ export type TreeRootSingleControlledSelectionProps = {
 
 /** 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;
@@ -59,10 +79,15 @@ export type TreeRootMultipleUncontrolledSelectionProps = {
 
 /** 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. */
+  /** 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;
@@ -86,7 +111,9 @@ export type TreeRootProps = TreeRootBaseProps &
 
 /** Props for `Tree.Item` — a selectable, focusable leaf treeitem. */
 export type TreeItemProps = ComponentProps<"div"> & {
-  /** Stable identifier for this item, unique within the tree. */
+  /** 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
@@ -95,16 +122,23 @@ export type TreeItemProps = ComponentProps<"div"> & {
    * Has no effect on what `Tree.Item` renders.
    */
   label?: string;
-  /** Disable selection and remove the item from roving navigation. */
+  /** 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>`. */
+  /** 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. */
+  /** 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
@@ -116,6 +150,7 @@ export type TreeBranchProps = Omit<ComponentProps<"div">, "ref"> & {
   /**
    * Disable selection, expansion-toggling, and roving navigation for
    * this branch. The branch and its current content remain rendered.
+   * @default false
    */
   disabled?: boolean;
   children: ReactNode;
@@ -123,7 +158,10 @@ export type TreeBranchProps = Omit<ComponentProps<"div">, "ref"> & {
 
 /** 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>`. */
+  /** 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;
 };
@@ -134,14 +172,18 @@ export type TreeBranchContentProps = ComponentProps<"div"> & {
   /**
    * 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`.
+   * 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>`. */
+  /** 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;
 };