@primitiv-ui/react 0.1.28 → 0.1.29

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

@@ -115,4 +115,9 @@ describe("Input basic rendering", () => {
     // Assert
     expect(onChange).toHaveBeenCalledTimes(2);
   });
+
+  it('sets displayName to "Input" for React DevTools and stack traces', () => {
+    // Assert — an empty displayName would render it as an anonymous component.
+    expect(Input.displayName).toBe("Input");
+  });
 });

package/src/Input/types.ts

@@ -1,11 +1,28 @@
 import { ComponentProps, ReactNode, Ref } from "react";
 
 /**
- * Props for {@link Input} — all native `<input>` attributes plus the
- * `asChild` escape hatch and a typed `ref`.
+ * Props for {@link Input} — all native `<input>` attributes (with `type`
+ * defaulting to `"text"`) plus the `asChild` escape hatch and a typed `ref`.
  */
 export type InputProps = ComponentProps<"input"> & {
+  /**
+   * Renders the child element instead of a native `<input>`, merging all
+   * props — `aria-*`, `data-*`, event handlers, `ref` — onto it via
+   * {@link Slot}. Event handlers compose (child runs first). `type` is
+   * not forwarded in this mode; the child owns its own type semantics.
+   * See the `asChild` example on {@link Input}.
+   * @default false
+   */
   asChild?: boolean;
+  /**
+   * Forwarded to the underlying `HTMLInputElement`. Under `asChild`,
+   * merged onto the rendered child via {@link Slot}.
+   */
   ref?: Ref<HTMLInputElement>;
+  /**
+   * Under `asChild`, becomes the single child element `Slot` merges props
+   * onto. Not rendered by the native `<input>` path (inputs are void
+   * elements in HTML).
+   */
   children?: ReactNode;
 };

package/src/InputGroup/InputGroup.tsx

@@ -19,6 +19,8 @@ import { InputGroupAdornmentProps, InputGroupRootProps } from "./types";
  * element instead of `<div>` — e.g. a `<label>` so a click anywhere on
  * the frame focuses the wrapped input.
  *
+ * @extends HTMLDivElement
+ *
  * @example Basic frame with no adornments
  * ```tsx
  * <InputGroup>
@@ -56,6 +58,7 @@ export function InputGroupRoot({
 }
 
 /** @internal */
+// Stryker disable next-line StringLiteral: overwritten by the compound alias — an equivalent mutant.
 InputGroupRoot.displayName = "InputGroupRoot";
 
 /**
@@ -76,6 +79,8 @@ InputGroupRoot.displayName = "InputGroupRoot";
  * search, opens a colour picker, or any other action. Event handlers
  * compose (child runs first); refs forward to the consumer element.
  *
+ * @extends HTMLSpanElement
+ *
  * @example Decorative leading icon
  * ```tsx
  * <InputGroup.LeadingAdornment>
@@ -131,6 +136,8 @@ InputGroupLeadingAdornment.displayName = "InputGroupLeadingAdornment";
  * element such as `<button>`. Event handlers compose (child runs
  * first); refs forward to the consumer element.
  *
+ * @extends HTMLSpanElement
+ *
  * @example Trailing clear button via asChild
  * ```tsx
  * <InputGroup.TrailingAdornment asChild>
@@ -191,9 +198,10 @@ export type TInputGroupCompound = typeof InputGroupRoot & {
  *   trailing slot, `data-input-group-adornment="trailing"`.
  *
  * **State coordination.** None. CSS handles disabled / invalid /
- * focus-within styling via `:has()` and `:focus-within`. When `Field`
- * lands it will sit *outside* `InputGroup` and own label / error /
- * description wiring without InputGroup needing to change.
+ * focus-within styling via `:has()` and `:focus-within`. {@link Field}
+ * sits *outside* `InputGroup` and owns the label / error / description
+ * wiring, so the two compose without `InputGroup` needing to know about
+ * it — wrap the `Input` in an `InputGroup` inside a `Field.Root`.
  *
  * @example Leading search icon
  * ```tsx

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

@@ -103,4 +103,18 @@ describe("InputGroup basic rendering", () => {
     expect(screen.getByTestId("lead")).toHaveClass("lead");
     expect(screen.getByTestId("trail")).toHaveClass("trail");
   });
