stimeo-ui 0.15.0 → 0.16.0

package/dist/controllers/flash_controller.js

@@ -42,6 +42,15 @@ var BeforeCacheReset = class _BeforeCacheReset {
   }
 };
 
+// src/utils/event_owner.ts
+function ownerIndex(candidates, node) {
+  if (!(node instanceof Node)) return -1;
+  return candidates.findIndex((candidate) => candidate.contains(node));
+}
+function ownerOf(candidates, node) {
+  return candidates[ownerIndex(candidates, node)] ?? null;
+}
+
 // src/utils/safe_timeout.ts
 var TimerRegistry = class {
   /** Live timer ids that have not yet been cleared (or, for timeouts, fired). */
@@ -138,6 +147,63 @@ var KeyedTimers = class {
   }
 };
 
+// src/utils/listener_set.ts
+var ListenerSet = class {
+  /** The generation every `add` joins until the next `dispose()`. */
+  #abort = new AbortController();
+  /**
+   * Attaches `handler` to the open generation, exactly as the caller spelled it.
+   *
+   * The set supplies the signal, so `options` carries everything else the DOM
+   * accepts — `capture` included, which has to match at release time and no
+   * longer has a second place to drift from.
+   */
+  add(target, type, handler, options) {
+    target.addEventListener(type, handler, { ...options, signal: this.#abort.signal });
+  }
+  /**
+   * Releases every listener of the open generation, synchronously, and opens the
+   * next one. Idempotent, and safe before anything has been added.
+   */
+  dispose() {
+    this.#abort.abort();
+    this.#abort = new AbortController();
+  }
+};
+
+// 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/utils/pausable_timers.ts
 var PausableTimers = class {
   #timers = new KeyedTimers();
@@ -151,16 +217,20 @@ var PausableTimers = class {
     const reasons = this.#entries.get(key)?.reasons ?? /* @__PURE__ */ new Set();
     const entry = { callback, startedAt: 0, remaining: delay, reasons };
     this.#entries.set(key, entry);
-    if (reasons.size === 0) this.#arm(key, entry);
+    if (reasons.size === 0) this.#arm(key, entry, callback);
   }
   /**
    * Holds `key` for `reason` and banks the time left, with a floor of one
-   * millisecond. Reports whether this call is the one that stopped a running
-   * timer, so the caller can write its held-state hook exactly once.
+   * millisecond. A key with no timer is held all the same. Reports whether this
+   * call is the one that stopped a running timer, so the caller can write its
+   * held-state hook exactly once.
    */
   pause(key, reason) {
-    const entry = this.#entries.get(key);
-    if (entry === void 0) return false;
+    let entry = this.#entries.get(key);
+    if (entry === void 0) {
+      entry = { callback: null, startedAt: 0, remaining: 0, reasons: /* @__PURE__ */ new Set() };
+      this.#entries.set(key, entry);
+    }
     entry.reasons.add(reason);
     if (!this.#timers.has(key)) return false;
     this.#timers.clear(key);
@@ -169,20 +239,40 @@ var PausableTimers = class {
   }
   /**
    * Releases `reason` on `key`, arming the banked time again once no reason is
-   * left. Reports whether this call is the one that started the timer again.
+   * left; a key released with no timer is forgotten. Reports whether this call
+   * is the one that started the timer again.
    */
   resume(key, reason) {
     const entry = this.#entries.get(key);
     if (entry === void 0) return false;
     entry.reasons.delete(reason);
     if (entry.reasons.size > 0 || this.#timers.has(key)) return false;
-    this.#arm(key, entry);
+    const { callback } = entry;
+    if (callback === null) {
+      this.#entries.delete(key);
+      return false;
+    }
+    this.#arm(key, entry, callback);
     return true;
   }
+  /** Whether any reason holds `key`, with or without a timer. */
+  isHeld(key) {
+    return (this.#entries.get(key)?.reasons.size ?? 0) > 0;
+  }
   /** Whether `key` is armed or held — that is, whether this registry drives it at all. */
   tracks(key) {
     return this.#entries.has(key);
   }
+  /**
+   * Cancels `key`'s timer and keeps its hold, so a release arms nothing; a key
+   * nothing holds is forgotten.
+   */
+  disarm(key) {
+    this.#timers.clear(key);
+    const entry = this.#entries.get(key);
+    if (entry?.reasons.size) entry.callback = null;
+    else this.#entries.delete(key);
+  }
   /** Cancels `key`'s timer and drops its hold. */
   clear(key) {
     this.#timers.clear(key);
@@ -196,20 +286,25 @@ var PausableTimers = class {
     this.#timers.clearAll();
     this.#entries.clear();
   }
-  /** Starts `entry`'s banked time running for `key`, and drops it as it fires. */
-  #arm(key, entry) {
+  /** Starts `entry`'s banked time running for `key`, and drops it as `callback` fires. */
+  #arm(key, entry, callback) {
     entry.startedAt = Date.now();
     this.#timers.set(
       key,
       () => {
         this.#entries.delete(key);
-        entry.callback();
+        callback();
       },
       entry.remaining
     );
   }
 };
 
+// src/utils/target_selector.ts
+function targetSelector(identifier, name) {
+  return `[data-${identifier}-target~="${name}"]`;
+}
+
 // src/utils/transition_completion.ts
 function timeMs(value) {
   const trimmed = value.trim();
@@ -246,8 +341,12 @@ function maxTransitionTotalMs(style) {
 
 // src/controllers/flash_controller.ts
 var ASSERTIVE_TYPES = /* @__PURE__ */ new Set(["alert", "error"]);
-var MESSAGE_SELECTOR = '[data-stimeo--flash-target="message"]';
+var MESSAGE_PART = "message";
 var FlashController = class extends Controller {
+  /** Selects the message parts, in the namespace this controller is registered under. */
+  get #messageSelector() {
+    return targetSelector(this.identifier, MESSAGE_PART);
+  }
   static targets = ["region", "message"];
   static values = {
     duration: { type: Number, default: 5e3 },
@@ -258,11 +357,33 @@ var FlashController = class extends Controller {
   static events = ["show", "dismiss", "reconcile"];
   /** Removal timers for the leaving transition; the auto-dismiss ones live below. */
   #timers = new SafeTimeout();
-  /** Per-message auto-dismiss, held open while the message is hovered or focused. */
+  /**
+   * Per-message auto-dismiss held open while the message is hovered or focused, and
+   * the one record of which messages hover or focus holds, which the cap reads.
+   */
   #dismiss = new PausableTimers();
+  /**
+   * Auto-dismiss of the messages taken on while `pauseOnHover` is off. It runs on
+   * whatever holds the message; the hold itself still keeps the cap away.
+   */
+  #fixedDismiss = new KeyedTimers();
+  /** Applies the cap again once the event that released a hold has run its course. */
+  #reapply = new MicrotaskCoalescer(() => this.#reapplyCap());
+  /** Messages the pointer or focus moved into since the cap was last applied again. */
+  #spared = [];
+  /** The next pointer movement, listened for while a hover hold waits on it. */
+  #pointer = new ListenerSet();
+  /** Messages whose hover hold waits for the next pointer movement to be confirmed. */
+  #awaitingPointer = /* @__PURE__ */ new Set();
   #observer = null;
   /** Whether the controller is between `connect()` and `disconnect()`. */
   #connected = false;
+  /**
+   * The `max` the stack was last held to, or `null` before the first time. `connect()`
+   * applies the cap only when `max` is not that one, so a reconnect of the same instance
+   * leaves the stack as it was unless `max` changed while it was away.
+   */
+  #appliedMax = null;
   /** Messages already processed, in insertion order, to enforce `max` and avoid double work. */
   #order = [];
   /**
@@ -274,12 +395,28 @@ var FlashController = class extends Controller {
   #leaving = /* @__PURE__ */ new Set();
   #beforeCache = new BeforeCacheReset(() => this.#rewindForCache());
   #onEnter = (event) => this.#pause(event.currentTarget, event.type === "focusin" ? "focus" : "hover");
-  #onLeave = (event) => this.#resume(event.currentTarget, event.type === "focusout" ? "focus" : "hover");
+  /**
+   * Releases hover or focus on a message. Focus moving between two of the message's
+   * own controls is no release, since `focusout` names a control still inside it; and
+   * the message the pointer or focus is moving into is spared when the release
+   * applies the cap again, because its own hold only arrives after this event.
+   */
+  #onLeave = (event) => {
+    const message = event.currentTarget;
+    const next = ownerOf(this.#order, event.relatedTarget);
+    if (next === message) return;
+    this.#resume(message, event.type === "focusout" ? "focus" : "hover", next);
+  };
   connect() {
     this.#connected = true;
+    this.#reapply.activate();
     for (const message of this.messageTargets) {
       if (this.#owns(message)) this.#process(message, true);
     }
+    if (!Object.is(this.#appliedMax, this.maxValue)) {
+      this.#appliedMax = this.maxValue;
+      this.#enforceMax();
+    }
     this.#syncObservation();
     this.#beforeCache.activate();
   }
@@ -289,6 +426,11 @@ var FlashController = class extends Controller {
     this.#stopObserving();
     this.#timers.clearAll();
     this.#dismiss.clearAll();
+    this.#fixedDismiss.clearAll();
+    this.#reapply.cancel();
+    this.#spared = [];
+    this.#pointer.dispose();
+    this.#awaitingPointer.clear();
     for (const message of this.#order) this.#unbindPause(message);
     this.#order.length = 0;
     this.#leaving.clear();
@@ -319,6 +461,19 @@ var FlashController = class extends Controller {
   regionTargetDisconnected() {
     this.#resync();
   }
+  /**
+   * Holds the stack to a changed `max`: lowering it below the count dismisses the
+   * oldest messages hover and focus do not hold, with reason `limit`, as an arrival
+   * past the cap does, while raising it or setting `0` dismisses nothing. Stimulus can
+   * also call this ahead of `connect()` — for an attribute that changed while the
+   * controller was away, and on every connect for an undeclared `max`, with its default;
+   * `connect()` decides then.
+   */
+  maxValueChanged() {
+    if (!this.#connected) return;
+    this.#appliedMax = this.maxValue;
+    this.#enforceMax();
+  }
   /**
    * Whether this controller owns `message`. Ownership is the current `region`'s
    * subtree: a message target anywhere else in the controller's scope is the
@@ -337,12 +492,16 @@ var FlashController = class extends Controller {
    * scheduled removal are cancelled. A move *within* the region keeps all of them —
    * which is why the element must still be a message to be treated as one: ownership
    * alone reads an in-place attribute rewrite as a move, and a node outside the target
-   * set belongs to the consumer, so nothing here may dismiss it.
+   * set belongs to the consumer, so nothing here may dismiss it. A move may still have
+   * ended a hold, so those are read again.
    */
   messageTargetDisconnected(message) {
     if (!this.#connected) return;
-    const moved = this.#owns(message) && message.matches(MESSAGE_SELECTOR);
-    if (moved) return;
+    const moved = this.#owns(message) && message.matches(this.#messageSelector);
+    if (moved) {
+      this.#afterMove(message);
+      return;
+    }
     this.#forget(message);
     this.#leaving.delete(message);
   }
@@ -376,13 +535,11 @@ var FlashController = class extends Controller {
     this.#observer = null;
   }
   /**
-   * Pause-on-hover/focus listeners, bound and unbound as a pair so the two sides
-   * stay in sync. Binding is gated by `pauseOnHover`; unbinding is unconditional
-   * and idempotent (a no-op when nothing was bound), which keeps teardown correct
-   * even if `pauseOnHover` were ever toggled during a message's life.
+   * Hover and focus listeners, bound and unbound as a pair so the two sides stay in
+   * sync. Every message gets them, whatever `pauseOnHover` says, because the cap reads
+   * the holds they record; unbinding is idempotent (a no-op when nothing was bound).
    */
   #bindPause(message) {
-    if (!this.pauseOnHoverValue) return;
     message.addEventListener("mouseenter", this.#onEnter);
     message.addEventListener("mouseleave", this.#onLeave);
     message.addEventListener("focusin", this.#onEnter);
@@ -397,7 +554,7 @@ var FlashController = class extends Controller {
   /** Dismisses the flash whose close control fired the event. */
   dismiss(event) {
     const target = event.currentTarget || event.target;
-    const message = target?.closest(MESSAGE_SELECTOR);
+    const message = target?.closest(this.#messageSelector);
     if (message) this.#beginDismiss(message, "user");
   }
   /** Processes messages added after connect (Turbo Stream); their own role announces them. */
@@ -405,20 +562,25 @@ var FlashController = class extends Controller {
     for (const mutation of mutations) {
       for (const node of mutation.addedNodes) {
         if (!(node instanceof HTMLElement)) continue;
-        if (node.matches(MESSAGE_SELECTOR)) this.#process(node, false);
-        for (const message of node.querySelectorAll(MESSAGE_SELECTOR)) {
+        if (node.matches(this.#messageSelector)) this.#process(node, false);
+        for (const message of node.querySelectorAll(this.#messageSelector)) {
           this.#process(message, false);
         }
       }
     }
   }
   /**
-   * Applies role/state, wires pause listeners, schedules auto-dismiss, and either
-   * bridges to the Announcer (`bridge`, for initial flashes) or leaves the message's
-   * own role to do the announcing (dynamic inserts). Idempotent per message.
+   * Applies role/state, wires pause listeners, takes the holds the message already has,
+   * and schedules auto-dismiss. A message `connect()` takes on (`atConnect`) is bridged
+   * to the Announcer and meets no cap here, `connect()` holding the stack to it; a later
+   * insert announces through its own role and meets the cap as it arrives. Idempotent
+   * per message, and a node that has left the region by the time its insertion is
+   * reported is not taken on.
    */
-  #process(message, bridge) {
-    if (this.#order.includes(message) || this.#leaving.has(message)) return;
+  #process(message, atConnect) {
+    if (this.#order.includes(message) || this.#leaving.has(message) || !this.#owns(message)) {
+      return;
+    }
     const type = message.getAttribute("data-flash-type") ?? "";
     const assertive = ASSERTIVE_TYPES.has(type);
     if (!message.hasAttribute("role")) {
@@ -427,44 +589,141 @@ var FlashController = class extends Controller {
     message.setAttribute("data-flash-state", "visible");
     this.#order.push(message);
     this.#bindPause(message);
+    this.#readHolds(message);
     const text = message.textContent?.trim() ?? "";
     this.dispatch("show", { target: message, detail: { type, message: text } });
-    if (bridge) announce(text, { assertive });
+    if (atConnect) announce(text, { assertive });
     this.#startTimer(message);
-    this.#enforceMax();
+    if (!atConnect) this.#enforceMax([message]);
   }
-  /** Removes the oldest visible flashes once the count exceeds `max` (0 = unlimited). */
-  #enforceMax() {
-    if (this.maxValue <= 0) return;
-    while (this.#order.length > this.maxValue) {
-      const oldest = this.#order[0];
-      if (!oldest) break;
-      this.#beginDismiss(oldest, "limit");
+  /**
+   * Dismisses the oldest messages with reason `limit` while more than `max` are shown
+   * (0 or less, or not a finite number, means no cap), passing over every message hover
+   * or focus holds and those in `spared` — the message just taken on, or the ones the
+   * pointer or focus moved into. Only messages still in the region count or go: one a
+   * script has just taken out stays on the stack until its removal is reported. With
+   * nothing else left to go the stack stays over the cap. The loop walks a copy and
+   * re-reads the count on every step, because a `dismiss` listener may already have
+   * changed both.
+   *
+   * @stimeoRenderRoot
+   */
+  #enforceMax(spared = []) {
+    if (!Number.isFinite(this.maxValue) || this.maxValue <= 0) return;
+    for (const message of [...this.#order]) {
+      if (this.#shownCount() <= this.maxValue) return;
+      if (this.#owns(message) && !spared.includes(message) && !this.#dismiss.isHeld(message)) {
+        this.#beginDismiss(message, "limit");
+      }
     }
   }
-  /** Arms a message's auto-dismiss; a non-positive `duration` means it never expires. */
+  /** How many messages the stack shows: the ones taken on that are still in the region. */
+  #shownCount() {
+    return this.#order.filter((message) => this.#owns(message)).length;
+  }
+  /**
+   * Arms a message's auto-dismiss; a non-positive `duration` means it never expires.
+   * The timer waits out hover and focus when `pauseOnHover` is on, and runs on
+   * regardless when it is off.
+   *
+   * @stimeoRuntimeOnly `duration` is the delay of the one dismissal timer this call arms,
+   *   and `pauseOnHover` whether hover and focus hold that timer.
+   */
   #startTimer(message) {
     if (this.durationValue <= 0) return;
-    this.#dismiss.set(message, () => this.#beginDismiss(message, "timeout"), this.durationValue);
+    const dismiss = () => this.#beginDismiss(message, "timeout");
+    if (this.pauseOnHoverValue) this.#dismiss.set(message, dismiss, this.durationValue);
+    else this.#fixedDismiss.set(message, dismiss, this.durationValue);
   }
   /**
-   * Holds a message's auto-dismiss open while it is hovered or focused
-   * (WCAG 2.2 2.2.1). Hover and focus are independent reasons, and the registry
-   * banks the time left on the first of them and waits for the last.
+   * Records hover or focus on a message. Hover and focus are independent reasons:
+   * the registry banks the time left on the first of them and waits for the last
+   * (WCAG 2.2 2.2.1), and the cap passes over the message while either is held.
    */
   #pause(message, reason) {
     this.#dismiss.pause(message, reason);
   }
-  /** Releases one reason, resuming the banked time once no reason is left. */
-  #resume(message, reason) {
+  /**
+   * Releases one reason, resuming the banked time once no reason is left. Releasing
+   * the last one applies the cap again, sparing `spare`.
+   */
+  #resume(message, reason, spare) {
+    const held = this.#dismiss.isHeld(message);
     this.#dismiss.resume(message, reason);
+    if (held && !this.#dismiss.isHeld(message)) this.#capLater(spare);
+  }
+  /**
+   * Applies the cap again once the current event is over, sparing `spare`. A hold can
+   * end in a `focusout` the engine fires while it is itself taking the node out for a
+   * script's move or removal, and dismissing the message inside that event would pull
+   * the node from under the caller's own call.
+   */
+  #capLater(spare) {
+    if (spare) this.#spared.push(spare);
+    this.#reapply.schedule();
+  }
+  /** Applies the cap again, sparing every message gathered since the last pass. */
+  #reapplyCap() {
+    const spared = this.#spared;
+    this.#spared = [];
+    this.#enforceMax(spared);
+  }
+  /**
+   * Reads the holds of a message that moved within the region. Focus is read at once:
+   * an ordinary move ends it with a `focusout` and `moveBefore` keeps it. Where the
+   * pointer is, nothing says until it moves again: no `mouseleave` reaches a moved node,
+   * and `:hover` can answer from before the move. A message still held waits for that
+   * movement.
+   */
+  #afterMove(message) {
+    if (!message.contains(document.activeElement)) this.#resume(message, "focus", null);
+    if (this.#dismiss.isHeld(message)) this.#awaitPointer(message);
   }
-  /** Releases every per-message resource: timer, stacking slot, pause listeners. */
+  /**
+   * Takes the holds a message already has as it is taken on: focus inside it, and the
+   * pointer over it by `:hover`. That answer can date from before the message came here,
+   * so a hover hold taken on it waits for the next pointer movement to be confirmed.
+   */
+  #readHolds(message) {
+    if (message.contains(document.activeElement)) this.#pause(message, "focus");
+    if (!message.matches(":hover")) return;
+    this.#pause(message, "hover");
+    this.#awaitPointer(message);
+  }
+  /** Leaves `message`'s hover hold to be confirmed or let go on the next pointer movement. */
+  #awaitPointer(message) {
+    this.#awaitingPointer.add(message);
+    this.#pointer.add(document, "pointermove", this.#onPointerMove, {
+      capture: true,
+      passive: true
+    });
+  }
+  /**
+   * Reads `:hover` once the pointer has moved, when the answer is current, and lets go of
+   * the hover hold of every waiting message the pointer is not over. Listens once.
+   */
+  #onPointerMove = () => {
+    this.#pointer.dispose();
+    const waiting = [...this.#awaitingPointer];
+    this.#awaitingPointer.clear();
+    for (const message of waiting) {
+      if (!message.matches(":hover")) this.#resume(message, "hover", null);
+    }
+  };
+  /**
+   * Releases every per-message resource: timers, hold, stacking slot, pause listeners,
+   * and the wait on the pointer. A message something still held counts as released: the
+   * cap is applied again.
+   */
   #forget(message) {
+    if (this.#dismiss.isHeld(message)) this.#capLater(null);
     this.#dismiss.clear(message);
+    this.#fixedDismiss.clear(message);
     const index = this.#order.indexOf(message);
     if (index !== -1) this.#order.splice(index, 1);
     this.#unbindPause(message);
+    this.#awaitingPointer.delete(message);
+    if (this.#awaitingPointer.size === 0) this.#pointer.dispose();
   }
   /** Marks a message leaving, then removes it after its CSS transition and emits dismiss. */
   #beginDismiss(message, reason) {