stimeo-ui 0.2.1 → 0.4.0

data/dist/controllers/command_palette_controller.js

@@ -2,6 +2,24 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/command_palette_controller.ts
 
+// src/utils/active_option.ts
+function syncActiveOption(options, active) {
+  let written = 0;
+  for (const option of options) {
+    const next = option === active ? "true" : "false";
+    if (option.getAttribute("aria-selected") === next) continue;
+    option.setAttribute("aria-selected", next);
+    written += 1;
+  }
+  return written;
+}
+
+// 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/composition_tracker.ts
 var CompositionTracker = class {
   #observedTargets = /* @__PURE__ */ new Set();
@@ -49,6 +67,35 @@ var CompositionTracker = class {
   };
 };
 
+// src/utils/before_cache_reset.ts
+var BeforeCacheReset = class _BeforeCacheReset {
+  /** Every subscribed instance, iterated by the one shared document listener. */
+  static #subscribers = /* @__PURE__ */ new Set();
+  /** The shared listener; installed while at least one instance is subscribed. */
+  static #onBeforeCache = () => {
+    for (const subscriber of _BeforeCacheReset.#subscribers) subscriber.#rewind();
+  };
+  #rewind;
+  /** @param rewind - the pass that returns this controller's state to its initial form. */
+  constructor(rewind) {
+    this.#rewind = rewind;
+  }
+  /** Subscribes to `turbo:before-cache`; call from `connect()`. Idempotent. */
+  activate() {
+    const first = _BeforeCacheReset.#subscribers.size === 0;
+    _BeforeCacheReset.#subscribers.add(this);
+    if (first) {
+      document.addEventListener("turbo:before-cache", _BeforeCacheReset.#onBeforeCache);
+    }
+  }
+  /** Unsubscribes; call from `disconnect()`. Safe when never subscribed. */
+  deactivate() {
+    _BeforeCacheReset.#subscribers.delete(this);
+    if (_BeforeCacheReset.#subscribers.size > 0) return;
+    document.removeEventListener("turbo:before-cache", _BeforeCacheReset.#onBeforeCache);
+  }
+};
+
 // src/utils/escape_layer.ts
 var EscapeLayer = class _EscapeLayer {
   static #registries = /* @__PURE__ */ new WeakMap();
@@ -182,7 +229,7 @@ var FocusTrap = class {
     }
     if (this.#flag(this.#options.isolate, true)) this.#isolateBackground();
     document.addEventListener("keydown", this.#onKeydown);
-    document.addEventListener("turbo:before-cache", this.#onBeforeCache);
+    this.#beforeCache.activate();
     const onEscape = this.#options.onEscape;
     if (onEscape) this.#escapeLayer.activate(document, { onDismiss: () => onEscape() });
     if (this.#flag(this.#options.autoFocus, true)) this.#focusInitial();
@@ -199,7 +246,7 @@ var FocusTrap = class {
     this.#activeState = false;
     this.#escapeLayer.deactivate();
     document.removeEventListener("keydown", this.#onKeydown);
-    document.removeEventListener("turbo:before-cache", this.#onBeforeCache);
+    this.#beforeCache.deactivate();
     if (this.#scrollLocked) {
       document.body.style.overflow = this.#previousBodyOverflow;
       this.#scrollLocked = false;
@@ -223,9 +270,7 @@ var FocusTrap = class {
    * untouched (restore-open designs reopen against a clean baseline), and focus
    * is left alone mid-navigation. The listener lives only while active.
    */
-  #onBeforeCache = () => {
-    this.deactivate({ restoreFocus: false });
-  };
+  #beforeCache = new BeforeCacheReset(() => this.deactivate({ restoreFocus: false }));
   /**
    * Handles `Tab` (focus trap) while active. `Escape` dismissal is owned by the
    * shared {@link EscapeLayer} resolver, so Tab trapping stays independent of
@@ -304,6 +349,39 @@ var FocusTrap = class {
   }
 };
 
+// src/utils/microtask_coalescer.ts
+var MicrotaskCoalescer = class {
+  #run;
+  #queued = false;
+  #active = false;
+  #generation = 0;
+  /** @param run - the single reconciliation pass, invoked at most once per batch. */
+  constructor(run) {
+    this.#run = run;
+  }
+  /** Opens the window in which {@link schedule} is honoured; call from `connect()`. */
+  activate() {
+    this.#active = true;
+  }
+  /** Closes the window and drops any pending pass; call from `disconnect()`. */
+  cancel() {
+    this.#active = false;
+    this.#queued = false;
+    this.#generation += 1;
+  }
+  /** Requests one pass after the batch settles. Idempotent; inert outside the window. */
+  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();
+    });
+  }
+};
+
 // src/controllers/command_palette_controller.ts
 var CommandPaletteController = class _CommandPaletteController extends Controller {
   static #ORIGINAL_ARIA_DISABLED = "data-command-palette-original-aria-disabled";
@@ -323,8 +401,13 @@ var CommandPaletteController = class _CommandPaletteController extends Controlle
     "toggle"
   ];
   static events = ["select"];
-  /** The index of the currently active option within the visible subset. */
-  #activeIndex = -1;
+  /** Stable ID of the active option; the live target is resolved before every use. */
+  #activeId = null;
+  /** Visible/selectable target ID order captured for removal fallback. */
+  #activeOrder = [];
+  #connected = false;
+  /** Collapses one mutation batch of target callbacks into a single pass. */
+  #reconcile = new MicrotaskCoalescer(() => this.#reconcileActive());
   /** Owns IME lifecycle state; confirmed text re-filters an open palette once. */
   #composition = new CompositionTracker({
     onEnd: () => {
@@ -358,9 +441,13 @@ var CommandPaletteController = class _CommandPaletteController extends Controlle
     const shouldOpen = this.#isOpen || this.openValue;
     this.#resetToClosedState();
     if (shouldOpen) this.open();
+    this.#connected = true;
+    this.#reconcile.activate();
   }
   /** Tears down the global hotkey listener and reverts the modal side effects. */
   disconnect() {
+    this.#connected = false;
+    this.#reconcile.cancel();
     document.removeEventListener("keydown", this.#onGlobalKeydown);
     this.#composition.disconnect();
     this.#trap.deactivate({ restoreFocus: false });
@@ -369,10 +456,20 @@ var CommandPaletteController = class _CommandPaletteController extends Controlle
   /** Initializes semantics for an option added before or after the controller connects. */
   optionTargetConnected(option) {
     this.#syncOptionSemanticsFor(option);
+    option.setAttribute("aria-selected", "false");
+    option.removeAttribute("data-active");
+    if (this.#connected) this.#queueOptionReconciliation();
+  }
+  /** Clears active residue on the old node and reconciles the surviving targets. */
+  optionTargetDisconnected(option) {
+    option.setAttribute("aria-selected", "false");
+    option.removeAttribute("data-active");
+    if (this.#connected) this.#queueOptionReconciliation();
   }
   /** Tracks an input added initially or after connect without extra consumer actions. */
   inputTargetConnected(input) {
     this.#composition.observe(input);
+    if (this.#connected) this.#queueOptionReconciliation();
   }
   /** Removes controller-owned listeners when the input target is replaced or removed. */
   inputTargetDisconnected(input) {
@@ -412,7 +509,7 @@ var CommandPaletteController = class _CommandPaletteController extends Controlle
       const matches = searchText.includes(query);
       if (matches) {
         option.removeAttribute("hidden");
-        if (!this.#isDisabled(option)) hasSelectableMatch = true;
+        if (this.#isNavigable(option)) hasSelectableMatch = true;
       } else {
         option.setAttribute("hidden", "true");
       }
@@ -427,8 +524,9 @@ var CommandPaletteController = class _CommandPaletteController extends Controlle
     const target = event.currentTarget;
     if (!target) return;
     const option = target.closest("[role='option']");
-    if (option) this.#syncOptionSemanticsFor(option);
-    if (option && !this.#isDisabled(option)) {
+    if (!option || !this.optionTargets.includes(option)) return;
+    this.#syncOptionSemanticsFor(option);
+    if (!option.hasAttribute("hidden") && !this.#isDisabled(option)) {
       this.#confirmSelection(option);
     }
   }
@@ -443,7 +541,10 @@ var CommandPaletteController = class _CommandPaletteController extends Controlle
    * focus — not only the input.
    */
   onKeydown(event) {
+    if (event.defaultPrevented) return;
+    if (isReservedArrowChord(event)) return;
     if (this.#composition.isComposing(event) || !this.#isOpen) return;
+    this.#reconcileActive();
     switch (event.key) {
       case "ArrowDown":
         event.preventDefault();
@@ -463,7 +564,9 @@ var CommandPaletteController = class _CommandPaletteController extends Controlle
         break;
       case "Enter": {
         event.preventDefault();
-        const activeOption = this.#visibleOptions[this.#activeIndex];
+        const visible = this.#visibleOptions;
+        const activeIndex = this.#findActiveIndex(visible);
+        const activeOption = activeIndex < 0 ? void 0 : visible[activeIndex];
         if (activeOption) this.#confirmSelection(activeOption);
         break;
       }
@@ -472,7 +575,7 @@ var CommandPaletteController = class _CommandPaletteController extends Controlle
   #navigate(direction) {
     const visible = this.#visibleOptions;
     if (visible.length === 0) return;
-    let newIndex = this.#activeIndex + direction;
+    let newIndex = this.#findActiveIndex(visible) + direction;
     if (newIndex >= visible.length) newIndex = 0;
     if (newIndex < 0) newIndex = visible.length - 1;
     this.#setActiveIndex(newIndex);
@@ -481,16 +584,16 @@ var CommandPaletteController = class _CommandPaletteController extends Controlle
     this.#syncOptionSemantics();
     const visible = this.#visibleOptions;
     const activeOption = visible[index] ?? null;
-    this.#activeIndex = activeOption ? index : -1;
+    syncActiveOption(this.optionTargets, activeOption);
     for (const option of this.optionTargets) {
-      option.setAttribute("aria-selected", "false");
-      option.removeAttribute("data-active");
+      if (option === activeOption) option.setAttribute("data-active", "true");
+      else option.removeAttribute("data-active");
     }
     if (activeOption) {
-      activeOption.setAttribute("aria-selected", "true");
-      activeOption.setAttribute("data-active", "true");
       activeOption.scrollIntoView({ block: "nearest" });
     }
+    this.#activeId = activeOption?.id || null;
+    this.#activeOrder = activeOption ? visible.map((option) => option.id).filter(Boolean) : [];
     if (this.hasInputTarget) {
       if (activeOption?.id) {
         this.inputTarget.setAttribute("aria-activedescendant", activeOption.id);
@@ -499,7 +602,75 @@ var CommandPaletteController = class _CommandPaletteController extends Controlle
       }
     }
   }
+  /** Re-resolves active identity and component-specific fallback against live targets. */
+  #reconcileActive() {
+    if (!this.#isOpen) {
+      this.#setActiveIndex(-1);
+      this.#reflectEmptyState();
+      return;
+    }
+    const visible = this.#visibleOptions;
+    const currentIndex = this.#findActiveIndex(visible);
+    if (currentIndex >= 0) {
+      const active = visible[currentIndex] ?? null;
+      const options = this.optionTargets;
+      const marked = options.filter((option) => option.hasAttribute("data-active"));
+      const selected = options.filter((option) => option.getAttribute("aria-selected") === "true");
+      const stateMatches = this.#activeId === (active?.id || null) && marked.length === 1 && marked[0] === active && selected.length === 1 && selected[0] === active && (!this.hasInputTarget || this.inputTarget.getAttribute("aria-activedescendant") === (active?.id || null));
+      if (stateMatches) {
+        this.#activeOrder = visible.map((option) => option.id).filter(Boolean);
+      } else {
+        this.#setActiveIndex(currentIndex);
+      }
+      this.#reflectEmptyState();
+      return;
+    }
+    const activeId = (this.hasInputTarget ? this.inputTarget.getAttribute("aria-activedescendant") : null) ?? this.#activeId;
+    this.#setActiveIndex(activeId ? this.#findFallbackIndex(visible, activeId) : -1);
+    this.#reflectEmptyState();
+  }
+  /** Resolves stable ID first, then active markers for the existing ID-less case. */
+  #findActiveIndex(options) {
+    const activeId = (this.hasInputTarget ? this.inputTarget.getAttribute("aria-activedescendant") : null) ?? this.#activeId;
+    if (activeId) return options.findIndex((option) => option.id === activeId);
+    return options.findIndex(
+      (option) => option.hasAttribute("data-active") || option.getAttribute("aria-selected") === "true"
+    );
+  }
+  /** Chooses a surviving former successor, then predecessor, from selectable targets only. */
+  #findFallbackIndex(options, activeId) {
+    const oldIndex = this.#activeOrder.indexOf(activeId);
+    if (oldIndex < 0) return -1;
+    const indexesById = new Map(options.map((option, index) => [option.id, index]));
+    for (let index = oldIndex + 1; index < this.#activeOrder.length; index += 1) {
+      const fallback = indexesById.get(this.#activeOrder[index] ?? "");
+      if (fallback !== void 0) return fallback;
+    }
+    for (let index = oldIndex - 1; index >= 0; index -= 1) {
+      const fallback = indexesById.get(this.#activeOrder[index] ?? "");
+      if (fallback !== void 0) return fallback;
+    }
+    return -1;
+  }
+  /** Reflects whether any visible, navigable command remains. */
+  #reflectEmptyState() {
+    if (this.hasEmptyTarget) this.emptyTarget.hidden = this.#visibleOptions.length > 0;
+  }
+  /** Coalesces all target callbacks from one MutationObserver batch. */
+  #queueOptionReconciliation() {
+    this.#reconcile.schedule();
+  }
+  /**
+   * Runs `option`: dispatches `select` and closes.
+   *
+   * **Activation is refused here, not at the call sites.** Every path that runs a
+   * command funnels through this method, so one check covers keyboard, pointer,
+   * and anything added later. Per-call-site guards would leave `aria-disabled`
+   * options — which stay within the keyboard's reach — runnable from whichever
+   * path forgets to consult the predicate.
+   */
   #confirmSelection(option) {
+    if (this.#isDisabled(option)) return;
     const value = option.dataset.value || option.textContent || "";
     this.dispatch("select", { detail: { value, option } });
     this.close();
@@ -510,14 +681,33 @@ var CommandPaletteController = class _CommandPaletteController extends Controlle
       option.removeAttribute("hidden");
     }
     const hasSelectableOption = this.#visibleOptions.length > 0;
-    if (this.hasEmptyTarget) this.emptyTarget.hidden = hasSelectableOption;
+    this.#reflectEmptyState();
     this.#setActiveIndex(hasSelectableOption ? 0 : -1);
   }
   get #visibleOptions() {
     return this.optionTargets.filter(
-      (option) => !option.hasAttribute("hidden") && !this.#isDisabled(option)
+      (option) => !option.hasAttribute("hidden") && this.#isNavigable(option)
     );
   }
+  /**
+   * Whether virtual focus may land on `option`.
+   *
+   * Only `data-disabled` disqualifies. That attribute is this controller's own —
+   * authors reach for it to mark a row that is not a destination at all, such as
+   * a group heading — so it can mean "skip entirely" without contradicting ARIA.
+   *
+   * **`aria-disabled` does not disqualify.** It marks a command that must stay
+   * *discoverable*: `aria-activedescendant` names it, so a reader announces it as
+   * unavailable rather than hiding its existence. Virtual focus does
+   * not change that — pointing `aria-activedescendant` at a disabled option is
+   * ordinary ARIA. Keeping the two attributes distinct is what leaves both
+   * meanings expressible; collapsing them would take "show it, say it is
+   * unavailable, do not run it" away from consumers.
+   */
+  #isNavigable(option) {
+    return option.dataset.disabled !== "true";
+  }
+  /** Whether activating `option` may run. Suppressed for either disabled marker. */
   #isDisabled(option) {
     return option.dataset.disabled === "true" || option.getAttribute("aria-disabled") === "true";
   }
@@ -525,9 +715,18 @@ var CommandPaletteController = class _CommandPaletteController extends Controlle
   #syncOptionSemantics() {
     for (const option of this.optionTargets) this.#syncOptionSemanticsFor(option);
   }
-  /** Reflects `data-disabled` to ARIA without losing a pre-existing authored value. */
+  /**
+   * Reflects `data-disabled` to ARIA without losing a pre-existing authored value,
+   * and puts `aria-selected` back to its baseline.
+   *
+   * Here `aria-selected` marks the *active* option, not a committed choice — the
+   * palette runs a command and keeps nothing selected — so an authored value is
+   * meaningless and is overwritten rather than preserved. Every caller either
+   * establishes the active option straight after (`filter`, `#setActiveIndex`) or
+   * is handling an option that cannot be the active one yet
+   * (`optionTargetConnected`).
+   */
   #syncOptionSemanticsFor(option) {
-    if (!option.hasAttribute("aria-selected")) option.setAttribute("aria-selected", "false");
     const originalAttribute = _CommandPaletteController.#ORIGINAL_ARIA_DISABLED;
     const originalValue = option.getAttribute(originalAttribute);
     if (option.dataset.disabled === "true") {
@@ -581,8 +780,13 @@ var CommandPaletteController = class _CommandPaletteController extends Controlle
   }
   /** Resets transient open state so reconnect starts from a predictable closed snapshot. */
   #resetToClosedState() {
-    this.#activeIndex = -1;
+    this.#activeId = null;
+    this.#activeOrder = [];
     this.openValue = false;
+    for (const option of this.optionTargets) {
+      option.setAttribute("aria-selected", "false");
+      option.removeAttribute("data-active");
+    }
     if (this.hasDialogTarget) {
       this.dialogTarget.hidden = true;
     }

data/dist/controllers/confirm_controller.js

@@ -2,6 +2,35 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/confirm_controller.ts
 
+// src/utils/before_cache_reset.ts
+var BeforeCacheReset = class _BeforeCacheReset {
+  /** Every subscribed instance, iterated by the one shared document listener. */
+  static #subscribers = /* @__PURE__ */ new Set();
+  /** The shared listener; installed while at least one instance is subscribed. */
+  static #onBeforeCache = () => {
+    for (const subscriber of _BeforeCacheReset.#subscribers) subscriber.#rewind();
+  };
+  #rewind;
+  /** @param rewind - the pass that returns this controller's state to its initial form. */
+  constructor(rewind) {
+    this.#rewind = rewind;
+  }
+  /** Subscribes to `turbo:before-cache`; call from `connect()`. Idempotent. */
+  activate() {
+    const first = _BeforeCacheReset.#subscribers.size === 0;
+    _BeforeCacheReset.#subscribers.add(this);
+    if (first) {
+      document.addEventListener("turbo:before-cache", _BeforeCacheReset.#onBeforeCache);
+    }
+  }
+  /** Unsubscribes; call from `disconnect()`. Safe when never subscribed. */
+  deactivate() {
+    _BeforeCacheReset.#subscribers.delete(this);
+    if (_BeforeCacheReset.#subscribers.size > 0) return;
+    document.removeEventListener("turbo:before-cache", _BeforeCacheReset.#onBeforeCache);
+  }
+};
+
 // src/utils/escape_layer.ts
 var EscapeLayer = class _EscapeLayer {
   static #registries = /* @__PURE__ */ new WeakMap();
@@ -135,7 +164,7 @@ var FocusTrap = class {
     }
     if (this.#flag(this.#options.isolate, true)) this.#isolateBackground();
     document.addEventListener("keydown", this.#onKeydown);
-    document.addEventListener("turbo:before-cache", this.#onBeforeCache);
+    this.#beforeCache.activate();
     const onEscape = this.#options.onEscape;
     if (onEscape) this.#escapeLayer.activate(document, { onDismiss: () => onEscape() });
     if (this.#flag(this.#options.autoFocus, true)) this.#focusInitial();
@@ -152,7 +181,7 @@ var FocusTrap = class {
     this.#activeState = false;
     this.#escapeLayer.deactivate();
     document.removeEventListener("keydown", this.#onKeydown);
-    document.removeEventListener("turbo:before-cache", this.#onBeforeCache);
+    this.#beforeCache.deactivate();
     if (this.#scrollLocked) {
       document.body.style.overflow = this.#previousBodyOverflow;
       this.#scrollLocked = false;
@@ -176,9 +205,7 @@ var FocusTrap = class {
    * untouched (restore-open designs reopen against a clean baseline), and focus
    * is left alone mid-navigation. The listener lives only while active.
    */
-  #onBeforeCache = () => {
-    this.deactivate({ restoreFocus: false });
-  };
+  #beforeCache = new BeforeCacheReset(() => this.deactivate({ restoreFocus: false }));
   /**
    * Handles `Tab` (focus trap) while active. `Escape` dismissal is owned by the
    * shared {@link EscapeLayer} resolver, so Tab trapping stays independent of

data/dist/controllers/context_menu_controller.js

@@ -2,6 +2,12 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/context_menu_controller.ts
 
+// 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 () => {
@@ -156,16 +162,16 @@ var ContextMenuController = class extends Controller {
   connect() {
     this.#closeMenu();
     this.element.addEventListener("click", this.#onItemClickCapture, true);
-    document.addEventListener("click", this.#onOutsidePointer);
-    document.addEventListener("contextmenu", this.#onOutsidePointer);
+    document.addEventListener("click", this.#onOutsidePointer, true);
+    document.addEventListener("contextmenu", this.#onOutsidePointer, true);
   }
   /** Releases the listeners, stack membership, and pending Tab-close task. */
   disconnect() {
     this.#timers.clearAll();
     this.#escapeLayer.deactivate();
     this.element.removeEventListener("click", this.#onItemClickCapture, true);
-    document.removeEventListener("click", this.#onOutsidePointer);
-    document.removeEventListener("contextmenu", this.#onOutsidePointer);
+    document.removeEventListener("click", this.#onOutsidePointer, true);
+    document.removeEventListener("contextmenu", this.#onOutsidePointer, true);
   }
   /**
    * Opens the menu from a `contextmenu` event: suppresses the native menu and
@@ -177,6 +183,7 @@ var ContextMenuController = class extends Controller {
   }
   /** Keyboard entry on the region: `Shift+F10` / `ContextMenu` open at center. */
   onRegionKeydown(event) {
+    if (event.defaultPrevented) return;
     const isContextKey = event.key === "ContextMenu" || event.key === "F10" && event.shiftKey;
     if (!isContextKey) return;
     event.preventDefault();
@@ -185,6 +192,8 @@ var ContextMenuController = class extends Controller {
   }
   /** Roving focus and closing keys inside the menu. */
   onItemKeydown(event) {
+    if (event.defaultPrevented) return;
+    if (isReservedArrowChord(event)) return;
     const items = this.#navigableItems;
     const currentIndex = items.indexOf(event.currentTarget);
     switch (event.key) {
@@ -247,7 +256,13 @@ var ContextMenuController = class extends Controller {
     this.#closeMenu();
     if (this.hasRegionTarget) this.regionTarget.focus();
   }
-  /** Closes when a click or context-menu invocation lands outside this instance. */
+  /**
+   * Closes when a click or context-menu invocation lands outside this instance.
+   * Both subscriptions observe in the capture phase, so the target is judged
+   * against the tree the user actually pressed even when a consumer handler
+   * detaches it, and application code that stops bubbling cannot leave the menu
+   * open.
+   */
   #onOutsidePointer = (event) => {
     if (this.#isOpen && !this.element.contains(event.target)) this.#closeMenu();
   };
@@ -265,18 +280,25 @@ var ContextMenuController = class extends Controller {
     event.preventDefault();
     event.stopImmediatePropagation();
   };
-  /** Menu items eligible for roving focus (excludes disabled / hidden). */
+  /** Menu items eligible for roving focus (excludes hidden / natively disabled). */
   get #navigableItems() {
     return this.itemTargets.filter((item) => this.#isNavigable(item));
   }
   /**
-   * An item can take roving focus unless it is `hidden`, `aria-disabled="true"`,
-   * or a natively `disabled` form control. CSS-only visibility is not detectable
-   * here and is the consumer's responsibility.
+   * An item can take roving focus unless it is `hidden` or a natively `disabled`
+   * form control. CSS-only visibility is not detectable here and is the
+   * consumer's responsibility.
+   *
+   * **`aria-disabled="true"` stays reachable.** APG separates the two attributes
+   * by intent: `disabled` is for controls whose existence can be inferred from a
+   * neighbour (a greyed Next next to a Prev), while `aria-disabled` marks a
+   * control that must stay *discoverable* — and it names menu items as the
+   * example. Skipping it would hide the command's existence from a keyboard user
+   * entirely. Activation is suppressed separately, so the item announces itself
+   * and does nothing.
    */
   #isNavigable(item) {
     if (item.hasAttribute("hidden")) return false;
-    if (item.getAttribute("aria-disabled") === "true") return false;
     return !item.disabled;
   }
   /** Whether the menu is currently visible. */