@primitiv-ui/react 0.1.0

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

@@ -0,0 +1,111 @@
+import "./dialog-polyfill";
+
+import { render, screen } from "@testing-library/react";
+
+import { Modal } from "../Modal";
+
+describe("Modal forceMount", () => {
+  describe("Modal.Portal", () => {
+    it("renders children while closed when forceMount is set", () => {
+      // Arrange & Act
+      render(
+        <Modal.Root>
+          <Modal.Portal forceMount>
+            <div data-testid="portaled">hello</div>
+          </Modal.Portal>
+        </Modal.Root>,
+      );
+
+      // Assert
+      expect(screen.getByTestId("portaled")).toBeInTheDocument();
+    });
+
+    it("still renders into a custom container when forceMount is set", () => {
+      // Arrange
+      const container = document.createElement("div");
+      document.body.appendChild(container);
+
+      // Act
+      render(
+        <Modal.Root>
+          <Modal.Portal forceMount container={container}>
+            <div data-testid="portaled">hello</div>
+          </Modal.Portal>
+        </Modal.Root>,
+      );
+
+      // Assert
+      expect(container).toContainElement(screen.getByTestId("portaled"));
+
+      // Cleanup
+      document.body.removeChild(container);
+    });
+  });
+
+  describe("Modal.Overlay", () => {
+    it("does not render while closed when only the Portal forceMounts", () => {
+      // Arrange & Act — Portal stays mounted but Overlay opts out of forceMount
+      render(
+        <Modal.Root>
+          <Modal.Portal forceMount>
+            <Modal.Overlay data-testid="overlay" />
+            <Modal.Content>body</Modal.Content>
+          </Modal.Portal>
+        </Modal.Root>,
+      );
+
+      // Assert — Overlay short-circuits independently
+      expect(screen.queryByTestId("overlay")).toBeNull();
+    });
+
+    it('renders with data-state="closed" while closed when forceMount is set', () => {
+      // Arrange & Act
+      render(
+        <Modal.Root>
+          <Modal.Portal forceMount>
+            <Modal.Overlay data-testid="overlay" forceMount />
+            <Modal.Content>body</Modal.Content>
+          </Modal.Portal>
+        </Modal.Root>,
+      );
+
+      // Assert
+      expect(screen.getByTestId("overlay")).toHaveAttribute(
+        "data-state",
+        "closed",
+      );
+    });
+
+    it("flips data-state to open when the modal opens", () => {
+      // Arrange
+      const { rerender } = render(
+        <Modal.Root>
+          <Modal.Portal forceMount>
+            <Modal.Overlay data-testid="overlay" forceMount />
+            <Modal.Content>body</Modal.Content>
+          </Modal.Portal>
+        </Modal.Root>,
+      );
+      expect(screen.getByTestId("overlay")).toHaveAttribute(
+        "data-state",
+        "closed",
+      );
+
+      // Act
+      rerender(
+        <Modal.Root open onOpenChange={() => undefined}>
+          <Modal.Portal forceMount>
+            <Modal.Overlay data-testid="overlay" forceMount />
+            <Modal.Content>body</Modal.Content>
+          </Modal.Portal>
+        </Modal.Root>,
+      );
+
+      // Assert
+      expect(screen.getByTestId("overlay")).toHaveAttribute(
+        "data-state",
+        "open",
+      );
+    });
+  });
+});

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

