@pie-players/pie-tool-annotation-toolbar 0.3.75 → 1.0.0-beta.0

package/README.md

@@ -1,4 +1,4 @@
-# Annotation Toolbar
+# @pie-players/pie-tool-annotation-toolbar
 
 A text selection toolbar for highlighting and annotating text in PIE assessment players. Uses modern CSS Custom Highlight API for zero DOM mutation and optimal performance.
 
@@ -6,24 +6,19 @@ A text selection toolbar for highlighting and annotating text in PIE assessment
 
 - **4-Color Highlighting**: Yellow, pink, blue, and green highlight swatches
 - **Underline Annotation**: Underline selected text
-- **Persistent Annotations**: Saved to sessionStorage and restored on page load
+- **Persistent Annotations**: Kept per section and attempt in the toolkit's tool-state store
 - **Clear Annotations**: Remove annotations from selected text or clear all
-- **Text-to-Speech (Read Aloud)**: Read selected text aloud with word-level highlighting
+- **Text-to-Speech (Read Aloud)**: Read selected text aloud through the toolkit's TTS service, which highlights by sentence on browser voices and by word on server voices that return speech marks ([TTS deep dive](../../docs/accessibility/tts-deep-dive.md))
 - **Selection Actions**: Host-supplied actions on the current selection; see below
 - **Viewport-Aware Placement**: Sits above the selection where it fits, flips below when it does not, and clamps so no control leaves the viewport. `data-pie-placement` on the strip reads `above` or `below`.
 - **Modern CSS Custom Highlight API**:
   - Zero DOM mutation (no `<span>` wrappers)
-  - 10-50x faster than traditional approaches
-  - 5-10x less memory usage
   - Framework-compatible (works with React, Vue, Svelte)
 - **Accessibility**:
   - Full ARIA labels and screen reader support
   - Keyboard navigation (Escape to close)
   - Focus-visible outlines
-  - WCAG 2.2 compliant
-- **Dark Mode**: Automatic adaptation to system color scheme
-- **High Contrast Mode**: Enhanced visibility in high contrast settings
-- **Responsive Design**: Optimized for mobile and desktop viewports
+- **Theme-aware**: the outline follows the declared `color-scheme` through `light-dark()`, and the `data-color-scheme` palettes set all three tokens (see Theming)
 
 ## Usage
 
@@ -72,15 +67,17 @@ The toolbar takes its surface and text from the canonical `--pie-background` and
 | `--pie-annotation-underline`           | `#4221d5`                      | Underline mark on a light page                     |
 | `--pie-annotation-underline-dark`      | `#9c89ec`                      | Underline mark on a dark page                      |
 
+All three are registered `component-public` tokens.
+
 The underline tokens are applied by `HighlightCoordinator` in `@pie-players/pie-assessment-toolkit`, which owns the `::highlight()` rules. They exist as a pair because one value cannot serve both surfaces — `#4221d5` is 2.41:1 on black and `#9c89ec` is 2.85:1 on white — and as two separate tokens so overriding one never silently moves the other. Under `data-theme="light"` and `data-theme="dark"` the underline reads only its own token, because a theme accent is chosen against one background and is illegible on the other. Under any other `data-theme` value, such as a host or DaisyUI palette, it reads `--pie-annotation-underline` and falls back to that palette's `--pie-primary`.
 
 Which of the pair applies is decided by `[data-theme]`, which reports what the **page** declares — not which color scheme is active. A host that declares itself light while running a dark scheme would otherwise pin the light value over a dark background, so the accessibility palettes hand both states their own accent (below).
 
-The outline does **not** read `--pie-border`. Under the DaisyUI bridge that token resolves to `--color-base-300`, a surface tint rather than a boundary colour, which renders the outline at 1.16:1 on the light base and 1.12:1 on the dark one — well short of the 3:1 that WCAG 2.2 SC 1.4.11 requires of a component boundary.
+The outline does **not** read `--pie-border`. Under the DaisyUI bridge that token resolves to `--color-base-300`, a surface tint rather than a boundary color, which renders the outline at 1.16:1 on the light base and 1.12:1 on the dark one — well short of the 3:1 that WCAG 2.2 SC 1.4.11 requires of a component boundary.
 
