@primitiv-ui/react 0.1.38 → 0.1.39

package/dist/MillerColumns/useMillerColumnsSelection.d.ts

@@ -0,0 +1,21 @@
+import type { MillerColumnsSelection } from "./types.js";
+/**
+ * Reads the current MillerColumns selection — the active path and the
+ * deepest selected item id.
+ *
+ * Intended for consumer content rendered inside a `MillerColumns.Root`
+ * (typically within a `MillerColumns.PreviewPanel`) that needs to know
+ * what is selected without owning the selection state itself. Works for
+ * both controlled and uncontrolled roots.
+ *
+ * Throws when called outside a `MillerColumns.Root`.
+ *
+ * @example
+ * ```tsx
+ * function FilePreview() {
+ *   const { selectedValue } = useMillerColumnsSelection();
+ *   return selectedValue ? <Preview id={selectedValue} /> : null;
+ * }
+ * ```
+ */
+export declare function useMillerColumnsSelection(): MillerColumnsSelection;

package/dist/MillerColumns/useMillerColumnsSelection.js

@@ -0,0 +1,28 @@
+"use client";
+import { useMillerColumnsContext } from "./hooks/index.js";
+/**
+ * Reads the current MillerColumns selection — the active path and the
+ * deepest selected item id.
+ *
+ * Intended for consumer content rendered inside a `MillerColumns.Root`
+ * (typically within a `MillerColumns.PreviewPanel`) that needs to know
+ * what is selected without owning the selection state itself. Works for
+ * both controlled and uncontrolled roots.
+ *
+ * Throws when called outside a `MillerColumns.Root`.
+ *
+ * @example
+ * ```tsx
+ * function FilePreview() {
+ *   const { selectedValue } = useMillerColumnsSelection();
+ *   return selectedValue ? <Preview id={selectedValue} /> : null;
+ * }
+ * ```
+ */
+export function useMillerColumnsSelection() {
+    const { activePath } = useMillerColumnsContext();
+    return {
+        path: activePath,
+        selectedValue: activePath.at(-1),
+    };
+}

package/dist/MillerColumns/utils.d.ts

@@ -0,0 +1,62 @@
+import { ReactElement, ReactNode } from "react";
+/**
+ * Produces the next active path when an item at `depth` with id `value`
+ * is selected: keeps the columns shallower than `depth` untouched,
+ * appends `value`, and drops everything deeper (those columns close).
+ */
+export declare function selectAtDepth(path: string[], depth: number, value: string): string[];
+/**
+ * Splits a props bag into its `aria-*` entries and everything else.
+ *
+ * `Root` renders two elements — a plain strip container and the inner
+ * `role="tree"` widget — so one props bag has two possible homes. ARIA
+ * belongs on the widget (an `aria-label` must name the tree, not its
+ * scroll container); `className`, `id`, `style` and the rest belong on
+ * the container the consumer actually lays out.
+ */
+export declare function partitionAriaProps(props: Record<string, unknown>): {
+    aria: Record<string, unknown>;
+    rest: Record<string, unknown>;
+};
+/**
+ * Marker a styling layer sets on a component that renders a `MillerColumns`
+ * part, so this module recognises the wrapper as that part.
+ *
+ * `Item` inspects its children **before** rendering them, so it sees the
+ * wrapper component rather than the `MillerColumns.Column` the wrapper
+ * returns. Without a marker a wrapped child column is mis-read as cell
+ * content: the item stops being a branch (no `aria-expanded`, no chevron, no
+ * ArrowRight) and — worse — the column projects into whatever depth slot
+ * happens to be open, so selecting *one* branch reveals *every* sibling's
+ * children at once.
+ *
+ * ```tsx
+ * function StyledColumn(props: MillerColumnsColumnProps) {
+ *   return <MillerColumns.Column {...props} className="column" />;
+ * }
+ * StyledColumn[MILLER_COLUMNS_PART] = "column";
+ * ```
+ */
+export declare const MILLER_COLUMNS_PART: "__primitivMillerColumnsPart";
+/** The part names {@link MILLER_COLUMNS_PART} accepts. */
+export type MillerColumnsPartName = "column";
+/**
+ * Whether `node` is a `MillerColumns.Column` element — either the part itself,
+ * or a component that marks itself as standing in for it (see
+ * {@link MILLER_COLUMNS_PART}).
+ */
+export declare function isColumnElement(node: ReactNode): node is ReactElement;
+/**
+ * Splits an `Item`'s children into its cell content and its single
+ * optional nested `<MillerColumns.Column>`.
+ *
+ * The child column is matched however deeply it is wrapped in
+ * fragments, since `Children.toArray` does not descend into fragments —
+ * so `{cond ? <><Indicator/><Column/></> : null}` is partitioned the
+ * same as a bare `<Column/>`. Cell entries are re-keyed because
+ * unwrapping fragments can collide the keys `Children.toArray` assigns.
+ */
+export declare function partitionItemChildren(children: ReactNode): {
+    cell: ReactNode[];
+    column: ReactElement | null;
+};

