@pie-players/pie-tool-tts-inline 0.3.74 → 1.0.0-beta.0

package/README.md

@@ -15,7 +15,7 @@ focuses on the inline custom element API.
 - Play/pause trigger that opens the expanded panel when reading starts
 - Expanded controls: configurable Speed options, Rewind, Fast-forward, Stop
 - Play button switches to Pause while reading
-- Panel remains open while reading and closes on Stop
+- Panel stays open while reading and after a read ends on its own; it closes on Stop or when the host calls `TTSService.stop()`
 - Arrow-key navigation within the controls toolbar
 - Takes its services from the toolkit runtime context and its reading scope from the enclosing item or passage shell
 - Integrates with `TTSService` for QTI 3.0 catalog-based TTS
@@ -31,13 +31,14 @@ bun add @pie-players/pie-tool-tts-inline
 
 ## Usage
 
-The element renders inside `<pie-item-shell>` or `<pie-passage-shell>` under
-`<pie-assessment-toolkit>`. The toolkit runtime context supplies the TTS
-service, the highlight coordinator and the toolkit coordinator, and the shell
-supplies the content to read; section players provide both. The packaged
+The element renders inside `<pie-item-scope>` or `<pie-passage-shell>` under
+`<pie-assessment-toolkit>`. The toolkit runtime context supplies the TTS service,
+the highlight coordinator and the toolkit coordinator, and the shell supplies the
+content to read. Section players provide both; around a plain item player, the
+host writes the toolkit and the scope. The packaged
 `textToSpeech` capability in `@pie-players/pie-default-tool-loaders` creates
-this element in item and passage toolbars, takes `catalog-id`, `language` and
-`size` from the toolbar, and takes `layout-mode`, `speedOptions` and
+this element in item and passage toolbars, takes `catalog-id` and `size` from
+the toolbar, and takes `layout-mode`, `speedOptions` and
 `showSingleSpeedOption` from the toolkit's `textToSpeech` tool configuration.
 
 ```javascript
@@ -73,9 +74,8 @@ passageHeader.append(ttsButton);
 ### HTML Attributes
 
 - `catalog-id` - QTI 3.0 accessibility catalog ID for SSML lookup (default: `''`)
-- `language` - Language code for TTS (default: `'en-US'`)
 - `size` - Icon size: `'sm'` (1.5rem), `'md'` (2rem), or `'lg'` (2.5rem) (default: `'md'`)
-- `layout-mode` - Panel placement (default: `'expanding-row'`). `'reserved-row'`
+- `layout-mode` - Panel placement (default: `'left-aligned'`). `'reserved-row'`
   and `'expanding-row'` drop the panel below the trigger; in the packaged toolbar
   the first keeps the controls row reserved and the second expands it while the
   panel is open. `'floating-overlay'` and `'left-aligned'` open the panel as an
@@ -132,21 +132,20 @@ Semantics:
 
 ## Behavior
 
-1. **Services**: Reads `ttsService`, `highlightCoordinator` and `toolkitCoordinator` from the toolkit runtime context; the controls stay disabled until a `ttsService` arrives, and starting playback awaits `toolkitCoordinator.ensureTTSReady()`
-2. **Text Extraction**: Reads the `textContent` of the scope element (the region scope, else the shell scope) when it is `[data-region='content']`, else of its first `[data-region='content']` descendant, else of the scope element itself
-3. **TTS Trigger**: Calls `ttsService.speak(text, { catalogId, catalogContext, language, contentElement })`, where `contentElement` is that reading target and `catalogContext` names the owning item or passage
+1. **Services**: Reads `ttsService`, `highlightCoordinator` and `toolkitCoordinator` from the toolkit runtime context; the controls stay disabled until a `ttsService` arrives. A read started before the service is ready waits on the service's readiness gate, and a failure there announces that text-to-speech could not initialize
+2. **Text Extraction**: Reads the text of the scope element's content region (the region scope, else the shell scope, when it is `[data-region='content']`, else its first `[data-region='content']` descendant, else the scope element itself), including text rendered into open shadow roots
+3. **TTS Trigger**: Calls `ttsService.speak(readingTarget, { ownerId, rate, catalogId, catalogContext, language })`, where `ownerId` names this instance, `rate` is the selected speed, `catalogContext` names the owning item or passage and `language` is the toolkit's `content-language`. The service decides whether anything is speakable, cards included; a read that settles without playing closes the panel and announces that there is nothing to read. `speak` resolves the read's language from it as [TTS language](../../docs/architecture/internationalization.md#tts-language) sets out
 4. **Catalog Resolution**: TTSService checks for SSML in accessibility catalogs (priority order):
    - **Extracted catalogs** (from embedded SSML) - generated before render by hosts that run `SSMLExtractor`
    - **Item-level catalogs** (manually authored)
    - **Assessment-level catalogs** (manually authored)
-   - **Plain text fallback** (browser TTS)
+   - **Generated speech** - MathML speech, else the visible text, on any backend
 5. **Expanded Controls**:
    - The trigger starts, pauses and resumes reading; starting opens the panel
-   - Starting one instance stops playback another instance owns and closes that instance's panel
+   - The instance owns the service's run its read started (`getRunOwner()`); a read started by anything else, another instance or a selection read, closes its panel
    - Stop halts playback and closes the panel
    - Fast-forward/Rewind call `seekForward(1)` / `seekBackward(1)` on the TTS service, one sentence per press, and are enabled only while reading
-   - Speed buttons call `ttsService.setPlaybackRate(rate)` when available,
-     otherwise `ttsService.updateSettings({ rate })`
+   - Speed buttons call `ttsService.setPlaybackRate(rate)`
    - Speed choices render as a named `Playback speed` radio group with
      `aria-checked` state
    - Selecting another speed switches the active radio to that option
@@ -155,7 +154,7 @@ Semantics:
      reset to `1x` while rewind/forward/stop still render
 6. **Keyboard Interaction**: Arrow keys, Home and End move focus within one cluster, either the speed radio group or the Rewind/Fast-forward/Stop buttons, and skip disabled controls; arrowing onto a speed also selects it. Every control is a Tab stop except the speed radios, which share one Tab stop on the checked option
 7. **Active State**: Opening or closing the panel dispatches a bubbling, composed `pie-tool-active-change` event with `{ active }` and mirrors the state in the host's `data-active` attribute
-8. **Cleanup**: Releases playback ownership and clears its highlight target resolver provider on unmount
+8. **Cleanup**: Clears its highlight target resolver provider on unmount
 
 ## SSML Extraction Integration
 
@@ -180,7 +179,7 @@ when a host/import pipeline runs `SSMLExtractor` before render:
 **Tool uses extracted catalog:**
 
 - User clicks TTS button in header
-- Tool calls `ttsService.speak(text, { catalogId: 'auto-prompt-q1-0' })`
+- Tool calls `ttsService.speak(readingTarget, { catalogId: 'auto-prompt-q1-0' })`
 - TTSService finds SSML in extracted catalogs
 - Speaks with proper math pronunciation and pacing
 
@@ -205,10 +204,12 @@ component-scoped variables instead of overriding broad semantic tokens such as
 --pie-tool-trigger-active-border-color: Active/open trigger border
 ```
 