-The defaults above are measured instead. A boundary on a light surface has to be dark and one on a dark surface has to be light, so the arms are the dark grey first and the light grey second. Both are measured against the surfaces the toolbar is actually drawn on rather than against pure white and pure black — real theme bases are off-white and off-black, and a grey chosen at the edge of passing against an extreme drops under threshold on everything else. Across DaisyUI's 21 light and 14 dark themes plus the PIE light and dark palettes, every light surface needs a grey no lighter than `#828282` and every dark surface one no darker than `#878787`; the ranges are disjoint, so one value cannot serve both. `#5c5c5c` holds 5.22:1 as its worst case on the light surfaces and `#949494` holds 3.56:1 on the dark ones. `light-dark()` follows the declared `color-scheme`, so every dark DaisyUI theme picks the dark value rather than only the theme literally named `dark`.
+The defaults above are measured instead. A boundary on a light surface has to be dark and one on a dark surface has to be light, so the arms are the dark gray first and the light gray second. Both are measured against the surfaces the toolbar is actually drawn on rather than against pure white and pure black — real theme bases are off-white and off-black, and a gray chosen at the edge of passing against an extreme drops under threshold on everything else. Across DaisyUI's 21 light and 14 dark themes plus the PIE light and dark palettes, every light surface needs a gray no lighter than `#828282` and every dark surface one no darker than `#878787`; the ranges are disjoint, so one value cannot serve both. `#5c5c5c` holds 5.22:1 as its worst case on the light surfaces and `#949494` holds 3.56:1 on the dark ones. `light-dark()` follows the declared `color-scheme`, so every dark DaisyUI theme picks the dark value rather than only the theme literally named `dark`.
 
-Palettes that choose their own colours deliberately set all three tokens in `@pie-players/pie-theme`: the ten `data-color-scheme` accessibility schemes point the outline at their own `--pie-border` and both underline states at their own `--pie-primary`, and the PIE dark theme pins the outline to `#949494`. Several of those palettes use mid-tone backgrounds that no single grey clears 3:1 on, which is why they override rather than inherit.
+Palettes that choose their own colors deliberately set all three tokens in `@pie-players/pie-theme`: the ten `data-color-scheme` accessibility schemes point the outline at their own `--pie-border` and both underline states at their own `--pie-primary`, and the PIE dark theme pins the outline to `#949494`. Several of those palettes use mid-tone backgrounds that no single gray clears 3:1 on, which is why they override rather than inherit.
 
 Those per-scheme values arrive by either delivery route: `<pie-theme scheme="…">` applies them as inline styles with no CSS import needed, and importing `@pie-players/pie-theme/color-schemes.css` plus setting `data-color-scheme` yourself produces the same result. Prefer the element — a host that hand-maintains its own copy of the scheme blocks stops receiving tokens added later.
 
@@ -100,15 +97,15 @@ Requires CSS Custom Highlight API support:
 
 - Chrome/Edge 105+
 - Safari 17.2+
-- Firefox 128+
+- Firefox 140+
 
 For unsupported browsers, the component gracefully degrades (no highlights shown).
 
 ## Annotation Persistence
 
-Annotations are saved to `sessionStorage` after each change and restored two seconds after the toolbar mounts. The key is `pie-annotations:<id>`, where `<id>` is the enclosing item's canonical item id, else its item id, else `global`, so each item keeps its own annotations across navigation within the browser session.
+Annotations are recorded in the toolkit's `elementToolStateStore` after each change, under tool id `annotationToolbar` and a key naming the assessment, section and attempt (`attempt-id` on the toolkit), plus the item when the toolbar sits in an item's shell. Two seconds after the toolbar mounts, and whenever that key changes, the shown annotations are replaced by the key's record, so a new attempt starts without the previous one's. They last as long as the toolkit coordinator; a host keeps them across reloads with the coordinator's `loadToolState` and `saveToolState` hooks.
 
