@primitiv-ui/web 0.1.53 → 0.1.55

package/dist/define/index.d.ts

@@ -4,4 +4,6 @@
  */
 import "./accordion.js";
 import "./collapsible.js";
+import "./modal.js";
+import "./popover.js";
 import "./tabs.js";

package/dist/define/index.js

@@ -4,4 +4,6 @@
  */
 import "./accordion.js";
 import "./collapsible.js";
+import "./modal.js";
+import "./popover.js";
 import "./tabs.js";

package/dist/define/modal.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/define/modal.js

@@ -0,0 +1,11 @@
+/**
+ * Side-effect entry: importing this module defines the six Modal elements
+ * (`<primitiv-modal>`, `-trigger`, `-content`, `-title`, `-description`,
+ * `-close`) on the global `customElements` registry.
+ *
+ * ```html
+ * <script type="module">import "@primitiv-ui/web/define/modal";</script>
+ * ```
+ */
+import { defineModal } from "../modal/elements.js";
+defineModal();

package/dist/define/popover.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/define/popover.js

@@ -0,0 +1,11 @@
+/**
+ * Side-effect entry: importing this module defines the seven Popover elements
+ * (`<primitiv-popover>`, `-trigger`, `-anchor`, `-content`, `-title`,
+ * `-description`, `-close`) on the global `customElements` registry.
+ *
+ * ```html
+ * <script type="module">import "@primitiv-ui/web/define/popover";</script>
+ * ```
+ */
+import { definePopover } from "../popover/elements.js";
+definePopover();

package/dist/frameworks/events.d.ts

