stimeo-ui 0.1.0.pre.beta.2 → 0.2.0

data/dist/controllers/context_menu_controller.js

@@ -1,17 +1,171 @@
 import { Controller } from '@hotwired/stimulus';
 
+// src/controllers/context_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/context_menu_controller.ts
 var ContextMenuController = class extends Controller {
   static targets = ["region", "menu", "item"];
   static actions = ["activate", "onItemKeydown", "onRegionKeydown", "open"];
-  /** 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 activation and outside-pointer listeners. */
   connect() {
     this.#closeMenu();
-    document.addEventListener("click", this.#onOutsideClick);
+    this.element.addEventListener("click", this.#onItemClickCapture, true);
+    document.addEventListener("click", this.#onOutsidePointer);
+    document.addEventListener("contextmenu", this.#onOutsidePointer);
   }
-  /** Removes the document-level listener registered in {@link connect}. */
+  /** Releases the listeners, stack membership, and pending Tab-close task. */
   disconnect() {
-    document.removeEventListener("click", this.#onOutsideClick);
+    this.#timers.clearAll();
+    this.#escapeLayer.deactivate();
+    this.element.removeEventListener("click", this.#onItemClickCapture, true);
+    document.removeEventListener("click", this.#onOutsidePointer);
+    document.removeEventListener("contextmenu", this.#onOutsidePointer);
   }
   /**
    * Opens the menu from a `contextmenu` event: suppresses the native menu and
@@ -36,11 +190,17 @@ var ContextMenuController = class extends Controller {
     switch (event.key) {
       case "ArrowDown":
         event.preventDefault();
-        if (items.length > 0) items[(currentIndex + 1) % items.length]?.focus();
+        if (items.length > 0) {
+          const nextIndex = currentIndex < 0 ? 0 : (currentIndex + 1) % items.length;
+          items[nextIndex]?.focus();
+        }
         break;
       case "ArrowUp":
         event.preventDefault();
-        if (items.length > 0) items[(currentIndex - 1 + items.length) % items.length]?.focus();
+        if (items.length > 0) {
+          const previousIndex = currentIndex < 0 ? items.length - 1 : currentIndex - 1;
+          items[(previousIndex + items.length) % items.length]?.focus();
+        }
         break;
       case "Home":
         event.preventDefault();
@@ -50,12 +210,9 @@ var ContextMenuController = class extends Controller {
         event.preventDefault();
         items[items.length - 1]?.focus();
         break;
-      case "Escape":
-        event.preventDefault();
-        this.#closeAndRestore();
-        break;
       case "Tab":
-        this.#closeMenu();
+        this.#timers.clearAll();
+        this.#timers.set(() => this.#closeMenu(), 0);
         break;
     }
   }
@@ -66,6 +223,11 @@ var ContextMenuController = class extends Controller {
   /** Opens the menu at viewport coordinates `(x, y)` and focuses the first item. */
   #openAt(x, y) {
     if (!this.hasMenuTarget) return;
+    this.#timers.clearAll();
+    this.#escapeLayer.activate(document, {
+      onDismiss: () => this.#closeAndRestore(),
+      claims: claimsWhileFocusWithin(this.element)
+    });
     this.menuTarget.style.setProperty("--stimeo-context-menu-x", `${x}px`);
     this.menuTarget.style.setProperty("--stimeo-context-menu-y", `${y}px`);
     this.menuTarget.hidden = false;
@@ -74,6 +236,8 @@ var ContextMenuController = class extends Controller {
   }
   /** Hides the menu and reflects the collapsed state on the region. */
   #closeMenu() {
+    this.#timers.clearAll();
+    this.#escapeLayer.deactivate();
     if (!this.hasMenuTarget) return;
     this.menuTarget.hidden = true;
     if (this.hasRegionTarget) this.regionTarget.setAttribute("data-state", "closed");
@@ -83,10 +247,24 @@ var ContextMenuController = class extends Controller {
     this.#closeMenu();
     if (this.hasRegionTarget) this.regionTarget.focus();
   }
-  /** Closes the menu when a click lands outside the controller's element. */
-  #onOutsideClick = (event) => {
+  /** Closes when a click or context-menu invocation lands outside this instance. */
+  #onOutsidePointer = (event) => {
     if (this.#isOpen && !this.element.contains(event.target)) this.#closeMenu();
   };
+  /**
+   * 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();
+  };
   /** Menu items eligible for roving focus (excludes disabled / hidden). */
   get #navigableItems() {
     return this.itemTargets.filter((item) => this.#isNavigable(item));

data/dist/controllers/countdown_controller.js

@@ -107,8 +107,8 @@ var CountdownController = class extends Controller {
    * paused (or completed) one resets the displayed amount but stays paused until the
    * user resumes — it never silently restarts. The run state is read from the DOM,
    * not re-derived from the declarative `autostart` Value (which only governs the
-   * initial state on connect); re-deriving it would override a user's pause, the same
-   * anti-pattern the Turbo-lifecycle guide warns about.
+   * initial state on connect); re-deriving it would override a user's pause —
+   * the DOM, not a re-run of declarative config, is the source of truth.
    */
   reset() {
     const wasRunning = this.#state === "running";

data/dist/controllers/dialog_controller.js

@@ -2,6 +2,90 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/dialog_controller.ts
 
+// src/utils/escape_layer.ts
+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/focus_trap.ts
 var FOCUSABLE = 'a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
 var FocusTrap = class {
@@ -15,6 +99,8 @@ var FocusTrap = class {
   #inertedSiblings = [];
   /** Whether the modal side effects are currently applied. */
   #activeState = false;
+  /** Registers the trap on the shared Escape stack while active (see {@link EscapeLayer}). */
+  #escapeLayer = new EscapeLayer();
   /** Returns the trapped element; called on every operation for the live target. */
   #getContainer;
   /** Closing/focus hooks; see {@link FocusTrapOptions}. */
@@ -49,6 +135,9 @@ var FocusTrap = class {
     }
     if (this.#flag(this.#options.isolate, true)) this.#isolateBackground();
     document.addEventListener("keydown", this.#onKeydown);
+    document.addEventListener("turbo:before-cache", this.#onBeforeCache);
+    const onEscape = this.#options.onEscape;
+    if (onEscape) this.#escapeLayer.activate(document, { onDismiss: () => onEscape() });
     if (this.#flag(this.#options.autoFocus, true)) this.#focusInitial();
   }
   /**
@@ -61,7 +150,9 @@ var FocusTrap = class {
   deactivate({ restoreFocus = true } = {}) {
     if (!this.#activeState) return;
     this.#activeState = false;
+    this.#escapeLayer.deactivate();
     document.removeEventListener("keydown", this.#onKeydown);
+    document.removeEventListener("turbo:before-cache", this.#onBeforeCache);
     if (this.#scrollLocked) {
       document.body.style.overflow = this.#previousBodyOverflow;
       this.#scrollLocked = false;
@@ -77,15 +168,23 @@ var FocusTrap = class {
     if (option === void 0) return fallback;
     return typeof option === "function" ? option() : option;
   }
-  /** Handles `Escape` (delegated) and `Tab` (focus trap) while active. */
+  /**
+   * Reverts the side effects just before Turbo caches the page snapshot, so an
+   * overlay left open does not bake the scroll lock into `body[style]` — a
+   * restored page would feed that locked value back into {@link activate} as the
+   * baseline, and closing would then never unlock the page. Markup state stays
+   * 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 });
+  };
+  /**
+   * Handles `Tab` (focus trap) while active. `Escape` dismissal is owned by the
+   * shared {@link EscapeLayer} resolver, so Tab trapping stays independent of
+   * which layer currently owns Escape.
+   */
   #onKeydown = (event) => {
-    if (event.key === "Escape") {
-      if (this.#options.onEscape) {
-        event.preventDefault();
-        this.#options.onEscape();
-      }
-      return;
-    }
     if (event.key === "Tab") this.#trapTab(event);
   };
   /** Keeps `Tab` focus cycling within the container's focusable elements. */

data/dist/controllers/dropdown_controller.js

@@ -1,35 +1,136 @@
 import { Controller } from '@hotwired/stimulus';
 
+// src/controllers/dropdown_controller.ts
+
+// src/utils/aria_ids.ts
+var counter = 0;
+function uniqueId(prefix = "stimeo") {
+  let candidate;
+  do {
+    counter += 1;
+    candidate = `${prefix}-${counter}`;
+  } while (typeof document !== "undefined" && document.getElementById(candidate) !== null);
+  return candidate;
+}
+function ensureId(element, prefix = "stimeo") {
+  if (element.id) return element.id;
+  const id = uniqueId(prefix);
+  element.id = id;
+  return id;
+}
+
+// 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/controllers/dropdown_controller.ts
 var DropdownController = class extends Controller {
   static targets = ["trigger", "menu"];
   static actions = ["close", "open", "toggle"];
+  /** Escape-stack membership while open; the shared resolver dismisses via it. */
+  #escapeLayer = new EscapeLayer();
   /** Closes the menu when a click lands outside the controller's element. */
   #onOutsideClick = (event) => {
     if (!this.element.contains(event.target)) {
       this.close();
     }
   };
-  /** Closes the menu on `Escape` and restores focus to the trigger. */
-  #onKeydown = (event) => {
-    if (event.key === "Escape" && this.#isOpen) {
-      this.close();
-      if (this.hasTriggerTarget) this.triggerTarget.focus();
-    }
-  };
-  /**
-   * Starts in the closed state and registers the document-level listeners that
-   * power outside-click and `Escape` handling.
-   */
+  /** Starts in the closed state and registers outside-click handling. */
   connect() {
+    this.#associateTriggerWithMenu();
     this.close();
-    document.addEventListener("click", this.#onOutsideClick);
-    document.addEventListener("keydown", this.#onKeydown);
+    document.addEventListener("click", this.#onOutsideClick, true);
   }
-  /** Removes the document-level listeners registered in {@link connect}. */
+  /** Removes the listeners registered in {@link connect}. */
   disconnect() {
-    document.removeEventListener("click", this.#onOutsideClick);
-    document.removeEventListener("keydown", this.#onKeydown);
+    this.#escapeLayer.deactivate();
+    document.removeEventListener("click", this.#onOutsideClick, true);
   }
   /** Toggles the menu between open and closed. Bound via `data-action`. */
   toggle() {
@@ -42,6 +143,10 @@ var DropdownController = class extends Controller {
   /** Reveals the menu and reflects the open state on the trigger. */
   open() {
     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");
@@ -49,16 +154,34 @@ var DropdownController = class extends Controller {
   }
   /** Hides the menu and reflects the closed state on the trigger. */
   close() {
+    this.#escapeLayer.deactivate();
     if (!this.hasMenuTarget) return;
     this.menuTarget.hidden = true;
     if (this.hasTriggerTarget) {
       this.triggerTarget.setAttribute("aria-expanded", "false");
     }
   }
+  /** Closes and restores focus to the trigger (the keyboard-dismissal path). */
+  #closeAndRestore() {
+    this.close();
+    if (this.hasTriggerTarget) this.triggerTarget.focus();
+  }
   /** Whether the menu is currently visible. */
   get #isOpen() {
     return this.hasMenuTarget && !this.menuTarget.hidden;
   }
+  /**
+   * Associates the disclosure trigger and controlled region without clobbering
+   * authored markup.
+   */
+  #associateTriggerWithMenu() {
+    if (!this.hasTriggerTarget || !this.hasMenuTarget) return;
+    if (this.triggerTarget.hasAttribute("aria-controls")) return;
+    this.triggerTarget.setAttribute(
+      "aria-controls",
+      ensureId(this.menuTarget, "stimeo--dropdown-menu")
+    );
+  }
 };
 
 export { DropdownController };