stimeo-ui 0.1.0.pre.beta.3 → 0.2.1

data/dist/controllers/menu_controller.js

@@ -1,5 +1,150 @@
 import { Controller } from '@hotwired/stimulus';
 
+// src/controllers/menu_controller.ts
+
+// 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/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/controllers/menu_controller.ts
 var MenuController = class extends Controller {
   static targets = ["trigger", "menu", "item"];
@@ -11,13 +156,20 @@ var MenuController = class extends Controller {
     "open",
     "toggle"
   ];
-  /** Starts closed and registers the outside-click listener. */
+  #timers = new SafeTimeout();
+  /** Escape-stack membership while open; the shared resolver dismisses via it. */
+  #escapeLayer = new EscapeLayer();
+  /** Starts closed and registers delegated listeners. */
   connect() {
     this.close();
+    this.element.addEventListener("click", this.#onItemClickCapture, true);
     document.addEventListener("click", this.#onOutsideClick);
   }
-  /** Removes the document-level listener registered in {@link connect}. */
+  /** Releases the listeners, stack membership, and any pending Tab-close task. */
   disconnect() {
+    this.#timers.clearAll();
+    this.#escapeLayer.deactivate();
+    this.element.removeEventListener("click", this.#onItemClickCapture, true);
     document.removeEventListener("click", this.#onOutsideClick);
   }
   /** Toggles the menu open/closed. Bound via `data-action` (click). */
@@ -31,12 +183,19 @@ var MenuController = class extends Controller {
   }
   /** Opens the menu and reflects the expanded state on the trigger. */
   open() {
+    this.#timers.clearAll();
     if (!this.hasMenuTarget) return;
+    this.#escapeLayer.activate(document, {
+      onDismiss: () => this.#closeAndRestore(),
+      claims: claimsWhileFocusWithin(this.element)
+    });
     this.menuTarget.hidden = false;
     if (this.hasTriggerTarget) this.triggerTarget.setAttribute("aria-expanded", "true");
   }
   /** Closes the menu and reflects the collapsed state on the trigger. */
   close() {
+    this.#timers.clearAll();
+    this.#escapeLayer.deactivate();
     if (!this.hasMenuTarget) return;
     this.menuTarget.hidden = true;
     if (this.hasTriggerTarget) this.triggerTarget.setAttribute("aria-expanded", "false");
@@ -81,18 +240,18 @@ var MenuController = class extends Controller {
         event.preventDefault();
         items[items.length - 1]?.focus();
         break;
-      case "Escape":
-        event.preventDefault();
-        this.close();
-        if (this.hasTriggerTarget) this.triggerTarget.focus();
-        break;
       case "Tab":
-        this.close();
+        this.#timers.clearAll();
+        this.#timers.set(() => this.close(), 0);
         break;
     }
   }
   /** Closes the menu after an item is activated. Bound via `data-action`. */
   activate() {
+    this.#closeAndRestore();
+  }
+  /** Closes and returns focus to the trigger (Escape / item-activation path). */
+  #closeAndRestore() {
     this.close();
     if (this.hasTriggerTarget) this.triggerTarget.focus();
   }
@@ -100,6 +259,20 @@ var MenuController = class extends Controller {
   #onOutsideClick = (event) => {
     if (this.#isOpen && !this.element.contains(event.target)) this.close();
   };
+  /**
+   * Captures clicks so `aria-disabled` commands cannot reach consumer handlers.
+   * Native Enter/Space activation also synthesizes a click and is blocked here.
+   */
+  #onItemClickCapture = (event) => {
+    const target = event.target;
+    if (!(target instanceof Node)) return;
+    const disabled = this.itemTargets.some(
+      (item) => item.getAttribute("aria-disabled") === "true" && item.contains(target)
+    );
+    if (!disabled) return;
+    event.preventDefault();
+    event.stopImmediatePropagation();
+  };
   /** Moves focus to the first navigable item (no-op if none). */
   #focusFirst() {
     this.#navigableItems[0]?.focus();

data/dist/controllers/menubar_controller.js

@@ -0,0 +1,433 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/menubar_controller.ts
+
+// 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/controllers/menubar_controller.ts
+var TYPEAHEAD_RESET_MS = 500;
+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;
+  #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. */
+  connect() {
+    const active = this.#roving.activeIndex;
+    this.#roving.setActive(active === -1 ? 0 : active);
+    this.#closeAllMenus();
+    document.addEventListener("click", this.#onOutsideClick);
+  }
+  /** Removes the document listener, stack membership, and any pending typeahead timer. */
+  disconnect() {
+    this.#escapeLayer.deactivate();
+    document.removeEventListener("click", this.#onOutsideClick);
+    this.#timers.clearAll();
+  }
+  /** 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) {
+    const tops = this.topTargets;
+    const index = tops.indexOf(event.currentTarget);
+    if (index === -1) return;
+    const length = tops.length;
+    const anyOpen = this.#isAnyOpen;
+    switch (event.key) {
+      case "ArrowRight":
+        event.preventDefault();
+        this.#gotoTop((index + 1) % length, anyOpen);
+        break;
+      case "ArrowLeft":
+        event.preventDefault();
+        this.#gotoTop((index - 1 + 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(0, anyOpen);
+        break;
+      case "End":
+        event.preventDefault();
+        this.#gotoTop(length - 1, anyOpen);
+        break;
+    }
+  }
+  /** Keyboard handling while focus is on a menu item. */
+  onItemKeydown(event) {
+    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, 1);
+        break;
+      case "ArrowLeft":
+        event.preventDefault();
+        this.#moveToAdjacentMenu(menu, -1);
+        break;
+      case "Tab":
+        this.#closeAllMenus();
+        break;
+      default:
+        if (this.#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 `index`, opening its menu when one was open. */
+  #gotoTop(index, reopen) {
+    const top = this.topTargets[index];
+    if (!top) return;
+    if (reopen) {
+      this.#openMenu(top, "first");
+    } else {
+      this.#roving.setActive(index, { focus: true });
+    }
+  }
+  /** Opens `top`'s menu (closing others) and focuses its first/last item. */
+  #openMenu(top, focus) {
+    if (!top) return;
+    this.#closeAllMenus();
+    const menu = this.#menuFor(top);
+    if (!menu) return;
+    menu.hidden = false;
+    top.setAttribute("aria-expanded", "true");
+    this.#escapeLayer.activate(document, {
+      onDismiss: () => this.#dismissOpenMenu(),
+      claims: claimsWhileFocusWithin(this.element)
+    });
+    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. */
+  #closeMenu(top) {
+    if (!top) return;
+    const menu = this.#menuFor(top);
+    if (menu) menu.hidden = true;
+    top.setAttribute("aria-expanded", "false");
+    if (!this.#isAnyOpen) this.#escapeLayer.deactivate();
+  }
+  /** Closes every menu and resets the typeahead buffer. */
+  #closeAllMenus() {
+    for (const top of this.topTargets) this.#closeMenu(top);
+    this.#resetTypeahead();
+  }
+  /**
+   * 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 top item `delta` steps from the one owning `menu`. */
+  #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;
+    this.#openMenu(tops[next], "first");
+  }
+  /** Closes when a click lands outside the controller's element. */
+  #onOutsideClick = (event) => {
+    if (this.#isAnyOpen && !this.element.contains(event.target)) this.#closeAllMenus();
+  };
+  /** 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 item targets that live inside `menu`, in DOM order. */
+  #itemsIn(menu) {
+    return this.itemTargets.filter((item) => menu.contains(item));
+  }
+  /** 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));
+  }
+  /**
+   * 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. */
+  #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);
+  }
+};
+
+export { MenubarController };
+//# sourceMappingURL=menubar_controller.js.map
+//# sourceMappingURL=menubar_controller.js.map