@@ -15,3 +15,11 @@ export type PrimitivAccordionChangeEvent = CustomEvent<{
 export type PrimitivCollapsibleChangeEvent = CustomEvent<{
     open: boolean;
 }>;
+/** The `primitiv-modal-change` event: bubbles, cancelable, fired before the change applies, with the open state afterwards. */
+export type PrimitivModalChangeEvent = CustomEvent<{
+    open: boolean;
+}>;
+/** The `primitiv-popover-change` event: bubbles, cancelable, fired before the change applies, with the open state afterwards. */
+export type PrimitivPopoverChangeEvent = CustomEvent<{
+    open: boolean;
+}>;

package/dist/frameworks/react.d.ts

@@ -20,13 +20,15 @@
 import type { DetailedHTMLProps, HTMLAttributes } from "react";
 import type { PrimitivAccordionContentElement, PrimitivAccordionElement, PrimitivAccordionItemElement, PrimitivAccordionTriggerElement, PrimitivAccordionTriggerIconElement } from "../accordion/elements.js";
 import type { PrimitivCollapsibleContentElement, PrimitivCollapsibleElement, PrimitivCollapsibleTriggerElement, PrimitivCollapsibleTriggerIconElement } from "../collapsible/elements.js";
+import type { PrimitivModalCloseElement, PrimitivModalContentElement, PrimitivModalDescriptionElement, PrimitivModalElement, PrimitivModalTitleElement, PrimitivModalTriggerElement } from "../modal/elements.js";
+import type { PrimitivPopoverAnchorElement, PrimitivPopoverCloseElement, PrimitivPopoverContentElement, PrimitivPopoverDescriptionElement, PrimitivPopoverElement, PrimitivPopoverTitleElement, PrimitivPopoverTriggerElement } from "../popover/elements.js";
 import type { PrimitivTabsContentElement, PrimitivTabsElement, PrimitivTabsListElement, PrimitivTabsTriggerElement } from "../tabs/elements.js";
-import type { PrimitivAccordionChangeEvent, PrimitivCollapsibleChangeEvent, PrimitivTabsChangeEvent } from "./events.js";
+import type { PrimitivAccordionChangeEvent, PrimitivCollapsibleChangeEvent, PrimitivModalChangeEvent, PrimitivPopoverChangeEvent, PrimitivTabsChangeEvent } from "./events.js";
 /** React's own props for an element, plus `class`, which React 19 passes to custom elements. */
 type ElementProps<E extends HTMLElement> = DetailedHTMLProps<HTMLAttributes<E>, E> & {
     class?: string;
 };
-export type { PrimitivAccordionChangeEvent, PrimitivCollapsibleChangeEvent, PrimitivTabsChangeEvent };
+export type { PrimitivAccordionChangeEvent, PrimitivCollapsibleChangeEvent, PrimitivModalChangeEvent, PrimitivPopoverChangeEvent, PrimitivTabsChangeEvent, };
 declare module "react" {
     namespace JSX {
         interface IntrinsicElements {
@@ -59,6 +61,27 @@ declare module "react" {
                 "onprimitiv-collapsible-show"?: (event: CustomEvent) => void;
             };
             "primitiv-collapsible-trigger-icon": ElementProps<PrimitivCollapsibleTriggerIconElement>;
+            "primitiv-modal": ElementProps<PrimitivModalElement> & {
+                open?: boolean;
+                "onprimitiv-modal-change"?: (event: PrimitivModalChangeEvent) => void;
+            };
+            "primitiv-modal-trigger": ElementProps<PrimitivModalTriggerElement>;
+            "primitiv-modal-content": ElementProps<PrimitivModalContentElement>;
+            "primitiv-modal-title": ElementProps<PrimitivModalTitleElement>;
+            "primitiv-modal-description": ElementProps<PrimitivModalDescriptionElement>;
+            "primitiv-modal-close": ElementProps<PrimitivModalCloseElement>;
+            "primitiv-popover": ElementProps<PrimitivPopoverElement> & {
+                open?: boolean;
+                "onprimitiv-popover-change"?: (event: PrimitivPopoverChangeEvent) => void;
+            };
+            "primitiv-popover-trigger": ElementProps<PrimitivPopoverTriggerElement>;
+            "primitiv-popover-anchor": ElementProps<PrimitivPopoverAnchorElement>;
+            "primitiv-popover-title": ElementProps<PrimitivPopoverTitleElement>;
+            "primitiv-popover-description": ElementProps<PrimitivPopoverDescriptionElement>;
+            "primitiv-popover-close": ElementProps<PrimitivPopoverCloseElement>;
+            "primitiv-popover-content": ElementProps<PrimitivPopoverContentElement> & {
+                popover?: "auto" | "manual" | "";
+            };
             "primitiv-tabs": ElementProps<PrimitivTabsElement> & {
                 value?: string;
                 orientation?: "horizontal" | "vertical";

package/dist/frameworks/svelte.d.ts

@@ -19,8 +19,10 @@
 import type { HTMLAttributes } from "svelte/elements";
 import type { PrimitivAccordionContentElement, PrimitivAccordionElement, PrimitivAccordionItemElement, PrimitivAccordionTriggerElement, PrimitivAccordionTriggerIconElement } from "../accordion/elements.js";
 import type { PrimitivCollapsibleContentElement, PrimitivCollapsibleElement, PrimitivCollapsibleTriggerElement, PrimitivCollapsibleTriggerIconElement } from "../collapsible/elements.js";
+import type { PrimitivModalCloseElement, PrimitivModalContentElement, PrimitivModalDescriptionElement, PrimitivModalElement, PrimitivModalTitleElement, PrimitivModalTriggerElement } from "../modal/elements.js";
+import type { PrimitivPopoverAnchorElement, PrimitivPopoverCloseElement, PrimitivPopoverContentElement, PrimitivPopoverDescriptionElement, PrimitivPopoverElement, PrimitivPopoverTitleElement, PrimitivPopoverTriggerElement } from "../popover/elements.js";
 import type { PrimitivTabsContentElement, PrimitivTabsElement, PrimitivTabsListElement, PrimitivTabsTriggerElement } from "../tabs/elements.js";
-import type { PrimitivAccordionChangeEvent, PrimitivCollapsibleChangeEvent, PrimitivTabsChangeEvent } from "./events.js";
+import type { PrimitivAccordionChangeEvent, PrimitivCollapsibleChangeEvent, PrimitivModalChangeEvent, PrimitivPopoverChangeEvent, PrimitivTabsChangeEvent } from "./events.js";
 /** Svelte's own attributes and events for an element. */
 type Attributes<E extends HTMLElement> = HTMLAttributes<E>;
 declare module "svelte/elements" {
@@ -54,6 +56,25 @@ declare module "svelte/elements" {
             "onprimitiv-collapsible-show"?: (event: CustomEvent) => void;
         };
         "primitiv-collapsible-trigger-icon": Attributes<PrimitivCollapsibleTriggerIconElement>;
+        "primitiv-modal": Attributes<PrimitivModalElement> & {
+            open?: boolean;
+            "onprimitiv-modal-change"?: (event: PrimitivModalChangeEvent) => void;
+        };
+        "primitiv-modal-trigger": Attributes<PrimitivModalTriggerElement>;
+        "primitiv-modal-content": Attributes<PrimitivModalContentElement>;
+        "primitiv-modal-title": Attributes<PrimitivModalTitleElement>;
+        "primitiv-modal-description": Attributes<PrimitivModalDescriptionElement>;
+        "primitiv-modal-close": Attributes<PrimitivModalCloseElement>;
+        "primitiv-popover": Attributes<PrimitivPopoverElement> & {
+            open?: boolean;
+            "onprimitiv-popover-change"?: (event: PrimitivPopoverChangeEvent) => void;
+        };
+        "primitiv-popover-trigger": Attributes<PrimitivPopoverTriggerElement>;
+        "primitiv-popover-anchor": Attributes<PrimitivPopoverAnchorElement>;
+        "primitiv-popover-content": Attributes<PrimitivPopoverContentElement>;
+        "primitiv-popover-title": Attributes<PrimitivPopoverTitleElement>;
+        "primitiv-popover-description": Attributes<PrimitivPopoverDescriptionElement>;
+        "primitiv-popover-close": Attributes<PrimitivPopoverCloseElement>;
         "primitiv-tabs": Attributes<PrimitivTabsElement> & {
             value?: string;
             orientation?: "horizontal" | "vertical";

package/dist/frameworks/vue.d.ts

@@ -19,7 +19,7 @@
  * JSR does not allow a published module to do.
  */
 import type { DefineComponent, EmitsOptions } from "vue";
-import type { PrimitivAccordionChangeEvent, PrimitivCollapsibleChangeEvent, PrimitivTabsChangeEvent } from "./events.js";
+import type { PrimitivAccordionChangeEvent, PrimitivCollapsibleChangeEvent, PrimitivModalChangeEvent, PrimitivPopoverChangeEvent, PrimitivTabsChangeEvent } from "./events.js";
 /** A tag as Vue's template checker sees it: its props, and the events it emits. */
 type Tag<Props, Events extends EmitsOptions = Record<never, never>> = DefineComponent<Props, Record<never, never>, Record<never, never>, Record<never, never>, Record<never, never>, Record<never, never>, Record<never, never>, Events>;
 declare module "vue" {
@@ -57,6 +57,27 @@ declare module "vue" {
             "primitiv-collapsible-show": (event: CustomEvent) => void;
         }>;
         "primitiv-collapsible-trigger-icon": Tag<Record<never, never>>;
+        "primitiv-modal": Tag<{
+            open?: boolean | "";
+        }, {
+            "primitiv-modal-change": (event: PrimitivModalChangeEvent) => void;
+        }>;
+        "primitiv-modal-trigger": Tag<Record<never, never>>;
+        "primitiv-modal-content": Tag<Record<never, never>>;
+        "primitiv-modal-title": Tag<Record<never, never>>;
+        "primitiv-modal-description": Tag<Record<never, never>>;
+        "primitiv-modal-close": Tag<Record<never, never>>;
+        "primitiv-popover": Tag<{
+            open?: boolean | "";
+        }, {
+            "primitiv-popover-change": (event: PrimitivPopoverChangeEvent) => void;
+        }>;
+        "primitiv-popover-trigger": Tag<Record<never, never>>;
+        "primitiv-popover-anchor": Tag<Record<never, never>>;
+        "primitiv-popover-content": Tag<Record<never, never>>;
+        "primitiv-popover-title": Tag<Record<never, never>>;
+        "primitiv-popover-description": Tag<Record<never, never>>;
+        "primitiv-popover-close": Tag<Record<never, never>>;
         "primitiv-tabs": Tag<{
             value?: string;
             orientation?: "horizontal" | "vertical";

package/dist/index.d.ts

@@ -5,4 +5,6 @@
  */
 export * from "./accordion/index.js";
 export * from "./collapsible/index.js";
+export * from "./modal/index.js";
+export * from "./popover/index.js";
 export * from "./tabs/index.js";

package/dist/index.js

@@ -5,4 +5,6 @@
  */
 export * from "./accordion/index.js";
 export * from "./collapsible/index.js";
+export * from "./modal/index.js";
+export * from "./popover/index.js";
 export * from "./tabs/index.js";

package/dist/modal/ModalController.d.ts

@@ -0,0 +1,58 @@
+/**
+ * What a {@link ModalController} asks of whoever hosts it. The controller owns
+ * behaviour and never owns state (RFC 0033 D28): the custom elements keep the
+ * open state in a reflected `open` attribute, the React adapter keeps it in
+ * React, and each answers these calls from wherever it keeps it.
+ */
+export type ModalControllerHost = {
+    /** The state the controller cannot see for itself. */
+    state(): {
+        /** Whether the modal is open. */
+        open: boolean;
+    };
+    /** Apply a change the user asked for: `open` is the state afterwards. */
+    change(open: boolean): void;
+    /**
+     * Escape was pressed (the dialog's native `cancel` event). Call
+     * `preventDefault()` on `event` to keep the modal open. Optional.
+     */
+    escapeKeyDown?(event: Event): void;
+    /**
+     * A pointer went down outside the dialog's box — on the `::backdrop`. Call
+     * `preventDefault()` on `event` to keep the modal open. Optional.
+     */
+    pointerDownOutside?(event: PointerEvent): void;
+};
+/**
+ * The DOM behaviour of a modal dialog, over a native `<dialog>` and its
+ * `showModal()`: the browser owns the inert background, the top layer and
+ * Escape, and this adds what it leaves out (WAI-ARIA APG Modal Dialog):
+ *
+ * - **Sync** — {@link ModalController.sync | `sync()`} shows the dialog
+ *   modally or closes it to match the host's state. A host calls it whenever
+ *   that state may have changed.
+ * - **Dismissal** — Escape and a press on the backdrop ask the host to close,
+ *   each vetoable through its optional hook, and Escape never lets the browser
+ *   close the dialog itself, so the host's state stays the only source of
+ *   truth. A dialog that closes natively anyway (a `<form method="dialog">`)
+ *   reports the close.
+ * - **Focus trap** — Tab wraps from the last focusable to the first and
+ *   Shift+Tab back, since a native modal dialog lets focus escape to the
+ *   browser chrome.
+ *
+ * Opening and closing from a trigger or a close button are the host's, as
+ * plain clicks: the React adapter renders those buttons apart from the dialog.
+ */
+export declare class ModalController {
+    #private;
+    constructor(dialog: HTMLDialogElement, host: ModalControllerHost);
+    /**
+     * Start listening on the dialog. Connecting again while connected does
+     * nothing, so a host whose lifecycle runs twice never stacks handlers.
+     */
+    connect(): void;
+    /** Stop listening. A later `connect` resumes. */
+    disconnect(): void;
+    /** Show the dialog modally, or close it, to match the host's state. */
+    sync(): void;
+}

package/dist/modal/ModalController.js

@@ -0,0 +1,91 @@
+import { FOCUSABLE_SELECTOR, modalPointerOutside, modalTabKeydown } from "@primitiv-ui/core";
+/**
+ * The DOM behaviour of a modal dialog, over a native `<dialog>` and its
+ * `showModal()`: the browser owns the inert background, the top layer and
+ * Escape, and this adds what it leaves out (WAI-ARIA APG Modal Dialog):
+ *
+ * - **Sync** — {@link ModalController.sync | `sync()`} shows the dialog
+ *   modally or closes it to match the host's state. A host calls it whenever
+ *   that state may have changed.
+ * - **Dismissal** — Escape and a press on the backdrop ask the host to close,
+ *   each vetoable through its optional hook, and Escape never lets the browser
+ *   close the dialog itself, so the host's state stays the only source of
+ *   truth. A dialog that closes natively anyway (a `<form method="dialog">`)
+ *   reports the close.
+ * - **Focus trap** — Tab wraps from the last focusable to the first and
+ *   Shift+Tab back, since a native modal dialog lets focus escape to the
+ *   browser chrome.
+ *
+ * Opening and closing from a trigger or a close button are the host's, as
+ * plain clicks: the React adapter renders those buttons apart from the dialog.
+ */
+export class ModalController {
+    #dialog;
+    #host;
+    #connection = null;
+    constructor(dialog, host) {
+        this.#dialog = dialog;
+        this.#host = host;
+    }
+    /**
+     * Start listening on the dialog. Connecting again while connected does
+     * nothing, so a host whose lifecycle runs twice never stacks handlers.
+     */
+    connect() {
+        if (this.#connection)
+            return;
+        this.#connection = new AbortController();
+        const { signal } = this.#connection;
+        const dialog = this.#dialog;
+        dialog.addEventListener("close", () => this.#host.change(false), { signal });
+        dialog.addEventListener("cancel", (event) => this.#cancel(event), { signal });
+        dialog.addEventListener("pointerdown", (event) => this.#pointerdown(event), { signal });
+        dialog.addEventListener("keydown", (event) => this.#keydown(event), { signal });
+    }
+    /** Stop listening. A later `connect` resumes. */
+    disconnect() {
+        this.#connection?.abort();
+        this.#connection = null;
+    }
+    /** Show the dialog modally, or close it, to match the host's state. */
+    sync() {
+        const { open } = this.#host.state();
+        if (open && !this.#dialog.open)
+            this.#dialog.showModal();
+        else if (!open && this.#dialog.open)
+            this.#dialog.close();
+    }
+    #cancel(event) {
+        this.#host.escapeKeyDown?.(event);
+        const vetoed = event.defaultPrevented;
+        // Never let the browser close the dialog itself: the host's state decides,
+        // and `sync()` closes it.
+        event.preventDefault();
+        if (!vetoed)
+            this.#host.change(false);
+    }
+    #pointerdown(event) {
+        const point = { x: event.clientX, y: event.clientY };
+        if (!modalPointerOutside(this.#dialog.getBoundingClientRect(), point))
+            return;
+        this.#host.pointerDownOutside?.(event);
+        if (!event.defaultPrevented)
+            this.#host.change(false);
+    }
+    #keydown(event) {
+        if (!this.#dialog.open)
+            return;
+        const focusables = [...this.#dialog.querySelectorAll(FOCUSABLE_SELECTOR)];
+        const outcome = modalTabKeydown({
+            key: event.key,
+            shiftKey: event.shiftKey,
+            active: focusables.indexOf(document.activeElement),
+            count: focusables.length,
+        });
+        if (!outcome)
+            return;
+        event.preventDefault();
+        if (outcome.focus !== null)
+            focusables[outcome.focus].focus();
+    }
+}

package/dist/modal/elements.d.ts

@@ -0,0 +1,86 @@
+import { ElementBase, type ElementRegistry } from "../internal/element.js";
+import { PrimitivRootElement } from "../internal/RootElement.js";
+export type { ElementRegistry };
+/**
+ * `<primitiv-modal>` — the state owner of a modal dialog, built on the native
+ * `<dialog>` and its `showModal()`: the browser makes the page behind it inert,
+ * paints the `::backdrop` and owns the top layer, and the element adds the
+ * rest of the WAI-ARIA Modal Dialog pattern — Tab wraps inside the dialog,
+ * Escape and a press on the backdrop close it, and closing hands focus back to
+ * the button that opened it.
+ *
+ * The root finds its own parts, so a modal nested in a dialog keeps its own,
+ * and reconciles their ARIA from its reflected state whenever a part arrives,
+ * leaves, or changes an attribute the root reads (the lifecycle is
+ * `PrimitivRootElement`'s). Leave `open` off the `<dialog>` itself: the root
+ * opens it, modally.
+ *
+ * @customElement primitiv-modal
+ * @summary The state owner of a modal dialog on the native `<dialog>`.
+ * @attr {boolean} open - Whether the dialog is open. Reflected: it changes as the user opens and dismisses the dialog, so a server re-render or a history snapshot sees the live state. Set it (or the `open` property) to open or close the dialog from script.
+ * @fires {CustomEvent<{ open: boolean }>} primitiv-modal-change - Bubbles, cancelable, fired before a user-driven change is applied — a trigger or close click, Escape, a press on the backdrop, or the dialog closing natively — with the open state afterwards. Call `preventDefault()` to veto it, e.g. to keep a form with unsaved changes open.
+ */
+export declare class PrimitivModalElement extends PrimitivRootElement {
+    #private;
+    protected readonly controller: {
+        connect(): void;
+        disconnect(): void;
+    };
+    protected readonly reconcileOn: readonly string[];
+    /** Whether the dialog is open, reflected as the boolean `open` attribute. */
+    get open(): boolean;
+    set open(next: boolean);
+    protected reconcile(): void;
+}
+/**
+ * `<primitiv-modal-trigger>` — an interactive part. It decorates exactly one
+ * child the consumer writes, a `<button>`, which opens the dialog and receives
+ * `aria-haspopup="dialog"`, `aria-expanded` and `aria-controls`, so the
+ * rendered DOM matches React's (RFC 0033 D24). A modal may have several.
+ *
+ * @customElement primitiv-modal-trigger
+ */
+export declare class PrimitivModalTriggerElement extends ElementBase {
+}
+/**
+ * `<primitiv-modal-content>` — decorates exactly one native `<dialog>` the
+ * consumer writes, which the root opens with `showModal()`, closes, and gives
+ * an id, `data-state`, and `aria-labelledby` / `aria-describedby` pointing at
+ * the title and description. The dialog keeps its implicit `dialog` role.
+ *
+ * @customElement primitiv-modal-content
+ */
+export declare class PrimitivModalContentElement extends ElementBase {
+}
+/**
+ * `<primitiv-modal-title>` — decorates exactly one heading the consumer writes
+ * (an `<h2>`, usually), whose id becomes the dialog's `aria-labelledby`, so it
+ * is the name a screen reader announces as the dialog opens.
+ *
+ * @customElement primitiv-modal-title
+ */
+export declare class PrimitivModalTitleElement extends ElementBase {
+}
+/**
+ * `<primitiv-modal-description>` — decorates exactly one element the consumer
+ * writes (a `<p>`, usually), whose id becomes the dialog's `aria-describedby`.
+ *
+ * @customElement primitiv-modal-description
+ */
+export declare class PrimitivModalDescriptionElement extends ElementBase {
+}
+/**
+ * `<primitiv-modal-close>` — an interactive part. It decorates exactly one
+ * `<button>` the consumer writes, which closes the dialog. A modal may have
+ * several: the header's icon button and the footer's Cancel.
+ *
+ * @customElement primitiv-modal-close
+ */
+export declare class PrimitivModalCloseElement extends ElementBase {
+}
+/**
+ * Define the six Modal elements on `registry` (the global `customElements` by
+ * default). Safe to call more than once, and a no-op where there is no
+ * registry (a server render).
+ */
+export declare function defineModal(registry?: ElementRegistry | undefined): void;