+These three are registered `component-public` tokens.
+
 If unset, the trigger looks the same open as closed: each hook falls back to the
 value the control already resolves to — background through
 `--pie-button-background-color` / `--pie-button-bg` / `--pie-background`, border
-through `--pie-button-border-color` / `--pie-button-border` / `--pie-border`, and
+through `--pie-button-border` / `--pie-border`, and
 foreground through `--pie-button-color` / `--pie-text`. Setting a hook is how a
 host opts into a distinct active/open appearance.
 
@@ -219,9 +220,9 @@ indication — so these defaults do not introduce one. Hosts remain responsible
 maintaining WCAG AA foreground/background contrast when overriding active trigger
 colors.
 
-### Overlay panel colours
+### Overlay panel colors
 
-The floating and left-aligned panels take their colour from the active theme.
+The floating and left-aligned panels take their color from the active theme.
 Each surface resolves a component-scoped hook first, then a canonical token,
 then a literal that only applies when no theme is loaded:
 
@@ -232,7 +233,7 @@ then a literal that only applies when no theme is loaded:
 --pie-selected-button-background /* selected speed chip      → --pie-button-active-bg */
 --pie-selected-button-border  /* selected speed chip border  → --pie-button-border */
 --pie-tts-menu-shadow         /* card elevation */
