@primitiv-ui/react 0.1.28 → 0.1.30

package/src/ToggleGroup/ToggleGroup.tsx

@@ -46,6 +46,8 @@ import { ToggleGroupItemProps, ToggleGroupRootProps } from "./types";
  * element in place of the native `<div>`, with the group's `role`,
  * `data-orientation`, and ref merged in.
  *
+ * @extends HTMLDivElement
+ *
  * @example Single mode — text alignment
  * ```tsx
  * <ToggleGroup.Root type="single" defaultValue="left" aria-label="Alignment">
@@ -140,6 +142,7 @@ export function ToggleGroupRoot({
 }
 
 /** @internal */
+// Stryker disable next-line StringLiteral: overwritten by the compound alias — an equivalent mutant.
 ToggleGroupRoot.displayName = "ToggleGroupRoot";
 
 /**
@@ -165,9 +168,19 @@ ToggleGroupRoot.displayName = "ToggleGroupRoot";
  *
  * **`asChild` prop.** Pass `asChild` to render any consumer element in
  * place of the native `<button>`, with the Item's `aria-pressed`,
- * `data-state`, `tabIndex`, and event handlers merged onto it.
+ * `data-state`, `tabIndex`, and event handlers merged onto it. The child
+ * must accept a `ref`. Useful for a link or a styled control that needs
+ * toggle-button semantics.
  *
  * @throws if rendered outside a `ToggleGroup.Root`.
+ *
+ * @extends HTMLButtonElement
+ *
+ * @example
+ * ```tsx
+ * <ToggleGroup.Item value="bold">Bold</ToggleGroup.Item>
+ * <ToggleGroup.Item value="strike" disabled>Strikethrough</ToggleGroup.Item>
+ * ```
  */
 export function ToggleGroupItem({
   value,

package/src/ToggleGroup/__tests__/ToggleGroup.asChild.test.tsx

@@ -62,4 +62,24 @@ describe("ToggleGroup asChild composition", () => {
     expect(consumerClick).toHaveBeenCalledOnce();
     expect(item).toHaveAttribute("aria-pressed", "true");
   });
+
+  it("Item asChild activates on Space through the keyboard handler", async () => {
+    // A non-button element fires no native click on Space, so toggling can
+    // only come from the roving handler's activate mapping — the guarantee a
+    // native <button> would otherwise mask.
+    const user = userEvent.setup();
+    render(
+      <ToggleGroup.Root type="single" aria-label="Alignment">
+        <ToggleGroup.Item value="left" asChild>
+          <div>Left</div>
+        </ToggleGroup.Item>
+      </ToggleGroup.Root>,
+    );
+    const item = screen
+      .getByLabelText("Alignment")
+      .querySelector<HTMLElement>("[data-state]")!;
+    item.focus();
+    await user.keyboard(" ");
+    expect(item).toHaveAttribute("aria-pressed", "true");
+  });
 });

package/src/ToggleGroup/__tests__/ToggleGroup.basic-rendering.test.tsx

@@ -47,4 +47,13 @@ describe("ToggleGroup basic rendering", () => {
       "horizontal",
     );
   });
+
+  it("sets a displayName on the compound and Item", () => {
+    // Assert — empty displayNames would render each as anonymous in DevTools.
+    // `ToggleGroup`, `ToggleGroup.Root`, and the underlying function are one
+    // object (Object.assign compound), so the compound's "ToggleGroup" alias is
+    // the observable Root displayName; only Item is a distinct object.
+    expect(ToggleGroup.displayName).toBe("ToggleGroup");
+    expect(ToggleGroup.Item.displayName).toBe("ToggleGroupItem");
+  });
 });

package/src/ToggleGroup/__tests__/ToggleGroup.dynamic-items.test.tsx

@@ -0,0 +1,70 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import { ToggleGroup } from "../ToggleGroup";
+
+function ItemsFixture({ items }: { items: string[] }) {
+  return (
+    <ToggleGroup.Root type="single" aria-label="Alignment">
+      {items.map((v) => (
+        <ToggleGroup.Item key={v} value={v}>
+          {v}
+        </ToggleGroup.Item>
+      ))}
+    </ToggleGroup.Root>
+  );
+}
+
+function DisabledFixture({ disabledItem }: { disabledItem?: string }) {
+  return (
+    <ToggleGroup.Root type="single" aria-label="Alignment">
+      <ToggleGroup.Item value="left" disabled={disabledItem === "left"}>
+        Left
+      </ToggleGroup.Item>
+      <ToggleGroup.Item value="center" disabled={disabledItem === "center"}>
+        Center
+      </ToggleGroup.Item>
+      <ToggleGroup.Item value="right" disabled={disabledItem === "right"}>
+        Right
+      </ToggleGroup.Item>
+    </ToggleGroup.Root>
+  );
+}
+
+describe("ToggleGroup dynamic items — registration lifecycle", () => {
+  it("unregisters an unmounted item so the tab stop moves to the survivor", () => {
+    // Arrange — "a" is the first enabled item, so it holds the tab stop.
+    const { rerender } = render(<ItemsFixture items={["a", "b"]} />);
+    expect(screen.getByRole("button", { name: "a" })).toHaveAttribute(
+      "tabindex",
+      "0",
+    );
+
+    // Act — remove "a"; its effect cleanup must unregister it.
+    rerender(<ItemsFixture items={["b"]} />);
+
+    // Assert — with "a" gone from the registry, "b" is now the tab stop. A
+    // no-op cleanup would leave "a" registered ahead of "b", stranding the
+    // tab stop on the detached element and leaving "b" at tabindex -1.
+    expect(screen.getByRole("button", { name: "b" })).toHaveAttribute(
+      "tabindex",
+      "0",
+    );
+  });
+
+  it("re-registers an item's disabled flag when it changes after mount", async () => {
+    // Arrange — all three enabled; focus can travel Left → Center → Right.
+    const user = userEvent.setup();
+    const { rerender } = render(<DisabledFixture />);
+
+    // Act — disable Center after mount, then navigate rightward from Left.
+    rerender(<DisabledFixture disabledItem="center" />);
+    screen.getByRole("button", { name: "Left" }).focus();
+    await user.keyboard("{ArrowRight}");
+
+    // Assert — the registrar effect re-ran, so Center is skipped and focus
+    // lands on Right. A stale registration would keep Center navigable and
+    // strand focus (a disabled button cannot receive it).
+    expect(screen.getByRole("button", { name: "Right" })).toHaveFocus();
+  });
+});

package/src/ToggleGroup/__tests__/ToggleGroup.error-handling.test.tsx

@@ -0,0 +1,23 @@
+import { render } from "@testing-library/react";
+
+import { ToggleGroup } from "../ToggleGroup";
+import { ToggleGroupContext } from "../ToggleGroupContext";
+
+describe("ToggleGroup error handling", () => {
+  it("throws a helpful error when ToggleGroup.Item is rendered outside Root", () => {
+    // Arrange
+    const error = vi.spyOn(console, "error").mockImplementation(() => {});
+
+    // Assert
+    expect(() =>
+      render(<ToggleGroup.Item value="left">Left</ToggleGroup.Item>),
+    ).toThrow(/ToggleGroup\.Item must be rendered inside a ToggleGroup\.Root/);
+
+    error.mockRestore();
+  });
+
+  it("names the context for React DevTools", () => {
+    // Assert — an empty displayName would render the provider as anonymous.
+    expect(ToggleGroupContext.displayName).toBe("ToggleGroupContext");
+  });
+});

package/src/ToggleGroup/__tests__/ToggleGroup.keyboard-interaction.test.tsx

@@ -1,4 +1,4 @@
-import { render, screen } from "@testing-library/react";
+import { fireEvent, render, screen } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 
 import { ToggleGroup } from "../ToggleGroup";
@@ -45,6 +45,28 @@ describe("ToggleGroup keyboard — roving tabindex", () => {
       "-1",
     );
   });
+
+  it("moves the tab stop to the focused item (onFocus updates the home base)", () => {
+    // Arrange — nothing selected, so the first item is the initial tab stop.
+    render(<SingleFixture />);
+    expect(screen.getByRole("button", { name: "Left" })).toHaveAttribute(
+      "tabindex",
+      "0",
+    );
+
+    // Act — focusing another item should hand it the tab stop.
+    fireEvent.focus(screen.getByRole("button", { name: "Right" }));
+
+    // Assert — Right is now the sole tab stop; Left drops out of the sequence.
+    expect(screen.getByRole("button", { name: "Right" })).toHaveAttribute(
+      "tabindex",
+      "0",
+    );
+    expect(screen.getByRole("button", { name: "Left" })).toHaveAttribute(
+      "tabindex",
+      "-1",
+    );
+  });
 });
 
 describe("ToggleGroup keyboard — arrow key navigation (no auto-select)", () => {

package/src/ToggleGroup/__tests__/ToggleGroup.ref-forwarding.test.tsx

@@ -0,0 +1,58 @@
+import { render, screen } from "@testing-library/react";
+
+import { ToggleGroup } from "../ToggleGroup";
+
+describe("ToggleGroup.Item ref forwarding", () => {
+  it("forwards the underlying button element to a consumer function ref", () => {
+    // Arrange
+    const received: (HTMLButtonElement | null)[] = [];
+    const functionRef = (node: HTMLButtonElement | null) => {
+      received.push(node);
+    };
+
+    // Act
+    render(
+      <ToggleGroup.Root type="single" aria-label="Alignment">
+        <ToggleGroup.Item value="left" ref={functionRef}>
+          Left
+        </ToggleGroup.Item>
+      </ToggleGroup.Root>,
+    );
+
+    // Assert
+    expect(received).toContain(screen.getByRole("button", { name: "Left" }));
+  });
+
+  it("re-attaches to a replacement ref when the ref prop changes", () => {
+    // Arrange — the item's ref memo must depend on `ref`, or a changed ref
+    // callback is never invoked with the element.
+    const firstReceived: (HTMLButtonElement | null)[] = [];
+    const secondReceived: (HTMLButtonElement | null)[] = [];
+    const firstRef = (node: HTMLButtonElement | null) => {
+      firstReceived.push(node);
+    };
+    const secondRef = (node: HTMLButtonElement | null) => {
+      secondReceived.push(node);
+    };
+
+    // Act — mount with the first ref, then re-render with a different one.
+    const { rerender } = render(
+      <ToggleGroup.Root type="single" aria-label="Alignment">
+        <ToggleGroup.Item value="left" ref={firstRef}>
+          Left
+        </ToggleGroup.Item>
+      </ToggleGroup.Root>,
+    );
+    rerender(
+      <ToggleGroup.Root type="single" aria-label="Alignment">
+        <ToggleGroup.Item value="left" ref={secondRef}>
+          Left
+        </ToggleGroup.Item>
+      </ToggleGroup.Root>,
+    );
+
+    // Assert — the replacement ref received the button.
+    const button = screen.getByRole("button", { name: "Left" });
+    expect(secondReceived).toContain(button);
+  });
+});

package/src/ToggleGroup/hooks/useToggleGroupRoot.ts

@@ -42,7 +42,16 @@ export function useToggleGroupRoot({
     (itemValue: string) => {
       const isSelected = value.includes(itemValue);
       if (type === "single") {
-        const next = isSelected ? [] : [itemValue];
+        // Deselecting clears the selection to the empty array. Stryker's
+        // ArrayDeclaration mutant fills this with a phantom value, but since
+        // that value can never equal a registered item's `value` — and single
+        // mode always overwrites the whole array on the next selection — no
+        // item ever reads it as pressed. The mutation is observationally
+        // identical, so it is isolated here to keep the disable off the tested
+        // `[itemValue]` literal below.
+        // Stryker disable next-line ArrayDeclaration
+        const cleared: string[] = [];
+        const next = isSelected ? cleared : [itemValue];
         setValue(next);
         (onValueChange as ((v: string | undefined) => void) | undefined)?.(
           isSelected ? undefined : itemValue,
@@ -68,6 +77,9 @@ export function useToggleGroupRoot({
     (itemValue: string, element: HTMLButtonElement | null, disabled = false) => {
       registerBase(itemValue, element ? { element, disabled } : null);
     },
+    // `registerBase` is a stable useCollection callback (its own deps never
+    // change), so emptying this array yields the identical memoised function.
+    // Stryker disable next-line ArrayDeclaration: equivalent — stable dependency.
     [registerBase],
   );
 
@@ -83,8 +95,16 @@ export function useToggleGroupRoot({
 
   const focusItem = useCallback(
     (itemValue: string) => {
+      // `itemValue` is always sourced from `navigable` (the enabled subset of
+      // `itemValues`), and useCollection's register() writes `itemsRef` and the
+      // `itemValues` state together — so a value that reaches here is guaranteed
+      // to have a live entry in the map.
+      // Stryker disable next-line OptionalChaining: unreachable given that invariant.
       itemsRef.current.get(itemValue)?.element.focus();
     },
+    // `itemsRef` is a stable RefObject, so emptying this array yields the
+    // identical memoised function.
+    // Stryker disable next-line ArrayDeclaration: equivalent — stable dependency.
     [itemsRef],
   );
 

package/src/ToggleGroup/types.ts

@@ -7,12 +7,27 @@ import { HTMLAttributes, ButtonHTMLAttributes, ReactNode, Ref } from "react";
  */
 export type ToggleGroupRootBaseProps = Omit<
   HTMLAttributes<HTMLDivElement>,
-  "dir"
+  "dir" | "defaultValue"
 > & {
+  /** Layout axis for keyboard navigation. `"horizontal"` binds
+   * ArrowLeft/ArrowRight; `"vertical"` binds ArrowUp/ArrowDown. Surfaces as
+   * `data-orientation` on the root for styling; it does not itself apply any
+   * flex/grid layout.
+   * @default "horizontal" */
   orientation?: "horizontal" | "vertical";
+  /** Reading direction. In `"rtl"` the horizontal arrow keys are mirrored so
+   * focus follows the visual order. Inherited from the nearest
+   * {@link DirectionProvider} when omitted, falling back to `"ltr"`. */
   dir?: "ltr" | "rtl";
+  /** Render a single consumer-supplied element in place of the native
+   * `<div>`, with the group's `role="group"`, `data-orientation`, and `ref`
+   * merged onto it via the {@link Slot} pattern.
+   * @default false */
   asChild?: boolean;
+  /** The {@link ToggleGroupItemProps | `ToggleGroup.Item`} elements that make
+   * up the segmented control. */
   children?: ReactNode;
+  /** Forwarded to the underlying `HTMLDivElement`. */
   ref?: Ref<HTMLDivElement>;
 };
 
@@ -21,9 +36,15 @@ export type ToggleGroupRootBaseProps = Omit<
  * initial value supplied via `defaultValue`.
  */
 export type SingleUncontrolledProps = {
+  /** Selects single-selection semantics: at most one item pressed at a time,
+   * and pressing the active item again clears the selection. */
   type: "single";
+  /** Value of the item pressed on first render. Omit to start with nothing
+   * pressed. */
   defaultValue?: string;
+  /** Forbidden in uncontrolled mode — use `defaultValue`. */
   value?: never;
+  /** Forbidden in uncontrolled mode. */
   onValueChange?: never;
 };
 
@@ -32,9 +53,16 @@ export type SingleUncontrolledProps = {
  * caller via `value` / `onValueChange`.
  */
 export type SingleControlledProps = {
+  /** Selects single-selection semantics: at most one item pressed at a time,
+   * and pressing the active item again clears the selection. */
   type: "single";
+  /** The currently pressed item's value, or `undefined` when none is pressed.
+   * Must be kept in sync by the caller via `onValueChange`. */
   value: string | undefined;
+  /** Called with the requested next value — the pressed item's value, or
+   * `undefined` when the active item is pressed again to deselect it. */
   onValueChange: (value: string | undefined) => void;
+  /** Forbidden in controlled mode — use `value`. */
   defaultValue?: never;
 };
 
@@ -43,9 +71,15 @@ export type SingleControlledProps = {
  * the initial set supplied via `defaultValue`.
  */
 export type MultipleUncontrolledProps = {
+  /** Selects multiple-selection semantics: any number of items can be pressed
+   * simultaneously and each toggles independently. */
   type: "multiple";
+  /** Values of the items pressed on first render. Omit to start with nothing
+   * pressed. */
   defaultValue?: string[];
+  /** Forbidden in uncontrolled mode — use `defaultValue`. */
   value?: never;
+  /** Forbidden in uncontrolled mode. */
   onValueChange?: never;
 };
 
@@ -54,9 +88,16 @@ export type MultipleUncontrolledProps = {
  * by the caller via `value` / `onValueChange`.
  */
 export type MultipleControlledProps = {
+  /** Selects multiple-selection semantics: any number of items can be pressed
+   * simultaneously and each toggles independently. */
   type: "multiple";
+  /** The full set of currently pressed item values. Must be kept in sync by
+   * the caller via `onValueChange`. */
   value: string[];
+  /** Called with the complete next array of pressed values whenever the user
+   * toggles any item. */
   onValueChange: (value: string[]) => void;
+  /** Forbidden in controlled mode — use `value`. */
   defaultValue?: never;
 };
 
@@ -81,11 +122,23 @@ export type ToggleGroupRootProps = ToggleGroupRootBaseProps &
  */
 export type ToggleGroupItemProps = Omit<
   ButtonHTMLAttributes<HTMLButtonElement>,
-  "type"
+  "type" | "value"
 > & {
+  /** Identifies this item within the group. It is this string — not the
+   * visible label — that is compared against the group's pressed
+   * `value` / `defaultValue`; use `children` for the label. */
   value: string;
+  /** Forwards the native `disabled` attribute and removes the item from the
+   * roving tab order so arrow-key navigation skips it. Also sets
+   * `data-disabled=""` for CSS targeting.
+   * @default false */
   disabled?: boolean;
+  /** Render a single consumer-supplied element in place of the native
+   * `<button>`, with the item's `aria-pressed`, `data-state`, `tabIndex`, and
+   * event handlers merged onto it via the {@link Slot} pattern.
+   * @default false */
   asChild?: boolean;
+  /** Forwarded to the underlying `HTMLButtonElement`. */
   ref?: Ref<HTMLButtonElement>;
 };
 

package/src/Tooltip/README.md

@@ -60,12 +60,12 @@ The two shapes are statically discriminated at the type level.
 
 ```tsx
 // Uncontrolled
