@pienter/ui 0.3.0 → 0.7.1

package/{utils/controllers/dialog.ts → composables/useDialog.ts}

@@ -1,22 +1,30 @@
-import { lockScroll } from '../dom/scroll-lock.js';
+import {
+    type MaybeRefOrGetter,
+    type Ref,
+    onBeforeUnmount,
+    onMounted,
+    toValue,
+    watch,
+} from 'vue';
+import { lockScroll } from '../utils/dom/scroll-lock.js';
 
 /**
- * Imperative control surface returned by `mountDialog`. The controller
- * owns the dialog's runtime state (open/closed, scroll lock) and lets the
- * native `<dialog>` element handle top-layer rendering, focus trapping,
- * and Escape dismissal. Frameworks (Vue, Astro consumer scripts) act as
- * the trigger source — they call `open()` / `close()` and watch incoming
- * prop changes — but they never own state directly. This avoids the dual
- * state-machine problem where framework state and controller state desync.
+ * Handle returned by `useDialog`. The composable owns the dialog's
+ * runtime side-effects (scroll lock, focus override, `data-state`
+ * reflection) and lets the native `<dialog>` element handle top-layer
+ * rendering, focus trapping, and Escape dismissal. The component's
+ * reactive prop stays the source of truth for the open/closed boolean —
+ * the composable never closes on its own; it reports close intent via
+ * `onClose` and waits for the prop to change. This avoids the dual
+ * state-machine problem where component state and DOM state desync.
  */
