stimeo-ui 0.15.0 → 0.17.0

package/CHANGELOG.md

@@ -7,6 +7,212 @@ 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.
 
+## [Unreleased]
+
+## [0.17.0] - 2026-10-04
+
+### Changed
+
+- **Breaking** Replace `reset-before-cache` with `reset-on-restore` (class, export,
+  and subpath).
+  Reset runs on restoration; remove `dispatchReset` and `:request` bindings.
+  Restored drawers and command palettes start closed.
+- **Breaking** Rename calendar, combobox, and command-palette `selectByClick`, and
+  tree-view `onClick`, to `select`; replace calendar `selectDayElement` with
+  `select(element)`.
+  Accordion `toggle`, theme `set`, and scrollspy `scrollTo` require owned targets.
+- **Breaking** State events are silent for unchanged state and superseded pending
+  reports.
+  For child edits within partial checkbox groups, use the children's native `change`.
+  Number Values and action params enforce finite values and their declared domains.
+  Update Inspector integrations to schema v15 and run `stimeo check` before deploying.
+- Target actions accept owned elements; user state reports include `detail.reason`.
+  Toast duration, persist debounce, and count-up duration changes apply to the next
+  operation. Portal destination changes update mounts; Cable params cannot replace
+  the declared channel.
+
+### Fixed
+
+- Preserve live state across Turbo caching, repair derived state after retained
+  morphs, and restore focus reliably across nested layers and Shadow DOM.
+
+## [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 +1307,9 @@ Initial public alpha: 101 behavior-only, accessible Stimulus controllers driven
 by `data-*` attributes, shipping no CSS. Published to npm (with provenance) and
 RubyGems.
 
