@primitiv-ui/web 0.1.53 → 0.1.55

package/dist/modal/elements.js

@@ -0,0 +1,235 @@
+import { defineElements, ElementBase, reportOnce, write } from "../internal/element.js";
+import { PrimitivRootElement } from "../internal/RootElement.js";
+import { ModalController } from "./ModalController.js";
+// Stryker disable StringLiteral: static — evaluated once at import, so runtime mutant switching never reaches them; the names are pinned by the defineModal registry test instead.
+const ROOT = "primitiv-modal";
+const TRIGGER = "primitiv-modal-trigger";
+const CONTENT = "primitiv-modal-content";
+const TITLE = "primitiv-modal-title";
+const DESCRIPTION = "primitiv-modal-description";
+const CLOSE = "primitiv-modal-close";
+// Stryker restore StringLiteral
+/**
+ * The one element child `part` decorates — the `<button>`, `<dialog>` or
+ * heading the consumer writes — or `null`, reported once, when it has anything
+ * but exactly one (RFC 0033 D24). `what` names the child in the report.
+ */
+function decoratable(part, what) {
+    if (part.childElementCount === 1)
+        return part.firstElementChild;
+    reportOnce(part, `<${part.localName}> needs exactly one element child (${what}) to decorate.`);
+    return null;
+}
+/** The `<dialog>` a content part decorates, or `null`, reported once, without exactly one. */
+function decoratableDialog(content) {
+    const child = content.firstElementChild;
+    if (content.childElementCount === 1 && child instanceof HTMLDialogElement)
+        return child;
+    reportOnce(content, `<${CONTENT}> needs exactly one <dialog> child to decorate.`);
+    return null;
+}
+/**
+ * `<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 class PrimitivModalElement extends PrimitivRootElement {
+    /** The dialog the root currently decorates, and the controller over it. */
+    #dialog = null;
+    #modal = null;
+    /** The decorated trigger and close buttons, as of the last reconcile. */
+    // Stryker disable next-line ArrayDeclaration: equivalent — the first reconcile runs as the root connects, before any click can reach it, and replaces both.
+    #openers = [];
+    // Stryker disable next-line ArrayDeclaration: equivalent — as above.
+    #closers = [];
+    /** The root's own click listener, while connected. */
+    #listening = null;
+    controller = {
+        connect: () => this.#connect(),
+        disconnect: () => this.#disconnect(),
+    };
+    reconcileOn = ["open"];
+    /** Whether the dialog is open, reflected as the boolean `open` attribute. */
+    get open() {
+        return this.hasAttribute("open");
+    }
+    set open(next) {
+        this.toggleAttribute("open", next);
+    }
+    /** The controller's view of this element: state lives in the reflected attribute. */
+    #host() {
+        return {
+            state: () => ({ open: this.open }),
+            change: (open) => this.#change(open),
+        };
+    }
+    /** A change the user asked for: announced first, so a listener can veto it. */
+    #change(open) {
+        if (open === this.open)
+            return;
+        if (this.announce("primitiv-modal-change", { open }))
+            this.open = open;
+        // A veto can leave the dialog out of step — it already closed natively —
+        // so put it back where the state says.
+        else
+            this.#modal?.sync();
+    }
+    #connect() {
+        this.#listening = new AbortController();
+        this.addEventListener("click", (event) => this.#click(event), {
+            signal: this.#listening.signal,
+        });
+        this.#modal?.connect();
+    }
+    #disconnect() {
+        // A root disconnects only after it connected, so it is listening.
+        this.#listening.abort();
+        this.#listening = null;
+        this.#modal?.disconnect();
+        // Leaving the document drops the dialog from the top layer but leaves it
+        // `open`, so a move would bring it back non-modally. Drop the attribute
+        // rather than calling close(): close() queues a close event that a move's
+        // reconnect would hear as the user dismissing it. The state is kept, and
+        // the next connect reopens the dialog modally.
+        if (this.#dialog)
+            write(this.#dialog, "open", null);
+    }
+    #click(event) {
+        const target = event.target;
+        if (this.#openers.some((button) => button.contains(target)))
+            this.#change(true);
+        else if (this.#closers.some((button) => button.contains(target)))
+            this.#change(false);
+    }
+    /**
+     * Decorate `dialog` from now on: the controller follows it. Only a reconcile
+     * calls this, and a root reconciles only while connected, so the new
+     * controller listens at once.
+     */
+    #use(dialog) {
+        // Stryker disable next-line ConditionalExpression: equivalent — rebuilding the controller over the same dialog swaps one listener set for an identical one.
+        if (dialog === this.#dialog)
+            return;
+        this.#modal?.disconnect();
+        // A dialog that arrives already `open` — a history snapshot, taken while it
+        // was showing — is open non-modally, and `showModal()` would leave it so.
+        // Drop the attribute (that fires no close event), and the sync below
+        // reopens it modally if the root says it is open.
+        if (dialog)
+            write(dialog, "open", null);
+        this.#dialog = dialog;
+        this.#modal = dialog ? new ModalController(dialog, this.#host()) : null;
+        this.#modal?.connect();
+    }
+    reconcile() {
+        const open = this.open;
+        const state = open ? "open" : "closed";
+        const rootId = this.rootId();
+        write(this, "data-state", state);
+        const [content] = this.parts(CONTENT);
+        const dialog = content ? decoratableDialog(content) : null;
+        const [titlePart] = this.parts(TITLE);
+        const title = titlePart ? decoratable(titlePart, "a heading") : null;
+        const [descriptionPart] = this.parts(DESCRIPTION);
+        const description = descriptionPart ? decoratable(descriptionPart, "a <p>") : null;
+        if (title && !title.id)
+            title.id = `${rootId}-title`;
+        if (description && !description.id)
+            description.id = `${rootId}-description`;
+        if (dialog) {
+            if (!dialog.id)
+                dialog.id = `${rootId}-content`;
+            write(dialog, "data-state", state);
+            write(dialog, "aria-labelledby", title ? title.id : null);
+            write(dialog, "aria-describedby", description ? description.id : null);
+        }
+        this.#openers = this.#buttons(TRIGGER);
+        for (const button of this.#openers) {
+            write(button, "aria-haspopup", "dialog");
+            write(button, "aria-expanded", String(open));
+            write(button, "aria-controls", dialog ? dialog.id : null);
+        }
+        this.#closers = this.#buttons(CLOSE);
+        this.#use(dialog);
+        this.#modal?.sync();
+    }
+    /** The buttons this root's `selector` parts decorate. */
+    #buttons(selector) {
+        return this.parts(selector).flatMap((part) => decoratable(part, "a <button>") ?? []);
+    }
+}
+/**
+ * `<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 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 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 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 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 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 function defineModal(registry = globalThis.customElements) {
+    defineElements(registry, [
+        [ROOT, PrimitivModalElement],
+        [TRIGGER, PrimitivModalTriggerElement],
+        [CONTENT, PrimitivModalContentElement],
+        [TITLE, PrimitivModalTitleElement],
+        [DESCRIPTION, PrimitivModalDescriptionElement],
+        [CLOSE, PrimitivModalCloseElement],
+    ]);
+}

package/dist/modal/index.d.ts

@@ -0,0 +1,2 @@
+export { ModalController, type ModalControllerHost } from "./ModalController.js";
+export { defineModal, PrimitivModalCloseElement, PrimitivModalContentElement, PrimitivModalDescriptionElement, PrimitivModalElement, PrimitivModalTitleElement, PrimitivModalTriggerElement, } from "./elements.js";

package/dist/modal/index.js

@@ -0,0 +1,2 @@
+export { ModalController } from "./ModalController.js";
+export { defineModal, PrimitivModalCloseElement, PrimitivModalContentElement, PrimitivModalDescriptionElement, PrimitivModalElement, PrimitivModalTitleElement, PrimitivModalTriggerElement, } from "./elements.js";

package/dist/popover/PopoverController.d.ts

@@ -0,0 +1,55 @@
+/**
+ * What a {@link PopoverController} 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 PopoverControllerHost = {
+    /** The state the controller cannot see for itself. */
+    state(): {
+        /** Whether the popover is open. */
+        open: boolean;
+    };
+    /** Apply a change the user asked for: `open` is the state afterwards. */
+    change(open: boolean): void;
+    /** The trigger: Escape hands focus back to it, and a press on it is not an outside press. */
+    trigger(): HTMLElement | null;
+    /**
+     * The element to hand `showPopover({ source })`, which makes it the panel's
+     * implicit anchor for CSS anchor positioning. Optional: without it the panel
+     * is shown with no source, and positioning is the consumer's to wire.
+     */
+    source?(): HTMLElement | null;
+};
+/**
+ * The DOM behaviour of a popover, over a `popover="auto"` panel: the browser
+ * owns the top layer and light dismiss, and this adds the rest of the WAI-ARIA
+ * non-modal dialog pattern:
+ *
+ * - **Sync** — {@link PopoverController.sync | `sync()`} shows or hides the
+ *   panel to match the host's state, moving focus into it as it opens (its
+ *   first focusable, or the panel itself). A host calls it whenever that state
+ *   may have changed.
+ * - **Dismissal** — the browser light-dismissing the panel is reported, Escape
+ *   inside it closes it and hands focus back to the trigger, and where the
+ *   browser has no Popover API a press outside closes it.
+ *
+ * Opening from the trigger is the host's, as a plain click.
+ */
+export declare class PopoverController {
+    #private;
+    constructor(content: HTMLElement, host: PopoverControllerHost);
+    /**
+     * Start listening. Connecting again while connected does nothing, so a host
+     * whose lifecycle runs twice never stacks handlers.
+     */
+    connect(): void;
+    /**
+     * Stop listening, and forget the panel was showing: a host disconnects when
+     * it leaves the document, which hides a popover with no event, so the next
+     * sync shows it again.
+     */
+    disconnect(): void;
+    /** Show or hide the panel to match the host's state. */
+    sync(): void;
+}

