stimeo-ui 0.2.0 → 0.3.0

package/dist/controllers/menubar_controller.js

@@ -0,0 +1,785 @@
+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 () => {
+    const active = element.ownerDocument.activeElement;
+    return active === null || active === element.ownerDocument.body || element.contains(active);
+  };
+}
+var EscapeLayer = class _EscapeLayer {
+  static #registries = /* @__PURE__ */ new WeakMap();
+  #ownerDocument = null;
+  /** Dismissal callback while active; `null` when inactive. */
+  #onDismiss = null;
+  /** Live predicate deciding whether the layer claims a press; `null` = always. */
+  #claims = null;
+  /**
+   * Activates this layer at the top of its document's Escape stack, installing
+   * the document's shared resolver listener if this is its first layer.
+   * Re-activating an already-active layer moves it to the top.
+   */
+  activate(ownerDocument = document, options) {
+    this.deactivate();
+    let registry = _EscapeLayer.#registries.get(ownerDocument);
+    if (!registry) {
+      registry = _EscapeLayer.#createRegistry();
+      _EscapeLayer.#registries.set(ownerDocument, registry);
+      ownerDocument.addEventListener("keydown", registry.onKeydown);
+    }
+    registry.stack.push(this);
+    this.#ownerDocument = ownerDocument;
+    this.#onDismiss = options.onDismiss;
+    this.#claims = options.claims ?? null;
+  }
+  /**
+   * Removes this layer from its document's Escape stack, uninstalling the
+   * shared listener when the stack empties. Safe to call when inactive.
+   */
+  deactivate() {
+    const ownerDocument = this.#ownerDocument;
+    if (!ownerDocument) return;
+    const registry = _EscapeLayer.#registries.get(ownerDocument);
+    if (registry) {
+      const index = registry.stack.lastIndexOf(this);
+      if (index >= 0) registry.stack.splice(index, 1);
+      if (registry.stack.length === 0) {
+        ownerDocument.removeEventListener("keydown", registry.onKeydown);
+        _EscapeLayer.#registries.delete(ownerDocument);
+      }
+    }
+    this.#ownerDocument = null;
+    this.#onDismiss = null;
+    this.#claims = null;
+  }
+  /**
+   * Whether this active layer would own a press right now: it is the topmost
+   * layer whose {@link EscapeLayerOptions.claims} passes. Exposed for tests
+   * and diagnostics — production dismissal goes through the shared listener.
+   */
+  get ownsEscape() {
+    const ownerDocument = this.#ownerDocument;
+    if (!ownerDocument) return false;
+    const registry = _EscapeLayer.#registries.get(ownerDocument);
+    if (!registry) return false;
+    return _EscapeLayer.#resolveOwner(registry.stack) === this;
+  }
+  /** Builds a document's registry with its shared resolver listener. */
+  static #createRegistry() {
+    const registry = {
+      stack: [],
+      onKeydown: (event) => {
+        if (event.key !== "Escape" || event.defaultPrevented || event.isComposing) return;
+        const owner = _EscapeLayer.#resolveOwner(registry.stack);
+        if (!owner) return;
+        event.preventDefault();
+        owner.#onDismiss?.();
+      }
+    };
+    return registry;
+  }
+  /** The topmost stack layer whose claims predicate passes, or `null`. */
+  static #resolveOwner(stack) {
+    for (let index = stack.length - 1; index >= 0; index--) {
+      const layer = stack[index];
+      if (!layer) continue;
+      if (layer.#claims && !layer.#claims()) continue;
+      return layer;
+    }
+    return null;
+  }
+};
+
+// src/utils/roving_tabindex.ts
+var RovingTabindex = class {
+  /** Returns the current ordered item elements; called on every operation. */
+  #getItems;
+  /**
+   * @param getItems - Returns the current ordered item elements. Called on every
+   *   operation so the live target list is always used.
+   */
+  constructor(getItems) {
+    this.#getItems = getItems;
+  }
+  /** Index of the currently tabbable item (`tabindex="0"`), or `-1` if none. */
+  get activeIndex() {
+    return this.#getItems().findIndex((item) => item.tabIndex === 0);
+  }
+  /**
+   * Makes exactly the item at `index` tabbable (`tabindex="0"`) and removes every
+   * other item from the Tab sequence (`tabindex="-1"`). An out-of-range `index`
+   * (e.g. `-1`) leaves all items at `-1`, which a controller can use to express
+   * "nothing is currently tabbable".
+   *
+   * @param index - Position of the item to make tabbable.
+   * @param options - Pass `{ focus: true }` to also move DOM focus to that item.
+   */
+  setActive(index, { focus = false } = {}) {
+    const items = this.#getItems();
+    items.forEach((item, i) => {
+      item.tabIndex = i === index ? 0 : -1;
+    });
+    if (focus) items[index]?.focus();
+  }
+};
+
+// src/utils/safe_timeout.ts
+var TimerRegistry = class {
+  /** Live timer ids that have not yet been cleared (or, for timeouts, fired). */
+  ids = /* @__PURE__ */ new Set();
+  /**
+   * Cancels a single tracked timer.
+   *
+   * No-ops if the id is unknown (already cleared, fired, or never owned by this
+   * registry), so callers can clear defensively without guarding.
+   */
+  clear(id) {
+    if (this.ids.delete(id)) {
+      this.cancel(id);
+    }
+  }
+  /**
+   * Cancels every tracked timer. Call this from a controller's `disconnect()`
+   * to guarantee no timer outlives the element.
+   */
+  clearAll() {
+    for (const id of this.ids) {
+      this.cancel(id);
+    }
+    this.ids.clear();
+  }
+  /** Number of timers currently tracked (pending). */
+  get size() {
+    return this.ids.size;
+  }
+};
+var SafeTimeout = class extends TimerRegistry {
+  /**
+   * Schedules `callback` after `delay` ms and returns the timer id.
+   *
+   * The id is removed from the registry automatically when the timeout fires,
+   * so {@link TimerRegistry.size | size} reflects only still-pending timers.
+   */
+  set(callback, delay) {
+    const id = this.schedule(() => {
+      this.ids.delete(id);
+      callback();
+    }, delay);
+    this.ids.add(id);
+    return id;
+  }
+  schedule(callback, delay) {
+    return window.setTimeout(callback, delay);
+  }
+  cancel(id) {
+    window.clearTimeout(id);
+  }
+};
+
+// 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 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();
+  /** 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() {
+    this.#closeAllMenus();
+    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 listeners, stack membership, and any pending timer (typeahead / Tab close). */
+  disconnect() {
+    this.#connected = false;
+    this.#escapeLayer.deactivate();
+    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;
+    if (this.#isExpanded(top)) {
+      this.#closeMenu(top);
+    } else {
+      this.#openMenu(top, "first");
+    }
+  }
+  /** Keyboard handling while focus is on a top item. */
+  onTopKeydown(event) {
+    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(tops[(index + step + length) % length], anyOpen);
+        break;
+      case "ArrowLeft":
+        event.preventDefault();
+        this.#gotoTop(tops[(index - step + length) % length], anyOpen);
+        break;
+      case "ArrowDown":
+        event.preventDefault();
+        this.#openMenu(tops[index], "first");
+        break;
+      case "ArrowUp":
+        event.preventDefault();
+        this.#openMenu(tops[index], "last");
+        break;
+      case "Home":
+        event.preventDefault();
+        this.#gotoTop(tops[0], anyOpen);
+        break;
+      case "End":
+        event.preventDefault();
+        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;
+    const items = this.#itemsIn(menu);
+    const index = items.indexOf(item);
+    const length = items.length;
+    switch (event.key) {
+      case "ArrowDown":
+        event.preventDefault();
+        this.#focusAt(items, (index + 1) % length);
+        break;
+      case "ArrowUp":
+        event.preventDefault();
+        this.#focusAt(items, (index - 1 + length) % length);
+        break;
+      case "Home":
+        event.preventDefault();
+        this.#focusAt(items, 0);
+        break;
+      case "End":
+        event.preventDefault();
+        this.#focusAt(items, length - 1);
+        break;
+      case "ArrowRight":
+        event.preventDefault();
+        this.#moveToAdjacentMenu(menu, isRtl(this.element) ? -1 : 1);
+        break;
+      case "ArrowLeft":
+        event.preventDefault();
+        this.#moveToAdjacentMenu(menu, isRtl(this.element) ? 1 : -1);
+        break;
+      case "Tab":
+        this.#closeMenusSoon();
+        break;
+      default:
+        if (isTypeaheadKey(event)) {
+          event.preventDefault();
+          this.#typeaheadTo(items, index, event.key);
+        }
+        break;
+    }
+  }
+  /** Closes the owning menu after an item is activated and refocuses its top. */
+  activate(event) {
+    const item = event.currentTarget;
+    const menu = item.closest("[role='menu']");
+    const top = this.#topFor(menu);
+    this.#closeAllMenus();
+    this.#focusTop(top);
+  }
+  /** 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(this.topTargets.indexOf(top), { focus: true });
+    }
+  }
+  /**
+   * 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;
+    const menu = this.#menuFor(top);
+    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. 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) return;
+    menu.hidden = true;
+    top.setAttribute("aria-expanded", "false");
+    this.#syncEscapeLayer();
+  }
+  /** Closes every menu and resets the typeahead query. */
+  #closeAllMenus() {
+    for (const top of this.topTargets) this.#closeMenu(top);
+    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
+   * closes that menu and returns focus to its top item (the APG behavior);
+   * pressed while focus is on a top item (or fell to the body) it closes every
+   * menu without moving focus.
+   */
+  #dismissOpenMenu() {
+    const active = document.activeElement;
+    const menu = this.menuTargets.find((candidate) => candidate.contains(active));
+    if (menu) {
+      const top = this.#topFor(menu);
+      this.#closeMenu(top);
+      this.#focusTop(top);
+      return;
+    }
+    this.#closeAllMenus();
+  }
+  /** 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.#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. 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");
+    return id ? this.menuTargets.find((menu) => menu.id === id) ?? null : null;
+  }
+  /** The top item that controls `menu` (reverse of `#menuFor`). */
+  #topFor(menu) {
+    if (!menu) return null;
+    return this.topTargets.find((top) => top.getAttribute("aria-controls") === menu.id) ?? null;
+  }
+  /** The navigable item targets that live inside `menu`, in DOM order. */
+  #itemsIn(menu) {
+    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) {
+    items[index]?.focus();
+  }
+  /** Returns roving focus to a top item (and makes it the single tab stop). */
+  #focusTop(top) {
+    if (!top) return;
+    this.#roving.setActive(this.topTargets.indexOf(top), { focus: true });
+  }
+  /** Whether `top`'s menu is currently expanded. */
+  #isExpanded(top) {
+    return top.getAttribute("aria-expanded") === "true";
+  }
+  /** Whether any top item's menu is currently open. */
+  get #isAnyOpen() {
+    return this.topTargets.some((top) => this.#isExpanded(top));
+  }
+  /** Advances focus to the next item in `items` matching the accumulated query. */
+  #typeaheadTo(items, current, key) {
+    const index = findTypeaheadMatch(items, current, this.#typeahead.push(key));
+    if (index !== -1) items[index]?.focus();
+  }
+};
+
+export { MenubarController };
+//# sourceMappingURL=menubar_controller.js.map
+//# sourceMappingURL=menubar_controller.js.map