-<Tooltip.Root defaultOpen>…</Tooltip.Root>
+<Tooltip.Root defaultOpen>...</Tooltip.Root>
 
 // Controlled
 const [open, setOpen] = useState(false);
 <Tooltip.Root open={open} onOpenChange={setOpen}>
-  …
+  ...
 </Tooltip.Root>
 ```
 
@@ -82,7 +82,7 @@ before the normal delay resumes.
 
 ```tsx
 <Tooltip.Provider delayDuration={400} skipDelayDuration={150}>
-  …
+  ...
 </Tooltip.Provider>
 ```
 
@@ -95,7 +95,7 @@ when the cursor leaves the trigger:
 
 ```tsx
 <Tooltip.Root disableHoverableContent>
-  …
+  ...
 </Tooltip.Root>
 ```
 
@@ -114,7 +114,7 @@ tooltip open:
     event.preventDefault(); // keep open when clicking outside
   }}
 >
-  …
+  ...
 </Tooltip.Content>
 ```
 
@@ -178,7 +178,7 @@ subtree stays in the DOM while closed so a CSS animation can play on
 
 ```tsx
 <Tooltip.Portal forceMount>
-  <Tooltip.Content forceMount>…</Tooltip.Content>
+  <Tooltip.Content forceMount>...</Tooltip.Content>
 </Tooltip.Portal>
 ```
 
