@primitiv-ui/react 0.1.0

package/src/Modal/__tests__/Modal.controlled-state.test.tsx

@@ -0,0 +1,120 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { useState } from "react";
+
+import { Modal } from "../Modal";
+
+describe("Modal — controlled state", () => {
+  it("reflects the consumer's open prop on the trigger", () => {
+    // Arrange & Act
+    render(
+      <Modal.Root open={true} onOpenChange={() => undefined}>
+        <Modal.Trigger>Open</Modal.Trigger>
+      </Modal.Root>,
+    );
+
+    // Assert
+    expect(screen.getByRole("button", { name: "Open" })).toHaveAttribute(
+      "aria-expanded",
+      "true",
+    );
+  });
+
+  it("calls onOpenChange(true) when the trigger is clicked in controlled mode", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    const onOpenChange = vi.fn();
+    render(
+      <Modal.Root open={false} onOpenChange={onOpenChange}>
+        <Modal.Trigger>Open</Modal.Trigger>
+      </Modal.Root>,
+    );
+
+    // Act
+    await user.click(screen.getByRole("button", { name: "Open" }));
+
+    // Assert
+    expect(onOpenChange).toHaveBeenCalledTimes(1);
+    expect(onOpenChange).toHaveBeenCalledWith(true);
+  });
+
+  it("calls onOpenChange(false) when Modal.Close is clicked in controlled mode", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    const onOpenChange = vi.fn();
+    render(
+      <Modal.Root open={true} onOpenChange={onOpenChange}>
+        <Modal.Close>Close</Modal.Close>
+      </Modal.Root>,
+    );
+
+    // Act
+    await user.click(screen.getByRole("button", { name: "Close" }));
+
+    // Assert
+    expect(onOpenChange).toHaveBeenCalledWith(false);
+  });
+
+  it("does not flip state internally when controlled — consumer must drive open", async () => {
+    // Arrange: consumer renders with open=false and deliberately ignores changes
+    const user = userEvent.setup();
+    const onOpenChange = vi.fn();
+    render(
+      <Modal.Root open={false} onOpenChange={onOpenChange}>
+        <Modal.Trigger>Open</Modal.Trigger>
+      </Modal.Root>,
+    );
+    const trigger = screen.getByRole("button", { name: "Open" });
+
+    // Act
+    await user.click(trigger);
+
+    // Assert: aria-expanded stays false because consumer never flipped open
+    expect(trigger).toHaveAttribute("aria-expanded", "false");
+  });
+
+  it("updates when the consumer lifts state and drives open via onOpenChange", async () => {
+    // Arrange
+    function Wrapper() {
+      const [open, setOpen] = useState(false);
+      return (
+        <Modal.Root open={open} onOpenChange={setOpen}>
+          <Modal.Trigger>Open</Modal.Trigger>
+          <Modal.Close>Close</Modal.Close>
+        </Modal.Root>
+      );
+    }
+    const user = userEvent.setup();
+    render(<Wrapper />);
+    const trigger = screen.getByRole("button", { name: "Open" });
+
+    // Act
+    await user.click(trigger);
+
+    // Assert
+    expect(trigger).toHaveAttribute("aria-expanded", "true");
+
+    // Act
+    await user.click(screen.getByRole("button", { name: "Close" }));
+
+    // Assert
+    expect(trigger).toHaveAttribute("aria-expanded", "false");
+  });
+
+  it("calls onOpenChange from uncontrolled mode too (defaultOpen)", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    const onOpenChange = vi.fn();
+    render(
+      <Modal.Root defaultOpen={false} onOpenChange={onOpenChange}>
+        <Modal.Trigger>Open</Modal.Trigger>
+      </Modal.Root>,
+    );
+
+    // Act
+    await user.click(screen.getByRole("button", { name: "Open" }));
+
+    // Assert
+    expect(onOpenChange).toHaveBeenCalledWith(true);
+  });
+});

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

