stimeo-ui 0.10.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9426006a2ca0153a2f91db44ca72beff51851141b42ab82bf64f55a68f853651
-  data.tar.gz: fdbd9afa0e2c79f74a823c69b04f55295626fec0b8315e3fec7ec1f88f0406d8
+  metadata.gz: 7f691ab87c2a0b5092226d8d319ebff3c7b6d8a658b8a62c42017b7dc3e50807
+  data.tar.gz: e2aebaed7d717a580cbd9af42ae6149e7cda083fbbdd3465488525fdac8ee01e
 SHA512:
-  metadata.gz: ac9a8e4008547f68a709b27964c767bae3adf601770a353b6834e58866f6d84ce68f257cb0d5a8e80aa685cbc2a12e4068414f8351952e2d9afeaf1582764d7f
-  data.tar.gz: ac6559ced3a65c78f00b836d8a5f6a6c7aed7dfe50b091b13f537418a32f9e76d5bf00c487faa23d13851670069dd2d7a1bfdb50c67cd17a29fd073c16be86f1
+  metadata.gz: 182402ce77c5e8a010e3c6f2229c8865f339ea20447907f776f7e557a3c52de7aa9b3eada614e9c64c2cb4d3a7850a1a1e5b3724e1f836ed666f6cfadf221787
+  data.tar.gz: 7061380101c2b4c7a1ad996e11ba1a6816ed276ba96944b55e1bd5d5efecefb8ee9607c466604f6ad97b7da990c86c1dbd5376256ef29d8c8c7d39dada7fd50b

data/CHANGELOG.md

@@ -7,6 +7,149 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 While the version is `0.x`, the public API (the `stimeo--*` data attributes) may
 change between releases.
 