@@ -0,0 +1,70 @@
+import "./dialog-polyfill";
+
+import { render, screen } from "@testing-library/react";
+
+import { Modal } from "../Modal";
+
+describe("Modal.Trigger", () => {
+  it('declares aria-haspopup="dialog"', () => {
+    // Arrange & Act
+    render(
+      <Modal.Root>
+        <Modal.Trigger>Open</Modal.Trigger>
+      </Modal.Root>,
+    );
+
+    // Assert
+    expect(screen.getByRole("button", { name: "Open" })).toHaveAttribute(
+      "aria-haspopup",
+      "dialog",
+    );
+  });
+
+  it("references the content via aria-controls using the same id the content will render with", () => {
+    // Arrange & Act
+    render(
+      <Modal.Root defaultOpen>
+        <Modal.Trigger>Open</Modal.Trigger>
+        <Modal.Portal>
+          <Modal.Content>hi</Modal.Content>
+        </Modal.Portal>
+      </Modal.Root>,
+    );
+    const trigger = screen.getByRole("button", { name: "Open" });
+
+    // Assert
+    const controlsId = trigger.getAttribute("aria-controls");
+    expect(controlsId).toBeTruthy();
+    expect(document.getElementById(controlsId!)).not.toBeNull();
+  });
+
+  it("defaults to type=button so the trigger never submits an enclosing form", () => {
+    // Arrange & Act
+    render(
+      <Modal.Root>
+        <Modal.Trigger>Open</Modal.Trigger>
+      </Modal.Root>,
+    );
+
+    // Assert
+    expect(screen.getByRole("button", { name: "Open" })).toHaveAttribute(
+      "type",
+      "button",
+    );
+  });
+
+  it("respects a consumer-supplied type override", () => {
+    // Arrange & Act
+    render(
+      <Modal.Root>
+        <Modal.Trigger type="submit">Open</Modal.Trigger>
+      </Modal.Root>,
+    );
+
+    // Assert
+    expect(screen.getByRole("button", { name: "Open" })).toHaveAttribute(
+      "type",
+      "submit",
+    );
+  });
+});

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

@@ -0,0 +1,72 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import { Modal } from "../Modal";
+
+describe("Modal — uncontrolled state", () => {
+  it("starts closed by default and reflects aria-expanded=false on the trigger", () => {
+    // Arrange & Act
+    render(
+      <Modal.Root>
+        <Modal.Trigger>Open</Modal.Trigger>
+      </Modal.Root>,
+    );
+
+    // Assert
+    expect(screen.getByRole("button", { name: "Open" })).toHaveAttribute(
+      "aria-expanded",
+      "false",
+    );
+  });
+
+  it("starts open when defaultOpen is true", () => {
+    // Arrange & Act
+    render(
+      <Modal.Root defaultOpen>
+        <Modal.Trigger>Open</Modal.Trigger>
+      </Modal.Root>,
+    );
+
+    // Assert
+    expect(screen.getByRole("button", { name: "Open" })).toHaveAttribute(
+      "aria-expanded",
+      "true",
+    );
+  });
+
+  it("opens when the trigger is clicked", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    render(
+      <Modal.Root>
+        <Modal.Trigger>Open</Modal.Trigger>
+      </Modal.Root>,
+    );
+    const trigger = screen.getByRole("button", { name: "Open" });
+
+    // Act
+    await user.click(trigger);
+
+    // Assert
+    expect(trigger).toHaveAttribute("aria-expanded", "true");
+  });
+
+  it("closes when Modal.Close is clicked", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    render(
+      <Modal.Root defaultOpen>
+        <Modal.Trigger>Open</Modal.Trigger>
+        <Modal.Close>Close</Modal.Close>
+      </Modal.Root>,
+    );
+    const trigger = screen.getByRole("button", { name: "Open" });
+    const close = screen.getByRole("button", { name: "Close" });
+
+    // Act
+    await user.click(close);
+
+    // Assert
+    expect(trigger).toHaveAttribute("aria-expanded", "false");
+  });
+});

package/src/Modal/__tests__/dialog-polyfill.ts

@@ -0,0 +1,40 @@
+/**
+ * Minimal scoped polyfill for the native <dialog> element in jsdom 29.
+ *
+ * jsdom does not implement showModal() / close() on HTMLDialogElement, so
+ * integration tests that render Modal.Content need a shim that:
+ *  - toggles the `open` attribute (which is what .open reflects)
+ *  - dispatches the native `close` event on close()
+ *
+ * The `cancel` event (Esc) is not raised automatically by this polyfill —
+ * tests dispatch it manually with `fireEvent.cancel(dialog)` when they
+ * need to exercise the Esc path, so the polyfill stays small and the
+ * tests stay honest about what they're simulating.
+ *
+ * Scoped to Modal tests only — imported explicitly where needed rather
+ * than installed in vitest.setup.ts so other components keep exercising
+ * the real DOM.
+ */
+
+type DialogProto = HTMLDialogElement & { returnValue: string };
+
+const proto = HTMLDialogElement.prototype as DialogProto;
+
+if (typeof proto.showModal !== "function") {
+  proto.showModal = function showModal(this: HTMLDialogElement) {
+    this.setAttribute("open", "");
+  };
+}
+
+if (typeof proto.close !== "function") {
+  proto.close = function close(this: HTMLDialogElement, returnValue?: string) {
+    if (!this.hasAttribute("open")) return;
+    this.removeAttribute("open");
+    if (returnValue !== undefined) {
+      (this as DialogProto).returnValue = String(returnValue);
+    }
+    this.dispatchEvent(new Event("close"));
+  };
+}
+
+export {};

