@primitiv-ui/react 0.1.28 → 0.1.30

package/src/Modal/__tests__/Modal.focus-trap.test.tsx

@@ -0,0 +1,162 @@
+import "./dialog-polyfill";
+
+import { createEvent, fireEvent, render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import { Modal } from "../Modal";
+
+function getDialog() {
+  return document.querySelector("dialog") as HTMLDialogElement;
+}
+
+// WAI-ARIA APG Modal Dialog pattern: Tab must cycle *within* the dialog and
+// never reach the browser chrome. A native <dialog> inerts the background but
+// does not wrap focus, so Modal.Content adds a boundary Tab-wrap trap. These
+// tests render a Trigger (outside the dialog) in the wrap cases so that,
+// without the trap, a native wrap would land on the Trigger — proving the
+// assertion is driven by the trap, not by jsdom's own tab order.
+describe("Modal focus trap — Tab cycles within the dialog", () => {
+  it("wraps focus from the last element back to the first on Tab", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    render(
+      <Modal.Root defaultOpen>
+        <Modal.Trigger>Open</Modal.Trigger>
+        <Modal.Content>
+          <button type="button">First</button>
+          <button type="button">Second</button>
+          <button type="button">Third</button>
+        </Modal.Content>
+      </Modal.Root>,
+    );
+    screen.getByRole("button", { name: "Third" }).focus();
+
+    // Act
+    await user.tab();
+
+    // Assert
+    expect(screen.getByRole("button", { name: "First" })).toHaveFocus();
+  });
+
+  it("leaves an interior forward Tab to native handling (no wrap)", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    render(
+      <Modal.Root defaultOpen>
+        <Modal.Content>
+          <button type="button">First</button>
+          <button type="button">Second</button>
+          <button type="button">Third</button>
+        </Modal.Content>
+      </Modal.Root>,
+    );
+    screen.getByRole("button", { name: "First" }).focus();
+
+    // Act
+    await user.tab();
+
+    // Assert
+    expect(screen.getByRole("button", { name: "Second" })).toHaveFocus();
+  });
+
+  it("wraps focus from the first element to the last on Shift+Tab", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    render(
+      <Modal.Root defaultOpen>
+        <Modal.Trigger>Open</Modal.Trigger>
+        <Modal.Content>
+          <button type="button">First</button>
+          <button type="button">Second</button>
+          <button type="button">Third</button>
+        </Modal.Content>
+      </Modal.Root>,
+    );
+    screen.getByRole("button", { name: "First" }).focus();
+
+    // Act
+    await user.tab({ shift: true });
+
+    // Assert
+    expect(screen.getByRole("button", { name: "Third" })).toHaveFocus();
+  });
+
+  it("leaves an interior Shift+Tab to native handling (no wrap)", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    render(
+      <Modal.Root defaultOpen>
+        <Modal.Content>
+          <button type="button">First</button>
+          <button type="button">Second</button>
+          <button type="button">Third</button>
+        </Modal.Content>
+      </Modal.Root>,
+    );
+    screen.getByRole("button", { name: "Second" }).focus();
+
+    // Act
+    await user.tab({ shift: true });
+
+    // Assert
+    expect(screen.getByRole("button", { name: "First" })).toHaveFocus();
+  });
+
+  it("ignores non-Tab keys (typing is never intercepted)", () => {
+    // Arrange
+    render(
+      <Modal.Root defaultOpen>
+        <Modal.Content>
+          <button type="button">First</button>
+          <button type="button">Second</button>
+        </Modal.Content>
+      </Modal.Root>,
+    );
+    const first = screen.getByRole("button", { name: "First" });
+    first.focus();
+
+    // Act
+    const event = createEvent.keyDown(first, { key: "a" });
+    fireEvent(first, event);
+
+    // Assert
+    expect(first).toHaveFocus();
+    expect(event.defaultPrevented).toBe(false);
+  });
+
+  it("blocks Tab when the dialog has no focusable content", () => {
+    // Arrange
+    render(
+      <Modal.Root defaultOpen>
+        <Modal.Content>Just text, nothing to focus.</Modal.Content>
+      </Modal.Root>,
+    );
+    const dialog = getDialog();
+
+    // Act
+    const event = createEvent.keyDown(dialog, { key: "Tab" });
+    fireEvent(dialog, event);
+
+    // Assert — Tab is swallowed so focus cannot escape to the browser chrome.
+    expect(event.defaultPrevented).toBe(true);
+  });
+
+  it("stays inactive while the dialog is closed", () => {
+    // Arrange — Content always renders its <dialog>; without defaultOpen it is
+    // mounted but closed, so the trap must not fire.
+    render(
+      <Modal.Root>
+        <Modal.Content>Just text, nothing to focus.</Modal.Content>
+      </Modal.Root>,
+    );
+    const dialog = getDialog();
+    expect(dialog.open).toBe(false);
+
+    // Act
+    const event = createEvent.keyDown(dialog, { key: "Tab" });
+    fireEvent(dialog, event);
+
+    // Assert — the guard returns before the empty-content block would preventDefault.
+    expect(event.defaultPrevented).toBe(false);
+  });
+});