+[Unreleased]: https://github.com/taiyaky/stimeo-ui/compare/v0.17.0...HEAD
+[0.17.0]: https://github.com/taiyaky/stimeo-ui/releases/tag/v0.17.0
+[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

@@ -62,7 +62,14 @@ registerStimeo(application); // registers every stimeo--* controller
 ```
 
 Need only a few controllers? Import them individually from
-`stimeo-ui/controllers/*` and register them under your own identifiers.
+`stimeo-ui/controllers/*` and register them under your own identifiers. Each
+file loads on its own, yet the coordination between components — which layer
+Escape closes, a focus trap's `Tab` and background, the value two components
+lend the same attribute — is kept once per page, whichever files the
+controllers came from, `stimeo-ui` itself included.
+Copies of the same controller also share dirty-form confirmations, highlight
+deadlines and portal origins. Opt-in Cable copies share the consumer, subscriptions
+and peer departure decisions; generated ARIA ids stay distinct across copies too.
 
 - **Peer dependencies:** `@hotwired/stimulus` (always), `@floating-ui/dom` (only
   if you use the opt-in `stimeo-ui/positioning` module — tooltips, popovers, etc.
@@ -114,6 +121,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.d.ts

@@ -62,9 +62,10 @@ import { Controller, Application } from '@hotwired/stimulus';
  * (local-only) counters never disable their triggers. `announceText` is opt-in
  * and empty by default; when set, reconciled counts reach the page's shared
  * announcer, debounced so a burst is one message. The subscription follows the
- * declaration — a `channel` or `params` change moves it — and is released on
- * `disconnect()` (Turbo navigation included) along with any pending
- * announcement.
+ * declaration — a `channel` or `params` change moves it, once per batch of
+ * changes and only when the identifier they name differs from the one it was
+ * opened for — and is released on `disconnect()` (Turbo navigation included)
+ * along with any pending announcement.
  */
 declare class LiveCounterController extends Controller<HTMLElement> {
     #private;
@@ -96,13 +97,7 @@ declare class LiveCounterController extends Controller<HTMLElement> {
     paramsValue: string;
     idValue: string;
     announceTextValue: string;
-    /**
-     * Re-parses the identifier parameters and moves the subscription to the
-     * identifier they now name.
-     *
-     * A malformed declaration falls back to no parameters, so the identifier keeps
-     * naming the channel instead of the subscription never being created at all.
-     */
+    /** Moves the subscription to the identifier the parameters now name. */
     paramsValueChanged(): void;
     /** Moves the subscription when the declaration names a different channel. */
     channelValueChanged(): void;
@@ -197,6 +192,22 @@ declare class LiveCounterController extends Controller<HTMLElement> {
  * Stream or a morph arrives empty and is drawn from the roster as it connects; the subscription, heartbeat interval,
  * per-peer expiry timers, and the `pagehide` listener are all released on
  * `disconnect()` (Turbo navigation included).
+ *
+ * The live resources follow the declaration; Values changed together move them
+ * once, after the batch, and nothing moves before `connect()` or after
+ * `disconnect()`. A `channel` or `params` change moves the subscription: the room
+ * being left gets the leaving notice under the same rules as `disconnect()`
+ * (confirmed, an own `id`, the last voice for it), and its roster, expiry timers,
+ * pending beacon and announcement, throttle window and rejected hook are dropped
+ * without an event, as a fresh connection would, since none of them is a fact of
+ * the new room. An `id` change keeps the subscription and its roster: the old id's
+ * voice is released once (the last voice leaves), the new id beacons at once —
+ * which also stands in for a convergence answer still queued — and a peer already
+ * listed under the new id is this client now, so it stops being counted without a
+ * `leave`: it went nowhere. A `heartbeat` change re-arms the running interval,
+ * counted from the change. `timeout` arms each peer's expiry when its beacon
+ * arrives, so a change applies from that peer's next beacon and never moves a
+ * deadline already set.
  */
 declare class PresenceController extends Controller<HTMLElement> {
     #private;
@@ -235,6 +246,18 @@ declare class PresenceController extends Controller<HTMLElement> {
             default: string;
         };
     };
+    static valueConstraints: {
+        heartbeat: {
+            readonly finite: true;
+            readonly exclusiveMin: 0;
+            readonly max: 2147483647;
+        };
+        timeout: {
+            readonly finite: true;
+            readonly exclusiveMin: 0;
+            readonly max: 2147483647;
+        };
+    };
     static events: readonly ["join", "leave", "change"];
     readonly hasCountTarget: boolean;
     readonly countTarget: HTMLElement;
@@ -250,13 +273,14 @@ declare class PresenceController extends Controller<HTMLElement> {
     timeoutValue: number;
     announceJoinTextValue: string;
     announceLeaveTextValue: string;
-    /**
-     * 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.
-     */
+    /** Moves the subscription to the declared channel. */
+    channelValueChanged(): void;
+    /** Moves the subscription to the identifier the parameters name. */
     paramsValueChanged(): void;
+    /** Moves this element's voice to the declared id. */
+    idValueChanged(): void;
+    /** Re-arms a running heartbeat on the declared period. */
+    heartbeatValueChanged(): void;
     /**
      * Draws the roster into a list target, which arrives empty from a Turbo Stream
      * replacement or a morph. Stimulus runs this before `connect()` on the first mount
@@ -264,8 +288,12 @@ declare class PresenceController extends Controller<HTMLElement> {
      * preserved is what `connect()` goes on to do anyway.
      */
     listTargetConnected(): void;
+    /** Draws the roster into the list target that stays when an earlier one leaves. */
+    listTargetDisconnected(): void;
     /** Paints the roster size into a count target that arrives blank, for the same reason. */
     countTargetConnected(): void;
+    /** Paints the roster size into the count target that stays when an earlier one leaves. */
+    countTargetDisconnected(): void;
     connect(): void;
     disconnect(): void;
 }
@@ -324,6 +352,22 @@ declare class PresenceController extends Controller<HTMLElement> {
  * from the stream. The subscription, the per-typer timers, and the delegated
  * `input` listener are all released on `disconnect()` (Turbo navigation
  * included).
+ *
+ * The declared `channel` names the subscription: `params` *adds* identifier
+ * parameters except `channel`, which is ignored. Without a declared channel
+ * nothing is subscribed whatever `params` holds.
+ *
+ * The subscription follows the declaration: a `channel` or `params` change moves
+ * it — once, after the batch, however many of the two changed together, and never
+ * before `connect()` or after `disconnect()` — and drops the typers, their expiry
+ * timers, a pending announcement, the throttle window and the rejected hook
+ * without an event, as a fresh connection would, since none of them is a fact of
+ * the new room. A `name` change keeps the subscription and the typers, except one
+ * shown under the new name: that is this client now, so it is dropped with its
+ * expiry and the display redrawn, without a `change` — it did not stop typing.
+ * The own echo is still filtered by the current `name`. `timeout` arms each
+ * typer's expiry when its signal arrives, so a change applies from that typer's
+ * next signal and never moves a deadline already set.
  */
 declare class TypingIndicatorController extends Controller<HTMLElement> {
     #private;
@@ -358,6 +402,17 @@ declare class TypingIndicatorController extends Controller<HTMLElement> {
             default: string;
         };
     };
+    static valueConstraints: {
+        timeout: {
+            readonly finite: true;
+            readonly min: 0;
+            readonly max: 2147483647;
+        };
+        throttle: {
+            readonly finite: true;
+            readonly min: 0;
+        };
+    };
     static events: readonly ["change"];
     readonly hasStatusTarget: boolean;
     readonly statusTarget: HTMLElement;
@@ -368,22 +423,23 @@ declare class TypingIndicatorController extends Controller<HTMLElement> {
     throttleValue: number;
     announceOneTextValue: string;
     announceManyTextValue: string;
-    /**
-     * 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.
-     */
+    /** Moves the subscription to the declared channel. */
+    channelValueChanged(): void;
+    /** Moves the subscription to the identifier the parameters name. */
     paramsValueChanged(): void;
+    /** Stops showing a typer under the name this client now declares. */
+    nameValueChanged(): void;
     /**
      * 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.
+     * set paints the empty copy, so a region that arrives with an old one is cleared.
      */
     statusTargetConnected(): void;
+    /** Paints the current copy, empty when nobody types, into the `status` target that stays. */
+    statusTargetDisconnected(): void;
     connect(): void;
     disconnect(): void;
 }