stimeo-ui 0.16.0 → 0.17.0

package/CHANGELOG.md

@@ -7,6 +7,35 @@ 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
@@ -1278,6 +1307,8 @@ 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

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.

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;
 }