@pie-players/pie-tool-answer-eliminator 0.3.75 → 1.0.0-beta.1

package/README.md

@@ -7,7 +7,7 @@ Test-taking strategy tool that allows students to eliminate answer choices they
 - **Element-Level State**: Answer eliminations tracked per PIE element (not per item)
 - **Visual Feedback**: Strikethrough styling for eliminated choices
 - **Global Uniqueness**: Uses composite keys for state management across sections
-- **Ephemeral State**: State is client-only, separate from PIE session data
+- **Separate from session data**: Eliminations never enter the PIE session; the coordinator's `saveToolState` hook persists them ([Persistence Integration](#persistence-integration))
 - **ElementToolStateStore Integration**: Works with Assessment Toolkit's state management
 
 ## Installation
@@ -28,14 +28,9 @@ The answer eliminator is automatically integrated when using the PIE Section Pla
 <script type="module">
   import '@pie-players/pie-section-player';
   import { ToolkitCoordinator } from '@pie-players/pie-assessment-toolkit';
-  import {
-    createPackagedToolRegistry,
-    DEFAULT_TOOL_MODULE_LOADERS,
-  } from '@pie-players/pie-default-tool-loaders';
+  import { createPackagedToolRegistry } from '@pie-players/pie-default-tool-loaders';
 