package/src/Modal/hooks/index.ts

@@ -0,0 +1,4 @@
+export * from "./useModalContent";
+export * from "./useModalContext";
+export * from "./useModalRoot";
+export * from "./useModalTrigger";

package/src/Modal/hooks/useModalContent.ts

@@ -0,0 +1,62 @@
+import { useEffect, useRef } from "react";
+
+import { useModalContext } from "./useModalContext";
+
+export function useModalContent() {
+  const { open, setOpen, contentId, contentCallbacksRef } = useModalContext();
+  const ref = useRef<HTMLDialogElement>(null);
+
+  useEffect(() => {
+    // React guarantees the ref is populated before effects run for a
+    // successfully-committed element, and Content always renders the
+    // dialog — so ref.current is non-null here.
+    const dialog = ref.current as HTMLDialogElement;
+    if (open && !dialog.open) {
+      dialog.showModal();
+    } else if (!open && dialog.open) {
+      dialog.close();
+    }
+  }, [open]);
+
+  useEffect(() => {
+    const dialog = ref.current as HTMLDialogElement;
+    const handleClose = () => setOpen(false);
+    const handleCancel = (event: Event) => {
+      contentCallbacksRef.current?.onEscapeKeyDown?.(event);
+      const consumerVetoed = event.defaultPrevented;
+      // Always block the browser's native auto-close so React drives the
+      // open state — otherwise the native close fires a `close` event and
+      // we'd race with React's effect-driven dialog.close().
+      event.preventDefault();
+      if (consumerVetoed) return;
+      setOpen(false);
+    };
+    const handlePointerDown = (event: PointerEvent) => {
+      // Native <dialog>.showModal() puts the dialog in the top layer and
+      // paints its own ::backdrop over any sibling overlay, so clicks on
+      // the visual backdrop target the <dialog> itself — not the overlay.
+      // Bounding-rect check: pointer inside the dialog's box (content or
+      // padding) is "inside"; anything else is a backdrop click.
+      const rect = dialog.getBoundingClientRect();
+      const inside =
+        event.clientX >= rect.left &&
+        event.clientX <= rect.right &&
+        event.clientY >= rect.top &&
+        event.clientY <= rect.bottom;
+      if (inside) return;
+      contentCallbacksRef.current?.onPointerDownOutside?.(event);
+      if (event.defaultPrevented) return;
+      setOpen(false);
+    };
+    dialog.addEventListener("close", handleClose);
+    dialog.addEventListener("cancel", handleCancel);
+    dialog.addEventListener("pointerdown", handlePointerDown);
+    return () => {
+      dialog.removeEventListener("close", handleClose);
+      dialog.removeEventListener("cancel", handleCancel);
+      dialog.removeEventListener("pointerdown", handlePointerDown);
+    };
+  }, [setOpen, contentCallbacksRef]);
+
+  return { ref, open, contentId };
+}

package/src/Modal/hooks/useModalContext.ts

@@ -0,0 +1 @@
+export { useModalContext } from "../ModalContext";

package/src/Modal/hooks/useModalRoot.ts

