npm - stimeo-ui - Versions diffs - 0.11.0 → 0.13.0 - Mend

stimeo-ui 0.11.0 → 0.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (153) hide show

package/CHANGELOG.md CHANGED Viewed

@@ -7,6 +7,111 @@ 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.13.0] - 2026-09-13
+Minor release with no new components. The three server-bound components are
+reworked — live-counter, presence, and optimistic — and each changed a contract,
+so read Changed before upgrading. The Inspector manifest stays on schema v12.
+### Changed
+- live-counter: a broadcast whose `count` or `delta` is not an integer is
+  ignored, a `delta` param that is not an integer falls back to `1`, and a
+  declared `channel` keeps the gate closed until the subscription is confirmed.
+  A delta carrying your own `id` is applied unless an optimistic add of the same
+  size is still outstanding. Runtime changes to `channel` / `params`
+  re-subscribe.
+- presence: a leave notice is sent by the last element claiming that `id` rather
+  than by every element, a `channel` key in `params` no longer overrides the
+  declared `channel`, `heartbeat` / `timeout` fall back to their defaults unless
+  finite, positive and at most 2147483647 — typing-indicator's `timeout` takes
+  the same bound — and `template` clones only its root element.
+- optimistic: `turbo:submit-end` is matched to the submission it names instead of
+  to any ending that reaches the element, so a submission whose ending never
+  arrives no longer strands the element. The `data-optimistic-toggled` marker
+  carries the authored value to restore instead of `"true"`, `aria-busy` gets the
+  same record (`data-optimistic-busy`), and a rollback writes those records back
+  rather than inverting the current value — `hidden="until-found"` no longer
+  degrades to a bare `hidden`, and an element registered for both `show` and
+  `hide` returns to its authored state.
+### Fixed
+- calendar: a malformed `<html lang>` (an `en_US`-style tag that `Intl` rejects)
+  no longer stops the month grid from painting. The month label falls back to
+  English while the 42 cells, the single tab stop, and the `monthchange` /
+  `select` conditions stay as they were; any other failure of the label
+  formatter still propagates.
+## [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
@@ -930,6 +1035,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.13.0]: https://github.com/taiyaky/stimeo-ui/releases/tag/v0.13.0
+[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

package/dist/cable/index.d.ts CHANGED Viewed

@@ -21,12 +21,18 @@ import { Controller, Application } from '@hotwired/stimulus';
  * Wire contract — the broadcast is either **authoritative** or a **delta**:
  * `{ count: 129 }` sets the absolute value (naturally idempotent; preferred —
  * the server owns the number), while `{ delta: 1, by: "17" }` adds to it,
- * skipped when `by` matches this client's `id` (the optimistic increment
- * already applied it). `increment` performs `increment` on the channel with
- * `{ id, delta }`; the server persists and broadcasts. Without an own `id`
- * the delta echo is indistinguishable from a foreign delta, so the optimistic
- * bump is skipped and the broadcast applies the increment exactly once — set
- * `id` (any per-client string, e.g. `SecureRandom.uuid`) for optimistic UX.
+ * skipped when `by` matches this client's `id` **and its amount matches an
+ * optimistic bump this client is still waiting to see echoed**. A counter
+ * holding no such guess — a sibling on the page, this user's other tab, one
+ * stepping by a different amount — applies the delta like any other, so every
+ * display converges. Only whole numbers are accepted: the
+ * display is the state, and a value that cannot be read back from text is not
+ * a count. `increment` performs `increment` on the channel with `{ id, delta }`;
+ * the server persists and broadcasts. Without an own `id` the delta echo is
+ * indistinguishable from a foreign delta, so the optimistic bump is skipped and
+ * the broadcast applies the increment exactly once — set `id` (any per-client,
+ * per-tab string, e.g. `SecureRandom.uuid`) for optimistic UX. Comparing `by`
+ * to `id` is an echo guard, not authentication — identity belongs to the server.
  *
  * `change` dispatches `{ count }`.
  *
@@ -38,7 +44,10 @@ import { Controller, Application } from '@hotwired/stimulus';
  * subscription lifecycle (via the shared confirmation-aware subscription):
  * increments are dropped before confirmation AND while the connection is down
  * (`disconnected` shuts the gate until Action Cable re-confirms), so the
- * display never advances past what the server can receive. A refused
+ * display never advances past what the server can receive. The gate reads the
+ * declaration, not the subscription object: while a `channel` is declared it
+ * stays shut until that subscription confirms, including the window where one
+ * has yet to be opened. A refused
  * subscription publishes the `data-live-counter-rejected` hook (cleared on
  * `connect()` — rejection is transient server state) so the consumer's CSS can
  * disable the trigger. Optional `trigger` targets make that declarative: they
@@ -47,9 +56,15 @@ import { Controller, Application } from '@hotwired/stimulus';
  * required, and a disabled form control is announced as such by AT. An
  * authored `disabled` (set by the consumer for its own reasons) is respected:
  * only a disabled this controller applied — tracked via a marker attribute —