-  const toolRegistry = createPackagedToolRegistry({
-    toolModuleLoaders: DEFAULT_TOOL_MODULE_LOADERS,
-  });
+  const toolRegistry = createPackagedToolRegistry();
   const coordinator = new ToolkitCoordinator({
     assessmentId: 'my-assessment',
     toolRegistry,
@@ -54,7 +49,7 @@ The answer eliminator is automatically integrated when using the PIE Section Pla
 
 The section player automatically:
 - Renders answer eliminator buttons in question toolbars
-- Generates global element IDs
+- Passes each element's composite state key to the tool as `elementStateKeys`
 - Manages state lifecycle
 
 The tool reads its coordinator and the `ElementToolStateStore` from the toolkit
@@ -62,7 +57,7 @@ runtime context, so it has to sit inside `<pie-assessment-toolkit>`.
 
 ### Manual Integration (Advanced)
 
-For a custom layout inside the toolkit:
+For a custom layout inside the toolkit. The tool detects choices under the item root its enclosing `<pie-item-scope>` provides, and with none it warns and injects nothing:
 
 ```html
 <script type="module">
@@ -71,21 +66,23 @@ For a custom layout inside the toolkit:
   const tool = document.querySelector('pie-tool-answer-eliminator');
   // Store key per PIE element in the question, by model id
   tool.elementStateKeys = {
-    mc1: 'my-assessment:section-1:question-1:mc1',
-    mc2: 'my-assessment:section-1:question-1:mc2',
+    mc1: 'my-assessment:section-1:attempt-1:question-1:mc1',
+    mc2: 'my-assessment:section-1:attempt-1:question-1:mc2',
   };
-  tool.scopeElement = document.querySelector('.question-content');
   tool.visible = true; // or alwaysOn = true; the tool injects no buttons while neither is set
 </script>
 
 <pie-assessment-toolkit>
-  <pie-tool-answer-eliminator></pie-tool-answer-eliminator>
+  <pie-item-scope item-id="question-1">
+    <!-- the item's rendered content -->
+    <pie-tool-answer-eliminator></pie-tool-answer-eliminator>
+  </pie-item-scope>
 </pie-assessment-toolkit>
 ```
 
 ## Props/Attributes
 
-`elementStateKeys` and `scopeElement` are JS properties only; the others also take the attribute shown.
+`elementStateKeys` is a JS property only; the others also take the attribute shown.
 
 | Property | Attribute | Type | Default | Description |
 |----------|-----------|------|---------|-------------|
@@ -93,42 +90,40 @@ For a custom layout inside the toolkit:
 | `alwaysOn` | `always-on` | `boolean` | `false` | Shows the buttons regardless of `visible`, for a profile-based accommodation |
 | `strategy` | `strategy` | `'strikethrough' \| 'mask'` | `'strikethrough'` | Elimination styling; any other value uses `strikethrough` |
 | `buttonAlignment` | `button-alignment` | `'left' \| 'right' \| 'inline'` | `'right'` | Button placement relative to the choice |
-| `toolId` | `tool-id` | `string` | `'answerEliminator'` | Id the tool registers with the coordinator under |
-| `elementStateKeys` | | `Record<string, string>` | `{}` | Composite key `assessmentId:sectionId:itemId:elementId` per PIE element, by model id, into the runtime context's element tool state store. A choice is tracked under its nearest ancestor with a listed id and persists under that key; choices outside a listed element are kept in memory only |
-| `scopeElement` | | `HTMLElement` | | Root to detect choices in. Without it the tool uses the root its enclosing `pie-item-scope` provides, and with neither it warns and injects nothing |
+| `elementStateKeys` | | `Record<string, string>` | `{}` | Composite key `assessmentId:sectionId:attemptId:itemId:elementId` per PIE element, by model id, into the runtime context's element tool state store. A choice is tracked under its nearest ancestor with a listed id and persists under that key; choices outside a listed element are kept in memory only |
 
 ## Global Element ID Format
 
 The tool uses globally unique composite keys for state management:
 
 ```
-${assessmentId}:${sectionId}:${itemId}:${elementId}
+${assessmentId}:${sectionId}:${attemptId}:${itemId}:${elementId}
 ```
 
 **Example:**
 ```typescript
-"demo-assessment:section-1:question-1:mc1"
-"biology-exam:section-2:genetics-q1:ebsr1"
+"demo-assessment:section-1:attempt-1:question-1:mc1"
+"biology-exam:section-2:attempt-1:genetics-q1:ebsr1"
 ```
 
 ### Benefits of Composite Keys
 
-- ✅ **Element-Level Granularity**: Each PIE element has independent eliminations
-- ✅ **No Cross-Item Contamination**: Eliminations from question 1 don't appear on question 2
-- ✅ **Cross-Section Persistence**: State persists when navigating between sections
-- ✅ **Global Uniqueness**: No ID collisions across entire assessment
+- **Element-Level Granularity**: Each PIE element has independent eliminations
+- **No Cross-Item Contamination**: Eliminations from question 1 don't appear on question 2
+- **Cross-Section Persistence**: State persists when navigating between sections
+- **Global Uniqueness**: No ID collisions across entire assessment
 
 ### Why Element-Level?
 
 Items can contain **multiple interactive elements** whose choice ids repeat (two multiple-choice elements both have a choice `a`). Each element needs independent state:
 
 ```typescript
-// ✅ Correct: Element-level state
+// Element-level state
 {
-  "demo:section-1:question-1:mc1": {
+  "demo:section-1:attempt-1:question-1:mc1": {
     "answerEliminator": { "eliminatedChoices": ["a", "c"] }
   },
-  "demo:section-1:question-1:mc2": {
+  "demo:section-1:attempt-1:question-1:mc2": {
     "answerEliminator": { "eliminatedChoices": ["a"] }
   }
 }
@@ -136,14 +131,14 @@ Items can contain **multiple interactive elements** whose choice ids repeat (two
 
 ## State Management
 
-### Ephemeral vs Persistent State
+### Tool state and session data
 
-The answer eliminator stores state in **ElementToolStateStore** (ephemeral, client-only):
+The answer eliminator stores eliminations in the toolkit's **ElementToolStateStore**, apart from the PIE session. They leave the browser only through the coordinator's `saveToolState` hook.
 
-**Tool State (Ephemeral - NOT sent to server):**
+**Tool state (not part of the session, never scored):**
 ```typescript
 {
-  "demo:section-1:question-1:mc1": {
+  "demo:section-1:attempt-1:question-1:mc1": {
     "answerEliminator": {
       "eliminatedChoices": ["choice-b", "choice-d"]
     }
@@ -168,46 +163,65 @@ The answer eliminator stores state in **ElementToolStateStore** (ephemeral, clie
 To persist tool state across page refreshes:
 
 ```typescript
-import {
-  createPackagedToolRegistry,
-  DEFAULT_TOOL_MODULE_LOADERS,
-} from '@pie-players/pie-default-tool-loaders';
+import { ToolkitCoordinator } from '@pie-players/pie-assessment-toolkit';
+import { createPackagedToolRegistry } from '@pie-players/pie-default-tool-loaders';
 
-const toolRegistry = createPackagedToolRegistry({
-  toolModuleLoaders: DEFAULT_TOOL_MODULE_LOADERS,
-});
+const storageKey = 'tool-state:my-assessment';
 const coordinator = new ToolkitCoordinator({
   assessmentId: 'my-assessment',
-  toolRegistry,
-  tools: { placement: { item: ['answerEliminator'] } }
+  toolRegistry: createPackagedToolRegistry(),
+  tools: { placement: { item: ['answerEliminator'] } },
+  hooks: {
+    loadToolState: () => JSON.parse(localStorage.getItem(storageKey) ?? 'null'),
+    saveToolState: (state) => localStorage.setItem(storageKey, JSON.stringify(state)),
+  },
 });
+```
 
-// Save to localStorage on change
-const storageKey = `tool-state:${coordinator.assessmentId}`;
-coordinator.elementToolStateStore.setOnStateChange((state) => {
-  localStorage.setItem(storageKey, JSON.stringify(state));
-});
+## How It Works
+
+### 1. Choice Detection
+
+Elements supply their own choices. An element takes the eliminator by declaring the AfA PNP 3.0 support term `answer-masking` on its class and answering `pieSupportTargets('answer-masking')` on its instances:
 
-// Load on mount
-const saved = localStorage.getItem(storageKey);
-if (saved) {
-  coordinator.elementToolStateStore.loadState(JSON.parse(saved));
+```typescript
+class ChoiceGrid extends HTMLElement {
+  static pieSupports = ['answer-masking'];
+
+  pieSupportTargets(term: string) {
+    if (term !== 'answer-masking') return [];
+    return this.rows.map((row) => ({
+      id: row.value,
+      label: row.text,
+      container: row.element,
+      content: row.labelElement,
+      isSelected: () => this.isChosen(row.value),
+      isEliminable: () => this.mode === 'gather' && !this.isChosen(row.value),
+      setEliminated: (eliminated: boolean) => this.block(row.value, eliminated),
+    }));
+  }
 }
 ```
 
-## How It Works
+Every field is required, and a choice missing one is skipped with a console warning:
 
-### 1. Choice Detection
+| Field | Contract |
+| --- | --- |
+| `id` | Unique within the element and stable across renders: eliminations persist by it. |
+| `label` | The choice's accessible name; the toggle is announced as "Toggle elimination for `label`". |
+| `container` | Receives the toggle and the eliminated state. The tool sets `position: relative` on it. An inline container, such as a token in running text, takes the toggle in the line. |
+| `content` | The part that is struck through or masked. It must be inside `container`. |
+| `isSelected()` | Whether the learner has chosen it. A selected choice hides its toggle and is never eliminated. |
+| `isEliminable()` | False in evaluate and view modes, and for disabled or selected choices. |
+| `setEliminated(eliminated)` | Blocks or restores the learner's selection of the choice. The element owns this: the tool never disables controls it did not render. A call with the value the choice already has changes nothing. |
 
-The tool detects choices through an **adapter registry** (`AdapterRegistry`), not a fixed selector list. Each adapter knows how to find and operate on choices for a specific PIE element type, and the registry runs them in priority order (`canHandle()`, then `findChoices()`), so a single question can mix element types:
+The toolbar reads the same `static pieSupports` declaration to decide whether to offer the eliminator, so an element built outside this repository needs no change here. A declaration that omits `answer-masking`, including `[]`, means the element takes no eliminator.
 
-| Adapter | Element type | How it finds choices |
-| --- | --- | --- |
-| `MultipleChoiceAdapter` | `multiple-choice` (single- or multi-select) | `.corespring-checkbox` / `.corespring-radio-button` choices |
-| `EBSRAdapter` | `ebsr` | delegates to the multiple-choice adapter for each `ebsr-multiple-choice` part (Part A/B), prefixing choice IDs with the part |
-| `InlineDropdownAdapter` | `inline-dropdown` | dropdown items with `role="option"` |
+An element may replace its choices' markup on any render, as select-text does. When a container leaves the document, the tool asks for the choices again and keeps their eliminations by id, moving focus to the replacement toggle. It does not call `setEliminated` again on the same element instance, so an element that re-renders from `setEliminated` settles; a new instance is asked to block its eliminated choices, and a choice no longer supplied is restored.
 
-The tool builds its registry internally with these three adapters and has no injection point. The `./adapters/adapter-registry` export provides `AdapterRegistry` and `registerAdapter(...)`, and a registry a host constructs is not the one the tool reads, so supporting another element type is a change to this package. A `ChoiceAdapter` declares `elementType`, `priority`, `canHandle`, `findChoices`, `getChoiceId`, `getChoiceLabel`, `canEliminate`, `createChoiceRange` and `getButtonContainer`.
+The outermost declaring element under the item owns its subtree: an element composed of declaring parts answers for them, prefixing ids with the part where they would collide, as EBSR does with `a-` and `b-`. Eliminations persist under the key of the nearest element listed in `elementStateKeys`, starting from the declaring element.
+
+Elements that declare nothing fall back to the multiple-choice and EBSR markup this package reads (`.corespring-checkbox` and `.corespring-radio-button` choices, and the `ebsr-multiple-choice` parts with ids `a` and `b`). That fallback serves legacy pie-elements and pie-elements-ng releases from before elements declared their supports, and never runs inside a declaring element.
 
 ### 2. State Storage
 
@@ -226,28 +240,28 @@ Elimination styling is applied by a pluggable `EliminationStrategy` built on the
 - `strikethrough` (default): a `::highlight(pie-answer-eliminated-<id>)` rule renders a line-through over the choice label.
 - `mask`: a `::highlight(pie-answer-masked-<id>)` rule dims and blurs the choice.
 
-Images need separate treatment: they are replaced elements, so neither `::highlight()` nor `text-decoration` paints on them and a picture choice would look untouched. The `strikethrough` strategy therefore wraps each `img` in the eliminated choice in a `span.pie-answer-eliminator-image-strike` (marked with `data-pie-answer-eliminator-image-strike`) and overlays a decorative, `pointer-events: none` SVG that draws an X corner to corner — upper-left to lower-right and lower-left to upper-right. Restoring the choice unwraps the image and returns the DOM to its original shape. Each diagonal is painted over a wider light casing line (`--pie-answer-eliminator-image-strike-casing-color`) so it stays legible over dark artwork.
+Images need separate treatment: they are replaced elements, so neither `::highlight()` nor `text-decoration` paints on them and a picture choice would look untouched. The `strikethrough` strategy therefore wraps each `img` in the eliminated choice in a `span.pie-answer-eliminator-image-strike` (marked with `data-pie-answer-eliminator-image-strike`) and overlays a decorative, `pointer-events: none` SVG that draws an X corner to corner — upper-left to lower-right and lower-left to upper-right. Restoring the choice unwraps the image and returns the DOM to its original shape. Each diagonal is painted over a wider light casing line (`--pie-answer-eliminator-image-strike-casing-color`, package-private with no compatibility guarantee) so it stays legible over dark artwork.
 
 MathJax-rendered math needs its own mark for the same reason. MathJax's CHTML output draws each glyph as an `mjx-c` element with empty `textContent` (the character comes from `::before` generated content, which belongs to no Range), and its SVG output has no text at all — so the highlight had nothing to decorate and a math-only choice looked untouched. For each `mjx-container` in the eliminated choice, the `strikethrough` strategy marks the inner `mjx-math` box with `pie-answer-eliminator-math-strike` plus one of two modifiers, and the theme paints it:
 
 | expression | mark | `data-pie-answer-eliminator-math-strike` |
 | --- | --- | --- |
-| single row of symbols | centred line-through, as the prose gets | `line` |
+| single row of symbols | centered line-through, as the prose gets | `line` |
 | contains a fraction bar or table rule | diagonals, as an eliminated image gets | `cross` |
 
-A centred line on a fraction lands on the math axis — exactly where the fraction bar already sits — so it reads as a recoloured bar rather than an elimination. The split is structural (`mjx-mfrac`, `mjx-mtable`), not height-based: an inline `a/b` is only 1.16× its font size, indistinguishable in height from a radical or a parenthesised row, yet it is precisely the colliding case. Radicals and stacked limits keep the line, since their bars sit at the top or the strike simply crosses the base.
+A centered line on a fraction lands on the math axis — exactly where the fraction bar already sits — so it reads as a recolored bar rather than an elimination. The split is structural (`mjx-mfrac`, `mjx-mtable`), not height-based: an inline `a/b` is only 1.16× its font size, indistinguishable in height from a radical or a parenthesised row, yet it is precisely the colliding case. Radicals and stacked limits keep the line, since their bars sit at the top or the strike simply crosses the base.
 
 The inner `mjx-math` box is the paint target, not the container: for inline math `mjx-container` is `display: inline`, so its rect is the surrounding line box while the expression itself overflows it — a fraction sticks out several pixels above and below.
 
 Only MathJax containers are marked: natively rendered MathML keeps real text in `mi`/`mn`/`mo`, so the highlight already strikes every token there.
 
-All three treatments — the text line-through, the diagonals over an image, the line over math — are drawn in one colour, `--pie-answer-eliminator-strike-color` (defaulting to `--pie-incorrect`), so a choice mixing prose, pictures, and math reads as a single strike and can be restyled from one place.
+All three treatments — the text line-through, the diagonals over an image, the line over math — are drawn in one color, `--pie-answer-eliminator-strike-color` (a registered `component-public` token, defaulting to `--pie-incorrect`), so a choice mixing prose, pictures, and math reads as a single strike and can be restyled from one place.
 
 For browsers without the Highlight API, each strategy falls back to a class on the choice container. Either way the eliminated choice also receives ARIA hooks (`data-pie-answer-eliminated`, plus `aria-disabled`/`aria-hidden` and an offscreen "(eliminated)" announcement) for assistive technology.
 
 ### 4. Toggle Behavior
 
-Each detected choice gets its own elimination toggle button (class `pie-answer-eliminator-toggle`, rendered as `⊗`) placed via the adapter's `getButtonContainer()`. Clicking the button toggles that choice through the active strategy. Eliminating is blocked when the adapter's `canEliminate()` returns false — for example when the choice is already selected, disabled, or the item is in evaluate/view mode. An active button is marked with `pie-answer-eliminator-toggle--active` and `aria-pressed="true"`; clicking again restores the choice.
+Each choice gets its own elimination toggle button (class `pie-answer-eliminator-toggle`, rendered as `⊗`) appended to its `container`. Clicking the button toggles that choice through the active strategy and calls `setEliminated`. Eliminating is blocked while `isEliminable()` returns false. An active button is marked with `pie-answer-eliminator-toggle--active` and `aria-pressed="true"`; clicking again restores the choice.
 
 ## Cleanup
 
@@ -255,7 +269,7 @@ The ElementToolStateStore provides cleanup methods:
 
 ```typescript
 // Clear state for a specific element
-store.clearElement('demo:section-1:question-1:mc1');
+store.clearElement('demo:section-1:attempt-1:question-1:mc1');
 
 // Clear all answer eliminator state across all elements
 store.clearTool('answerEliminator');
@@ -279,24 +293,16 @@ interface AnswerEliminatorState {
 }
 ```
 
-## Browser Support
-
-- Chrome/Edge 90+
-- Firefox 88+
-- Safari 14+
-
-Requires ES2020+ support (native ES modules, optional chaining, nullish coalescing).
-
 ## Examples
 
 See the [section-demos](../../apps/section-demos/) for complete examples:
 
 - **Three Questions Demo**: Element-level answer eliminator with state persistence
-- **Paired Passages Demo**: Multi-section assessment with cross-section state
+- **Two Passages Demo**: Multi-section assessment with cross-section state
 
 ## Related Documentation
 
-- [ToolkitCoordinator Architecture](../../docs/architecture/architecture.md#toolkitcoordinator-centralized-service-management) - Element-level state design
+- [Assessment toolkit architecture](../../docs/architecture/architecture.md#assessment-toolkit): the coordinator and element-level tool state
 - [Assessment Toolkit README](../assessment-toolkit/README.md) - Toolkit overview
 - [Section Player README](../section-player/README.md) - Integration guide
 

package/custom-elements.json

@@ -0,0 +1,127 @@
+{
+	"schemaVersion": "2.1.0",
+	"modules": [
+		{
+			"kind": "javascript-module",
+			"path": "dist/tool-answer-eliminator.js",
+			"declarations": [
+				{
+					"kind": "class",
+					"description": "Process-of-elimination tool for the item in its enclosing `<pie-item-scope>`: it adds a toggle beside each choice an element supplies for `answer-masking` that strikes the choice through or masks it, per `strategy`. It renders nothing of its own and is active while `visible` or `always-on` is set. Eliminations persist in the runtime context's element tool state store, under the key `elementStateKeys` gives each PIE element.",
+					"name": "ToolAnswerEliminator",
+					"tagName": "pie-tool-answer-eliminator",
+					"customElement": true,
+					"members": [
+						{
+							"kind": "field",
+							"name": "visible",
+							"type": {
+								"text": "boolean"
+							},
+							"default": "false",
+							"attribute": "visible"
+						},
+						{
+							"kind": "field",
+							"name": "strategy",
+							"type": {
+								"text": "'strikethrough' | 'mask'"
+							},
+							"default": "'strikethrough'",
+							"attribute": "strategy"
+						},
+						{
+							"kind": "field",
+							"name": "alwaysOn",
+							"type": {
+								"text": "boolean"
+							},
+							"default": "false",
+							"attribute": "always-on"
+						},
+						{
+							"kind": "field",
+							"name": "buttonAlignment",
+							"type": {
+								"text": "'left' | 'right' | 'inline'"
+							},
+							"default": "'right'",
+							"attribute": "button-alignment"
+						},
+						{
+							"kind": "field",
+							"name": "elementStateKeys",
+							"type": {
+								"text": "ElementStateKeys"
+							},
+							"default": "{}",
+							"description": "Store key per PIE element, by model id (JS property only)",
+							"attribute": "elementstatekeys"
+						}
+					],
+					"attributes": [
+						{
+							"name": "visible",
+							"type": {
+								"text": "boolean"
+							},
+							"default": "false",
+							"fieldName": "visible"
+						},
+						{
+							"name": "strategy",
+							"type": {
+								"text": "string"
+							},
+							"default": "'strikethrough'",
+							"fieldName": "strategy"
+						},
+						{
+							"name": "always-on",
+							"type": {
+								"text": "boolean"
+							},
+							"default": "false",
+							"fieldName": "alwaysOn"
+						},
+						{
+							"name": "button-alignment",
+							"type": {
+								"text": "string"
+							},
+							"default": "'right'",
+							"fieldName": "buttonAlignment"
+						},
+						{
+							"name": "elementstatekeys",
+							"type": {
+								"text": "ElementStateKeys"
+							},
+							"default": "{}",
+							"description": "Store key per PIE element, by model id (JS property only)",
+							"fieldName": "elementStateKeys"
+						}
+					],
+					"cssProperties": [
+						{
+							"name": "--pie-answer-eliminator-strike-color",
+							"description": "Single colour for every part of an elimination: the text line-through, the diagonals over an image, and the line or diagonals over rendered math, so one choice reads as one treatment. Must fall back through canonical --pie-incorrect so a host that themes only the canonical feedback tokens still gets a coherent strike."
+						}
+					],
+					"x-pie": {
+						"shadow": "open"
+					}
+				}
+			],
+			"exports": [
+				{
+					"kind": "custom-element-definition",
+					"name": "pie-tool-answer-eliminator",
+					"declaration": {
+						"name": "ToolAnswerEliminator"
+					}
+				}
+			]
+		}
+	]
+}