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

package/README.md

@@ -1,37 +1,84 @@
 # @pie-players/pie-tool-theme
 
-Accessible color scheme selection tool for PIE assessment players.
+The color-scheme tool (`theme`): a picker in which a learner chooses one of the
+color schemes in the `@pie-players/pie-theme` catalog. It registers
+`<pie-tool-theme>` and changes the `scheme` of the `<pie-theme>` element that
+hosts the player. Theming itself, the tokens, base themes and `<pie-theme>`,
+belongs to [`@pie-players/pie-theme`](../theme/README.md). The picker addresses
+the WCAG 2.2 Level AA color, contrast, focus and keyboard requirements.
 
-## Overview
+## Installation
 
-Provides a theme/color scheme picker that applies accessible color schemes via the `<pie-theme>` provider. It is designed for the relevant WCAG 2.2 Level AA color, contrast, focus, and keyboard requirements.
+```bash
+bun add @pie-players/pie-tool-theme
+```
 
-## Custom Element
+## Usage
 
-Tag: `pie-tool-theme`
+The packaged tool set registers the tool as `theme` and loads the element on
+demand; hosts place it through `tools.placement`. It supports the assessment
+and section levels, and the section toolbar is its recommended placement. It
+opens in a fixed-size overlay, 520×380px initially and at least 420×300px. A
+host that registers the element itself imports the package:
 
-| Attribute | Type | Default | Description |
-|---|---|---|---|
-| `visible` | `boolean` | `false` | Controls visibility |
-| `tool-id` | `string` | `'theme'` | Identifier used by the ToolCoordinator |
+```ts
+import "@pie-players/pie-tool-theme";
+```
 
-## Features
+| Property | Attribute | Default | Purpose |
+| --- | --- | --- | --- |
+| `visible` | `visible` | `false` | Shows the picker. `"false"`, `"0"`, `"off"` and `"no"` read as false. |
+| `toolId` | `tool-id` | `"theme"` | The id the tool registers under with the tool coordinator. |
 
-- Dropdown scheme selector with color previews
-- Reads the shared `@pie-players/pie-theme` scheme catalog and updates immediately when a custom scheme is registered or unregistered
-- Uses centrally derived catalog previews instead of carrying a duplicate palette; custom previews use PIE's canonical light-base resolution on a stable opaque swatch
-- Retains a requested custom scheme when it is temporarily unavailable, clearly labels it as unavailable, and restores it automatically if it is registered again
-- Persists selection to `localStorage` (key: `pie-color-scheme`)
-- Applies scheme by setting the `scheme` attribute on the nearest `<pie-theme>` element
-- Focus trap when visible; keyboard navigation with arrow keys and Escape
-- Connects to `AssessmentToolkitRuntimeContext` for ToolCoordinator integration
+The element has an open shadow root and takes its tool coordinator and
+interface locale from the toolkit runtime context.
 
-## Integration
+## Scheme selection
 
-Registered through the `ToolRegistry` as `theme`. Managed by `ToolkitCoordinator` via `tools.placement`.
+The picker lists every scheme in the shared catalog and follows registrations
+and unregistrations as they happen. Previews come from the catalog; a custom
+scheme's preview resolves against PIE's light base on an opaque swatch.
 
-Register custom schemes globally with `registerPieColorSchemes` from `@pie-players/pie-theme`. Every mounted theme picker observes the same immutable catalog; per-element scheme catalogs are not supported.
+Choosing a scheme sets `scheme` on the theme host and closes the tool. The theme
+host is the nearest `<pie-theme>` ancestor, searched across shadow roots, else
+`<pie-theme scope="document">`, else the first `<pie-theme>` in the document.
+With no `<pie-theme>` at all, the picker sets `data-color-scheme` on the
+document element. The picker writes nothing to `localStorage`.
 
