stimeo-ui 0.15.0 → 0.16.0

package/CHANGELOG.md

@@ -7,6 +7,183 @@ 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.16.0] - 2026-09-26
+
+Minor release with no new components. Widgets now report their own state
+changes — `open` / `close`, and `reconcile` when the page rather than the user
+moves committed state — mirror their value into hidden form fields that fire a
+native `change`, and no longer write normalized values back to their Values.
+Several event, detail, action, and Value names were unified, so read Changed and
+Removed before upgrading. The Inspector manifest moves to schema v14, and
+**`stimeo check` can report errors on views that passed under 0.15.0** (row
+templates, action params, event names, submit-once's `idle` / `busy` pairs), so
+run it before deploying.
+
+### Added
+
+- accordion, collapsible, context-menu, dialog, drawer, dropdown, hover-card,
+  menu, menubar, navigation-menu, popover, read-more, sidebar, and tooltip:
+  `open` / `close` events whose `detail.reason` says why the state moved, typed
+  by the new `StateReason` type export. accordion also carries
+  `{ index, trigger, panel }`, menubar `{ index, menu }`, navigation-menu
+  `{ index, panel }`, and sidebar `{ mode }`.
+- tabs: a `change` event with `{ index, total, previous }`.
+- A `reconcile` event, once per batch and never on connect, when the page — code
+  writing a Value or an attribute, or a morph — rather than the user moves
+  committed state: calendar `{ date }`, currency-input `{ value, formatted }`,
+  data-grid `{ rows }`, date-range-picker `{ start, end }`, listbox
+  `{ value, option }`, pagination `{ page, total, previous }`, range-slider
+  `{ start, end }`, resizable `{ value, fraction }`, separator and slider
+  `{ value }`, stepper `{ index, previous, total, step }`, switch `{ checked }`,
+  theme `{ mode, resolved }`, toggle-group `{ values }`, and tree-view
+  `{ item }`. sidebar reports `reconcile` `{ mode, open }` when crossing its
+  breakpoint switches the mode.
+- Hidden form fields that fire a native `change` on a user commit and stay
+  silent on connect, morphs, and Value writes: calendar `field` / `monthField`,
+  range-slider `startField` / `endField`, and a `field` on slider, switch
+  (`"true"` / `"false"`), and tree-view (the selected item's `data-value`).
+  toggle-group and data-grid mirror into a `fields` container with `name`
+  (`values[]` / `rows[]`) and `form` Values, data-grid from the selected rows'
+  `data-value`. tags-input gains the `form` Value multi-select already has.
+- Label pairs the controller swaps with the state: `expandedLabel` /
+  `collapsedLabel` on accordion, collapsible, and read-more, and `onLabel` /
+  `offLabel` on carousel's play toggle and password-reveal. Regions it shows
+  only in their state: `empty` on combobox and multi-select, `hasNew` on
+  stick-to-bottom, and `prompt` / `idle` on idle, which also sets `data-prompt`
+  while the warning stands.
+- listbox: a `placeholder` Value the trigger shows while nothing is selected.
+- clipboard: `copy` carries `message`, the `copiedLabel` or `errorLabel` for the
+  outcome, so `stimeo--clipboard:copy->stimeo--toast#show` needs no script.
+- stepper: `change` also carries `total`, so it wires straight into
+  step-indicator's `setIndex`.
+- Inspector: `unknown-action-event`, `invalid-template-root`, and action-param
+  checks (`missing-action-param`, `invalid-action-param`, and the warning
+  `confusable-action-param`) for overflow-indicator's `direction`, stepper's
+  `index`, toast's `type`, and announcer's `assertive`.
+
+### Changed
+
+- **Breaking** switch: the event is `change` (was `changed`).
+- **Breaking** step-indicator: the `current` Value is `index`, `setCurrent` is
+  `setIndex` and reads `detail.index`, and `change` carries
+  `{ index, previous, total }`.
+- **Breaking** toast: `body` → `message` (param, detail, and
+  `data-toast-slot`).
+- **Breaking** toast, tags-input, multi-select, and file-dropzone: the row
+  `<template>` must hold exactly one element, and that element carries the
+  `item` / `tag` target itself. A wrapped row or a second element adds nothing;
+  tags-input, multi-select, and file-dropzone say so on the console once per
+  connection, and `stimeo check` reports `invalid-template-root`.
+- **Breaking** detail keys: filter `visible` → `visibleCount`, overflow-menu
+  `{ visible, hidden }` → `{ overflowCount, total }`, portal `mount`
+  `target` → `destination`.
+- **Breaking** slider, range-slider, separator, resizable, rating, color-picker,
+  stepper, pagination, bulk-select, carousel (`autoplay`), and calendar (`month`)
+  no longer write a normalized value back to their Values: the attribute keeps
+  what the page wrote, only a user move writes it, and a declared value takes
+  effect again once the bounds allow it. Read the published state
+  from ARIA, the hidden field, or the events. theme still writes a stored choice
+  back to `mode`.
+- **Breaking** a page-driven move reports `reconcile`, not `change`:
+  currency-input on a `locale`, `currency`, or `precision` change, a swapped-in
+  display, or a reconnect that re-rounds; otp on a native form reset or a
+  `pattern` change that drops entered characters, with no `complete` either.
+  rating's `reconcile` reports every move of the shown rating the page causes, an
+  in-range `value` write included, and nothing for a clamp that leaves it where
+  it was.
+- **Breaking** color-picker, date-range-picker, multi-select, rating, and
+  tags-input fire a native `change` on a user commit — from the hidden `field`,
+  or from the `fields` container on multi-select and tags-input — so a form with
+  `stimeo--auto-submit` or a `change` listener now reacts to it.
+- **Breaking** number-input: a step from the buttons, the arrow and Page keys,
+  Home and End, or press-and-hold fires the native `input` and `change` a typed
+  value does, ahead of `stimeo--number-input:change`, so a form with
+  `stimeo--auto-submit` or a `change` listener now reacts to each step.
+- **Breaking** calendar: without a `month`, the grid opens on the selected day's
+  month instead of today's and leaves `month` empty (read the shown month from
+  `monthField`). A `selected` day outside `min` / `max` is withheld — no
+  `aria-selected`, an empty `field` — and published again once the bounds allow
+  it; the `selected` Value is never rewritten. Focus inside the grid follows a
+  `month` change that moves the painted month to the new month's tab stop.
+- **Breaking** date-range-picker: a confirmed range whose ends `min`, `max`, or
+  `disabledDates` exclude narrows to the nearest selectable days, or clears when
+  none remain, and reports `reconcile`; `connect()` narrows a range read from its
+  fields the same way, silently.
+- **Breaking** flash and toast never evict a hovered or focused notification for
+  `max`: the stack stays over the cap until that hold ends, then the oldest
+  unheld ones go. toast evicts with reason `limit` (was `timeout`), and a `max`
+  of `0` or less, or not a finite number, means no limit (toast used to remove
+  every toast).
+- **Breaking** carousel: the `autoplay` Value is no longer switched off at the
+  end of a non-looping set or under reduced motion. The declared rotation
+  resumes once a slide lies ahead again; reduced motion holds it until the user
+  presses play or the page changes `autoplay`.
+- **Breaking** resizable and filter dispatch `change` only when the outcome
+  moved: resizable's position, filter's `{ active, visibleCount, total }`.
+- **Breaking** slider, range-slider, and separator decide a user move's
+  `change` against the last published value; toggle-group, calendar, and
+  date-range-picker skip a `change` or `select` that a listener superseded.
+- Components follow more runtime changes: calendar repaints on `min`, `max`, and
+  `weekStart`, and a consumer's `aria-disabled` moves with its date to the cell
+  that shows it; countdown follows `completeLabel`; clipboard rewrites a shown
+  result on `copiedLabel` / `errorLabel`; flash applies a changed `max` at once;
+  theme applies a `mode` declaration, reported as `reconcile`, while a stored
+  choice still wins; overflow-menu relabels its More trigger on `moreLabel`;
+  stepper re-derives every step when steps are added or removed.
+- countdown: the completion text it wrote, marked
+  `data-stimeo--countdown-owns-status`, is taken back when the timer leaves
+  `complete`, and a `deadline` moved forward returns it to `paused`.
+  overflow-menu marks the More label it wrote the same way
+  (`data-stimeo--overflow-menu-owns-label`) and leaves alone a trigger the
+  consumer put elements or a name into.
+- listbox: with nothing selected the trigger shows `placeholder`, else the text
+  it held before the first selection, instead of keeping the last selected
+  option's text.
+- number-input: a text-type spinbutton reads full-width digits and signs
+  (`３４`, `－５`) as numbers.
+- color-picker: a repaint that does not move the color no longer overwrites text
+  being typed into the hex input.
+- carousel: an in-page move keeps a running rotation without a new `play`, and a
+  real detach while the element stays in the document emits `pause`.
+- Target attributes are read as a token list: calendar, date-range-picker,
+  flash, nested-form, and toast find a target that also carries other names, and
+  `stimeo check` resolves them the same way.
+- currency-input, input-mask, number-input, and otp hold a page write that
+  arrives during IME composition until the composition ends.
+- Inspector: submit-once's `idle` / `busy` pair is checked per submit control,
+  so a button holding one half is reported (`missing-conditional-target`) even
+  when another button holds both.
+
+### Removed
+
+- **Breaking** overflow-indicator: the `update` action. The controller listens
+  to its viewport's `scroll` itself, and `stimeo check` reports a leftover
+  `scroll->stimeo--overflow-indicator#update` as `unknown-action-method`.
+- **Breaking** calendar: the public `render()` method; the grid repaints itself
+  when `min`, `max`, or `weekStart` change.
+
+### Fixed
+
+- A user-clicked form reset re-derives checkbox, conditional-fields, and otp
+  state.
+- pointer-drag: a `setPointerCapture()` that throws no longer locks the handle
+  out of both pointer and keyboard dragging. slider, range-slider, and
+  color-picker: another element taking the pointer capture mid-drag no longer
+  ends the drag.
+- otp: an edit that reaches a field right after an IME confirmation without a
+  keystroke — dictation, autofill, a drop — is taken instead of dropped.
+- otp: the authored `aria-invalid`, `aria-errormessage`, and `aria-describedby`
+  come back even when a page cached while an error showed is restored under
+  another connection; while the error shows, each field carries a
+  `data-otp-*-lease` marker holding them.
+- tags-input, multi-select, and file-dropzone: a row whose root is itself the
+  `remove` button or the `label` can be removed, focused, and relabelled.
+- stepper: `goto` stays put on an `index` param that is empty or that Stimulus
+  reads as a boolean, `null`, or an array (`"true"`, `"null"`, `"[1]"`), instead
+  of jumping to a step; `stimeo check` already reports these params.
+- The type declarations link `open`, `close`, `confirm`, and `scrollTo` to the
+  component's own method instead of the DOM global of the same name.
+
 ## [0.15.0] - 2026-09-20
 
 Minor release with no new components. Shared internals were consolidated across
@@ -1101,6 +1278,7 @@ Initial public alpha: 101 behavior-only, accessible Stimulus controllers driven
 by `data-*` attributes, shipping no CSS. Published to npm (with provenance) and
 RubyGems.
 
+[0.16.0]: https://github.com/taiyaky/stimeo-ui/releases/tag/v0.16.0
 [0.15.0]: https://github.com/taiyaky/stimeo-ui/releases/tag/v0.15.0
 [0.14.0]: https://github.com/taiyaky/stimeo-ui/releases/tag/v0.14.0
 [0.13.0]: https://github.com/taiyaky/stimeo-ui/releases/tag/v0.13.0

package/README.md

@@ -114,6 +114,126 @@ The `eslint-plugin-jsx-a11y` equivalents are
 `no-noninteractive-tabindex`. These components' real accessibility is exercised
 with axe-core and real screen readers in this project's own test suite.
 
+## Composing components
+
+Parts dispatch `stimeo--<identifier>:<event>` with a `detail`, and Stimulus can bind
+one part's event straight to another part's action. Wiring two parts is a
+`data-action`, not a `<script>`.
+
+```html
+<!-- Copy a link and say so, with nothing in between. -->
+<div data-controller="stimeo--toast"
+     data-action="stimeo--clipboard:copy->stimeo--toast#show">
+  <div data-controller="stimeo--clipboard"
+       data-stimeo--clipboard-text-value="https://example.com/share"
+       data-stimeo--clipboard-copied-label-value="Copied"
+       data-stimeo--clipboard-error-label-value="Copy failed">
+    <button type="button" data-stimeo--clipboard-target="button"
+            data-action="click->stimeo--clipboard#copy">Copy</button>
+  </div>
+  <ol data-stimeo--toast-target="list"></ol>
+  <template data-stimeo--toast-target="template">
+    <li data-stimeo--toast-target="item"><span data-toast-slot="message"></span></li>
+  </template>
+</div>
+```
+
+```html
+<!-- A wizard moves a read-only progress indicator. -->
+<div data-controller="stimeo--stepper">
+  <ol data-controller="stimeo--step-indicator"
+      data-action="stimeo--stepper:change@window->stimeo--step-indicator#setIndex">
+    <li data-stimeo--step-indicator-target="step">Cart</li>
+    <li data-stimeo--step-indicator-target="step">Shipping</li>
+  </ol>
+  <!-- the stepper's own step targets and buttons -->
+</div>
+```
+
+```html
+<!-- A value a widget stepped submits the form, through the events a browser
+     would have fired for its own control. -->
+<form data-controller="stimeo--auto-submit"
+      data-action="change->stimeo--auto-submit#submit">
+  <div data-controller="stimeo--number-input">
+    <input type="number" name="quantity" value="1" aria-label="Quantity"
+           data-stimeo--number-input-target="input"
+           data-action="change->stimeo--number-input#onInput
+                        keydown->stimeo--number-input#onKeydown" />
+    <button type="button" aria-label="Increase" tabindex="-1"
+            data-stimeo--number-input-target="increment"
+            data-action="click->stimeo--number-input#increment">+</button>
+  </div>
+</form>
+```
+
+Two things to know:
+
+- **Events bubble from the part that dispatched them.** The receiver has to be an
+  ancestor. Anywhere else — a sibling, or a receiver nested *inside* the part that
+  dispatches — needs `@window`, because bubbling only ever goes up:
+  `stimeo--clipboard:copy@window->stimeo--toast#show`.
+- **Do not say the same thing twice.** A toast's message slot is a `role="status"`
+  live region. Wiring the same result to the shared announcer as well
+  (`announce-copied-text`, …) reads it out twice. Pick one.
+
+`stimeo check` verifies both halves of a wire: the controller and action on the
+receiving side, and the event name on the emitting side.
+
+## Styling notes
+
+### `hidden` under a utility CSS layer
+
+Controllers show and hide their own declared regions with the `hidden` attribute —
+a listbox option filtered out, an "empty" row, the half of a label that does not
+belong to the current state. `hidden` only carries `display: none` from the user-agent
+stylesheet, so any rule that sets `display` wins over it.
+
+Utility-first frameworks make that collision likely. Tailwind v4 declares
+`@layer theme, base, components, utilities`, and DaisyUI puts component classes such
+as `.menu li`, `.tabs`, and `.steps` in the **last** layer. A hidden element inside one
+of them stays visible, and a `display: none` you add in `@layer components` still loses.
+
+Put the override **outside every layer** — unlayered rules beat layered ones, so no
+`!important` is needed:
+
+```css
+/* not inside @layer */
+.menu li[hidden],
+.menu [role="option"][hidden] {
+  display: none;
+}
+```
+
+Most visible with `combobox`, `listbox`, `multi-select`, `empty-state`, `filter`, and
+`command-palette`, whose options and empty rows are the ones being hidden.
+
+### State-dependent text belongs in markup
+
+It is tempting to put the words that change with a state into CSS:
+
+```css
+/* don't */
+.play::after                      { content: "Auto-advance: off"; }
+.play[aria-pressed="true"]::after { content: "Auto-advance: on"; }
+```
+
+Text in `content` never reaches a translation catalogue, and the usual "find untranslated
+strings" scan reads HTML, so it does not turn up there either. `content: attr(aria-valuetext)`
+has the same problem from the other side: the attribute is composed at runtime in one
+language. Keep the words in markup and let the controller show the half that applies:
+
+```html
+<button data-stimeo--read-more-target="trigger" aria-expanded="false">
+  <span data-stimeo--read-more-target="collapsedLabel">Read more</span>
+  <span data-stimeo--read-more-target="expandedLabel" hidden>Show less</span>
+</button>
+```
+
+Controllers that read out a composed value take the wording as an attribute instead —
+`color-picker` accepts `data-value-text`, and the announcing controllers accept
+`announce-*-text`.
+
 ## Inspector CLI & MCP server
 
 Stimeo UI bundles a zero-dependency static checker for its own markup contract

package/dist/cable/index.js

@@ -164,6 +164,18 @@ var SafeInterval = class extends TimerRegistry {
     window.clearInterval(id);
   }
 };
