stimeo-ui 0.15.0 → 0.16.0

package/dist/controllers/toast_controller.js

@@ -2,6 +2,72 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/toast_controller.ts
 
+// 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/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/safe_timeout.ts
 var TimerRegistry = class {
   /** Live timer ids that have not yet been cleared (or, for timeouts, fired). */
@@ -111,16 +177,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);
@@ -129,20 +199,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);
@@ -156,20 +246,31 @@ 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/template_row.ts
+function cloneTemplateRoot(template) {
+  const root = template.content.firstElementChild;
+  return root instanceof HTMLElement ? root.cloneNode(true) : null;
+}
+
 // src/utils/transition_completion.ts
 function timeMs(value) {
   const trimmed = value.trim();
@@ -218,6 +319,16 @@ var ToastController = class extends Controller {
   #timers = new SafeTimeout();
   /** Per-toast auto-dismiss, held open while the toast is hovered or focused. */
   #dismiss = new PausableTimers();
+  /** Toasts taken on and not let go; a move within the list keeps a toast here. */
+  #taken = /* @__PURE__ */ new Set();
+  /** Applies the `max` limit again once the event that released a hold has run its course. */
+  #reapply = new MicrotaskCoalescer(() => this.#reapplyLimit());
+  /** Toasts the pointer or focus moved into since the limit was last applied again. */
+  #spared = [];
+  /** The next pointer movement, listened for while a hover hold waits on it. */
+  #pointer = new ListenerSet();
+  /** Toasts whose hover hold waits for the next pointer movement to be confirmed. */
+  #awaitingPointer = /* @__PURE__ */ new Set();
   /**
    * Pending one-shot `requestAnimationFrame` handles (the entering→visible flip).
    * Tracked so {@link disconnect} can cancel any that have not fired, preventing a
@@ -226,19 +337,43 @@ var ToastController = class extends Controller {
   #rafHandles = /* @__PURE__ */ new Map();
   /** The stable list that owns delegated listeners for dynamically added items. */
   #delegatedList = null;
+  /** Whether the controller is between `connect()` and `disconnect()`. */
+  #connected = false;
+  /**
+   * The `max` the list was last held to, or `null` before the first time. `connect()`
+   * applies the limit only when `max` is not that one, so a reconnect of the same instance
+   * leaves the list as it was unless `max` changed while it was away.
+   */
+  #appliedMax = null;
+  /**
+   * Stimulus reports every toast the list already holds before this runs, and each is
+   * taken on then with its holds, meeting no limit. The limit is applied here once, over
+   * all of them, unless the list was already held to the current `max`.
+   */
   connect() {
+    this.#connected = true;
+    this.#reapply.activate();
     this.#connectDelegatedEvents();
-    this.enforceMaxLimit();
     for (const item of this.itemTargets) {
       if (!this.#dismiss.tracks(item) && item.dataset.state !== "leaving") {
         this.#startTimer(item);
       }
     }
+    if (!Object.is(this.#appliedMax, this.maxValue)) {
+      this.#appliedMax = this.maxValue;
+      this.#enforceMax();
+    }
   }
   disconnect() {
+    this.#connected = false;
     this.#disconnectDelegatedEvents();
     this.#timers.clearAll();
     this.#dismiss.clearAll();
+    this.#taken.clear();
+    this.#reapply.cancel();
+    this.#spared = [];
+    this.#pointer.dispose();
+    this.#awaitingPointer.clear();
     for (const handle of this.#rafHandles.values()) {
       window.cancelAnimationFrame(handle);
     }
@@ -256,24 +391,37 @@ var ToastController = class extends Controller {
     for (const item of this.itemTargets) {
       if (item.dataset.state === "leaving") continue;
       if (this.durationValue <= 0) {
-        this.#dismiss.clear(item);
+        this.#dismiss.disarm(item);
         item.removeAttribute("data-paused");
       } else {
         this.#startTimer(item);
       }
     }
   }
+  /**
+   * Holds the list to a changed `max`. 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.enforceMaxLimit();
   }
   /**
    * Stimulus lifecycle callback triggered automatically when a new item target
-   * enters the DOM, from a client-side injection or a Turbo Stream append alike. An
-   * item already leaving, or parented outside `list`, is skipped.
+   * enters the DOM, from a client-side injection or a Turbo Stream append alike, and for
+   * every toast the list already holds ahead of `connect()`. An item already leaving,
+   * parented outside `list`, or already taken on (a move within the list) is skipped; any
+   * other is taken on with the holds it already has. On a connected controller the `max`
+   * limit is then applied, never to the arrival itself; the toasts reported ahead of
+   * `connect()` are left to it.
    */
   itemTargetConnected(element) {
-    this.enforceMaxLimit();
+    if (this.#taken.has(element)) return;
     if (element.dataset.state === "leaving" || element.parentNode !== this.listTarget) return;
+    this.#taken.add(element);
+    this.#readHolds(element);
     this.#startTimer(element);
     element.setAttribute("data-state", "entering");
     this.#cancelAnimation(element);
@@ -283,10 +431,23 @@ var ToastController = class extends Controller {
       element.setAttribute("data-state", "visible");
     });
     this.#rafHandles.set(element, handle);
+    if (this.#connected) this.#enforceMax([element]);
   }
-  /** Clears any active timer when a toast is removed from the DOM. */
+  /**
+   * Lets go of a toast that left the list or stopped being an item: its timer, holds,
+   * `data-paused` and pending frame. After a move within the list the node is already
+   * back, still an item, when Stimulus reports it, so it keeps all of those, and only the
+   * holds the move may have ended are read again.
+   */
   itemTargetDisconnected(element) {
-    this.#dismiss.clear(element);
+    const moved = this.#isShown(element) && element.matches(targetSelector(this.identifier, "item"));
+    if (moved) {
+      this.#afterMove(element);
+      return;
+    }
+    this.#taken.delete(element);
+    element.removeAttribute("data-paused");
+    this.#letGo(element);
     this.#cancelAnimation(element);
   }
   /**
@@ -295,24 +456,31 @@ var ToastController = class extends Controller {
    * (remote / Turbo trigger); the action param wins when both are present.
    *
    *   <button data-action="click->stimeo--toast#show"
-   *           data-stimeo--toast-body-param="Saved"
+   *           data-stimeo--toast-message-param="Saved"
    *           data-stimeo--toast-type-param="status">Show</button>
    *
-   *   element.dispatchEvent(new CustomEvent("show", { detail: { body, type } }))
+   *   element.dispatchEvent(new CustomEvent("show", { detail: { message, type } }))
    *
-   * Clones the template slot, interpolates the body text, and appends to the list.
+   * Clones the template slot, interpolates the message, and appends to the list.
+   * `message` is the wording key the rest of the library dispatches under, so a
+   * part that already carries its own wording — `stimeo--clipboard:copy`,
+   * `stimeo--auto-submit:done` — wires straight into this action.
    */
   show(event) {
     if (!this.hasTemplateTarget || !this.hasListTarget) return;
-    const body = this.#readField(event, "body");
-    if (!body) return;
-    const clone = this.templateTarget.content.cloneNode(true);
-    const item = clone.querySelector("[data-stimeo--toast-target='item']");
-    if (!item) return;
-    const bodySlot = item.querySelector("[data-toast-slot='body']");
-    if (!bodySlot) return;
-    bodySlot.textContent = body;
-    bodySlot.setAttribute("role", this.#readField(event, "type") === "alert" ? "alert" : "status");
+    const message = this.#readField(event, "message");
+    if (!message) return;
+    const template = this.templateTarget;
+    const item = cloneTemplateRoot(template);
+    if (template.content.children.length !== 1) return;
+    if (!item?.matches(targetSelector(this.identifier, "item"))) return;
+    const messageSlot = item.querySelector("[data-toast-slot='message']");
+    if (!messageSlot) return;
+    messageSlot.textContent = message;
+    messageSlot.setAttribute(
+      "role",
+      this.#readField(event, "type") === "alert" ? "alert" : "status"
+    );
     this.listTarget.appendChild(item);
     this.dispatch("show", { detail: { item } });
   }
@@ -354,7 +522,9 @@ var ToastController = class extends Controller {
    * Hover and focus are tracked as independent reasons: the timer is only
    * snapshotted on the first active reason, and only resumed once *every*
    * reason has been released (see {@link resume}). This keeps a toast paused
-   * while it is still hovered *or* focused, per WCAG 2.2.1.
+   * while it is still hovered *or* focused, per WCAG 2.2.1. The hold is recorded
+   * whether or not a timer runs, so the `max` limit passes over the toast either
+   * way; `data-paused` marks a timer that stopped, and only that.
    */
   pause(event) {
     const item = this.#itemFromEvent(event);
@@ -362,38 +532,129 @@ var ToastController = class extends Controller {
       item.setAttribute("data-paused", "true");
     }
   }
-  /** Resumes the auto-dismiss timer once both hover and focus have been released. */
+  /**
+   * Resumes the auto-dismiss timer once both hover and focus have been released,
+   * and then applies the `max` limit again, sparing the toast the pointer or focus is
+   * moving into: its own hold only arrives after this event.
+   */
   resume(event) {
     const item = this.#itemFromEvent(event);
-    if (item && this.#dismiss.resume(item, this.#pauseReason(event))) {
-      item.removeAttribute("data-paused");
+    if (item) {
+      this.#release(
+        item,
+        this.#pauseReason(event),
+        ownerOf(this.itemTargets, event.relatedTarget)
+      );
     }
   }
+  /** Releases one reason on `item`; releasing the last one applies the limit again. */
+  #release(item, reason, spare) {
+    const held = this.#dismiss.isHeld(item);
+    if (this.#dismiss.resume(item, reason)) item.removeAttribute("data-paused");
+    if (held && !this.#dismiss.isHeld(item)) this.#limitLater(spare);
+  }
+  /**
+   * Applies the limit 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 taking the toast away inside that event would pull
+   * the node from under the caller's own call.
+   */
+  #limitLater(spare) {
+    if (spare) this.#spared.push(spare);
+    this.#reapply.schedule();
+  }
+  /** Applies the limit again, sparing every toast gathered since the last pass. */
+  #reapplyLimit() {
+    const spared = this.#spared;
+    this.#spared = [];
+    this.#enforceMax(spared);
+  }
+  /**
+   * Reads the holds of a toast that moved within the list. 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 `mouseout` reaches a moved node, and
+   * `:hover` can answer from before the move. A toast still held waits for that movement.
+   */
+  #afterMove(item) {
+    if (!item.contains(document.activeElement)) this.#release(item, "focus", null);
+    if (this.#dismiss.isHeld(item)) this.#awaitPointer(item);
+  }
+  /**
+   * Takes the holds a toast already has as it is taken on: focus inside it, and the pointer
+   * over it by `:hover`. That answer can date from before the toast came here, so a hover
+   * hold taken on it waits for the next pointer movement to be confirmed.
+   */
+  #readHolds(item) {
+    if (item.contains(document.activeElement)) this.#dismiss.pause(item, "focus");
+    if (!item.matches(":hover")) return;
+    this.#dismiss.pause(item, "hover");
+    this.#awaitPointer(item);
+  }
+  /** Leaves `item`'s hover hold to be confirmed or let go on the next pointer movement. */
+  #awaitPointer(item) {
+    this.#awaitingPointer.add(item);
+    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 toast the pointer is not over. Listens once.
+   */
+  #onPointerMove = () => {
+    this.#pointer.dispose();
+    const waiting = [...this.#awaitingPointer];
+    this.#awaitingPointer.clear();
+    for (const item of waiting) {
+      if (!item.matches(":hover")) this.#release(item, "hover", null);
+    }
+  };
+  /**
+   * Drops a toast's timer and holds as it leaves, and stops waiting on the pointer for it.
+   * A toast something still held counts as released: the limit is applied again.
+   */
+  #letGo(item) {
+    if (this.#dismiss.isHeld(item)) this.#limitLater(null);
+    this.#dismiss.clear(item);
+    this.#awaitingPointer.delete(item);
+    if (this.#awaitingPointer.size === 0) this.#pointer.dispose();
+  }
   /** Resolves the toast item element a pause/resume event targets. */
   #itemFromEvent(event) {
     const target = event.target instanceof Element ? event.target : event.currentTarget;
     if (!(target instanceof Element) || !this.hasListTarget) return null;
-    const item = target.closest("[data-stimeo--toast-target='item']");
+    const item = target.closest(targetSelector(this.identifier, "item"));
     return item && this.listTarget.contains(item) ? item : null;
   }
   /** Classifies a pause/resume event as a hover or focus reason. */
   #pauseReason(event) {
     return event.type === "focusin" || event.type === "focusout" ? "focus" : "hover";
   }
-  /** Arms a toast's auto-dismiss; a non-positive `duration` means it never expires. */
+  /**
+   * Arms a toast's auto-dismiss; a non-positive `duration` means it never expires.
+   * On a toast hover or focus already holds, the timer waits for the release.
+   * `data-paused` is written from that state, so a mark the toast carried in with it,
+   * from a restored page, does not outlive it.
+   *
+   * @stimeoRuntimeOnly `duration` is the delay of the one dismissal timer this call arms.
+   */
   #startTimer(element) {
-    if (this.durationValue <= 0 || element.dataset.state === "leaving" || element.parentNode !== this.listTarget) {
-      return;
+    if (element.dataset.state === "leaving" || element.parentNode !== this.listTarget) return;
+    const armed = this.durationValue > 0;
+    if (armed) {
+      this.#dismiss.set(
+        element,
+        () => this.#removeWithTransition(element, "timeout"),
+        this.durationValue
+      );
     }
-    this.#dismiss.set(
-      element,
-      () => this.#removeWithTransition(element, "timeout"),
-      this.durationValue
-    );
+    if (armed && this.#dismiss.isHeld(element)) element.setAttribute("data-paused", "true");
+    else element.removeAttribute("data-paused");
   }
   #removeWithTransition(element, reason) {
     if (element.dataset.state === "leaving" || element.parentNode !== this.listTarget) return;
-    this.#dismiss.clear(element);
+    this.#letGo(element);
     this.#cancelAnimation(element);
     element.setAttribute("data-state", "leaving");
     const finalize = () => {
@@ -409,24 +670,46 @@ var ToastController = class extends Controller {
     }
   }
   /**
-   * Removes the oldest toasts when the list exceeds `maxValue`.
+   * Removes the oldest toasts while the list shows more than `maxValue`, passing
+   * over every toast hover or focus holds.
    *
    * Public (not `#private`) as a deterministic seam: enforcement normally runs
-   * from `itemTargetConnected`, a Stimulus callback delivered through a
-   * MutationObserver, which a DOM-only environment does not reliably fire — so
-   * it can also be invoked directly. It is not a user-wired action.
+   * as each toast is taken on in `itemTargetConnected`, a Stimulus callback delivered
+   * through a MutationObserver, which a DOM-only environment does not reliably fire —
+   * so it can also be invoked directly. It counts only the toasts taken on. It is not a
+   * user-wired action.
    */
   enforceMaxLimit() {
-    const currentItems = this.itemTargets;
-    const max = Math.max(0, this.maxValue);
-    if (currentItems.length > max) {
-      const excessCount = currentItems.length - max;
-      for (let i = 0; i < excessCount; i++) {
-        const oldest = currentItems[i];
-        if (oldest) this.#removeWithTransition(oldest, "timeout");
+    this.#enforceMax();
+  }
+  /**
+   * Removes the oldest toasts with reason `limit` while the list shows more than `max`
+   * (`0` or less, or not a finite number, means no limit), passing over every toast hover
+   * or focus holds and those in `spared` — the toast just taken on, or the ones the
+   * pointer or focus moved into. Only toasts taken on count or go, so one Stimulus has
+   * yet to report is neither; a toast already leaving does not count. With nothing else
+   * left to go the list stays over the limit. The count is read again on every step,
+   * because a `dismiss` listener may already have changed it.
+   *
+   * @stimeoRenderRoot
+   */
+  #enforceMax(spared = []) {
+    if (!Number.isFinite(this.maxValue) || this.maxValue <= 0) return;
+    for (const item of this.itemTargets) {
+      if (this.#shownCount() <= this.maxValue) return;
+      if (this.#isShown(item) && !spared.includes(item) && !this.#dismiss.isHeld(item)) {
+        this.#removeWithTransition(item, "limit");
       }
     }
   }
+  /** How many toasts the list shows: the ones taken on that are still shown. */
+  #shownCount() {
+    return this.itemTargets.filter((item) => this.#isShown(item)).length;
+  }
+  /** Whether the list shows `item`: a toast taken on, a child of `list`, not leaving. */
+  #isShown(item) {
+    return this.#taken.has(item) && this.hasListTarget && item.parentNode === this.listTarget && item.dataset.state !== "leaving";
+  }
   /** Wires stable-container delegation so newly appended items work immediately. */
   #connectDelegatedEvents(list = this.hasListTarget ? this.listTarget : null) {
     this.#disconnectDelegatedEvents();