---pie-tts-card-border         /* card hairline; `transparent` for shadow-only */
+--pie-tts-card-border         /* card hairline */
 ```
 
 None of the seven is a registered host token. Each is read as
@@ -242,27 +243,21 @@ carries no compatibility guarantee — the panel's internals may move it.
 The card carries a hairline mixed from `--pie-text` because its shadow is black
 and disappears once the surface goes dark. It is deliberately not derived from
 `--pie-border`: a host that wants borderless controls sets that to transparent,
-which is the case where the shadow is the only edge. Set
-`--pie-tts-card-border: transparent` for the shadow-only card.
+which is the case where the shadow is the only edge.
 
 A host that sets `--pie-button-border: transparent` also flattens the selected
-speed chip, which defaults through it — set `--pie-selected-button-border` to
-keep the chip outlined.
+speed chip, which defaults through it.
 
 Foregrounds default through `--pie-button-color` (DaisyUI `base-content`) rather
 than `--pie-primary` or `--pie-tertiary`: those are direct mappings of DaisyUI
-slots chosen to pair with their own `-content` colour, so an accent glyph taken
+slots chosen to pair with their own `-content` color, so an accent glyph taken
 from either falls under 3:1 against the card in 11 of the 35 shipped themes.
-Selection reads from the chip fill and the bolder weight instead of from hue. A
-host that wants a branded accent sets `--pie-tts-button-color` and owns the
-contrast, as with the active-trigger hooks above.
+Selection reads from the chip fill and the bolder weight instead of from hue.
 
-Ordinary trigger and control button styling also preserves these legacy aliases:
-`--pie-button-background-color`, `--pie-button-border-color`, and
-`--pie-button-hover-background-color`. They remain supported for host
-compatibility, but fall back through the canonical `--pie-button-bg`,
-`--pie-button-border`, and `--pie-button-hover-bg` tokens before broad surface
-tokens.
+Trigger and control backgrounds read `--pie-button-background-color` ahead of
+the canonical `--pie-button-bg`; borders and hover backgrounds read
+`--pie-button-border` and `--pie-button-hover-bg`. Each falls back to the broad
+surface tokens.
 
 ## Architecture
 
@@ -275,10 +270,6 @@ This tool follows the PIE Assessment Toolkit tool pattern:
 - Panel state is announced with `pie-tool-active-change`, which the packaged
   toolbar registration subscribes to
 
-## Example
-
-See active demos in `apps/section-demos`.
-
 ## License
 
 MIT

package/custom-elements.json

@@ -0,0 +1,144 @@
+{
+	"schemaVersion": "2.1.0",
+	"modules": [
+		{
+			"kind": "javascript-module",
+			"path": "dist/tool-tts-inline.js",
+			"declarations": [
+				{
+					"kind": "class",
+					"description": "Read-aloud trigger for an item or passage header inside `<pie-item-scope>` or `<pie-passage-shell>`: play/pause opens a panel of speed, rewind, fast-forward and stop controls. It reads the shell's content region through the TTS service in the toolkit runtime context, passing `catalog-id` so the service can speak authored SSML from the accessibility catalogs. Its controls stay disabled until the runtime context supplies a TTS service.",
+					"name": "ToolTtsInline",
+					"tagName": "pie-tool-tts-inline",
+					"customElement": true,
+					"members": [
+						{
+							"kind": "field",
+							"name": "catalogId",
+							"type": {
+								"text": "string"
+							},
+							"default": "''",
+							"attribute": "catalog-id"
+						},
+						{
+							"kind": "field",
+							"name": "size",
+							"type": {
+								"text": "'sm' | 'md' | 'lg'"
+							},
+							"default": "'md'",
+							"attribute": "size"
+						},
+						{
+							"kind": "field",
+							"name": "speedOptions",
+							"type": {
+								"text": "TTSSpeedOption[]"
+							},
+							"attribute": "speed-options"
+						},
+						{
+							"kind": "field",
+							"name": "showSingleSpeedOption",
+							"type": {
+								"text": "boolean"
+							},
+							"default": "false",
+							"attribute": "show-single-speed-option"
+						},
+						{
+							"kind": "field",
+							"name": "layoutMode",
+							"type": {
+								"text": "TTSLayoutMode"
+							},
+							"default": "'left-aligned'",
+							"attribute": "layout-mode"
+						}
+					],
+					"attributes": [
+						{
+							"name": "catalog-id",
+							"type": {
+								"text": "string"
+							},
+							"default": "''",
+							"fieldName": "catalogId"
+						},
+						{
+							"name": "size",
+							"type": {
+								"text": "string"
+							},
+							"default": "'md'",
+							"fieldName": "size"
+						},
+						{
+							"name": "speed-options",
+							"type": {
+								"text": "TTSSpeedOption[]"
+							},
+							"fieldName": "speedOptions"
+						},
+						{
+							"name": "show-single-speed-option",
+							"type": {
+								"text": "boolean"
+							},
+							"default": "false",
+							"fieldName": "showSingleSpeedOption"
+						},
+						{
+							"name": "layout-mode",
+							"type": {
+								"text": "string"
+							},
+							"default": "'left-aligned'",
+							"fieldName": "layoutMode"
+						}
+					],
+					"events": [
+						{
+							"name": "pie-tool-active-change",
+							"type": {
+								"text": "CustomEvent<{ active: boolean }>"
+							},
+							"description": "When its panel opens or closes."
+						}
+					],
+					"cssProperties": [
+						{
+							"name": "--pie-button-background-color",
+							"description": "Compatibility alias retained for TTS inline button backgrounds; implementations must fall back through canonical --pie-button-bg before broad surface tokens."
+						},
+						{
+							"name": "--pie-tool-trigger-active-background",
+							"description": "Component trigger active/open background hook; falls back through existing semantic tokens and must preserve WCAG contrast when overridden by hosts."
+						},
+						{
+							"name": "--pie-tool-trigger-active-border-color",
+							"description": "Component trigger active/open border hook; falls back through existing semantic tokens."
+						},
+						{
+							"name": "--pie-tool-trigger-active-color",
+							"description": "Component trigger active/open foreground hook; hosts are responsible for preserving contrast with the active trigger background."
+						}
+					],
+					"x-pie": {
+						"shadow": "open"
+					}
+				}
+			],
+			"exports": [
+				{
+					"kind": "custom-element-definition",
+					"name": "pie-tool-tts-inline",
+					"declaration": {
+						"name": "ToolTtsInline"
+					}
+				}
+			]
+		}
+	]
+}