package/dist/popover/PopoverController.js

@@ -0,0 +1,100 @@
+import { FOCUSABLE_SELECTOR, popoverKeydown, popoverPressDismisses } from "@primitiv-ui/core";
+/**
+ * The DOM behaviour of a popover, over a `popover="auto"` panel: the browser
+ * owns the top layer and light dismiss, and this adds the rest of the WAI-ARIA
+ * non-modal dialog pattern:
+ *
+ * - **Sync** — {@link PopoverController.sync | `sync()`} shows or hides the
+ *   panel to match the host's state, moving focus into it as it opens (its
+ *   first focusable, or the panel itself). A host calls it whenever that state
+ *   may have changed.
+ * - **Dismissal** — the browser light-dismissing the panel is reported, Escape
+ *   inside it closes it and hands focus back to the trigger, and where the
+ *   browser has no Popover API a press outside closes it.
+ *
+ * Opening from the trigger is the host's, as a plain click.
+ */
+export class PopoverController {
+    #content;
+    #host;
+    #connection = null;
+    /** Whether this controller showed the panel and has not hidden it since. */
+    #shown = false;
+    constructor(content, host) {
+        this.#content = content;
+        this.#host = host;
+    }
+    /**
+     * Start listening. 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;
+        this.#content.addEventListener("toggle", (event) => this.#toggle(event), { signal });
+        this.#content.addEventListener("keydown", (event) => this.#keydown(event), { signal });
+        document.addEventListener("click", (event) => this.#press(event), { signal });
+    }
+    /**
+     * Stop listening, and forget the panel was showing: a host disconnects when
+     * it leaves the document, which hides a popover with no event, so the next
+     * sync shows it again.
+     */
+    disconnect() {
+        this.#connection?.abort();
+        this.#connection = null;
+        this.#shown = false;
+    }
+    /** Show or hide the panel to match the host's state. */
+    sync() {
+        const { open } = this.#host.state();
+        if (open && !this.#shown) {
+            this.#shown = true;
+            const source = this.#host.source?.();
+            if (source)
+                this.#content.showPopover({ source });
+            else
+                this.#content.showPopover();
+            // Move focus into the panel (WAI-ARIA non-modal dialog): the first
+            // focusable, or the panel itself, which carries tabindex="-1".
+            (this.#content.querySelector(FOCUSABLE_SELECTOR) ?? this.#content).focus();
+        }
+        else if (!open && this.#shown) {
+            this.#shown = false;
+            try {
+                this.#content.hidePopover();
+            }
+            catch {
+                // Already hidden: the browser light-dismissed it first.
+            }
+        }
+    }
+    #toggle(event) {
+        if (event.newState !== "closed")
+            return;
+        this.#shown = false;
+        this.#host.change(false);
+    }
+    #keydown(event) {
+        // A popover nested in this panel handles its own Escape first, as the
+        // event bubbles out of it; leave that one alone, or both would close.
+        if (event.defaultPrevented || !popoverKeydown(event.key))
+            return;
+        event.preventDefault();
+        this.#host.change(false);
+        this.#host.trigger()?.focus();
+    }
+    #press(event) {
+        const target = event.target;
+        const dismisses = popoverPressDismisses({
+            open: this.#host.state().open,
+            nativeLightDismiss: "popover" in HTMLElement.prototype,
+            inTrigger: this.#host.trigger()?.contains(target) ?? false,
+            inPopover: target.closest("[popover]") !== null,
+        });
+        if (dismisses)
+            this.#host.change(false);
+    }
+}

