stimeo-ui 0.16.0 → 0.17.0

data/dist/controllers/menubar_controller.js

@@ -1,19 +1,46 @@
 import { Controller } from '@hotwired/stimulus';
 
-// src/controllers/menubar_controller.ts
+var FOCUS_EVENTS = /* @__PURE__ */ new Set(["blur", "focus", "focusin", "focusout"]);
+var POINTER_EVENTS = /* @__PURE__ */ new Set(["mouseenter", "mouseleave", "pointerenter", "pointerleave"]);
+function stateReasonFor(event) {
+  if (!event) return "api";
+  if (FOCUS_EVENTS.has(event.type)) return "focus";
+  if (POINTER_EVENTS.has(event.type)) return "pointer";
+  return "user";
+}
+
+function actionSource(source) {
+  if (source instanceof HTMLElement) {
+    return { event: null, host: source, origin: source, reason: "api" };
+  }
+  const event = source ?? null;
+  return {
+    event,
+    host: event?.currentTarget instanceof Element ? event.currentTarget : null,
+    origin: event?.target instanceof Element ? event.target : null,
+    reason: stateReasonFor(event)
+  };
+}
 
-// 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 sharedRegistry(key, create) {
+  const symbol = Symbol.for(key);
+  const scope = globalThis;
+  const existing = scope[symbol];
+  if (existing !== void 0) return existing;
+  const registry = create();
+  Object.defineProperty(globalThis, symbol, { value: registry });
+  return registry;
+}
+
 function claimsWhileFocusWithin(element) {
   return () => {
     const active = element.ownerDocument.activeElement;
@@ -21,17 +48,11 @@ function claimsWhileFocusWithin(element) {
   };
 }
 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.
-   */
+  static #registries = sharedRegistry(
+    "stimeo-ui.escape-layer.registry.v1",
+    () => /* @__PURE__ */ new WeakMap()
+  );
+  #active = null;
   activate(ownerDocument = document, options) {
     this.deactivate();
     let registry = _EscapeLayer.#registries.get(ownerDocument);
@@ -40,44 +61,31 @@ var EscapeLayer = class _EscapeLayer {
       _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.
-   */
+    const entry = { onDismiss: options.onDismiss, claims: options.claims ?? null };
+    registry.stack.push(entry);
+    this.#active = { document: ownerDocument, entry };
+  }
   deactivate() {
-    const ownerDocument = this.#ownerDocument;
-    if (!ownerDocument) return;
-    const registry = _EscapeLayer.#registries.get(ownerDocument);
+    const active = this.#active;
+    if (!active) return;
+    const registry = _EscapeLayer.#registries.get(active.document);
     if (registry) {
-      const index = registry.stack.lastIndexOf(this);
+      const index = registry.stack.lastIndexOf(active.entry);
       if (index >= 0) registry.stack.splice(index, 1);
       if (registry.stack.length === 0) {
-        ownerDocument.removeEventListener("keydown", registry.onKeydown);
-        _EscapeLayer.#registries.delete(ownerDocument);
+        active.document.removeEventListener("keydown", registry.onKeydown);
+        _EscapeLayer.#registries.delete(active.document);
       }
     }
-    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.
-   */
+    this.#active = null;
+  }
   get ownsEscape() {
-    const ownerDocument = this.#ownerDocument;
-    if (!ownerDocument) return false;
-    const registry = _EscapeLayer.#registries.get(ownerDocument);
+    const active = this.#active;
+    if (!active) return false;
+    const registry = _EscapeLayer.#registries.get(active.document);
     if (!registry) return false;
-    return _EscapeLayer.#resolveOwner(registry.stack) === this;
+    return _EscapeLayer.#resolveOwner(registry.stack) === active.entry;
   }
-  /** Builds a document's registry with its shared resolver listener. */
   static #createRegistry() {
     const registry = {
       stack: [],
@@ -86,24 +94,22 @@ var EscapeLayer = class _EscapeLayer {
         const owner = _EscapeLayer.#resolveOwner(registry.stack);
         if (!owner) return;
         event.preventDefault();
-        owner.#onDismiss?.();
+        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;
+      if (layer.claims && !layer.claims()) continue;
       return layer;
     }
     return null;
   }
 };
 