@@ -199,7 +199,7 @@ child element; the child's own handlers run first.
 </Tooltip.Trigger>
 
 <Tooltip.Arrow asChild>
-  <svg viewBox="0 0 10 5">…</svg>
+  <svg viewBox="0 0 10 5">...</svg>
 </Tooltip.Arrow>
 ```
 

package/src/Tooltip/Tooltip.tsx

@@ -24,11 +24,27 @@ import type {
 } from "./types";
 
 /**
- * Wraps one or more `Tooltip.Root` instances and provides shared
- * delay configuration. Required ancestor — rendering `Tooltip.Root`
- * without a Provider throws a context error.
+ * Wraps one or more {@link TooltipRoot | `Tooltip.Root`} instances and provides
+ * the shared delay configuration and group-wide open coordination. Required
+ * ancestor — rendering `Tooltip.Root` without a Provider throws a context
+ * error. Renders no DOM of its own (a `TooltipProviderContext` provider only).
  *
- * @example
+ * **Delay coordination.** Two timings govern how a group of tooltips feels:
+ *
+ * - `delayDuration` — how long a pointer must rest on a trigger before its
+ *   tooltip opens (hover only; focus always opens immediately).
+ * - `skipDelayDuration` — the grace window after a tooltip closes during which
+ *   moving to *another* trigger in the same Provider opens that tooltip
+ *   instantly, with no `delayDuration` wait. Rest longer than this window and
+ *   the next hover pays the full `delayDuration` again. This is what makes a
+ *   toolbar of icon buttons feel responsive once the first tip has shown.
+ *
+ * Place a single Provider high in the tree (typically at the app root) so every
+ * tooltip shares one skip window. A per-instance
+ * {@link TooltipRootProps.delayDuration | `delayDuration`} on `Tooltip.Root`
+ * overrides the Provider's value for that one tooltip.
+ *
+ * @example App-wide provider
  * ```tsx
  * <Tooltip.Provider delayDuration={400}>
  *   <App />
