@primitiv-ui/react 0.1.28 → 0.1.30

package/src/MillerColumns/hooks/useMillerColumnsResizeHandle.ts

@@ -1,4 +1,11 @@
-import { PointerEvent, useEffect, useState } from "react";
+import {
+  KeyboardEvent,
+  PointerEvent,
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+} from "react";
 
 import type { MillerColumnsResizeHandleProps } from "../types";
 
@@ -9,12 +16,43 @@ type DragState = { startX: number; startWidth: number };
 
 export function useMillerColumnsResizeHandle({
   onPointerDown,
+  onKeyDown,
+  minWidth = 0,
+  maxWidth = Number.POSITIVE_INFINITY,
+  step = 10,
   ...rest
 }: MillerColumnsResizeHandleProps) {
-  const { columnWidths, setColumnWidth } = useMillerColumnsContext();
+  const { columnWidths, setColumnWidth, dir } = useMillerColumnsContext();
   const { depth } = useMillerColumnsColumnContext();
 
+  const handleRef = useRef<HTMLDivElement>(null);
   const [drag, setDrag] = useState<DragState | null>(null);
+  // The column's rendered width before anything resizes it. Tracked so
+  // `aria-valuenow` is truthful from the first render — a splitter whose
+  // value only appears after the first drag announces nothing until then.
+  const [measured, setMeasured] = useState(0);
+
+  const clamp = (width: number) =>
+    Math.min(maxWidth, Math.max(minWidth, width));
+
+  // The resized width wins; otherwise the column is still sized by CSS.
+  const width = columnWidths.get(depth) ?? measured;
+
+  useLayoutEffect(() => {
+    const column = handleRef.current?.closest<HTMLElement>(
+      "[data-miller-columns-column]",
+    );
+    /* c8 ignore next 3 -- the handle only renders inside a Column, which
+       context already enforces, so the ancestor is always present. */
+    if (!column) {
+      return;
+    }
+    const measure = () => setMeasured(column.getBoundingClientRect().width);
+    measure();
+    const observer = new ResizeObserver(measure);
+    observer.observe(column);
+    return () => observer.disconnect();
+  }, []);
 
   // A drag is tracked on `window`, not the handle, so the pointer can
   // travel anywhere once it is down; the listeners live only for the
@@ -27,13 +65,8 @@ export function useMillerColumnsResizeHandle({
     const activeDrag = drag;
 
     function handleMove(event: globalThis.PointerEvent) {
-      setColumnWidth(
-        depth,
-        Math.max(
-          0,
-          activeDrag.startWidth + event.clientX - activeDrag.startX,
-        ),
-      );
+      const next = activeDrag.startWidth + event.clientX - activeDrag.startX;
+      setColumnWidth(depth, Math.min(maxWidth, Math.max(minWidth, next)));
     }
 
     function endDrag() {
@@ -48,7 +81,7 @@ export function useMillerColumnsResizeHandle({
       window.removeEventListener("pointerup", endDrag);
       window.removeEventListener("pointercancel", endDrag);
     };
-  }, [drag, depth, setColumnWidth]);
+  }, [drag, depth, setColumnWidth, minWidth, maxWidth]);
 
   function handlePointerDown(event: PointerEvent<HTMLDivElement>) {
     onPointerDown?.(event);
@@ -63,13 +96,50 @@ export function useMillerColumnsResizeHandle({
     setDrag({ startX: event.clientX, startWidth });
   }
 
+  // The column extends towards the inline-end edge, which is leftwards
+  // under rtl — so the key that widens it mirrors with the direction.
+  const growKey = dir === "rtl" ? "ArrowLeft" : "ArrowRight";
+  const shrinkKey = dir === "rtl" ? "ArrowRight" : "ArrowLeft";
+
+  function handleKeyDown(event: KeyboardEvent<HTMLDivElement>) {
+    onKeyDown?.(event);
+
+    const next = (() => {
+      switch (event.key) {
+        case growKey:
+          return width + step;
+        case shrinkKey:
+          return width - step;
+        case "Home":
+          return minWidth;
+        case "End":
+          return maxWidth;
+        default:
+          return null;
+      }
+    })();
+
+    if (next === null || !Number.isFinite(next)) {
+      return;
+    }
+
+    event.preventDefault();
+    setColumnWidth(depth, clamp(next));
+  }
+
   return {
     handleProps: {
+      ref: handleRef,
       role: "separator" as const,
       "aria-orientation": "vertical" as const,
+      tabIndex: 0,
+      "aria-valuenow": Math.round(width),
+      "aria-valuemin": minWidth,
+      ...(Number.isFinite(maxWidth) ? { "aria-valuemax": maxWidth } : {}),
       "data-miller-columns-resize-handle": "",
       ...(drag ? { "data-dragging": "" } : {}),
       onPointerDown: handlePointerDown,
+      onKeyDown: handleKeyDown,
       ...rest,
     },
   };

package/src/MillerColumns/index.ts

@@ -1,3 +1,7 @@
 export * from "./MillerColumns";
+export {
+  MILLER_COLUMNS_PART,
+  type MillerColumnsPartName,
+} from "./utils";
 export { useMillerColumnsSelection } from "./useMillerColumnsSelection";
 export * from "./types";

package/src/MillerColumns/types.ts

@@ -1,77 +1,173 @@
-import { ComponentProps, ReactNode, Ref } from "react";
+import { ComponentProps, KeyboardEvent, 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. */
+import type { Direction } from "../DirectionProvider/types";
+
+/**
+ * Shared base for both {@link MillerColumnsRootProps} variants — the native
+ * `<div>` attributes (minus `ref`, which the strip owns internally, and
+ * `dir`, narrowed below to the {@link Direction} union).
+ */
+export type MillerColumnsRootBaseProps = Omit<
+  ComponentProps<"div">,
+  "ref" | "defaultValue" | "dir"
+> & {
+  /**
+   * Reading direction. Under `"rtl"` the horizontal arrow pair is
+   * mirrored — ArrowLeft steps *into* a branch's child column and
+   * ArrowRight walks back out — so navigation follows the visual order.
+   * Inherited from a `DirectionProvider` ancestor when omitted.
+   * @default "ltr"
+   */
+  dir?: Direction;
+  /**
+   * 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. */
-  children: ReactNode;
+  /** The column's {@link MillerColumnsItemProps | Items} and, optionally, a
+   * {@link MillerColumnsResizeHandleProps | ResizeHandle}. Optional: a
+   * childless branch legitimately opens an empty column, which carries
+   * `data-empty` for the styling layer. */
+  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. */
-export type MillerColumnsResizeHandleProps = ComponentProps<"div">;
+/**
+ * Props for {@link MillerColumnsResizeHandle | `MillerColumns.ResizeHandle`},
+ * the drag-to-resize separator for its containing column.
+ */
+export type MillerColumnsResizeHandleProps = ComponentProps<"div"> & {
+  /**
+   * Smallest width the column can be dragged or stepped to, in pixels.
+   * Also published as `aria-valuemin`.
+   * @default 0
+   */
+  minWidth?: number;
+  /**
+   * Largest width the column can be dragged or stepped to, in pixels.
+   * Published as `aria-valuemax` when finite; left unbounded by default,
+   * in which case the attribute is omitted.
+   * @default Infinity
+   */
+  maxWidth?: number;
+  /**
+   * Pixels moved per arrow-key press.
+   * @default 10
+   */
+  step?: number;
+};
 
-/** 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;
+  /**
+   * Keep the panel mounted regardless of the selection, instead of following
+   * Finder's rule (a preview only where a selected *leaf* would open a child
+   * column). Use it for a persistent inspector, or to animate the panel in
+   * and out.
+   * @default false
+   */
+  forceMount?: boolean;
 };
 
 /** The current selection, as returned by `useMillerColumnsSelection`. */
@@ -100,6 +196,8 @@ export type MillerColumnsItemAddress = {
 
 /** Value shared through the root MillerColumns context. */
 export type MillerColumnsContextValue = {
+  /** The resolved reading direction — the `dir` prop, else the inherited one. */
+  dir: Direction;
   /** Portal slots keyed by column depth. */
   slots: Map<number, HTMLElement>;
   /** Per-depth column widths set via the resize handle. */
@@ -116,9 +214,15 @@ export type MillerColumnsContextValue = {
     value: string,
     element: HTMLElement | null,
     disabled: boolean,
+    hasChildren: boolean,
   ) => void;
+  /** Whether the deepest selected item is a leaf — Finder's rule for whether a
+   * preview occupies the slot after it. `false` when nothing is selected. */
+  terminalIsLeaf: boolean;
   /** Get the registered items for a column. */
   getColumnItems: (depth: number) => MillerColumnsItemMeta[];
+  /** Read a registered item's rendered cell text, for typeahead matching. */
+  getItemLabel: (depth: number, value: string) => string;
   /** Move focus to the given item. */
   focusItem: (depth: number, value: string) => void;
   /** Focus the first item in a column; returns whether one was focused. */
@@ -129,6 +233,8 @@ export type MillerColumnsContextValue = {
   activeItem: MillerColumnsItemAddress | null;
   /** Set the active (focused) item. */
   setActiveItem: (item: MillerColumnsItemAddress) => void;
+  /** Printable-character typeahead, scoped to the focused item's column. */
+  handleTypeahead: (event: KeyboardEvent<HTMLElement>) => void;
 };
 
 /** Value shared through a column's context. */

package/src/MillerColumns/utils.ts

@@ -23,11 +23,77 @@ export function selectAtDepth(
 }
 
 /**
- * Whether `node` is a `MillerColumns.Column` element — the identity
- * check used to separate an Item's cell content from its child column.
+ * Splits a props bag into its `aria-*` entries and everything else.
+ *
+ * `Root` renders two elements — a plain strip container and the inner
+ * `role="tree"` widget — so one props bag has two possible homes. ARIA
+ * belongs on the widget (an `aria-label` must name the tree, not its
+ * scroll container); `className`, `id`, `style` and the rest belong on
+ * the container the consumer actually lays out.
+ */
+export function partitionAriaProps(props: Record<string, unknown>): {
+  aria: Record<string, unknown>;
+  rest: Record<string, unknown>;
+} {
+  const aria: Record<string, unknown> = {};
+  const rest: Record<string, unknown> = {};
+
+  for (const [key, value] of Object.entries(props)) {
+    if (key.startsWith("aria-")) {
+      aria[key] = value;
+    } else {
+      rest[key] = value;
+    }
+  }
+
+  return { aria, rest };
+}
+
+/**
+ * Marker a styling layer sets on a component that renders a `MillerColumns`
+ * part, so this module recognises the wrapper as that part.
+ *
+ * `Item` inspects its children **before** rendering them, so it sees the
+ * wrapper component rather than the `MillerColumns.Column` the wrapper
+ * returns. Without a marker a wrapped child column is mis-read as cell
+ * content: the item stops being a branch (no `aria-expanded`, no chevron, no
+ * ArrowRight) and — worse — the column projects into whatever depth slot
+ * happens to be open, so selecting *one* branch reveals *every* sibling's
+ * children at once.
+ *
+ * ```tsx
+ * function StyledColumn(props: MillerColumnsColumnProps) {
+ *   return <MillerColumns.Column {...props} className="column" />;
+ * }
+ * StyledColumn[MILLER_COLUMNS_PART] = "column";
+ * ```
+ */
+export const MILLER_COLUMNS_PART: "__primitivMillerColumnsPart" =
+  "__primitivMillerColumnsPart";
+
+/** The part names {@link MILLER_COLUMNS_PART} accepts. */
+export type MillerColumnsPartName = "column";
+
+/** Read a component's {@link MILLER_COLUMNS_PART} marker, if it declares one. */
+function millerColumnsPartOf(
+  type: unknown,
+): MillerColumnsPartName | undefined {
+  return (type as Record<string, MillerColumnsPartName | undefined> | null)?.[
+    MILLER_COLUMNS_PART
+  ];
+}
+
+/**
+ * Whether `node` is a `MillerColumns.Column` element — either the part itself,
+ * or a component that marks itself as standing in for it (see
+ * {@link MILLER_COLUMNS_PART}).
  */
 export function isColumnElement(node: ReactNode): node is ReactElement {
-  return isValidElement(node) && node.type === MillerColumnsColumn;
+  return (
+    isValidElement(node) &&
+    (node.type === MillerColumnsColumn ||
+      millerColumnsPartOf(node.type) === "column")
+  );
 }
 
 /**

package/src/Modal/Modal.tsx

@@ -51,7 +51,7 @@ import {
  * @example Uncontrolled
  * ```tsx
  * <Modal.Root defaultOpen>
- *   <Modal.Content>…</Modal.Content>
+ *   <Modal.Content>...</Modal.Content>
  * </Modal.Root>
  * ```
  *
@@ -63,7 +63,7 @@ import {
  *   <Modal.Trigger>Open</Modal.Trigger>
  *   <Modal.Portal>
  *     <Modal.Overlay />
- *     <Modal.Content>…</Modal.Content>
+ *     <Modal.Content>...</Modal.Content>
  *   </Modal.Portal>
  * </Modal.Root>
  * ```
@@ -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>
@@ -138,7 +140,7 @@ ModalTrigger.displayName = "ModalTrigger";
  * ```tsx
  * <Modal.Portal container={document.getElementById("modal-root")!}>
  *   <Modal.Overlay />
- *   <Modal.Content>…</Modal.Content>
+ *   <Modal.Content>...</Modal.Content>
  * </Modal.Portal>
  * ```
  */
@@ -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
@@ -246,7 +267,7 @@ ModalOverlay.displayName = "ModalOverlay";
  *     if (hasUnsavedChanges) event.preventDefault();
  *   }}
  * >
- *   …
+ *   ...
  * </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
 
@@ -83,12 +90,12 @@ rejects mixing them.
 
 ```tsx
 // Uncontrolled
-<Modal.Root defaultOpen>…</Modal.Root>;
+<Modal.Root defaultOpen>...</Modal.Root>;
 
 // Controlled
 const [open, setOpen] = useState(false);
 <Modal.Root open={open} onOpenChange={setOpen}>
-  …
+  ...
 </Modal.Root>;
 ```
 
@@ -108,7 +115,7 @@ open. `onPointerDownOutside` receives the native `PointerEvent`
     if (isRequiredFlow) event.preventDefault();
   }}
 >
-  …
+  ...
 </Modal.Content>
 ```
 
@@ -119,7 +126,7 @@ import { Modal, type ModalImperativeApi } from "@primitiv-ui/react";
 
 const ref = useRef<ModalImperativeApi>(null);
 
-<Modal.Root ref={ref}>…</Modal.Root>;
+<Modal.Root ref={ref}>...</Modal.Root>;
 
 ref.current?.open();
 ref.current?.close();
@@ -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
 
@@ -168,7 +177,7 @@ animation can play against the `data-state="closed"` attribute:
 ```tsx
 <Modal.Portal forceMount>
   <Modal.Overlay forceMount />
-  <Modal.Content>…</Modal.Content>
+  <Modal.Content>...</Modal.Content>
 </Modal.Portal>
 ```