@pie-players/pie-tool-answer-eliminator 0.2.0

package/README.md

@@ -0,0 +1,282 @@
+# @pie-players/pie-tool-answer-eliminator
+
+Test-taking strategy tool that allows students to eliminate answer choices they believe are incorrect.
+
+## Features
+
+- **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
+- **ElementToolStateStore Integration**: Works with Assessment Toolkit's state management
+
+## Installation
+
+```bash
+npm install @pie-players/pie-tool-answer-eliminator
+# or
+bun add @pie-players/pie-tool-answer-eliminator
+```
+
+## Usage
+
+### As Web Component
+
+The answer eliminator is automatically integrated when using the PIE Section Player with ToolkitCoordinator:
+
+```html
+<script type="module">
+  import '@pie-players/pie-section-player';
+  import { ToolkitCoordinator } from '@pie-players/pie-assessment-toolkit';
+
+  const coordinator = new ToolkitCoordinator({
+    assessmentId: 'my-assessment',
+    tools: {
+      answerEliminator: { enabled: true }
+    }
+  });
+
+  const player = document.getElementById('player');
+  player.toolkitCoordinator = coordinator;
+  player.section = mySection;
+</script>
+
+<pie-section-player id="player"></pie-section-player>
+```
+
+The section player automatically:
+- Renders answer eliminator buttons in question toolbars
+- Generates global element IDs
+- Passes ElementToolStateStore to the tool
+- Manages state lifecycle
+
+### Manual Integration (Advanced)
+
+For custom implementations outside the section player:
+
+```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');
+</script>
+
+<pie-tool-answer-eliminator></pie-tool-answer-eliminator>
+```
+
+## Props/Attributes
+
+The web component accepts the following properties (set via JavaScript, not HTML attributes):
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `globalElementId` | `string` | Yes | Composite key: `assessmentId:sectionId:itemId:elementId` |
+| `elementToolStateStore` | `IElementToolStateStore` | Yes | Store for element-level tool state |
+| `scopeElement` | `HTMLElement` | No | DOM element to scope choice detection (defaults to document) |
+
+## Global Element ID Format
+
+The tool uses globally unique composite keys for state management:
+
+```
+${assessmentId}:${sectionId}:${itemId}:${elementId}
+```
+
+**Example:**
+```typescript
+"demo-assessment:section-1:question-1:mc1"
+"biology-exam:section-2:genetics-q1:ebsr-part1"
+```
+
+### 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
+
+### Why Element-Level?
+
+Items can contain **multiple interactive elements** (e.g., EBSR with two parts). Each element needs independent state:
+
+```typescript
+// ✅ Correct: Element-level state
+{
+  "demo:section-1:question-1:ebsr-part1": {
+    "answerEliminator": { "eliminatedChoices": ["choice-a", "choice-c"] }
+  },
+  "demo:section-1:question-1:ebsr-part2": {
+    "answerEliminator": { "eliminatedChoices": ["choice-b"] }
+  }
+}
+```
+
+## State Management
+
+### Ephemeral vs Persistent State
+
+The answer eliminator stores state in **ElementToolStateStore** (ephemeral, client-only):
+
+**Tool State (Ephemeral - NOT sent to server):**
+```typescript
+{
+  "demo:section-1:question-1:mc1": {
+    "answerEliminator": {
+      "eliminatedChoices": ["choice-b", "choice-d"]
+    }
+  }
+}
+```
+
+**PIE Session Data (Persistent - sent to server for scoring):**
+```typescript
+{
+  "question-1": {
+    "id": "session-123",
+    "data": [
+      { "id": "mc1", "element": "multiple-choice", "value": ["choice-a"] }
+    ]
+  }
+}
+```
+
+### Persistence Integration
+
+To persist tool state across page refreshes:
+
+```typescript
+const coordinator = new ToolkitCoordinator({
+  assessmentId: 'my-assessment',
+  tools: { answerEliminator: { enabled: true } }
+});
+
+// Save to localStorage on change
+const storageKey = `tool-state:${coordinator.assessmentId}`;
+coordinator.elementToolStateStore.setOnStateChange((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
+
+### 1. Choice Detection
+
+The tool automatically detects answer choices within the scoped element:
+
+```typescript
+// Searches for choice elements with these patterns
+const choiceSelectors = [
+  '[data-choice-id]',           // PIE standard
+  '.choice',                     // Common class
+  '[role="radio"]',              // Accessibility
+  '[role="checkbox"]',           // Accessibility
+  'input[type="radio"]',         // Native inputs
+  'input[type="checkbox"]'       // Native inputs
+];
+```
+
+### 2. State Storage
+
+Eliminated choices are stored by choice ID:
+
+```typescript
+{
+  "eliminatedChoices": ["choice-a", "choice-c"]
+}
+```
+
+### 3. Visual Feedback
+
+Eliminated choices receive the `eliminated` CSS class:
+
+```css
+.choice.eliminated {
+  text-decoration: line-through;
+  opacity: 0.5;
+}
+```
+
+### 4. Toggle Behavior
+
+Clicking a choice toggles its elimination state:
+
+```typescript
+// First click: eliminate
+choiceElement.classList.add('eliminated');
+
+// Second click: restore
+choiceElement.classList.remove('eliminated');
+```
+
+## Cleanup
+
+The ElementToolStateStore provides cleanup methods:
+
+```typescript
+// Clear state for a specific element
+store.clearElement('demo:section-1:question-1:mc1');
+
+// Clear all answer eliminator state across all elements
+store.clearTool('answerEliminator');
+
+// Clear all elements in a section
+store.clearSection('demo', 'section-1');
+
+// Clear all state
+store.clearAll();
+```
+
+## TypeScript Support
+
+Full TypeScript definitions included:
+
+```typescript
+import type { IElementToolStateStore } from '@pie-players/pie-assessment-toolkit';
+
+interface AnswerEliminatorState {
+  eliminatedChoices: string[];
+}
+```
+
+## 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
+
+## Related Documentation
+
+- [ToolkitCoordinator Architecture](../../docs/architecture/TOOLKIT_COORDINATOR.md) - Element-level state design
+- [Assessment Toolkit README](../assessment-toolkit/README.md) - Toolkit overview
+- [Section Player README](../section-player/README.md) - Integration guide
+
+## License
+
+MIT

package/adapters/adapter-registry.ts

@@ -0,0 +1,64 @@
+import type { ChoiceAdapter } from "./choice-adapter";
+import { EBSRAdapter } from "./ebsr-adapter";
+import { InlineDropdownAdapter } from "./inline-dropdown-adapter";
+import { MultipleChoiceAdapter } from "./multiple-choice-adapter";
+
+export interface ChoiceWithAdapter {
+	choice: HTMLElement;
+	adapter: ChoiceAdapter;
+}
+
+/**
+ * Registry for choice adapters
+ * Automatically detects which adapter to use for different PIE elements
+ */
+export class AdapterRegistry {
+	private adapters: ChoiceAdapter[];
+
+	constructor() {
+		// Register adapters in priority order (higher priority first)
+		this.adapters = [
+			new MultipleChoiceAdapter(),
+			new EBSRAdapter(),
+			new InlineDropdownAdapter(),
+		].sort((a, b) => b.priority - a.priority);
+	}
+
+	/**
+	 * Find the appropriate adapter for an element
+	 */
+	findAdapter(element: HTMLElement): ChoiceAdapter | null {
+		return this.adapters.find((adapter) => adapter.canHandle(element)) || null;
+	}
+
+	/**
+	 * Find all choices with their adapters within a root element
+	 */
+	findAllChoicesWithAdapters(root: HTMLElement): ChoiceWithAdapter[] {
+		const results: ChoiceWithAdapter[] = [];
+		const processedChoices = new Set<HTMLElement>();
+
+		// Try each adapter
+		for (const adapter of this.adapters) {
+			const choices = adapter.findChoices(root);
+
+			for (const choice of choices) {
+				// Avoid duplicates (in case adapters overlap)
+				if (processedChoices.has(choice)) continue;
+
+				processedChoices.add(choice);
+				results.push({ choice, adapter });
+			}
+		}
+
+		return results;
+	}
+
+	/**
+	 * Register a custom adapter
+	 */
+	registerAdapter(adapter: ChoiceAdapter): void {
+		this.adapters.push(adapter);
+		this.adapters.sort((a, b) => b.priority - a.priority);
+	}
+}

package/adapters/choice-adapter.ts

@@ -0,0 +1,50 @@
+/**
+ * Adapter interface for detecting and working with choice elements
+ * from different PIE element types.
+ *
+ * Adapters enable the answer eliminator to work generically with
+ * multiple-choice, EBSR, inline-dropdown, and future choice elements.
+ */
+export interface ChoiceAdapter {
+	/** Element type this adapter handles */
+	readonly elementType: string;
+
+	/** Priority (higher = checked first) */
+	readonly priority: number;
+
+	/**
+	 * Check if this adapter can handle the given element
+	 */
+	canHandle(element: HTMLElement): boolean;
+
+	/**
+	 * Find all choice elements within the root
+	 */
+	findChoices(root: HTMLElement): HTMLElement[];
+
+	/**
+	 * Create a Range covering the choice content (for CSS Highlight API)
+	 */
+	createChoiceRange(choice: HTMLElement): Range | null;
+
+	/**
+	 * Get unique identifier for this choice (for persistence)
+	 */
+	getChoiceId(choice: HTMLElement): string;
+
+	/**
+	 * Get human-readable label (for screen readers)
+	 */
+	getChoiceLabel(choice: HTMLElement): string;
+
+	/**
+	 * Check if choice can be eliminated
+	 * (not already selected, not in evaluate mode, etc.)
+	 */
+	canEliminate(choice: HTMLElement): boolean;
+
+	/**
+	 * Get the container element to attach elimination button
+	 */
+	getButtonContainer(choice: HTMLElement): HTMLElement | null;
+}

package/adapters/ebsr-adapter.ts

@@ -0,0 +1,61 @@
+import type { ChoiceAdapter } from "./choice-adapter";
+import { MultipleChoiceAdapter } from "./multiple-choice-adapter";
+
+/**
+ * Adapter for EBSR (Evidence-Based Selected Response) elements
+ *
+ * EBSR contains two multiple-choice questions (Part A and Part B),
+ * so we delegate to MultipleChoiceAdapter and prefix IDs with part identifier
+ */
+export class EBSRAdapter implements ChoiceAdapter {
+	readonly elementType = "ebsr";
+	readonly priority = 95;
+
+	private mcAdapter = new MultipleChoiceAdapter();
+
+	canHandle(element: HTMLElement): boolean {
+		return (
+			element.tagName.toLowerCase() === "ebsr" ||
+			element.querySelector("ebsr-multiple-choice") !== null
+		);
+	}
+
+	findChoices(root: HTMLElement): HTMLElement[] {
+		// EBSR contains ebsr-multiple-choice elements
+		// Find choices in both Part A and Part B
+		const partA = root.querySelector('ebsr-multiple-choice[id="a"]');
+		const partB = root.querySelector('ebsr-multiple-choice[id="b"]');
+
+		const choices: HTMLElement[] = [];
+		if (partA)
+			choices.push(...this.mcAdapter.findChoices(partA as HTMLElement));
+		if (partB)
+			choices.push(...this.mcAdapter.findChoices(partB as HTMLElement));
+
+		return choices;
+	}
+
+	// Delegate all other methods to MultipleChoiceAdapter
+	createChoiceRange(choice: HTMLElement): Range | null {
+		return this.mcAdapter.createChoiceRange(choice);
+	}
+
+	getChoiceId(choice: HTMLElement): string {
+		// Prefix with part ID (a or b)
+		const part = choice.closest("ebsr-multiple-choice")?.id || "unknown";
+		const choiceId = this.mcAdapter.getChoiceId(choice);
+		return `${part}-${choiceId}`;
+	}
+
+	getChoiceLabel(choice: HTMLElement): string {
+		return this.mcAdapter.getChoiceLabel(choice);
+	}
+
+	canEliminate(choice: HTMLElement): boolean {
+		return this.mcAdapter.canEliminate(choice);
+	}
+
+	getButtonContainer(choice: HTMLElement): HTMLElement | null {
+		return this.mcAdapter.getButtonContainer(choice);
+	}
+}

package/adapters/inline-dropdown-adapter.ts

@@ -0,0 +1,46 @@
+import type { ChoiceAdapter } from "./choice-adapter";
+
+/**
+ * Adapter for PIE inline-dropdown elements
+ *
+ * Works with dropdown menu items (role="option")
+ */
+export class InlineDropdownAdapter implements ChoiceAdapter {
+	readonly elementType = "inline-dropdown";
+	readonly priority = 90;
+
+	canHandle(element: HTMLElement): boolean {
+		return (
+			element.tagName.toLowerCase() === "inline-dropdown" ||
+			element.querySelector('[role="combobox"]') !== null
+		);
+	}
+
+	findChoices(root: HTMLElement): HTMLElement[] {
+		// Find dropdown menu items
+		return Array.from(root.querySelectorAll<HTMLElement>('[role="option"]'));
+	}
+
+	createChoiceRange(choice: HTMLElement): Range | null {
+		const range = document.createRange();
+		range.selectNodeContents(choice);
+		return range;
+	}
+
+	getChoiceId(choice: HTMLElement): string {
+		return choice.id || choice.getAttribute("data-value") || "";
+	}
+
+	getChoiceLabel(choice: HTMLElement): string {
+		return choice.textContent?.trim() || "Unlabeled option";
+	}
+
+	canEliminate(choice: HTMLElement): boolean {
+		// Can't eliminate if already selected
+		return choice.getAttribute("aria-selected") !== "true";
+	}
+
+	getButtonContainer(choice: HTMLElement): HTMLElement | null {
+		return choice;
+	}
+}

package/adapters/multiple-choice-adapter.ts

@@ -0,0 +1,96 @@
+import type { ChoiceAdapter } from "./choice-adapter";
+
+/**
+ * Adapter for PIE multiple-choice elements
+ *
+ * Works with both single-select (radio) and multiple-select (checkbox) modes
+ * Detects PIE's corespring-checkbox and corespring-radio-button classes
+ */
+export class MultipleChoiceAdapter implements ChoiceAdapter {
+	readonly elementType = "multiple-choice";
+	readonly priority = 100;
+
+	canHandle(element: HTMLElement): boolean {
+		return (
+			element.tagName.toLowerCase() === "multiple-choice" ||
+			element.classList.contains("multiple-choice")
+		);
+	}
+
+	findChoices(root: HTMLElement): HTMLElement[] {
+		// Find by PIE's corespring classes
+		return Array.from(
+			root.querySelectorAll<HTMLElement>(
+				".corespring-checkbox, .corespring-radio-button",
+			),
+		);
+	}
+
+	createChoiceRange(choice: HTMLElement): Range | null {
+		// Create range covering the label content
+		// Try multiple possible selectors for the label
+		const labelElement =
+			choice.querySelector(".label") ||
+			choice.querySelector("label") ||
+			choice.querySelector('[class*="label"]') ||
+			choice.querySelector("span");
+
+		if (!labelElement) {
+			return null;
+		}
+
+		const range = document.createRange();
+		range.selectNodeContents(labelElement);
+		return range;
+	}
+
+	getChoiceId(choice: HTMLElement): string {
+		// Get value from input element
+		const input = choice.querySelector(
+			'input[type="checkbox"], input[type="radio"]',
+		);
+		return (
+			input?.getAttribute("value") ||
+			input?.id ||
+			this.generateFallbackId(choice)
+		);
+	}
+
+	getChoiceLabel(choice: HTMLElement): string {
+		const label = choice.querySelector(".label");
+		return label?.textContent?.trim() || "Unlabeled choice";
+	}
+
+	canEliminate(choice: HTMLElement): boolean {
+		const input = choice.querySelector(
+			'input[type="checkbox"], input[type="radio"]',
+		);
+		if (!input) return false;
+
+		// Can't eliminate if:
+		// 1. Already selected (checked)
+		if (input.getAttribute("aria-checked") === "true") return false;
+
+		// 2. Disabled
+		if ((input as HTMLInputElement).disabled) return false;
+
+		// 3. In evaluate/view mode (has feedback tick)
+		if (choice.closest(".multiple-choice")?.querySelector(".feedback-tick"))
+			return false;
+
+		return true;
+	}
+
+	getButtonContainer(choice: HTMLElement): HTMLElement | null {
+		// Return the choice-input container
+		return choice;
+	}
+
+	private generateFallbackId(choice: HTMLElement): string {
+		// Generate stable ID based on choice position
+		const parent = choice.closest(".multiple-choice");
+		const choices = parent?.querySelectorAll(".choice-input") || [];
+		const index = Array.from(choices).indexOf(choice);
+		return `choice-${index}`;
+	}
+}