@wcstack/speech 1.15.0 → 1.17.0

package/README.ja.md

@@ -164,6 +164,79 @@ export default {
 
 ---
 
+## `:state()` による CSS スタイリング
+
+`<wcs-speak>` と `<wcs-listen>` はそれぞれ、自分自身の boolean 出力ステートを
+[`ElementInternals` の `CustomStateSet`](https://developer.mozilla.org/ja/docs/Web/API/CustomStateSet)
+に反映します。そのため `data-wcs` バインディングやクラスの手動トグルなしに、CSS の
+`:state()` 疑似クラスで直接スタイリングできます。
+
+### `<wcs-speak>`
+
+| ステート | on になる条件 |
+|----------|----------------|
+| `speaking` | `wcs-speak:speaking-changed` が `true` で発火（`false` でクリア） |
+| `paused` | `wcs-speak:paused-changed` が `true` で発火（`false` でクリア） |
+| `pending` | `wcs-speak:pending-changed` が `true` で発火（`false` でクリア） |
+| `unsupported` | `wcs-speak:unsupported-changed` が `true` で発火（`false` でクリア） |
+| `error` | `wcs-speak:error` が非 `null` の detail で発火（`null` でクリア） |
+
+```css
+wcs-speak:state(speaking) ~ .indicator { color: green; }
+wcs-speak:state(unsupported) ~ .fallback { display: block; }
+```
+
+### `<wcs-listen>`
+
+| ステート | on になる条件 |
+|----------|----------------|
+| `listening` | `wcs-listen:listening-changed` が `true` で発火（`false` でクリア） |
+| `unsupported` | `wcs-listen:unsupported-changed` が `true` で発火（`false` でクリア） |
+| `error` | `wcs-listen:error` が非 `null` の detail で発火（`null` でクリア） |
+
+```css
+wcs-listen:state(listening) ~ .mic-indicator { color: red; }
+form:has(wcs-listen:state(error)) .banner { display: block; }
+```
+
+属性やクラスと異なり `:state()` は要素の外部から書き込めないため、この出力ステートが
+入力と混同される心配がありません。
+
+**対応ブラウザ**（新構文 `:state(x)`）: Chrome/Edge 125+、Safari 17.4+、Firefox 126+。
+非対応の環境ではステートが一切 set されないだけです — `:state()` セレクタがマッチしなく
+なりますが、各コンポーネント自体は通常どおり動作し続けます（graceful degradation・
+never-throw）。これは特に `<wcs-listen>` の `unsupported` ステートで意味を持ちます。
+SpeechRecognition 自体が Chrome 系のみの対応だからです（後述の「注意・制限」参照）——
+`:state(unsupported)` はまさに、それ以外のブラウザでフォールバックを表示するために使う
+セレクタです。
+
+**SSR:** `:state()` は HTML にシリアライズできないため、サーバーレンダリングされた
+マークアップの初期ペイントにはこれらのステートは乗りません（`@wcstack/server` は無改変）。
+ハイドレーション前の見た目を制御したい場合は、代わりに
+`wcs-speak:not(:defined)` / `wcs-listen:not(:defined)` と組み合わせてください。
+
+### デバッグ
+
+カスタムステートは DevTools の Elements パネルには表示されず、`attachInternals()`
+は同一要素に 2 回呼べないため、コンソールから直接覗く手段がありません。そのための
+デバッグ専用の補助を 2 つ用意しています:
+
+- `el.debugStates` — 現在 on になっているステート名の**スナップショット**配列
+  （例: `["speaking"]`）。`wc-bindable` の一部ではなく（バインド対象ではない）、
+  形状も契約として保証されません — デバッグ用途にのみ使ってください。
+- `debug-states` 属性（opt-in・既定 OFF）は、ステート変化を要素の
+  `data-wcs-state-*` 属性にミラーします。Elements パネルを開いておけば、
+  トグルのたびにハイライトされます:
+
+  ```html
+  <wcs-speak say="Hello" debug-states></wcs-speak>
+  <wcs-listen debug-states></wcs-listen>
+  ```
+
+**CSS は `data-wcs-state-*` ではなく `:state()` に書いてください。** ミラーされた
+属性は、DevTools を開いた状態でステート変化を可視化するためだけのものであり、
+スタイリング用の正式なフックではありません。
+
 ## 注意・制限
 
 - **セキュアコンテキスト必須。** 両 API とも HTTPS か `localhost` が必要。`<wcs-listen>` はさらにマイク permission が必要です。

package/README.md

@@ -165,6 +165,79 @@ Clicking an element with `data-listentarget="<id>"` toggles `start()` / `stop()`
 
 ---
 
+## CSS styling with `:state()`
+
+`<wcs-speak>` and `<wcs-listen>` each reflect their boolean output states onto
+their own [`ElementInternals` `CustomStateSet`](https://developer.mozilla.org/en-US/docs/Web/API/CustomStateSet),
+so you can style them directly from CSS with the `:state()` pseudo-class — no
+`data-wcs` binding or extra class toggling required.
+
+### `<wcs-speak>`
+
+| State | On when |
+|-------|---------|
+| `speaking` | `wcs-speak:speaking-changed` fires with `true` (cleared on `false`) |
+| `paused` | `wcs-speak:paused-changed` fires with `true` (cleared on `false`) |
+| `pending` | `wcs-speak:pending-changed` fires with `true` (cleared on `false`) |
+| `unsupported` | `wcs-speak:unsupported-changed` fires with `true` (cleared on `false`) |
+| `error` | `wcs-speak:error` fires with a non-`null` detail (cleared on `null`) |
+
+```css
+wcs-speak:state(speaking) ~ .indicator { color: green; }
+wcs-speak:state(unsupported) ~ .fallback { display: block; }
+```
+
+### `<wcs-listen>`
+
+| State | On when |
+|-------|---------|
+| `listening` | `wcs-listen:listening-changed` fires with `true` (cleared on `false`) |
+| `unsupported` | `wcs-listen:unsupported-changed` fires with `true` (cleared on `false`) |
+| `error` | `wcs-listen:error` fires with a non-`null` detail (cleared on `null`) |
+
+```css
+wcs-listen:state(listening) ~ .mic-indicator { color: red; }
+form:has(wcs-listen:state(error)) .banner { display: block; }
+```
+
+Unlike attributes or classes, `:state()` cannot be written from outside the
+element, so there is no risk of confusing this output state with an input.
+
+**Browser support** (`:state(x)` syntax): Chrome/Edge 125+, Safari 17.4+,
+Firefox 126+. In older browsers the states are simply never set — `:state()`
+selectors never match, but the components keep working normally (graceful
+degradation, never-throw). This matters in particular for `<wcs-listen>`'s
+`unsupported` state, since SpeechRecognition itself is Chrome-only (see
+"Notes & limitations" below) — `:state(unsupported)` is exactly the selector
+you would use to show a fallback in every other browser.
+
+**SSR**: `:state()` cannot be serialized into HTML, so server-rendered markup
+never carries these states on first paint (`@wcstack/server` is unaffected).
+If you need to style the pre-hydration gap, pair your rule with
+`wcs-speak:not(:defined)` / `wcs-listen:not(:defined)` instead.
+
+### Debugging
+
+Custom states are invisible in DevTools' Elements panel and `attachInternals()`
+cannot be called twice, so there is no console way to inspect them directly.
+Two debug-only aids are provided for that:
+
+- `el.debugStates` — a **snapshot** array of the currently-on state names
+  (e.g. `["speaking"]`). It is not part of `wc-bindable` (not a bind target)
+  and its shape is not a guaranteed contract — use it for debugging only.
+- The `debug-states` attribute (opt-in, default off) mirrors state changes
+  onto `data-wcs-state-*` attributes on the element, so the Elements panel
+  highlights them as they toggle:
+
+  ```html
+  <wcs-speak say="Hello" debug-states></wcs-speak>
+  <wcs-listen debug-states></wcs-listen>
+  ```
+
+**Write your CSS against `:state()`, not `data-wcs-state-*`.** The mirrored
+attributes exist purely to make state changes visible while debugging with
+DevTools open; they are not a supported styling hook.
+
 ## Notes & limitations
 
 - **Secure context required.** Both APIs need HTTPS or `localhost`; `<wcs-listen>` additionally needs microphone permission.

package/dist/index.d.ts

@@ -346,8 +346,12 @@ declare class WcsSpeak extends HTMLElement {
     private _core;
     private _say;
     private _connectedCallbackPromise;
+    private _internals;
     constructor();
     get connectedCallbackPromise(): Promise<void>;
+    get debugStates(): string[];
+    private _initInternals;
+    private _wireStates;
     get rate(): number;
     set rate(value: number);
     get pitch(): number;
@@ -492,8 +496,12 @@ declare class WcsListen extends HTMLElement {
     private _core;
     private _trigger;
     private _connectedCallbackPromise;
+    private _internals;
     constructor();
     get connectedCallbackPromise(): Promise<void>;
+    get debugStates(): string[];
+    private _initInternals;
+    private _wireStates;
     get lang(): string;
     set lang(value: string | null);
     get continuous(): boolean;

package/dist/index.esm.js

@@ -570,13 +570,75 @@ class WcsSpeak extends HTMLElement {
     _core;
     _say = "";
     _connectedCallbackPromise = Promise.resolve();
+    _internals = null;
     constructor() {
         super();
+        // States are wired BEFORE the Core is constructed (unlike the canonical
+        // Core-then-internals-then-wireStates order): SpeakCore's constructor
+        // synchronously dispatches `wcs-speak:unsupported-changed` when the
+        // SpeechSynthesis API is absent, so the listener must already be attached
+        // to observe that first (and, in a fixed-support environment, only) event.
+        this._internals = this._initInternals();
+        this._wireStates({
+            "wcs-speak:speaking-changed": (d) => ({ speaking: d === true }),
+            "wcs-speak:paused-changed": (d) => ({ paused: d === true }),
+            "wcs-speak:pending-changed": (d) => ({ pending: d === true }),
+            "wcs-speak:unsupported-changed": (d) => ({ unsupported: d === true }),
+            "wcs-speak:error": (d) => ({ error: d != null }),
+        });
         this._core = new SpeakCore(this);
     }
     get connectedCallbackPromise() {
         return this._connectedCallbackPromise;
     }
+    // CSS state reflection (:state()) — debug-only snapshot getter. NOT part of
+    // wc-bindable (not a bind target); see README "CSS styling with :state()".
+    // MUST NOT return the live CustomStateSet (that would let callers write
+    // states from outside, defeating the point of :state() being read-only).
+    get debugStates() {
+        return this._internals ? [...this._internals.states] : [];
+    }
+    _initInternals() {
+        // never-throw (async-io-node-guidelines.md §3.6): attachInternals is absent
+        // in happy-dom / older environments, and pre-125 Chromium rejects
+        // non-dashed state names from states.add() (probed and discarded here).
+        // Either case silently disables reflection — the component still works,
+        // it just doesn't expose :state() selectors.
+        try {
+            if (typeof this.attachInternals !== "function")
+                return null;
+            const internals = this.attachInternals();
+            internals.states.add("wcs-probe");
+            internals.states.delete("wcs-probe");
+            return internals;
+        }
+        catch {
+            return null;
+        }
+    }
+    _wireStates(map) {
+        if (this._internals === null)
+            return;
+        const states = this._internals.states;
+        for (const [event, toStates] of Object.entries(map)) {
+            this.addEventListener(event, (e) => {
+                const debug = this.hasAttribute("debug-states");
+                for (const [name, on] of Object.entries(toStates(e.detail))) {
+                    try {
+                        if (on) {
+                            states.add(name);
+                        }
+                        else {
+                            states.delete(name);
+                        }
+                    }
+                    catch { /* never-throw */ }
+                    if (debug)
+                        this.toggleAttribute(`data-wcs-state-${name}`, on);
+                }
+            });
+        }
+    }
     // --- Attribute accessors ---
     get rate() {
         return this._numberAttr("rate", 1);
@@ -1202,13 +1264,75 @@ class WcsListen extends HTMLElement {
     _core;
     _trigger = false;
     _connectedCallbackPromise = Promise.resolve();
+    _internals = null;
     constructor() {
         super();
+        // States are wired BEFORE the Core is constructed (unlike the canonical
+        // Core-then-internals-then-wireStates order): ListenCore's constructor
+        // synchronously dispatches `wcs-listen:unsupported-changed` when the
+        // SpeechRecognition API is absent (notably Safari, which ships
+        // SpeechSynthesis but not SpeechRecognition), so the listener must already
+        // be attached to observe that first (and, in a fixed-support environment,
+        // only) event.
+        this._internals = this._initInternals();
+        this._wireStates({
+            "wcs-listen:listening-changed": (d) => ({ listening: d === true }),
+            "wcs-listen:unsupported-changed": (d) => ({ unsupported: d === true }),
+            "wcs-listen:error": (d) => ({ error: d != null }),
+        });
         this._core = new ListenCore(this);
     }
     get connectedCallbackPromise() {
         return this._connectedCallbackPromise;
     }
+    // CSS state reflection (:state()) — debug-only snapshot getter. NOT part of
+    // wc-bindable (not a bind target); see README "CSS styling with :state()".
+    // MUST NOT return the live CustomStateSet (that would let callers write
+    // states from outside, defeating the point of :state() being read-only).
+    get debugStates() {
+        return this._internals ? [...this._internals.states] : [];
+    }
+    _initInternals() {
+        // never-throw (async-io-node-guidelines.md §3.6): attachInternals is absent
+        // in happy-dom / older environments, and pre-125 Chromium rejects
+        // non-dashed state names from states.add() (probed and discarded here).
+        // Either case silently disables reflection — the component still works,
+        // it just doesn't expose :state() selectors.
+        try {
+            if (typeof this.attachInternals !== "function")
+                return null;
+            const internals = this.attachInternals();
+            internals.states.add("wcs-probe");
+            internals.states.delete("wcs-probe");
+            return internals;
+        }
+        catch {
+            return null;
+        }
+    }
+    _wireStates(map) {
+        if (this._internals === null)
+            return;
+        const states = this._internals.states;
+        for (const [event, toStates] of Object.entries(map)) {
+            this.addEventListener(event, (e) => {
+                const debug = this.hasAttribute("debug-states");
+                for (const [name, on] of Object.entries(toStates(e.detail))) {
+                    try {
+                        if (on) {
+                            states.add(name);
+                        }
+                        else {
+                            states.delete(name);
+                        }
+                    }
+                    catch { /* never-throw */ }
+                    if (debug)
+                        this.toggleAttribute(`data-wcs-state-${name}`, on);
+                }
+            });
+        }
+    }
     // --- Attribute accessors ---
     get lang() {
         return this.getAttribute("lang") ?? "";