@primitiv-ui/react 0.1.38 → 0.1.40

package/dist/Modal/Modal.js

@@ -0,0 +1,386 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useId } from "react";
+import { Portal } from "../Portal/index.js";
+import { Slot, composeEventHandlers, composeRefs } from "../Slot/index.js";
+import { ModalProvider } from "./ModalContext.js";
+import { useModalContent, useModalContext, useModalRoot, useModalTrigger, } from "./hooks/index.js";
+/**
+ * The root of a Modal — owns open state, registers the dialog's id,
+ * title id, and description id, and exposes an imperative handle for
+ * opening / closing from outside the React subtree.
+ *
+ * Supports two state modes, statically discriminated at the type level:
+ *
+ * - **Uncontrolled** — pass {@link ModalRootProps.defaultOpen | `defaultOpen`}
+ *   (or omit it for closed-on-mount). The component owns the open flag
+ *   internally.
+ * - **Controlled** — pass {@link ModalRootProps.open | `open`} *and*
+ *   {@link ModalRootProps.onOpenChange | `onOpenChange`} together. The
+ *   parent owns the flag; the component defers every state change back
+ *   through the callback.
+ *
+ * The imperative API is exposed via `ref`:
+ *
+ * ```tsx
+ * const ref = useRef<ModalImperativeApi>(null);
+ * ref.current?.open();
+ * ref.current?.close();
+ * ```
+ *
+ * In controlled mode the imperative methods call `onOpenChange` rather
+ * than flipping any internal state — the parent stays in charge.
+ *
+ * @example Uncontrolled
+ * ```tsx
+ * <Modal.Root defaultOpen>
+ *   <Modal.Content>...</Modal.Content>
+ * </Modal.Root>
+ * ```
+ *
+ * @example Controlled
+ * ```tsx
+ * const [open, setOpen] = useState(false);
+ *
+ * <Modal.Root open={open} onOpenChange={setOpen}>
+ *   <Modal.Trigger>Open</Modal.Trigger>
+ *   <Modal.Portal>
+ *     <Modal.Overlay />
+ *     <Modal.Content>...</Modal.Content>
+ *   </Modal.Portal>
+ * </Modal.Root>
+ * ```
+ */
+export function ModalRoot({ ref, children, defaultOpen, open, onOpenChange, }) {
+    const { contextValue } = useModalRoot({ defaultOpen, open, onOpenChange }, ref);
+    return _jsx(ModalProvider, { value: contextValue, children: children });
+}
+ModalRoot.displayName = "ModalRoot";
+/**
+ * A button that toggles the modal open. Renders a
+ * `<button type="button">` with full ARIA wiring:
+ *
+ * - `aria-haspopup="dialog"`
+ * - `aria-expanded` tracks open state
+ * - `aria-controls` points at the `Modal.Content` dialog's id
+ *
+ * **`asChild` prop.** Pass `asChild` to render any consumer-supplied
+ * 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>
+ *
+ * <Modal.Trigger asChild>
+ *   <Link to="/upgrade">Upgrade</Link>
+ * </Modal.Trigger>
+ * ```
+ */
+export function ModalTrigger({ onClick, type, asChild = false, ...rest }) {
+    const { getTriggerProps } = useModalTrigger(onClick, rest);
+    if (asChild) {
+        return _jsx(Slot, { ...getTriggerProps() });
+    }
+    return _jsx("button", { type: type ?? "button", ...getTriggerProps() });
+}
+ModalTrigger.displayName = "ModalTrigger";
+/**
+ * Renders its children through `React.createPortal` so the dialog is
+ * detached from wherever `Modal.Root` lives in the React tree and
+ * becomes a direct child of {@link ModalPortalProps.container | `container`}
+ * (default `document.body`).
+ *
+ * By default the portal only renders while the modal is open. Pass
+ * {@link ModalPortalProps.forceMount | `forceMount`} to keep the
+ * subtree in the DOM after `open` flips false — useful for CSS exit
+ * animations driven by `data-state="closed"`.
+ *
+ * @example
+ * ```tsx
+ * <Modal.Portal container={document.getElementById("modal-root")!}>
+ *   <Modal.Overlay />
+ *   <Modal.Content>...</Modal.Content>
+ * </Modal.Portal>
+ * ```
+ */
+export function ModalPortal({ children, container, forceMount, }) {
+    const { open } = useModalContext();
+    if (!open && !forceMount)
+        return null;
+    return _jsx(Portal, { container: container, children: children });
+}
+ModalPortal.displayName = "ModalPortal";
+/**
+ * A decorative, animation-friendly backdrop rendered as a **sibling**
+ * of `Modal.Content`. It is **not** an event surface for
+ * click-outside — opening a native `<dialog>` via `showModal()`
+ * promotes it to the top layer with a browser-painted `::backdrop`
+ * that sits *above* this overlay, so clicks on the visible backdrop
+ * never reach the overlay div. Click-outside-to-close is wired on
+ * the dialog itself via {@link ModalContentCallbacks.onPointerDownOutside | `onPointerDownOutside`}.
+ *
+ * - `aria-hidden="true"` (the backdrop is decorative).
+ * - `data-state="open" | "closed"` follows the modal's open state.
+ * - Consumer `onClick` (and any other event handler) is forwarded
+ *   through — the overlay does not compose or intercept them.
+ *
+ * **`asChild` prop.** Pass `asChild` to render a consumer-supplied
+ * element (e.g. a motion wrapper) with the overlay's ARIA and
+ * data-state merged in.
+ *
+ * **`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 />
+ *
+ * <Modal.Overlay asChild forceMount>
+ *   <motion.div
+ *     initial={{ opacity: 0 }}
+ *     animate={{ opacity: 1 }}
+ *     exit={{ opacity: 0 }}
+ *   />
+ * </Modal.Overlay>
+ * ```
+ */
+export function ModalOverlay({ asChild = false, forceMount, ...rest }) {
+    const { open } = useModalContext();
+    if (!open && !forceMount)
+        return null;
+    const overlayProps = {
+        ...rest,
+        "aria-hidden": "true",
+        "data-state": (open ? "open" : "closed"),
+    };
+    if (asChild) {
+        return _jsx(Slot, { ...overlayProps });
+    }
+    return _jsx("div", { ...overlayProps });
+}
+ModalOverlay.displayName = "ModalOverlay";
+/**
+ * The native `<dialog>` element. React drives its `showModal()` and
+ * `close()` calls in response to `open` state changes, letting the
+ * 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
+ * as descendants. The dialog has an implicit `role="dialog"` — do not
+ * pass one explicitly (WCAG redundancy rule).
+ *
+ * **Escape hatches.**
+ * - {@link ModalContentCallbacks.onEscapeKeyDown | `onEscapeKeyDown`}
+ *   fires on the native `cancel` event (Esc). Consumers can
+ *   `event.preventDefault()` to keep the modal open.
+ * - {@link ModalContentCallbacks.onPointerDownOutside | `onPointerDownOutside`}
+ *   fires on a `pointerdown` whose coordinates land outside the
+ *   dialog's bounding rect — i.e. on the native `::backdrop`. Consumers
+ *   can `event.preventDefault()` to keep the modal open. The native
+ *   `PointerEvent` is passed through, not a synthetic React event.
+ *
+ * **`asChild` is intentionally not supported.** The native dialog
+ * 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
+ *   onEscapeKeyDown={(event) => {
+ *     if (hasUnsavedChanges) event.preventDefault();
+ *   }}
+ * >
+ *   ...
+ * </Modal.Content>
+ * ```
+ */
+export function ModalContent({ children, id, onEscapeKeyDown, onPointerDownOutside, ref: externalRef, ...rest }) {
+    const { ref: innerRef, open, contentId } = useModalContent();
+    const { contentCallbacksRef, titleId, descriptionId } = useModalContext();
+    // Keep the ref pointed at the latest callbacks so event handlers wired
+    // through context (dialog pointerdown, native cancel) always see the most
+    // recent consumer props across re-renders.
+    contentCallbacksRef.current = { onEscapeKeyDown, onPointerDownOutside };
+    const composedRef = externalRef
+        ? composeRefs(innerRef, externalRef)
+        : innerRef;
+    return (_jsx("dialog", { ref: composedRef, id: id ?? contentId, "data-state": open ? "open" : "closed", "aria-labelledby": titleId, "aria-describedby": descriptionId, ...rest, children: children }));
+}
+ModalContent.displayName = "ModalContent";
+/**
+ * The dialog's accessible name. Renders an `<h2>` by default and
+ * auto-registers its generated id with `Modal.Root` so
+ * `Modal.Content` can wire it up as `aria-labelledby`.
+ *
+ * Pass `asChild` to render the consumer's own heading element (e.g.
+ * 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>
+ *
+ * <Modal.Title asChild>
+ *   <h3>Nested section</h3>
+ * </Modal.Title>
+ * ```
+ */
+export function ModalTitle({ children, asChild = false, ...rest }) {
+    const { registerTitle } = useModalContext();
+    const id = useId();
+    useEffect(() => {
+        registerTitle(id);
+        return () => registerTitle(undefined);
+    }, [registerTitle, id]);
+    if (asChild) {
+        return (_jsx(Slot, { id: id, ...rest, children: children }));
+    }
+    return (_jsx("h2", { id: id, ...rest, children: children }));
+}
+ModalTitle.displayName = "ModalTitle";
+/**
+ * The dialog's accessible description. Renders a `<p>` by default and
+ * auto-registers its generated id with `Modal.Root` so
+ * `Modal.Content` can wire it up as `aria-describedby`.
+ *
+ * Pass `asChild` to render any consumer-supplied element; the id is
+ * still registered.
+ *
+ * @extends HTMLParagraphElement
+ *
+ * @example
+ * ```tsx
+ * <Modal.Description>
+ *   Enter your card details below. You can change your plan later.
+ * </Modal.Description>
+ * ```
+ */
+export function ModalDescription({ children, asChild = false, ...rest }) {
+    const { registerDescription } = useModalContext();
+    const id = useId();
+    useEffect(() => {
+        registerDescription(id);
+        return () => registerDescription(undefined);
+    }, [registerDescription, id]);
+    if (asChild) {
+        return (_jsx(Slot, { id: id, ...rest, children: children }));
+    }
+    return (_jsx("p", { id: id, ...rest, children: children }));
+}
+ModalDescription.displayName = "ModalDescription";
+/**
+ * A button that closes the modal. Renders a `<button type="button">`
+ * whose `onClick` is composed with `setOpen(false)` — consumer
+ * handlers run first and can `event.preventDefault()` to veto closing.
+ *
+ * **`asChild` prop.** Pass `asChild` to render any element (e.g. a
+ * 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>
+ *
+ * <Modal.Close asChild>
+ *   <IconButton aria-label="Close" icon={<XIcon />} />
+ * </Modal.Close>
+ * ```
+ */
+export function ModalClose({ onClick, asChild = false, ...rest }) {
+    const { setOpen } = useModalContext();
+    const closeProps = {
+        ...rest,
+        onClick: composeEventHandlers(onClick, () => setOpen(false)),
+    };
+    if (asChild) {
+        return _jsx(Slot, { ...closeProps });
+    }
+    return _jsx("button", { type: "button", ...closeProps });
+}
+ModalClose.displayName = "ModalClose";
+/**
+ * Headless, accessible **Modal** — a compound component built on the
+ * native `<dialog>` element and its `showModal()` API. Implements the
+ * [WAI-ARIA Modal Dialog pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/)
+ * with zero styles.
+ *
+ * `Modal` is both callable (it's an alias of {@link ModalRoot | `Modal.Root`})
+ * and carries its sub-components as static properties. Prefer the
+ * namespaced form in application code for readability and grep-ability.
+ *
+ * - {@link ModalRoot | `Modal.Root`} — state owner, context provider, imperative API holder.
+ * - {@link ModalTrigger | `Modal.Trigger`} — `<button>` that opens the modal.
+ * - {@link ModalPortal | `Modal.Portal`} — `createPortal` wrapper with `container` + `forceMount`.
+ * - {@link ModalOverlay | `Modal.Overlay`} — click-outside backdrop sibling of the dialog.
+ * - {@link ModalContent | `Modal.Content`} — native `<dialog>` with escape hatches and auto-ARIA.
+ * - {@link ModalTitle | `Modal.Title`} — accessible name; auto-wires `aria-labelledby`.
+ * - {@link ModalDescription | `Modal.Description`} — auto-wires `aria-describedby`.
+ * - {@link ModalClose | `Modal.Close`} — `<button>` that closes the modal.
+ *
+ * @example Minimal usage
+ * ```tsx
+ * import { Modal } from "@primitiv-ui/react";
+ *
+ * <Modal.Root>
+ *   <Modal.Trigger>Open</Modal.Trigger>
+ *   <Modal.Portal>
+ *     <Modal.Overlay />
+ *     <Modal.Content>
+ *       <Modal.Title>Payment</Modal.Title>
+ *       <Modal.Description>Enter your card details</Modal.Description>
+ *       <Modal.Close>Cancel</Modal.Close>
+ *     </Modal.Content>
+ *   </Modal.Portal>
+ * </Modal.Root>;
+ * ```
+ *
+ * @example Scroll lock (CSS only)
+ * ```css
+ * html:has(dialog[open]) { overflow: hidden; }
+ * ```
+ *
+ * @see {@link ModalRoot} for state modes and the imperative API.
+ * @see {@link ModalContent} for the escape hatches and ARIA auto-wiring.
+ * @see {@link ModalOverlay} for the click-outside contract.
+ */
+const ModalCompound = Object.assign(ModalRoot, {
+    Root: ModalRoot,
+    Trigger: ModalTrigger,
+    Portal: ModalPortal,
+    Overlay: ModalOverlay,
+    Content: ModalContent,
+    Title: ModalTitle,
+    Description: ModalDescription,
+    Close: ModalClose,
+});
+ModalCompound.displayName = "Modal";
+export { ModalCompound as Modal };