package/dist/MillerColumns/utils.js

@@ -0,0 +1,102 @@
+"use client";
+import { Children, cloneElement, Fragment, isValidElement, } from "react";
+import { MillerColumnsColumn } from "./MillerColumns.js";
+/**
+ * Produces the next active path when an item at `depth` with id `value`
+ * is selected: keeps the columns shallower than `depth` untouched,
+ * appends `value`, and drops everything deeper (those columns close).
+ */
+export function selectAtDepth(path, depth, value) {
+    return [...path.slice(0, depth), value];
+}
+/**
+ * Splits a props bag into its `aria-*` entries and everything else.
+ *
+ * `Root` renders two elements — a plain strip container and the inner
+ * `role="tree"` widget — so one props bag has two possible homes. ARIA
+ * belongs on the widget (an `aria-label` must name the tree, not its
+ * scroll container); `className`, `id`, `style` and the rest belong on
+ * the container the consumer actually lays out.
+ */
+export function partitionAriaProps(props) {
+    const aria = {};
+    const rest = {};
+    for (const [key, value] of Object.entries(props)) {
+        if (key.startsWith("aria-")) {
+            aria[key] = value;
+        }
+        else {
+            rest[key] = value;
+        }
+    }
+    return { aria, rest };
+}
+/**
+ * Marker a styling layer sets on a component that renders a `MillerColumns`
+ * part, so this module recognises the wrapper as that part.
+ *
+ * `Item` inspects its children **before** rendering them, so it sees the
+ * wrapper component rather than the `MillerColumns.Column` the wrapper
+ * returns. Without a marker a wrapped child column is mis-read as cell
+ * content: the item stops being a branch (no `aria-expanded`, no chevron, no
+ * ArrowRight) and — worse — the column projects into whatever depth slot
+ * happens to be open, so selecting *one* branch reveals *every* sibling's
+ * children at once.
+ *
+ * ```tsx
+ * function StyledColumn(props: MillerColumnsColumnProps) {
+ *   return <MillerColumns.Column {...props} className="column" />;
+ * }
+ * StyledColumn[MILLER_COLUMNS_PART] = "column";
+ * ```
+ */
+export const MILLER_COLUMNS_PART = "__primitivMillerColumnsPart";
+/** Read a component's {@link MILLER_COLUMNS_PART} marker, if it declares one. */
+function millerColumnsPartOf(type) {
+    return type?.[MILLER_COLUMNS_PART];
+}
+/**
+ * Whether `node` is a `MillerColumns.Column` element — either the part itself,
+ * or a component that marks itself as standing in for it (see
+ * {@link MILLER_COLUMNS_PART}).
+ */
+export function isColumnElement(node) {
+    return (isValidElement(node) &&
+        (node.type === MillerColumnsColumn ||
+            millerColumnsPartOf(node.type) === "column"));
+}
+/**
+ * Splits an `Item`'s children into its cell content and its single
+ * optional nested `<MillerColumns.Column>`.
+ *
+ * The child column is matched however deeply it is wrapped in
+ * fragments, since `Children.toArray` does not descend into fragments —
+ * so `{cond ? <><Indicator/><Column/></> : null}` is partitioned the
+ * same as a bare `<Column/>`. Cell entries are re-keyed because
+ * unwrapping fragments can collide the keys `Children.toArray` assigns.
+ */
+export function partitionItemChildren(children) {
+    const cell = [];
+    let column = null;
+    const visit = (nodes) => {
+        for (const child of Children.toArray(nodes)) {
+            if (isColumnElement(child)) {
+                if (column !== null) {
+                    throw new Error("A MillerColumns.Item may contain at most one nested <MillerColumns.Column>.");
+                }
+                column = child;
+            }
+            else if (isValidElement(child) && child.type === Fragment) {
+                visit(child.props.children);
+            }
+            else {
+                cell.push(child);
+            }
+        }
+    };
+    visit(children);
+    return {
+        cell: cell.map((node, index) => isValidElement(node) ? cloneElement(node, { key: `mc-${index}` }) : node),
+        column,
+    };
+}

