@primitiv-ui/react 0.1.28 → 0.1.30

package/src/Tooltip/__tests__/Tooltip.timer-coordination.test.tsx

@@ -0,0 +1,223 @@
+import { act, fireEvent, render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import { Tooltip } from "../Tooltip";
+
+describe("Tooltip.Root — timer callbacks stay current across re-renders", () => {
+  it("uses the current onOpenChange for both a focus-open and a blur-close after the Provider re-renders", async () => {
+    const user = userEvent.setup();
+    const firstOnOpenChange = vi.fn();
+    const secondOnOpenChange = vi.fn();
+
+    function Wrapper({
+      onOpenChange,
+    }: {
+      onOpenChange: (open: boolean) => void;
+    }) {
+      return (
+        <Tooltip.Provider>
+          <Tooltip.Root onOpenChange={onOpenChange}>
+            <Tooltip.Trigger>Focusable</Tooltip.Trigger>
+            <Tooltip.Content>Tooltip text</Tooltip.Content>
+          </Tooltip.Root>
+          <button>Other</button>
+        </Tooltip.Provider>
+      );
+    }
+
+    const { rerender } = render(<Wrapper onOpenChange={firstOnOpenChange} />);
+    rerender(<Wrapper onOpenChange={secondOnOpenChange} />);
+
+    await user.tab();
+    await user.tab();
+
+    expect(firstOnOpenChange).not.toHaveBeenCalled();
+    expect(secondOnOpenChange).toHaveBeenCalledWith(true);
+    expect(secondOnOpenChange).toHaveBeenCalledWith(false);
+  });
+});
+
+describe("Tooltip.Root — timer coordination (fake timers)", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("opens synchronously when the effective delay is 0, not via a scheduled timer", () => {
+    render(
+      <Tooltip.Provider delayDuration={0}>
+        <Tooltip.Root>
+          <Tooltip.Trigger>Hover me</Tooltip.Trigger>
+          <Tooltip.Content>Tooltip text</Tooltip.Content>
+        </Tooltip.Root>
+      </Tooltip.Provider>,
+    );
+
+    fireEvent.pointerEnter(screen.getByRole("button", { name: "Hover me" }));
+
+    expect(screen.getByRole("tooltip")).toBeInTheDocument();
+  });
+
+  it("cancels a pending hover-delay open timer when the trigger is focused before it elapses", () => {
+    const onOpenChange = vi.fn();
+
+    render(
+      <Tooltip.Provider delayDuration={1000}>
+        <Tooltip.Root onOpenChange={onOpenChange}>
+          <Tooltip.Trigger>Hover me</Tooltip.Trigger>
+          <Tooltip.Content>Tooltip text</Tooltip.Content>
+        </Tooltip.Root>
+      </Tooltip.Provider>,
+    );
+
+    fireEvent.pointerEnter(screen.getByRole("button", { name: "Hover me" }));
+    fireEvent.focus(screen.getByRole("button", { name: "Hover me" }));
+
+    expect(onOpenChange).toHaveBeenCalledTimes(1);
+
+    act(() => {
+      vi.advanceTimersByTime(1000);
+    });
+
+    expect(onOpenChange).toHaveBeenCalledTimes(1);
+  });
+
+  it("cancels a pending grace-period timer when the tooltip closes immediately during the grace window", () => {
+    const onOpenChange = vi.fn();
+
+    // No Tooltip.Content here: its document-level Escape listener would also
+    // fire and call closeImmediate a second time, muddying the call count
+    // this test cares about. The trigger's own Escape handler is enough to
+    // exercise closeImmediate while a grace-period timer is pending.
+    render(
+      <Tooltip.Provider delayDuration={0}>
+        <Tooltip.Root onOpenChange={onOpenChange}>
+          <Tooltip.Trigger>Hover me</Tooltip.Trigger>
+        </Tooltip.Root>
+      </Tooltip.Provider>,
+    );
+
+    fireEvent.pointerEnter(screen.getByRole("button", { name: "Hover me" }));
+    expect(onOpenChange).toHaveBeenCalledTimes(1);
+
+    // Leaving the trigger starts the grace-period close timer...
+    fireEvent.pointerLeave(screen.getByRole("button", { name: "Hover me" }));
+    // ...then Escape closes immediately, which must cancel that pending timer.
+    fireEvent.keyDown(screen.getByRole("button", { name: "Hover me" }), {
+      key: "Escape",
+    });
+
+    expect(onOpenChange).toHaveBeenCalledTimes(2);
+
+    act(() => {
+      vi.advanceTimersByTime(100);
+    });
+
+    expect(onOpenChange).toHaveBeenCalledTimes(2);
+  });
+
+  it("cancels the grace-period close timer when the pointer moves into the content", () => {
+    render(
+      <Tooltip.Provider delayDuration={0}>
+        <Tooltip.Root>
+          <Tooltip.Trigger>Hover me</Tooltip.Trigger>
+          <Tooltip.Content>Tooltip text</Tooltip.Content>
+        </Tooltip.Root>
+      </Tooltip.Provider>,
+    );
+
+    fireEvent.pointerEnter(screen.getByRole("button", { name: "Hover me" }));
+    expect(screen.getByRole("tooltip")).toBeInTheDocument();
+
+    fireEvent.pointerLeave(screen.getByRole("button", { name: "Hover me" }));
+    fireEvent.pointerEnter(screen.getByRole("tooltip"));
+
+    act(() => {
+      vi.advanceTimersByTime(100);
+    });
+
+    expect(screen.getByRole("tooltip")).toBeInTheDocument();
+  });
+
+  it("closes after the grace period once the pointer leaves the trigger without re-entering the content", () => {
+    render(
+      <Tooltip.Provider delayDuration={0}>
+        <Tooltip.Root>
+          <Tooltip.Trigger>Hover me</Tooltip.Trigger>
+          <Tooltip.Content>Tooltip text</Tooltip.Content>
+        </Tooltip.Root>
+      </Tooltip.Provider>,
+    );
+
+    fireEvent.pointerEnter(screen.getByRole("button", { name: "Hover me" }));
+    expect(screen.getByRole("tooltip")).toBeInTheDocument();
+
+    fireEvent.pointerLeave(screen.getByRole("button", { name: "Hover me" }));
+
+    // Still open right up until the grace period elapses.
+    expect(screen.getByRole("tooltip")).toBeInTheDocument();
+
+    act(() => {
+      vi.advanceTimersByTime(100);
+    });
+
+    expect(screen.queryByRole("tooltip")).toBeNull();
+  });
+
+  it("cancels a pending hover-delay open timer when the pointer leaves before it elapses, so the tooltip does not open later", () => {
+    render(
+      <Tooltip.Provider delayDuration={500}>
+        <Tooltip.Root>
+          <Tooltip.Trigger>Hover me</Tooltip.Trigger>
+          <Tooltip.Content>Tooltip text</Tooltip.Content>
+        </Tooltip.Root>
+      </Tooltip.Provider>,
+    );
+
+    fireEvent.pointerEnter(screen.getByRole("button", { name: "Hover me" }));
+    fireEvent.pointerLeave(screen.getByRole("button", { name: "Hover me" }));
+
+    act(() => {
+      vi.advanceTimersByTime(500);
+    });
+
+    expect(screen.queryByRole("tooltip")).toBeNull();
+  });
+
+  it("uses the current onOpenChange callback for a grace-period close after a re-render", () => {
+    const firstOnOpenChange = vi.fn();
+    const secondOnOpenChange = vi.fn();
+
+    function Wrapper({
+      onOpenChange,
+    }: {
+      onOpenChange: (open: boolean) => void;
+    }) {
+      return (
+        <Tooltip.Provider delayDuration={0}>
+          <Tooltip.Root onOpenChange={onOpenChange}>
+            <Tooltip.Trigger>Hover me</Tooltip.Trigger>
+            <Tooltip.Content>Tooltip text</Tooltip.Content>
+          </Tooltip.Root>
+        </Tooltip.Provider>
+      );
+    }
+
+    const { rerender } = render(<Wrapper onOpenChange={firstOnOpenChange} />);
+    rerender(<Wrapper onOpenChange={secondOnOpenChange} />);
+
+    fireEvent.pointerEnter(screen.getByRole("button", { name: "Hover me" }));
+    fireEvent.pointerLeave(screen.getByRole("button", { name: "Hover me" }));
+
+    act(() => {
+      vi.advanceTimersByTime(100);
+    });
+
+    expect(firstOnOpenChange).not.toHaveBeenCalled();
+    expect(secondOnOpenChange).toHaveBeenCalledWith(true);
+    expect(secondOnOpenChange).toHaveBeenCalledWith(false);
+  });
+});

