stimeo-ui 0.10.0 → 0.12.0

package/CHANGELOG.md

@@ -7,6 +7,149 @@ 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.12.0] - 2026-09-06
+
+Minor release with no new components. Six existing ones are reworked — count-up,
+intersection, lazy-frame, reading-progress, smart-sticky-header, and sortable —
+and the number reading count-up gained reaches live-counter too. Most of them
+changed a contract, so read Removed and Changed before upgrading. The Inspector
+manifest stays on schema v12.
+
+### Removed
+
+- sortable: the `status` target, its `data-grabbed` / `data-moved` /
+  `data-dropped` / `data-canceled` templates, and the English fallback wording.
+  Seat a `stimeo--announcer` on the page and set `announceGrabbedText` /
+  `announceMovedText` / `announceDroppedText` / `announceCanceledText`
+  (`{name}` / `{position}` / `{total}`); an unset one announces nothing.
+  `stimeo check` stops asking for the live region and warns when no announcer
+  is seated.
+
+### Changed
+
+- count-up: only the text node holding the number is animated, and while it
+  ticks it is wrapped in a `role="img"` element named with the authored text —
+  the host's own `aria-label` and `role` are never touched, and sibling markup
+  stays where it was.
+- count-up and live-counter read a formatted number by one rule: the first
+  numeric token, group separators dropped, the fraction truncated, and a hyphen
+  a sign only where it opens the token — `"Sign-ups: 1,200"` reads 1200, not
+  -1200.
+- intersection: `0` is always among the observed lines, so a non-zero
+  `threshold` also reports the element leaving for good (one more `change`;
+  `data-passed` and the ratio property follow the departure to its end), and an
+  exit across the start edge reports `position: "before"` while the element
+  still overlaps the root.
+- lazy-frame: a re-fetch needs a genuine re-entry — the frame is seen inside the
+  observed area, leaves it, and comes back; where a connection or a
+  focus-started load first finds it is the baseline. A frame with `once` off is
+  armed again after a cache restore, and `load` names the URL that was fetched.
+- reading-progress: an article with no layout box is not measured, the
+  article's own box is watched so late-settling content re-measures, and the
+  connect frame is the baseline — a restored scroll position does not fire
+  `complete`. Both faces of the custom property are leased: the element's copy
+  is returned on `disconnect()` too, an authored `:root` declaration comes back,
+  and a later writer is left alone.
+- smart-sticky-header: `change` fires on transitions only (connecting is
+  silent), and the `offset` zone is decided ahead of the jitter guard.
+- sortable: insertion is relative to the neighbouring item — the `list`-less
+  markup works and the last slot is after the last item — and a drag signal from
+  a pointer-drag nested inside an item no longer moves the card. The pickup slot
+  is remembered as neighbours, so rows inserted or removed mid-drag shift neither
+  the restore nor `from`; only laid-out siblings take part in pointer following;
+  and a session whose item leaves the item set ends instead of refusing every
+  later grab. pointer-drag consumes `Home` / `End` while grabbed.
+- A declaration that cannot be read falls back to its default: count-up's
+  `duration` / `from`, smart-sticky-header's `offset`, and a `rootSelector` /
+  `containerSelector` that does not parse (intersection, sticky-observer,
+  smart-sticky-header) observes the viewport or the window. Runtime changes to
+  intersection's `threshold`, lazy-frame's `url` / `rootMargin`, and
+  smart-sticky-header's `offset` are followed.
+
+### Fixed
+
+- lazy-frame: focus moving inside a loaded frame no longer re-fetches it, the
+  first intersection after a focus-started load is not a re-entry, and an empty
+  `url` is never written to `src`.
+- intersection: with `once`, a handler calling `refresh()` from `enter` no longer
+  clears the one-shot marker, so a cache restore does not fire `enter` again.
+- reading-progress: hiding a half-read article no longer publishes `1` and
+  `complete`.
+
+## [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,
@@ -856,6 +999,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.12.0]: https://github.com/taiyaky/stimeo-ui/releases/tag/v0.12.0
+[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

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,