-## License
+Until a learner chooses, the picker shows the host's scheme, and it re-reads the
+host each time it opens. A chosen custom scheme that is no longer registered
+stays selected, labeled unavailable with a status message, and is listed as
+available again once registered.
 
-MIT
+## Learner choice
+
+The picker records the choice in the toolkit's `elementToolStateStore` under
+tool id `theme`, keyed by assessment, section and attempt, and reapplies it when
+the tool mounts again in that section attempt. Without a store, an
+`assessmentId` or a `sectionId` in the runtime context, the choice lasts only on
+the theme host. Nothing is kept for the device, so one learner's choice never
+overrides the scheme a host sets for the next. The host persists the store as
+[State persistence pattern](../../docs/tools-and-accomodations/architecture.md#state-persistence-pattern)
+describes.
+
+## Custom schemes
+
+Hosts register custom schemes globally with `registerPieColorSchemes` from
+`@pie-players/pie-theme`
+([Registered custom schemes](../theme/README.md#registered-custom-schemes)).
+Every mounted picker observes the same immutable catalog; there are no
+per-element catalogs. Scheme names and descriptions come from the registration,
+so the party that registers a scheme localizes them.
+
+## Keyboard and focus
+
+The picker is a dialog that traps focus while visible. With the scheme menu
+open, ArrowDown and ArrowUp move between schemes, Escape closes the menu and
+returns focus to its trigger, and a click outside closes it.
+
+## Styling
+
+The picker reads the canonical semantic tokens `--pie-background`, `--pie-text`,
+`--pie-border`, `--pie-button-bg`, `--pie-button-border`, `--pie-button-color`,
+`--pie-button-hover-bg`, `--pie-button-hover-border`, `--pie-button-hover-color`,
+`--pie-button-active-bg` and `--pie-button-focus-outline`.

package/custom-elements.json

@@ -0,0 +1,77 @@
+{
+	"schemaVersion": "2.1.0",
+	"modules": [
+		{
+			"kind": "javascript-module",
+			"path": "dist/tool-color-scheme.js",
+			"declarations": [
+				{
+					"kind": "class",
+					"description": "Colour scheme picker: a dropdown of the schemes registered with `@pie-players/pie-theme`, each with a preview, that applies the chosen scheme to the nearest `<pie-theme>`. The choice is recorded per section and attempt in the runtime context's element tool state store and reapplied when the tool mounts again in that attempt. The host shows it with `visible`; it registers `tool-id` with the tool coordinator on the modal layer, traps focus while open, and hides itself there once a scheme is chosen.",
+					"name": "ToolColorScheme",
+					"tagName": "pie-tool-theme",
+					"customElement": true,
+					"members": [
+						{
+							"kind": "field",
+							"name": "visible",
+							"type": {
+								"text": "boolean"
+							},
+							"default": "false",
+							"attribute": "visible"
+						},
+						{
+							"kind": "field",
+							"name": "toolId",
+							"type": {
+								"text": "string"
+							},
+							"default": "'theme'",
+							"attribute": "tool-id"
+						}
+					],
+					"attributes": [
+						{
+							"name": "visible",
+							"type": {
+								"text": "boolean"
+							},
+							"default": "false",
+							"fieldName": "visible"
+						},
+						{
+							"name": "tool-id",
+							"type": {
+								"text": "string"
+							},
+							"default": "'theme'",
+							"fieldName": "toolId"
+						}
+					],
+					"x-pie": {
+						"shadow": "open"
+					}
+				}
+			],
+			"exports": [
+				{
+					"kind": "custom-element-definition",
+					"name": "pie-theme",
+					"declaration": {
+						"name": "PieThemeElement",
+						"module": "dist/index.js",
+						"package": "@pie-players/pie-theme"
+					}
+				},
+				{
+					"kind": "custom-element-definition",
+					"name": "pie-tool-theme",
+					"declaration": {
+						"name": "ToolColorScheme"
+					}
+				}
+			]
+		}
+	]
+}