@primitiv-ui/react 0.1.38 → 0.1.40

package/src/Modal/README.md

@@ -1,222 +0,0 @@
-# Modal
-
-A headless, accessible compound component implementing the
-[WAI-ARIA Modal Dialog pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/).
-
-Modal is built on the native
-[`<dialog>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dialog)
-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`.
-- A portal for placing the dialog at the end of `document.body`.
-- Controlled / uncontrolled state plumbing.
-- `asChild` composition for every slot-able sub-component.
-- An imperative API for firing open/close from outside the subtree.
-- `forceMount` hooks for driving CSS exit animations.
-
-### Why is click-outside on the dialog, not the overlay?
-
-`showModal()` promotes the `<dialog>` into the browser's **top layer**
-and paints a `::backdrop` pseudo-element underneath it — also in the
-top layer. Any sibling `Modal.Overlay` sits _below_ that backdrop
-visually, so clicks on the "outside" area never reach it. Detection
-therefore has to live on the dialog itself: a `pointerdown` whose
-coordinates fall outside the dialog's bounding rect is, by
-elimination, a click on the backdrop. `Modal.Overlay` stays in the
-tree as a cosmetic + animation surface (for custom backdrop styling
-or motion wrappers that exceed what `::backdrop` can express).
-
-```tsx
-import { Modal } from "@primitiv-ui/react";
-
-<Modal.Root open={open} onOpenChange={setOpen}>
-  <Modal.Trigger>Open</Modal.Trigger>
-  <Modal.Portal>
-    <Modal.Overlay />
-    <Modal.Content>
-      <Modal.Title>Payment</Modal.Title>
-      <Modal.Description>Enter your card details</Modal.Description>
-      {/* body */}
-      <Modal.Close>Cancel</Modal.Close>
-    </Modal.Content>
-  </Modal.Portal>
-</Modal.Root>;
-```
-
-This headless layer is structure-only. The **styled distribution** (`primitiv add
-modal`) composes these primitives into the full Figma anatomy — a divided
-header / body / footer, and an icon-button close (a ghost `Button` + `Close` icon
-via `Modal.Close asChild`, sized one step below the dialog). See that package's
-README for the canonical composed example; nothing below changes.
-
-## Sub-components
-
-| Export              | Element           | Notes                                                                                                                                          |
-| ------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| `Modal.Root`        | context provider  | Owns open state. Exposes `ModalImperativeApi` via `ref`                                                                                        |
-| `Modal.Trigger`     | `<button>`        | `aria-haspopup="dialog"`, `aria-expanded`, `aria-controls`. `asChild`                                                                          |
-| `Modal.Portal`      | `createPortal`    | `container?: HTMLElement` (default `document.body`). `forceMount`                                                                              |
-| `Modal.Overlay`     | `<div>` (sibling) | Decorative / animation target — **not** a click-outside event surface (see below). `aria-hidden="true"`. `data-state`. `asChild`, `forceMount` |
-| `Modal.Content`     | `<dialog>`        | Native modal dialog. `data-state`. Escape hatches for Esc / click-outside                                                                      |
-| `Modal.Title`       | `<h2>`            | Auto-wires `aria-labelledby` on Content. `asChild`                                                                                             |
-| `Modal.Description` | `<p>`             | Auto-wires `aria-describedby` on Content. `asChild`                                                                                            |
-| `Modal.Close`       | `<button>`        | Closes the modal. `asChild`                                                                                                                    |
-
-## Keyboard interaction
-
-| 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
-
-- **Uncontrolled** — pass `defaultOpen` (or omit for closed on mount).
-- **Controlled** — pass `open` **and** `onOpenChange` together.
-
-The two shapes are statically discriminated at the type level; TypeScript
-rejects mixing them.
-
-```tsx
-// Uncontrolled
-<Modal.Root defaultOpen>...</Modal.Root>;
-
-// Controlled
-const [open, setOpen] = useState(false);
-<Modal.Root open={open} onOpenChange={setOpen}>
-  ...
-</Modal.Root>;
-```
-
-## Escape hatches
-
-Both close paths — `Esc` and click-outside — fire observable callbacks
-on `Modal.Content`. Call `event.preventDefault()` to keep the modal
-open. `onPointerDownOutside` receives the native `PointerEvent`
-(fires on `pointerdown`, not `click`, matching the prop name).
-
-```tsx
-<Modal.Content
-  onEscapeKeyDown={(event) => {
-    if (hasUnsavedChanges) event.preventDefault();
-  }}
-  onPointerDownOutside={(event) => {
-    if (isRequiredFlow) event.preventDefault();
-  }}
->
-  ...
-</Modal.Content>
-```
-
-## Imperative API
-
-```tsx
-import { Modal, type ModalImperativeApi } from "@primitiv-ui/react";
-
-const ref = useRef<ModalImperativeApi>(null);
-
-<Modal.Root ref={ref}>...</Modal.Root>;
-
-ref.current?.open();
-ref.current?.close();
-```
-
-In controlled mode the imperative methods delegate to `onOpenChange` —
-the parent stays in charge of the actual state update.
-
-## `asChild` composition
-
-`Modal.Trigger`, `Modal.Close`, `Modal.Title`, `Modal.Description`, and
-`Modal.Overlay` accept an `asChild` boolean. When set, the component
-delegates rendering to its single child element and merges its own ARIA
-attributes, ids, composed event handlers, and ref onto the child
-following the asChild pattern (child handler runs first, then the
-library's). `Modal.Overlay` is decorative and has no library-side
-handlers, so only its ARIA and `data-state` are forwarded.
-
-```tsx
-// Router link with dialog-trigger semantics
-<Modal.Trigger asChild>
-  <Link to="/upgrade">Upgrade</Link>
-</Modal.Trigger>
-
-// Alternate heading level
-<Modal.Title asChild>
-  <h3>Payment</h3>
-</Modal.Title>
-
-// Motion wrapper on the backdrop
-<Modal.Overlay asChild>
-  <motion.div initial={{ opacity: 0 }} animate={{ opacity: 1 }} />
-</Modal.Overlay>
-```
-
-`Modal.Content` is intentionally **not** slot-able. Its native
-`<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
-
-`Modal.Portal` and `Modal.Overlay` accept a `forceMount` boolean. When
-set, the subtree stays in the DOM regardless of `open` state so a CSS
-animation can play against the `data-state="closed"` attribute:
-
-```tsx
-<Modal.Portal forceMount>
-  <Modal.Overlay forceMount />
-  <Modal.Content>...</Modal.Content>
-</Modal.Portal>
-```
-
-```css
-[data-state="open"] {
-  animation: fade-in var(--primitiv-motion-duration-control) var(--primitiv-motion-easing-enter);
-}
-[data-state="closed"] {
-  animation: fade-out var(--primitiv-motion-duration-feedback) var(--primitiv-motion-easing-exit) forwards;
-}
-```
-
-Consumers who use `forceMount` own the unmount lifecycle themselves
-(e.g. by tracking a separate `presence` state that flips false only
-once the exit animation ends).
-
-## Scroll lock
-
-Modal intentionally ships no JavaScript scroll lock. The one-line CSS
-equivalent works in every modern browser:
-
-```css
-html:has(dialog[open]) {
-  overflow: hidden;
-}
-```
-
-## Styling hooks
-
-`data-state="open" | "closed"` is set on `Modal.Overlay` and
-`Modal.Content`, letting any CSS system target the two phases.
-
-```css
-dialog[data-state="open"] {
-  display: grid;
-  place-items: center;
-}
-
-dialog::backdrop {
-  background: oklch(0 0 0 / 0.6);
-}
-```

package/src/Modal/__tests__/Modal.accessibility.test.tsx

@@ -1,167 +0,0 @@
-import "./dialog-polyfill";
-
-import { render, screen } from "@testing-library/react";
-
-import { Modal } from "../Modal";
-
-function getDialog() {
-  return document.querySelector("dialog") as HTMLDialogElement;
-}
-
-describe("Modal accessibility — Title and Description", () => {
-  it("renders Title as an <h2> with its children", () => {
-    // Arrange & Act
-    render(
-      <Modal.Root defaultOpen>
-        <Modal.Content>
-          <Modal.Title>Payment</Modal.Title>
-        </Modal.Content>
-      </Modal.Root>,
-    );
-
-    // Assert
-    const heading = screen.getByRole("heading", { level: 2, name: "Payment" });
-    expect(heading.tagName).toBe("H2");
-  });
-
-  it("renders Description as a <p> with its children", () => {
-    // Arrange & Act
-    render(
-      <Modal.Root defaultOpen>
-        <Modal.Content>
-          <Modal.Description>Enter your card details</Modal.Description>
-        </Modal.Content>
-      </Modal.Root>,
-    );
-
-    // Assert
-    const paragraph = screen.getByText("Enter your card details");
-    expect(paragraph.tagName).toBe("P");
-  });
-
-  it("wires aria-labelledby on the dialog to the Title's id", () => {
-    // Arrange & Act
-    render(
-      <Modal.Root defaultOpen>
-        <Modal.Content>
-          <Modal.Title>Payment</Modal.Title>
-        </Modal.Content>
-      </Modal.Root>,
-    );
-
-    // Assert
-    const heading = screen.getByRole("heading", { level: 2, name: "Payment" });
-    const dialog = getDialog();
-    expect(heading.id).toBeTruthy();
-    expect(dialog).toHaveAttribute("aria-labelledby", heading.id);
-  });
-
-  it("wires aria-describedby on the dialog to the Description's id", () => {
-    // Arrange & Act
-    render(
-      <Modal.Root defaultOpen>
-        <Modal.Content>
-          <Modal.Description>Enter your card details</Modal.Description>
-        </Modal.Content>
-      </Modal.Root>,
-    );
-
-    // Assert
-    const paragraph = screen.getByText("Enter your card details");
-    const dialog = getDialog();
-    expect(paragraph.id).toBeTruthy();
-    expect(dialog).toHaveAttribute("aria-describedby", paragraph.id);
-  });
-
-  it("has neither aria-labelledby nor aria-describedby when Title/Description are absent", () => {
-    // Arrange & Act
-    render(
-      <Modal.Root defaultOpen>
-        <Modal.Content data-testid="content">body</Modal.Content>
-      </Modal.Root>,
-    );
-
-    // Assert
-    const dialog = getDialog();
-    expect(dialog).not.toHaveAttribute("aria-labelledby");
-    expect(dialog).not.toHaveAttribute("aria-describedby");
-  });
-
-  it("drops aria-labelledby when the Title unmounts", () => {
-    // Arrange
-    const { rerender } = render(
-      <Modal.Root defaultOpen>
-        <Modal.Content>
-          <Modal.Title>Payment</Modal.Title>
-        </Modal.Content>
-      </Modal.Root>,
-    );
-    expect(getDialog()).toHaveAttribute("aria-labelledby");
-
-    // Act
-    rerender(
-      <Modal.Root defaultOpen>
-        <Modal.Content>body</Modal.Content>
-      </Modal.Root>,
-    );
-
-    // Assert
-    expect(getDialog()).not.toHaveAttribute("aria-labelledby");
-  });
-
-  it("drops aria-describedby when the Description unmounts", () => {
-    // Arrange
-    const { rerender } = render(
-      <Modal.Root defaultOpen>
-        <Modal.Content>
-          <Modal.Description>Enter your card details</Modal.Description>
-        </Modal.Content>
-      </Modal.Root>,
-    );
-    expect(getDialog()).toHaveAttribute("aria-describedby");
-
-    // Act
-    rerender(
-      <Modal.Root defaultOpen>
-        <Modal.Content>body</Modal.Content>
-      </Modal.Root>,
-    );
-
-    // Assert
-    expect(getDialog()).not.toHaveAttribute("aria-describedby");
-  });
-
-  it("forwards extra HTML attributes (e.g. className) to the Description element", () => {
-    // Arrange & Act
-    render(
-      <Modal.Root defaultOpen>
-        <Modal.Content>
-          <Modal.Description className="my-description" data-testid="desc-el">
-            Enter your card details
-          </Modal.Description>
-        </Modal.Content>
-      </Modal.Root>,
-    );
-
-    // Assert
-    const paragraph = screen.getByTestId("desc-el");
-    expect(paragraph).toHaveClass("my-description");
-  });
-
-  it("forwards extra HTML attributes (e.g. className) to the Title element", () => {
-    // Arrange & Act
-    render(
-      <Modal.Root defaultOpen>
-        <Modal.Content>
-          <Modal.Title className="my-title" data-testid="title-el">
-            Payment
-          </Modal.Title>
-        </Modal.Content>
-      </Modal.Root>,
-    );
-
-    // Assert
-    const heading = screen.getByTestId("title-el");
-    expect(heading).toHaveClass("my-title");
-  });
-});

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

@@ -1,162 +0,0 @@
-import "./dialog-polyfill";
-
-import { createRef } from "react";
-import { render, screen } from "@testing-library/react";
-import userEvent from "@testing-library/user-event";
-
-import { Modal } from "../Modal";
-
-describe("Modal.Trigger — asChild", () => {
-  it("renders the consumer-supplied element instead of a button", () => {
-    // Arrange & Act
-    render(
-      <Modal.Root>
-        <Modal.Trigger asChild>
-          <a href="/foo" data-testid="link">
-            Open
-          </a>
-        </Modal.Trigger>
-      </Modal.Root>,
-    );
-
-    // Assert
-    const link = screen.getByTestId("link");
-    expect(link.tagName).toBe("A");
-    expect(link).toHaveAttribute("aria-haspopup", "dialog");
-    expect(link).toHaveAttribute("aria-expanded", "false");
-    expect(link).toHaveAttribute("aria-controls");
-  });
-
-  it("still opens the modal when the slotted element is clicked", async () => {
-    // Arrange
-    const user = userEvent.setup();
-    const onOpenChange = vi.fn();
-    render(
-      <Modal.Root onOpenChange={onOpenChange}>
-        <Modal.Trigger asChild>
-          <a href="/foo" data-testid="link">
-            Open
-          </a>
-        </Modal.Trigger>
-      </Modal.Root>,
-    );
-
-    // Act
-    await user.click(screen.getByTestId("link"));
-
-    // Assert
-    expect(onOpenChange).toHaveBeenCalledWith(true);
-  });
-
-  it("composes the consumer's ref with the library's", () => {
-    // Arrange
-    const ref = createRef<HTMLAnchorElement>();
-
-    // Act
-    render(
-      <Modal.Root>
-        <Modal.Trigger asChild>
-          <a ref={ref} href="/foo" data-testid="link">
-            Open
-          </a>
-        </Modal.Trigger>
-      </Modal.Root>,
-    );
-
-    // Assert
-    expect(ref.current).toBe(screen.getByTestId("link"));
-  });
-});
-
-describe("Modal.Close — asChild", () => {
-  it("renders the consumer-supplied element and closes on click", async () => {
-    // Arrange
-    const user = userEvent.setup();
-    const onOpenChange = vi.fn();
-    render(
-      <Modal.Root open={true} onOpenChange={onOpenChange}>
-        <Modal.Content>
-          <Modal.Close asChild>
-            <a href="#" data-testid="close-link">
-              Dismiss
-            </a>
-          </Modal.Close>
-        </Modal.Content>
-      </Modal.Root>,
-    );
-
-    // Act
-    await user.click(screen.getByTestId("close-link"));
-
-    // Assert
-    const link = screen.getByTestId("close-link");
-    expect(link.tagName).toBe("A");
-    expect(onOpenChange).toHaveBeenCalledWith(false);
-  });
-});
-
-describe("Modal.Title — asChild", () => {
-  it("renders the consumer-supplied heading and still registers aria-labelledby", () => {
-    // Arrange & Act
-    render(
-      <Modal.Root defaultOpen>
-        <Modal.Content>
-          <Modal.Title asChild>
-            <h3 data-testid="custom-title">Payment</h3>
-          </Modal.Title>
-        </Modal.Content>
-      </Modal.Root>,
-    );
-
-    // Assert
-    const heading = screen.getByTestId("custom-title");
-    expect(heading.tagName).toBe("H3");
-    const dialog = document.querySelector("dialog") as HTMLDialogElement;
-    expect(dialog).toHaveAttribute("aria-labelledby", heading.id);
-    expect(heading.id).toBeTruthy();
-  });
-});
-
-describe("Modal.Description — asChild", () => {
-  it("renders the consumer-supplied element and still registers aria-describedby", () => {
-    // Arrange & Act
-    render(
-      <Modal.Root defaultOpen>
-        <Modal.Content>
-          <Modal.Description asChild>
-            <div data-testid="custom-description">Enter card details</div>
-          </Modal.Description>
-        </Modal.Content>
-      </Modal.Root>,
-    );
-
-    // Assert
-    const description = screen.getByTestId("custom-description");
-    expect(description.tagName).toBe("DIV");
-    const dialog = document.querySelector("dialog") as HTMLDialogElement;
-    expect(dialog).toHaveAttribute("aria-describedby", description.id);
-    expect(description.id).toBeTruthy();
-  });
-});
-
-describe("Modal.Overlay — asChild", () => {
-  it("renders the consumer-supplied element with the overlay's ARIA and data-state forwarded", () => {
-    // Arrange & Act
-    render(
-      <Modal.Root defaultOpen>
-        <Modal.Portal>
-          <Modal.Overlay asChild>
-            <section data-testid="custom-overlay" />
-          </Modal.Overlay>
-          <Modal.Content>body</Modal.Content>
-        </Modal.Portal>
-      </Modal.Root>,
-    );
-    const overlay = screen.getByTestId("custom-overlay");
-
-    // Assert — Slot-composed tag, ARIA, and data-state are forwarded to the consumer element
-    expect(overlay.tagName).toBe("SECTION");
-    expect(overlay).toHaveAttribute("aria-hidden", "true");
-    expect(overlay).toHaveAttribute("data-state", "open");
-  });
-});

package/src/Modal/__tests__/Modal.click-outside.test.tsx

@@ -1,115 +0,0 @@
-import "./dialog-polyfill";
-
-import { act, fireEvent, render } from "@testing-library/react";
-
-import { Modal } from "../Modal";
-
-function getDialog() {
-  return document.querySelector("dialog") as HTMLDialogElement;
-}
-
-function stubRect(
-  dialog: HTMLDialogElement,
-  rect: { left: number; top: number; right: number; bottom: number },
-) {
-  const domRect = {
-    ...rect,
-    x: rect.left,
-    y: rect.top,
-    width: rect.right - rect.left,
-    height: rect.bottom - rect.top,
-    toJSON() {
-      return this;
-    },
-  } as DOMRect;
-  dialog.getBoundingClientRect = () => domRect;
-}
-
-describe("Modal.Content — click-outside via dialog bounding rect", () => {
-  it("closes the modal when pointerdown lands outside the dialog's rect (the native ::backdrop area)", () => {
-    // Arrange — dialog occupies the middle 200x200 of the viewport
-    const onOpenChange = vi.fn();
-    render(
-      <Modal.Root open={true} onOpenChange={onOpenChange}>
-        <Modal.Content>body</Modal.Content>
-      </Modal.Root>,
-    );
-    const dialog = getDialog();
-    stubRect(dialog, { left: 100, top: 100, right: 300, bottom: 300 });
-
-    // Act — pointerdown at (50, 50), outside the rect
-    act(() => {
-      fireEvent.pointerDown(dialog, { clientX: 50, clientY: 50 });
-    });
-
-    // Assert
-    expect(onOpenChange).toHaveBeenCalledWith(false);
-  });
-
-  it("does not close the modal when pointerdown lands inside the dialog's rect (content or padding)", () => {
-    // Arrange
-    const onOpenChange = vi.fn();
-    render(
-      <Modal.Root open={true} onOpenChange={onOpenChange}>
-        <Modal.Content>body</Modal.Content>
-      </Modal.Root>,
-    );
-    const dialog = getDialog();
-    stubRect(dialog, { left: 100, top: 100, right: 300, bottom: 300 });
-
-    // Act — pointerdown at (200, 200), inside the rect
-    act(() => {
-      fireEvent.pointerDown(dialog, { clientX: 200, clientY: 200 });
-    });
-
-    // Assert
-    expect(onOpenChange).not.toHaveBeenCalled();
-  });
-
-  it("fires onPointerDownOutside with the native event when the backdrop is pressed", () => {
-    // Arrange
-    const onPointerDownOutside = vi.fn();
-    render(
-      <Modal.Root defaultOpen>
-        <Modal.Content onPointerDownOutside={onPointerDownOutside}>
-          body
-        </Modal.Content>
-      </Modal.Root>,
-    );
-    const dialog = getDialog();
-    stubRect(dialog, { left: 100, top: 100, right: 300, bottom: 300 });
-
-    // Act
-    act(() => {
-      fireEvent.pointerDown(dialog, { clientX: 50, clientY: 50 });
-    });
-
-    // Assert
-    expect(onPointerDownOutside).toHaveBeenCalledTimes(1);
-    expect(onPointerDownOutside.mock.calls[0][0]).toBeInstanceOf(Event);
-  });
-
-  it("does not close when the consumer's onPointerDownOutside calls event.preventDefault()", () => {
-    // Arrange
-    const onOpenChange = vi.fn();
-    render(
-      <Modal.Root open={true} onOpenChange={onOpenChange}>
-        <Modal.Content
-          onPointerDownOutside={(event) => event.preventDefault()}
-        >
-          body
-        </Modal.Content>
-      </Modal.Root>,
-    );
-    const dialog = getDialog();
-    stubRect(dialog, { left: 100, top: 100, right: 300, bottom: 300 });
-
-    // Act
-    act(() => {
-      fireEvent.pointerDown(dialog, { clientX: 50, clientY: 50 });
-    });
-
-    // Assert
-    expect(onOpenChange).not.toHaveBeenCalled();
-  });
-});