stimeo-ui 0.9.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3a8ccbe681a75206e0bb8a8866faeb91e0f3878c6b05cba845d00a333bb87041
-  data.tar.gz: f037b2908d8f19d55f1b9c5823a80b0459f995837b396dcc686b6b9318ee58dc
+  metadata.gz: dbc740b1497e7c760dce2eb0207e1e513a64e944aef2d666b8785c1244bd4618
+  data.tar.gz: e687fa19aae7ea8432130228a1bb0bfeb82868f56b18c8d823edb5d6dd1b77c7
 SHA512:
-  metadata.gz: 785070e68e5d1cad2c96d1ca1821096662d2612a42121c254d5d0b92400b2e4f04af759fb1ad8827c1100dad712a43e5c0d45032aa72449d54956d3bf606f982
-  data.tar.gz: 2e1632573e162636ffd659fb01b0cc0c5d5d22d0d521e6f9c39793a28023f0403eb3008fd5640d65f73b74d7d19ce210d01b7413b459db3fa5e6bbf8bcb58dce
+  metadata.gz: eeeef9df2dedeb5aa23da6de1c08bc6921f0c85554de9162999895d48ddd89950dfe5dfa32b895d3fd80a780470966a2ae9f9517e8743b6b7868c9a1e441b2da
+  data.tar.gz: 3a40f5f32596616f06fa52a93a446ddf73ed25421c610c54209d200eb8c631d5b334e1f014852e8331e4fd9b09ad0933929ad1de54d36aaa4d14361e05a2bcc0

data/CHANGELOG.md

@@ -7,6 +7,153 @@ 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.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,
+focus, password-reveal, password-strength, scroll-restore, scroll-visibility,
+theme, and transition — and a shared change to the focus trap reaches the six
+modal overlays too. Most of them changed a contract, so read Removed and Changed
+before upgrading. The Inspector manifest stays on schema v12.
+
+### Removed
+
+- theme: the `mode` action param. Options declare their mode with
+  `data-value="light|dark|system"` — migrate every option or it can never become
+  the selection.
+- password-strength: the live region on the `label` target. Drop its `aria-live`,
+  seat a `stimeo--announcer` on the page, and set `announceText`.
+- focus: `[autofocus]` initial focus and the optional scroll lock, neither of
+  which was ever implemented. Initial focus is the `initial` target, else the
+  first focusable descendant, else the container.
+
+### Added
+
+- password-strength: `announceText` (`{level}` / `{score}` / `{max}` / `{band}`),
+  a `setScore` action for a score computed outside the built-in heuristic, and a
+  `reconcile` event.
+- `stimeo check` warns when a page uses password-strength with no
+  `stimeo--announcer`.
+
+### Changed
+
+- alert-dialog, command-palette, confirm, dialog, drawer, sidebar, and focus:
+  background isolation walks from the element up to `<body>` and inerts each
+  ancestor's other children, so one nested below `<body>` isolates its own branch.
+- transition: declare a token as a stage Value **or** author it as a standing
+  class, not both — a token already on the element is the consumer's and is never
+  applied or removed. `connect()` no longer strips half-applied stage classes.
+- A half-applied state is rewound before Turbo caches the page, silently:
+  transition's stage classes, focus's `data-focus-trapped`, password-reveal's
+  revealed field, and everything password-strength derives from the field value.
+- focus reads its declarations at fixed moments: only `trap` is watched, `auto`
+  and `inert` are read when the trap turns on, and `restore` when it turns off.
+- A declaration that cannot be read falls back to its default instead of poisoning
+  the widget — anchored's `placement` / `offset` / `padding`, theme's `mode` /
+  `target`, scroll-visibility's `offset` / `root` / `focusSelector`,
+  password-strength's `minScore` / `levels`.
+- Targets and declarations swapped in at runtime are followed: anchored's `anchor`
+  / `floating`, password-reveal's `input` / `toggle`, password-strength's targets,
+  theme's options, scroll-visibility's `element` / `offset` / `mode`, and
+  scroll-restore's `key` / `axis`.
+- Events report transitions only — theme's `change` when `mode` or `resolved`
+  actually moved, scroll-visibility's `change` on a real visibility change
+  (connecting is silent), password-strength's announcement when the level changes.
+  A scroll with no vertical movement leaves scroll-visibility alone.
+- Smaller contract shifts: password-strength's `data-strength` bands anchor both
+  ends of the declared scale (a level count other than four moves the boundaries)
+  and its `meter` target needs an accessible name; scroll-restore always restores
+  instantly (so `scroll-behavior: smooth` no longer animates it) and writes
+  nothing for an element it never restored and the reader never scrolled; theme writes
+  `aria-pressed` only on a button and passes modified `Home` / `End` through.
+
+### Fixed
+
+- transition: `enter()` from `hidden` runs the CSS transition instead of popping
+  in, so `entered` arrives on the real terminal event rather than the safety
+  timeout.
+- A control that owns focus is no longer hidden or stranded: scroll-visibility
+  holds the hide until it blurs and `toTop` focuses without scrolling, and focus's
+  state hook and events follow the controller's own record of trapping.
+- Stored and measured state holds: scroll-restore keeps a saved offset that a
+  clamped restore would have overwritten and never republishes it under a new
+  `key`; password-reveal arms the `autoHide` it skipped on an already-revealed
+  field; anchored measures a target swapped in at runtime and writes no stale
+  placement after teardown.
+
 ## [0.9.0] - 2026-08-28
 
 Minor release with no new components. Ten existing ones are reworked —