package/src/Tooltip/hooks/__tests__/useTooltipProvider.test.tsx

@@ -0,0 +1,40 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import { useTooltipProvider } from "../useTooltipProvider";
+
+/**
+ * `useTooltipProvider` schedules its skip-delay reset with a raw
+ * `setTimeout`, so it is exercised here directly rather than through the
+ * full `Tooltip.Provider` tree — the defect under test (a timer surviving
+ * unmount) has no user-facing render output to assert on.
+ */
+function Probe() {
+  const { contextValue } = useTooltipProvider({
+    delayDuration: 0,
+    skipDelayDuration: 300,
+  });
+  return <button onClick={contextValue.onCloseGlobally}>close</button>;
+}
+
+describe("useTooltipProvider — timer cleanup", () => {
+  it("clears the pending skip-delay timeout on unmount instead of letting it fire later", async () => {
+    const user = userEvent.setup();
+    const setTimeoutSpy = vi.spyOn(globalThis, "setTimeout");
+    const clearTimeoutSpy = vi.spyOn(globalThis, "clearTimeout");
+
+    const { unmount } = render(<Probe />);
+    await user.click(screen.getByRole("button", { name: "close" }));
+
+    // setTimeoutSpy also captures unrelated timers (userEvent's own
+    // scheduling, React internals) — find the one this hook scheduled with
+    // its 300ms skipDelayDuration.
+    const callIndex = setTimeoutSpy.mock.calls.findIndex(
+      ([, delay]) => delay === 300,
+    );
+    const timerId = setTimeoutSpy.mock.results[callIndex].value;
+    unmount();
+
+    expect(clearTimeoutSpy).toHaveBeenCalledWith(timerId);
+  });
+});