@@ -0,0 +1,81 @@
+import {
+  Ref,
+  useCallback,
+  useId,
+  useImperativeHandle,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+
+import { useControllableState } from "../../hooks";
+
+import {
+  ModalContentCallbacks,
+  ModalContextValue,
+  ModalImperativeApi,
+} from "../types";
+
+type UseModalRootArgs = {
+  defaultOpen?: boolean;
+  open?: boolean;
+  onOpenChange?: (open: boolean) => void;
+};
+
+export function useModalRoot(
+  { defaultOpen = false, open: controlledOpen, onOpenChange }: UseModalRootArgs,
+  ref?: Ref<ModalImperativeApi>,
+) {
+  const [open, setOpen] = useControllableState<boolean>(
+    controlledOpen,
+    defaultOpen,
+    onOpenChange,
+  );
+  const contentId = useId();
+  const contentCallbacksRef = useRef<ModalContentCallbacks>({});
+  const [titleId, setTitleId] = useState<string | undefined>(undefined);
+  const [descriptionId, setDescriptionId] = useState<string | undefined>(
+    undefined,
+  );
+
+  const registerTitle = useCallback((id: string | undefined) => {
+    setTitleId(id);
+  }, []);
+
+  const registerDescription = useCallback((id: string | undefined) => {
+    setDescriptionId(id);
+  }, []);
+
+  useImperativeHandle(
+    ref,
+    () => ({
+      open: () => setOpen(true),
+      close: () => setOpen(false),
+    }),
+    [setOpen],
+  );
+
+  const contextValue = useMemo<ModalContextValue>(
+    () => ({
+      open,
+      setOpen,
+      contentId,
+      contentCallbacksRef,
+      titleId,
+      descriptionId,
+      registerTitle,
+      registerDescription,
+    }),
+    [
+      open,
+      setOpen,
+      contentId,
+      titleId,
+      descriptionId,
+      registerTitle,
+      registerDescription,
+    ],
+  );
+
+  return { contextValue };
+}

package/src/Modal/hooks/useModalTrigger.ts

@@ -0,0 +1,25 @@
+import { MouseEventHandler } from "react";
+import { useModalContext } from ".";
+import { composeEventHandlers } from "../../Slot";
+import type { ModalTriggerProps } from "../types";
+
+export function useModalTrigger(
+  onClick?: MouseEventHandler,
+  rest: Omit<ModalTriggerProps, "asChild" | "onClick" | "type"> = {},
+) {
+  const { open, setOpen, contentId } = useModalContext();
+
+  function getTriggerProps() {
+    return {
+      ...rest,
+      "aria-haspopup": "dialog" as const,
+      "aria-expanded": open,
+      "aria-controls": contentId,
+      onClick: composeEventHandlers(onClick, () => setOpen(true)),
+    };
+  }
+
+  return {
+    getTriggerProps,
+  };
+}

package/src/Modal/index.ts

@@ -0,0 +1,3 @@
+export * from "./Modal";
+export * from "./ModalContext";
+export * from "./types";

package/src/Modal/types.ts

@@ -0,0 +1,76 @@
+import {
+  ComponentProps,
+  HTMLAttributes,
+  ReactNode,
+  Ref,
+  RefObject,
+} from "react";
+
+export type ModalImperativeApi = {
+  open: () => void;
+  close: () => void;
+};
+
+export type ModalContentCallbacks = {
+  onEscapeKeyDown?: (event: Event) => void;
+  onPointerDownOutside?: (event: PointerEvent) => void;
+};
+
+export type ModalContextValue = {
+  open: boolean;
+  setOpen: (open: boolean) => void;
+  contentId: string;
+  contentCallbacksRef: RefObject<ModalContentCallbacks>;
+  titleId: string | undefined;
+  descriptionId: string | undefined;
+  registerTitle: (id: string | undefined) => void;
+  registerDescription: (id: string | undefined) => void;
+};
+
+export type ModalContentProps = ComponentProps<"dialog"> &
+  ModalContentCallbacks;
+
+type UncontrolledModalRootProps = {
+  defaultOpen?: boolean;
+  open?: never;
+  onOpenChange?: (open: boolean) => void;
+};
+
+type ControlledModalRootProps = {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  defaultOpen?: never;
+};
+
+export type ModalRootProps = {
+  children?: ReactNode;
+} & (UncontrolledModalRootProps | ControlledModalRootProps) & {
+    ref?: Ref<ModalImperativeApi>;
+  };
+
+export type ModalTriggerProps = ComponentProps<"button"> & {
+  asChild?: boolean;
+};
+
+export type ModalCloseProps = ComponentProps<"button"> & {
+  asChild?: boolean;
+};
+
+export type ModalPortalProps = {
+  children?: ReactNode;
+  container?: HTMLElement;
+  forceMount?: boolean;
+};
+
+export type ModalOverlayProps = ComponentProps<"div"> & {
+  asChild?: boolean;
+  forceMount?: boolean;
+};
+
+export type ModalTitleProps = HTMLAttributes<HTMLElement> & {
+  asChild?: boolean;
+};
+
+export type ModalDescriptionProps = HTMLAttributes<HTMLElement> & {
+  asChild?: boolean;
+};

package/src/Portal/Portal.tsx

@@ -0,0 +1,28 @@
+import { createPortal } from "react-dom";
+
+import type { PortalProps } from "./types";
+
+/**
+ * Renders children outside the current React subtree by mounting them into a
+ * DOM node via `createPortal`. Defaults to `document.body`; pass `container`
+ * to target a different element.
+ *
+ * @example
+ * // Mount into document.body (default)
+ * <Portal>
+ *   <div role="dialog">…</div>
+ * </Portal>
+ *
+ * @example
+ * // Mount into a specific container
+ * <Portal container={document.getElementById("overlays")}>
+ *   <div role="dialog">…</div>
+ * </Portal>
+ */
+function Portal({ children, container }: PortalProps) {
+  return createPortal(children, container ?? document.body);
+}
+
+Portal.displayName = "Portal";
+
+export { Portal };

package/src/Portal/README.md

@@ -0,0 +1,70 @@
+# Portal
+
+A utility component that renders its children outside the current React subtree
+using React's [`createPortal`](https://react.dev/reference/react-dom/createPortal).
+Use it whenever a subtree needs to escape its parent's stacking context, overflow
+clipping, or z-index hierarchy — tooltips, modals, dropdowns, and similar overlays
+are typical candidates.
+
+## Usage
+
+### Default — mount into `document.body`
+
+```tsx
+import { Portal } from "@primitiv-ui/react";
+
+<Portal>
+  <div role="dialog" aria-modal="true">
+    Modal content rendered directly in document.body
+  </div>
+</Portal>
+```
+
+### Custom container
+
+Pass any `HTMLElement` as `container` to mount into a specific node instead of
+`document.body`:
+
+```tsx
+const overlayRoot = document.getElementById("overlay-root");
+
+<Portal container={overlayRoot}>
+  <div role="tooltip">Tooltip content</div>
+</Portal>
+```
+
+### Composing with conditional rendering
+
+`Portal` always renders when mounted. Control visibility by conditionally
+rendering the `Portal` itself, or by wrapping it with open/closed logic:
+
+```tsx
+{isOpen && (
+  <Portal>
+    <div role="dialog">…</div>
+  </Portal>
+)}
+```
+
+For CSS-driven exit animations, keep the portal in the DOM and drive styles
+from a `data-state` attribute:
+
+```tsx
+<Portal>
+  <div data-state={isOpen ? "open" : "closed"}>…</div>
+</Portal>
+```
+
+## Props
+
+| Prop        | Type          | Default          | Description                                          |
+| ----------- | ------------- | ---------------- | ---------------------------------------------------- |
+| `children`  | `ReactNode`   | —                | Content to render inside the portal                  |
+| `container` | `HTMLElement` | `document.body`  | DOM node to mount into                               |
+
+## Notes
+
+- `Portal` is a thin wrapper; it carries no state, context, or open/close
+  awareness of its own. Those concerns belong in the component that composes it.
+- `Modal.Portal` internally uses this component and adds open-state suppression
+  and `forceMount` on top.

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

@@ -0,0 +1,17 @@
+import { render, screen } from "@testing-library/react";
+
+import { Portal } from "../Portal";
+
+describe("Portal basic rendering", () => {
+  it("renders children into document.body", () => {
+    // Arrange & Act
+    render(
+      <Portal>
+        <p>Portal content</p>
+      </Portal>,
+    );
+
+    // Assert
+    expect(screen.getByText("Portal content")).toBeInTheDocument();
+  });
+});

package/src/Portal/index.ts

@@ -0,0 +1,2 @@
+export * from "./Portal";
+export * from "./types";

package/src/Portal/types.ts

@@ -0,0 +1,6 @@
+import { ReactNode } from "react";
+
+export type PortalProps = {
+  children?: ReactNode;
+  container?: HTMLElement;
+};