-Storage format, an array with one record per annotation:
+Recorded format, an array with one record per annotation:
 
 ```typescript
 [
@@ -127,10 +124,7 @@ Storage format, an array with one record per annotation:
 
 `startContainer` and `endContainer` are selector paths relative to the scope root, with ` >>> ` marking a step into a shadow root.
 
-Stored annotations are removed when:
-
-- The user presses "Clear all", which removes that item's key
-- `sessionStorage` is cleared, for example when the tab closes
+"Clear all" records an empty list under the key.
 
 ## Text-to-Speech Integration
 
@@ -141,7 +135,7 @@ The annotation toolbar includes a "Read" button that uses the TTS service to rea
 1. **User selects text** in the assessment content
 2. **Annotation toolbar appears** with highlight and read buttons
 3. **User clicks "Read"** button (speaker icon)
-4. **TTS service speaks the selected text** using Web Speech API
+4. **TTS service speaks the selected text** using the toolkit's configured TTS backend
 5. **Words are highlighted** in sync with speech using CSS Custom Highlight API
 
 ### Technical Implementation
@@ -175,16 +169,4 @@ under tts-inline; part of one reads as the selected text.
 
 ### TTS Browser Support
 
-- **TTS (Web Speech API)**: 97%+ browser support
-- **Word Highlighting**: 85-90% browser support (CSS Custom Highlight API)
 - **Graceful degradation**: TTS works without highlighting in older browsers
-
-## Based On
-
-This implementation is inspired by production annotation toolbar patterns but uses modern 2025 web standards:
-
-- CSS Custom Highlight API instead of DOM mutation
-- Svelte 5 patterns and best practices
-- Modern accessibility (WCAG 2.2)
-- Dark mode and high contrast support
-- Responsive design for mobile devices

package/custom-elements.json

@@ -0,0 +1,76 @@
+{
+	"schemaVersion": "2.1.0",
+	"modules": [
+		{
+			"kind": "javascript-module",
+			"path": "dist/tool-annotation-toolbar.js",
+			"declarations": [
+				{
+					"kind": "class",
+					"description": "Toolbar that appears at a text selection, offering four highlight colours, underline, read-aloud, removal, clear-all and the host's `selectionActions`. Annotations are drawn through the runtime context's highlight coordinator and recorded per section and attempt in its element tool state store; read-aloud uses the context's TTS service. Under `<pie-assessment-toolkit>` the capability's registration supplies `enabled` and `selectionActions`.",
+					"name": "ToolAnnotationToolbar",
+					"tagName": "pie-tool-annotation-toolbar",
+					"customElement": true,
+					"members": [
+						{
+							"kind": "field",
+							"name": "enabled",
+							"type": {
+								"text": "boolean"
+							},
+							"default": "true",
+							"attribute": "enabled"
+						},
+						{
+							"kind": "field",
+							"name": "selectionActions",
+							"type": {
+								"text": "ToolSelectionAction[] | null"
+							},
+							"default": "null",
+							"description": "Actions on the current selection, supplied by whoever mounts this gateway. This strip does not know what they do — it renders the buttons and hands each one the selection. Pairing an action to a capability is the composer's job, which is what keeps a highlighter from naming a dictionary and lets a host contribute an action for a capability PIE does not ship.",
+							"attribute": "selectionactions"
+						}
+					],
+					"attributes": [
+						{
+							"name": "enabled",
+							"type": {
+								"text": "boolean"
+							},
+							"default": "true",
+							"fieldName": "enabled"
+						},
+						{
+							"name": "selectionactions",
+							"type": {
+								"text": "ToolSelectionAction[] | null"
+							},
+							"default": "null",
+							"description": "Actions on the current selection, supplied by whoever mounts this gateway. This strip does not know what they do — it renders the buttons and hands each one the selection. Pairing an action to a capability is the composer's job, which is what keeps a highlighter from naming a dictionary and lets a host contribute an action for a capability PIE does not ship.",
+							"fieldName": "selectionActions"
+						}
+					],
+					"cssProperties": [
+						{
+							"name": "--pie-tool-annotation-toolbar-border",
+							"description": "Outline of the floating annotation toolbar. Deliberately does not fall through --pie-border, which the DaisyUI bridge maps to the base-300 surface tint and which leaves the outline near 1.1:1; the component default is a measured light-dark(#5c5c5c, #949494) pair instead -- dark grey on light surfaces, light grey on dark ones, each measured against DaisyUI's real theme bases rather than pure white and black. The data-color-scheme accessibility palettes and the PIE dark theme set it explicitly so their own boundary colour wins. Hosts overriding it must keep 3:1 against both the toolbar surface and the content behind it (WCAG 2.2 SC 1.4.11)."
+						}
+					],
+					"x-pie": {
+						"shadow": "open"
+					}
+				}
+			],
+			"exports": [
+				{
+					"kind": "custom-element-definition",
+					"name": "pie-tool-annotation-toolbar",
+					"declaration": {
+						"name": "ToolAnnotationToolbar"
+					}
+				}
+			]
+		}
+	]
+}