@pie-players/pie-tool-answer-eliminator 0.3.74 → 1.0.0-beta.0

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
@@ -49,93 +49,96 @@ 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 ElementToolStateStore to the tool
+- 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
+runtime context, so it has to sit inside `<pie-assessment-toolkit>`.
+
 ### Manual Integration (Advanced)
 
-For custom implementations outside the section player:
+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">
   import '@pie-players/pie-tool-answer-eliminator';
-  import { ElementToolStateStore } from '@pie-players/pie-assessment-toolkit';
-
-  const store = new ElementToolStateStore();
-  const globalElementId = store.getGlobalElementId(
-    'my-assessment',
-    'section-1',
-    'question-1',
-    'mc1'
-  );
 
   const tool = document.querySelector('pie-tool-answer-eliminator');
-  tool.globalElementId = globalElementId;
-  tool.elementToolStateStore = store;
-  tool.scopeElement = document.querySelector('.question-content');
+  // Store key per PIE element in the question, by model id
+  tool.elementStateKeys = {
+    mc1: 'my-assessment:section-1:attempt-1:question-1:mc1',
+    mc2: 'my-assessment:section-1:attempt-1:question-1:mc2',
+  };
+  tool.visible = true; // or alwaysOn = true; the tool injects no buttons while neither is set
 </script>
 
-<pie-tool-answer-eliminator></pie-tool-answer-eliminator>
+<pie-assessment-toolkit>
+  <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
 
-The web component accepts the following properties (set via JavaScript, not HTML attributes):
+`elementStateKeys` is a JS property only; the others also take the attribute shown.
 
-| Property | Type | Required | Description |
-|----------|------|----------|-------------|
-| `globalElementId` | `string` | Yes | Composite key: `assessmentId:sectionId:itemId:elementId` |
-| `elementToolStateStore` | `ElementToolStateStoreApi` | Yes | Store for element-level tool state |
-| `scopeElement` | `HTMLElement` | No | DOM element to scope choice detection (defaults to document) |
+| Property | Attribute | Type | Default | Description |
+|----------|-----------|------|---------|-------------|
+| `visible` | `visible` | `boolean` | `false` | Shows the elimination buttons; the toolbar toggle sets it |
+| `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 |
+| `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:ebsr-part1"
+"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** (e.g., EBSR with two parts). Each element needs independent state:
+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:ebsr-part1": {
-    "answerEliminator": { "eliminatedChoices": ["choice-a", "choice-c"] }
+  "demo:section-1:attempt-1:question-1:mc1": {
+    "answerEliminator": { "eliminatedChoices": ["a", "c"] }
   },
-  "demo:section-1:question-1:ebsr-part2": {
-    "answerEliminator": { "eliminatedChoices": ["choice-b"] }
+  "demo:section-1:attempt-1:question-1:mc2": {
+    "answerEliminator": { "eliminatedChoices": ["a"] }
   }
 }
 ```
 
 ## 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"]
     }
@@ -160,26 +163,19 @@ The answer eliminator stores state in **ElementToolStateStore** (ephemeral, clie
 To persist tool state across page refreshes:
 
 ```typescript
+import { ToolkitCoordinator } from '@pie-players/pie-assessment-toolkit';
 import { createPackagedToolRegistry } from '@pie-players/pie-default-tool-loaders';
 
-const toolRegistry = createPackagedToolRegistry();
+const storageKey = 'tool-state:my-assessment';
 const coordinator = new ToolkitCoordinator({
   assessmentId: 'my-assessment',
-  toolRegistry,
-  tools: { placement: { item: ['answerEliminator'] } }
-});
-
-// Save to localStorage on change
-const storageKey = `tool-state:${coordinator.assessmentId}`;
-coordinator.elementToolStateStore.setOnStateChange((state) => {
-  localStorage.setItem(storageKey, JSON.stringify(state));
+  toolRegistry: createPackagedToolRegistry(),
+  tools: { placement: { item: ['answerEliminator'] } },
+  hooks: {
+    loadToolState: () => JSON.parse(localStorage.getItem(storageKey) ?? 'null'),
+    saveToolState: (state) => localStorage.setItem(storageKey, JSON.stringify(state)),
+  },
 });
-
-// Load on mount
-const saved = localStorage.getItem(storageKey);
-if (saved) {
-  coordinator.elementToolStateStore.loadState(JSON.parse(saved));
-}
 ```
 
 ## How It Works
@@ -194,14 +190,7 @@ The tool detects choices through an **adapter registry** (`AdapterRegistry`), no
 | `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"` |
 
-Support more element types at runtime by registering your own adapter (any object implementing the `ChoiceAdapter` interface: `canHandle`, `findChoices`, `getChoiceId`, `getChoiceLabel`, `canEliminate`, `createChoiceRange`, `getButtonContainer`):
-
-```typescript
-import { AdapterRegistry } from '@pie-players/pie-tool-answer-eliminator/adapters/adapter-registry';
-
-const registry = new AdapterRegistry();
-registry.registerAdapter(myCustomChoiceAdapter);
-```
+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`.
 
 ### 2. State Storage
 
@@ -220,22 +209,22 @@ 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.
 
@@ -249,7 +238,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');
@@ -273,24 +262,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 multiple-choice, EBSR and inline-dropdown choice 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"
+					}
+				}
+			]
+		}
+	]
+}