-export interface DialogControl {
+export interface DialogHandle {
     open(): void;
     close(): void;
     isOpen(): boolean;
-    teardown(): void;
 }
 
-export interface DialogConfig {
+export interface UseDialogOptions {
     /**
      * ARIA role assigned to the `<dialog>` element. The browser's default
      * for `<dialog>` is `'dialog'`; only override (e.g. for AlertDialog)
@@ -24,16 +32,16 @@ export interface DialogConfig {
      */
     role?: 'dialog' | 'alertdialog';
     /**
-     * When `true`, the controller suppresses the default close behavior on
+     * When `true`, the composable suppresses the default close behavior on
      * Escape (by calling `event.preventDefault()` on the `cancel` event)
      * and ignores backdrop clicks. Used by AlertDialog. Default: `false`.
      */
-    persistent?: boolean;
+    persistent?: MaybeRefOrGetter<boolean>;
     /**
      * Where focus lands when the dialog opens.
      *
      * The native `<dialog>.showModal()` already auto-focuses the first
-     * focusable child (or the element with `[autofocus]`). This config
+     * focusable child (or the element with `[autofocus]`). This option
      * lets callers override that default:
      * - `'first'` (default): defer to the browser's native behavior.
      * - `'cancel'`: focus the element marked `[data-dialog-cancel]`
@@ -45,95 +53,71 @@ export interface DialogConfig {
      * it ALWAYS wins over the configured value (consumer override).
      */
     initialFocus?: 'first' | 'cancel' | HTMLElement | null;
+    /**
+     * Controlled open state. When the getter yields a boolean, the dialog
+     * follows it: `true` opens, `false` closes, `undefined` is ignored.
+     * The initial value is applied on mount.
+     */
+    open?: () => boolean | undefined;
+    /** Runs just before the dialog opens, on every open path. */
+    onBeforeOpen?: () => void;
     /**
      * Called when the user requests close (Escape key, backdrop click).
-     * The controller does NOT auto-close in this case — the framework
-     * reflects the close intent back through its prop/v-model and calls
-     * `close()` itself, keeping framework state authoritative for the
-     * open/closed boolean.
+     * The composable does NOT auto-close in this case — the component
+     * reflects the close intent back through its prop/v-model, and the
+     * controlled `open` getter (or an explicit `close()` call) performs
+     * the actual close.
      */
     onClose?: () => void;
 }
 
 /**
- * Mount the dialog controller on `el`, which MUST be a `<dialog>`
- * element. The native element provides top-layer rendering, focus
+ * Dialog behavior for a `<dialog>` element rendered by the calling
+ * component. The native element provides top-layer rendering, focus
  * trapping, Escape dismissal (via the `cancel` event), and the
- * `::backdrop` pseudo-element; this controller layers on body-scroll
+ * `::backdrop` pseudo-element; this composable layers on body-scroll
  * lock, backdrop-click dismissal, persistent suppression, an
  * `initialFocus` override, and `data-state` reflection so the existing
- * CSS conventions keep working.
- *
- * Lifecycle:
- * 1. On mount: optionally set `role` (AlertDialog uses `'alertdialog'`),
- *    wire `cancel` and `click` listeners.
- * 2. `open()`: capture trigger, call `el.showModal()` (native top-layer
- *    + focus trap), set `data-state="open"`, lock scroll, apply
- *    `initialFocus` override after a frame.
- * 3. `close()`: call `el.close()` (native focus restoration to trigger),
- *    set `data-state="closed"`, unlock scroll. A backup focus restore
- *    runs only when the browser fails to restore (e.g., the trigger
- *    was removed from the DOM mid-open).
- * 4. `teardown()`: ensures close ran, then removes listeners.
- *
- * The controller does NOT decide when to close — `onClose` is invoked
- * on user-requested close (Escape, backdrop click). The caller is
- * responsible for reflecting that into framework state and calling
- * `close()`. The framework's reactive prop is the source of truth for
- * open/closed; the controller is the source of truth for runtime
- * side-effects (focus override, scroll lock).
+ * CSS conventions keep working. Listeners are wired on mount and
+ * removed before unmount.
  */
-export function mountDialog(
-    el: HTMLDialogElement,
-    config: DialogConfig = {},
-): DialogControl {
-    const onClose = config.onClose;
-    const persistent = config.persistent ?? false;
-
-    // Optional role override — AlertDialog uses `'alertdialog'`. The
-    // browser's default for `<dialog>` is already `'dialog'`, so we only
-    // setAttribute when the caller asks for something different.
-    if (config.role && config.role !== 'dialog') {
-        el.setAttribute('role', config.role);
-    }
-
-    // Initial state.
-    el.setAttribute('data-state', 'closed');
-
+export function useDialog(
+    elRef: Ref<HTMLDialogElement | null>,
+    options: UseDialogOptions = {},
+): DialogHandle {
     // Per-open transient state.
     let triggerEl: HTMLElement | null = null;
     let unlockScrollFn: (() => void) | null = null;
 
+    const isPersistent = () => toValue(options.persistent) ?? false;
+
     // The native `cancel` event fires on Escape press. Browser default:
     // closes the dialog. For persistent dialogs, suppress the close.
     function handleCancel(event: Event): void {
-        if (persistent) {
+        if (isPersistent()) {
             event.preventDefault();
             return;
         }
-        onClose?.();
+        options.onClose?.();
     }
 
     // Backdrop click — `<dialog>` IS the backdrop element. Clicks on its
     // children bubble through with `event.target` set to the inner content,
-    // so a target equal to `el` means the click landed on the backdrop.
+    // so a target equal to the dialog means the click landed on the backdrop.
     function handleBackdropClick(event: MouseEvent): void {
-        if (persistent) return;
-        if (event.target !== el) return;
-        onClose?.();
+        if (isPersistent()) return;
+        if (event.target !== elRef.value) return;
+        options.onClose?.();
     }
 
-    el.addEventListener('cancel', handleCancel);
-    el.addEventListener('click', handleBackdropClick);
-
-    function resolveInitialFocus(): HTMLElement | null {
+    function resolveInitialFocus(el: HTMLDialogElement): HTMLElement | null {
         // Consumer override always wins.
         const override = el.querySelector<HTMLElement>(
             '[data-dialog-initial-focus]',
         );
         if (override) return override;
 
-        const target = config.initialFocus ?? 'first';
+        const target = options.initialFocus ?? 'first';
         if (target === null) return null;
         if (target instanceof HTMLElement) return target;
         if (target === 'cancel') {
@@ -144,7 +128,10 @@ export function mountDialog(
     }
 
     function open(): void {
-        if (el.open) return; // idempotent
+        const el = elRef.value;
+        if (!el || el.open) return; // idempotent
+
+        options.onBeforeOpen?.();
 
         // Capture the element that had focus before the dialog opened so
         // we can restore it on close if the browser fails to do so.
@@ -163,13 +150,14 @@ export function mountDialog(
         // child by default — only override when the consumer asked for it.
         requestAnimationFrame(() => {
             if (!el.open) return; // guard against rapid open→close
-            const target = resolveInitialFocus();
+            const target = resolveInitialFocus(el);
             if (target) target.focus();
         });
     }
 
     function close(): void {
-        if (!el.open) return; // idempotent
+        const el = elRef.value;
+        if (!el || !el.open) return; // idempotent
 
         el.close(); // native focus restoration to the trigger
         el.setAttribute('data-state', 'closed');
@@ -178,8 +166,8 @@ export function mountDialog(
 
         // Backup: if the browser failed to restore focus (e.g. the trigger
         // was removed from the DOM during the open, or the page lost focus),
-        // restore manually. We check for activeElement === body which is
-        // the browser's "no specific element focused" state.
+        // restore manually. activeElement === body is the browser's
+        // "no specific element focused" state.
         const trigger = triggerEl;
         triggerEl = null;
         if (
@@ -192,14 +180,38 @@ export function mountDialog(
     }
 
     function isOpen(): boolean {
-        return el.open;
+        return elRef.value?.open ?? false;
     }
 
-    function teardown(): void {
+    onMounted(() => {
+        const el = elRef.value;
+        if (!el) return;
+        // The browser's default role for `<dialog>` is already `'dialog'`,
+        // so only setAttribute when the caller asks for something different.
+        if (options.role && options.role !== 'dialog') {
+            el.setAttribute('role', options.role);
+        }
+        el.setAttribute('data-state', 'closed');
+        el.addEventListener('cancel', handleCancel);
+        el.addEventListener('click', handleBackdropClick);
+        if (options.open && toValue(options.open)) open();
+    });
+
+    if (options.open) {
+        watch(options.open, (value) => {
+            if (!elRef.value || value === undefined) return;
+            if (value) open();
+            else close();
+        });
+    }
+
+    onBeforeUnmount(() => {
+        const el = elRef.value;
+        if (!el) return;
         if (el.open) close();
         el.removeEventListener('cancel', handleCancel);
         el.removeEventListener('click', handleBackdropClick);
-    }
+    });
 
-    return { open, close, isOpen, teardown };
+    return { open, close, isOpen };
 }

package/composables/useDisclosure.ts

@@ -0,0 +1,113 @@
+import {
+    type MaybeRefOrGetter,
+    type Ref,
+    onBeforeUnmount,
+    onMounted,
+    toValue,
+} from 'vue';
+
+/**
+ * Disclosure behavior — shared by Accordion and Collapsible per the
+ * sharing mapping in `CONVENTIONS.md`.
+ *
+ * Built on the **native HTML `<details>` / `<summary>` element pair**
+ * per the locked "Use native APIs where applicable" rule. The browser
+ * already handles expand/collapse on summary click, the `[open]`
+ * attribute, Enter/Space activation, and focus on the summary rather
+ * than the panel. What the browser does NOT provide and the composable
+ * layers on top:
+ *
+ * - **Single-open coordination** for Accordion mode — when one
+ *   `<details>` opens, sibling `<details>` elements within the same
+ *   root close. Native `<details>` has no built-in mutual exclusion
+ *   (the `name` attribute exists in some browsers but is not reliable
+ *   cross-browser in 2026).
+ * - A **callback** so the component can react to toggles without each
+ *   `<details>` wiring its own `@toggle` listener.
+ *
+ * The root may be either a single `<details>` (Collapsible) or a
+ * wrapper containing multiple `<details>` children (Accordion).
+ */
+export interface UseDisclosureOptions {
+    /**
+     * When `true`, opening any **top-level** `<details>` within the
+     * root closes all sibling top-level `<details>` elements
+     * (Accordion single-open mode). A "top-level" `<details>` here
+     * means one whose nearest ancestor `<details>` lies outside the
+     * root — i.e., a disclosure that belongs to THIS root, not a
+     * nested disclosure inside an item's panel content.
+     *
+     * When `false`, multiple disclosures can be open simultaneously
+     * (Collapsible / Accordion multi-open mode). Read reactively —
+     * a getter or ref takes effect on the next toggle. Default: `false`.
+     */
+    singleOpen?: MaybeRefOrGetter<boolean>;
+    /**
+     * Called whenever a `<details>` within the root toggles. Receives
+     * the toggled element and its new open state, for reflecting the
+     * change back into reactive state (e.g. `update:open`). The
+     * composable does NOT track open state itself — the DOM is the
+     * source of truth via `el.open`.
+     */
+    onToggle?: (target: HTMLDetailsElement, open: boolean) => void;
+}
+
+/**
+ * Wire disclosure behavior on the element behind `elRef` for the
+ * component's lifetime. A single capturing `toggle` listener at the
+ * root covers any number of `<details>` descendants without
+ * per-element wiring.
+ */
+export function useDisclosure(
+    elRef: Ref<HTMLElement | null>,
+    options: UseDisclosureOptions = {},
+): void {
+    /**
+     * A `<details>` is "top-level" relative to the root when no other
+     * `<details>` lies between it and the root in the ancestor chain.
+     * Only top-level disclosures participate in single-open
+     * coordination — nested disclosures are part of the consumer's
+     * panel content and must not be closed by the outer root.
+     */
+    function isTopLevel(details: HTMLDetailsElement): boolean {
+        const el = elRef.value;
+        const parentDetails = details.parentElement?.closest('details') ?? null;
+        if (!parentDetails) return true;
+        // If the parent `<details>` is outside the root, treat
+        // `details` as top-level for THIS root.
+        return !el?.contains(parentDetails);
+    }
+
+    function handleToggle(event: Event): void {
+        const el = elRef.value;
+        const target = event.target;
+        if (!el || !(target instanceof HTMLDetailsElement)) return;
+        if (!el.contains(target)) return;
+
+        const singleOpen = toValue(options.singleOpen) ?? false;
+        if (singleOpen && target.open && isTopLevel(target)) {
+            // Close every other top-level `<details>` rooted here.
+            const allDetails =
+                el.querySelectorAll<HTMLDetailsElement>('details');
+            allDetails.forEach((other) => {
+                if (other === target) return;
+                if (!isTopLevel(other)) return;
+                if (other.open) other.open = false;
+            });
+        }
+
+        options.onToggle?.(target, target.open);
+    }
+
+    // `toggle` does not bubble in the standards sense — but a capturing
+    // listener fires for any descendant `<details>` toggle. Use capture
+    // phase so a single root listener covers every `<details>` within
+    // the scope.
+    onMounted(() => {
+        elRef.value?.addEventListener('toggle', handleToggle, true);
+    });
+
+    onBeforeUnmount(() => {
+        elRef.value?.removeEventListener('toggle', handleToggle, true);
+    });
+}

package/composables/useEventListener.ts

@@ -0,0 +1,16 @@
+import { onBeforeUnmount, onMounted } from 'vue';
+
+/**
+ * Bind a `window` listener for the lifetime of the component.
+ *
+ * Only for targets a template cannot reach. `window` is resolved inside
+ * `onMounted`, so a server-rendered component never touches it.
+ */
+export function useWindowListener<K extends keyof WindowEventMap>(
+    type: K,
+    listener: (event: WindowEventMap[K]) => void,
+    options?: AddEventListenerOptions,
+): void {
+    onMounted(() => window.addEventListener(type, listener, options));
+    onBeforeUnmount(() => window.removeEventListener(type, listener, options));
+}

package/composables/useMenu.ts

@@ -0,0 +1,212 @@
+import { type Ref, onBeforeUnmount, onMounted } from 'vue';
+
+/**
+ * Menu keyboard navigation for `role="menu"` surfaces. Pairs with
+ * `usePopover` (which owns open/close/positioning) to provide the
+ * menu-specific affordances per the WAI-ARIA Menu pattern:
+ * ArrowDown/Up cycle through items with wrap, Home/End jump to the
+ * ends, Escape closes via the consumer-supplied callback, and a click
+ * on a menu item triggers the activate-and-close consumer callback
+ * (`onItemActivate`).
+ *
+ * The items form a roving-tabindex group: only the focused item
+ * carries `tabindex="0"`; the rest carry `tabindex="-1"`. This is the
+ * canonical menu pattern — Tab moves focus past the menu rather than
+ * walking through every item.
+ *
+ * Item discovery is lazy — the keydown handler re-queries on every
+ * navigation event so consumers may add/remove menu items at runtime
+ * (e.g., async-loaded items or filter views) without re-wiring.
+ *
+ * Disabled items (`[disabled]` or `aria-disabled="true"`) are skipped
+ * during arrow / Home / End navigation so users do not get "stuck" on
+ * a non-actionable item.
+ *
+ * The composable does NOT decide when to close; consumers wire
+ * `onEscape` and `onItemActivate` to their popover handle's `hide()`
+ * (the standard dropdown menu UX is auto-close on activate).
+ */
+export interface UseMenuOptions {
+    /**
+     * Selector matching the menu items. Defaults to all three
+     * canonical menuitem roles so the same composable serves vanilla
+     * menus, checkbox-style menus, and radio-style menus. Override
+     * when the consumer needs to filter (e.g. exclude a group label).
+     */
+    itemSelector?: string;
+    /**
+     * Called when Escape is pressed inside the menu. The consumer
+     * typically forwards to the popover handle's `hide()` so the menu
+     * closes and focus returns to the trigger.
+     */
+    onEscape?: () => void;
+    /**
+     * Called when a menu item is activated by pointer click or by
+     * Enter / Space on the focused item. The consumer typically
+     * forwards to the popover handle's `hide()` so the menu
+     * auto-closes after a selection. Item-specific actions (the
+     * consumer's `@click` handler on each `<button role="menuitem">`)
+     * run independently and first (DOM events bubble bottom-up); this
+     * callback then closes the menu.
+     */
+    onItemActivate?: (item: HTMLElement) => void;
+}
+
+const DEFAULT_ITEM_SELECTOR =
+    '[role="menuitem"], [role="menuitemcheckbox"], [role="menuitemradio"]';
+
+/**
+ * Wire menu-style keyboard navigation onto the `role="menu"` container
+ * behind `menuRef` for the component's lifetime. Teardown leaves
+ * items' tabindex attributes as-is — a remount re-applies correct
+ * values, and removing them risks stomping author-supplied tabindex
+ * attributes the composable didn't set originally.
+ */
+export function useMenu(
+    menuRef: Ref<HTMLElement | null>,
+    options: UseMenuOptions = {},
+): void {
+    const itemSelector = options.itemSelector ?? DEFAULT_ITEM_SELECTOR;
+
+    function getItems(): HTMLElement[] {
+        const menuEl = menuRef.value;
+        if (!menuEl) return [];
+        return Array.from(menuEl.querySelectorAll<HTMLElement>(itemSelector));
+    }
+
+    function isDisabled(item: HTMLElement): boolean {
+        return (
+            item.hasAttribute('disabled') ||
+            item.getAttribute('aria-disabled') === 'true'
+        );
+    }
+
+    function getEnabledItems(): HTMLElement[] {
+        return getItems().filter((it) => !isDisabled(it));
+    }
+
+    function setRovingTabindex(
+        activeItem: HTMLElement | undefined,
+        items = getItems(),
+    ): void {
+        for (const item of items) {
+            item.setAttribute('tabindex', item === activeItem ? '0' : '-1');
+        }
+    }
+
+    function initRovingTabindex(): void {
+        const items = getItems();
+        setRovingTabindex(
+            items.find((item) => !isDisabled(item)),
+            items,
+        );
+    }
+
+    function focusItem(item: HTMLElement): void {
+        // Focusing the current item does not fire focusin.
+        if (document.activeElement === item) setRovingTabindex(item);
+        else {
+            item.setAttribute('tabindex', '0');
+            item.focus();
+        }
+    }
+
+    function moveFocus(direction: 1 | -1): void {
+        const enabled = getEnabledItems();
+        if (enabled.length === 0) return;
+
+        const active = document.activeElement as HTMLElement | null;
+        const currentIdx = active ? enabled.indexOf(active) : -1;
+
+        let nextIdx: number;
+        if (currentIdx === -1) {
+            // Focus is not on any enabled item (could be on the menu
+            // container itself, or a disabled item). Land on the first
+            // for ArrowDown, last for ArrowUp.
+            nextIdx = direction === 1 ? 0 : enabled.length - 1;
+        } else {
+            nextIdx =
+                (currentIdx + direction + enabled.length) % enabled.length;
+        }
+
+        focusItem(enabled[nextIdx]!);
+    }
+
+    function focusFirst(): void {
+        const enabled = getEnabledItems();
+        if (enabled.length > 0) focusItem(enabled[0]!);
+    }
+
+    function focusLast(): void {
+        const enabled = getEnabledItems();
+        if (enabled.length > 0) focusItem(enabled[enabled.length - 1]!);
+    }
+
+    function onKeydown(event: KeyboardEvent): void {
+        switch (event.key) {
+            case 'ArrowDown':
+                event.preventDefault();
+                moveFocus(1);
+                break;
+            case 'ArrowUp':
+                event.preventDefault();
+                moveFocus(-1);
+                break;
+            case 'Home':
+                event.preventDefault();
+                focusFirst();
+                break;
+            case 'End':
+                event.preventDefault();
+                focusLast();
+                break;
+            case 'Escape':
+                // The native Popover API also closes on Escape via
+                // `popover="auto"` light-dismiss; calling `onEscape`
+                // here lets consumers using `popover="manual"` (or
+                // future variants) hook the same key. No
+                // preventDefault — the browser's light-dismiss should
+                // still run for `auto` popovers.
+                options.onEscape?.();
+                break;
+            default:
+                break;
+        }
+    }
+
+    function onClick(event: MouseEvent): void {
+        const menuEl = menuRef.value;
+        const target = event.target as HTMLElement | null;
+        if (!menuEl || !target) return;
+        const item = target.closest<HTMLElement>(itemSelector);
+        if (!item || !menuEl.contains(item)) return;
+        if (isDisabled(item)) return;
+        options.onItemActivate?.(item);
+    }
+
+    function onFocusIn(event: FocusEvent): void {
+        const menuEl = menuRef.value;
+        const target = event.target as HTMLElement | null;
+        if (!menuEl || !target) return;
+        const item = target.closest<HTMLElement>(itemSelector);
+        if (!item || !menuEl.contains(item) || isDisabled(item)) return;
+        setRovingTabindex(item);
+    }
+
+    onMounted(() => {
+        const menuEl = menuRef.value;
+        if (!menuEl) return;
+        initRovingTabindex();
+        menuEl.addEventListener('keydown', onKeydown);
+        menuEl.addEventListener('click', onClick);
+        menuEl.addEventListener('focusin', onFocusIn);
+    });
+
+    onBeforeUnmount(() => {
+        const menuEl = menuRef.value;
+        if (!menuEl) return;
+        menuEl.removeEventListener('keydown', onKeydown);
+        menuEl.removeEventListener('click', onClick);
+        menuEl.removeEventListener('focusin', onFocusIn);
+    });
+}