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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PIE Framework contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -82,15 +82,16 @@ For a custom layout inside the toolkit. The tool detects choices under the item
 
 ## Props/Attributes
 
-`elementStateKeys` is a JS property only; the others also take the attribute shown.
+`elementStateKeys` and `elementIds` are JS properties only; the others also take the attribute shown.
 
 | 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 |
+| `buttonAlignment` | `button-alignment` | `'start' \| 'end' \| 'inline'` | `'inline'` | Toggle placement: `inline` in the flow after the choice, or `start`/`end` beside it, resolved against the choice's own direction so they mirror under right-to-left content. `left` and `right` are aliases of `start` and `end`; any other value is `inline` |
 | `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 |
+| `elementIds` | | `string[]` | unset | Model ids of the PIE elements whose choices take a toggle; unset, every element's do. A choice belongs to an element when that element or one of its ancestors up to the item has a listed id. The toolbar sets it from the host's element list |
 
 ## Global Element ID Format
 
@@ -182,15 +183,62 @@ const coordinator = new ToolkitCoordinator({
 
 ### 1. Choice Detection
 
-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:
+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:
 
-| 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"` |
+```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),
+    }));
+  }
+}
+```
+
+Every field is required, and a choice missing one is skipped with a console warning:
+
+| 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 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.
+
+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 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.
 
-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`.
+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.
+
+### Host element list
+
+A host limits the eliminator to the elements whose support it has vetted, by package name, in the tool's provider entry:
+
+```typescript
+new ToolkitCoordinator({
+  tools: {
+    providers: {
+      answerEliminator: { elements: ['multiple-choice', 'ebsr'] },
+    },
+  },
+});
+```
+
+A name is the `<name>` of `@pie-element/<name>`, matched against the package the item's `elements` map binds a model's tag to, or, for a tag the map does not bind, against the tag with its version suffix and `pie-`/`pie-element-` prefix removed. A tag bound to a package outside `@pie-element` matches no name. A listed element must still support answer masking. The toolbar withdraws the eliminator from an item with no listed element, even under a PNP grant, and in a mixed item gives toggles only to the listed elements' choices. Omitting `elements` keeps every supporting element; an empty list allows none. A value that is not a list of names fails config validation and, under `toolConfigStrictness: "warn"` or `"off"`, allows none.
 
 ### 2. State Storage
 
@@ -226,11 +274,13 @@ Only MathJax containers are marked: natively rendered MathML keeps real text in
 
 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.
+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`, `aria-disabled`, and an offscreen "(eliminated)" announcement in the interface language) for assistive technology. The choice container is never `aria-hidden` — it hosts the strategy's toggle, which must stay reachable for screen-reader and keyboard users (WCAG 4.1.2).
 
 ### 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.
+
+The toggle's accessible name ("Toggle elimination for {choice}", with "Unlabeled choice" standing in for a choice without text) and the "(eliminated)" announcement come from the players' catalog under `tools.answerEliminator`, in the interface locale of the runtime context. Both carry that locale's `lang` and `dir` while the choice content keeps its own, and a locale change relabels them in place without dropping eliminations.
 
 ## Cleanup
 

package/custom-elements.json

@@ -7,7 +7,7 @@
 			"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.",
+					"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; `elementIds` limits the toggles to those elements' choices. 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,
@@ -43,9 +43,10 @@
 							"kind": "field",
 							"name": "buttonAlignment",
 							"type": {
-								"text": "'left' | 'right' | 'inline'"
+								"text": "'start' | 'end' | 'inline' | 'left' | 'right'"
 							},
-							"default": "'right'",
+							"default": "'inline'",
+							"description": "Toggle placement: `inline` in the flow after the choice, or `start`/`end` beside it, mirrored under right-to-left content; `left` and `right` alias `start` and `end`.",
 							"attribute": "button-alignment"
 						},
 						{
@@ -57,6 +58,15 @@
 							"default": "{}",
 							"description": "Store key per PIE element, by model id (JS property only)",
 							"attribute": "elementstatekeys"
+						},
+						{
+							"kind": "field",
+							"name": "elementIds",
+							"type": {
+								"text": "readonly string[]"
+							},
+							"description": "Model ids of the PIE elements whose choices take a toggle. Unset, every element's choices do.",
+							"attribute": "elementids"
 						}
 					],
 					"attributes": [
@@ -89,7 +99,8 @@
 							"type": {
 								"text": "string"
 							},
-							"default": "'right'",
+							"default": "'inline'",
+							"description": "Toggle placement: `inline` in the flow after the choice, or `start`/`end` beside it, mirrored under right-to-left content; `left` and `right` alias `start` and `end`.",
 							"fieldName": "buttonAlignment"
 						},
 						{
@@ -100,6 +111,14 @@
 							"default": "{}",
 							"description": "Store key per PIE element, by model id (JS property only)",
 							"fieldName": "elementStateKeys"
+						},
+						{
+							"name": "elementids",
+							"type": {
+								"text": "readonly string[]"
+							},
+							"description": "Model ids of the PIE elements whose choices take a toggle. Unset, every element's choices do.",
+							"fieldName": "elementIds"
 						}
 					],
 					"cssProperties": [

package/dist/THIRD-PARTY-LICENSES.txt

@@ -0,0 +1,14 @@
+Third-party software included in this package's bundles, with the licence each is used under.
+
+========================================================================
+
+svelte 5.57.3
+License: MIT
+
+Copyright (c) 2016-2025 [Svelte Contributors](https://github.com/sveltejs/svelte/graphs/contributors)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/dist/element-props.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Store key per PIE element, by the element's model id (which is also its DOM
+ * id). A choice persists under the key of the nearest ancestor listed here.
+ */
+export type ElementStateKeys = Readonly<Record<string, string>>;
+/** Inputs shared by the component and its native element declaration. */
+export interface AnswerEliminatorProps {
+    visible?: boolean;
+    strategy?: 'strikethrough' | 'mask';
+    alwaysOn?: boolean;
+    buttonAlignment?: 'start' | 'end' | 'inline' | 'left' | 'right';
+    elementStateKeys?: ElementStateKeys;
+    /**
+     * Model ids of the PIE elements whose choices take a toggle. Unset, every
+     * element's choices do.
+     */
+    elementIds?: readonly string[];
+}

package/dist/index.d.ts

@@ -1,7 +1,9 @@
-/**
- * pie-tool-answer-eliminator - PIE Assessment Tool
- *
- * Importing this package registers `<pie-tool-answer-eliminator>`. The build
- * entry is the component, so this file is the type entry alone.
- */
-export type {};
+import { AnswerEliminatorProps } from './element-props.js';
+/** Native host interface for `<pie-tool-answer-eliminator>`. Properties may be unset until it mounts. */
+export interface PieToolAnswerEliminatorElement extends HTMLElement, AnswerEliminatorProps {
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        "pie-tool-answer-eliminator": PieToolAnswerEliminatorElement;
+    }
+}