stimeo-ui 0.2.1 → 0.3.0

data/dist/controllers/menubar_controller.js

@@ -2,6 +2,17 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/menubar_controller.ts
 
+// src/utils/logical_scroll.ts
+function isRtl(element) {
+  return window.getComputedStyle(element).direction === "rtl";
+}
+
+// src/utils/arrow_step.ts
+function isReservedArrowChord(event, allow = []) {
+  if (!event.key.startsWith("Arrow")) return false;
+  return event.altKey && !allow.includes("alt") || event.ctrlKey && !allow.includes("ctrl") || event.metaKey && !allow.includes("meta") || event.shiftKey && !allow.includes("shift");
+}
+
 // src/utils/escape_layer.ts
 function claimsWhileFocusWithin(element) {
   return () => {
@@ -178,32 +189,198 @@ var SafeTimeout = class extends TimerRegistry {
   }
 };
 
-// src/controllers/menubar_controller.ts
+// src/utils/typeahead.ts
 var TYPEAHEAD_RESET_MS = 500;
+var Typeahead = class {
+  /** Timer registry for the pending idle reset; private so `reset()` is the only exit. */
+  #timers = new SafeTimeout();
+  /** Idle window before the query resets, in milliseconds. */
+  #resetMs;
+  /** The accumulated lowercase query, empty when idle. */
+  #query = "";
+  /** Id of the pending reset timer, `0` when none is scheduled. */
+  #timerId = 0;
+  /** @param options - Overrides for the idle window. */
+  constructor({ resetMs = TYPEAHEAD_RESET_MS } = {}) {
+    this.#resetMs = resetMs;
+  }
+  /** The query a search would currently run with; empty while idle. */
+  get query() {
+    return this.#query;
+  }
+  /**
+   * Folds `key` into the query, restarts the idle window, and returns the query to
+   * search with. A repeated character collapses the query to that one character.
+   */
+  push(key) {
+    const char = key.toLowerCase();
+    const repeated = this.#query.length > 0 && [...this.#query].every((c) => c === char);
+    this.#query = repeated ? char : this.#query + char;
+    this.#timers.clear(this.#timerId);
+    this.#timerId = this.#timers.set(() => this.reset(), this.#resetMs);
+    return this.#query;
+  }
+  /** Clears the query and cancels the pending idle reset. */
+  reset() {
+    this.#query = "";
+    this.#timers.clear(this.#timerId);
+    this.#timerId = 0;
+  }
+};
+function isTypeaheadKey(event) {
+  return event.key.length === 1 && event.key !== " " && !event.ctrlKey && !event.metaKey && !event.altKey && !event.isComposing;
+}
+function typeaheadLabel(element, fallbackText) {
+  const label = element.getAttribute("aria-label")?.trim();
+  if (label) return label.toLowerCase();
+  const text = element.textContent ?? "";
+  return text.trim().toLowerCase();
+}
+function findTypeaheadMatch(items, from, query, label = (item) => typeaheadLabel(item)) {
+  if (query === "") return -1;
+  const count = items.length;
+  for (let step = 1; step <= count; step += 1) {
+    const index = ((from + step) % count + count) % count;
+    const candidate = items[index];
+    if (candidate && label(candidate).startsWith(query)) return index;
+  }
+  return -1;
+}
+
+// src/controllers/menubar_controller.ts
+var STATE_ATTRIBUTES = ["disabled", "hidden"];
 var MenubarController = class extends Controller {
   static targets = ["top", "menu", "item"];
   static actions = ["activate", "onItemKeydown", "onTopKeydown", "toggle"];
   /** Roving tabindex across the top-level menuitems (one Tab stop). */
   #roving = new RovingTabindex(() => this.topTargets);
-  /** Typeahead buffer and its idle-reset timer (scoped to the open menu). */
-  #typeahead = "";
-  #typeaheadId = 0;
+  /** Typeahead query and its idle-reset timer (scoped to the open menu). */
+  #typeahead = new Typeahead();
   #timers = new SafeTimeout();
   /** Escape-stack membership while a menu is open; the shared resolver dismisses via it. */
   #escapeLayer = new EscapeLayer();
-  /** Establishes the single tab stop and the closed baseline. */
+  /** Whether {@link #escapeLayer} is currently on the stack (see {@link #syncEscapeLayer}). */
+  #layerActive = false;
+  /** Watches `disabled`/`hidden` under the menubar; `null` while disconnected. */
+  #observer = null;
+  /**
+   * Live between `connect()` and `disconnect()`. Stimulus reports the *initial*
+   * targets before `connect()` and re-reports them as disconnected afterwards;
+   * gating on this keeps the target callbacks from clobbering the authored Tab
+   * stop on mount and from resurrecting one after teardown.
+   */
+  #connected = false;
+  /** The element inside the menubar that last took DOM focus, if any. */
+  #focused = null;
+  /**
+   * Records where DOM focus sits inside the menubar. `focusin` bubbles, so one
+   * listener covers the top items and everything nested in their menus. The
+   * record is needed because a top or menu becomes unreachable *before* this
+   * controller hears about it, by which point the browser has already reset
+   * `document.activeElement`.
+   */
+  #onFocusIn = (event) => {
+    this.#focused = event.target;
+  };
+  /**
+   * Forgets the record once focus genuinely lands on something else, so a later
+   * mutation cannot pull focus back in. A `relatedTarget` of `null` is the case
+   * that must be kept: it is what "focus went nowhere" looks like, which is
+   * exactly the state the rescue exists for.
+   */
+  #onFocusOut = (event) => {
+    const next = event.relatedTarget;
+    if (next && !this.element.contains(next)) this.#focused = null;
+  };
+  /**
+   * Establishes the closed baseline and the single tab stop: keep an existing tab
+   * stop when it is still navigable (so a Turbo cache restore preserves the user's
+   * position), else fall back to the first navigable top item.
+   *
+   * The outside-click listener is registered in the **capture** phase: in the
+   * bubble phase an inside handler that removes its own click target detaches the
+   * node before `contains()` runs, so an *inside* click would read as outside and
+   * close the menu.
+   */
   connect() {
-    const active = this.#roving.activeIndex;
-    this.#roving.setActive(active === -1 ? 0 : active);
     this.#closeAllMenus();
-    document.addEventListener("click", this.#onOutsideClick);
+    this.#reconcile();
+    this.element.addEventListener("click", this.#onDisabledClickCapture, true);
+    this.element.addEventListener("focusin", this.#onFocusIn);
+    this.element.addEventListener("focusout", this.#onFocusOut);
+    document.addEventListener("click", this.#onOutsideClick, true);
+    if (typeof MutationObserver !== "undefined") {
+      this.#observer = new MutationObserver(() => this.#reconcile());
+      this.#observer.observe(this.element, {
+        subtree: true,
+        childList: true,
+        attributes: true,
+        attributeFilter: STATE_ATTRIBUTES
+      });
+    }
+    this.#connected = true;
   }
-  /** Removes the document listener, stack membership, and any pending typeahead timer. */
+  /** Removes the listeners, stack membership, and any pending timer (typeahead / Tab close). */
   disconnect() {
+    this.#connected = false;
     this.#escapeLayer.deactivate();
-    document.removeEventListener("click", this.#onOutsideClick);
+    this.#layerActive = false;
+    this.element.removeEventListener("click", this.#onDisabledClickCapture, true);
+    this.element.removeEventListener("focusin", this.#onFocusIn);
+    this.element.removeEventListener("focusout", this.#onFocusOut);
+    document.removeEventListener("click", this.#onOutsideClick, true);
+    this.#focused = null;
+    this.#observer?.disconnect();
+    this.#observer = null;
+    this.#typeahead.reset();
     this.#timers.clearAll();
   }
+  /**
+   * A top item added at runtime is dropped out of the Tab sequence first — a fresh
+   * `<button>` is tabbable by default, which would leave the menubar with two Tab
+   * stops — before the lone stop is re-established.
+   */
+  topTargetConnected(top) {
+    if (!this.#connected) return;
+    top.tabIndex = -1;
+    this.#reconcile();
+  }
+  /**
+   * Removing a top item can strand two things: the Tab stop it held, and the menu
+   * it owned (which nothing could close afterwards).
+   *
+   * The departing element is handed back in a neutral state first. A target can
+   * leave without leaving the document — a morph that only drops the
+   * `data-*-target` token keeps the node — and it would then sit in the page
+   * carrying this controller's `tabindex="0"` (a second Tab stop next to the one
+   * re-established below) and an `aria-expanded="true"` nothing can collapse.
+   * When the node really is gone these writes are harmless no-ops.
+   */
+  topTargetDisconnected(top) {
+    if (!this.#connected) return;
+    top.tabIndex = -1;
+    if (this.#isExpanded(top)) top.setAttribute("aria-expanded", "false");
+    this.#reconcile();
+  }
+  /** See {@link MenubarController.menuTargetDisconnected}. */
+  menuTargetConnected() {
+    if (!this.#connected) return;
+    this.#reconcile();
+  }
+  /**
+   * A menu removed while open leaves its owner claiming `aria-expanded="true"` for
+   * a popup that no longer exists, and the menubar holding an Escape layer that
+   * would swallow presses meant for something else.
+   *
+   * As with {@link MenubarController.topTargetDisconnected}, the departing menu is
+   * closed first: a token-only removal leaves a visible popup in the page that no
+   * key and no click can dismiss any more.
+   */
+  menuTargetDisconnected(menu) {
+    if (!this.#connected) return;
+    if (!menu.hidden) menu.hidden = true;
+    this.#reconcile();
+  }
   /** Toggles a top item's menu. Bound via `data-action` (click on the top item). */
   toggle(event) {
     const top = event.currentTarget;
@@ -215,19 +392,22 @@ var MenubarController = class extends Controller {
   }
   /** Keyboard handling while focus is on a top item. */
   onTopKeydown(event) {
-    const tops = this.topTargets;
+    if (event.defaultPrevented) return;
+    if (isReservedArrowChord(event)) return;
+    const tops = this.#navigableTops;
     const index = tops.indexOf(event.currentTarget);
     if (index === -1) return;
     const length = tops.length;
     const anyOpen = this.#isAnyOpen;
+    const step = isRtl(this.element) ? -1 : 1;
     switch (event.key) {
       case "ArrowRight":
         event.preventDefault();
-        this.#gotoTop((index + 1) % length, anyOpen);
+        this.#gotoTop(tops[(index + step + length) % length], anyOpen);
         break;
       case "ArrowLeft":
         event.preventDefault();
-        this.#gotoTop((index - 1 + length) % length, anyOpen);
+        this.#gotoTop(tops[(index - step + length) % length], anyOpen);
         break;
       case "ArrowDown":
         event.preventDefault();
@@ -239,16 +419,21 @@ var MenubarController = class extends Controller {
         break;
       case "Home":
         event.preventDefault();
-        this.#gotoTop(0, anyOpen);
+        this.#gotoTop(tops[0], anyOpen);
         break;
       case "End":
         event.preventDefault();
-        this.#gotoTop(length - 1, anyOpen);
+        this.#gotoTop(tops[length - 1], anyOpen);
+        break;
+      case "Tab":
+        this.#closeMenusSoon();
         break;
     }
   }
   /** Keyboard handling while focus is on a menu item. */
   onItemKeydown(event) {
+    if (event.defaultPrevented) return;
+    if (isReservedArrowChord(event)) return;
     const item = event.currentTarget;
     const menu = item.closest("[role='menu']");
     if (!menu) return;
@@ -274,17 +459,17 @@ var MenubarController = class extends Controller {
         break;
       case "ArrowRight":
         event.preventDefault();
-        this.#moveToAdjacentMenu(menu, 1);
+        this.#moveToAdjacentMenu(menu, isRtl(this.element) ? -1 : 1);
         break;
       case "ArrowLeft":
         event.preventDefault();
-        this.#moveToAdjacentMenu(menu, -1);
+        this.#moveToAdjacentMenu(menu, isRtl(this.element) ? 1 : -1);
         break;
       case "Tab":
-        this.#closeAllMenus();
+        this.#closeMenusSoon();
         break;
       default:
-        if (this.#isTypeaheadKey(event)) {
+        if (isTypeaheadKey(event)) {
           event.preventDefault();
           this.#typeaheadTo(items, index, event.key);
         }
@@ -299,44 +484,89 @@ var MenubarController = class extends Controller {
     this.#closeAllMenus();
     this.#focusTop(top);
   }
-  /** Moves the roving focus to top `index`, opening its menu when one was open. */
-  #gotoTop(index, reopen) {
-    const top = this.topTargets[index];
+  /** Moves the roving focus to `top`, opening its menu when one was open. */
+  #gotoTop(top, reopen) {
     if (!top) return;
     if (reopen) {
       this.#openMenu(top, "first");
     } else {
-      this.#roving.setActive(index, { focus: true });
+      this.#roving.setActive(this.topTargets.indexOf(top), { focus: true });
     }
   }
-  /** Opens `top`'s menu (closing others) and focuses its first/last item. */
+  /**
+   * Opens `top`'s menu (closing others) and focuses its first/last item.
+   *
+   * Three kinds of top item never open a menu:
+   * - **`aria-disabled`** — focusable but never activated, and opening a popup is
+   *   activation.
+   * - **plain command** (no `aria-controls` at all) — a legitimate top item that
+   *   simply has no popup.
+   * - **dangling `aria-controls`** (names a menu that is not a target) — broken
+   *   markup.
+   *
+   * The first two still take the roving focus, and any open menu closes: the APG
+   * makes closing unconditional for the horizontal move ("closes the submenu,
+   * moves focus to the next menubar item, and *optionally* opens that item's
+   * submenu"), so only the opening half is skipped. Leaving the old menu open
+   * would strand a popup that no longer contains focus.
+   *
+   * The dangling case instead leaves the open/closed state and focus untouched
+   * rather than closing everything and dropping focus to the body — but only on
+   * this "open a menu" path. A dangling top is still an ordinary roving
+   * destination while nothing is open.
+   */
   #openMenu(top, focus) {
     if (!top) return;
-    this.#closeAllMenus();
     const menu = this.#menuFor(top);
-    if (!menu) return;
+    if (!menu || this.#isActivationBlocked(top)) {
+      if (menu || !top.hasAttribute("aria-controls")) {
+        this.#closeAllMenus();
+        this.#focusTop(top);
+      }
+      return;
+    }
+    this.#timers.clearAll();
+    this.#closeAllMenus();
     menu.hidden = false;
     top.setAttribute("aria-expanded", "true");
     this.#escapeLayer.activate(document, {
       onDismiss: () => this.#dismissOpenMenu(),
       claims: claimsWhileFocusWithin(this.element)
     });
+    this.#layerActive = true;
     this.#roving.setActive(this.topTargets.indexOf(top));
     const items = this.#itemsIn(menu);
     this.#focusAt(items, focus === "first" ? 0 : items.length - 1);
   }
-  /** Hides `top`'s menu and reflects the collapsed state. */
+  /**
+   * Hides `top`'s menu and reflects the collapsed state. A top item that controls
+   * no menu (a plain command in an otherwise popup-bearing menubar) is left alone
+   * — stamping `aria-expanded="false"` on it would announce a popup it lacks.
+   */
   #closeMenu(top) {
     if (!top) return;
     const menu = this.#menuFor(top);
-    if (menu) menu.hidden = true;
+    if (!menu) return;
+    menu.hidden = true;
     top.setAttribute("aria-expanded", "false");
-    if (!this.#isAnyOpen) this.#escapeLayer.deactivate();
+    this.#syncEscapeLayer();
   }
-  /** Closes every menu and resets the typeahead buffer. */
+  /** Closes every menu and resets the typeahead query. */
   #closeAllMenus() {
     for (const top of this.topTargets) this.#closeMenu(top);
-    this.#resetTypeahead();
+    this.#typeahead.reset();
+  }
+  /**
+   * Closes every menu on the next task instead of synchronously.
+   *
+   * Used by `Tab`: closing right away removes the focused element before the
+   * browser performs its own Tab move, which can restart traversal at the
+   * document head and lose the user's place in the Tab order.
+   */
+  #closeMenusSoon() {
+    if (!this.#isAnyOpen) return;
+    this.#timers.clearAll();
+    this.#timers.set(() => this.#closeAllMenus(), 0);
   }
   /**
    * Escape path, invoked by the shared resolver: pressed inside an open menu it
@@ -355,18 +585,143 @@ var MenubarController = class extends Controller {
     }
     this.#closeAllMenus();
   }
-  /** Opens the menu of the top item `delta` steps from the one owning `menu`. */
+  /** Opens the menu of the navigable top item `delta` steps from `menu`'s owner. */
   #moveToAdjacentMenu(menu, delta) {
     const top = this.#topFor(menu);
     if (!top) return;
-    const tops = this.topTargets;
-    const next = (tops.indexOf(top) + delta + tops.length) % tops.length;
+    const tops = this.#navigableTops;
+    const current = tops.indexOf(top);
+    if (current === -1) return;
+    const next = (current + delta + tops.length) % tops.length;
     this.#openMenu(tops[next], "first");
   }
-  /** Closes when a click lands outside the controller's element. */
+  /**
+   * Closes when a click lands outside the controller's element. Focus is left on
+   * whatever the user clicked — see the focus-restoration contract in the class
+   * docs.
+   */
   #onOutsideClick = (event) => {
     if (this.#isAnyOpen && !this.element.contains(event.target)) this.#closeAllMenus();
   };
+  /**
+   * Captures clicks so `aria-disabled` top items and commands cannot reach
+   * consumer handlers (nor `toggle`/`activate`). Native Enter/Space activation
+   * also synthesizes a click and is blocked here; natively `disabled` buttons
+   * dispatch no click at all.
+   */
+  #onDisabledClickCapture = (event) => {
+    const target = event.target;
+    if (!(target instanceof Node)) return;
+    const blocked = [...this.topTargets, ...this.itemTargets].some(
+      (element) => this.#isActivationBlocked(element) && element.contains(target)
+    );
+    if (!blocked) return;
+    event.preventDefault();
+    event.stopImmediatePropagation();
+  };
+  /**
+   * Re-derives every piece of state this controller owns from the live targets:
+   * expanded flags, menu visibility, the single Tab stop, and Escape-stack
+   * membership. Runtime DOM edits can leave those out of step with each other — a
+   * top can claim `aria-expanded="true"` after its menu target was removed or after
+   * being hidden itself, a menu can stay visible after its owning top was removed,
+   * an open pair can appear from a morph with no layer registered for it, and the
+   * Tab stop can end up on a now-inert top, on a runtime-added one, or on none at
+   * all. Nothing is remembered between calls (except which side of the Escape stack
+   * this layer is on, which the stack itself does not expose), so the outcome is the
+   * same whichever mutation arrived and calling it more often than needed is free.
+   */
+  #reconcile() {
+    for (const top of this.topTargets) {
+      const own = this.#menuFor(top);
+      if (this.#isExpanded(top) && (!own || own.hidden || !this.#isNavigable(top))) {
+        top.setAttribute("aria-expanded", "false");
+      }
+    }
+    for (const menu of this.menuTargets) {
+      if (menu.hidden) continue;
+      const owner = this.#topFor(menu);
+      if (!owner || !this.#isExpanded(owner)) menu.hidden = true;
+    }
+    this.#ensureTabStop();
+    this.#rescueFocus();
+    this.#syncEscapeLayer();
+  }
+  /**
+   * Returns DOM focus to the menubar when the element holding it became
+   * unreachable — hidden, natively disabled, or removed — and the document had
+   * nowhere to put it. The destination is the top item that now owns the Tab
+   * stop, which is where `Escape` from a closed menu would have left the user.
+   *
+   * Focus is only *restored*, never *stolen*: it moves solely when the tracked
+   * element can no longer take it **and** focus is either already gone or still
+   * sitting on that element. The second half is what makes a `hidden` ancestor
+   * work — a browser blurs the element it hides on its next style pass, not when
+   * the attribute is written, so waiting to observe `<body>` here would always
+   * come too early. Removal is the other side of the same condition: the browser
+   * has already fallen back to the body, or left a detached `activeElement`.
+   */
+  #rescueFocus() {
+    const focused = this.#focused;
+    if (!focused) return;
+    const owner = this.topTargets.find(
+      (top2) => top2 === focused || this.#menuFor(top2)?.contains(focused)
+    );
+    if (focused.isConnected && owner && this.#isNavigable(owner)) return;
+    const doc = this.element.ownerDocument;
+    const active = doc.activeElement;
+    const lost = active === null || active === doc.body || active === doc.documentElement || !active.isConnected || active === focused || focused.contains(active);
+    if (!lost) return;
+    const index = this.#roving.activeIndex;
+    const top = index === -1 ? void 0 : this.topTargets[index];
+    if (top && top !== focused && !focused.contains(top)) top.focus();
+  }
+  /**
+   * Brings Escape-stack membership back in line with what the DOM now says is
+   * open, in both directions.
+   *
+   * The deactivate half is the common one (something closed). The activate half
+   * covers a menu that became open *without* going through {@link #openMenu} —
+   * a Turbo morph that patches `aria-expanded` and the menu's `hidden` in place,
+   * which is legitimate here because the DOM is this controller's only source of
+   * truth. Without it the popup is visible but `Escape` does nothing, since no
+   * layer is registered to claim the press.
+   *
+   * `#layerActive` exists because re-activating an already-active layer moves it
+   * to the top of the stack, which would reshuffle nested layers on every
+   * unrelated mutation. Registering only on the false→true edge keeps activation
+   * ordered by when each layer actually opened.
+   */
+  #syncEscapeLayer() {
+    const open = this.#isAnyOpen;
+    if (open === this.#layerActive) return;
+    if (open) {
+      this.#escapeLayer.activate(document, {
+        onDismiss: () => this.#dismissOpenMenu(),
+        claims: claimsWhileFocusWithin(this.element)
+      });
+    } else {
+      this.#escapeLayer.deactivate();
+    }
+    this.#layerActive = open;
+  }
+  /**
+   * Re-establishes the single Tab stop: keep the current one while it is still
+   * navigable, else hand it to the first navigable top item. Every other top is
+   * explicitly removed from the Tab sequence, so a top that arrived tabbable
+   * cannot leave two stops behind. No Tab stop at all (`-1`) happens only when
+   * every top is inert, and is recovered from as soon as one becomes navigable.
+   */
+  #ensureTabStop() {
+    const active = this.#roving.activeIndex;
+    const activeTop = active === -1 ? void 0 : this.topTargets[active];
+    if (activeTop && this.#isNavigable(activeTop)) {
+      this.#roving.setActive(active);
+      return;
+    }
+    const first = this.#navigableTops[0];
+    this.#roving.setActive(first ? this.topTargets.indexOf(first) : -1);
+  }
   /** The menu element controlled by `top` (matched by `aria-controls`/`id`). */
   #menuFor(top) {
     const id = top.getAttribute("aria-controls");
@@ -377,9 +732,29 @@ var MenubarController = class extends Controller {
     if (!menu) return null;
     return this.topTargets.find((top) => top.getAttribute("aria-controls") === menu.id) ?? null;
   }
-  /** The item targets that live inside `menu`, in DOM order. */
+  /** The navigable item targets that live inside `menu`, in DOM order. */
   #itemsIn(menu) {
-    return this.itemTargets.filter((item) => menu.contains(item));
+    return this.itemTargets.filter((item) => menu.contains(item) && this.#isNavigable(item));
+  }
+  /** Top items eligible for the roving tab stop and the arrow keys. */
+  get #navigableTops() {
+    return this.topTargets.filter((top) => this.#isNavigable(top));
+  }
+  /**
+   * Whether `element` can take roving focus: `hidden` and natively `disabled`
+   * controls are out of reach and are skipped. `aria-disabled` is deliberately
+   * **not** checked — the APG keeps such items focusable so they stay
+   * discoverable, and {@link MenubarController.#isActivationBlocked} is what
+   * suppresses acting on them. CSS-only visibility is not detectable headlessly
+   * and stays the consumer's responsibility.
+   */
+  #isNavigable(element) {
+    if (element.hasAttribute("hidden")) return false;
+    return !element.disabled;
+  }
+  /** Whether `element` is `aria-disabled`: reachable, but never activated. */
+  #isActivationBlocked(element) {
+    return element.getAttribute("aria-disabled") === "true";
   }
   /** Moves DOM focus to the item at `index` (no-op if out of range). */
   #focusAt(items, index) {
@@ -398,33 +773,10 @@ var MenubarController = class extends Controller {
   get #isAnyOpen() {
     return this.topTargets.some((top) => this.#isExpanded(top));
   }
-  /**
-   * Whether the event is a single printable character usable for typeahead.
-   * `Space` is excluded: on a `<button>` menuitem it natively activates the item
-   * (Enter/Space → click), so swallowing it for typeahead would break activation.
-   */
-  #isTypeaheadKey(event) {
-    return event.key.length === 1 && event.key !== " " && !event.ctrlKey && !event.metaKey && !event.altKey;
-  }
-  /** Advances focus to the next item in `items` matching the accumulated buffer. */
+  /** Advances focus to the next item in `items` matching the accumulated query. */
   #typeaheadTo(items, current, key) {
-    this.#typeahead += key.toLowerCase();
-    this.#timers.clear(this.#typeaheadId);
-    this.#typeaheadId = this.#timers.set(() => this.#resetTypeahead(), TYPEAHEAD_RESET_MS);
-    const count = items.length;
-    for (let step = 1; step <= count; step++) {
-      const candidate = items[(current + step) % count];
-      const label = (candidate?.textContent ?? "").trim().toLowerCase();
-      if (label.startsWith(this.#typeahead)) {
-        candidate?.focus();
-        return;
-      }
-    }
-  }
-  /** Clears the typeahead buffer and its timer. */
-  #resetTypeahead() {
-    this.#typeahead = "";
-    this.#timers.clear(this.#typeaheadId);
+    const index = findTypeaheadMatch(items, current, this.#typeahead.push(key));
+    if (index !== -1) items[index]?.focus();
   }
 };