package/src/Modal/hooks/useModalContent.ts

@@ -1,5 +1,6 @@
 import { useEffect, useRef } from "react";
 
+import { FOCUSABLE_SELECTOR } from "../../utils/index.ts";
 import { useModalContext } from "./useModalContext";
 
 export function useModalContent() {
@@ -48,13 +49,44 @@ export function useModalContent() {
       if (event.defaultPrevented) return;
       setOpen(false);
     };
+    const handleKeyDown = (event: KeyboardEvent) => {
+      // WAI-ARIA APG Modal Dialog: Tab must cycle within the dialog. A native
+      // modal <dialog> inerts the background (Tab can't reach the page) but
+      // does NOT wrap — Tab past the last element escapes to the browser
+      // chrome, then returns. Close only the two boundary gaps here; interior
+      // Tabs stay native so the browser's inert-aware order (radio groups,
+      // etc.) keeps working.
+      if (event.key !== "Tab") return;
+      if (!dialog.open) return;
+      const focusables = Array.from(
+        dialog.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR),
+      );
+      if (focusables.length === 0) {
+        // Nothing tabbable inside — block Tab so focus can't leak to the
+        // browser chrome (native <dialog> would otherwise let it out).
+        event.preventDefault();
+        return;
+      }
+      const first = focusables[0];
+      const last = focusables[focusables.length - 1];
+      const active = document.activeElement;
+      if (!event.shiftKey && active === last) {
+        event.preventDefault();
+        first.focus();
+      } else if (event.shiftKey && active === first) {
+        event.preventDefault();
+        last.focus();
+      }
+    };
     dialog.addEventListener("close", handleClose);
     dialog.addEventListener("cancel", handleCancel);
     dialog.addEventListener("pointerdown", handlePointerDown);
+    dialog.addEventListener("keydown", handleKeyDown);
     return () => {
       dialog.removeEventListener("close", handleClose);
       dialog.removeEventListener("cancel", handleCancel);
       dialog.removeEventListener("pointerdown", handlePointerDown);
+      dialog.removeEventListener("keydown", handleKeyDown);
     };
   }, [setOpen, contentCallbacksRef]);
 

package/src/Modal/types.ts