@@ -0,0 +1,30 @@
+import { render } from "@testing-library/react";
+
+import { Modal } from "../Modal";
+
+describe("Modal — error handling", () => {
+  describe("context consumer null guard", () => {
+    it.each([
+      ["Modal.Trigger", <Modal.Trigger key="t">Open</Modal.Trigger>],
+      ["Modal.Portal", <Modal.Portal key="p">portal</Modal.Portal>],
+      ["Modal.Overlay", <Modal.Overlay key="o" />],
+      ["Modal.Content", <Modal.Content key="c">content</Modal.Content>],
+      ["Modal.Title", <Modal.Title key="ti">title</Modal.Title>],
+      ["Modal.Description", <Modal.Description key="d">desc</Modal.Description>],
+      ["Modal.Close", <Modal.Close key="cl">close</Modal.Close>],
+    ])(
+      "%s throws when rendered outside Modal.Root",
+      (_name, element) => {
+        // Arrange
+        const err = vi.spyOn(console, "error").mockImplementation(() => undefined);
+
+        // Act & Assert
+        expect(() => render(element)).toThrow(
+          "Component must be rendered as a child of Modal.Root",
+        );
+
+        err.mockRestore();
+      },
+    );
+  });
+});

package/src/Modal/__tests__/Modal.escape-hatches.test.tsx

@@ -0,0 +1,99 @@
+import "./dialog-polyfill";
+
+import { act, fireEvent, render } from "@testing-library/react";
+
+import { Modal } from "../Modal";
+
+function getDialog() {
+  return document.querySelector("dialog") as HTMLDialogElement;
+}
+
+describe("Modal.Content — onEscapeKeyDown", () => {
+  it("fires onEscapeKeyDown when the native cancel event is dispatched (Esc)", () => {
+    // Arrange
+    const onEscapeKeyDown = vi.fn();
+    render(
+      <Modal.Root defaultOpen>
+        <Modal.Content onEscapeKeyDown={onEscapeKeyDown}>body</Modal.Content>
+      </Modal.Root>,
+    );
+
+    // Act
+    act(() => {
+      fireEvent(getDialog(), new Event("cancel", { cancelable: true }));
+    });
+
+    // Assert
+    expect(onEscapeKeyDown).toHaveBeenCalledTimes(1);
+  });
+
+  it("still closes the modal when the consumer does not veto", () => {
+    // Arrange
+    const onOpenChange = vi.fn();
+    const onEscapeKeyDown = vi.fn();
+    render(
+      <Modal.Root open={true} onOpenChange={onOpenChange}>
+        <Modal.Content onEscapeKeyDown={onEscapeKeyDown}>body</Modal.Content>
+      </Modal.Root>,
+    );
+
+    // Act
+    act(() => {
+      fireEvent(getDialog(), new Event("cancel", { cancelable: true }));
+    });
+
+    // Assert
+    expect(onOpenChange).toHaveBeenCalledWith(false);
+  });
+
+  it("does not close when the consumer calls event.preventDefault()", () => {
+    // Arrange
+    const onOpenChange = vi.fn();
+    render(
+      <Modal.Root open={true} onOpenChange={onOpenChange}>
+        <Modal.Content onEscapeKeyDown={(event) => event.preventDefault()}>
+          body
+        </Modal.Content>
+      </Modal.Root>,
+    );
+
+    // Act
+    act(() => {
+      fireEvent(getDialog(), new Event("cancel", { cancelable: true }));
+    });
+
+    // Assert
+    expect(onOpenChange).not.toHaveBeenCalled();
+  });
+
+  it("sees the latest onEscapeKeyDown across re-renders", () => {
+    // Arrange
+    const first = vi.fn();
+    const second = vi.fn();
+    const { rerender } = render(
+      <Modal.Root defaultOpen>
+        <Modal.Content onEscapeKeyDown={first}>body</Modal.Content>
+      </Modal.Root>,
+    );
+    rerender(
+      <Modal.Root defaultOpen>
+        <Modal.Content onEscapeKeyDown={second}>body</Modal.Content>
+      </Modal.Root>,
+    );
+
+    // Act
+    act(() => {
+      fireEvent(getDialog(), new Event("cancel", { cancelable: true }));
+    });
+
+    // Assert
+    expect(first).not.toHaveBeenCalled();
+    expect(second).toHaveBeenCalledTimes(1);
+  });
+});
+
+// onPointerDownOutside is driven by the dialog's own pointerdown event
+// and is covered in Modal.click-outside.test.tsx — it used to be wired
+// through the sibling Overlay's onClick, but the native <dialog>'s
+// ::backdrop paints over the overlay so that path was unreachable in
+// real browsers.