package/dist/popover/elements.d.ts

@@ -0,0 +1,98 @@
+import { ElementBase, type ElementRegistry } from "../internal/element.js";
+import { PrimitivRootElement } from "../internal/RootElement.js";
+export type { ElementRegistry };
+/**
+ * `<primitiv-popover>` — the state owner of a non-modal popover: a trigger
+ * that opens a floating panel, built on the native Popover API. The browser
+ * puts the panel in the top layer and light-dismisses it; the element adds the
+ * rest of the WAI-ARIA non-modal dialog pattern — focus moves into the panel
+ * as it opens, Escape closes it and hands focus back to the trigger, and the
+ * trigger's `aria-expanded` follows it.
+ *
+ * The panel is shown with its trigger (or the anchor) as its source, which
+ * makes that element the panel's implicit anchor, so CSS anchor positioning
+ * (`position-area`) places it with no `anchor-name` to wire.
+ *
+ * The root finds its own parts, so a popover nested in a panel 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).
+ *
+ * @customElement primitiv-popover
+ * @summary The state owner of a non-modal popover on the native Popover API.
+ * @attr {boolean} open - Whether the panel is open. Reflected: it changes as the user opens and dismisses it, so a server re-render or a history snapshot sees the live state. Set it (or the `open` property) to open or close the panel from script.
+ * @fires {CustomEvent<{ open: boolean }>} primitiv-popover-change - Bubbles, cancelable, fired before a user-driven change is applied — a trigger or close click, Escape, or a light dismiss — with the open state afterwards. Call `preventDefault()` to veto it.
+ */
+export declare class PrimitivPopoverElement extends PrimitivRootElement {
+    #private;
+    protected readonly controller: {
+        connect(): void;
+        disconnect(): void;
+    };
+    protected readonly reconcileOn: readonly string[];
+    /** Whether the panel is open, reflected as the boolean `open` attribute. */
+    get open(): boolean;
+    set open(next: boolean);
+    protected reconcile(): void;
+}
+/**
+ * `<primitiv-popover-trigger>` — an interactive part. It decorates exactly one
+ * child the consumer writes, a `<button>`, which toggles the panel and receives
+ * `aria-haspopup="dialog"`, `aria-expanded` and `aria-controls`, so the
+ * rendered DOM matches React's (RFC 0033 D24).
+ *
+ * @customElement primitiv-popover-trigger
+ */
+export declare class PrimitivPopoverTriggerElement extends ElementBase {
+}
+/**
+ * `<primitiv-popover-anchor>` — optional. It decorates exactly one element the
+ * consumer writes, which the panel is anchored to in place of the trigger: a
+ * field, say, whose trigger is an icon inside it.
+ *
+ * @customElement primitiv-popover-anchor
+ */
+export declare class PrimitivPopoverAnchorElement extends ElementBase {
+}
+/**
+ * `<primitiv-popover-content>` — the panel. Structural: the root gives it an
+ * id, `role="dialog"`, `popover="auto"` (write it in your markup too, so the
+ * panel is hidden before the script loads), `tabindex="-1"`, `data-state`, and
+ * `aria-labelledby` / `aria-describedby` pointing at the title and description.
+ *
+ * @customElement primitiv-popover-content
+ */
+export declare class PrimitivPopoverContentElement extends ElementBase {
+}
+/**
+ * `<primitiv-popover-title>` — decorates exactly one heading the consumer
+ * writes, whose id becomes the panel's `aria-labelledby`.
+ *
+ * @customElement primitiv-popover-title
+ */
+export declare class PrimitivPopoverTitleElement extends ElementBase {
+}
+/**
+ * `<primitiv-popover-description>` — decorates exactly one element the
+ * consumer writes (a `<p>`, usually), whose id becomes the panel's
+ * `aria-describedby`.
+ *
+ * @customElement primitiv-popover-description
+ */
+export declare class PrimitivPopoverDescriptionElement extends ElementBase {
+}
+/**
+ * `<primitiv-popover-close>` — an interactive part. It decorates exactly one
+ * `<button>` the consumer writes, which closes the panel. A popover may have
+ * several.
+ *
+ * @customElement primitiv-popover-close
+ */
+export declare class PrimitivPopoverCloseElement extends ElementBase {
+}
+/**
+ * Define the seven Popover 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 definePopover(registry?: ElementRegistry | undefined): void;