+
+  it("sets a displayName on the compound and each adornment", () => {
+    // Assert — empty displayNames would render each as anonymous in DevTools.
+    // `InputGroup`, `InputGroup.Root`, and the underlying function are one
+    // object (Object.assign compound), so the compound's "InputGroup" alias is
+    // the observable Root displayName; the adornments are distinct objects.
+    expect(InputGroup.displayName).toBe("InputGroup");
+    expect(InputGroup.LeadingAdornment.displayName).toBe(
+      "InputGroupLeadingAdornment",
+    );
+    expect(InputGroup.TrailingAdornment.displayName).toBe(
+      "InputGroupTrailingAdornment",
+    );
+  });
 });

package/src/InputGroup/types.ts

@@ -1,22 +1,43 @@
 import { ComponentProps, ReactNode, Ref } from "react";
 
 /**
- * Props for {@link InputGroup.Root} — all `<div>` attributes plus the
- * `asChild` escape hatch and a typed `ref`.
+ * Props for {@link InputGroupRoot | `InputGroup.Root`} — the frame
+ * wrapper. Extends the native `<div>` attributes plus the `asChild`
+ * escape hatch and a typed `ref`.
  */
 export type InputGroupRootProps = ComponentProps<"div"> & {
+  /** Render the consumer's element instead of `<div>` via the
+   * {@link Slot} pattern — e.g. a `<label>` so the whole frame is
+   * clickable. The `data-input-group` hook is preserved.
+   * @default false */
   asChild?: boolean;
+  /** Forwarded to the underlying `HTMLDivElement` (or the `asChild`
+   * element). */
   ref?: Ref<HTMLDivElement>;
+  /** The wrapped control and its optional leading / trailing
+   * adornments. */
   children?: ReactNode;
 };
 
 /**
- * Props for {@link InputGroup.LeadingAdornment} and
- * {@link InputGroup.TrailingAdornment} — all `<span>` attributes plus the
- * `asChild` escape hatch and a typed `ref`.
+ * Props shared by
+ * {@link InputGroupLeadingAdornment | `InputGroup.LeadingAdornment`} and
+ * {@link InputGroupTrailingAdornment | `InputGroup.TrailingAdornment`} —
+ * the positioned adornment slots. Extends the native `<span>` attributes
+ * plus the `asChild` escape hatch and a typed `ref`.
  */
 export type InputGroupAdornmentProps = ComponentProps<"span"> & {
+  /** Render the consumer's element instead of `<span>` via the
+   * {@link Slot} pattern — e.g. an interactive `<button>`. Event
+   * handlers compose (child runs first) and the `data-input-group-adornment`
+   * hook is preserved.
+   * @default false */
   asChild?: boolean;
+  /** Forwarded to the underlying `HTMLSpanElement` (or the `asChild`
+   * element). */
   ref?: Ref<HTMLSpanElement>;
+  /** The adornment content — a decorative icon (mark it
+   * `aria-hidden="true"`), suffix text, or an interactive control with an
+   * accessible name. */
   children?: ReactNode;
 };

package/src/MillerColumns/MillerColumns.tsx