package/src/Modal/__tests__/Modal.imperative-api.test.tsx

@@ -0,0 +1,119 @@
+import "./dialog-polyfill";
+
+import { createRef } from "react";
+import { act, render, screen } from "@testing-library/react";
+
+import { Modal } from "../Modal";
+import { ModalImperativeApi } from "../types";
+
+describe("Modal imperative API", () => {
+  it("opens the modal via ref.current.open()", () => {
+    // Arrange
+    const ref = createRef<ModalImperativeApi>();
+    render(
+      <Modal.Root ref={ref}>
+        <Modal.Content>body</Modal.Content>
+      </Modal.Root>,
+    );
+    const dialog = document.querySelector("dialog") as HTMLDialogElement;
+    expect(dialog.hasAttribute("open")).toBe(false);
+
+    // Act
+    act(() => {
+      ref.current?.open();
+    });
+
+    // Assert
+    expect(dialog.hasAttribute("open")).toBe(true);
+  });
+
+  it("closes the modal via ref.current.close()", () => {
+    // Arrange
+    const ref = createRef<ModalImperativeApi>();
+    render(
+      <Modal.Root ref={ref} defaultOpen>
+        <Modal.Content>body</Modal.Content>
+      </Modal.Root>,
+    );
+    const dialog = document.querySelector("dialog") as HTMLDialogElement;
+    expect(dialog.hasAttribute("open")).toBe(true);
+
+    // Act
+    act(() => {
+      ref.current?.close();
+    });
+
+    // Assert
+    expect(dialog.hasAttribute("open")).toBe(false);
+  });
+
+  it("notifies onOpenChange when opened or closed imperatively", () => {
+    // Arrange
+    const ref = createRef<ModalImperativeApi>();
+    const onOpenChange = vi.fn();
+    render(
+      <Modal.Root ref={ref} onOpenChange={onOpenChange}>
+        <Modal.Content>body</Modal.Content>
+      </Modal.Root>,
+    );
+
+    // Act
+    act(() => {
+      ref.current?.open();
+    });
+
+    // Assert
+    expect(onOpenChange).toHaveBeenNthCalledWith(1, true);
+
+    // Act
+    act(() => {
+      ref.current?.close();
+    });
+
+    // Assert
+    expect(onOpenChange).toHaveBeenNthCalledWith(2, false);
+  });
+
+  it("works in controlled mode by delegating to the consumer's onOpenChange", () => {
+    // Arrange
+    const ref = createRef<ModalImperativeApi>();
+    const onOpenChange = vi.fn();
+    render(
+      <Modal.Root ref={ref} open={false} onOpenChange={onOpenChange}>
+        <Modal.Content>body</Modal.Content>
+      </Modal.Root>,
+    );
+
+    // Act
+    act(() => {
+      ref.current?.open();
+    });
+
+    // Assert — controlled mode: the library asks the parent to open
+    expect(onOpenChange).toHaveBeenCalledWith(true);
+    // And does NOT flip internal state; parent must re-render
+    const dialog = document.querySelector("dialog") as HTMLDialogElement;
+    expect(dialog.hasAttribute("open")).toBe(false);
+  });
+
+  it("Modal.Trigger still works alongside the imperative API", async () => {
+    // Arrange
+    const ref = createRef<ModalImperativeApi>();
+    const { rerender: _ } = render(
+      <Modal.Root ref={ref}>
+        <Modal.Trigger>Open</Modal.Trigger>
+        <Modal.Content>body</Modal.Content>
+      </Modal.Root>,
+    );
+    const trigger = screen.getByRole("button", { name: "Open" });
+    expect(trigger).toHaveAttribute("aria-expanded", "false");
+
+    // Act
+    act(() => {
+      ref.current?.open();
+    });
+
+    // Assert
+    expect(trigger).toHaveAttribute("aria-expanded", "true");
+  });
+});

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

