@primitiv-ui/web 0.1.56 → 0.1.57

package/dist/define/dropdown.d.ts

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

package/dist/define/dropdown.js

@@ -0,0 +1,12 @@
+/**
+ * Side-effect entry: importing this module defines the fourteen Dropdown
+ * elements (`<primitiv-dropdown>`, `-trigger`, `-content`, the items, groups,
+ * label, separator and indicator, and the `-sub` parts) on the global
+ * `customElements` registry.
+ *
+ * ```html
+ * <script type="module">import "@primitiv-ui/web/define/dropdown";</script>
+ * ```
+ */
+import { defineDropdown } from "../dropdown/elements.js";
+defineDropdown();

package/dist/define/index.d.ts

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

package/dist/define/index.js

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

package/dist/dropdown/DropdownController.d.ts

@@ -0,0 +1,63 @@
+/**
+ * What a {@link DropdownController} 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 DropdownControllerHost = {
+    /** The state the controller cannot see for itself. */
+    state(): {
+        /** Whether the menu is open. */
+        open: boolean;
+    };
+    /**
+     * Apply a change the user asked for: `open` is the state afterwards. A close
+     * can be reported more than once for one dismissal (the browser's and the
+     * press's), so the host decides what a repeat means.
+     */
+    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 menu's
+     * implicit anchor for CSS anchor positioning. Optional: without it the menu
+     * is shown with no source, and positioning is the consumer's to wire.
+     */
+    source?(): HTMLElement | null;
+};
+/**
+ * The DOM behaviour of a dropdown menu over a `popover="auto"` panel (WAI-ARIA
+ * APG Menu Button): the browser owns the top layer and light dismiss, and this
+ * adds the rest.
+ *
+ * - **Sync** — {@link DropdownController.sync | `sync()`} shows or hides the
+ *   menu to match the host's state, moving focus to its first enabled item as
+ *   it opens unless focus is already inside. A host calls it whenever that
+ *   state may have changed.
+ * - **Dismissal** — the browser hiding the menu is reported, and so is a press
+ *   outside it (not on the trigger, and not inside any popover, so a submenu
+ *   keeps its parent open).
+ * - **Keyboard** — the arrows, Home and End move through the enabled items of
+ *   the menu holding focus (this one or an open submenu inside it), Enter and
+ *   Space click the focused item, typing focuses the item it starts, and Escape
+ *   closes the menu and hands focus back to the trigger.
+ *
+ * Opening from the trigger, and what an item does when chosen, are the host's.
+ */
+export declare class DropdownController {
+    #private;
+    constructor(menu: HTMLElement, host: DropdownControllerHost);
+    /**
+     * 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 menu 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 menu to match the host's state. */
+    sync(): void;
+}

package/dist/dropdown/DropdownController.js