@@ -33,11 +33,41 @@ import type {
  * The root of a Miller Columns widget — a horizontal strip of vertical
  * lists where selecting a node reveals its children in the next column.
  *
- * Renders the strip container (`role="tree"`) into which every
- * `MillerColumns.Column` projects itself via a portal. Authoring the tree
- * is recursive: an `Item` declares its child column as a *nested*
- * `<MillerColumns.Column>`, and the strip flattens those nested columns
- * into a single left-to-right row.
+ * Renders the strip container (`role="tree"`, `data-orientation="horizontal"`)
+ * into which every {@link MillerColumnsColumn | `MillerColumns.Column`}
+ * projects itself via a portal. Authoring the tree is **recursive** and
+ * data-less: there is no `items` prop — an {@link MillerColumnsItem | `Item`}
+ * declares its child column as a *nested* `<MillerColumns.Column>`, and the
+ * strip flattens those nested columns into a single left-to-right row by
+ * rendering one `display: contents` slot per visible depth and portalling
+ * each column into its slot. This fixes left-to-right DOM order by slot
+ * order rather than by portal commit order.
+ *
+ * **Controlled vs uncontrolled.** State is the *selection path* — an array
+ * of item ids, root column first (`["docs", "guides"]`). The two modes are
+ * statically discriminated at the type level:
+ *
+ * - **Uncontrolled** — pass {@link MillerColumnsRootUncontrolledProps.defaultValue | `defaultValue`}
+ *   (or omit it to start empty). The component owns the path.
+ * - **Controlled** — pass {@link MillerColumnsRootControlledProps.value | `value`}
+ *   and {@link MillerColumnsRootControlledProps.onValueChange | `onValueChange`}
+ *   together; every selection defers back through the callback.
+ *
+ * **Roving tabindex.** The whole tree has exactly **one** Tab stop
+ * (`tabIndex={0}`), not one per column. It follows the last-focused item;
+ * before any focus it defaults to the deepest selected item, falling back
+ * to the first enabled root item. Within a column, Up/Down/Home/End move
+ * focus; ArrowRight opens (and steps into) a branch item's child column,
+ * ArrowLeft returns to the parent item.
+ *
+ * **Context.** Root establishes {@link MillerColumnsContext} (selection
+ * path, portal slots, item registry, column widths, and focus commands);
+ * each Column provides {@link MillerColumnsColumnContext} (its depth) and
+ * each Item {@link MillerColumnsItemContext} (`selected` / `hasChildren`).
+ * Read the current selection from consumer content with
+ * {@link useMillerColumnsSelection}.
+ *
+ * @extends HTMLDivElement
  *
  * @example
  * ```tsx
@@ -86,9 +116,20 @@ MillerColumnsRoot.displayName = "MillerColumnsRoot";
 
 /**
  * A single vertical list of items within the strip. Renders a
- * `<div role="group">` that is portal-projected into the `Root` strip, so
- * a `Column` nested inside an `Item` still appears side-by-side with its
- * ancestors rather than in document flow.
+ * `<div role="group">` (carrying `data-depth`) that is **portal-projected**
+ * into the {@link MillerColumnsRoot | `Root`} strip's depth slot, so a
+ * `Column` nested inside an `Item` still appears side-by-side with its
+ * ancestors rather than in document flow. Until its slot has mounted the
+ * component renders `null`.
+ *
+ * It reads its depth from {@link MillerColumnsContext} and re-provides it to
+ * descendant {@link MillerColumnsItem | Items} via
+ * {@link MillerColumnsColumnContext}. A width set by a
+ * {@link MillerColumnsResizeHandle | `ResizeHandle`} in this column is
+ * applied here as an inline `width` style (consumer `style` still wins for
+ * every other property).
+ *
+ * @extends HTMLDivElement
  *
  * @example
  * ```tsx
@@ -128,27 +169,44 @@ export function MillerColumnsColumn({
 MillerColumnsColumn.displayName = "MillerColumnsColumn";
 
 /**
- * A single selectable node within a `Column`. Renders a
- * `<div role="treeitem">` for its cell content.
+ * A single selectable node within a {@link MillerColumnsColumn | `Column`}.
+ * Renders a `<div role="treeitem">` for its cell content, with
+ * `aria-selected`, `aria-level` (1-based depth), and `data-state` /
+ * `data-depth` styling hooks.
  *
  * The {@link MillerColumnsItemProps.value | `value`} prop is the stable
  * identifier used to match this item against the active selection path.
  *
- * An `Item` becomes a branch by nesting a `<MillerColumns.Column>` among
- * its children. That child column is mounted (and projected into the
- * strip) only while the item is selected; an item with no nested column
- * is a leaf.
+ * **Branch vs leaf.** An `Item` becomes a *branch* by nesting a
+ * `<MillerColumns.Column>` among its children — `partitionItemChildren`
+ * splits the children into the cell content and that single optional
+ * nested column (matched however deeply it is wrapped in fragments; a
+ * second nested column throws). A branch carries `aria-expanded` and
+ * mounts its child column (projecting it into the strip) only while the
+ * item is selected; an item with no nested column is a *leaf*.
+ *
+ * **Keyboard & selection.** Clicking or activating (Enter/Space) selects
+ * the item, truncating the path to this depth. ArrowRight on a branch opens
+ * and steps into the child column; ArrowLeft returns focus to the parent
+ * item. The item participates in the tree-wide single roving Tab stop.
+ *
+ * **Disabled.** Pass `disabled` to render `aria-disabled="true"` /
+ * `data-disabled`; the item is skipped by roving navigation and cannot be
+ * selected, focused, or activated.
  *
  * **`asChild` prop.** Pass `asChild` to render the cell as a
  * consumer-supplied element (e.g. an `<a>`) instead of the default
  * `<div>`. All treeitem ARIA attributes, event handlers, and the internal
- * ref are merged onto that child. A nested `<MillerColumns.Column>` is
- * still declared as a sibling of the cell element.
+ * ref are merged onto that child via the {@link Slot} pattern. A nested
+ * `<MillerColumns.Column>` is still declared as a sibling of the cell
+ * element.
  *
  * **Ref forwarding.** A `ref` prop (React 19 ref-as-prop style) is
  * forwarded to the rendered element and composed with the library's
  * internal ref.
  *
+ * @extends HTMLDivElement
+ *
  * @example Leaf
  * ```tsx
  * <MillerColumns.Item value="guides">Guides</MillerColumns.Item>
@@ -204,6 +262,8 @@ MillerColumnsItem.displayName = "MillerColumnsItem";
  * - `data-has-children` — always present (the indicator only renders
  *   for branch items).
  *
+ * @extends HTMLSpanElement
+ *
  * @example
  * ```tsx
  * <MillerColumns.Item value="docs">
@@ -243,10 +303,13 @@ MillerColumnsItemIndicator.displayName = "MillerColumnsItemIndicator";
  * `<div role="separator" aria-orientation="vertical">` that, while
  * pointer-dragged, drives that column's width as state on the `Root`.
  *
- * Must be rendered among a `MillerColumns.Column`'s children — it reads
- * the column's depth from context. Position it with CSS (typically
+ * Must be rendered among a {@link MillerColumnsColumn | `MillerColumns.Column`}'s
+ * children — it reads the column's depth from
+ * {@link MillerColumnsColumnContext}. Position it with CSS (typically
  * absolutely, against the column's trailing edge).
  *
+ * @extends HTMLDivElement
+ *
  * @example
  * ```tsx
  * <MillerColumns.Column>
@@ -277,7 +340,11 @@ MillerColumnsResizeHandle.displayName = "MillerColumnsResizeHandle";
  *
  * Pair it with {@link useMillerColumnsSelection} to render content for
  * the current selection. Author it as the **last child** of `Root`, a
- * sibling of the root `Column`.
+ * sibling of the root `Column`. It subscribes to
+ * {@link MillerColumnsContext} (so it must live inside a `Root`) but does
+ * not portal — it stays in document flow after the projected columns.
+ *
+ * @extends HTMLDivElement
  *
  * @example
  * ```tsx

package/src/MillerColumns/types.ts

@@ -1,76 +1,132 @@
 import { ComponentProps, ReactNode, Ref } from "react";
 
-/** Props common to both controlled and uncontrolled `MillerColumns.Root` modes. */
-export type MillerColumnsRootBaseProps = Omit<ComponentProps<"div">, "ref"> & {
-  /** The columns and panels that make up the strip. */
+/**
+ * Shared base for both {@link MillerColumnsRootProps} variants — the native
+ * `<div>` attributes (minus `ref`, which the strip owns internally).
+ */
+export type MillerColumnsRootBaseProps = Omit<
+  ComponentProps<"div">,
+  "ref" | "defaultValue"
+> & {
+  /**
+   * The strip's tree, authored recursively: root
+   * {@link MillerColumnsColumnProps | Column(s)} whose branch
+   * {@link MillerColumnsItemProps | Items} nest further Columns, plus an
+   * optional trailing {@link MillerColumnsPreviewPanelProps | PreviewPanel}.
+   * There is no `items` data prop — the JSX *is* the data.
+   */
   children: ReactNode;
 };
 
 /**
- * Props for `MillerColumns.Root` in uncontrolled mode — the component owns the
- * selection path. Pass `defaultValue` to set the initial path.
+ * Uncontrolled variant of {@link MillerColumnsRootProps}: the component owns
+ * the selection path. Pass `defaultValue` (or omit it to start empty).
  */
 export type MillerColumnsRootUncontrolledProps = MillerColumnsRootBaseProps & {
-  /** Initial selection path when uncontrolled. */
+  /** Initial selection path on first render, root column first (e.g.
+   * `["docs", "guides"]`). The component owns the path thereafter. */
   defaultValue?: string[];
-  /** Forbidden in uncontrolled mode. */
+  /** Forbidden in uncontrolled mode — use `defaultValue` instead. */
   value?: never;
-  /** Forbidden in uncontrolled mode. */
+  /** Forbidden in uncontrolled mode — pass `value` + `onValueChange` to
+   * control the component. */
   onValueChange?: never;
 };
 
 /**
- * Props for `MillerColumns.Root` in controlled mode — the parent owns the
+ * Controlled variant of {@link MillerColumnsRootProps}: the parent owns the
  * selection path. Pass `value` and `onValueChange` together.
  */
 export type MillerColumnsRootControlledProps = MillerColumnsRootBaseProps & {
-  /** Forbidden in controlled mode. */
+  /** Forbidden in controlled mode — use `value` instead. */
   defaultValue?: never;
-  /** The controlled selection path, root column first. */
+  /** The controlled selection path, root column first. Must be kept in sync
+   * by the parent via `onValueChange`. */
   value: string[];
-  /** Called with the new path whenever the selection changes. */
+  /** Called with the new selection path whenever the selection changes.
+   * Required in controlled mode. */
   onValueChange: (path: string[]) => void;
 };
 
-/** Props for `MillerColumns.Root` — discriminated controlled/uncontrolled union. */
+/**
+ * Props for {@link MillerColumnsRoot | `MillerColumns.Root`}.
+ *
+ * Resolves to either {@link MillerColumnsRootUncontrolledProps} or
+ * {@link MillerColumnsRootControlledProps} — only one shape is accepted by
+ * TypeScript at a time.
+ */
 export type MillerColumnsRootProps =
   | MillerColumnsRootUncontrolledProps
   | MillerColumnsRootControlledProps;
 
-/** Props for `MillerColumns.Column`, a single vertical list within the strip. */
+/**
+ * Props for {@link MillerColumnsColumn | `MillerColumns.Column`}, a single
+ * vertical list. Rendered element is portal-projected into the Root strip.
+ */
 export type MillerColumnsColumnProps = ComponentProps<"div"> & {
-  /** The items (and optional resize handle) of this column. */
+  /** The column's {@link MillerColumnsItemProps | Items} and, optionally, a
+   * {@link MillerColumnsResizeHandleProps | ResizeHandle}. */
   children: ReactNode;
 };
 
-/** Props for `MillerColumns.Item`, a single selectable node within a column. */
+/**
+ * Props for {@link MillerColumnsItem | `MillerColumns.Item`}, a single
+ * selectable node within a column.
+ *
+ * Generic over the rendered element type so `asChild` consumers can type
+ * the forwarded `ref` (e.g. `MillerColumns.Item<HTMLAnchorElement>`).
+ */
 export type MillerColumnsItemProps<T extends HTMLElement = HTMLDivElement> =
   Omit<ComponentProps<"div">, "ref"> & {
-    /** Stable identifier used to match this item against the selection path. */
+    /** Stable identifier used to match this item against the selection path.
+     * The item is selected when the path entry at its depth equals `value`. */
     value: string;
-    /** When `true`, the item cannot be selected or focused. */
+    /**
+     * When `true`, the item renders `aria-disabled` / `data-disabled` and is
+     * skipped by roving navigation — it cannot be selected, focused, or
+     * activated.
+     * @default false
+     */
     disabled?: boolean;
-    /** Render the child element instead of the default `<div>`. */
+    /**
+     * Render the cell as a single consumer-supplied child element (e.g. an
+     * `<a>`) instead of the default `<div>`, merging the treeitem ARIA,
+     * handlers, and ref onto it via the {@link Slot} pattern. Any nested
+     * `<MillerColumns.Column>` remains a sibling of the cell element.
+     * @default false
+     */
     asChild?: boolean;
-    /** Cell content and, for a branch, a nested `<MillerColumns.Column>`. */
+    /** The cell content and, for a branch item, a single nested
+     * `<MillerColumns.Column>` (split out by `partitionItemChildren`). */
     children: ReactNode;
-    /** Ref to the rendered element. Defaults to `HTMLDivElement`; when using
-     * `asChild`, specify the child's element type. */
+    /** Forwarded to the rendered element. Defaults to `HTMLDivElement`; when
+     * using `asChild`, specify the child's element type. Composed with the
+     * library's internal ref. */
     ref?: Ref<T>;
   };
 
-/** Props for `MillerColumns.ItemIndicator`, the branch chevron affordance. */
+/**
+ * Props for {@link MillerColumnsItemIndicator | `MillerColumns.ItemIndicator`},
+ * the branch chevron affordance (renders nothing for leaf items).
+ */
 export type MillerColumnsItemIndicatorProps = ComponentProps<"span"> & {
-  /** The glyph to render (defaults to none). */
+  /** The glyph to render (e.g. `▸`). Optional. */
   children?: ReactNode;
 };
 
-/** Props for `MillerColumns.ResizeHandle`, the drag-to-resize separator. */
+/**
+ * Props for {@link MillerColumnsResizeHandle | `MillerColumns.ResizeHandle`},
+ * the drag-to-resize separator for its containing column.
+ */
 export type MillerColumnsResizeHandleProps = ComponentProps<"div">;
 
-/** Props for `MillerColumns.PreviewPanel`, the trailing preview pane. */
+/**
+ * Props for {@link MillerColumnsPreviewPanel | `MillerColumns.PreviewPanel`},
+ * the trailing preview pane.
+ */
 export type MillerColumnsPreviewPanelProps = ComponentProps<"div"> & {
-  /** The preview content for the current selection. */
+  /** The preview content for the current selection (typically driven by
+   * {@link useMillerColumnsSelection}). */
   children?: ReactNode;
 };
 

package/src/Modal/Modal.tsx

@@ -97,6 +97,8 @@ ModalRoot.displayName = "ModalRoot";
  * element (e.g. a router `<Link>`) with the trigger's ARIA attributes,
  * composed event handlers, and ref merged in.
  *
+ * @extends HTMLButtonElement
+ *
  * @example
  * ```tsx
  * <Modal.Trigger>Open</Modal.Trigger>
@@ -177,6 +179,8 @@ ModalPortal.displayName = "ModalPortal";
  * **`forceMount` prop.** Pass `forceMount` to keep the overlay in the
  * DOM while `open` is false so a CSS exit animation can play.
  *
+ * @extends HTMLDivElement
+ *
  * @example
  * ```tsx
  * <Modal.Overlay />
@@ -215,8 +219,15 @@ ModalOverlay.displayName = "ModalOverlay";
 /**
  * The native `<dialog>` element. React drives its `showModal()` and
  * `close()` calls in response to `open` state changes, letting the
- * browser own focus trapping, inert background, top-layer rendering,
- * and the `Esc` key.
+ * browser own the inert background, top-layer rendering, and the `Esc`
+ * key.
+ *
+ * **Focus trapping.** `showModal()` inerts the background but does
+ * *not* cycle focus — `Tab` past the last element escapes to the
+ * browser chrome, then wraps back in. To conform to the WAI-ARIA APG
+ * Modal Dialog pattern, a `keydown` handler wraps `Tab` (last → first)
+ * and `Shift+Tab` (first → last); interior Tabs are left to the
+ * browser's native, inert-aware order.
  *
  * **ARIA wiring.** `aria-labelledby` and `aria-describedby` are set
  * automatically when `Modal.Title` and `Modal.Description` are rendered
@@ -234,11 +245,21 @@ ModalOverlay.displayName = "ModalOverlay";
  *   `PointerEvent` is passed through, not a synthetic React event.
  *
  * **`asChild` is intentionally not supported.** The native dialog
- * primitive is what provides the focus trap and the inert background;
- * swapping it for a `<div>` would break both.
+ * primitive is what provides the inert background and top-layer
+ * stacking (and hosts the Tab-wrap handler above); swapping it for a
+ * `<div>` would break all of it.
  *
  * **Styling hook.** `data-state="open" | "closed"` on the dialog.
  *
+ * **Nested modals.** A `Modal.Root` may be rendered inside another modal's
+ * `Modal.Content`. Each root owns its own {@link ModalContextValue | context}
+ * and dialog, so every dialog stacks independently in the browser's top
+ * layer and each dismissal gesture (Close, Esc, click-outside) resolves
+ * against the nearest dialog only — closing the inner modal leaves the
+ * outer one open.
+ *
+ * @extends HTMLDialogElement
+ *
  * @example
  * ```tsx
  * <Modal.Content
@@ -293,6 +314,8 @@ ModalContent.displayName = "ModalContent";
  * an `<h3>` for a nested dialog or a styled heading component); the
  * id is still registered.
  *
+ * @extends HTMLHeadingElement
+ *
  * @example
  * ```tsx
  * <Modal.Title>Payment</Modal.Title>
@@ -340,6 +363,8 @@ ModalTitle.displayName = "ModalTitle";
  * Pass `asChild` to render any consumer-supplied element; the id is
  * still registered.
  *
+ * @extends HTMLParagraphElement
+ *
  * @example
  * ```tsx
  * <Modal.Description>
@@ -386,6 +411,8 @@ ModalDescription.displayName = "ModalDescription";
  * text link or an icon-only `<button>` of your own) with the close
  * behaviour merged in.
  *
+ * @extends HTMLButtonElement
+ *
  * @example
  * ```tsx
  * <Modal.Close>Cancel</Modal.Close>

package/src/Modal/README.md

@@ -5,10 +5,16 @@ A headless, accessible compound component implementing the
 
 Modal is built on the native
 [`<dialog>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dialog)
-element and its `showModal()` API, so focus trapping, inert background,
-top-layer stacking, and Esc-to-close are handled by the browser. The
-React layer adds what native `<dialog>` doesn't give you:
-
+element and its `showModal()` API, so the inert background, top-layer
+stacking, and Esc-to-close are handled by the browser. The React layer
+adds what native `<dialog>` doesn't give you:
+
+- **Focus trapping.** `showModal()` inerts the background but does
+  _not_ cycle focus — Tab past the last element escapes to the browser
+  chrome and back. A `keydown` handler on the dialog wraps `Tab`
+  (last → first) and `Shift+Tab` (first → last) so focus stays inside,
+  as the WAI-ARIA APG requires. Interior Tabs stay native, so the
+  browser's inert-aware order (radio groups, etc.) is untouched.
 - Click-outside-to-close via a `pointerdown` listener on the dialog
   that checks the pointer against `getBoundingClientRect()` — coords
   outside the rect mean the pointer landed on the native `::backdrop`.
@@ -68,10 +74,11 @@ README for the canonical composed example; nothing below changes.
 
 ## Keyboard interaction
 
-| Key   | Behaviour                                                                     |
-| ----- | ----------------------------------------------------------------------------- |
-| `Esc` | Closes the modal (native `cancel` event). Preventable via `onEscapeKeyDown`   |
-| `Tab` | Focus is trapped inside the dialog by the browser's native modal dialog logic |
+| Key         | Behaviour                                                                                                                                                                                       |
+| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Esc`       | Closes the modal (native `cancel` event). Preventable via `onEscapeKeyDown`                                                                                                                      |
+| `Tab`       | Wraps from the last focusable back to the first — focus stays inside the dialog. `showModal()` inerts the background but doesn't cycle focus, so this wrap is added by a `keydown` handler |
+| `Shift+Tab` | Wraps from the first focusable to the last                                                                                                                                                       |
 
 ## State modes
 
@@ -156,8 +163,10 @@ handlers, so only its ARIA and `data-state` are forwarded.
 ```
 
 `Modal.Content` is intentionally **not** slot-able. Its native
-`<dialog>` element is the whole reason Modal works without a focus
-trap or a scroll-lock library, so we don't expose a way to swap it.
+`<dialog>` element — the inert background and top-layer stacking — is
+the whole reason Modal needs no scroll-lock library and only a minimal
+Tab-wrap (rather than a full focus-trap library), so we don't expose a
+way to swap it.
 
 ## Animation hooks