@pienter/ui 0.2.0 → 0.5.0

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/{utils/controllers/menu.ts → composables/useMenu.ts}

@@ -1,63 +1,53 @@
+import { type Ref, onBeforeUnmount, onMounted } from 'vue';
+
 /**
- * Menu controller — keyboard navigation for `role="menu"` surfaces.
- * Pairs with `mountPopover` (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 controller treats the items as 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.
+ * 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`).
  *
- * Mount on:
- * - The menu container element (the element that carries
- *   `role="menu"`). Items are queried inside the container via
- *   `itemSelector` (default covers `menuitem`,
- *   `menuitemcheckbox`, and `menuitemradio` roles).
+ * 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 (for e.g., async-loaded items or filter views) without
- * remounting the controller.
+ * 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 controller does NOT decide when to close; consumers wire
- * `onEscape` and `onItemActivate` to their popover control's
- * `hide()` (the standard dropdown menu UX is auto-close on activate).
+ * 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 MenuConfig {
-    /**
-     * The menu container element with `role="menu"`. Items are
-     * resolved by querying this element with `itemSelector`.
-     */
-    menuEl: HTMLElement;
+export interface UseMenuOptions {
     /**
      * Selector matching the menu items. Defaults to all three
-     * canonical menuitem roles so the same controller serves
-     * vanilla menus, checkbox-style menus, and radio-style menus.
-     * Override when the consumer needs to filter (e.g. exclude a
-     * group label) — but the role-based default is correct for the
-     * v1 DropdownMenu component.
+     * 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 `popoverControl.hide()` so the menu
+     * 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 `popoverControl.hide()` so the menu auto-closes
-     * after a selection — the standard menu UX. Item-specific
-     * actions (the consumer's `@click` handler on each
-     * `<button role="menuitem">`) run independently from this
-     * callback; the consumer's handler runs first, then this
-     * callback closes the menu.
+     * 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;
 }
@@ -66,47 +56,21 @@ const DEFAULT_ITEM_SELECTOR =
     '[role="menuitem"], [role="menuitemcheckbox"], [role="menuitemradio"]';
 
 /**
- * Wire menu-style keyboard navigation onto a `role="menu"`
- * container. Returns a teardown function that removes the
- * listeners and restores any tabindex attributes the controller
- * managed.
- *
- * Lifecycle:
- * 1. On mount: set `tabindex="-1"` on every item (only the
- *    currently-focused item gets `tabindex="0"` after the menu
- *    opens and the consumer focuses the first item). The first
- *    focus event inside the menu promotes that item.
- * 2. On `keydown` inside the menu:
- *    - ArrowDown moves to the next item; wraps to first.
- *    - ArrowUp moves to the previous item; wraps to last.
- *    - Home jumps to the first item.
- *    - End jumps to the last item.
- *    - Escape calls `onEscape`.
- *    - Enter / Space on an item calls `onItemActivate(item)` and
- *      lets the native click behavior of `<button>` items run on
- *      the same key. (Native `<button>` already triggers click on
- *      Enter/Space, so we only call `onItemActivate` to close;
- *      the consumer's click handler runs from the synthetic
- *      click.)
- * 3. On click of an item: call `onItemActivate(item)`. The
- *    consumer's own click handler runs first (DOM event bubbles
- *    bottom-up; we listen on the menu container).
- * 4. On `focus` inside the menu (capture): re-rove the tabindex
- *    so only the focused item has `tabindex="0"`.
- *
- * Cross-cutting:
- * - Disabled items (`[disabled]` or `aria-disabled="true"`) are
- *   skipped during arrow / Home / End navigation. They remain in
- *   the DOM and can still receive direct clicks (native
- *   `disabled` already blocks that), but the keyboard path
- *   skips them so users do not get "stuck" on a non-actionable
- *   item.
+ * 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 mountMenu(config: MenuConfig): () => void {
-    const menuEl = config.menuEl;
-    const itemSelector = config.itemSelector ?? DEFAULT_ITEM_SELECTOR;
+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));
     }
 
@@ -121,15 +85,12 @@ export function mountMenu(config: MenuConfig): () => void {
         return getItems().filter((it) => !isDisabled(it));
     }
 
-    // Initial roving tabindex — every item starts at `-1`. The
-    // first item is promoted to `0` so a Tab into the menu (rare —
+    // Initial roving tabindex — every item starts at `-1`. The first
+    // enabled item is promoted to `0` so a Tab into the menu (rare —
     // the trigger usually opens with explicit focus) lands somewhere.
     function initRovingTabindex(): void {
         const items = getItems();
         items.forEach((item, idx) => {
-            // Don't override an explicit author tabindex on disabled items;
-            // for active items, the first enabled item gets `0` and the
-            // rest get `-1`.
             if (isDisabled(item)) {
                 item.setAttribute('tabindex', '-1');
                 return;
@@ -139,8 +100,6 @@ export function mountMenu(config: MenuConfig): () => void {
         });
     }
 
-    initRovingTabindex();
-
     function focusItem(item: HTMLElement): void {
         // Promote the focus target to `tabindex="0"` and demote the
         // rest to `-1` BEFORE focusing — focus on a `tabindex="-1"`
@@ -206,10 +165,10 @@ export function mountMenu(config: MenuConfig): () => void {
                 // 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. We do NOT
+                // future variants) hook the same key. No
                 // preventDefault — the browser's light-dismiss should
                 // still run for `auto` popovers.
-                config.onEscape?.();
+                options.onEscape?.();
                 break;
             default:
                 break;
@@ -217,17 +176,19 @@ export function mountMenu(config: MenuConfig): () => void {
     }
 
     function onClick(event: MouseEvent): void {
+        const menuEl = menuRef.value;
         const target = event.target as HTMLElement | null;
-        if (!target) return;
+        if (!menuEl || !target) return;
         const item = target.closest<HTMLElement>(itemSelector);
         if (!item || !menuEl.contains(item)) return;
         if (isDisabled(item)) return;
-        config.onItemActivate?.(item);
+        options.onItemActivate?.(item);
     }
 
     function onFocusIn(event: FocusEvent): void {
+        const menuEl = menuRef.value;
         const target = event.target as HTMLElement | null;
-        if (!target) return;
+        if (!menuEl || !target) return;
         const item = target.closest<HTMLElement>(itemSelector);
         if (!item || !menuEl.contains(item) || isDisabled(item)) return;
         // Re-rove so only the freshly-focused item carries
@@ -239,17 +200,20 @@ export function mountMenu(config: MenuConfig): () => void {
         });
     }
 
-    menuEl.addEventListener('keydown', onKeydown);
-    menuEl.addEventListener('click', onClick);
-    menuEl.addEventListener('focusin', onFocusIn);
-
-    return function teardown(): void {
+    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);
-        // Leave items' tabindex attributes as-is — if the menu
-        // remounts, `initRovingTabindex` will re-apply correct values.
-        // Removing them risks stomping author-supplied tabindex
-        // attributes the controller didn't set originally.
-    };
+    });
 }