stimeo-ui 0.16.0 → 0.18.0

package/CHANGELOG.md

@@ -7,6 +7,139 @@ 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.18.0] - 2026-10-22
+
+Minor release with no new components. IME composition, Turbo morphs, and form
+submission now behave consistently across the input components, and several
+contracts change, so read Changed before upgrading. The Inspector manifest moves
+to schema v16; update `stimeo check` and the VS Code extension together and run
+`stimeo check` before deploying.
+
+### Added
+
+- time-picker: `amLabel` and `pmLabel` Values set the meridiem text and its
+  speech, and `hour12ZeroBased` shows and enters a twelve-hour clock's hours as
+  0–11, as `午前` / `午後` time is written. The submitted value stays on the
+  24-hour clock.
+
+### Changed
+
+- **Breaking** input-mask: a synchronized hidden field carries a unique internal
+  DOM name; native FormData and native / Turbo submission restore the original
+  name, and removing the source submits an empty entry. Find managed fields by id
+  or the pairing attribute, use native FormData, and call
+  `prepareInputMaskForm(form)` before reading FormData from a new detached form.
+  input-mask clears only the raw value it wrote.
+- **Breaking** otp: a pattern drop held for a composition is reported as
+  `reconcile` before the edit's own `change` / `complete` / `invalid`, and a
+  reconnect under another `pattern` drops what it rejects as `reconcile`. Use the
+  edit events for submission.
+- **Breaking** number-input: a range or step change made during IME composition
+  applies when the user confirms, reported as `change`; a morph that changes
+  neither holds nothing.
+- **Breaking** currency-input: actions and events act only on the first `display`
+  target, and a display already focused when the controller connects starts
+  formatting at its next ordinary edit or composition end. Render the initial
+  hidden and accessible values on the server. `stimeo check` warns about extra
+  displays.
+- **Breaking** tabs, calendar, date-range-picker, slider, range-slider,
+  color-picker, multi-select, and tags-input read the writing direction from their
+  layout targets instead of the root; carousel gains a `pickerList` and
+  navigation-menu a `list` target.
+- **Breaking** dirty-form and optimistic accept only the terminal event matching
+  the latest start's source and token, and only `success: true` succeeds. For a
+  custom save, call `markClean` or dispatch the paired events with `success`.
+- **Breaking** local-time and relative-time read `datetime` strictly: a clock
+  without a zone is UTC (relative-time read it as local time), and an incomplete
+  or invalid value keeps the current display.
+- **Breaking** presence and typing-indicator templates use `{count}`, `{name}`,
+  and `{names}` instead of `%{…}`.
+- **Breaking** modified `Home` / `End` / `PageUp` / `PageDown` go to the browser
+  in widgets without a dedicated binding; pointer-drag cancels a keyboard grab
+  when focus leaves the handle; time-picker accepts digits typed with `Shift`.
+- **Breaking** progress, meter, pointer-drag, countdown, overflow-menu, listbox,
+  submit-once, clipboard, announcer, and currency-input change their ownership
+  markers (pointer-drag: `data-stimeo--pointer-drag-tabindex-loan`, listbox:
+  `owns-label`); re-render persisted HTML from authored markup. progress and meter
+  restore the authored `aria-valuetext` when the template is cleared or the
+  controller disconnects.
+- **Breaking** menubar, navigation-menu, menu, and context-menu treat an entry
+  inside an `aria-disabled="true"` ancestor as disabled (it stays reachable with
+  the arrow keys), and with nested entries refuse an action when any entry holding
+  its target is disabled. A click is judged when it reaches the component, so a
+  handler inside the component that disables its entry during the click keeps the
+  open or close it started; a menubar top it leaves natively `disabled` then has
+  its menu closed again, without a `close` event.
+- **Breaking** pointer-drag: `reset()` returns the inline `translate` to the
+  origin only when `follow` is on; otherwise it cancels the gesture in flight and
+  leaves the author's `translate` alone.
+- toggle-group writes `aria-pressed`, time-picker `aria-valuenow`, and radio-group
+  its arrival and release `tabindex` only when the value changes.
+- context-menu: the region contract drops `aria-haspopup`; give the region a role
+  and name that fit its content and advertise the key with
+  `aria-keyshortcuts="Shift+F10"`.
+- `stimeo check` reports `missing-announcer` for the `stimeo-ui/cable`
+  controllers (live-counter, presence, typing-indicator), and the
+  `stimeo:install` generator writes commented-out pins and registrations for the
+  opt-in `stimeo-ui/cable` and `stimeo-ui/positioning` entry points.
+
+### Removed
+
+- character-counter: the `announceTextValueChanged()` callback is gone from the
+  shipped types; pending announcements still read the current `announceText`.
+
+### Fixed
+
+- IME composition no longer sticks after a page write, a move, or a Turbo morph
+  in auto-submit, character-counter, combobox, command-palette, currency-input,
+  editable, input-mask, multi-select, number-input, otp, tags-input, and toolbar.
+  A morph leaves a field mid-composition alone, and a focused draft survives
+  morphs and reconnection.
+- switch, otp, currency-input, and input-mask keep their hidden form values right
+  across Turbo morphs and removal.
+- State events and reconciliation stay right when a `change` listener disconnects
+  the controller or the page edits state during a repair.
+- Components release what an earlier connection registered when connected twice,
+  and keep authored text, ARIA, and tab stops through restores.
+- relative-time follows live `datetime` changes; template substitution leaves
+  inherited names such as `{constructor}` unchanged.
+- menubar, navigation-menu, menu, and context-menu refuse a `hidden`, natively
+  `disabled`, or `aria-disabled` entry on every route — an explicit element, any
+  event, or hover — as a click on it already was; `context-menu#activate` takes
+  the optional event.
+- The MCP server accepts JSON-RPC batches in sessions that negotiated protocol
+  version 2025-03-26; other versions, and batches before `initialize`, are still
+  rejected.
+
+## [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 +1411,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.18.0...HEAD
+[0.18.0]: https://github.com/taiyaky/stimeo-ui/releases/tag/v0.18.0
+[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

@@ -15,9 +15,9 @@
 owns the look entirely.
 
 - Lean by design: the **core** needs only `@hotwired/stimulus` at runtime (kept
-  external in the build). The opt-in `stimeo-ui/positioning` module is the one
-  exception — it uses `@floating-ui/dom` (an optional **peer dependency**; see the
-  Peer dependencies note below).
+  external in the build). Two opt-in subpaths each add one optional **peer
+  dependency**: `stimeo-ui/positioning` (`@floating-ui/dom`) and `stimeo-ui/cable`
+  (`@rails/actioncable`); see the Peer dependencies note below.
 - Accessibility first: every controller follows the relevant WAI-ARIA APG pattern
   and the related WCAG 2.2 AA criteria.
 - Public controller identifiers use the `stimeo--` namespace (e.g.
@@ -36,8 +36,12 @@ bin/rails generate stimeo:install
 ```
 
 The generator vendors the prebuilt JS into `vendor/javascript/stimeo/`, pins
-`stimeo-ui` in `config/importmap.rb`, and registers all controllers with your
-Stimulus application. Then drive components from HTML alone:
+`stimeo-ui` in `config/importmap.rb`, and registers the core controllers with your
+Stimulus application (`app/javascript/controllers/stimeo.js`). It writes the opt-in
+`stimeo-ui/positioning` and `stimeo-ui/cable` entry points into those two files
+commented out; to enable one, uncomment its lines. The cable lines include the pin
+for its `@rails/actioncable` peer; positioning also needs a pin for
+`@floating-ui/dom`. Then drive components from HTML alone:
 
 ```erb
 <div data-controller="stimeo--dropdown">
@@ -58,15 +62,26 @@ import { Application } from "@hotwired/stimulus";
 import { registerStimeo } from "stimeo-ui";
 
 const application = Application.start();
-registerStimeo(application); // registers every stimeo--* controller
+registerStimeo(application); // registers every controller of the core entry point
 ```
 
+The opt-in `stimeo-ui/positioning` and `stimeo-ui/cable` entry points register
+theirs with `registerPositioning` / `registerCable`.
+
 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.
-  work without it via the default flow layout).
+  work without it via the default flow layout), and `@rails/actioncable` (only if
+  you use the opt-in `stimeo-ui/cable` module).
 - **No CSS is shipped.** Style the components yourself; controllers only toggle
   ARIA state and `data-*` hooks.
 
@@ -111,8 +126,9 @@ keep the rules on everywhere else. For Biome:
 The `eslint-plugin-jsx-a11y` equivalents are
 `no-noninteractive-element-to-interactive-role`, `no-redundant-roles`,
 `prefer-tag-over-role`, `interactive-supports-focus`, and
-`no-noninteractive-tabindex`. These components' real accessibility is exercised
-with axe-core and real screen readers in this project's own test suite.
+`no-noninteractive-tabindex`. This repository's tests check these components
+with axe-core and with a virtual screen reader for speech order; neither stands
+in for a real screen reader on your own pages.
 
 ## Composing components
 
@@ -272,7 +288,7 @@ or in `.mcp.json` (Claude Code) / `.cursor/mcp.json` (Cursor):
 It exposes four read-only tools — `stimeo_check` (validate a source string),
 `stimeo_catalog`, `stimeo_controller` (one controller's full contract,
 accessibility requirements included), and `stimeo_example` (verified example
-markup: the official catalog demo under [`examples/`](examples/), bundled at
+markup: the controller's demo under [`examples/`](examples/), bundled at
 build time and guaranteed to pass the checker) — plus MCP resources
 (`stimeo://manifest`, `stimeo://examples/<id>`) for preloading context without
 a tool round-trip. The server reads only its bundled manifest and example

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;
@@ -150,7 +145,7 @@ declare class LiveCounterController extends Controller<HTMLElement> {
  *        data-stimeo--presence-channel-value="PresenceChannel"
  *        data-stimeo--presence-params-value='{"room":"doc_7"}'
  *        data-stimeo--presence-id-value="17" data-stimeo--presence-name-value="Alice">
- *     <span data-stimeo--presence-target="count" data-other="%{count} viewing"></span>
+ *     <span data-stimeo--presence-target="count" data-other="{count} viewing"></span>
  *     <ul data-stimeo--presence-target="list"></ul>
  *     <template data-stimeo--presence-target="template">
  *       <li><span data-presence-name></span></li>
@@ -174,7 +169,7 @@ declare class LiveCounterController extends Controller<HTMLElement> {
  * `template` pair, one clone per peer is appended (elements marked
  * `data-presence-name` receive the name; the clone root is tagged
  * `data-presence-id`), and the `count` target renders through localizable
- * `data-zero` / `data-one` / `data-other` templates (`%{count}`). Richer
+ * `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. A `template` holds
  * one root element: the clone appended for a peer, and the node removed when the
@@ -194,9 +189,26 @@ declare class LiveCounterController extends Controller<HTMLElement> {
  * 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; 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).
+ * 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 +247,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 +274,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 +289,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;
 }
@@ -288,7 +317,7 @@ declare class PresenceController extends Controller<HTMLElement> {
  *        data-stimeo--typing-indicator-announce-one-text-value="{name} is typing">
  *     <textarea data-stimeo--typing-indicator-target="input"></textarea>
  *     <p data-stimeo--typing-indicator-target="status"
- *        data-one="%{name} is typing…" data-many="%{names} are typing…"></p>
+ *        data-one="{name} is typing…" data-many="{names} are typing…"></p>
  *   </div>
  *
  * Server contract (a trivial rebroadcast channel):
@@ -309,8 +338,8 @@ declare class PresenceController extends Controller<HTMLElement> {
  * @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` /
- * `data-many` templates (`%{name}` / `%{names}` / `%{count}`, terse English
- * fallback — the same channel design as `stimeo--sortable`). The own echo is
+ * `data-many` templates (`{name}` / `{names}` / `{count}`), with terse English
+ * as the fallback. The own echo is
  * dropped by comparing the broadcast `name` against `name` (a same-name guard,
  * not authentication — identity belongs to the server). Sending tracks the full
  * subscription lifecycle (via the shared confirmation-aware subscription):
@@ -324,6 +353,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 +403,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 +424,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;
 }