stimeo-ui 0.14.0 → 0.16.0

data/dist/controllers/announcer_controller.js

@@ -31,39 +31,6 @@ var BeforeCacheReset = class _BeforeCacheReset {
   }
 };
 
-// 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). */
@@ -117,6 +84,82 @@ var SafeTimeout = class extends TimerRegistry {
   }
 };
 
+// src/utils/keyed_timers.ts
+var KeyedTimers = class {
+  #timers = new SafeTimeout();
+  /** The pending timer of each key; an entry lives exactly as long as its timer. */
+  #pending = /* @__PURE__ */ new Map();
+  /**
+   * Arms `callback` after `delay` ms for `key`, cancelling the timer `key` had
+   * pending. The entry is dropped before the callback runs, so the callback sees
+   * the key unarmed and may arm it again for the next round.
+   */
+  set(key, callback, delay) {
+    this.clear(key);
+    const id = this.#timers.set(() => {
+      this.#pending.delete(key);
+      callback();
+    }, delay);
+    this.#pending.set(key, id);
+  }
+  /**
+   * Cancels `key`'s pending timer, if it has one.
+   *
+   * A timer id is a positive integer, so `-1` stands for "nothing pending" and
+   * the registry ignores an id it does not own — the unarmed case needs no
+   * branch of its own, and no other key's timer can be reached from here.
+   */
+  clear(key) {
+    this.#timers.clear(this.#pending.get(key) ?? -1);
+    this.#pending.delete(key);
+  }
+  /**
+   * Cancels every pending timer and forgets every key. Call this from a
+   * controller's `disconnect()` so no timer, and no entry, outlives the element.
+   */
+  clearAll() {
+    this.#timers.clearAll();
+    this.#pending.clear();
+  }
+  /** Whether `key` has a timer pending. */
+  has(key) {
+    return this.#pending.has(key);
+  }
+};
+
+// 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/controllers/announcer_controller.ts
 var LEVELS = ["polite", "assertive"];
 var AnnouncerController = class extends Controller {
@@ -126,8 +169,14 @@ var AnnouncerController = class extends Controller {
     dedupeReannounce: { type: Boolean, default: true }
   };
   static actions = ["announce"];
-  /** Clear/re-announce timers; one `clearAll()` in disconnect tears them all down. */
+  /** Drain timers, which belong to a politeness level rather than to a region. */
   #timers = new SafeTimeout();
+  /**
+   * The one timer a region may have outstanding — its dedupe re-set, then its
+   * auto-clear. A region carries at most one, and the registry releases the
+   * previous one whenever a newer message takes the region over.
+   */
+  #regionTimers = new KeyedTimers();
   /** Live regions generated to stand in for absent targets, for teardown. */
   #generated = /* @__PURE__ */ new Map();
   /** Messages waiting to be written, oldest first, one queue per politeness. */
@@ -147,13 +196,6 @@ var AnnouncerController = class extends Controller {
   });
   /** Rewinds to an announceable initial state for the snapshot; see the remarks. */
   #beforeCache = new BeforeCacheReset(() => this.#rewindForCache());
-  /**
-   * The one timer a region may have outstanding — its dedupe re-set, then its
-   * auto-clear. Held weakly so a swapped-out target is not retained; a leftover
-   * id is harmless because {@link SafeTimeout.clear} no-ops on an id it does not
-   * own.
-   */
-  #pending = /* @__PURE__ */ new WeakMap();
   /**
    * Guards against handling the same CustomEvent twice. An event dispatched on
    * the controller element with `bubbles: true` reaches both the element and the
@@ -184,6 +226,7 @@ var AnnouncerController = class extends Controller {
     this.element.removeEventListener("stimeo--announcer:announce", this.#onAnnounceEvent);
     window.removeEventListener("stimeo--announcer:announce", this.#onAnnounceEvent);
     this.#timers.clearAll();
+    this.#regionTimers.clearAll();
     this.#queues.clear();
     this.#draining.clear();
     this.#removeGenerated();
@@ -303,6 +346,9 @@ var AnnouncerController = class extends Controller {
    * region (it has to be in the accessibility tree before the text arrives) and
    * emptying a region that already holds this exact text (an unchanged node is not
    * re-read, so `dedupeReannounce` clears first and writes on the following pass).
+   *
+   * @stimeoRuntimeOnly `dedupeReannounce` decides whether one queued message is spoken again; the
+   *   region's text is the message itself.
    */
   #drain(level) {
     const queue = this.#queues.get(level);