@@ -783,6 +930,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.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
 [0.7.0]: https://github.com/taiyaky/stimeo-ui/releases/tag/v0.7.0

data/dist/cable/index.js

@@ -2,6 +2,15 @@ import { Controller } from '@hotwired/stimulus';
 import { createConsumer } from '@rails/actioncable';
 
 // src/cable/live_counter_controller.ts
+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,41 +19,93 @@ 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
 var DISABLED_MARKER = "data-live-counter-disabled";
@@ -52,17 +113,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)
@@ -240,13 +312,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 +330,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 +524,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 +600,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 +617,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 +628,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 +645,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 +722,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`;
   }
 };
 

data/dist/controllers/alert_dialog_controller.js

@@ -315,15 +315,25 @@ var FocusTrap = class {
    * content cannot be focused or reached by assistive technology, honoring the
    * `aria-modal="true"` contract. An element that was *already* `inert` is left
    * untracked so `#releaseBackground` does not wrongly clear it.
+   *
+   * The walk climbs from the container to `body` and inerts each ancestor's other
+   * children. Scanning only `body`'s children would skip the branch the container
+   * sits in — everything beside it inside that branch is background too, and a
+   * nested container is the ordinary case.
    */
   #isolateBackground() {
     const container = this.#getContainer();
     this.#inertedSiblings = [];
-    for (const sibling of Array.from(document.body.children)) {
-      if (!(sibling instanceof HTMLElement)) continue;
-      if (sibling.contains(container) || sibling.inert) continue;
-      sibling.inert = true;
-      this.#inertedSiblings.push(sibling);
+    for (let node = container; node !== document.body; ) {
+      const parent = node.parentElement;
+      if (!parent) break;
+      for (const sibling of Array.from(parent.children)) {
+        if (!(sibling instanceof HTMLElement)) continue;
+        if (sibling === node || sibling.inert) continue;
+        sibling.inert = true;
+        this.#inertedSiblings.push(sibling);
+      }
+      node = parent;
     }
   }
   /** Reverts the `inert` flags applied by `#isolateBackground`. */
@@ -361,8 +371,8 @@ var AlertDialogController = class extends Controller {
   static actions = ["cancel", "confirm", "open"];
   static events = ["cancel", "confirm"];
   /**
-   * Owns the modal side effects. Escape is routed through {@link cancel} so it
-   * emits the same event as the cancel button (tagged `"escape"`); focus falls
+   * Owns the modal side effects. Escape takes the same cancel path as
+   * {@link cancel} and emits the same event, tagged `"escape"` instead of `"user"`; focus falls
    * back to the trigger when nothing was focused before opening.
    */
   #trap = new FocusTrap(() => this.dialogTarget, {

data/dist/controllers/announcer_controller.js

@@ -338,7 +338,7 @@ var AnnouncerController = class extends Controller {
   }
   /**
    * Arms `region`'s single pending timer. Callers reach here with the slot
-   * already free — `#announce` releases it, and a fired timer clears its own
+   * 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) {

data/dist/controllers/bulk_select_controller.js

@@ -63,8 +63,8 @@ var BulkSelectController = class extends Controller {
   static events = ["change", "reconcile"];
   /** All-pages mode is a transient UI state, mirrored to `data-all-pages` so a
    *  `connect()` over markup that already carries the attribute rehydrates the
-   *  mode — a morph, a Turbo Stream, or a server that renders it back. A restore
-   *  visit serves the server's markup instead, so the mode does not survive one. */
+   *  mode — a morph, a Turbo Stream, a server that renders it back, or a restore
+   *  visit, whose cached snapshot carries the attribute too. */
   #allPagesMode = false;
   /** Last emitted figures, so a recompute reports only on a real change. */
   #lastCount = -1;

data/dist/controllers/collapsible_controller.js

@@ -217,7 +217,7 @@ var CollapsibleController = class extends Controller {
    * `open` Value disagrees. An already-open region remains open without a
    * close/reopen cycle. The Value only seeds a genuinely fresh render where no
    * state attribute is present yet; any opening animation in that case belongs to
-   * the consumer's CSS. Mirrors `sidebar`'s `#restoreCollapsed`.
+   * the consumer's CSS.
    */
   connect() {
     this.#connected = true;