+
+// src/utils/transient_hooks.ts
+var TransientHooks = class {
+  #attributes;
+  constructor(options) {
+    this.#attributes = options.attributes;
+  }
+  /** Drops the declared hooks from `element`; what it carries besides stays. */
+  reset(element) {
+    for (const attribute of this.#attributes) element.removeAttribute(attribute);
+  }
+};
 function parseSubscriptionParams(raw) {
   try {
     const parsed = JSON.parse(raw);
@@ -270,6 +282,7 @@ function openSharedSubscription(consumer, channel) {
 }
 
 // src/cable/live_counter_controller.ts
+var TRANSIENT = new TransientHooks({ attributes: ["data-live-counter-rejected"] });
 var DISABLED_MARKER = "data-live-counter-disabled";
 var LiveCounterController = class _LiveCounterController extends Controller {
   static targets = ["value", "trigger"];
@@ -323,9 +336,12 @@ var LiveCounterController = class _LiveCounterController extends Controller {
    * The rejected hook is transient server state: a Turbo cache snapshot must not
    * resurrect it — the fresh subscription re-decides it. An outstanding guess
    * belongs to the identifier that is going away, so it is dropped with it.
+   *
+   * @stimeoRuntimeOnly `channel` decides whether this call opens a subscription at all; the
+   *   rejected hook it clears does not depend on it.
    */
   #subscribe() {
-    this.element.removeAttribute("data-live-counter-rejected");
+    TRANSIENT.reset(this.element);
     this.#outstanding.length = 0;
     if (this.channelValue) {
       this.#subscription = this.#open();
@@ -340,6 +356,9 @@ var LiveCounterController = class _LiveCounterController extends Controller {
    * half-wired: no gate reflected, and a trigger that looks live. The gate reads
    * the declaration, so a null subscription keeps it shut and the display never
    * moves past what the server can receive.
+   *
+   * @stimeoRuntimeOnly `channel` and its params choose the one subscription this call opens; `id`
+   *   is read by the handlers it wires.
    */
   #open() {
     try {
@@ -388,7 +407,7 @@ var LiveCounterController = class _LiveCounterController extends Controller {
     this.#focusedTriggers.releaseAll();
     this.#subscription?.unsubscribe();
     this.#subscription = null;
-    this.element.removeAttribute("data-live-counter-rejected");
+    TRANSIENT.reset(this.element);
     for (const trigger of this.triggerTargets) this.#release(trigger);
   }
   /** Late-added triggers (e.g. via a Turbo Stream) pick up the current gate. */
@@ -467,6 +486,8 @@ var LiveCounterController = class _LiveCounterController extends Controller {
    * authored-disabled trigger ("disabled until valid", say) is never
    * re-enabled by the gate. A marked disabled restored from a Turbo cache
    * snapshot is recognized as ours and lifted once the gate opens.
+   *
+   * @stimeoRenderRoot
    */
   #syncTrigger(trigger) {
     if (this.#ready) {
@@ -510,6 +531,9 @@ var LiveCounterController = class _LiveCounterController extends Controller {
    * Settles the display on a count the server stated, announcing what it settled
    * on. Announcing the optimistic bump instead would read a guess out and then
    * correct it, so the announcement rides this path only.
+   *
+   * @stimeoRuntimeOnly The count shown is the value received; `announceText` words the one
+   *   announcement of this change.
    */
   #reconcile(count) {
     if (this.#write(count)) this.#announce(count);
@@ -574,7 +598,16 @@ var KeyedTimers = class {
   }
 };
 
+// src/utils/template_row.ts
+function cloneTemplateRoot(template) {
+  const root = template.content.firstElementChild;
+  return root instanceof HTMLElement ? root.cloneNode(true) : null;
+}
+
 // src/cable/presence_controller.ts
+var TRANSIENT2 = new TransientHooks({
+  attributes: ["data-present", "data-present-count", "data-presence-rejected"]
+});
 var BEACON_THROTTLE_MS = 2e3;
 var DEFAULT_HEARTBEAT_MS = 15e3;
 var DEFAULT_TIMEOUT_MS = 4e4;
@@ -669,7 +702,6 @@ var PresenceController = class _PresenceController extends Controller {
   }
   connect() {
     this.#reset();
-    this.element.removeAttribute("data-presence-rejected");
     if (this.hasCountTarget) this.countTarget.textContent = this.#countMessage(0);
     if (!this.channelValue) return;
     this.#claimSpeaker();
@@ -695,7 +727,6 @@ var PresenceController = class _PresenceController extends Controller {
     this.#subscription = null;
     this.#intervals.clearAll();
     this.#reset();
-    this.element.removeAttribute("data-presence-rejected");
   }
   /**
    * Registers this element as one of the voices for its peer, so a sibling on the
@@ -775,6 +806,9 @@ ${this.idValue}`;
    * Tracks a broadcast beacon: upserts the peer (restarting its expiry timer),
    * removes it on a `leaving` notice, and re-announces this client when the
    * peer was unknown (roster convergence — see the class doc).
+   *
+   * @stimeoRuntimeOnly `id` filters this client's own echo, `timeout` arms one peer's expiry,
+   *   `name` answers one beacon and the texts word one announcement.
    */
   #onReceived(data) {
     const beacon = data;
@@ -799,7 +833,11 @@ ${this.idValue}`;
       this.#render();
     }
   }
-  /** Removes a peer (expiry or graceful leave) and reflects the change. */
+  /**
+   * Removes a peer (expiry or graceful leave) and reflects the change.
+   *
+   * @stimeoRuntimeOnly `announceLeaveText` words the one announcement this departure makes.
+   */
   #drop(id) {
     const peer = this.#peers.get(id);
     if (peer === void 0) return;
@@ -810,7 +848,9 @@ ${this.idValue}`;
     this.#announce(this.announceLeaveTextValue, peer.name);
     this.dispatch("leave", { detail: { id } });
   }
-  /** Reflects the roster onto the hooks + count target and emits `change`. */
+  /**
+   * Reflects the roster onto the hooks + count target and emits `change`.
+   */
   #render() {
     const users = [...this.#peers.entries()].map(([id, peer]) => ({ id, name: peer.name }));
     this.element.setAttribute("data-present", users.length > 0 ? "true" : "false");
@@ -849,8 +889,8 @@ ${this.idValue}`;
   /** Appends one template clone for a newly present peer (list + template only). */
   #appendClone(id, name) {
     if (!this.hasListTarget || !this.hasTemplateTarget) return;
-    const root = this.templateTarget.content.firstElementChild?.cloneNode(true);
-    if (!(root instanceof Element)) return;
+    const root = cloneTemplateRoot(this.templateTarget);
+    if (!root) return;
     root.setAttribute("data-presence-id", id);
     this.#fillName(root, name);
     this.listTarget.appendChild(root);
@@ -885,8 +925,7 @@ ${this.idValue}`;
     this.#announceId = null;
     this.#peers.clear();
     this.#lastBeaconAt = 0;
-    this.element.removeAttribute("data-present");
-    this.element.removeAttribute("data-present-count");
+    TRANSIENT2.reset(this.element);
     if (this.hasCountTarget) this.countTarget.textContent = "";
     if (this.hasListTarget) {
       for (const child of this.listTarget.querySelectorAll("[data-presence-id]")) {
@@ -895,6 +934,9 @@ ${this.idValue}`;
     }
   }
 };
+var TRANSIENT3 = new TransientHooks({
+  attributes: ["data-typing", "data-typing-indicator-rejected"]
+});
 var DEFAULT_TIMEOUT = 3e3;
 var DEFAULT_THROTTLE = 2e3;
 var fillTokens = (template, values) => template.replace(/%\{(name|names|count)\}/g, (match, token) => values[token] ?? match);
@@ -948,8 +990,7 @@ var TypingIndicatorController = class _TypingIndicatorController extends Control
     if (this.#typers.size > 0) this.#paint();
   }
   connect() {
-    this.element.removeAttribute("data-typing");
-    this.element.removeAttribute("data-typing-indicator-rejected");
+    TRANSIENT3.reset(this.element);
     if (this.hasStatusTarget) this.statusTarget.textContent = "";
     this.element.addEventListener("input", this.#onInput);
     if (this.channelValue) {
@@ -974,8 +1015,7 @@ var TypingIndicatorController = class _TypingIndicatorController extends Control
     this.#expiry.clearAll();
     this.#announceId = null;
     this.#typers.clear();
-    this.element.removeAttribute("data-typing");
-    this.element.removeAttribute("data-typing-indicator-rejected");
+    TRANSIENT3.reset(this.element);
     if (this.hasStatusTarget) this.statusTarget.textContent = "";
     this.#lastSentAt = 0;
   }
@@ -991,6 +1031,9 @@ var TypingIndicatorController = class _TypingIndicatorController extends Control
    * Tracks a broadcast typer. The own echo is dropped (same `name`); every
    * further signal from a name restarts its auto-clear timer, so the indicator
    * survives continuous typing and clears `timeout` ms after the last signal.
+   *
+   * @stimeoRuntimeOnly `name` filters this client's own echo and `timeout` arms one typer's expiry;
+   *   the typers shown come from what is received.
    */
   #onReceived(data) {
     const name = data?.name;
@@ -1027,7 +1070,9 @@ var TypingIndicatorController = class _TypingIndicatorController extends Control
     this.#typers.delete(name);
     this.#render();
   }
-  /** Reflects the typer set onto the display, announces it, and emits `change`. */
+  /**
+   * Reflects the typer set onto the display, announces it, and emits `change`.
+   */
   #render() {
     const names = this.#paint();
     this.#announce(names);
@@ -1041,6 +1086,9 @@ var TypingIndicatorController = class _TypingIndicatorController extends Control
    * 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.
+   *
+   * @stimeoRuntimeOnly The wording Values are read to compose one announcement; the
+   * visible typer list is rendered from the set, not from them.
    */
   #announce(names) {
     if (this.#announceId !== null) this.#timers.clear(this.#announceId);