stimeo-ui 0.9.0 → 0.11.0

package/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

package/dist/cable/index.d.ts

@@ -28,6 +28,8 @@ import { Controller, Application } from '@hotwired/stimulus';
  * bump is skipped and the broadcast applies the increment exactly once — set
  * `id` (any per-client string, e.g. `SecureRandom.uuid`) for optimistic UX.
  *
+ * `change` dispatches `{ count }`.
+ *
  * @remarks
  * Behavior only — the displayed number IS the state, and the **DOM is the
  * source of truth**: the server renders the initial count into the `value`
@@ -58,8 +60,8 @@ declare class LiveCounterController extends Controller<HTMLElement> {
             default: string;
         };
         params: {
-            type: ObjectConstructor;
-            default: {};
+            type: StringConstructor;
+            default: string;
         };
         id: {
             type: StringConstructor;
@@ -72,8 +74,15 @@ declare class LiveCounterController extends Controller<HTMLElement> {
     readonly valueTarget: HTMLElement;
     readonly triggerTargets: HTMLElement[];
     channelValue: string;
-    paramsValue: Record<string, unknown>;
+    paramsValue: string;
     idValue: 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.
+     */
+    paramsValueChanged(): void;
     connect(): void;
     disconnect(): void;
     /** Late-added triggers (e.g. via a Turbo Stream) pick up the current gate. */
@@ -103,7 +112,7 @@ declare class LiveCounterController extends Controller<HTMLElement> {
  *
  * Roster convergence: a late joiner would otherwise see peers only as their
  * next heartbeats arrive, so on hearing a beacon from an *unknown* peer, each
- * client re-announces itself (throttled to {@link BEACON_THROTTLE_MS}) — the
+ * client re-announces itself (at most one such answer every 2s) — the
  * roster converges in one round-trip instead of one heartbeat period.
  *
  * Markup contract (identifier: `stimeo--presence`):
@@ -125,6 +134,9 @@ declare class LiveCounterController extends Controller<HTMLElement> {
  *       { id: data["id"], name: data["name"], leaving: data["leaving"] })
  *   end
  *
+ * `join` dispatches `{ id, name }`; `leave` dispatches `{ id }`; `change` dispatches
+ * `{ users }`.
+ *
  * @remarks
  * Behavior only — the dot/stack look is the consumer's CSS, keyed off the
  * `data-present` / `data-present-count` hooks. The roster counts and renders
@@ -160,8 +172,8 @@ declare class PresenceController extends Controller<HTMLElement> {
             default: string;
         };
         params: {
-            type: ObjectConstructor;
-            default: {};
+            type: StringConstructor;
+            default: string;
         };
         id: {
             type: StringConstructor;
@@ -188,11 +200,18 @@ declare class PresenceController extends Controller<HTMLElement> {
     readonly hasTemplateTarget: boolean;
     readonly templateTarget: HTMLTemplateElement;
     channelValue: string;
-    paramsValue: Record<string, unknown>;
+    paramsValue: string;
     idValue: string;
     nameValue: string;
     heartbeatValue: number;
     timeoutValue: number;
+    /**
+     * 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(): void;
     connect(): void;
     disconnect(): void;
 }
@@ -201,7 +220,7 @@ declare class PresenceController extends Controller<HTMLElement> {
  * Headless **typing indicator** — a *server-bound* behavior: a controller whose
  * state lives on the server stream, not in client memory. Typing in the composer
  * throttle-broadcasts a `typing` signal over an Action Cable channel; received
- * signals from *other* clients render "X is typing…" into a `status` live region
+ * signals from *other* clients render "X is typing…" into a visible `status` slot
  * and auto-clear after `timeout` ms of silence. The whole behavior is HTML + a
  * broadcast — no app JS, no client store, no reconciler. Ships in the opt-in
  * `stimeo-ui/cable` subpath (`@rails/actioncable` optional peer); the core stays
@@ -211,9 +230,10 @@ declare class PresenceController extends Controller<HTMLElement> {
  *   <div data-controller="stimeo--typing-indicator"
  *        data-stimeo--typing-indicator-channel-value="TypingChannel"
  *        data-stimeo--typing-indicator-params-value='{"room":"chat_42"}'
- *        data-stimeo--typing-indicator-name-value="Alice">
+ *        data-stimeo--typing-indicator-name-value="Alice"
+ *        data-stimeo--typing-indicator-announce-one-text-value="{name} is typing">
  *     <textarea data-stimeo--typing-indicator-target="input"></textarea>
- *     <p role="status" data-stimeo--typing-indicator-target="status"
+ *     <p data-stimeo--typing-indicator-target="status"
  *        data-one="%{name} is typing…" data-many="%{names} are typing…"></p>
  *   </div>
  *
@@ -224,6 +244,14 @@ declare class PresenceController extends Controller<HTMLElement> {
  *                                                     { name: data["name"] })
  *   end
  *
+ * The `status` target is a plain visible slot, not a live region: assistive tech is
+ * reached through the page's shared announcer instead, so a set that settles is sent
+ * there as `announceOneText` / `announceManyText` (`{name}` / `{names}` / `{count}`,
+ * debounced). Both default to empty, and an empty message announces nothing — a page
+ * that wants the indicator seen but not heard simply leaves them off.
+ *
+ * `change` dispatches `{ names }`.
+ *
  * @remarks
  * Behavior only — the indicator's look is the consumer's CSS, keyed off the
  * `data-typing` hook; the copy is localizable through the `data-one` /
@@ -237,7 +265,7 @@ declare class PresenceController extends Controller<HTMLElement> {
  * subscription publishes the `data-typing-indicator-rejected` hook (cleared on
  * `connect()` — rejection is transient server state), mirroring
  * `data-live-counter-rejected`. Typing state is transient by nature:
- * `connect()` resets the hook and the live region (a Turbo cache snapshot must
+ * `connect()` resets the hook and the status slot (a Turbo cache snapshot must
  * not resurrect a stale "X is typing…"), and re-population happens naturally
  * from the stream. The subscription, the per-typer timers, and the delegated
  * `input` listener are all released on `disconnect()` (Turbo navigation
@@ -252,8 +280,8 @@ declare class TypingIndicatorController extends Controller<HTMLElement> {
             default: string;
         };
         params: {
-            type: ObjectConstructor;
-            default: {};
+            type: StringConstructor;
+            default: string;
         };
         name: {
             type: StringConstructor;
@@ -267,15 +295,41 @@ declare class TypingIndicatorController extends Controller<HTMLElement> {
             type: NumberConstructor;
             default: number;
         };
+        announceOneText: {
+            type: StringConstructor;
+            default: string;
+        };
+        announceManyText: {
+            type: StringConstructor;
+            default: string;
+        };
     };
     static events: readonly ["change"];
     readonly hasStatusTarget: boolean;
     readonly statusTarget: HTMLElement;
     channelValue: string;
-    paramsValue: Record<string, unknown>;
+    paramsValue: string;
     nameValue: string;
     timeoutValue: number;
     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.
+     */
+    paramsValueChanged(): 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.
+     */
+    statusTargetConnected(): void;
     connect(): void;
     disconnect(): void;
 }
@@ -346,6 +400,17 @@ interface ConfirmedCableSubscription extends CableSubscription {
  * caller's own handler runs (so a handler reading `subscription.confirmed`
  * sees the post-transition state), and `received` passes straight through.
  *
+ * **Callers with the same identifier (channel + params) share one wire
+ * subscription.** The server confirms an identifier once and silently ignores a
+ * repeated `subscribe` for it, so a second wire subscription would never be
+ * confirmed — its sends would stay gated and the client would keep re-sending
+ * `subscribe` until the next reconnect. Instead every caller is a member of the
+ * identifier's one subscription: lifecycle callbacks and broadcasts fan out to all
+ * members, a member joining an already confirmed (or refused) identifier is told
+ * so on the next microtask — after its caller has stored the returned
+ * subscription, the way a callback from the wire would arrive — and the wire is
+ * unsubscribed when the last member leaves.
+ *
  * This is deliberately a *tracker*, not an automatic `perform()` gate: the
  * controllers must skip the local side effects that surround a send (an
  * optimistic DOM bump, a throttle timestamp) together with the send itself,