package/dist/Modal/Modal.d.ts

@@ -0,0 +1,331 @@
+import { Ref } from "react";
+import type { ReactElement } from "react";
+import { ModalCloseProps, ModalContentProps, ModalDescriptionProps, ModalOverlayProps, ModalPortalProps, ModalRootProps, ModalTitleProps, ModalTriggerProps } from "./types.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 declare function ModalRoot({ ref, children, defaultOpen, open, onOpenChange, }: ModalRootProps): ReactElement;
+export declare namespace ModalRoot {
+    var displayName: string;
+}
+/**
+ * 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 declare function ModalTrigger({ onClick, type, asChild, ...rest }: ModalTriggerProps): ReactElement;
+export declare namespace ModalTrigger {
+    var displayName: string;
+}
+/**
+ * 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 declare function ModalPortal({ children, container, forceMount, }: ModalPortalProps): ReactElement | null;
+export declare namespace ModalPortal {
+    var displayName: string;
+}
+/**
+ * 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 declare function ModalOverlay({ asChild, forceMount, ...rest }: ModalOverlayProps): ReactElement | null;
+export declare namespace ModalOverlay {
+    var displayName: string;
+}
+/**
+ * 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 declare function ModalContent({ children, id, onEscapeKeyDown, onPointerDownOutside, ref: externalRef, ...rest }: ModalContentProps & {
+    ref?: Ref<HTMLDialogElement>;
+}): ReactElement;
+export declare namespace ModalContent {
+    var displayName: string;
+}
+/**
+ * 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 declare function ModalTitle({ children, asChild, ...rest }: ModalTitleProps): ReactElement;
+export declare namespace ModalTitle {
+    var displayName: string;
+}
+/**
+ * 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 declare function ModalDescription({ children, asChild, ...rest }: ModalDescriptionProps): ReactElement;
+export declare namespace ModalDescription {
+    var displayName: string;
+}
+/**
+ * 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 declare function ModalClose({ onClick, asChild, ...rest }: ModalCloseProps): ReactElement;
+export declare namespace ModalClose {
+    var displayName: string;
+}
+/** @internal */
+type ModalCompound = typeof ModalRoot & {
+    Root: typeof ModalRoot;
+    Trigger: typeof ModalTrigger;
+    Portal: typeof ModalPortal;
+    Overlay: typeof ModalOverlay;
+    Content: typeof ModalContent;
+    Title: typeof ModalTitle;
+    Description: typeof ModalDescription;
+    Close: typeof 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.
+ */
+declare const ModalCompound: ModalCompound;
+export { ModalCompound as Modal };