@pie-players/pie-assessment-toolkit 0.2.0

package/src/components/QuestionToolBar.svelte

@@ -0,0 +1,406 @@
+<svelte:options
+	customElement={{
+		tag: 'pie-question-toolbar',
+		shadow: 'none',
+		props: {
+			itemId: { type: 'String', attribute: 'item-id' },
+			catalogId: { type: 'String', attribute: 'catalog-id' },
+			tools: { type: 'String', attribute: 'tools' },
+			size: { type: 'String', attribute: 'size' },
+			language: { type: 'String', attribute: 'language' },
+
+			// Services (passed as JS properties, not attributes)
+			ttsService: { type: 'Object', reflect: false },
+			toolCoordinator: { type: 'Object', reflect: false },
+			highlightCoordinator: { type: 'Object', reflect: false },
+			scopeElement: { type: 'Object', reflect: false },
+			elementToolStateStore: { type: 'Object', reflect: false },
+
+			// IDs for element-level state (passed as JS properties, not attributes)
+			assessmentId: { type: 'String', reflect: false },
+			sectionId: { type: 'String', reflect: false }
+		}
+	}}
+/>
+
+<!--
+  QuestionToolBar - Inline toolbar for question/passage headers
+
+  Displays tool buttons (TTS, Answer Eliminator, etc.) in a compact,
+  horizontal layout suitable for embedding in question headers.
+
+  Similar to the SchoolCity pattern where tool buttons appear next to
+  question titles rather than in a global sidebar.
+-->
+<script lang="ts">
+	import type {
+		IToolCoordinator,
+		ITTSService,
+		IHighlightCoordinator,
+	} from '../services/interfaces';
+
+	// NOTE: Tool web components must be imported by parent components
+	// that use QuestionToolBar (to avoid circular dependencies).
+	// Parent components should:
+	//   import '@pie-players/pie-tool-answer-eliminator';
+	//   import '@pie-players/pie-tool-tts-inline';
+	//   import '@pie-players/pie-tool-calculator-inline';
+
+	const isBrowser = typeof window !== 'undefined';
+
+	// Track if tools have been loaded
+	let toolsLoaded = $state(false);
+
+	/**
+	 * Detect if the scoped element contains compatible answer choices for the answer eliminator.
+	 * Checks for PIE multiple-choice, EBSR, and inline-dropdown elements.
+	 */
+	function hasCompatibleAnswerChoices(element: HTMLElement): boolean {
+		// Check for multiple-choice elements
+		const hasMultipleChoice = element.querySelector('.corespring-checkbox, .corespring-radio-button, .multiple-choice');
+		if (hasMultipleChoice) return true;
+
+		// Check for EBSR parts (extended constructed response with selectable parts)
+		const hasEBSR = element.querySelector('[class*="ebsr"]');
+		if (hasEBSR) return true;
+
+		// Check for inline-dropdown elements
+		const hasInlineDropdown = element.querySelector('inline-dropdown, .inline-dropdown, [class*="inline-dropdown"]');
+		if (hasInlineDropdown) return true;
+
+		return false;
+	}
+
+	// Props
+	let {
+		itemId = '',
+		catalogId = '',
+		tools = 'calculator,tts,answerEliminator',
+		ttsService,
+		toolCoordinator,
+		highlightCoordinator,
+		scopeElement = null,
+		elementToolStateStore,
+		assessmentId = '',
+		sectionId = '',
+		class: className = '',
+		size = 'md' as 'sm' | 'md' | 'lg',
+		language = 'en-US'
+	}: {
+		itemId?: string;
+		catalogId?: string;
+		tools?: string;
+		ttsService?: ITTSService;
+		toolCoordinator?: IToolCoordinator;
+		highlightCoordinator?: IHighlightCoordinator;
+		scopeElement?: HTMLElement | null;
+		elementToolStateStore?: any;
+		assessmentId?: string;
+		sectionId?: string;
+		class?: string;
+		size?: 'sm' | 'md' | 'lg';
+		language?: string;
+	} = $props();
+
+	// Generate globalElementId using store utility
+	let globalElementId = $derived.by(() => {
+		if (!elementToolStateStore || !assessmentId || !sectionId || !itemId) return null;
+		return elementToolStateStore.getGlobalElementId(assessmentId, sectionId, itemId, itemId);
+		// Note: Using itemId as elementId since toolbar is scoped to one item/element
+	});
+
+	// Parse enabled tools
+	let enabledTools = $derived(
+		tools
+			.split(',')
+			.map((t) => t.trim())
+			.filter(Boolean),
+	);
+
+	// Detect if current item has compatible choices for answer eliminator
+	let hasCompatibleChoices = $state(false);
+
+	$effect(() => {
+		if (!isBrowser || !scopeElement) {
+			hasCompatibleChoices = false;
+			return;
+		}
+
+		// Use MutationObserver to detect when PIE elements are rendered
+		const checkChoices = () => {
+			const hasChoices = hasCompatibleAnswerChoices(scopeElement);
+			hasCompatibleChoices = hasChoices;
+			console.debug('[QuestionToolBar] Checked choices:', {
+				scopeElementTag: scopeElement.tagName,
+				hasCompatibleChoices
+			});
+		};
+
+		// Initial check
+		checkChoices();
+
+		// Watch for DOM changes (PIE elements load asynchronously)
+		const observer = new MutationObserver(() => {
+			checkChoices();
+		});
+
+		observer.observe(scopeElement, {
+			childList: true,
+			subtree: true
+		});
+
+		return () => observer.disconnect();
+	});
+
+	// Dynamically load tool components based on enabled tools
+	$effect(() => {
+		if (!isBrowser || toolsLoaded) return;
+
+		(async () => {
+			const loadPromises = [];
+
+			if (enabledTools.includes('tts')) {
+				loadPromises.push(import('@pie-players/pie-tool-tts-inline'));
+			}
+			if (enabledTools.includes('answerEliminator')) {
+				loadPromises.push(import('@pie-players/pie-tool-answer-eliminator'));
+			}
+			if (enabledTools.includes('calculator')) {
+				loadPromises.push(
+					import('@pie-players/pie-tool-calculator-inline'),
+					import('@pie-players/pie-tool-calculator')
+				);
+			}
+
+			await Promise.all(loadPromises);
+			toolsLoaded = true;
+		})();
+	});
+
+	// Should show each tool
+	let showTTS = $derived(enabledTools.includes('tts') && ttsService && toolsLoaded);
+	let showAnswerEliminator = $derived(
+		enabledTools.includes('answerEliminator') &&
+		toolCoordinator &&
+		hasCompatibleChoices &&
+		toolsLoaded
+	);
+	let showCalculator = $derived(enabledTools.includes('calculator') && toolCoordinator && toolsLoaded);
+
+	// Track answer eliminator visibility state
+	let answerEliminatorVisible = $state(false);
+
+	// Subscribe to tool coordinator to update button state
+	$effect(() => {
+		if (!isBrowser || !toolCoordinator) return;
+
+		const unsubscribe = toolCoordinator.subscribe(() => {
+			answerEliminatorVisible = toolCoordinator.isToolVisible(
+				`answerEliminator-${itemId}`,
+			);
+		});
+
+		// Initial update
+		answerEliminatorVisible = toolCoordinator.isToolVisible(
+			`answerEliminator-${itemId}`,
+		);
+
+		return unsubscribe;
+	});
+
+	// TTS element reference for service binding
+	let ttsToolElement = $state<HTMLElement | null>(null);
+	let ttsBound = $state(false);
+
+	// Bind services to TTS tool
+	$effect(() => {
+		if (ttsToolElement && !ttsBound) {
+			if (toolCoordinator) {
+				(ttsToolElement as any).coordinator = toolCoordinator;
+			}
+			if (ttsService) {
+				(ttsToolElement as any).ttsService = ttsService;
+			}
+			if (highlightCoordinator) {
+				(ttsToolElement as any).highlightCoordinator = highlightCoordinator;
+			}
+			ttsBound = true;
+		}
+	});
+
+	// Answer eliminator element reference for scope binding
+	let answerEliminatorElement = $state<HTMLElement | null>(null);
+	let eliminatorBound = $state(false);
+
+	// Bind scope, coordinator, store, and globalElementId to answer eliminator
+	$effect(() => {
+		if (answerEliminatorElement && !eliminatorBound) {
+			if (toolCoordinator) {
+				(answerEliminatorElement as any).coordinator = toolCoordinator;
+			}
+			if (scopeElement) {
+				(answerEliminatorElement as any).scopeElement = scopeElement;
+			}
+			if (elementToolStateStore && globalElementId) {
+				(answerEliminatorElement as any).elementToolStateStore = elementToolStateStore;
+				(answerEliminatorElement as any).globalElementId = globalElementId;
+			}
+			eliminatorBound = true;
+		}
+	});
+
+	// Handle answer eliminator toggle
+	function toggleAnswerEliminator() {
+		if (!toolCoordinator) return;
+		toolCoordinator.toggleTool(`answerEliminator-${itemId}`);
+	}
+
+	// Calculator element reference for coordinator binding
+	let calculatorInlineElement = $state<HTMLElement | null>(null);
+	let calculatorBound = $state(false);
+
+	// Bind coordinator to calculator inline tool
+	$effect(() => {
+		if (calculatorInlineElement && !calculatorBound) {
+			if (toolCoordinator) {
+				(calculatorInlineElement as any).coordinator = toolCoordinator;
+			}
+			calculatorBound = true;
+		}
+	});
+</script>
+
+{#if isBrowser}
+	<div class="question-toolbar {className} question-toolbar--{size}">
+		<!-- Calculator Button (inline tool) -->
+		{#if showCalculator}
+			<pie-tool-calculator-inline
+				bind:this={calculatorInlineElement}
+				tool-id="calculator-inline-{itemId}"
+				calculator-type="scientific"
+				available-types="basic,scientific,graphing"
+				size={size}
+			></pie-tool-calculator-inline>
+		{/if}
+
+		<!-- TTS Button (inline tool) -->
+		{#if showTTS}
+			<pie-tool-tts-inline
+				bind:this={ttsToolElement}
+				tool-id="tts-{itemId}"
+				catalog-id={catalogId || itemId}
+				language={language}
+				size={size}
+			></pie-tool-tts-inline>
+		{/if}
+
+		<!-- Answer Eliminator Toggle Button -->
+		{#if showAnswerEliminator}
+			<button
+				type="button"
+				class="question-toolbar__button"
+				class:question-toolbar__button--active={answerEliminatorVisible}
+				onclick={toggleAnswerEliminator}
+				aria-label="Answer Eliminator"
+				aria-pressed={answerEliminatorVisible}
+				title="Toggle answer elimination mode"
+			>
+				<!-- X in Circle Icon (matches SchoolCity) -->
+				<svg
+					xmlns="http://www.w3.org/2000/svg"
+					viewBox="0 0 24 24"
+					width="20"
+					height="20"
+					fill="currentColor"
+					aria-hidden="true"
+				>
+					<path
+						d="M19,3H16.3H7.7H5A2,2 0 0,0 3,5V7.7V16.4V19A2,2 0 0,0 5,21H7.7H16.4H19A2,2 0 0,0 21,19V16.3V7.7V5A2,2 0 0,0 19,3M15.6,17L12,13.4L8.4,17L7,15.6L10.6,12L7,8.4L8.4,7L12,10.6L15.6,7L17,8.4L13.4,12L17,15.6L15.6,17Z"
+					/>
+				</svg>
+			</button>
+
+			<!-- Answer Eliminator Tool Instance (hidden, manages state) -->
+			<pie-tool-answer-eliminator
+				bind:this={answerEliminatorElement}
+				visible={answerEliminatorVisible}
+				tool-id="answerEliminator-{itemId}"
+				strategy="strikethrough"
+				button-alignment="inline"
+				coordinator={toolCoordinator}
+			></pie-tool-answer-eliminator>
+		{/if}
+	</div>
+{/if}
+
+<style>
+	.question-toolbar {
+		display: flex;
+		align-items: center;
+		gap: 0.5rem;
+	}
+
+	.question-toolbar__button {
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		width: 2rem;
+		height: 2rem;
+		padding: 0.25rem;
+		border: 1px solid var(--pie-border, #ccc);
+		border-radius: 0.25rem;
+		background-color: var(--pie-background, white);
+		color: var(--pie-text, #333);
+		cursor: pointer;
+		transition: all 0.15s ease;
+	}
+
+	.question-toolbar--sm .question-toolbar__button {
+		width: 1.5rem;
+		height: 1.5rem;
+	}
+
+	.question-toolbar--lg .question-toolbar__button {
+		width: 2.5rem;
+		height: 2.5rem;
+	}
+
+	.question-toolbar__button:hover:not(:disabled) {
+		background-color: var(
+			--pie-secondary-background,
+			#f5f5f5
+		);
+		transform: translateY(-1px);
+		box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
+	}
+
+	.question-toolbar__button:active:not(:disabled) {
+		transform: translateY(0);
+		box-shadow: none;
+	}
+
+	.question-toolbar__button--active {
+		background-color: var(--pie-primary, #1976d2);
+		color: white;
+		border-color: var(--pie-primary, #1976d2);
+	}
+
+	.question-toolbar__button--active:hover:not(:disabled) {
+		background-color: var(--pie-primary-dark, #1565c0);
+	}
+
+	.question-toolbar__button:focus-visible {
+		outline: 2px solid var(--pie-primary, #1976d2);
+		outline-offset: 2px;
+	}
+
+	.question-toolbar__button:disabled {
+		opacity: 0.5;
+		cursor: not-allowed;
+	}
+
+	.question-toolbar__button svg {
+		width: 100%;
+		height: 100%;
+	}
+</style>

package/src/player/AssessmentLayout.svelte

@@ -0,0 +1,68 @@
+<script lang="ts">
+	import type { AssessmentEntity } from '@pie-players/pie-players-shared';
+	import { onDestroy, onMount } from 'svelte';
+	import { ReferenceLayout } from '../reference-layout';
+	import { AssessmentPlayer } from './AssessmentPlayer';
+
+	let {
+		assessment,
+		bundleHost,
+		organizationId,
+		userName
+	}: {
+		assessment: AssessmentEntity;
+		bundleHost?: string;
+		organizationId?: string | null;
+		userName?: string;
+	} = $props();
+
+	let player = $state<AssessmentPlayer | null>(null);
+
+	onMount(() => {
+		// Initialize reference player
+		player = new AssessmentPlayer({
+			assessment,
+			organizationId: organizationId || undefined,
+			bundleHost,
+			mode: 'gather',
+			role: 'student',
+			enableTTS: true,
+			theme: {
+				highContrast: false,
+				fontSize: 'normal'
+			}
+		});
+
+		// Start at first item
+		player.start();
+	});
+
+	onDestroy(() => {
+		player?.destroy();
+	});
+</script>
+
+{#if player}
+	<ReferenceLayout {player} {assessment} {bundleHost} {organizationId} {userName} />
+{:else}
+	<div class="loading-container">
+		<span class="loading loading-spinner loading-lg"></span>
+		<p>Loading assessment...</p>
+	</div>
+{/if}
+
+<style>
+	.loading-container {
+		display: flex;
+		flex-direction: column;
+		align-items: center;
+		justify-content: center;
+		height: 100vh;
+		gap: 1rem;
+	}
+
+	.loading-container p {
+		color: var(--pie-text-secondary, #666);
+	}
+</style>
+

package/src/player/README.md

@@ -0,0 +1,154 @@
+# PIE Assessment Toolkit - Assessment Player
+
+This directory contains an **optional assessment player implementation** showing how to wire toolkit services together.
+
+## Purpose
+
+- **Learning**: See how services work together
+- **Quick Start**: Products can use as-is or extend
+- **Customization**: Extend or copy patterns
+
+Products like Quiz Engine can ignore this and use toolkit services directly.
+
+## What's Included
+
+- **AssessmentPlayer** - Core player class with navigation and state management
+- **ReferenceAssessmentLayout** - Complete assessment UI using reference layout
+- Linear navigation (sequential items)
+- Basic session state management
+- Event wiring examples
+
+## Architecture
+
+The default implementation consists of two parts:
+
+1. **AssessmentPlayer** (`AssessmentPlayer.ts`)
+   - Core business logic
+   - Navigation and state management
+   - Integration with assessment toolkit services
+   - Framework-agnostic (plain TypeScript class)
+
+2. **ReferenceAssessmentLayout** (TBD)
+   - Visual presentation layer
+   - Uses `ReferenceLayout` from `../reference-layout`
+   - Wires AssessmentPlayer to visual components
+   - Demonstrates complete assessment UI
+
+This separation allows:
+- **AssessmentPlayer** to be used with any layout
+- **ReferenceLayout** to be used independently or with other players
+- Products to mix and match components as needed
+
+## What's Not Included (Product-Specific)
+
+- Backend integration (each product different)
+- Adaptive navigation algorithms
+- Branching logic
+- Scoring/grading
+- LTI integration
+- Authentication/authorization
+
+## Usage
+
+### Using ReferenceAssessmentLayout (Recommended)
+
+The simplest way to get a complete assessment UI:
+
+```svelte
+<script>
+  import { ReferenceAssessmentLayout } from '@pie-framework/pie-assessment-toolkit/assessment-player/Layout.svelte';
+</script>
+
+<ReferenceAssessmentLayout
+  {assessment}
+  {organizationId}
+  bundleHost="prod"
+/>
+```
+
+### Using AssessmentPlayer Directly
+
+If you want to use your own layout:
+
+```typescript
+import { AssessmentPlayer } from '@pie-framework/pie-assessment-toolkit/assessment-player';
+
+const player = new AssessmentPlayer({
+  assessment,
+  organizationId,
+  bundleHost,
+  mode: 'gather',
+  role: 'student',
+  // ...
+});
+
+// Subscribe to state changes
+player.onNavigationChange((state) => {
+  // Handle navigation state
+});
+
+player.onItemChange((item) => {
+  // Handle item changes
+});
+
+// Navigate to first item
+await player.start();
+```
+
+### Using ReferenceLayout Directly
+
+If you want to use the reference layout with a different player:
+
+```svelte
+<script>
+  import { ReferenceLayout } from '$lib/assessment-toolkit/reference-layout';
+  // ... create your own player instance
+</script>
+
+<ReferenceLayout {player} {assessment} />
+```
+
+### Using Services Directly
+
+If you want complete control:
+
+```typescript
+import { TypedEventBus, ToolCoordinator, TTSService } from '$lib/assessment-toolkit';
+
+// Wire up services yourself
+const eventBus = new TypedEventBus();
+const toolCoordinator = new ToolCoordinator();
+const ttsService = TTSService.getInstance();
+// ...
+```
+
+## Directory Structure
+
+```
+reference-implementation/
+├── index.ts                    # Exports AssessmentPlayer and layout
+├── AssessmentPlayer.ts # Core player class (business logic)
+├── ReferenceAssessmentLayout.svelte # Complete UI wrapper (TBD)
+└── README.md                   # This file
+
+reference-layout/               # Reference layout implementation
+├── ReferenceLayout.svelte      # Main layout component
+├── components/                 # Sub-components
+└── README.md                   # Layout-specific docs
+```
+
+## Status
+
+🚧 **Under development** - Implementation in progress.
+
+### Completed
+- ✅ AssessmentPlayer class
+- ✅ Navigation and state management
+- ✅ Integration with assessment toolkit services
+
+### In Progress
+- 🚧 ReferenceAssessmentLayout wrapper
+- 🚧 ReferenceLayout implementation
+- 🚧 Visual components
+
+See [../reference-layout/LAYOUT-PLAN.md](../reference-layout/LAYOUT-PLAN.md) for detailed implementation plan.