- * is ever lifted. Channel-less (local-only) counters never disable their
- * triggers. There are no timers; the subscription is released on
- * `disconnect()` (Turbo navigation included).
+ * is ever lifted, and it is given back when the controller or the target goes
+ * away. A trigger that holds focus keeps it: the disable waits for it to blur,
+ * since taking focus away mid-outage strands a keyboard user. Channel-less
+ * (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.
  */
 declare class LiveCounterController extends Controller<HTMLElement> {
     #private;
@@ -67,6 +82,10 @@ declare class LiveCounterController extends Controller<HTMLElement> {
             type: StringConstructor;
             default: string;
         };
+        announceText: {
+            type: StringConstructor;
+            default: string;
+        };
     };
     static actions: readonly ["increment"];
     static events: readonly ["change"];
@@ -76,17 +95,23 @@ declare class LiveCounterController extends Controller<HTMLElement> {
     channelValue: string;
     paramsValue: string;
     idValue: string;
+    announceTextValue: string;
     /**
-     * Re-parses the identifier parameters when the declaration changes.
+     * 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.
      */
     paramsValueChanged(): void;
+    /** Moves the subscription when the declaration names a different channel. */
+    channelValueChanged(): void;
     connect(): void;
     disconnect(): void;
     /** Late-added triggers (e.g. via a Turbo Stream) pick up the current gate. */
     triggerTargetConnected(target: HTMLElement): void;
+    /** A trigger that stops being one keeps nothing this controller lent it. */
+    triggerTargetDisconnected(target: HTMLElement): void;
     /**
      * Optimistic local increment: bumps the display immediately, then asks the
      * server to persist and broadcast. The step comes from the action param
@@ -110,6 +135,11 @@ declare class LiveCounterController extends Controller<HTMLElement> {
  * `disconnect()` never runs); a lost notice is caught by the expiry. Ships in
  * the opt-in `stimeo-ui/cable` subpath (`@rails/actioncable` optional peer).
  *
+ * The notice speaks for a *peer*, not for a wire subscription: on `disconnect()`
+ * only the last element claiming a given `id` on a given identifier sends it, so a
+ * sibling that stays mounted keeps the peer in every roster. `pagehide` takes the
+ * whole page with it, so there every element sends and peers absorb the duplicates.
+ *
  * 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 (at most one such answer every 2s) — the
@@ -146,7 +176,11 @@ declare class LiveCounterController extends Controller<HTMLElement> {
  * `data-presence-id`), and the `count` target renders through localizable
  * `data-zero` / `data-one` / `data-other` templates (`%{count}`). Richer
  * per-user rendering (avatars, links) belongs to the consumer via the `join` /
- * `leave` / `change` events or a server-rendered Turbo Stream. The `id`
+ * `leave` / `change` events or a server-rendered Turbo Stream. A `template` holds
+ * one root element: the clone appended for a peer, and the node removed when the
+ * peer goes, are that same element. Roster changes reach assistive tech only when
+ * the consumer opts in through `announceJoinText` / `announceLeaveText` — reading
+ * out every entry and exit of a busy room is noise, so silence is the default. The `id`
  * comparison is display-level echo suppression, not authentication — identity
  * belongs to the server. Sending tracks the full subscription lifecycle (via
  * the shared confirmation-aware subscription): beacons — heartbeats, the
@@ -159,7 +193,8 @@ declare class LiveCounterController extends Controller<HTMLElement> {
  * `data-live-counter-rejected`. Presence is transient: `connect()` clears
  * whatever a Turbo cache snapshot preserved (hooks + rendered clones), renders
  * the known-empty count (the `data-present*` hooks stay absent until the first
- * beacon), and the stream re-populates; the subscription, heartbeat interval,
+ * beacon), and the stream re-populates; a `count` or `list` target swapped in by a
+ * 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).
  */
@@ -191,6 +226,14 @@ declare class PresenceController extends Controller<HTMLElement> {
             type: NumberConstructor;
             default: number;
         };
+        announceJoinText: {
+            type: StringConstructor;
+            default: string;
+        };
+        announceLeaveText: {
+            type: StringConstructor;
+            default: string;
+        };
     };
     static events: readonly ["join", "leave", "change"];
     readonly hasCountTarget: boolean;
@@ -205,6 +248,8 @@ declare class PresenceController extends Controller<HTMLElement> {
     nameValue: string;
     heartbeatValue: number;
     timeoutValue: number;
+    announceJoinTextValue: string;
+    announceLeaveTextValue: string;
     /**
      * Re-parses the identifier parameters when the declaration changes.
      *
@@ -212,6 +257,15 @@ declare class PresenceController extends Controller<HTMLElement> {
      * naming the channel instead of the subscription never being created at all.
      */
     paramsValueChanged(): 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
+     * too, where the roster is still empty and clearing whatever a cache snapshot
+     * preserved is what `connect()` goes on to do anyway.
+     */
+    listTargetConnected(): void;
+    /** Paints the roster size into a count target that arrives blank, for the same reason. */
+    countTargetConnected(): void;
     connect(): void;
     disconnect(): void;
 }