package/dist/Modal/ModalContext.d.ts

@@ -0,0 +1,9 @@
+import type { Context, Provider } from "react";
+import { ModalContextValue } from "./types.js";
+/** React context carrying the shared {@link ModalContextValue} for a modal. */
+export declare const ModalContext: Context<ModalContextValue | null>;
+/** Hook returning the nearest {@link ModalContextValue}; throws outside `Modal.Root`. */
+export declare const useModalContext: () => ModalContextValue;
+/** Context provider for {@link ModalContext}, rendered internally by `Modal.Root`. */
+declare const ModalProvider: Provider<ModalContextValue | null>;
+export { ModalProvider };

package/dist/Modal/ModalContext.js

@@ -0,0 +1,10 @@
+"use client";
+import { createStrictContext } from "../utils/index.js";
+const modalContextPair = createStrictContext("Component must be rendered as a child of Modal.Root", "ModalContext");
+/** React context carrying the shared {@link ModalContextValue} for a modal. */
+export const ModalContext = modalContextPair[0];
+/** Hook returning the nearest {@link ModalContextValue}; throws outside `Modal.Root`. */
+export const useModalContext = modalContextPair[1];
+/** Context provider for {@link ModalContext}, rendered internally by `Modal.Root`. */
+const ModalProvider = ModalContext.Provider;
+export { ModalProvider };