@@ -0,0 +1,106 @@
+import "./dialog-polyfill";
+
+import { act, fireEvent, render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { useState } from "react";
+
+import { Modal } from "../Modal";
+
+describe("Modal — nested dialogs", () => {
+  function NestedModals() {
+    const [outerOpen, setOuterOpen] = useState(true);
+    const [innerOpen, setInnerOpen] = useState(true);
+    return (
+      <Modal.Root open={outerOpen} onOpenChange={setOuterOpen}>
+        <Modal.Portal>
+          <Modal.Overlay data-testid="outer-overlay" />
+          <Modal.Content data-testid="outer-content">
+            <Modal.Close>Close outer</Modal.Close>
+            <Modal.Root open={innerOpen} onOpenChange={setInnerOpen}>
+              <Modal.Portal>
+                <Modal.Overlay data-testid="inner-overlay" />
+                <Modal.Content data-testid="inner-content">
+                  <Modal.Close>Close inner</Modal.Close>
+                </Modal.Content>
+              </Modal.Portal>
+            </Modal.Root>
+          </Modal.Content>
+        </Modal.Portal>
+      </Modal.Root>
+    );
+  }
+
+  it("closes only the inner modal when the inner Close button is clicked", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    render(<NestedModals />);
+    expect(screen.getByTestId("outer-content")).toHaveAttribute(
+      "data-state",
+      "open",
+    );
+    expect(screen.getByTestId("inner-content")).toHaveAttribute(
+      "data-state",
+      "open",
+    );
+
+    // Act
+    await user.click(screen.getByRole("button", { name: "Close inner" }));
+
+    // Assert — inner closed, outer still open
+    expect(screen.queryByTestId("inner-content")).toBeNull();
+    expect(screen.getByTestId("outer-content")).toHaveAttribute(
+      "data-state",
+      "open",
+    );
+  });
+
+  it("closes only the inner modal when a pointerdown lands on the inner dialog's backdrop", () => {
+    // Arrange
+    render(<NestedModals />);
+    const innerDialog = screen.getByTestId(
+      "inner-content",
+    ) as HTMLDialogElement;
+    innerDialog.getBoundingClientRect = () =>
+      ({
+        left: 100,
+        top: 100,
+        right: 300,
+        bottom: 300,
+        x: 100,
+        y: 100,
+        width: 200,
+        height: 200,
+        toJSON: () => ({}),
+      }) as DOMRect;
+
+    // Act — pointerdown at (50, 50), outside the inner dialog's rect
+    act(() => {
+      fireEvent.pointerDown(innerDialog, { clientX: 50, clientY: 50 });
+    });
+
+    // Assert
+    expect(screen.queryByTestId("inner-content")).toBeNull();
+    expect(screen.getByTestId("outer-content")).toHaveAttribute(
+      "data-state",
+      "open",
+    );
+  });
+
+  it("closes only the inner modal when the native cancel event fires on the inner dialog", () => {
+    // Arrange
+    render(<NestedModals />);
+    const innerDialog = screen.getByTestId("inner-content");
+
+    // Act — native cancel (Esc) on the inner dialog
+    act(() => {
+      fireEvent(innerDialog, new Event("cancel", { cancelable: true }));
+    });
+
+    // Assert — inner dialog has unmounted, outer remains open
+    expect(screen.queryByTestId("inner-content")).toBeNull();
+    expect(screen.getByTestId("outer-content")).toHaveAttribute(
+      "data-state",
+      "open",
+    );
+  });
+});

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