@@ -314,21 +360,25 @@ var AnnouncerController = class extends Controller {
     }
     const region = this.#regionFor(level);
     if (this.dedupeReannounceValue && region.textContent === message) {
-      this.#cancelPending(region);
+      this.#regionTimers.clear(region);
       region.textContent = "";
       this.#scheduleDrain(level);
       return;
     }
     queue.shift();
-    this.#cancelPending(region);
+    this.#regionTimers.clear(region);
     region.textContent = message;
     this.#scheduleClear(region, message);
     if (queue.length > 0) this.#scheduleDrain(level);
   }
-  /** Clears the region after `clearAfter` ms, unless a newer message replaced it. */
+  /**
+   * Clears the region after `clearAfter` ms, unless a newer message replaced it.
+   *
+   * @stimeoRuntimeOnly `clearAfter` is the delay of the one clearing timer this call arms.
+   */
   #scheduleClear(region, message) {
     if (this.clearAfterValue <= 0) return;
-    this.#schedule(
+    this.#regionTimers.set(
       region,
       () => {
         if (region.textContent === message) region.textContent = "";
@@ -336,23 +386,6 @@ var AnnouncerController = class extends Controller {
       this.clearAfterValue
     );
   }
-  /**
-   * Arms `region`'s single pending timer. Callers reach here with the slot
-   * already free — `#drain` releases it before writing, and a fired timer clears its own
-   * entry below — so this does not cancel again.
-   */
-  #schedule(region, callback, delay) {
-    const id = this.#timers.set(() => {
-      this.#pending.delete(region);
-      callback();
-    }, delay);
-    this.#pending.set(region, id);
-  }
-  /** Releases `region`'s pending timer, if it has one. */
-  #cancelPending(region) {
-    this.#timers.clear(this.#pending.get(region) ?? -1);
-    this.#pending.delete(region);
-  }
   /**
    * Resolves the live region for a politeness level.
    *
@@ -378,6 +411,7 @@ var AnnouncerController = class extends Controller {
     this.#queues.clear();
     this.#draining.clear();
     this.#timers.clearAll();
+    this.#regionTimers.clearAll();
     for (const level of LEVELS) {
       if (this.#hasTargetFor(level)) {
         const target = level === "assertive" ? this.assertiveTarget : this.politeTarget;

data/dist/controllers/auto_submit_controller.js

@@ -2,6 +2,17 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/auto_submit_controller.ts
 
+// src/utils/announce.ts
+function announce(message, options = {}) {
+  const text = message.trim();
+  if (text.length === 0) return;
+  window.dispatchEvent(
+    new CustomEvent("stimeo--announcer:announce", {
+      detail: { message: text, assertive: options.assertive === true }
+    })
+  );
+}
+
 // src/utils/before_cache_reset.ts
 var BeforeCacheReset = class _BeforeCacheReset {
   /** Every subscribed instance, iterated by the one shared document listener. */
@@ -32,11 +43,19 @@ var BeforeCacheReset = class _BeforeCacheReset {
 };
 
 // src/utils/composition_tracker.ts
