stimeo-ui 0.1.0-beta.1 → 0.1.0-beta.2

package/CHANGELOG.md

@@ -7,6 +7,44 @@ 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.1.0-beta.2] - 2026-07-12
+
+The Inspector grows two new faces: an MCP server for AI coding agents and a
+VS Code extension that checks markup as you type.
+
+### Added
+
+- **MCP server** (`stimeo-ui mcp`): the Inspector engine now runs as a Model
+  Context Protocol server, so AI coding agents (Claude Code, Cursor, …) can
+  discover the catalog, fetch a controller's exact contract and verified
+  example markup, and check generated HTML/ERB before presenting it. Four
+  read-only tools (`stimeo_check`, `stimeo_catalog`, `stimeo_controller`,
+  `stimeo_example`), preloadable resources (`stimeo://manifest`,
+  `stimeo://examples/<id>`), and two prompts (`stimeo_build_ui`,
+  `stimeo_fix_markup`) — hand-written like the rest of the Inspector, adding
+  zero runtime dependencies.
+- **VS Code extension — Stimeo UI Inspector**: live diagnostics, quick fixes,
+  manifest-driven completions, and contract hovers for `stimeo--*` markup in
+  HTML/ERB, published on the
+  [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=stimeo-labs.stimeo-ui)
+  and [Open VSX](https://open-vsx.org/extension/stimeo-labs/stimeo-ui).
+- Ten new components — the catalog now spans **111 controllers**: count-up,
+  intersection, optimistic, pointer-drag, reading-progress,
+  smart-sticky-header, sortable, and — backed by Action Cable — live-counter,
+  presence, and typing-indicator.
+- pointer-drag: opt-in follow mode that translates the dragged element while
+  the pointer moves.
+- Inspector: checks now also cover keyboard-focusability prerequisites,
+  controller-managed ARIA that must not be hardcoded, and conditional
+  cross-controller composition rules (manifest schema v5). Verified example
+  markup for every component ships with the package.
+
+### Fixed
+
+- listbox, combobox, and multi-select: the active option now scrolls into
+  view while navigating with the keyboard (`aria-activedescendant` lists
+  keep the highlighted option visible).
+
 ## [0.1.0-beta.1] - 2026-06-30
 
 First beta. The 101 core components meet the accessibility quality bar, so the
@@ -32,5 +70,6 @@ Initial public alpha: 101 behavior-only, accessible Stimulus controllers driven
 by `data-*` attributes, shipping no CSS. Published to npm (with provenance) and
 RubyGems.
 
+[0.1.0-beta.2]: https://github.com/taiyaky/stimeo-ui/releases/tag/v0.1.0-beta.2
 [0.1.0-beta.1]: https://github.com/taiyaky/stimeo-ui/releases/tag/v0.1.0-beta.1
 [0.1.0-alpha.1]: https://github.com/taiyaky/stimeo-ui/releases/tag/v0.1.0-alpha.1

package/README.md

@@ -31,7 +31,7 @@ owns the look entirely.
 ### Rails with importmap (recommended)
 
 ```bash
-bundle add stimeo-ui --version "0.1.0.pre.beta.1"
+bundle add stimeo-ui --version "0.1.0.pre.beta.2"
 bin/rails generate stimeo:install
 ```
 
@@ -114,12 +114,72 @@ The `eslint-plugin-jsx-a11y` equivalents are
 `no-noninteractive-tabindex`. These components' real accessibility is exercised
 with axe-core and real screen readers in this project's own test suite.
 
+## Inspector CLI & MCP server
+
+Stimeo UI bundles a zero-dependency static checker for its own markup contract
+— spelling of controllers/targets/values, required structure, and the ARIA
+attributes you (the author) must supply:
+
+```bash
+npx stimeo-ui check app/views    # check your templates (exit 1 on errors)
+npx stimeo-ui catalog            # list every controller's public API
+```
+
+Both commands accept `--json` for machine-readable output, so `check` drops
+straight into CI.
+
+The same engine runs as a **Model Context Protocol** server, so AI coding
+agents (Claude Code, Cursor, …) can discover the catalog, fetch verified
+reference markup, and validate generated HTML/ERB before presenting it:
+
+```bash
+claude mcp add stimeo -- npx -y stimeo-ui mcp
+```
+
+or in `.mcp.json` (Claude Code) / `.cursor/mcp.json` (Cursor):
+
+```json
+{
+  "mcpServers": {
+    "stimeo": {
+      "command": "npx",
+      "args": ["-y", "stimeo-ui", "mcp"]
+    }
+  }
+}
+```
+
+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
+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
+index; there are no write-capable tools.
+
+The same checks also run **live in your editor**: the **Stimeo UI Inspector**
+extension on the
+[VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=stimeo-labs.stimeo-ui)
+and [Open VSX](https://open-vsx.org/extension/stimeo-labs/stimeo-ui) (for Cursor /
+VSCodium / Windsurf) gives as-you-type diagnostics, quick fixes, completions,
+and contract hovers. No setup: the engine and a manifest snapshot are bundled,
+and when your workspace installs `stimeo-ui`, the nearest installed version
+wins — so diagnostics always match what you run.
+
 ## Contributing
 
 Bug reports and feature requests are very welcome — please open a GitHub issue.
 For code changes, open an issue first to discuss direction; see
 [`CONTRIBUTING.md`](CONTRIBUTING.md).
 
-## License
+## License & Pro
+
+Free and open source under the [MIT License](LICENSE) © Stimeo Labs. Every
+component in this repository is Core, and the MIT grant is irrevocable.
 
-Released under the [MIT License](LICENSE) © Stimeo Labs.
+**Stimeo UI Pro** — advanced behavior components that are the most work to
+build yourself — is planned around 1.0 as a separately licensed commercial
+track, built alongside (never carved out of) Core. For release news and
+early access, join the waitlist at
+[stimeo-labs.com/waitlist](https://stimeo-labs.com/waitlist).

package/dist/cable/index.d.ts

@@ -0,0 +1,391 @@
+import { Controller, Application } from '@hotwired/stimulus';
+
+/**
+ * Headless **live counter** — the third *server-bound* behavior: a
+ * number bound to an Action Cable stream (likes, views, active users) that
+ * ticks across every connected client. A local action applies an **optimistic**
+ * increment immediately, then reconciles with the broadcast; the own echo of a
+ * delta broadcast is deduped so the increment is never applied twice. Ships in
+ * the opt-in `stimeo-ui/cable` subpath (`@rails/actioncable` optional peer).
+ *
+ * Markup contract (identifier: `stimeo--live-counter`):
+ *   <div data-controller="stimeo--live-counter"
+ *        data-stimeo--live-counter-channel-value="LikesChannel"
+ *        data-stimeo--live-counter-params-value='{"post":42}'
+ *        data-stimeo--live-counter-id-value="<%= SecureRandom.uuid %>">
+ *     <span data-stimeo--live-counter-target="value">128</span>
+ *     <button type="button" data-action="stimeo--live-counter#increment"
+ *             data-stimeo--live-counter-target="trigger">♥</button>
+ *   </div>
+ *
+ * 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.
+ *
+ * @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`
+ * target (the element itself without one), so a Turbo cache restore needs no
+ * reconciliation and `connect()` only (re)subscribes. Sending tracks the full
+ * 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
+ * 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
+ * carry the real `disabled` attribute exactly while an increment would be
+ * dropped (before confirmation, during an outage, after a rejection) — no CSS
+ * 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).
+ */
+declare class LiveCounterController extends Controller<HTMLElement> {
+    #private;
+    static targets: string[];
+    static values: {
+        channel: {
+            type: StringConstructor;
+            default: string;
+        };
+        params: {
+            type: ObjectConstructor;
+            default: {};
+        };
+        id: {
+            type: StringConstructor;
+            default: string;
+        };
+    };
+    static actions: readonly ["increment"];
+    static events: readonly ["change"];
+    readonly hasValueTarget: boolean;
+    readonly valueTarget: HTMLElement;
+    readonly triggerTargets: HTMLElement[];
+    channelValue: string;
+    paramsValue: Record<string, unknown>;
+    idValue: string;
+    connect(): void;
+    disconnect(): void;
+    /** Late-added triggers (e.g. via a Turbo Stream) pick up the current gate. */
+    triggerTargetConnected(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
+     * (`data-stimeo--live-counter-delta-param`), default 1. Bound via `data-action`.
+     */
+    increment(event?: Event & {
+        params?: {
+            delta?: number;
+        };
+    }): void;
+}
+
+/**
+ * Headless **presence** — the second *server-bound* behavior: online
+ * dots / a "who's viewing this" stack, bound to an Action Cable channel. Like
+ * `stimeo--typing-indicator`, the server stays a trivial rebroadcast channel
+ * with **zero presence state**: every client heartbeats an `appear` beacon
+ * (`{ id, name }`), and each client expires peers it has not heard from for
+ * `timeout` ms. Leaving (`{ id, leaving: true }`) is broadcast best-effort on
+ * `disconnect()` and on `pagehide` (tab close / hard navigation, where
+ * `disconnect()` never runs); a lost notice is caught by the expiry. Ships in
+ * the opt-in `stimeo-ui/cable` subpath (`@rails/actioncable` optional peer).
+ *
+ * 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
+ * roster converges in one round-trip instead of one heartbeat period.
+ *
+ * Markup contract (identifier: `stimeo--presence`):
+ *   <div data-controller="stimeo--presence"
+ *        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>
+ *     <ul data-stimeo--presence-target="list"></ul>
+ *     <template data-stimeo--presence-target="template">
+ *       <li><span data-presence-name></span></li>
+ *     </template>
+ *   </div>
+ *
+ * Server contract (a trivial rebroadcast channel):
+ *   class PresenceChannel < ApplicationCable::Channel
+ *     def subscribed = stream_from "presence:#{params[:room]}"
+ *     def appear(data) = ActionCable.server.broadcast("presence:#{params[:room]}",
+ *       { id: data["id"], name: data["name"], leaving: data["leaving"] })
+ *   end
+ *
+ * @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
+ * **other** clients (`id` ≠ own `id`); rendering is optional: given a `list` +
+ * `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
+ * per-user rendering (avatars, links) belongs to the consumer via the `join` /
+ * `leave` / `change` events or a server-rendered Turbo Stream. 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
+ * convergence answer, the leaving notice — are dropped before confirmation and
+ * while the connection is down, where Action Cable would discard them anyway
+ * (and a discarded beacon must not burn the convergence throttle); `connected`
+ * re-fires on every reconnect and force-beacons, so the roster self-heals. A
+ * refused subscription publishes the `data-presence-rejected` hook (cleared on
+ * `connect()` — rejection is transient server state), mirroring
+ * `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,
+ * per-peer expiry timers, and the `pagehide` listener are all released on
+ * `disconnect()` (Turbo navigation included).
+ */
+declare class PresenceController extends Controller<HTMLElement> {
+    #private;
+    static targets: string[];
+    static values: {
+        channel: {
+            type: StringConstructor;
+            default: string;
+        };
+        params: {
+            type: ObjectConstructor;
+            default: {};
+        };
+        id: {
+            type: StringConstructor;
+            default: string;
+        };
+        name: {
+            type: StringConstructor;
+            default: string;
+        };
+        heartbeat: {
+            type: NumberConstructor;
+            default: number;
+        };
+        timeout: {
+            type: NumberConstructor;
+            default: number;
+        };
+    };
+    static events: readonly ["join", "leave", "change"];
+    readonly hasCountTarget: boolean;
+    readonly countTarget: HTMLElement;
+    readonly hasListTarget: boolean;
+    readonly listTarget: HTMLElement;
+    readonly hasTemplateTarget: boolean;
+    readonly templateTarget: HTMLTemplateElement;
+    channelValue: string;
+    paramsValue: Record<string, unknown>;
+    idValue: string;
+    nameValue: string;
+    heartbeatValue: number;
+    timeoutValue: number;
+    connect(): void;
+    disconnect(): void;
+}
+
+/**
+ * Headless **typing indicator** — the first *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 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 zero-dep.
+ *
+ * Markup contract (identifier: `stimeo--typing-indicator`):
+ *   <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">
+ *     <textarea data-stimeo--typing-indicator-target="input"></textarea>
+ *     <p role="status" data-stimeo--typing-indicator-target="status"
+ *        data-one="%{name} is typing…" data-many="%{names} are typing…"></p>
+ *   </div>
+ *
+ * Server contract (a trivial rebroadcast channel):
+ *   class TypingChannel < ApplicationCable::Channel
+ *     def subscribed = stream_from "typing:#{params[:room]}"
+ *     def typing(data) = ActionCable.server.broadcast("typing:#{params[:room]}",
+ *                                                     { name: data["name"] })
+ *   end
+ *
+ * @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
+ * 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):
+ * signals are dropped before confirmation and while the connection is down, so
+ * an outage never burns the throttle window on undeliverable sends. A refused
+ * 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
+ * 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
+ * included).
+ */
+declare class TypingIndicatorController extends Controller<HTMLElement> {
+    #private;
+    static targets: string[];
+    static values: {
+        channel: {
+            type: StringConstructor;
+            default: string;
+        };
+        params: {
+            type: ObjectConstructor;
+            default: {};
+        };
+        name: {
+            type: StringConstructor;
+            default: string;
+        };
+        timeout: {
+            type: NumberConstructor;
+            default: number;
+        };
+        throttle: {
+            type: NumberConstructor;
+            default: number;
+        };
+    };
+    static events: readonly ["change"];
+    readonly hasStatusTarget: boolean;
+    readonly statusTarget: HTMLElement;
+    channelValue: string;
+    paramsValue: Record<string, unknown>;
+    nameValue: string;
+    timeoutValue: number;
+    throttleValue: number;
+    connect(): void;
+    disconnect(): void;
+}
+
+/**
+ * Minimal structural view of an Action Cable subscription — the two members the
+ * server-bound controllers use. Keeping our own narrow interface (instead of
+ * re-exporting the full `@rails/actioncable` types) lets consumers hand us any
+ * structurally compatible object, including test doubles.
+ */
+interface CableSubscription {
+    /** Invokes a channel action on the server (`ChannelName#action`). */
+    perform(action: string, data?: Record<string, unknown>): void;
+    /** Cancels the subscription (the channel's `unsubscribed` runs server-side). */
+    unsubscribe(): void;
+}
+/** The mixin a controller passes to {@link CableConsumer.subscriptions}' create. */
+interface CableSubscriptionMixin {
+    /** Called once the subscription is confirmed (`perform` is deliverable). */
+    connected?(): void;
+    /**
+     * Called when the connection drops — perform() is silently undeliverable
+     * until Action Cable reconnects and re-confirms (`connected` fires again).
+     */
+    disconnected?(): void;
+    /** Called when the server refuses the subscription (it will never confirm). */
+    rejected?(): void;
+    /** Called with each broadcast the channel transmits to this client. */
+    received?(data: unknown): void;
+}
+/** Minimal structural view of an Action Cable consumer (the websocket owner). */
+interface CableConsumer {
+    subscriptions: {
+        create(channel: string | Record<string, unknown>, mixin: CableSubscriptionMixin): CableSubscription;
+    };
+}
+/**
+ * Replaces (or clears, with `null`) the shared Action Cable consumer.
+ *
+ * Call this once at boot when the app already owns a consumer (the usual
+ * `app/javascript/channels/consumer.js`), so the server-bound controllers reuse
+ * its websocket instead of opening a second one. Tests use it to inject a
+ * double. With `null`, the next {@link getCableConsumer} lazily re-creates one.
+ */
+declare function setCableConsumer(consumer: CableConsumer | null): void;
+/**
+ * The shared Action Cable consumer, lazily created on first use via
+ * `createConsumer()` (which reads the standard `action_cable_meta_tag` URL).
+ */
+declare function getCableConsumer(): CableConsumer;
+/**
+ * A {@link CableSubscription} that also tracks its confirmation lifecycle.
+ * Action Cable silently drops a `perform()` sent before the subscription is
+ * confirmed or while the connection is down — every server-bound controller
+ * must therefore gate its sends (and their local side effects: optimistic
+ * updates, throttle bookkeeping) on {@link confirmed}.
+ */
+interface ConfirmedCableSubscription extends CableSubscription {
+    /** True while the subscription is confirmed — `perform()` is deliverable. */
+    readonly confirmed: boolean;
+    /** True once the server refused the subscription (it will never confirm). */
+    readonly rejected: boolean;
+}
+/**
+ * Creates a subscription on the shared consumer with confirmation tracking
+ * layered over the caller's mixin: `connected` / `disconnected` / `rejected`
+ * flip the {@link ConfirmedCableSubscription.confirmed} flag *before* the
+ * caller's own handler runs (so a handler reading `subscription.confirmed`
+ * sees the post-transition state), and `received` passes straight through.
+ *
+ * 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,
+ * which only the call site can decide — so they check `confirmed` and bail
+ * before any of it.
+ */
+declare function createConfirmedSubscription(channel: string | Record<string, unknown>, mixin: CableSubscriptionMixin): ConfirmedCableSubscription;
+
+/**
+ * Opt-in **server-bound** behaviors for Stimeo — controllers whose state lives
+ * on an Action Cable / Turbo stream rather than in client memory: presence,
+ * typing indicators, live counters.
+ *
+ * **Why this is a separate entry point.** The core library is zero-runtime-dep:
+ * `import "stimeo-ui"` pulls in nothing but `@hotwired/stimulus`. Binding the
+ * DOM to a server stream genuinely needs `@rails/actioncable`, so — exactly
+ * like `stimeo-ui/positioning` and `@floating-ui/dom` — that cost is opt-in:
+ * this module lives at `stimeo-ui/cable`, `@rails/actioncable` is an *optional*
+ * peer, and nothing in the core imports it.
+ *
+ * When the app already owns a consumer (`app/javascript/channels/consumer.js`),
+ * hand it over once at boot so no second websocket is opened:
+ *
+ * ```ts
+ * import consumer from "./channels/consumer";
+ * import { registerCable, setCableConsumer } from "stimeo-ui/cable";
+ *
+ * setCableConsumer(consumer);
+ * registerCable(application);
+ * ```
+ */
+declare const cableControllers: {
+    readonly "stimeo--live-counter": typeof LiveCounterController;
+    readonly "stimeo--presence": typeof PresenceController;
+    readonly "stimeo--typing-indicator": typeof TypingIndicatorController;
+};
+/**
+ * Registers the opt-in server-bound controllers on a Stimulus Application
+ * (additive to `registerStimeo`, mirroring `registerPositioning`).
+ */
+declare function registerCable(application: Application): void;
+
+export { type CableConsumer, type CableSubscription, type CableSubscriptionMixin, type ConfirmedCableSubscription, LiveCounterController, PresenceController, TypingIndicatorController, cableControllers, createConfirmedSubscription, getCableConsumer, registerCable, setCableConsumer };