@@ -0,0 +1,99 @@
+import "./dialog-polyfill";
+
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import { Modal } from "../Modal";
+
+describe("Modal.Overlay", () => {
+  it("renders only when the modal is open", () => {
+    // Arrange & Act
+    render(
+      <Modal.Root>
+        <Modal.Portal>
+          <Modal.Overlay data-testid="overlay" />
+          <Modal.Content>body</Modal.Content>
+        </Modal.Portal>
+      </Modal.Root>,
+    );
+
+    // Assert
+    expect(screen.queryByTestId("overlay")).toBeNull();
+  });
+
+  it('renders with data-state="open" when the modal is open', () => {
+    // Arrange & Act
+    render(
+      <Modal.Root defaultOpen>
+        <Modal.Portal>
+          <Modal.Overlay data-testid="overlay" />
+          <Modal.Content>body</Modal.Content>
+        </Modal.Portal>
+      </Modal.Root>,
+    );
+
+    // Assert
+    expect(screen.getByTestId("overlay")).toHaveAttribute(
+      "data-state",
+      "open",
+    );
+  });
+
+  it('declares aria-hidden="true" so the decorative backdrop is skipped by screen readers', () => {
+    // Arrange & Act
+    render(
+      <Modal.Root defaultOpen>
+        <Modal.Portal>
+          <Modal.Overlay data-testid="overlay" />
+          <Modal.Content>body</Modal.Content>
+        </Modal.Portal>
+      </Modal.Root>,
+    );
+
+    // Assert
+    expect(screen.getByTestId("overlay")).toHaveAttribute(
+      "aria-hidden",
+      "true",
+    );
+  });
+
+  it("does not close the modal when clicked — the native <dialog>'s ::backdrop paints over this div, so click-outside is wired on the dialog itself", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    const onOpenChange = vi.fn();
+    render(
+      <Modal.Root open={true} onOpenChange={onOpenChange}>
+        <Modal.Portal>
+          <Modal.Overlay data-testid="overlay" />
+          <Modal.Content>body</Modal.Content>
+        </Modal.Portal>
+      </Modal.Root>,
+    );
+
+    // Act
+    await user.click(screen.getByTestId("overlay"));
+
+    // Assert — overlay click is a no-op for closing; see Modal.click-outside.test.tsx
+    expect(onOpenChange).not.toHaveBeenCalled();
+  });
+
+  it("still forwards consumer onClick handlers", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    const onClick = vi.fn();
+    render(
+      <Modal.Root defaultOpen>
+        <Modal.Portal>
+          <Modal.Overlay data-testid="overlay" onClick={onClick} />
+          <Modal.Content>body</Modal.Content>
+        </Modal.Portal>
+      </Modal.Root>,
+    );
+
+    // Act
+    await user.click(screen.getByTestId("overlay"));
+
+    // Assert
+    expect(onClick).toHaveBeenCalledTimes(1);
+  });
+});

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

@@ -0,0 +1,90 @@
+import "./dialog-polyfill";
+
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import { Modal } from "../Modal";
+
+describe("Modal.Portal", () => {
+  it("renders its children into document.body by default when open", () => {
+    // Arrange & Act
+    render(
+      <section data-testid="tree-root">
+        <Modal.Root defaultOpen>
+          <Modal.Portal>
+            <div data-testid="portaled">hello</div>
+          </Modal.Portal>
+        </Modal.Root>
+      </section>,
+    );
+
+    // Assert
+    const portaled = screen.getByTestId("portaled");
+    expect(document.body).toContainElement(portaled);
+    // Not nested under the Root's React parent
+    expect(screen.getByTestId("tree-root")).not.toContainElement(portaled);
+  });
+
+  it("renders children into a consumer-supplied container element", () => {
+    // Arrange
+    const container = document.createElement("div");
+    container.id = "custom-modal-root";
+    document.body.appendChild(container);
+
+    // Act
+    render(
+      <Modal.Root defaultOpen>
+        <Modal.Portal container={container}>
+          <div data-testid="portaled">hello</div>
+        </Modal.Portal>
+      </Modal.Root>,
+    );
+
+    // Assert
+    expect(container).toContainElement(screen.getByTestId("portaled"));
+
+    // Cleanup
+    document.body.removeChild(container);
+  });
+
+  it("does not render children when the modal is closed", () => {
+    // Arrange & Act
+    render(
+      <Modal.Root>
+        <Modal.Portal>
+          <div data-testid="portaled">hello</div>
+        </Modal.Portal>
+      </Modal.Root>,
+    );
+
+    // Assert
+    expect(screen.queryByTestId("portaled")).toBeNull();
+  });
+
+  it("mounts children when the modal opens and unmounts them when it closes", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    render(
+      <Modal.Root>
+        <Modal.Trigger>Open</Modal.Trigger>
+        <Modal.Close>Close</Modal.Close>
+        <Modal.Portal>
+          <div data-testid="portaled">hello</div>
+        </Modal.Portal>
+      </Modal.Root>,
+    );
+    expect(screen.queryByTestId("portaled")).toBeNull();
+
+    // Act
+    await user.click(screen.getByRole("button", { name: "Open" }));
+
+    // Assert
+    expect(screen.getByTestId("portaled")).toBeInTheDocument();
+
+    // Act
+    await user.click(screen.getByRole("button", { name: "Close" }));
+
+    // Assert
+    expect(screen.queryByTestId("portaled")).toBeNull();
+  });
+});