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

data/dist/controllers/tooltip_controller.js

@@ -2,6 +2,90 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/tooltip_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/safe_timeout.ts
 var TimerRegistry = class {
   /** Live timer ids that have not yet been cleared (or, for timeouts, fired). */
@@ -88,27 +172,39 @@ var TooltipController = class extends Controller {
     hideDelay: { type: Number, default: 0 },
     closeOnScroll: { type: Boolean, default: false }
   };
-  static actions = ["hide", "onKeydown", "show"];
-  /** Pending show/hide timers, torn down together on disconnect. */
+  static actions = ["hide", "show"];
+  /** Registry whose pending timers are cancelled individually with their guard ids. */
   #timers = new SafeTimeout();
-  /** The id of the currently pending show or hide timer, if any. */
+  /** Escape-stack membership while shown; the shared resolver dismisses via it. */
+  #escapeLayer = new EscapeLayer();
+  /** The id of the currently pending show timer, if any. */
   #pendingShow = null;
+  /** The id of the currently pending hide timer, if any. */
   #pendingHide = null;
+  /** Whether focus or the pointer currently requires the tooltip to persist. */
+  #focusActive = false;
+  #pointerActive = false;
   /** Cleanup for the dismiss-on-scroll listeners while shown, or `null`. */
   #stopScrollDismiss = null;
-  /** Starts hidden. */
+  /** Starts hidden with no stale timer or interaction state from a prior connection. */
   connect() {
+    this.#cancelShow();
+    this.#cancelHide();
+    this.#resetInteractionState();
     this.#conceal();
   }
-  /** Clears timers and the document `Escape` / scroll listeners so nothing outlives the element. */
+  /** Clears timers, the Escape-stack membership, and scroll listeners so nothing outlives the element. */
   disconnect() {
-    this.#timers.clearAll();
-    document.removeEventListener("keydown", this.#onDocumentKeydown);
+    this.#cancelShow();
+    this.#cancelHide();
+    this.#resetInteractionState();
+    this.#escapeLayer.deactivate();
     this.#stopScrollDismiss?.();
     this.#stopScrollDismiss = null;
   }
-  /** Shows the tooltip, after `showDelay` ms (or immediately at 0). Cancels a pending hide. */
-  show() {
+  /** Shows after `showDelay`, recording the focus/pointer reason supplied by an action event. */
+  show(event) {
+    this.#activateInteraction(event);
     this.#cancelHide();
     if (this.#isVisible || this.#pendingShow !== null) return;
     if (this.showDelayValue <= 0) {
@@ -120,8 +216,13 @@ var TooltipController = class extends Controller {
       this.#reveal();
     }, this.showDelayValue);
   }
-  /** Hides the tooltip, after `hideDelay` ms (or immediately at 0). Cancels a pending show. */
-  hide() {
+  /** Hides after `hideDelay` once no focus/pointer reason remains; eventless calls are explicit. */
+  hide(event) {
+    const interactionEnded = this.#deactivateInteraction(event);
+    if (interactionEnded && this.#hasActiveInteraction) {
+      this.#cancelHide();
+      return;
+    }
     this.#cancelShow();
     if (!this.#isVisible || this.#pendingHide !== null) return;
     if (this.hideDelayValue <= 0) {
@@ -133,52 +234,57 @@ var TooltipController = class extends Controller {
       this.#conceal();
     }, this.hideDelayValue);
   }
-  /**
-   * Dismisses the tooltip on `Escape` from the trigger. The authoritative
-   * dismissal path is the document-level listener (added while shown) so a
-   * hover-triggered tooltip is dismissible regardless of focus; this handler
-   * keeps the documented `keydown->#onKeydown` binding meaningful too.
-   */
-  onKeydown(event) {
-    if (event.key === "Escape" && this.#isVisible) {
-      event.preventDefault();
-      this.#cancelShow();
-      this.#cancelHide();
-      this.#conceal();
-    }
-  }
-  /** Reveals the content and starts watching for a dismissing `Escape`/scroll. */
+  /** Reveals the content and joins the Escape stack / starts the scroll watcher. */
   #reveal() {
     if (!this.hasContentTarget) return;
     this.contentTarget.hidden = false;
     this.contentTarget.setAttribute("data-state", "open");
-    document.addEventListener("keydown", this.#onDocumentKeydown);
+    this.#escapeLayer.activate(document, { onDismiss: () => this.#dismiss() });
     if (this.closeOnScrollValue && !this.#stopScrollDismiss) {
-      this.#stopScrollDismiss = observeScrollDismiss(this.element, () => {
-        this.#cancelShow();
-        this.#cancelHide();
-        this.#conceal();
-      });
+      this.#stopScrollDismiss = observeScrollDismiss(this.element, () => this.#dismiss());
     }
   }
-  /** Hides the content and stops watching for `Escape`/scroll. */
+  /** Hides the content and leaves the Escape stack / stops the scroll watcher. */
   #conceal() {
-    document.removeEventListener("keydown", this.#onDocumentKeydown);
+    this.#escapeLayer.deactivate();
     this.#stopScrollDismiss?.();
     this.#stopScrollDismiss = null;
     if (!this.hasContentTarget) return;
     this.contentTarget.hidden = true;
     this.contentTarget.setAttribute("data-state", "closed");
   }
-  /** Document-level `Escape` watcher (active only while shown). */
-  #onDocumentKeydown = (event) => {
-    if (event.key === "Escape") {
-      event.preventDefault();
-      this.#cancelShow();
-      this.#cancelHide();
-      this.#conceal();
+  /** Cancels pending timers and conceals immediately (shared Escape / scroll path). */
+  #dismiss() {
+    this.#cancelShow();
+    this.#cancelHide();
+    this.#conceal();
+  }
+  /** Records the modality whose enter/focus event requires the tooltip to stay visible. */
+  #activateInteraction(event) {
+    if (event?.type === "mouseenter") this.#pointerActive = true;
+    if (event?.type === "focusin") this.#focusActive = true;
+  }
+  /** Clears a modality on leave/blur and reports whether the event represented such a change. */
+  #deactivateInteraction(event) {
+    if (event?.type === "mouseleave") {
+      this.#pointerActive = false;
+      return true;
     }
-  };
+    if (event?.type === "focusout") {
+      this.#focusActive = false;
+      return true;
+    }
+    return false;
+  }
+  /** Discards interaction reasons at a lifecycle boundary. */
+  #resetInteractionState() {
+    this.#focusActive = false;
+    this.#pointerActive = false;
+  }
+  /** Whether focus or pointer presence still requires a persistent tooltip. */
+  get #hasActiveInteraction() {
+    return this.#focusActive || this.#pointerActive;
+  }
   /** Cancels any pending show timer. */
   #cancelShow() {
     if (this.#pendingShow !== null) {

data/dist/controllers/transition_controller.js

@@ -2,6 +2,11 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/transition_controller.ts
 
+// src/utils/reduced_motion.ts
+function prefersReducedMotion() {
+  return typeof window.matchMedia === "function" && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+}
+
 // src/utils/safe_timeout.ts
 var TimerRegistry = class {
   /** Live timer ids that have not yet been cleared (or, for timeouts, fired). */
@@ -55,14 +60,149 @@ var SafeTimeout = class extends TimerRegistry {
   }
 };
 
+// src/utils/transition_completion.ts
+function timeMs(value) {
+  const trimmed = value.trim();
+  const amount = Number.parseFloat(trimmed);
+  if (!Number.isFinite(amount)) return 0;
+  if (trimmed.endsWith("ms")) return amount;
+  if (trimmed.endsWith("s")) return amount * 1e3;
+  return 0;
+}
+function cssList(value) {
+  return value.split(",").map((item) => item.trim()).filter(Boolean);
+}
+function transitionTimings(style) {
+  const properties = cssList(style.transitionProperty);
+  const durations = cssList(style.transitionDuration).map(timeMs);
+  const delays = cssList(style.transitionDelay).map(timeMs);
+  const effectiveProperties = properties.length > 0 ? properties : Array.from({ length: Math.max(durations.length, delays.length, 1) }, () => "all");
+  const effectiveDurations = durations.length > 0 ? durations : [0];
+  const effectiveDelays = delays.length > 0 ? delays : [0];
+  return effectiveProperties.filter((property) => property !== "none").map((property, index) => ({
+    property,
+    totalMs: Math.max(
+      0,
+      (effectiveDurations[index % effectiveDurations.length] ?? 0) + (effectiveDelays[index % effectiveDelays.length] ?? 0)
+    )
+  }));
+}
+function maxTotalMs(timings) {
+  return timings.reduce((max, { totalMs }) => Math.max(max, totalMs), 0);
+}
+var TransitionCompletion = class {
+  #timers = new SafeTimeout();
+  #element = null;
+  #complete = null;
+  #pendingProperties = null;
+  #deadline = 0;
+  /**
+   * Replaces any prior wait and invokes `complete` synchronously for a 0ms
+   * transition (including when `getComputedStyle` is unavailable).
+   *
+   * With a positive `options.timeoutMs` the synchronous fast-path is skipped and
+   * the override replaces the auto-computed fallback (see {@link TransitionWaitOptions}).
+   */
+  wait(element, complete, options = {}) {
+    this.cancel();
+    const requested = options.timeoutMs ?? 0;
+    const override = Number.isFinite(requested) && requested > 0 ? requested : 0;
+    const timings = typeof window.getComputedStyle === "function" ? transitionTimings(window.getComputedStyle(element)) : [];
+    const maximum = maxTotalMs(timings);
+    if (maximum <= 0 && override <= 0) {
+      complete();
+      return;
+    }
+    this.#element = element;
+    this.#complete = complete;
+    this.#deadline = Date.now() + maximum;
+    const activeProperties = this.#activeTransitionProperties(element);
+    this.#pendingProperties = activeProperties.size > 0 ? activeProperties : this.#explicitPendingProperties(timings);
+    element.addEventListener("transitionend", this.#onTerminal);
+    element.addEventListener("transitioncancel", this.#onTerminal);
+    this.#timers.set(() => this.#finish(), override > 0 ? override : maximum + 50);
+  }
+  /** Cancels the pending wait without invoking its completion callback. */
+  cancel() {
+    this.#complete = null;
+    this.#teardown();
+  }
+  /**
+   * Handles terminal events from the observed element only.
+   *
+   * For explicit property lists, every declared positive-time property must
+   * settle. For `all`, no reliable property set exists, so an event can finish
+   * only after the computed maximum time; the safety timeout owns the usual path.
+   */
+  #onTerminal = (event) => {
+    if (event.target !== this.#element) return;
+    const transitionEvent = event;
+    if (transitionEvent.pseudoElement) return;
+    if (this.#pendingProperties) {
+      const propertyName = transitionEvent.propertyName;
+      const active = this.#activeTransitionProperties(this.#element);
+      if (active.has(propertyName)) return;
+      if (!this.#pendingProperties.delete(propertyName)) return;
+      if (this.#pendingProperties.size > 0) return;
+      if (active.size > 0) {
+        this.#pendingProperties = active;
+        return;
+      }
+      this.#finish();
+      return;
+    }
+    if (Date.now() >= this.#deadline) this.#finish();
+  };
+  /**
+   * Returns active CSS transition properties expanded to the names reported by
+   * terminal events. CSS animations and pseudo-element effects are excluded.
+   */
+  #activeTransitionProperties(element) {
+    if (!element || typeof element.getAnimations !== "function") return /* @__PURE__ */ new Set();
+    try {
+      const properties = element.getAnimations().flatMap((animation) => {
+        if (animation.playState === "idle" || animation.playState === "finished") return [];
+        const effect = animation.effect;
+        if (effect?.pseudoElement) return [];
+        const target = effect?.target;
+        if (target && target !== element) return [];
+        const property = animation.transitionProperty;
+        return typeof property === "string" && property.length > 0 ? [property] : [];
+      });
+      return new Set(properties);
+    } catch {
+      return /* @__PURE__ */ new Set();
+    }
+  }
+  /** Returns explicit positive-time properties, or `null` for the ambiguous `all`. */
+  #explicitPendingProperties(timings) {
+    if (timings.some(({ property }) => property === "all")) return null;
+    const pending = new Set(
+      timings.filter(({ totalMs }) => totalMs > 0).map(({ property }) => property)
+    );
+    return pending.size > 0 ? pending : null;
+  }
+  /** Completes exactly once, releasing listeners and the fallback before the callback. */
+  #finish() {
+    const complete = this.#complete;
+    if (!complete) return;
+    this.#complete = null;
+    this.#teardown();
+    complete();
+  }
+  /** Releases the exact element listeners and timer owned by the current wait. */
+  #teardown() {
+    this.#timers.clearAll();
+    this.#element?.removeEventListener("transitionend", this.#onTerminal);
+    this.#element?.removeEventListener("transitioncancel", this.#onTerminal);
+    this.#element = null;
+    this.#pendingProperties = null;
+    this.#deadline = 0;
+  }
+};
+
 // src/controllers/transition_controller.ts
 var tokensOf = (value) => value.split(/\s+/).filter(Boolean);
-var firstTimeMs = (value) => {
-  const first = value.split(",")[0]?.trim() ?? "";
-  const amount = Number.parseFloat(first);
-  if (Number.isNaN(amount)) return 0;
-  return first.endsWith("ms") ? amount : amount * 1e3;
-};
 var TransitionController = class extends Controller {
   static values = {
     enter: { type: String, default: "" },
@@ -75,9 +215,9 @@ var TransitionController = class extends Controller {
   };
   static actions = ["enter", "leave", "toggle"];
   static events = ["entered", "left"];
-  #timers = new SafeTimeout();
+  /** Owns the cancellable completion wait (terminal events + bounded fallback). */
+  #transition = new TransitionCompletion();
   #rafId = null;
-  #endListener = null;
   connect() {
     this.#strip();
     this.element.setAttribute("data-transition-state", this.element.hidden ? "left" : "entered");
@@ -104,7 +244,7 @@ var TransitionController = class extends Controller {
     const isEnter = kind === "enter";
     if (isEnter) this.element.hidden = false;
     this.element.setAttribute("data-transition-state", isEnter ? "entering" : "leaving");
-    if (this.#prefersReducedMotion()) {
+    if (prefersReducedMotion()) {
       this.#finish(kind);
       return;
     }
@@ -116,12 +256,13 @@ var TransitionController = class extends Controller {
       this.#rafId = null;
       this.#remove(from);
       this.#add(to);
-      this.#awaitEnd(() => this.#finish(kind));
+      this.#transition.wait(this.element, () => this.#finish(kind), {
+        timeoutMs: this.timeoutValue
+      });
     });
   }
   /** Settles the element into the completed state, clearing the stage classes. */
   #finish(kind) {
-    this.#cleanupEnd();
     this.#strip();
     if (kind === "enter") {
       this.element.setAttribute("data-transition-state", "entered");
@@ -132,29 +273,13 @@ var TransitionController = class extends Controller {
       this.dispatch("left", { detail: {} });
     }
   }
-  /** Resolves on the element's own `transitionend`, with a safety timeout fallback. */
-  #awaitEnd(done) {
-    this.#endListener = (event) => {
-      if (event.target === this.element) done();
-    };
-    this.element.addEventListener("transitionend", this.#endListener);
-    const ms = this.timeoutValue > 0 ? this.timeoutValue : this.#duration();
-    this.#timers.set(done, ms);
-  }
-  #cleanupEnd() {
-    if (this.#endListener) {
-      this.element.removeEventListener("transitionend", this.#endListener);
-      this.#endListener = null;
-    }
-    this.#timers.clearAll();
-  }
   /** Cancels any in-flight transition (interruption / teardown). */
   #cancel() {
     if (this.#rafId !== null) {
       this.#cancelRaf(this.#rafId);
       this.#rafId = null;
     }
-    this.#cleanupEnd();
+    this.#transition.cancel();
     this.#strip();
   }
   #add(...lists) {
@@ -176,13 +301,6 @@ var TransitionController = class extends Controller {
       this.leaveToValue
     );
   }
-  /** Auto-computed safety duration (transition time + delay, with a small buffer). */
-  #duration() {
-    if (typeof window.getComputedStyle !== "function") return 0;
-    const style = window.getComputedStyle(this.element);
-    const total = firstTimeMs(style.transitionDuration) + firstTimeMs(style.transitionDelay);
-    return total > 0 ? total + 50 : 0;
-  }
   #raf(callback) {
     if (typeof window.requestAnimationFrame === "function") {
       return window.requestAnimationFrame(() => callback());
@@ -193,9 +311,6 @@ var TransitionController = class extends Controller {
     if (typeof window.cancelAnimationFrame === "function") window.cancelAnimationFrame(id);
     else window.clearTimeout(id);
   }
-  #prefersReducedMotion() {
-    return typeof window.matchMedia === "function" && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
-  }
 };
 
 export { TransitionController };