-// src/utils/event_owner.ts
 function ownerIndex(candidates, node) {
   if (!(node instanceof Node)) return -1;
   return candidates.findIndex((candidate) => candidate.contains(node));
@@ -112,31 +118,78 @@ function ownerOf(candidates, node) {
   return candidates[ownerIndex(candidates, node)] ?? null;
 }
 
-// src/utils/roving_tabindex.ts
+var ListenerSet = class {
+  #abort = new AbortController();
+  add(target, type, handler, options) {
+    target.addEventListener(type, handler, { ...options, signal: this.#abort.signal });
+  }
+  dispose() {
+    this.#abort.abort();
+    this.#abort = new AbortController();
+  }
+};
+
+var MicrotaskCoalescer = class {
+  #run;
+  #queued = false;
+  #active = false;
+  #generation = 0;
+  constructor(run) {
+    this.#run = run;
+  }
+  activate() {
+    this.#active = true;
+  }
+  cancel() {
+    this.#active = false;
+    this.#queued = false;
+    this.#generation += 1;
+  }
+  schedule() {
+    if (!this.#active || this.#queued) return;
+    this.#queued = true;
+    const generation = this.#generation;
+    queueMicrotask(() => {
+      if (generation !== this.#generation || !this.#queued || !this.#active) return;
+      this.#queued = false;
+      this.#run();
+    });
+  }
+};
+
+var MorphRenderWatcher = class {
+  #listeners = new ListenerSet();
+  #pass;
+  #element = null;
+  #onMorph = () => this.#pass.schedule();
+  constructor(run) {
+    this.#pass = new MicrotaskCoalescer(run);
+  }
+  observe(element) {
+    if (this.#element === element) return;
+    this.disconnect();
+    this.#element = element;
+    this.#pass.activate();
+    this.#listeners.add(element, "turbo:morph-element", this.#onMorph);
+  }
+  schedule() {
+    this.#pass.schedule();
+  }
+  disconnect() {
+    this.#listeners.dispose();
+    this.#pass.cancel();
+    this.#element = null;
+  }
+};
+
 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,
-   *   and `items` to reuse an event-scoped collection snapshot.
-   */
   setActive(index, options = {}) {
     const { focus = false } = options;
     const items = options.items ?? this.#getItems();
@@ -147,43 +200,24 @@ var RovingTabindex = class {
   }
 };
 
-// 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);
@@ -200,39 +234,22 @@ var SafeTimeout = class extends TimerRegistry {
   }
 };
 
-// src/utils/state_reason.ts
-var FOCUS_EVENTS = /* @__PURE__ */ new Set(["blur", "focus", "focusin", "focusout"]);
-var POINTER_EVENTS = /* @__PURE__ */ new Set(["mouseenter", "mouseleave", "pointerenter", "pointerleave"]);
-function stateReasonFor(event) {
-  if (!event) return "api";
-  if (FOCUS_EVENTS.has(event.type)) return "focus";
-  if (POINTER_EVENTS.has(event.type)) return "pointer";
-  return "user";
+function targetSelector(identifier, name) {
+  return `[data-${identifier}-target~="${name}"]`;
 }
 
-// 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);
@@ -241,7 +258,6 @@ var Typeahead = class {
     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);
@@ -268,65 +284,30 @@ function findTypeaheadMatch(items, from, query, label = (item) => typeaheadLabel
   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"];
   static events = ["close", "open"];
-  /** 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;
-  /** Whether state moves are reported: set once `connect()` settled the baseline. */
   #reporting = 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.
-   */
+  #morph = new MorphRenderWatcher(() => this.#reconcile());
   connect() {
+    this.#morph.observe(this.element);
     this.#closeAllMenus("api");
     this.#reconcile();
     this.element.addEventListener("click", this.#onDisabledClickCapture, true);
@@ -334,7 +315,7 @@ var MenubarController = class extends Controller {
     this.element.addEventListener("focusout", this.#onFocusOut);
     document.addEventListener("click", this.#onOutsideClick, true);
     if (typeof MutationObserver !== "undefined") {
-      this.#observer = new MutationObserver(() => this.#reconcile());
+      this.#observer = new MutationObserver(() => this.#morph.schedule());
       this.#observer.observe(this.element, {
         subtree: true,
         childList: true,
@@ -345,8 +326,8 @@ var MenubarController = class extends Controller {
     this.#connected = true;
     this.#reporting = true;
   }
-  /** Removes the listeners, stack membership, and any pending timer (typeahead / Tab close). */
   disconnect() {
+    this.#morph.disconnect();
     this.#connected = false;
     this.#reporting = false;
     this.#escapeLayer.deactivate();
@@ -361,63 +342,39 @@ var MenubarController = class extends Controller {
     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;
-    const reason = stateReasonFor(event);
+  toggle(source) {
+    const { event, host, origin, reason } = actionSource(source);
+    const top = host?.closest(targetSelector(this.identifier, "top"));
+    if (!top || !this.topTargets.includes(top)) return;
+    if (origin && origin.closest(`[data-controller~="${this.identifier}"]`) !== this.element)
+      return;
+    const moveFocus = event !== null || this.element.contains(document.activeElement);
     if (this.#isExpanded(top)) {
       this.#closeMenu(top, reason);
     } else {
-      this.#openMenu(top, "first", reason);
+      this.#openMenu(top, "first", reason, moveFocus);
     }
   }
-  /** Keyboard handling while focus is on a top item. */
   onTopKeydown(event) {
     if (event.defaultPrevented) return;
     if (isReservedArrowChord(event)) return;
@@ -457,7 +414,6 @@ var MenubarController = class extends Controller {
         break;
     }
   }
-  /** Keyboard handling while focus is on a menu item. */
   onItemKeydown(event) {
     if (event.defaultPrevented) return;
     if (isReservedArrowChord(event)) return;
@@ -503,76 +459,60 @@ var MenubarController = class extends Controller {
         break;
     }
   }
-  /** Closes the owning menu after an item is activated and refocuses its top. */
-  activate(event) {
-    const item = event.currentTarget;
+  activate(source) {
+    const { event, host, origin } = actionSource(source);
+    const item = host?.closest(targetSelector(this.identifier, "item"));
+    if (!item || !this.itemTargets.includes(item)) return;
+    if (origin && origin.closest(`[data-controller~="${this.identifier}"]`) !== this.element)
+      return;
+    const moveFocus = event !== null || this.element.contains(document.activeElement);
     const menu = item.closest("[role='menu']");
     const top = this.#topFor(menu);
     this.#closeAllMenus("select");
-    this.#focusTop(top);
+    this.#focusTop(
+      top,
+      moveFocus && (event !== null || this.element.contains(document.activeElement))
+    );
   }
-  /** Moves the roving focus to `top`, opening its menu when one was open. */
-  #gotoTop(top, reopen, reason) {
-    if (!top) return;
+  #gotoTop(destination, reopen, reason) {
+    if (!destination) return;
     if (reopen) {
-      this.#openMenu(top, "first", reason);
+      this.#openMenu(destination, "first", reason);
     } else {
-      this.#roving.setActive(this.topTargets.indexOf(top), { focus: true });
+      this.#roving.setActive(this.topTargets.indexOf(destination), { 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, reason) {
-    if (!top) return;
-    const menu = this.#menuFor(top);
-    if (!menu || this.#isActivationBlocked(top)) {
-      if (menu || !top.hasAttribute("aria-controls")) {
+  #openMenu(opener, focus, reason, moveFocus = true) {
+    if (!opener) return;
+    const menu = this.#menuFor(opener);
+    if (!menu || this.#isActivationBlocked(opener)) {
+      if (menu || !opener.hasAttribute("aria-controls")) {
         this.#closeAllMenus(reason);
-        this.#focusTop(top);
+        this.#focusTop(
+          opener,
+          moveFocus && (reason !== "api" || this.element.contains(document.activeElement))
+        );
       }
       return;
     }
     this.#timers.clearAll();
-    const was = this.#isExpanded(top);
-    this.#closeAllMenus(reason, top);
+    const was = this.#isExpanded(opener);
+    this.#closeAllMenus(reason, opener);
     menu.hidden = false;
-    top.setAttribute("aria-expanded", "true");
-    if (!was) this.#report("open", top, menu, reason);
-    if (!this.#isExpanded(top)) return;
+    opener.setAttribute("aria-expanded", "true");
+    if (!was) this.#report("open", opener, menu, reason);
+    if (!this.#isExpanded(opener)) return;
     this.#escapeLayer.activate(document, {
       onDismiss: () => this.#dismissOpenMenu(),
       claims: claimsWhileFocusWithin(this.element)
     });
     this.#layerActive = true;
-    this.#roving.setActive(this.topTargets.indexOf(top));
+    this.#roving.setActive(this.topTargets.indexOf(opener));
     const items = this.#itemsIn(menu);
-    this.#focusAt(items, focus === "first" ? 0 : items.length - 1);
+    if (moveFocus && (reason !== "api" || this.element.contains(document.activeElement))) {
+      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, reason, silent = false) {
     if (!top) return;
     const menu = this.#menuFor(top);
@@ -583,40 +523,21 @@ var MenubarController = class extends Controller {
     if (was && !silent) this.#report("close", top, menu, reason);
     this.#syncEscapeLayer();
   }
-  /**
-   * Closes every menu and resets the typeahead query. `except` still has its
-   * attributes rewritten — the caller is about to reopen it — but its move is
-   * left for that caller to report.
-   */
   #closeAllMenus(reason, except = null) {
     for (const top of this.topTargets) this.#closeMenu(top, reason, top === except);
     this.#typeahead.reset();
   }
-  /** Names the menu that moved, so a subscriber does not have to re-derive it. */
   #report(name, top, menu, reason) {
     if (!this.#reporting) return;
     const detail = { reason, index: this.topTargets.indexOf(top), menu };
     if (name === "open") this.dispatch("open", { detail, cancelable: false });
     else this.dispatch("close", { detail, cancelable: false });
   }
-  /**
-   * 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("focus"), 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 menu = ownerOf(this.menuTargets, document.activeElement);
     if (menu) {
@@ -627,32 +548,20 @@ var MenubarController = class extends Controller {
     }
     this.#closeAllMenus("escape");
   }
-  /** 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 ownerTop = this.#topFor(menu);
+    if (!ownerTop) return;
     const tops = this.#navigableTops;
-    const current = tops.indexOf(top);
+    const current = tops.indexOf(ownerTop);
     if (current === -1) return;
     const next = (current + delta + tops.length) % tops.length;
     this.#openMenu(tops[next], "first", "user");
   }
-  /**
-   * 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("outside");
     }
   };
-  /**
-   * 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;
@@ -663,18 +572,6 @@ var MenubarController = class extends Controller {
     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. The only state carried between calls is the tracked focus record and 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);
@@ -691,20 +588,6 @@ var MenubarController = class extends Controller {
     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;
@@ -720,22 +603,6 @@ var MenubarController = class extends Controller {
     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;
@@ -749,13 +616,6 @@ var MenubarController = class extends Controller {
     }
     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];
@@ -766,58 +626,40 @@ var MenubarController = class extends Controller {
     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) {
+  #focusTop(top, focus = true) {
     if (!top) return;
-    this.#roving.setActive(this.topTargets.indexOf(top), { focus: true });
+    this.#roving.setActive(this.topTargets.indexOf(top), { focus });
   }
-  /** 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();
@@ -825,5 +667,4 @@ var MenubarController = class extends Controller {
 };
 
 export { MenubarController };
-//# sourceMappingURL=menubar_controller.js.map
 //# sourceMappingURL=menubar_controller.js.map