@@ -0,0 +1,130 @@
+import { MENU_ITEM_SELECTOR, MENU_TYPEAHEAD_RESET_MS, menuKeydown, menuTypeahead } from "@primitiv-ui/core";
+/**
+ * The DOM behaviour of a dropdown menu over a `popover="auto"` panel (WAI-ARIA
+ * APG Menu Button): the browser owns the top layer and light dismiss, and this
+ * adds the rest.
+ *
+ * - **Sync** — {@link DropdownController.sync | `sync()`} shows or hides the
+ *   menu to match the host's state, moving focus to its first enabled item as
+ *   it opens unless focus is already inside. A host calls it whenever that
+ *   state may have changed.
+ * - **Dismissal** — the browser hiding the menu is reported, and so is a press
+ *   outside it (not on the trigger, and not inside any popover, so a submenu
+ *   keeps its parent open).
+ * - **Keyboard** — the arrows, Home and End move through the enabled items of
+ *   the menu holding focus (this one or an open submenu inside it), Enter and
+ *   Space click the focused item, typing focuses the item it starts, and Escape
+ *   closes the menu and hands focus back to the trigger.
+ *
+ * Opening from the trigger, and what an item does when chosen, are the host's.
+ */
+export class DropdownController {
+    #menu;
+    #host;
+    #connection = null;
+    /** Whether this controller showed the menu and has not hidden it since. */
+    #shown = false;
+    /** The typeahead query so far, and the timer that lapses it. */
+    #query = "";
+    #lapse;
+    constructor(menu, host) {
+        this.#menu = menu;
+        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.#menu.addEventListener("toggle", (event) => this.#toggle(event), { signal });
+        this.#menu.addEventListener("keydown", (event) => this.#keydown(event), { signal });
+        document.addEventListener("click", (event) => this.#press(event), { signal });
+    }
+    /**
+     * Stop listening, and forget the menu 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 menu 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.#menu.showPopover({ source });
+            else
+                this.#menu.showPopover();
+            if (!this.#menu.contains(document.activeElement))
+                this.#menu.querySelector(MENU_ITEM_SELECTOR)?.focus();
+        }
+        else if (!open && this.#shown) {
+            this.#shown = false;
+            try {
+                this.#menu.hidePopover();
+            }
+            catch {
+                // Already hidden, or no longer a popover.
+            }
+        }
+    }
+    #toggle(event) {
+        if (event.newState !== "closed")
+            return;
+        this.#shown = false;
+        this.#host.change(false);
+    }
+    #keydown(event) {
+        // The items of the menu holding focus: this one, or an open submenu inside
+        // it — never those of a deeper, closed submenu. A key a script dispatches on
+        // the menu while focus is elsewhere searches this menu.
+        const scope = document.activeElement.closest("[popover]") ?? this.#menu;
+        const items = [...scope.querySelectorAll(MENU_ITEM_SELECTOR)].filter((item) => item.closest("[popover]") === scope);
+        const active = items.indexOf(document.activeElement);
+        const outcome = menuKeydown({ key: event.key, active, count: items.length });
+        if (outcome) {
+            event.preventDefault();
+            if ("focus" in outcome)
+                items[outcome.focus].focus();
+            else if ("activate" in outcome)
+                items[outcome.activate].click();
+            else {
+                this.#host.change(false);
+                this.#host.trigger()?.focus();
+            }
+            return;
+        }
+        const typed = menuTypeahead({
+            query: this.#query,
+            key: event.key,
+            labels: items.map((item) => item.textContent),
+            active,
+        });
+        if (!typed)
+            return;
+        this.#query = typed.query;
+        clearTimeout(this.#lapse);
+        this.#lapse = setTimeout(() => (this.#query = ""), MENU_TYPEAHEAD_RESET_MS);
+        if (typed.focus === null)
+            return;
+        event.preventDefault();
+        items[typed.focus].focus();
+    }
+    #press(event) {
+        if (!this.#host.state().open)
+            return;
+        const target = event.target;
+        if (this.#host.trigger()?.contains(target) || target.closest("[popover]"))
+            return;
+        this.#host.change(false);
+    }
+}

package/dist/dropdown/DropdownSubController.d.ts

@@ -0,0 +1,34 @@
+import type { DropdownControllerHost } from "./DropdownController.js";
+/**
+ * What a {@link DropdownSubController} asks of whoever hosts it: a dropdown
+ * host's calls, for the submenu, plus the key that closes it.
+ */
+export type DropdownSubControllerHost = DropdownControllerHost & {
+    /** The arrow that closes the submenu: the one pointing back at its parent, `ArrowLeft` in a left-to-right menu. */
+    closeKey(): string;
+};
+/**
+ * The DOM behaviour of a submenu over a `popover="auto"` panel nested inside
+ * its parent menu. The parent's {@link DropdownController} moves focus through
+ * the submenu's items, since their keys bubble to it; this adds what is the
+ * submenu's own.
+ *
+ * - **Sync** — {@link DropdownSubController.sync | `sync()`} shows or hides the
+ *   submenu to match the host's state, moving focus to its first enabled item
+ *   as it opens.
+ * - **Dismissal** — the browser hiding the submenu is reported, and its close
+ *   key closes it and hands focus back to its trigger, without the parent menu
+ *   seeing the key.
+ *
+ * Opening from the sub-trigger (a click, a hover or the open key) is the host's.
+ */
+export declare class DropdownSubController {
+    #private;
+    constructor(menu: HTMLElement, host: DropdownSubControllerHost);
+    /** Start listening. Connecting again while connected does nothing. */
+    connect(): void;
+    /** Stop listening, and forget the submenu was showing, as {@link DropdownController.disconnect} does. */
+    disconnect(): void;
+    /** Show or hide the submenu to match the host's state. */
+    sync(): void;
+}

package/dist/dropdown/DropdownSubController.js

@@ -0,0 +1,78 @@
+import { MENU_ITEM_SELECTOR } from "@primitiv-ui/core";
+/**
+ * The DOM behaviour of a submenu over a `popover="auto"` panel nested inside
+ * its parent menu. The parent's {@link DropdownController} moves focus through
+ * the submenu's items, since their keys bubble to it; this adds what is the
+ * submenu's own.
+ *
+ * - **Sync** — {@link DropdownSubController.sync | `sync()`} shows or hides the
+ *   submenu to match the host's state, moving focus to its first enabled item
+ *   as it opens.
+ * - **Dismissal** — the browser hiding the submenu is reported, and its close
+ *   key closes it and hands focus back to its trigger, without the parent menu
+ *   seeing the key.
+ *
+ * Opening from the sub-trigger (a click, a hover or the open key) is the host's.
+ */
+export class DropdownSubController {
+    #menu;
+    #host;
+    #connection = null;
+    /** Whether this controller showed the submenu and has not hidden it since. */
+    #shown = false;
+    constructor(menu, host) {
+        this.#menu = menu;
+        this.#host = host;
+    }
+    /** Start listening. Connecting again while connected does nothing. */
+    connect() {
+        if (this.#connection)
+            return;
+        this.#connection = new AbortController();
+        const { signal } = this.#connection;
+        this.#menu.addEventListener("toggle", (event) => this.#toggle(event), { signal });
+        this.#menu.addEventListener("keydown", (event) => this.#keydown(event), { signal });
+    }
+    /** Stop listening, and forget the submenu was showing, as {@link DropdownController.disconnect} does. */
+    disconnect() {
+        this.#connection?.abort();
+        this.#connection = null;
+        this.#shown = false;
+    }
+    /** Show or hide the submenu 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.#menu.showPopover({ source });
+            else
+                this.#menu.showPopover();
+            this.#menu.querySelector(MENU_ITEM_SELECTOR)?.focus();
+        }
+        else if (!open && this.#shown) {
+            this.#shown = false;
+            try {
+                this.#menu.hidePopover();
+            }
+            catch {
+                // Already hidden, or no longer a popover.
+            }
+        }
+    }
+    #toggle(event) {
+        if (event.newState !== "closed")
+            return;
+        this.#shown = false;
+        this.#host.change(false);
+    }
+    #keydown(event) {
+        if (event.key !== this.#host.closeKey())
+            return;
+        event.preventDefault();
+        event.stopPropagation();
+        this.#host.change(false);
+        this.#host.trigger()?.focus();
+    }
+}

package/dist/dropdown/elements.d.ts

@@ -0,0 +1,174 @@
+import { ElementBase, type ElementRegistry } from "../internal/element.js";
+import { PrimitivRootElement } from "../internal/RootElement.js";
+export type { ElementRegistry };
+/**
+ * `<primitiv-dropdown>` — the state owner of a dropdown menu (WAI-ARIA APG
+ * Menu Button): a trigger that opens a menu of items. The menu is a
+ * `popover="auto"` in the top layer, shown with the trigger as its source,
+ * which makes the trigger its implicit anchor for CSS anchor positioning.
+ * Choosing an item — any item, a submenu's too — closes the menu and hands
+ * focus back to the trigger.
+ *
+ * The root finds its own parts 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-dropdown
+ * @summary The state owner of a dropdown menu.
+ * @attr {boolean} open - Whether the menu is open. Reflected: it changes as the user opens and dismisses it. Set it (or the `open` property) to open or close it from script.
+ * @fires {CustomEvent<{ open: boolean }>} primitiv-dropdown-change - Bubbles, cancelable, fired before a user-driven change is applied — the trigger, Escape, a press outside or a chosen item — with the open state afterwards. Call `preventDefault()` to veto it.
+ * @fires {CustomEvent<null>} primitiv-dropdown-select - Bubbles, cancelable, fired on the item part when an item is chosen, after a checkbox or radio item has changed. Call `preventDefault()` to keep the menu open.
+ * @fires {CustomEvent<{ checked: boolean }>} primitiv-dropdown-checked-change - Bubbles, cancelable, fired on a checkbox item before it changes, with its state afterwards. Call `preventDefault()` to veto it.
+ * @fires {CustomEvent<{ value: string }>} primitiv-dropdown-value-change - Bubbles, cancelable, fired on a radio group before its value changes, with the value afterwards. Call `preventDefault()` to veto it.
+ */
+export declare class PrimitivDropdownElement extends PrimitivRootElement {
+    #private;
+    protected readonly controller: {
+        connect(): void;
+        disconnect(): void;
+    };
+    protected readonly reconcileOn: readonly string[];
+    /** Whether the menu is open, reflected as the boolean `open` attribute. */
+    get open(): boolean;
+    set open(next: boolean);
+    protected reconcile(): void;
+}
+/**
+ * `<primitiv-dropdown-sub>` — the state owner of a submenu, inside a dropdown's
+ * menu: a sub-trigger row that opens a nested menu on a click, a hover, or the
+ * arrow pointing away from its parent (ArrowRight, or ArrowLeft right to
+ * left), and closes it on the arrow back, or when the pointer moves to another
+ * row of the parent menu.
+ *
+ * @customElement primitiv-dropdown-sub
+ * @summary The state owner of a submenu.
+ * @attr {boolean} open - Whether the submenu is open. Reflected.
+ * @fires {CustomEvent<{ open: boolean }>} primitiv-dropdown-sub-change - Bubbles, cancelable, fired before a user-driven change is applied, with the open state afterwards. Call `preventDefault()` to veto it.
+ */
+export declare class PrimitivDropdownSubElement extends PrimitivRootElement {
+    #private;
+    protected readonly controller: {
+        connect(): void;
+        disconnect(): void;
+    };
+    protected readonly reconcileOn: readonly string[];
+    /** Whether the submenu is open, reflected as the boolean `open` attribute. */
+    get open(): boolean;
+    set open(next: boolean);
+    protected reconcile(): void;
+}
+/**
+ * `<primitiv-dropdown-trigger>` — an interactive part. It decorates exactly
+ * one child the consumer writes, a `<button>`, which toggles the menu and is
+ * its menu button (`aria-haspopup`, `aria-expanded`, `aria-controls`).
+ *
+ * @customElement primitiv-dropdown-trigger
+ */
+export declare class PrimitivDropdownTriggerElement extends ElementBase {
+}
+/**
+ * `<primitiv-dropdown-content>` — the menu itself. Structural: the root gives
+ * it an id, `role="menu"` and `popover="auto"` (write it in your markup too, so
+ * it is hidden before the script loads).
+ *
+ * @customElement primitiv-dropdown-content
+ */
+export declare class PrimitivDropdownContentElement extends ElementBase {
+}
+/**
+ * `<primitiv-dropdown-item>` — an interactive part: one item. It decorates
+ * exactly one child the consumer writes, an `<li>` (or a link), which gets
+ * `role="menuitem"`, `tabindex="-1"` and `data-highlighted` while the pointer
+ * is over it.
+ *
+ * @customElement primitiv-dropdown-item
+ * @attr {boolean} disabled - Skipped by the keyboard, and does nothing when clicked (`aria-disabled` on the child).
+ */
+export declare class PrimitivDropdownItemElement extends ElementBase {
+}
+/**
+ * `<primitiv-dropdown-checkbox-item>` — an item that toggles. Its child gets
+ * `role="menuitemcheckbox"` and `aria-checked`.
+ *
+ * @customElement primitiv-dropdown-checkbox-item
+ * @attr {boolean} checked - Whether it is checked; `checked="indeterminate"` for mixed. Reflected.
+ * @attr {boolean} disabled - As on an item.
+ */
+export declare class PrimitivDropdownCheckboxItemElement extends ElementBase {
+}
+/**
+ * `<primitiv-dropdown-radio-group>` — a group of radio items, one of which is
+ * checked. Structural: `role="group"`.
+ *
+ * @customElement primitiv-dropdown-radio-group
+ * @attr {string} value - The checked item's value. Reflected.
+ */
+export declare class PrimitivDropdownRadioGroupElement extends ElementBase {
+}
+/**
+ * `<primitiv-dropdown-radio-item>` — an item checked when its value is its
+ * group's. Its child gets `role="menuitemradio"` and `aria-checked`.
+ *
+ * @customElement primitiv-dropdown-radio-item
+ * @attr {string} value - The value it sets on its group.
+ * @attr {boolean} disabled - As on an item.
+ */
+export declare class PrimitivDropdownRadioItemElement extends ElementBase {
+}
+/**
+ * `<primitiv-dropdown-item-indicator>` — the check or dot inside a checkbox or
+ * radio item, `hidden` while unchecked. Structural: it gets `data-state`.
+ *
+ * @customElement primitiv-dropdown-item-indicator
+ * @attr {boolean} force-mount - Keep it shown while unchecked, to animate it.
+ */
+export declare class PrimitivDropdownItemIndicatorElement extends ElementBase {
+}
+/**
+ * `<primitiv-dropdown-group>` — a labelled group of items. Structural:
+ * `role="group"`, named by the label inside it.
+ *
+ * @customElement primitiv-dropdown-group
+ */
+export declare class PrimitivDropdownGroupElement extends ElementBase {
+}
+/**
+ * `<primitiv-dropdown-label>` — a group's label, not an item. Structural: the
+ * root gives it an id.
+ *
+ * @customElement primitiv-dropdown-label
+ */
+export declare class PrimitivDropdownLabelElement extends ElementBase {
+}
+/**
+ * `<primitiv-dropdown-separator>` — a rule between items. Structural:
+ * `role="separator"`.
+ *
+ * @customElement primitiv-dropdown-separator
+ */
+export declare class PrimitivDropdownSeparatorElement extends ElementBase {
+}
+/**
+ * `<primitiv-dropdown-sub-trigger>` — the row that opens a submenu. It
+ * decorates exactly one child, an `<li>`, which gets `role="menuitem"` and the
+ * submenu's `aria-haspopup`, `aria-expanded` and `aria-controls`.
+ *
+ * @customElement primitiv-dropdown-sub-trigger
+ * @attr {boolean} disabled - It does not open the submenu.
+ */
+export declare class PrimitivDropdownSubTriggerElement extends ElementBase {
+}
+/**
+ * `<primitiv-dropdown-sub-content>` — the submenu itself, inside the parent
+ * menu. Structural, as the content: an id, `role="menu"`, `popover="auto"`.
+ *
+ * @customElement primitiv-dropdown-sub-content
+ */
+export declare class PrimitivDropdownSubContentElement extends ElementBase {
+}
+/**
+ * Define the fourteen Dropdown 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 defineDropdown(registry?: ElementRegistry | undefined): void;