package/dist/Modal/hooks/index.d.ts

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

package/dist/Modal/hooks/index.js

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

package/dist/Modal/hooks/useModalContent.d.ts

@@ -0,0 +1,5 @@
+export declare function useModalContent(): {
+    ref: import("react").RefObject<HTMLDialogElement | null>;
+    open: boolean;
+    contentId: string;
+};

package/dist/Modal/hooks/useModalContent.js

@@ -0,0 +1,94 @@
+"use client";
+import { useEffect, useRef } from "react";
+import { FOCUSABLE_SELECTOR } from "../../utils/index.js";
+import { useModalContext } from "./useModalContext.js";
+export function useModalContent() {
+    const { open, setOpen, contentId, contentCallbacksRef } = useModalContext();
+    const ref = useRef(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;
+        if (open && !dialog.open) {
+            dialog.showModal();
+        }
+        else if (!open && dialog.open) {
+            dialog.close();
+        }
+    }, [open]);
+    useEffect(() => {
+        const dialog = ref.current;
+        const handleClose = () => setOpen(false);
+        const handleCancel = (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) => {
+            // 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);
+        };
+        const handleKeyDown = (event) => {
+            // 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(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]);
+    return { ref, open, contentId };
+}

package/dist/Modal/hooks/useModalContext.d.ts

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

package/dist/Modal/hooks/useModalContext.js

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

package/dist/Modal/hooks/useModalRoot.d.ts

@@ -0,0 +1,11 @@
+import { Ref } from "react";
+import { ModalContextValue, ModalImperativeApi } from "../types.js";
+type UseModalRootArgs = {
+    defaultOpen?: boolean;
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+};
+export declare function useModalRoot({ defaultOpen, open: controlledOpen, onOpenChange }: UseModalRootArgs, ref?: Ref<ModalImperativeApi>): {
+    contextValue: ModalContextValue;
+};
+export {};

package/dist/Modal/hooks/useModalRoot.js

@@ -0,0 +1,39 @@
+"use client";
+import { useCallback, useId, useImperativeHandle, useMemo, useRef, useState, } from "react";
+import { useControllableState } from "../../hooks/index.js";
+export function useModalRoot({ defaultOpen = false, open: controlledOpen, onOpenChange }, ref) {
+    const [open, setOpen] = useControllableState(controlledOpen, defaultOpen, onOpenChange);
+    const contentId = useId();
+    const contentCallbacksRef = useRef({});
+    const [titleId, setTitleId] = useState(undefined);
+    const [descriptionId, setDescriptionId] = useState(undefined);
+    const registerTitle = useCallback((id) => {
+        setTitleId(id);
+    }, []);
+    const registerDescription = useCallback((id) => {
+        setDescriptionId(id);
+    }, []);
+    useImperativeHandle(ref, () => ({
+        open: () => setOpen(true),
+        close: () => setOpen(false),
+    }), [setOpen]);
+    const contextValue = useMemo(() => ({
+        open,
+        setOpen,
+        contentId,
+        contentCallbacksRef,
+        titleId,
+        descriptionId,
+        registerTitle,
+        registerDescription,
+    }), [
+        open,
+        setOpen,
+        contentId,
+        titleId,
+        descriptionId,
+        registerTitle,
+        registerDescription,
+    ]);
+    return { contextValue };
+}