package/src/Tooltip/hooks/useTooltipContent.ts

@@ -29,6 +29,9 @@ export function useTooltipContent({
   useEffect(() => {
     if (!open) return;
     const handlePointerDown = (event: PointerEvent) => {
+      // Stryker disable next-line OptionalChaining: equivalent — this listener
+      // is only attached while `open` is true, and the Content `<div>` (and
+      // therefore internalRef.current) is always mounted whenever open is true.
       if (internalRef.current?.contains(event.target as Node)) return;
       onPointerDownOutside?.(event);
       if (event.defaultPrevented) return;

package/src/Tooltip/hooks/useTooltipProvider.ts

@@ -1,4 +1,4 @@
-import { useCallback, useRef, useState } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
 
 import type { TooltipProviderContextValue } from "../types";
 
@@ -14,21 +14,59 @@ export function useTooltipProvider({
   const [isOpenGlobally, setIsOpenGlobally] = useState(false);
   const skipDelayTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
 
-  const onOpenGlobally = useCallback(() => {
-    if (skipDelayTimerRef.current !== null) {
-      clearTimeout(skipDelayTimerRef.current);
-      skipDelayTimerRef.current = null;
-    }
-    setIsOpenGlobally(true);
-  }, []);
+  const onOpenGlobally = useCallback(
+    () => {
+      // Stryker disable next-line ConditionalExpression: equivalent —
+      // clearTimeout(null) is a spec'd no-op, so forcing this guard true is
+      // harmless when no skip-delay timer is pending; the false / never-clear
+      // variant is killed by the "clears a pending skip-delay timer when a
+      // tooltip opens again within the skip window" test.
+      if (skipDelayTimerRef.current !== null) {
+        clearTimeout(skipDelayTimerRef.current);
+        skipDelayTimerRef.current = null;
+      }
+      setIsOpenGlobally(true);
+    },
+    // Stryker disable next-line ArrayDeclaration: equivalent — no dependency to freeze.
+    [],
+  );
 
   const onCloseGlobally = useCallback(() => {
+    // Cancel before re-scheduling. The ref tracks only the newest timer, so
+    // overwriting it without cancelling orphans the previous one: it survives,
+    // fires unobserved, and can no longer be cancelled by a later open. Two
+    // closes in a row is not hypothetical — `closeImmediate` is unguarded and
+    // both Escape and blur are wired straight to it, so pressing Escape and then
+    // tabbing away leaks a timer. `clearTimeout(undefined)` is a spec'd no-op, so
+    // this needs no guard for the first close.
+    clearTimeout(skipDelayTimerRef.current ?? undefined);
     skipDelayTimerRef.current = setTimeout(() => {
       setIsOpenGlobally(false);
       skipDelayTimerRef.current = null;
     }, skipDelayDuration);
   }, [skipDelayDuration]);
 
+  // The skip-delay reset is a raw `setTimeout`, so it outlives the
+  // component it was scheduled from unless explicitly cancelled — without
+  // this, an in-flight timer fires after unmount and can throw once its
+  // surrounding environment (e.g. a test's jsdom `window`) is gone.
+  useEffect(
+    () => {
+      return () => {
+        // Stryker disable next-line ConditionalExpression: equivalent —
+        // clearTimeout(null) is a spec'd no-op, so forcing this guard true is
+        // harmless when no skip-delay timer is pending; the false / never-clear
+        // variant is killed by the "clears the pending skip-delay timeout on
+        // unmount" test.
+        if (skipDelayTimerRef.current !== null) {
+          clearTimeout(skipDelayTimerRef.current);
+        }
+      };
+    },
+    // Stryker disable next-line ArrayDeclaration: equivalent — no dependency to freeze (mount/unmount only).
+    [],
+  );
+
   const contextValue: TooltipProviderContextValue = {
     delayDuration,
     skipDelayDuration,

package/src/Tooltip/hooks/useTooltipRoot.ts

@@ -31,6 +31,11 @@ export function useTooltipRoot({
   const gracePeriodTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
 
   const openImmediate = useCallback(() => {
+    // Stryker disable next-line ConditionalExpression: equivalent —
+    // clearTimeout(null) is a spec'd no-op, so forcing this guard true is
+    // harmless when no open timer is pending; the false / never-clear variant
+    // is killed by the "cancels a pending hover-delay open timer when the
+    // trigger is focused before it elapses" test.
     if (openTimerRef.current !== null) {
       clearTimeout(openTimerRef.current);
       openTimerRef.current = null;
@@ -52,6 +57,11 @@ export function useTooltipRoot({
   }, [openImmediate, effectiveDelayDuration, providerCtx.isOpenGlobally]);
 
   const closeImmediate = useCallback(() => {
+    // Stryker disable next-line ConditionalExpression: equivalent —
+    // clearTimeout(null) is a spec'd no-op, so forcing this guard true is
+    // harmless when no grace timer is pending; the false / never-clear variant
+    // is killed by the "cancels a pending grace-period timer when the tooltip
+    // closes immediately during the grace window" test.
     if (gracePeriodTimerRef.current !== null) {
       clearTimeout(gracePeriodTimerRef.current);
       gracePeriodTimerRef.current = null;
@@ -60,14 +70,28 @@ export function useTooltipRoot({
     providerCtx.onCloseGlobally();
   }, [setOpen, providerCtx]);
 
-  const cancelGrace = useCallback(() => {
-    if (gracePeriodTimerRef.current !== null) {
-      clearTimeout(gracePeriodTimerRef.current);
-      gracePeriodTimerRef.current = null;
-    }
-  }, []);
+  const cancelGrace = useCallback(
+    () => {
+      // Stryker disable next-line ConditionalExpression: equivalent —
+      // clearTimeout(null) is a spec'd no-op, so forcing this guard true is
+      // harmless when no grace timer is pending; the false / never-clear
+      // variant is killed by the "cancels the grace-period close timer when
+      // the pointer moves into the content" test.
+      if (gracePeriodTimerRef.current !== null) {
+        clearTimeout(gracePeriodTimerRef.current);
+        gracePeriodTimerRef.current = null;
+      }
+    },
+    // Stryker disable next-line ArrayDeclaration: equivalent — no dependency to freeze.
+    [],
+  );
 
   const closeWithGrace = useCallback(() => {
+    // Stryker disable next-line ConditionalExpression: equivalent —
+    // clearTimeout(null) is a spec'd no-op, so forcing this guard true is
+    // harmless when no open timer is pending; the false / never-clear variant
+    // is killed by the "cancels a pending hover-delay open timer when the
+    // pointer leaves before it elapses" test.
     if (openTimerRef.current !== null) {
       clearTimeout(openTimerRef.current);
       openTimerRef.current = null;

package/src/Tooltip/types.ts

@@ -30,12 +30,26 @@ export type TooltipContextValue = {
 };
 
 /**
- * Props for {@link Tooltip.Provider} — sets the `delayDuration` and
- * `skipDelayDuration` shared by every tooltip in the subtree.
+ * Props for {@link Tooltip.Provider} — sets the delay timings shared by every
+ * tooltip in the subtree.
  */
 export type TooltipProviderProps = {
+  /** The tooltips (and other markup) that share this Provider's timings. */
   children?: ReactNode;
+  /**
+   * How long, in milliseconds, a pointer must rest on a trigger before the
+   * tooltip opens on hover. Focus always opens immediately regardless of this.
+   * Overridable per tooltip via {@link TooltipRootProps.delayDuration}.
+   * @default 700
+   */
   delayDuration?: number;
+  /**
+   * The grace window, in milliseconds, after a tooltip in this group closes
+   * during which hovering *another* trigger in the same Provider opens it
+   * instantly (no `delayDuration` wait). Rest longer than this and the next
+   * hover pays the full delay again.
+   * @default 300
+   */
   skipDelayDuration?: number;
 };
 
@@ -45,8 +59,16 @@ export type TooltipProviderProps = {
  * and `open` is forbidden.
  */
 export type UncontrolledTooltipRootProps = {
+  /**
+   * Whether the tooltip is open on first render. The component owns the flag
+   * from then on (hover/focus/blur/Escape drive it internally).
+   * @default false
+   */
   defaultOpen?: boolean;
+  /** Forbidden in uncontrolled mode — use `defaultOpen` instead. */
   open?: never;
+  /** Called with the new open state after every transition. Optional in
+   * uncontrolled mode; use it to observe (not drive) open/close. */
   onOpenChange?: (open: boolean) => void;
 };
 
@@ -56,8 +78,13 @@ export type UncontrolledTooltipRootProps = {
  * forbidden.
  */
 export type ControlledTooltipRootProps = {
+  /** The current open state. The delay and grace timers still run and call
+   * `onOpenChange`, but the tooltip only moves when the parent updates this. */
   open: boolean;
+  /** Called with the requested open state whenever the tooltip wants to open
+   * or close. Optional even in controlled mode. */
   onOpenChange?: (open: boolean) => void;
+  /** Forbidden in controlled mode — use `open` instead. */
   defaultOpen?: never;
 };
 
@@ -68,45 +95,99 @@ export type ControlledTooltipRootProps = {
  * so TypeScript accepts exactly one mode.
  */
 export type TooltipRootProps = {
+  /** The tooltip's {@link TooltipTriggerProps | `Tooltip.Trigger`},
+   * {@link TooltipContentProps | `Tooltip.Content`} (usually inside a
+   * {@link TooltipPortalProps | `Tooltip.Portal`}), and optional
+   * {@link TooltipArrowProps | `Tooltip.Arrow`}. */
   children?: ReactNode;
+  /**
+   * Overrides {@link TooltipProviderProps.delayDuration} for this tooltip only
+   * — the hover open delay in milliseconds. Falls back to the Provider's value
+   * when omitted.
+   */
   delayDuration?: number;
+  /**
+   * When `true`, removes the pointer-leave grace period: the tooltip closes the
+   * instant the pointer leaves the trigger, so the user cannot move into the
+   * content. Leave `false` for tooltips whose content is meant to be hovered.
+   * @default false
+   */
   disableHoverableContent?: boolean;
 } & (UncontrolledTooltipRootProps | ControlledTooltipRootProps);
 
 /**
  * Props for {@link Tooltip.Trigger} — all native `<button>` attributes plus
- * the `asChild` escape hatch.
+ * the `asChild` escape hatch. The `aria-describedby`, `data-state`, and the
+ * hover/focus/blur/Escape open-close handlers are added by the component
+ * (consumer handlers compose and run first).
  */
 export type TooltipTriggerProps = ComponentProps<"button"> & {
+  /**
+   * Render the single child element (a link, icon button, etc.) instead of the
+   * default `<button>`, merging the trigger's ARIA and event handlers onto it
+   * via the {@link Slot} pattern.
+   * @default false
+   */
   asChild?: boolean;
 };
 
 /**
  * Props for {@link Tooltip.Portal} — the `container` to render the content
- * into (defaults to `document.body`) and `forceMount` to keep the content
- * in the DOM while closed for exit animations.
+ * into and `forceMount` to keep the content in the DOM while closed for exit
+ * animations.
  */
 export type TooltipPortalProps = {
+  /** The content to portal — typically a single
+   * {@link TooltipContentProps | `Tooltip.Content`}. */
   children?: ReactNode;
+  /**
+   * The element to portal the content into.
+   * @default document.body
+   */
   container?: HTMLElement;
+  /**
+   * Keep the content mounted while the tooltip is closed (instead of removing
+   * it), so a CSS exit animation on `data-state="closed"` can play.
+   * @default false
+   */
   forceMount?: boolean;
 };
 
 /**
  * Props for {@link Tooltip.Content} — all native `<div>` attributes plus
- * `forceMount` and the dismissal callbacks fired on Escape
- * (`onEscapeKeyDown`) and outside pointer-down (`onPointerDownOutside`).
+ * `forceMount` and the dismissal escape hatches. The component adds
+ * `role="tooltip"`, the shared `id` (for the trigger's `aria-describedby`),
+ * the `data-state` hook, and the pointer handlers that cancel/allow the grace
+ * period close.
  */
 export type TooltipContentProps = ComponentProps<"div"> & {
+  /**
+   * Keep the content mounted while the tooltip is closed (instead of removing
+   * it), so a CSS exit animation on `data-state="closed"` can play.
+   * @default false
+   */
   forceMount?: boolean;
+  /**
+   * Fires when `Escape` is pressed while the tooltip is open. Call
+   * `event.preventDefault()` to keep the tooltip open; otherwise it closes.
+   */
   onEscapeKeyDown?: (event: KeyboardEvent) => void;
+  /**
+   * Fires on a pointer-down outside the content. Call `event.preventDefault()`
+   * to keep the tooltip open; otherwise it closes.
+   */
   onPointerDownOutside?: (event: PointerEvent) => void;
 };
 
 /**
  * Props for {@link Tooltip.Arrow} — all native `<span>` attributes plus the
- * `asChild` escape hatch.
+ * `asChild` escape hatch. Purely presentational; position and size it with CSS.
  */
 export type TooltipArrowProps = ComponentProps<"span"> & {
+  /**
+   * Render the single child element (e.g. an `<svg>`) instead of the default
+   * `<span>` via the {@link Slot} pattern.
+   * @default false
+   */
   asChild?: boolean;
 };

package/src/Tree/README.md

@@ -56,7 +56,7 @@ Passing both `default*` and the controlled prop is a type error.
 
 ```ts
 // Uncontrolled
-<Tree.Root defaultExpandedValues={["src"]} onExpandedChange={(v) => …}>
+<Tree.Root defaultExpandedValues={["src"]} onExpandedChange={(v) => ...}>
 
 // Controlled
 <Tree.Root expandedValues={values} onExpandedChange={setValues}>
@@ -70,14 +70,14 @@ The selection shape depends on `selectionMode`:
 
 ```ts
 // Single (default) — selectedValue is `string | null`
-<Tree.Root defaultSelectedValue="readme" onSelectedValueChange={(v) => …}>
+<Tree.Root defaultSelectedValue="readme" onSelectedValueChange={(v) => ...}>
 <Tree.Root selectedValue={v} onSelectedValueChange={setV}>
 
 // Multiple — selectedValues is `string[]`
 <Tree.Root
   selectionMode="multiple"
   defaultSelectedValues={["readme", "index"]}
-  onSelectedValuesChange={(v) => …}
+  onSelectedValuesChange={(v) => ...}
 >
 <Tree.Root
   selectionMode="multiple"
@@ -187,7 +187,7 @@ styles.
 > [role="treeitem"][data-depth="2"] > .row {
 >   padding-inline-start: 3rem;
 > }
-> /* …extend as deep as your tree can go */
+> /* ...extend as deep as your tree can go */
 > ```
 >
 > **2. Set a CSS variable inline from the render layer** — the
@@ -223,6 +223,70 @@ styles.
 > }
 > ```
 
+## Wrapping Tree in a styled layer
+
+`Tree.Branch` finds its control and content by **inspecting its children before
+rendering them**, so it sees the component you wrote — not what that component
+renders. A styling layer that wraps each part in its own component to attach
+classes is therefore invisible to it, and the branch throws:
+
+```
+A Tree.Branch must contain a <Tree.BranchControl>.
+```
+
+Set `TREE_PART` on the wrapper and it partitions like the part it renders:
+
+```tsx
+import { TREE_PART, Tree } from "@primitiv-ui/react";
+
+function StyledBranchControl(props: TreeBranchControlProps) {
+  return <Tree.BranchControl {...props} className="row" />;
+}
+StyledBranchControl[TREE_PART] = "branch-control";
+
+function StyledBranchContent(props: TreeBranchContentProps) {
+  return <Tree.BranchContent {...props} className="group" />;
+}
+StyledBranchContent[TREE_PART] = "branch-content";
+```
+
+The accepted names are `"branch-control"` and `"branch-content"`
+(`TreePartName`). Only these two parts need it — every other part is found by
+position or context, not by inspection. The one-control and one-content rules
+still apply: two marked controls in a branch is still an error.
+
+This is what the registry `tree` component does; no other primitive in the
+library needs a marker, because none of the others read their children's types.
+
+### Indenting without `attr()`
+
+`useTreeLevel()` returns `{ depth }` — `0` directly under `Tree.Root`, one
+deeper per enclosing `BranchContent`. A styling layer needs the depth as a
+*number* to apply the indent as the **row's own padding**, which is what keeps
+each row's box full-width so a hover or selected band runs edge to edge rather
+than starting at the nested level. Reading `data-depth` back in CSS would need
+`attr(data-depth type(<integer>))` — Chrome 133+ / Safari 18.2+, unsupported in
+Firefox — so the depth is exposed here instead.
+
+```tsx
+function StyledItem(props: TreeItemProps) {
+  const { depth } = useTreeLevel();
+  return (
+    <Tree.Item
+      {...props}
+      style={{ "--depth": depth } as CSSProperties}
+      className="row"
+    />
+  );
+}
+```
+
+```css
+.row {
+  padding-inline-start: calc(var(--depth, 0) * 1.25rem + 0.5rem);
+}
+```
+
 ## Selection path
 
 `Tree.Item` and `Tree.Branch` accept an optional `label` prop. It does
@@ -256,7 +320,7 @@ import { Tree } from "@primitiv-ui/react";
 import { ChevronRight } from "@primitiv-ui/icons";
 
 <Tree.Root defaultSelectedValue="index">
-  …
+  ...
   <Tree.SelectionPath separator={<ChevronRight />} />
 </Tree.Root>;
 ```