stimeo-ui 0.16.0 → 0.17.0

package/dist/controllers/announcer_controller.js

@@ -1,73 +1,62 @@
 import { Controller } from '@hotwired/stimulus';
 
-// src/controllers/announcer_controller.ts
-
-// src/utils/before_cache_reset.ts
-var BeforeCacheReset = class _BeforeCacheReset {
-  /** Every subscribed instance, iterated by the one shared document listener. */
-  static #subscribers = /* @__PURE__ */ new Set();
-  /** The shared listener; installed while at least one instance is subscribed. */
-  static #onBeforeCache = () => {
-    for (const subscriber of _BeforeCacheReset.#subscribers) subscriber.#rewind();
-  };
-  #rewind;
-  /** @param rewind - the pass that returns this controller's state to its initial form. */
-  constructor(rewind) {
-    this.#rewind = rewind;
-  }
-  /** Subscribes to `turbo:before-cache`; call from `connect()`. Idempotent. */
-  activate() {
-    const first = _BeforeCacheReset.#subscribers.size === 0;
-    _BeforeCacheReset.#subscribers.add(this);
-    if (first) {
-      document.addEventListener("turbo:before-cache", _BeforeCacheReset.#onBeforeCache);
+var DetachGate = class _DetachGate {
+  #pending = false;
+  get pending() {
+    return this.#pending;
+  }
+  static isDetached(host) {
+    return !host.element.isConnected || !_DetachGate.#listed(host);
+  }
+  disconnected(host, teardown) {
+    const carried = _DetachGate.#carried(host);
+    if (!carried && _DetachGate.isDetached(host)) {
+      this.#pending = false;
+      teardown();
+      return;
     }
+    this.#pending = true;
+    const probe = () => {
+      if (!this.#pending) return;
+      this.#pending = false;
+      teardown();
+    };
+    if (carried) setTimeout(probe, 0);
+    else queueMicrotask(probe);
+  }
+  static #carried(host) {
+    const element = host.element;
+    return !element.isConnected && element.closest("[data-turbo-permanent]") !== null && _DetachGate.#listed(host);
+  }
+  static #listed(host) {
+    const tokens = (host.element.getAttribute("data-controller") ?? "").split(/\s+/);
+    return tokens.includes(host.identifier);
   }
-  /** Unsubscribes; call from `disconnect()`. Safe when never subscribed. */
-  deactivate() {
-    _BeforeCacheReset.#subscribers.delete(this);
-    if (_BeforeCacheReset.#subscribers.size > 0) return;
-    document.removeEventListener("turbo:before-cache", _BeforeCacheReset.#onBeforeCache);
+  cancel() {
+    this.#pending = false;
   }
 };
 
-// src/utils/safe_timeout.ts
+var MAX_TIMER_DELAY_MS = 2147483647;
+
 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);
@@ -84,16 +73,9 @@ 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(() => {
@@ -102,52 +84,35 @@ var KeyedTimers = class {
     }, 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;
@@ -160,49 +125,81 @@ var MicrotaskCoalescer = class {
   }
 };
 
-// src/controllers/announcer_controller.ts
+var NUMBER_BOUNDS = {
+  timer: { finite: true, min: 0, max: MAX_TIMER_DELAY_MS }};
+function matchesNumberBounds(value, bounds) {
+  if (!Number.isFinite(value)) {
+    const direction = value === Infinity ? "positive" : value === -Infinity ? "negative" : null;
+    if (direction === null) return false;
+    if (bounds.allowInfinity !== "both" && bounds.allowInfinity !== direction) return false;
+  }
+  if (bounds.min !== void 0 && value < bounds.min) return false;
+  if (bounds.max !== void 0 && value > bounds.max) return false;
+  if (bounds.exclusiveMin !== void 0 && value <= bounds.exclusiveMin) return false;
+  if (bounds.integer && !Number.isInteger(value)) return false;
+  if (bounds.allowedValues !== void 0 && !bounds.allowedValues.includes(value)) return false;
+  return true;
+}
+
+function readNumber(raw, fallback, bounds) {
+  return matchesNumberBounds(raw, bounds) ? raw : fallback;
+}
+
+var NumberValueReader = class {
+  #lastRejected = /* @__PURE__ */ new Map();
+  read(owner, name, raw, fallback, bounds) {
+    const resolved = readNumber(raw, fallback, bounds);
+    if (matchesNumberBounds(raw, bounds)) {
+      this.#lastRejected.delete(name);
+      return resolved;
+    }
+    const attribute = `data-${owner.identifier}-${name.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)}-value`;
+    const literal = owner.element.getAttribute(attribute);
+    if (literal === null) {
+      this.#lastRejected.delete(name);
+      return resolved;
+    }
+    if (this.#lastRejected.get(name) !== literal) {
+      this.#lastRejected.set(name, literal);
+      console.warn(
+        `Stimeo UI: "${owner.identifier}" has an invalid number Value "${name}" declaration ${JSON.stringify(literal)}; using ${fallback}.`
+      );
+    }
+    return resolved;
+  }
+};
+
 var LEVELS = ["polite", "assertive"];
-var AnnouncerController = class extends Controller {
+var STAND_IN = "stand-in";
+var ANNOUNCED = "announced";
+var AnnouncerController = class _AnnouncerController extends Controller {
+  #numbers = new NumberValueReader();
   static targets = ["polite", "assertive"];
   static values = {
     clearAfter: { type: Number, default: 1e3 },
     dedupeReannounce: { type: Boolean, default: true }
   };
+  static valueConstraints = {
+    clearAfter: NUMBER_BOUNDS.timer
+  };
   static actions = ["announce"];
-  /** 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.
-   */
+  #gate = new DetachGate();
   #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. */
+  get #standIn() {
+    return `data-${this.identifier}-${STAND_IN}`;
+  }
+  get #announced() {
+    return `data-${this.identifier}-${ANNOUNCED}`;
+  }
   #queues = /* @__PURE__ */ new Map();
-  /** Politeness levels whose next drain is already armed. */
   #draining = /* @__PURE__ */ new Set();
-  /** Collapses a batch of target callbacks (and morph removals) into one pass. */
   #reconcile = new MicrotaskCoalescer(() => this.#reconcileRegions());
-  /**
-   * Watches the host's own children for a generated region disappearing. A morph
-   * drops it — the server's HTML never had it — and no target callback reports
-   * that, because a generated region carries no target attribute. `subtree` stays
-   * off so writing a message inside a region does not re-enter this pass.
-   */
   #hostWatch = new MutationObserver(() => {
     this.#reconcile.schedule();
   });
-  /** Rewinds to an announceable initial state for the snapshot; see the remarks. */
-  #beforeCache = new BeforeCacheReset(() => this.#rewindForCache());
-  /**
-   * Guards against handling the same CustomEvent twice. An event dispatched on
-   * the controller element with `bubbles: true` reaches both the element and the
-   * `window` listener; this WeakSet ensures it announces only once.
-   */
   #handled = /* @__PURE__ */ new WeakSet();
-  /** Receives programmatic announcements at the element or bubbled to `window`. */
   #onAnnounceEvent = (event) => {
     if (this.#handled.has(event)) return;
     this.#handled.add(event);
@@ -212,17 +209,23 @@ var AnnouncerController = class extends Controller {
     this.#announce(message, this.#assertiveFromDetail(detail));
   };
   connect() {
+    const moved = this.#gate.pending;
+    this.#gate.cancel();
+    if (moved) return;
     this.#reconcile.activate();
-    this.#beforeCache.activate();
+    this.#dropInheritedStandIns();
+    this.#emptyInheritedMessages();
     this.#reconcileRegions();
     this.#hostWatch.observe(this.element, { childList: true });
     this.element.addEventListener("stimeo--announcer:announce", this.#onAnnounceEvent);
     window.addEventListener("stimeo--announcer:announce", this.#onAnnounceEvent);
   }
   disconnect() {
+    this.#gate.disconnected(this, () => this.#teardown());
+  }
+  #teardown() {
     this.#reconcile.cancel();
     this.#hostWatch.disconnect();
-    this.#beforeCache.deactivate();
     this.element.removeEventListener("stimeo--announcer:announce", this.#onAnnounceEvent);
     window.removeEventListener("stimeo--announcer:announce", this.#onAnnounceEvent);
     this.#timers.clearAll();
@@ -231,39 +234,23 @@ var AnnouncerController = class extends Controller {
     this.#draining.clear();
     this.#removeGenerated();
   }
-  /** Retires the stand-in once the consumer supplies a polite region. */
   politeTargetConnected() {
     this.#reconcile.schedule();
   }
-  /** Materialises a stand-in once the consumer's polite region goes away. */
   politeTargetDisconnected() {
     this.#reconcile.schedule();
   }
-  /** Retires the stand-in once the consumer supplies an assertive region. */
   assertiveTargetConnected() {
     this.#reconcile.schedule();
   }
-  /** Materialises a stand-in once the consumer's assertive region goes away. */
   assertiveTargetDisconnected() {
     this.#reconcile.schedule();
   }
-  /**
-   * Brings the region set back to exactly one region per politeness and reports
-   * whether anything had to be created.
-   *
-   * A region created here is not written to in the same task: assistive tech
-   * reports changes to regions it already knows about, so {@link drain} waits a
-   * task whenever this says a region is new.
-   */
   #reconcileRegions() {
     let created = false;
     for (const level of LEVELS) {
       if (this.#hasTargetFor(level)) {
-        const generated = this.#generated.get(level);
-        if (generated) {
-          generated.remove();
-          this.#generated.delete(level);
-        }
+        this.#generated.get(level)?.remove();
         continue;
       }
       const existing = this.#generated.get(level);
@@ -273,38 +260,33 @@ var AnnouncerController = class extends Controller {
     }
     return created;
   }
-  /** Whether the consumer supplied a target for `level`. */
   #hasTargetFor(level) {
     return level === "assertive" ? this.hasAssertiveTarget : this.hasPoliteTarget;
   }
-  /** Builds a visually hidden live region for `level` and attaches it. */
   #createRegion(level) {
     const region = document.createElement("div");
     region.setAttribute("aria-live", level);
     region.setAttribute("aria-atomic", "true");
+    region.setAttribute(this.#standIn, "");
     visuallyHide(region);
     this.element.appendChild(region);
     return region;
   }
-  /**
-   * Removes and forgets every region this controller generated. Authored targets
-   * belong to the consumer and are left untouched. Forgetting them is what keeps
-   * the live page working after a snapshot rewind: the next announcement finds an
-   * empty map and materialises a fresh region.
-   */
-  #removeGenerated() {
-    for (const region of this.#generated.values()) {
-      region.remove();
+  #dropInheritedStandIns() {
+    for (const child of Array.from(this.element.children)) {
+      if (child.hasAttribute(this.#standIn)) child.remove();
+    }
+  }
+  #emptyInheritedMessages() {
+    for (const region of [...this.politeTargets, ...this.assertiveTargets]) {
+      if (!region.hasAttribute(this.#announced)) continue;
+      region.replaceChildren();
+      region.removeAttribute(this.#announced);
     }
-    this.#generated.clear();
-  }
-  /**
-   * Announces a message. Reads the text from a Stimulus action param
-   * (`message`, plus optional `assertive`) for attribute-only triggers, falling
-   * back to a CustomEvent `detail` when the same handler is wired to an event.
-   * An empty/non-string message is ignored so untrusted payloads cannot blank
-   * the region.
-   */
+  }
+  #removeGenerated() {
+    for (const region of this.#generated.values()) region.remove();
+  }
   announce(event) {
     const params = event.params;
     const fromParam = params?.message;
@@ -313,13 +295,6 @@ var AnnouncerController = class extends Controller {
     const assertive = params?.assertive === true || this.#assertiveFromDetail(event.detail);
     this.#announce(message, assertive);
   }
-  /**
-   * Queues `message` for its politeness and arms the drain.
-   *
-   * Queuing is what makes a burst audible: assistive tech announces the changes it
-   * observes, so several messages written into one region within a single task are
-   * one change and only the last is read.
-   */
   #announce(message, assertive) {
     const level = assertive ? "assertive" : "polite";
     const queue = this.#queues.get(level);
@@ -330,7 +305,6 @@ var AnnouncerController = class extends Controller {
     }
     this.#scheduleDrain(level);
   }
-  /** Arms one drain pass for `level`; further messages ride the pass already armed. */
   #scheduleDrain(level) {
     if (this.#draining.has(level)) return;
     this.#draining.add(level);
@@ -339,28 +313,17 @@ var AnnouncerController = class extends Controller {
       this.#drain(level);
     }, 0);
   }
-  /**
-   * Writes one queued message, then arms the next pass while the queue holds more.
-   *
-   * Two steps take a whole pass without consuming the message: materialising a
-   * 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);
     const message = queue?.[0];
     if (queue === void 0 || message === void 0) return;
-    if (this.#reconcileRegions()) {
+    const created = this.#reconcileRegions();
+    const region = this.#regionFor(level);
+    if (created || region === void 0) {
       this.#scheduleDrain(level);
       return;
     }
-    const region = this.#regionFor(level);
     if (this.dedupeReannounceValue && region.textContent === message) {
-      this.#regionTimers.clear(region);
       region.textContent = "";
       this.#scheduleDrain(level);
       return;
@@ -368,60 +331,27 @@ var AnnouncerController = class extends Controller {
     queue.shift();
     this.#regionTimers.clear(region);
     region.textContent = message;
+    region.setAttribute(this.#announced, "");
     this.#scheduleClear(region, message);
     if (queue.length > 0) this.#scheduleDrain(level);
   }
-  /**
-   * 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;
+    if (this.#safeClearAfter <= 0) return;
     this.#regionTimers.set(
       region,
       () => {
-        if (region.textContent === message) region.textContent = "";
+        if (region.textContent !== message) return;
+        region.textContent = "";
+        region.removeAttribute(this.#announced);
       },
-      this.clearAfterValue
+      this.#safeClearAfter
     );
   }
-  /**
-   * Resolves the live region for a politeness level.
-   *
-   * The remembered stand-in is used only while it is still in the document: a morph
-   * can drop it, and writing into the detached node would announce nothing at all.
-   */
   #regionFor(level) {
     if (level === "assertive" && this.hasAssertiveTarget) return this.assertiveTarget;
     if (level === "polite" && this.hasPoliteTarget) return this.politeTarget;
-    const existing = this.#generated.get(level);
-    if (existing?.isConnected) return existing;
-    const region = this.#createRegion(level);
-    this.#generated.set(level, region);
-    return region;
+    return this.#generated.get(level);
   }
-  /**
-   * Restores the announceable initial state for the snapshot Turbo is about to
-   * take: queued and displayed messages go, generated regions go, and the live
-   * page — which keeps running when a visit is aborted — gets its regions back on
-   * the next task, after the clone.
-   */
-  #rewindForCache() {
-    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;
-        target.textContent = "";
-      }
-    }
-    this.#removeGenerated();
-    this.#timers.set(() => this.#reconcileRegions(), 0);
-  }
-  /** Extracts a non-empty string `message` from a CustomEvent detail, else null. */
   #messageFromDetail(detail) {
     if (detail && typeof detail === "object" && "message" in detail) {
       const value = detail.message;
@@ -429,10 +359,18 @@ var AnnouncerController = class extends Controller {
     }
     return null;
   }
-  /** Reads an `assertive === true` flag from a CustomEvent detail (default polite). */
   #assertiveFromDetail(detail) {
     return !!detail && typeof detail === "object" && detail.assertive === true;
   }
+  get #safeClearAfter() {
+    return this.#numbers.read(
+      this,
+      "clearAfter",
+      this.clearAfterValue,
+      _AnnouncerController.values.clearAfter.default,
+      _AnnouncerController.valueConstraints.clearAfter
+    );
+  }
 };
 function visuallyHide(node) {
   const { style } = node;
@@ -449,5 +387,4 @@ function visuallyHide(node) {
 }
 
 export { AnnouncerController, visuallyHide };
-//# sourceMappingURL=announcer_controller.js.map
 //# sourceMappingURL=announcer_controller.js.map