@pie-players/pie-tool-line-reader 0.3.75 → 1.0.0-beta.0

package/README.md

@@ -6,7 +6,7 @@ Draggable reading guide overlay tool for PIE assessment players.
 
 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.
+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 neighboring lines. The frame starts as a 48px band above and below the pane and a 12px edge to its left and right.
 
 ## Custom Element
 
@@ -24,7 +24,7 @@ Tag: `pie-tool-line-reader`
 - 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
+  - **Reading-window resize** (bottom center) changes the pane height
   - **Frame resize** (bottom right) changes the frame band height and the overall width
 - Full keyboard support:
   - On the tool: arrow keys to move, `+`/`-` to resize the reading window, `Escape` to
@@ -41,7 +41,7 @@ Tag: `pie-tool-line-reader`
 
 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
+context a test taker can still see, which is a call a program makes for its whole
 population, so it is configured once per deployment rather than adjusted mid-test.
 
 ```css
@@ -57,7 +57,7 @@ population, so it is configured once per deployment rather than adjusted mid-tes
 |---|---|---|
 | `--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 |
+| `--pie-tool-line-reader-control-color` | `#fff` | Glyph color 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
@@ -67,27 +67,27 @@ 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
+schemes you ship (see [Color schemes](#color-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
+default to white to pair with a dark scrim, so a light fill needs a new glyph color
 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
+## Color schemes
 
-The frame stays a dark scrim in every PIE colour scheme instead of following
+The frame stays a dark scrim in every PIE color 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
+an ink-colored 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.
+and opacity, across all ten built-in schemes the covered text drops from
+6.2–21:1 down to 1.36–1.66: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,
+its own edge against the background (7.7–12.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
+the scrim (7.6–10: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
@@ -97,9 +97,8 @@ that overrides it owns these numbers for the schemes it ships.
 
 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.
+component, for the geometry ones), carry no compatibility guarantee, and may
+change with the tool's internals. Prefer the semantic tokens they derive from.
 
 | Custom property | Default | Description |
 |---|---|---|

package/custom-elements.json

@@ -0,0 +1,82 @@
+{
+	"schemaVersion": "2.1.0",
+	"modules": [
+		{
+			"kind": "javascript-module",
+			"path": "dist/tool-line-reader.js",
+			"declarations": [
+				{
+					"kind": "class",
+					"description": "Reading-guide overlay: a transparent reading window inside an obscuring frame that the student drags over text, with controls on the frame to resize the window, resize the frame and close. The host shows it with `visible`; inside a toolkit runtime context it registers `tool-id` with the tool coordinator on the tool layer, and the close control hides it there. Arrow keys move it, `+` and `-` resize the window, and Escape closes it.",
+					"name": "ToolLineReader",
+					"tagName": "pie-tool-line-reader",
+					"customElement": true,
+					"members": [
+						{
+							"kind": "field",
+							"name": "visible",
+							"type": {
+								"text": "boolean"
+							},
+							"default": "false",
+							"attribute": "visible"
+						},
+						{
+							"kind": "field",
+							"name": "toolId",
+							"type": {
+								"text": "string"
+							},
+							"default": "'lineReader'",
+							"attribute": "tool-id"
+						}
+					],
+					"attributes": [
+						{
+							"name": "visible",
+							"type": {
+								"text": "boolean"
+							},
+							"default": "false",
+							"fieldName": "visible"
+						},
+						{
+							"name": "tool-id",
+							"type": {
+								"text": "string"
+							},
+							"default": "'lineReader'",
+							"fieldName": "toolId"
+						}
+					],
+					"cssProperties": [
+						{
+							"name": "--pie-tool-line-reader-control-color",
+							"description": "Glyph colour of the line reader's close and resize controls. Registered as the required companion to --pie-tool-line-reader-frame-color rather than as a hook worth setting on its own: the controls sit on the frame, so this is paired with the fill and not with the page, and the #fff default only holds while the fill stays dark. A host that sets a light fill must set this too. Does not fall through --pie-text or the canonical button tokens, which track the page rather than the scrim the glyphs are drawn on. Must keep 3:1 against the resolved fill (WCAG 2.2 SC 1.4.11); the controls are fully opaque regardless of --pie-tool-line-reader-frame-opacity, so the fill alone determines the ratio."
+						},
+						{
+							"name": "--pie-tool-line-reader-frame-color",
+							"description": "Fill of the line reader's obscuring frame, configured per deployment alongside --pie-tool-line-reader-frame-opacity. Deliberately does not fall through --pie-text or any canonical surface token, and deliberately does not follow data-color-scheme: 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. The #000 default dims in both directions instead, dropping covered text from 6.2-21:1 to 1.36-1.66:1 across the ten built-in schemes. A host overriding it owns that verification for every scheme it ships, and must set --pie-tool-line-reader-control-color with it when picking a light fill, because the control glyphs default to white to pair with the dark scrim."
+						},
+						{
+							"name": "--pie-tool-line-reader-frame-opacity",
+							"description": "Masking strength of the line reader's obscuring frame. A programme-level decision rather than a student one -- it sets how much surrounding context a test taker can still see -- so it is configured per deployment and the tool exposes no in-session control for it. Read as var() with a 0.8 default and never written inline by the component, so a host declaration wins without !important. Does not fall through any canonical token: this is unitless masking strength, not a palette value. Lowering it weakens the masking the tool exists to provide and invalidates the contrast figures recorded for --pie-tool-line-reader-frame-color, which were measured at the 0.8 default."
+						}
+					],
+					"x-pie": {
+						"shadow": "open"
+					}
+				}
+			],
+			"exports": [
+				{
+					"kind": "custom-element-definition",
+					"name": "pie-tool-line-reader",
+					"declaration": {
+						"name": "ToolLineReader"
+					}
+				}
+			]
+		}
+	]
+}