+## [0.12.0] - 2026-09-06
+
+Minor release with no new components. Six existing ones are reworked — count-up,
+intersection, lazy-frame, reading-progress, smart-sticky-header, and sortable —
+and the number reading count-up gained reaches live-counter too. Most of them
+changed a contract, so read Removed and Changed before upgrading. The Inspector
+manifest stays on schema v12.
+
+### Removed
+
+- sortable: the `status` target, its `data-grabbed` / `data-moved` /
+  `data-dropped` / `data-canceled` templates, and the English fallback wording.
+  Seat a `stimeo--announcer` on the page and set `announceGrabbedText` /
+  `announceMovedText` / `announceDroppedText` / `announceCanceledText`
+  (`{name}` / `{position}` / `{total}`); an unset one announces nothing.
+  `stimeo check` stops asking for the live region and warns when no announcer
+  is seated.
+
+### Changed
+
+- count-up: only the text node holding the number is animated, and while it
+  ticks it is wrapped in a `role="img"` element named with the authored text —
+  the host's own `aria-label` and `role` are never touched, and sibling markup
+  stays where it was.
+- count-up and live-counter read a formatted number by one rule: the first
+  numeric token, group separators dropped, the fraction truncated, and a hyphen
+  a sign only where it opens the token — `"Sign-ups: 1,200"` reads 1200, not
+  -1200.
+- intersection: `0` is always among the observed lines, so a non-zero
+  `threshold` also reports the element leaving for good (one more `change`;
+  `data-passed` and the ratio property follow the departure to its end), and an
+  exit across the start edge reports `position: "before"` while the element
+  still overlaps the root.
+- lazy-frame: a re-fetch needs a genuine re-entry — the frame is seen inside the
+  observed area, leaves it, and comes back; where a connection or a
+  focus-started load first finds it is the baseline. A frame with `once` off is
+  armed again after a cache restore, and `load` names the URL that was fetched.
+- reading-progress: an article with no layout box is not measured, the
+  article's own box is watched so late-settling content re-measures, and the
+  connect frame is the baseline — a restored scroll position does not fire
+  `complete`. Both faces of the custom property are leased: the element's copy
+  is returned on `disconnect()` too, an authored `:root` declaration comes back,
+  and a later writer is left alone.
+- smart-sticky-header: `change` fires on transitions only (connecting is
+  silent), and the `offset` zone is decided ahead of the jitter guard.
+- sortable: insertion is relative to the neighbouring item — the `list`-less
+  markup works and the last slot is after the last item — and a drag signal from
+  a pointer-drag nested inside an item no longer moves the card. The pickup slot
+  is remembered as neighbours, so rows inserted or removed mid-drag shift neither
+  the restore nor `from`; only laid-out siblings take part in pointer following;
+  and a session whose item leaves the item set ends instead of refusing every
+  later grab. pointer-drag consumes `Home` / `End` while grabbed.
+- A declaration that cannot be read falls back to its default: count-up's
+  `duration` / `from`, smart-sticky-header's `offset`, and a `rootSelector` /
+  `containerSelector` that does not parse (intersection, sticky-observer,
+  smart-sticky-header) observes the viewport or the window. Runtime changes to
+  intersection's `threshold`, lazy-frame's `url` / `rootMargin`, and
+  smart-sticky-header's `offset` are followed.
+
+### Fixed
+
+- lazy-frame: focus moving inside a loaded frame no longer re-fetches it, the
+  first intersection after a focus-started load is not a re-entry, and an empty
+  `url` is never written to `src`.
+- intersection: with `once`, a handler calling `refresh()` from `enter` no longer
+  clears the one-shot marker, so a cache restore does not fire `enter` again.
+- reading-progress: hiding a half-read article no longer publishes `1` and
+  `complete`.
+
+## [0.11.0] - 2026-09-05
+
+Minor release with no new components. Eight existing ones are reworked — the three
+cable controllers (live-counter, presence, typing-indicator) plus pointer-drag,
+portal, preview-guard, roving, and stick-to-bottom. Two of them changed a contract,
+so read Removed before upgrading. The Inspector manifest stays on schema v12.
+
+### Removed
+
+- preview-guard: the `mode` Value. `placeholder` alone decides the guard's form —
+  empty (the default) hides the element with `visibility`, and any other text takes
+  the place of its content.
+- typing-indicator: the live region on the `status` target. It is a plain visible
+  slot now — drop its `aria-live`, seat a `stimeo--announcer` on the page, and set
+  `announceOneText` / `announceManyText`. `stimeo check` stops asking for the
+  live-region semantics too.
+
+### Added
+
+- typing-indicator: `announceOneText` / `announceManyText` (`{name}` / `{names}` /
+  `{count}`), debounced through the shared announcer.
+- pointer-drag: a `reset` action that returns the element to its origin — dropping
+  the committed follow offset and cancelling an in-flight drag.
+
+### Changed
+
+- The cable controllers share one wire subscription per identifier (channel +
+  params), so a second widget on the same stream sends instead of waiting on a
+  confirmation that never comes. A caller joining a confirmed or refused
+  identifier is told so on the next microtask, and the wire is released when the
+  last one leaves.
+- Cable identifier parameters are read by the controller, so an unreadable
+  `params` declaration falls back to the channel alone instead of stopping the
+  subscription from being created at all.
+- An element moved within the page keeps what it was carrying: pointer-drag's
+  session and the attributes it lends its handles, portal's teleport,
+  preview-guard's guard, and roving's tab stop.
+- A declaration that cannot be read falls back to its default — typing-indicator's
+  `timeout` / `throttle`, stick-to-bottom's `threshold`, and portal's `to`, which
+  now lands the node at the default destination instead of leaving it in place.
+- A key that steers an IME conversion is left to the composition (pointer-drag,
+  roving), roving passes a modified `Home` / `End` through to the browser, and
+  pointer-drag leaves a press to a native control or editing surface inside the
+  handle.
+- roving: an item that cannot take focus — `hidden`, natively `disabled`,
+  including through a `fieldset` — is neither a move target nor a tab-stop
+  candidate, and the horizontal arrow pair follows the writing direction.
+- pointer-drag: the `touch-action` and `tabindex` lent to a handle are given back
+  when an element stops being one, and a handle that leaves the controller ends
+  its session in `cancel`.
+- preview-guard: the rewind Turbo's snapshot needs runs on `turbo:before-cache`,
+  the inline `visibility` is leased so an authored declaration survives, and the
+  child markup a placeholder displaced is put back intact.
+- Transient state is re-derived on connect rather than trusted from a restored
+  snapshot: the cable controllers' rejection hooks, stick-to-bottom's
+  `data-pinned` / `data-has-new`, and preview-guard's `data-preview-hidden`.
+- A swap at runtime is followed rather than left behind: typing-indicator repaints
+  a `status` slot swapped in mid-conversation, stick-to-bottom moves its append
+  watch onto a `content` target that arrives or leaves and re-derives pinned from a
+  `threshold` changed on the element, and preview-guard re-forms a guard that is
+  already up to match a changed `placeholder`.
+
+### Fixed
+
+- stick-to-bottom: a container connected without a box holds unpinned until the
+  layout arrives, so what arrives meanwhile is flagged rather than followed into a
+  box that cannot move.
+- pointer-drag: an in-flight follow offset leaves the DOM on teardown, so a
+  re-inserted element does not read it back as a committed base.
+- portal: an instance that has been replaced on the same element no longer rewinds
+  the teleport the live one holds.
+- typing-indicator: a name carrying `$&`, `` $` ``, `$'` or `$$` is written into the
+  status copy literally instead of expanding into the template's own text.
+
 ## [0.10.0] - 2026-08-31
 
 Minor release with no new components. Eight existing ones are reworked — anchored,