+var COMPOSITION_INPUT_TYPES = /* @__PURE__ */ new Set([
+  "insertCompositionText",
+  "insertFromComposition",
+  "deleteCompositionText",
+  "deleteByComposition"
+]);
 var CompositionTracker = class {
   #observedTargets = /* @__PURE__ */ new Set();
   #activeTargets = /* @__PURE__ */ new Set();
   #onStart;
   #onEnd;
+  /** The field whose confirming `input` is still owed, while the window is open. */
+  #confirmedTarget = null;
   constructor(options = {}) {
     this.#onStart = options.onStart;
     this.#onEnd = options.onEnd;
@@ -46,6 +65,7 @@ var CompositionTracker = class {
     if (this.#observedTargets.has(target)) return;
     target.addEventListener("compositionstart", this.#handleStart);
     target.addEventListener("compositionend", this.#handleEnd);
+    target.addEventListener("keydown", this.#handleKeydown);
     this.#observedTargets.add(target);
   }
   /** Stops tracking one target and clears any active composition it owned. */
@@ -53,29 +73,76 @@ var CompositionTracker = class {
     if (!this.#observedTargets.delete(target)) return;
     target.removeEventListener("compositionstart", this.#handleStart);
     target.removeEventListener("compositionend", this.#handleEnd);
+    target.removeEventListener("keydown", this.#handleKeydown);
     this.#activeTargets.delete(target);
+    if (this.#confirmedTarget === target) this.#confirmedTarget = null;
   }
   /** Releases every listener and clears state so reconnect starts cleanly. */
   disconnect() {
     for (const target of this.#observedTargets) {
       target.removeEventListener("compositionstart", this.#handleStart);
       target.removeEventListener("compositionend", this.#handleEnd);
+      target.removeEventListener("keydown", this.#handleKeydown);
     }
     this.#observedTargets.clear();
     this.#activeTargets.clear();
+    this.#confirmedTarget = null;
   }
   /** True when lifecycle tracking or the current event reports composition. */
   isComposing(event) {
     return this.#activeTargets.size > 0 || event?.isComposing === true;
   }
+  /**
+   * Whether `event` is the `input` echoing the composition just confirmed.
+   *
+   * Asking closes the window either way, so one confirmation is folded at most
+   * once and a consumer asks once per `input`.
+   */
+  consumesConfirmedInput(event) {
+    const confirmed = this.#confirmedTarget;
+    this.#confirmedTarget = null;
+    if (confirmed === null || confirmed !== event.target) return false;
+    const inputType = event.inputType;
+    return !inputType || COMPOSITION_INPUT_TYPES.has(inputType);
+  }
   #handleStart = (event) => {
+    this.#confirmedTarget = null;
     if (event.currentTarget) this.#activeTargets.add(event.currentTarget);
     this.#onStart?.(event);
   };
   #handleEnd = (event) => {
     if (event.currentTarget) this.#activeTargets.delete(event.currentTarget);
+    this.#confirmedTarget = event.target;
     this.#onEnd?.(event);
   };
+  /** A key on an observed field opens an edit of its own, so no echo is owed. */
+  #handleKeydown = () => {
+    this.#confirmedTarget = 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/safe_timeout.ts
@@ -146,18 +213,23 @@ var AutoSubmitController = class extends Controller {
   #timers = new SafeTimeout();
   /** Id of the pending debounce timer, so a new keystroke can reset it. */
   #pendingId = 0;
+  /** Listeners that live with the bound form rather than with the connection. */
+  #formListeners = new ListenerSet();
   /** The form the listeners are attached to; target callbacks rebind it. */
   #boundForm = null;
   /** Rewinds the transient state hooks just before Turbo snapshots the page. */
   #beforeCache = new BeforeCacheReset(() => this.#rewindForCache());
-  /** Clears `aria-busy` and emits completion once Turbo finishes the submit. */
+  /**
+   * Clears `aria-busy` and emits completion once Turbo finishes the submit.
+   *
+   * @stimeoRuntimeOnly `message` and `announce` shape the event and the announcement of one
+   *   finished submit; the busy flag it clears does not depend on them.
+   */
   #onSubmitEnd = () => {
     this.#boundForm?.removeAttribute("aria-busy");
     const message = this.messageValue;
     this.dispatch("done", { detail: { message: message || void 0 } });
-    if (this.announceValue && message) {
-      window.dispatchEvent(new CustomEvent("stimeo--announcer:announce", { detail: { message } }));
-    }
+    if (this.announceValue) announce(message);
   };
   /** Owns delegated IME lifecycle state and submits confirmed input text. */
   #composition = new CompositionTracker({
@@ -194,7 +266,11 @@ var AutoSubmitController = class extends Controller {
     if (event.type === "input" && this.#composition.isComposing(event)) return;
     this.#schedule(event.target ?? null);
   }
-  /** Schedules (and coalesces) the debounced submit for the given trigger. */
+  /**
+   * Schedules (and coalesces) the debounced submit for the given trigger.
+   *
+   * @stimeoRuntimeOnly `debounce` is the delay of the one submit timer this call arms.
+   */
   #schedule(trigger) {
     const form = this.#boundForm;
     if (!form) return;
@@ -228,12 +304,12 @@ var AutoSubmitController = class extends Controller {
     if (previous) {
       this.#cancelPending();
       previous.removeAttribute("data-auto-submit-pending");
-      previous.removeEventListener("turbo:submit-end", this.#onSubmitEnd);
+      this.#formListeners.dispose();
       this.#composition.unobserve(previous);
     }
     this.#boundForm = form;
     if (!form) return;
-    form.addEventListener("turbo:submit-end", this.#onSubmitEnd);
+    this.#formListeners.add(form, "turbo:submit-end", this.#onSubmitEnd);
     this.#composition.observe(form);
   }
   /** Resolves the form: the explicit `form` target, else a `<form>` root, else null. */

data/dist/controllers/avatar_controller.js

@@ -224,7 +224,7 @@ var AvatarController = class extends Controller {
   }
   /** Applies Value precedence and returns the effective raw `src` attribute. */
   #applySource(image) {
-    if (!this.element.hasAttribute("data-stimeo--avatar-src-value")) {
+    if (!this.element.hasAttribute(`data-${this.identifier}-src-value`)) {
       this.#src.return(image);
       return image.getAttribute("src");
     }

data/dist/controllers/breadcrumb_controller.js

@@ -63,10 +63,15 @@ var LayoutObserver = class {
   #resizeObserverFactory;
   #resizeObserver = null;
   #observingViewport = false;
+  #loadContainer = null;
   /** Stable bound handler so add/removeEventListener target the same reference. */
   #handleViewportResize = () => {
     this.#callback();
   };
+  /** Stable bound handler for the capture-phase `load`; see {@link observeDescendantLoads}. */
+  #handleDescendantLoad = () => {
+    this.#callback();
+  };
   constructor(callback, options = {}) {
     this.#callback = callback;
     this.#resizeObserverFactory = options.resizeObserverFactory ?? (typeof ResizeObserver === "undefined" ? null : (cb) => new ResizeObserver(cb));
@@ -102,14 +107,35 @@ var LayoutObserver = class {
     window.removeEventListener("resize", this.#handleViewportResize);
   }
   /**
-   * Releases every observation: disconnects the {@link ResizeObserver} and
-   * removes the viewport listener. Safe to call multiple times. Call this from a
-   * controller's `disconnect()`.
+   * Starts reporting a `load` from anywhere inside `container` — an image or a
+   * frame settling changes the box it sits in, and it measures as zero high until
+   * then. `load` does not bubble, so the subscription is a capture-phase listener
+   * on the container itself and nothing the caller spells.
+   *
+   * **One container at a time.** A further call moves the observation, so a widget
+   * whose content element is swapped at runtime releases the element it let go by
+   * naming the new one — there is no second place for the release to drift from.
+   */
+  observeDescendantLoads(container) {
+    this.unobserveDescendantLoads();
+    this.#loadContainer = container;
+    container.addEventListener("load", this.#handleDescendantLoad, true);
+  }
+  /** Stops reporting descendant loads without affecting element or viewport observation. */
+  unobserveDescendantLoads() {
+    this.#loadContainer?.removeEventListener("load", this.#handleDescendantLoad, true);
+    this.#loadContainer = null;
+  }
+  /**
+   * Releases every observation: disconnects the {@link ResizeObserver} and removes
+   * the viewport and descendant-load listeners. Safe to call multiple times. Call
+   * this from a controller's `disconnect()`.
    */
   disconnect() {
     this.#resizeObserver?.disconnect();
     this.#resizeObserver = null;
     this.unobserveViewport();
+    this.unobserveDescendantLoads();
   }
 };
 
@@ -161,21 +187,24 @@ var BreadcrumbController = class extends Controller {
     this.#resync();
   }
   /**
-   * Re-measures when the disclosure set gains or loses a member. The set is a
-   * precondition for collapsing at all, so it needs the same watching the list
-   * and items get: without these callbacks a swap that breaks or completes the
-   * set would only take effect at the next resize or list mutation, which may
-   * never come.
+   * Re-measures when an `ellipsis` target arrives. The `ellipsis` and `trigger`
+   * targets form the disclosure set, a precondition for collapsing at all, so they
+   * need the same watching the list and items get: without their callbacks a swap
+   * that breaks or completes the set would only take effect at the next resize or
+   * list mutation, which may never come.
    */
   ellipsisTargetConnected() {
     this.#resync();
   }
+  /** Re-measures when an `ellipsis` target leaves the disclosure set. */
   ellipsisTargetDisconnected() {
     this.#resync();
   }
+  /** Re-measures when a `trigger` target joins the disclosure set. */
   triggerTargetConnected() {
     this.#resync();
   }
+  /** Re-measures when a `trigger` target leaves the disclosure set. */
   triggerTargetDisconnected() {
     this.#resync();
   }
@@ -184,7 +213,7 @@ var BreadcrumbController = class extends Controller {
    *
    * The marker is the source of truth for what may be collapsed, so an element
    * that loses it while the controller is live is an always-visible item again —
-   * and `#render` only walks the *current* targets, so nothing else would ever
+   * and rendering only walks the *current* targets, so nothing else would ever
    * clear the `hidden` this controller put there.
    *
    * The `#connected` guard is load-bearing, not defensive. Stimulus fires this
@@ -289,8 +318,6 @@ var BreadcrumbController = class extends Controller {
   }
   /**
    * Applies the collapsed/expanded state to the items, ellipsis, and trigger.
-   *
-   * @stimeoRenderRoot
    */
   #render() {
     const collapsed = this.#overflowing && !this.#expanded;

data/dist/controllers/bulk_select_controller.js

@@ -108,12 +108,8 @@ var BulkSelectController = class extends Controller {
   allTargetDisconnected() {
     this.#reconcile.schedule();
   }
-  /** Repaints the count for a total that changed at runtime, rejecting non-finite ones. */
+  /** Repaints the count for a total that changed at runtime. */
   totalCountValueChanged() {
-    if (!Number.isFinite(this.totalCountValue)) {
-      this.totalCountValue = 0;
-      return;
-    }
     this.#reconcile.schedule();
   }
   /** Repaints so wording changed at runtime is used by the next announcement. */
@@ -175,6 +171,11 @@ var BulkSelectController = class extends Controller {
   #announce(detail) {
     announce(fillTemplate(this.announceTextValue, { count: detail.count }));
   }
+  /** The declared `totalCount`, or the default `0` in place of a non-finite one. */
+  get #totalCount() {
+    const declared = this.totalCountValue;
+    return Number.isFinite(declared) ? declared : 0;
+  }
   /**
    * Recomputes the count, the select-all checked/indeterminate state, and the bar
    * visibility from the current DOM. Returns the figures when the emitted count or
@@ -191,7 +192,7 @@ var BulkSelectController = class extends Controller {
       this.allTarget.checked = total > 0 && checked === total;
       this.allTarget.indeterminate = checked > 0 && checked < total;
     }
-    const count = allPages ? this.totalCountValue : checked;
+    const count = allPages ? this.#totalCount : checked;
     const show = allPages || checked > 0;
     if (this.hasBarTarget) {
       if (!show && this.hasAllTarget && this.barTarget.contains(document.activeElement)) {