@@ -8,23 +8,36 @@ import {
 
 /**
  * Imperative handle exposed on `Modal.Root`'s `ref`, letting callers open
- * and close the modal programmatically.
+ * and close the modal programmatically from outside the React subtree.
+ *
+ * In controlled mode these methods defer to `onOpenChange` rather than
+ * flipping any internal state — the parent stays the source of truth.
  */
 export type ModalImperativeApi = {
-  /** Opens the modal. */
+  /** Opens the modal (uncontrolled: sets open; controlled: calls `onOpenChange(true)`). */
   open: () => void;
-  /** Closes the modal. */
+  /** Closes the modal (uncontrolled: clears open; controlled: calls `onOpenChange(false)`). */
   close: () => void;
 };
 
 /**
- * Optional escape-hatch callbacks accepted by `Modal.Content` for
- * intercepting dismissal gestures.
+ * Optional escape-hatch callbacks accepted by
+ * {@link ModalContentProps | `Modal.Content`} for intercepting the two
+ * dismissal gestures the browser drives on a native `<dialog>`. Both receive
+ * the raw native event (not a synthetic React event).
  */
 export type ModalContentCallbacks = {
-  /** Fires when the user presses Escape; call `preventDefault` to keep the modal open. */
+  /**
+   * Fires on the dialog's native `cancel` event when the user presses
+   * Escape. Call `event.preventDefault()` to veto closing and keep the
+   * modal open (e.g. to confirm unsaved changes first).
+   */
   onEscapeKeyDown?: (event: Event) => void;
-  /** Fires on a pointer-down outside the content; call `preventDefault` to keep the modal open. */
+  /**
+   * Fires on a `pointerdown` whose coordinates land outside the dialog's
+   * bounding rect — i.e. on the browser-painted `::backdrop`. Call
+   * `event.preventDefault()` to veto closing and keep the modal open.
+   */
   onPointerDownOutside?: (event: PointerEvent) => void;
 };
 
@@ -51,75 +64,143 @@ export type ModalContextValue = {
   registerDescription: (id: string | undefined) => void;
 };
 
-/** Props for `Modal.Content` — native `<dialog>` props plus dismissal callbacks. */
+/**
+ * Props for `Modal.Content` — every native `<dialog>` attribute plus the
+ * two {@link ModalContentCallbacks | dismissal callbacks}. `asChild` is
+ * intentionally absent: the native `<dialog>` is what supplies the inert
+ * background, top-layer stacking, and the Tab-wrap focus trap, so it cannot
+ * be swapped for another element.
+ */
 export type ModalContentProps = ComponentProps<"dialog"> &
   ModalContentCallbacks;
 
-/** `Modal.Root` props for the uncontrolled (self-managed) open state. */
+/**
+ * `Modal.Root` props for the **uncontrolled** (self-managed) open state.
+ * The component owns the open flag internally. Mutually exclusive with
+ * {@link ControlledModalRootProps}.
+ */
 export type UncontrolledModalRootProps = {
-  /** Initial open state when uncontrolled. */
+  /**
+   * Whether the modal is open on first render. The component owns the flag
+   * from then on. Omit for closed-on-mount.
+   * @default false
+   */
   defaultOpen?: boolean;
+  /** Forbidden in uncontrolled mode — use `defaultOpen` instead. */
   open?: never;
-  /** Called whenever the open state changes. */
+  /**
+   * Called with the new open state whenever it changes (open or close).
+   * Optional in uncontrolled mode — useful purely to observe transitions.
+   */
   onOpenChange?: (open: boolean) => void;
 };
 
-/** `Modal.Root` props for the controlled open state. */
+/**
+ * `Modal.Root` props for the **controlled** open state. The parent owns the
+ * flag and must keep it in sync via `onOpenChange`. Mutually exclusive with
+ * {@link UncontrolledModalRootProps}.
+ */
 export type ControlledModalRootProps = {
-  /** Controlled open state. */
+  /** The current open state. Must be kept in sync by the parent via `onOpenChange`. */
   open: boolean;
-  /** Called whenever the modal requests an open-state change. */
+  /**
+   * Called with the requested open state whenever the modal wants to open or
+   * close (trigger click, Close button, Esc, click-outside, imperative API).
+   * Required in controlled mode.
+   */
   onOpenChange: (open: boolean) => void;
+  /** Forbidden in controlled mode — use `open` instead. */
   defaultOpen?: never;
 };
 
-/** Props for `Modal.Root`, in either the controlled or uncontrolled mode. */
+/**
+ * Props for {@link ModalRoot | `Modal.Root`}, in either the controlled or
+ * uncontrolled mode — resolves to
+ * {@link UncontrolledModalRootProps} | {@link ControlledModalRootProps}, so
+ * TypeScript accepts only one shape at a time.
+ */
 export type ModalRootProps = {
-  /** Modal sub-components. */
+  /** The modal's sub-components (Trigger, Portal, Overlay, Content, ...). */
   children?: ReactNode;
 } & (UncontrolledModalRootProps | ControlledModalRootProps) & {
-    /** Ref receiving the imperative open/close handle. */
+    /** Ref receiving the imperative {@link ModalImperativeApi | open/close handle}. */
     ref?: Ref<ModalImperativeApi>;
   };
 
 /** Props for `Modal.Trigger` — a `<button>` that opens the modal. */
 export type ModalTriggerProps = ComponentProps<"button"> & {
-  /** Render into the consumer's own element instead of a `<button>`. */
+  /**
+   * Render into the consumer's own element (e.g. a router `<Link>`) instead
+   * of the default `<button>`, merging the trigger's ARIA wiring, composed
+   * event handlers, and ref onto it via the Slot pattern.
+   * @default false
+   */
   asChild?: boolean;
 };
 
 /** Props for `Modal.Close` — a `<button>` that closes the modal. */
 export type ModalCloseProps = ComponentProps<"button"> & {
-  /** Render into the consumer's own element instead of a `<button>`. */
+  /**
+   * Render into the consumer's own element (e.g. an icon-only button)
+   * instead of the default `<button>`, merging the close behaviour in. The
+   * consumer's `onClick` runs first and can `event.preventDefault()` to veto.
+   * @default false
+   */
   asChild?: boolean;
 };
 
 /** Props for `Modal.Portal` — renders its children into `container`. */
 export type ModalPortalProps = {
-  /** Content to portal. */
+  /** The dialog subtree to portal — typically `Modal.Overlay` + `Modal.Content`. */
   children?: ReactNode;
-  /** Target element to portal into. Defaults to `document.body`. */
+  /**
+   * Target element to portal into.
+   * @default document.body
+   */
   container?: HTMLElement;
-  /** Keep the portal mounted even while the modal is closed. */
+  /**
+   * Keep the portalled subtree mounted after `open` flips false, so a CSS
+   * exit animation keyed off `data-state="closed"` can play. Without it the
+   * portal unmounts as soon as the modal closes.
+   * @default false
+   */
   forceMount?: boolean;
 };
 
-/** Props for `Modal.Overlay` — the click-outside backdrop. */
+/** Props for `Modal.Overlay` — the animation-friendly backdrop sibling. */
 export type ModalOverlayProps = ComponentProps<"div"> & {
-  /** Render into the consumer's own element instead of a `<div>`. */
+  /**
+   * Render into the consumer's own element (e.g. a motion wrapper) instead of
+   * the default `<div>`, merging the overlay's `aria-hidden` and `data-state`
+   * onto it via the Slot pattern.
+   * @default false
+   */
   asChild?: boolean;
-  /** Keep the overlay mounted even while the modal is closed. */
+  /**
+   * Keep the overlay mounted after `open` flips false so a CSS fade-out can
+   * play. Without it the overlay unmounts as soon as the modal closes.
+   * @default false
+   */
   forceMount?: boolean;
 };
 
-/** Props for `Modal.Title` — supplies the dialog's accessible name. */
+/** Props for `Modal.Title` — supplies the dialog's accessible name (`aria-labelledby`). */
 export type ModalTitleProps = HTMLAttributes<HTMLElement> & {
-  /** Render into the consumer's own element instead of an `<h2>`. */
+  /**
+   * Render into the consumer's own heading element (e.g. an `<h3>` for a
+   * nested dialog) instead of the default `<h2>`; the generated id is still
+   * registered for `aria-labelledby`.
+   * @default false
+   */
   asChild?: boolean;
 };
 
-/** Props for `Modal.Description` — supplies the dialog's accessible description. */
+/** Props for `Modal.Description` — supplies the dialog's accessible description (`aria-describedby`). */
 export type ModalDescriptionProps = HTMLAttributes<HTMLElement> & {
-  /** Render into the consumer's own element instead of a `<p>`. */
+  /**
+   * Render into the consumer's own element instead of the default `<p>`; the
+   * generated id is still registered for `aria-describedby`.
+   * @default false
+   */
   asChild?: boolean;
 };