@@ -55,13 +71,27 @@ export function TooltipProviderComponent({
 TooltipProviderComponent.displayName = "TooltipProvider";
 
 /**
- * The state boundary for a single tooltip. Owns the open/closed
- * state and wires it down to all sub-components via context.
+ * The state boundary for a single tooltip. Owns the open/closed state, runs the
+ * open-delay and grace-period timers, and wires everything down to the
+ * sub-components via `TooltipContext`. Renders no DOM of its own. Must be a
+ * descendant of {@link TooltipProviderComponent | `Tooltip.Provider`}.
  *
- * Supports two state modes, statically discriminated at the type level:
+ * **Controlled vs uncontrolled**, statically discriminated at the type level so
+ * TypeScript accepts only one shape:
  *
- * - **Uncontrolled** — pass `defaultOpen` or omit for closed-on-mount.
- * - **Controlled** — pass `open` (and optionally `onOpenChange`).
+ * - **Uncontrolled** — pass {@link UncontrolledTooltipRootProps.defaultOpen | `defaultOpen`}
+ *   (or omit it for closed-on-mount). The component owns the flag; observe
+ *   transitions with `onOpenChange`.
+ * - **Controlled** — pass {@link ControlledTooltipRootProps.open | `open`}
+ *   (with an optional `onOpenChange`). The parent owns the flag; the delay and
+ *   grace timers still run and drive `onOpenChange`, but the tooltip only moves
+ *   when the parent updates `open`.
+ *
+ * **Timing overrides.** {@link TooltipRootProps.delayDuration | `delayDuration`}
+ * overrides the Provider's open delay for this tooltip only.
+ * {@link TooltipRootProps.disableHoverableContent | `disableHoverableContent`}
+ * removes the grace period, so the tooltip closes the instant the pointer
+ * leaves the trigger (the user cannot move into the content).
  *
  * @example
  * ```tsx
@@ -90,17 +120,28 @@ export function TooltipRoot({
   return <TooltipProvider value={contextValue}>{children}</TooltipProvider>;
 }
 
-/** @internal */
+// Stryker disable next-line StringLiteral: overwritten by the compound alias — an equivalent mutant.
 TooltipRoot.displayName = "TooltipRoot";
 
 /**
- * The element that triggers the tooltip on hover and focus. Renders a
- * `<button type="button">` by default; use `asChild` to wrap a custom
- * element.
+ * The element that opens the tooltip. Renders a `<button type="button">` by
+ * default; pass `asChild` to project the trigger behaviour onto a custom
+ * element (a link, an icon button, etc.).
+ *
+ * **Open / close behaviour.** Pointer-enter opens after the effective
+ * `delayDuration` (immediately if the group's skip window is active);
+ * pointer-leave closes after a short grace period so the pointer can travel
+ * into hoverable content (immediately when `disableHoverableContent` is set on
+ * Root). Focus opens immediately and blur closes immediately, and `Escape`
+ * while focused closes immediately — matching the WAI-ARIA tooltip pattern.
+ * Consumer `onPointerEnter` / `onPointerLeave` / `onFocus` / `onBlur` /
+ * `onKeyDown` all compose (they run first).
+ *
+ * **ARIA wiring.**
+ * - `aria-describedby` points at {@link TooltipContent | `Tooltip.Content`}'s id.
+ * - `data-state="open" | "closed"` mirrors the tooltip state for CSS.
  *
- * ARIA wiring:
- * - `aria-describedby` points at `Tooltip.Content`'s id.
- * - `data-state="open" | "closed"` mirrors the tooltip state.
+ * @extends HTMLButtonElement
  *
  * @example
  * ```tsx
@@ -148,12 +189,13 @@ TooltipTrigger.displayName = "TooltipTrigger";
  *
  * By default the portal only renders while the tooltip is open. Pass
  * `forceMount` to keep the subtree mounted when closed — useful for
- * CSS exit animations driven by `data-state="closed"`.
+ * CSS exit animations driven by `data-state="closed"`. Renders no wrapper
+ * element of its own.
  *
  * @example
  * ```tsx
  * <Tooltip.Portal>
- *   <Tooltip.Content>…</Tooltip.Content>
+ *   <Tooltip.Content>...</Tooltip.Content>
  * </Tooltip.Portal>
  * ```
  */
@@ -192,6 +234,8 @@ TooltipPortal.displayName = "TooltipPortal";
  * `anchor-name` to the trigger and `position-anchor` / `position-area`
  * to the content in your own stylesheet.
  *
+ * @extends HTMLDivElement
+ *
  * @example
  * ```tsx
  * <Tooltip.Content className="tooltip__content">
@@ -233,6 +277,8 @@ TooltipContent.displayName = "TooltipContent";
  *
  * All positioning and styling is the consumer's responsibility via CSS.
  *
+ * @extends HTMLSpanElement
+ *
  * @example
  * ```tsx
  * <Tooltip.Content>
@@ -270,11 +316,43 @@ export type TooltipCompound = typeof TooltipRoot & {
  * Headless, accessible **Tooltip** — a compound component implementing the
  * [WAI-ARIA tooltip pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/):
  * a deferred, hoverable label anchored to a trigger, with a shared
- * {@link Tooltip.Provider} governing open / skip delays across a group. Zero
- * styles ship.
+ * {@link TooltipProviderComponent | `Tooltip.Provider`} governing open / skip
+ * delays across a group. Opens on hover (after a delay) and on focus
+ * (immediately); closes on blur, on `Escape`, and after a short grace period on
+ * pointer-leave so the pointer can travel into hoverable content. Zero styles
+ * ship; visual placement is your CSS concern (CSS anchor positioning).
+ *
+ * `Tooltip` is both callable (an alias of {@link TooltipRoot | `Tooltip.Root`})
+ * and carries its sub-components as static properties. A `Tooltip.Provider`
+ * ancestor is required — `Tooltip.Root` throws without one.
+ *
+ * - {@link TooltipProviderComponent | `Tooltip.Provider`} — shared delay config + group open coordination.
+ * - {@link TooltipRoot | `Tooltip.Root`} — per-tooltip state owner and timing.
+ * - {@link TooltipTrigger | `Tooltip.Trigger`} — `<button>` that opens on hover/focus.
+ * - {@link TooltipPortal | `Tooltip.Portal`} — optional portal to `document.body`.
+ * - {@link TooltipContent | `Tooltip.Content`} — the `role="tooltip"` panel.
+ * - {@link TooltipArrow | `Tooltip.Arrow`} — optional visual pointer.
+ *
+ * @example Minimal usage
+ * ```tsx
+ * import { Tooltip } from "@primitiv-ui/react";
+ *
+ * <Tooltip.Provider>
+ *   <Tooltip.Root>
+ *     <Tooltip.Trigger>Save</Tooltip.Trigger>
+ *     <Tooltip.Portal>
+ *       <Tooltip.Content>
+ *         Save your changes
+ *         <Tooltip.Arrow />
+ *       </Tooltip.Content>
+ *     </Tooltip.Portal>
+ *   </Tooltip.Root>
+ * </Tooltip.Provider>;
+ * ```
  *
- * The default export is the `Root`; sub-components are attached as static
- * properties (`Tooltip.Provider`, `Tooltip.Trigger`, `Tooltip.Content`, …).
+ * @see {@link TooltipProviderComponent} for delay / skip-delay coordination.
+ * @see {@link TooltipRoot} for the controlled/uncontrolled state modes and timing overrides.
+ * @see {@link TooltipContent} for the grace period and the Escape / outside-pointer escape hatches.
  */
 const TooltipCompound: TooltipCompound = Object.assign(TooltipRoot, {
   Provider: TooltipProviderComponent,