@pie-players/pie-tool-line-reader 0.3.62 → 0.3.64

package/README.md

@@ -4,7 +4,9 @@ Draggable reading guide overlay tool for PIE assessment players.
 
 ## Overview
 
-Provides a movable, resizable colored overlay strip that helps students focus on specific lines of text during assessments. Supports both highlight mode (colored strip) and obscure/masking mode (darkens everything except the reading window).
+Provides a movable, resizable reading window that helps students focus on specific lines of text during assessments.
+
+The tool renders as a "window": a fully transparent **pane** through which the underlying page content is visible unchanged, surrounded on all four edges by an obscuring **frame** (black at 80% opacity by default) that largely hides the neighbouring lines. The frame starts as a 48px band above and below the pane and a 12px edge to its left and right.
 
 ## Custom Element
 
@@ -17,18 +19,92 @@ Tag: `pie-tool-line-reader`
 
 ## Features
 
-- Drag to reposition; bottom handle to resize height
-- Two modes: **highlight** (colored overlay) and **obscure** (masks surrounding content)
-- Five color options (yellow, blue, pink, green, orange) with adjustable opacity
+- Clear window pane inside an obscuring frame, at a host-configured opacity
+- Drag anywhere on the frame to reposition
+- Three controls on the frame:
+  - **Close** (top right) hides the tool through `ToolCoordinator.hideTool`, which also
+    deactivates its toolbar button
+  - **Reading-window resize** (bottom centre) changes the pane height
+  - **Frame resize** (bottom right) changes the frame band height and the overall width
 - Full keyboard support:
-  - Arrow keys to move
-  - `+`/`-` to resize height
-  - `C` to cycle colors
-  - `[`/`]` to adjust opacity
-  - `M` to toggle highlight/masking mode
+  - On the tool: arrow keys to move, `+`/`-` to resize the reading window, `Escape` to
+    close
+  - On the reading-window handle: up/down arrows change the pane height
+  - On the frame handle: up/down arrows change the frame band height, left/right arrows
+    change the width
+- Every drag has a keyboard equivalent (WCAG 2.5.7) and controls meet the 24x24 minimum
+  target size (WCAG 2.5.8)
 - Screen reader announcements for all state changes
 - Connects to `AssessmentToolkitRuntimeContext` for ToolCoordinator integration
 
+## Configuration
+
+How the frame masks the page — its fill and how strongly it obscures — is a host
+setting, not a student one. It trades reading focus against how much surrounding
+context a test taker can still see, which is a call a programme makes for its whole
+population, so it is configured once per deployment rather than adjusted mid-test.
+
+```css
+:root {
+  /* Masking strength; the pane is always fully transparent. */
+  --pie-tool-line-reader-frame-opacity: 0.65;
+  /* Fill of the obscuring frame. */
+  --pie-tool-line-reader-frame-color: #10233b;
+}
+```
+
+| Custom property | Default | Description |
+|---|---|---|
+| `--pie-tool-line-reader-frame-opacity` | `0.8` | Masking strength of the frame |
+| `--pie-tool-line-reader-frame-color` | `#000` | Fill of the obscuring frame |
+| `--pie-tool-line-reader-control-color` | `#fff` | Glyph colour of the close and resize controls |
+
+All three are `component-public` entries in
+`packages/theme/src/token-registry.json` and are safe for a host to rely on. The
+component only reads them — it never writes them inline — so a plain host
+declaration wins without `!important`.
+
+Two constraints come with overriding them. Lowering the opacity weakens the masking
+the tool exists to provide, and there is no in-session control for a student to
+recover from a value that masks too little, so check any override against the
+schemes you ship (see [Colour schemes](#colour-schemes) for the figures the
+defaults produce). And `--pie-tool-line-reader-control-color` is a companion to the
+fill rather than a hook worth setting alone: the control glyphs sit on the frame and
+default to white to pair with a dark scrim, so a light fill needs a new glyph colour
+with it, keeping 3:1 against the fill (WCAG 2.2 SC 1.4.11). The controls stay fully
+opaque whatever the frame opacity is, so the fill alone decides that ratio.
+
+## Colour schemes
+
+The frame stays a dark scrim in every PIE colour scheme instead of following
+`--pie-text`. Masking works by collapsing the contrast of whatever it covers, and
+an ink-coloured scrim defeats that on its own scheme — a yellow scrim over
+`yellow-on-blue` text hides nothing, and a white one glares in a dark scheme the
+reader chose to avoid glare. Dimming works in both directions: at the default fill
+and opacity, across all six built-in schemes the covered text drops from
+10.9–19.3:1 down to 1.09–1.71:1.
+
+What does follow the scheme is the boundary. On a light page the dark scrim shows
+its own edge against the background (11.7–17.6:1), but on a dark page it blends in,
+so `--pie-tool-line-reader-outline-color` draws an ink hairline that reads against
+the scrim (7.6–9.8:1 in the dark schemes). The drop shadow is ink-derived for the
+same reason, becoming a soft halo rather than disappearing.
+
+Because the fill is a deployment setting rather than a scheme-derived one, a host
+that overrides it owns these numbers for the schemes it ships.
+
+## Theming
+
+The remaining custom properties are package-private, not part of the registered
+host token contract: they are read as `var(--x, fallback)` (or set inline by the
+component, for the geometry ones), so a host can override them, but they carry no
+compatibility guarantee and may change with the tool's internals. Prefer the
+semantic tokens they derive from.
+
+| Custom property | Default | Description |
+|---|---|---|
+| `--pie-tool-line-reader-outline-color` | `--pie-text` at 70% | Hairline marking the window boundary |
+
 ## Integration
 
 Registered through the `ToolRegistry` as `lineReader`. Managed by `ToolkitCoordinator` via `tools.placement`.