@@ -856,6 +999,8 @@ Initial public alpha: 101 behavior-only, accessible Stimulus controllers driven
 by `data-*` attributes, shipping no CSS. Published to npm (with provenance) and
 RubyGems.
 
+[0.12.0]: https://github.com/taiyaky/stimeo-ui/releases/tag/v0.12.0
+[0.11.0]: https://github.com/taiyaky/stimeo-ui/releases/tag/v0.11.0
 [0.10.0]: https://github.com/taiyaky/stimeo-ui/releases/tag/v0.10.0
 [0.9.0]: https://github.com/taiyaky/stimeo-ui/releases/tag/v0.9.0
 [0.8.0]: https://github.com/taiyaky/stimeo-ui/releases/tag/v0.8.0

data/dist/cable/index.js

@@ -2,6 +2,37 @@ import { Controller } from '@hotwired/stimulus';
 import { createConsumer } from '@rails/actioncable';
 
 // src/cable/live_counter_controller.ts
+
+// src/utils/authored_integer.ts
+var TOKEN_BODY = /\d[\d.,'’’    _]*\d|\d/;
+var SIGN_OPENER = /[\s([]/;
+function authoredInteger(text) {
+  const firstDigit = /\d/.exec(text);
+  if (firstDigit === null) return null;
+  const at = firstDigit.index;
+  const signed = at > 0 && text[at - 1] === "-" && (at === 1 || SIGN_OPENER.test(text[at - 2]));
+  const body = TOKEN_BODY.exec(text.slice(at));
+  const runs = body[0].split(/\D+/);
+  const separators = body[0].match(/\D+/g) ?? [];
+  const lead = runs[0];
+  const heads = lead.length <= 3 && !lead.startsWith("0");
+  let digits = lead;
+  for (let i = 1; heads && i < runs.length; i += 1) {
+    if (separators[i - 1]?.length !== 1 || runs[i]?.length !== 3) break;
+    digits += runs[i];
+  }
+  const magnitude = Number.parseInt(digits, 10);
+  return signed ? -magnitude || 0 : magnitude;
+}
+function parseSubscriptionParams(raw) {
+  try {
+    const parsed = JSON.parse(raw);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return {};
+    return parsed;
+  } catch {
+    return {};
+  }
+}
 var sharedConsumer = null;
 function setCableConsumer(consumer) {
   sharedConsumer = consumer;
@@ -10,40 +41,92 @@ function getCableConsumer() {
   if (!sharedConsumer) sharedConsumer = createConsumer();
   return sharedConsumer;
 }
+var sharedSubscriptions = /* @__PURE__ */ new WeakMap();
+function identifierOf(channel) {
+  return JSON.stringify(typeof channel === "string" ? { channel } : channel);
+}
 function createConfirmedSubscription(channel, mixin) {
-  let confirmed = false;
-  let rejected = false;
-  const subscription = getCableConsumer().subscriptions.create(channel, {
-    // A refusal is final: Action Cable never confirms a rejected subscription,
-    // so a late connected/disconnected (only possible from a misbehaving
-    // consumer double) must not reopen the gate `rejected` promised shut.
-    connected: () => {
-      if (rejected) return;
-      confirmed = true;
-      mixin.connected?.();
-    },
-    disconnected: () => {
-      if (rejected) return;
-      confirmed = false;
-      mixin.disconnected?.();
-    },
-    rejected: () => {
-      confirmed = false;
-      rejected = true;
-      mixin.rejected?.();
-    },
-    received: (data) => mixin.received?.(data)
-  });
+  const consumer = getCableConsumer();
+  let registry = sharedSubscriptions.get(consumer);
+  if (!registry) {
+    registry = /* @__PURE__ */ new Map();
+    sharedSubscriptions.set(consumer, registry);
+  }
+  const identifier = identifierOf(channel);
+  const member = { mixin, catchUp: false };
+  let shared = registry.get(identifier);
+  if (!shared) {
+    shared = openSharedSubscription(consumer, channel);
+    registry.set(identifier, shared);
+  } else if (shared.rejected || shared.confirmed) {
+    const owed = shared;
+    member.catchUp = true;
+    queueMicrotask(() => {
+      if (!member.catchUp) return;
+      member.catchUp = false;
+      if (owed.rejected) mixin.rejected?.();
+      else mixin.connected?.();
+    });
+  }
+  shared.members.add(member);
+  const owner = shared;
+  const registered = registry;
+  let active = true;
   return {
-    perform: (action, data) => subscription.perform(action, data),
-    unsubscribe: () => subscription.unsubscribe(),
+    perform: (action, data) => owner.subscription.perform(action, data),
+    unsubscribe: () => {
+      if (!active) return;
+      active = false;
+      member.catchUp = false;
+      owner.members.delete(member);
+      if (owner.members.size === 0) {
+        registered.delete(identifier);
+        owner.subscription.unsubscribe();
+      }
+    },
     get confirmed() {
-      return confirmed;
+      return owner.confirmed;
     },
     get rejected() {
-      return rejected;
+      return owner.rejected;
+    }
+  };
+}
+function openSharedSubscription(consumer, channel) {
+  const members = /* @__PURE__ */ new Set();
+  const fanOut = (deliver) => {
+    for (const member of [...members]) {
+      member.catchUp = false;
+      deliver(member.mixin);
     }
   };
+  const shared = {
+    members,
+    confirmed: false,
+    rejected: false,
+    subscription: consumer.subscriptions.create(channel, {
+      // A refusal is final: Action Cable never confirms a rejected subscription,
+      // so a late connected/disconnected (only possible from a misbehaving
+      // consumer double) must not reopen the gate `rejected` promised shut.
+      connected: () => {
+        if (shared.rejected) return;
+        shared.confirmed = true;
+        fanOut((mixin) => mixin.connected?.());
+      },
+      disconnected: () => {
+        if (shared.rejected) return;
+        shared.confirmed = false;
+        fanOut((mixin) => mixin.disconnected?.());
+      },
+      rejected: () => {
+        shared.confirmed = false;
+        shared.rejected = true;
+        fanOut((mixin) => mixin.rejected?.());
+      },
+      received: (data) => fanOut((mixin) => mixin.received?.(data))
+    })
+  };
+  return shared;
 }
 
 // src/cable/live_counter_controller.ts
@@ -52,17 +135,28 @@ var LiveCounterController = class extends Controller {
   static targets = ["value", "trigger"];
   static values = {
     channel: { type: String, default: "" },
-    params: { type: Object, default: {} },
+    params: { type: String, default: "" },
     id: { type: String, default: "" }
   };
   static actions = ["increment"];
   static events = ["change"];
+  /** Identifier parameters parsed once from their declaration, never in the hot path. */
+  #params = {};
   #subscription = null;
+  /**
+   * Re-parses the identifier parameters when the declaration changes.
+   *
+   * A malformed declaration falls back to no parameters, so the identifier keeps
+   * naming the channel instead of the subscription never being created at all.
+   */
+  paramsValueChanged() {
+    this.#params = parseSubscriptionParams(this.paramsValue);
+  }
   connect() {
     this.element.removeAttribute("data-live-counter-rejected");
     if (this.channelValue) {
       this.#subscription = createConfirmedSubscription(
-        { channel: this.channelValue, ...this.paramsValue },
+        { channel: this.channelValue, ...this.#params },
         {
           connected: () => this.#syncTriggers(),
           // A drop closes the send window (the shared subscription tracks it)
@@ -157,8 +251,7 @@ var LiveCounterController = class extends Controller {
   }
   /** The current count, parsed from the DOM (the single source of truth). */
   get #current() {
-    const parsed = Number.parseInt((this.#display.textContent ?? "").replace(/[^0-9-]/g, ""), 10);
-    return Number.isNaN(parsed) ? 0 : parsed;
+    return authoredInteger(this.#display.textContent ?? "") ?? 0;
   }
   #write(count) {
     if (count === this.#current) return;
@@ -240,13 +333,15 @@ var PresenceController = class extends Controller {
   static targets = ["count", "list", "template"];
   static values = {
     channel: { type: String, default: "" },
-    params: { type: Object, default: {} },
+    params: { type: String, default: "" },
     id: { type: String, default: "" },
     name: { type: String, default: "" },
     heartbeat: { type: Number, default: 15e3 },
     timeout: { type: Number, default: 4e4 }
   };
   static events = ["join", "leave", "change"];
+  /** Identifier parameters parsed once from their declaration, never in the hot path. */
+  #params = {};
   #subscription = null;
   /** Present peers keyed by id (insertion order = join order). */
   #peers = /* @__PURE__ */ new Map();
@@ -256,13 +351,22 @@ var PresenceController = class extends Controller {
   #lastBeaconAt = 0;
   /** Pending trailing-edge convergence beacon (at most one queued). */
   #pendingBeacon = null;
+  /**
+   * Re-parses the identifier parameters when the declaration changes.
+   *
+   * A malformed declaration falls back to no parameters, so the identifier keeps
+   * naming the channel instead of the subscription never being created at all.
+   */
+  paramsValueChanged() {
+    this.#params = parseSubscriptionParams(this.paramsValue);
+  }
   connect() {
     this.#reset();
     this.element.removeAttribute("data-presence-rejected");
     if (this.hasCountTarget) this.countTarget.textContent = this.#countMessage(0);
     if (!this.channelValue) return;
     this.#subscription = createConfirmedSubscription(
-      { channel: this.channelValue, ...this.paramsValue },
+      { channel: this.channelValue, ...this.#params },
       {
         // The first beacon must wait for the confirmed subscription — a
         // perform() before that is silently dropped by Action Cable. Fires
@@ -441,25 +545,75 @@ var PresenceController = class extends Controller {
     }
   }
 };
-var TypingIndicatorController = class extends Controller {
+
+// 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 }
+    })
+  );
+}
+function fillTemplate(template, values) {
+  return template.replace(/\{([a-zA-Z][a-zA-Z0-9]*)\}/g, (match, name) => {
+    const replacement = values[name];
+    return replacement === void 0 ? match : String(replacement);
+  });
+}
+
+// src/cable/typing_indicator_controller.ts
+var DEFAULT_TIMEOUT = 3e3;
+var DEFAULT_THROTTLE = 2e3;
+var fillTokens = (template, values) => template.replace(/%\{(name|names|count)\}/g, (match, token) => values[token] ?? match);
+var TypingIndicatorController = class _TypingIndicatorController extends Controller {
   static targets = ["input", "status"];
   static values = {
     channel: { type: String, default: "" },
-    params: { type: Object, default: {} },
+    params: { type: String, default: "" },
     name: { type: String, default: "" },
-    timeout: { type: Number, default: 3e3 },
+    timeout: { type: Number, default: DEFAULT_TIMEOUT },
     // Must stay below `timeout`: the throttle is leading-edge only (no trailing
     // send), so a receiver's display survives continuous typing only while a
     // fresh signal lands within its timeout window.
-    throttle: { type: Number, default: 2e3 }
+    throttle: { type: Number, default: DEFAULT_THROTTLE },
+    announceOneText: { type: String, default: "" },
+    announceManyText: { type: String, default: "" }
   };
   static events = ["change"];
+  /** Delay (ms) before one settled typer set is sent to the shared announcer. */
+  static #announceDelay = 200;
+  /** Identifier parameters parsed once from their declaration, never in the hot path. */
+  #params = {};
   #subscription = null;
   /** Names currently typing (other clients), each with its auto-clear timer id. */
   #typers = /* @__PURE__ */ new Map();
   #timers = new SafeTimeout();
   /** Epoch ms of the last broadcast, for leading-edge throttling. */
   #lastSentAt = 0;
+  /** The one outstanding announcement, so a newer set supersedes it. */
+  #announceId = null;
+  /**
+   * Re-parses the identifier parameters when the declaration changes.
+   *
+   * A malformed declaration falls back to no parameters, so the identifier keeps
+   * naming the channel instead of the subscription never being created at all.
+   */
+  paramsValueChanged() {
+    this.#params = parseSubscriptionParams(this.paramsValue);
+  }
+  /**
+   * Paints the current copy into a `status` target that arrived at runtime.
+   *
+   * No event: the set of typers did not change, only the element that displays it.
+   * Without this a region swapped in mid-conversation stays empty while `data-typing`
+   * still says someone is typing, leaving the state in the visual hook alone. An empty
+   * set needs no paint — a fresh region already shows it.
+   */
+  statusTargetConnected() {
+    if (this.#typers.size > 0) this.#paint();
+  }
   connect() {
     this.element.removeAttribute("data-typing");
     this.element.removeAttribute("data-typing-indicator-rejected");
@@ -467,7 +621,7 @@ var TypingIndicatorController = class extends Controller {
     this.element.addEventListener("input", this.#onInput);
     if (this.channelValue) {
       this.#subscription = createConfirmedSubscription(
-        { channel: this.channelValue, ...this.paramsValue },
+        { channel: this.channelValue, ...this.#params },
         {
           // The server refused the subscription: the send gate stays shut for
           // good, and the hook lets the consumer's CSS reflect the dead stream.
@@ -484,6 +638,7 @@ var TypingIndicatorController = class extends Controller {
     this.#subscription?.unsubscribe();
     this.#subscription = null;
     this.#timers.clearAll();
+    this.#announceId = null;
     this.#typers.clear();
     this.element.removeAttribute("data-typing");
     this.element.removeAttribute("data-typing-indicator-rejected");
@@ -494,7 +649,7 @@ var TypingIndicatorController = class extends Controller {
   #onInput = () => {
     if (!this.#subscription?.confirmed) return;
     const now = Date.now();
-    if (now - this.#lastSentAt < this.throttleValue) return;
+    if (now - this.#lastSentAt < this.#throttle) return;
     this.#lastSentAt = now;
     this.#subscription.perform("typing", { name: this.nameValue });
   };
@@ -511,25 +666,74 @@ var TypingIndicatorController = class extends Controller {
     const added = existing === void 0;
     this.#typers.set(
       name,
-      this.#timers.set(() => this.#untrack(name), this.timeoutValue)
+      this.#timers.set(() => this.#untrack(name), this.#timeout)
     );
     if (added) this.#render();
   }
+  /**
+   * The silence after which a typer is dropped, in ms: a finite, non-negative number.
+   * Anything else names no delay — `setTimeout` reads `NaN`, a negative value and
+   * `Infinity` alike as "now", so the typer would vanish in the same task it appeared
+   * and the indicator could never be seen. Such a declaration falls back to the default.
+   */
+  get #timeout() {
+    const declared = this.timeoutValue;
+    return Number.isFinite(declared) && declared >= 0 ? declared : DEFAULT_TIMEOUT;
+  }
+  /**
+   * The minimum gap between outgoing signals, in ms: a finite, non-negative number.
+   * Anything else names no interval, and the gate then settles the same way at every
+   * keystroke — `NaN` and a negative gap leave it open, so every keystroke broadcasts,
+   * while `Infinity` is never exceeded, so nothing is ever sent. Such a declaration
+   * falls back to the default.
+   */
+  get #throttle() {
+    const declared = this.throttleValue;
+    return Number.isFinite(declared) && declared >= 0 ? declared : DEFAULT_THROTTLE;
+  }
   #untrack(name) {
     this.#typers.delete(name);
     this.#render();
   }
-  /** Reflects the typer set onto the hook + live region and emits `change`. */
+  /** Reflects the typer set onto the display, announces it, and emits `change`. */
   #render() {
+    const names = this.#paint();
+    this.#announce(names);
+    this.dispatch("change", { detail: { names } });
+  }
+  /**
+   * Hands the settled typer set to the page's shared announcer.
+   *
+   * Debounced: a burst of arrivals is one announcement, not one per name. Only a
+   * non-empty set is announced — that typing stopped is not news worth interrupting
+   * a reader for, and the visible copy already clears. Wording comes from the
+   * consumer, and {@link announce} drops an empty message, so an undeclared template
+   * announces nothing at all.
+   */
+  #announce(names) {
+    if (this.#announceId !== null) this.#timers.clear(this.#announceId);
+    this.#announceId = null;
+    if (names.length === 0) return;
+    const message = names.length === 1 ? fillTemplate(this.announceOneTextValue, { name: names[0] ?? "" }) : fillTemplate(this.announceManyTextValue, {
+      names: names.join(", "),
+      count: names.length
+    });
+    this.#announceId = this.#timers.set(() => {
+      announce(message);
+      this.#announceId = null;
+    }, _TypingIndicatorController.#announceDelay);
+  }
+  /** Writes the current typer set onto the hook and the status slot. */
+  #paint() {
     const names = [...this.#typers.keys()];
     this.element.setAttribute("data-typing", names.length > 0 ? "true" : "false");
     if (this.hasStatusTarget) {
       this.statusTarget.textContent = this.#message(names);
     }
-    this.dispatch("change", { detail: { names } });
+    return names;
   }
   /**
-   * Builds the live-region copy. Localizable through `data-one` / `data-many`
+   * Builds the status copy. Localizable through `data-one` / `data-many`
    * templates on the status target (`%{name}` / `%{names}` / `%{count}`); terse
    * English is the fallback.
    */
@@ -539,10 +743,10 @@ var TypingIndicatorController = class extends Controller {
     if (names.length === 1) {
       const template2 = this.statusTarget.dataset.one;
       const name = names[0] ?? "";
-      return template2 ? template2.replace("%{name}", name) : `${name} is typing\u2026`;
+      return template2 ? fillTokens(template2, { name }) : `${name} is typing\u2026`;
     }
     const template = this.statusTarget.dataset.many;
-    return template ? template.replace("%{names}", joined).replace("%{count}", String(names.length)) : `${joined} are typing\u2026`;
+    return template ? fillTokens(template, { names: joined, count: String(names.length) }) : `${joined} are typing\u2026`;
   }
 };