@pie-players/pie-assessment-toolkit 0.2.0

package/src/reference-layout/README.md

@@ -0,0 +1,135 @@
+# Reference Layout
+
+A reference assessment layout implementation for PIE assessments.
+
+## Overview
+
+This directory contains a complete layout implementation demonstrating a production-ready assessment interface. It provides:
+
+- Three-column layout (passage | item | notes)
+- Top bar with accommodations and assessment controls
+- Navigation bar with question selector and numbered navigation
+- Bottom bar with item-level tools
+- Item-specific inline tools (answer eliminator, notes)
+
+## Architecture
+
+This layout is **presentation-only** - it orchestrates visual layout but delegates all business logic to:
+- `AssessmentPlayer` for navigation and state management
+- Assessment Toolkit services (ToolCoordinator, TTSService, etc.)
+- Existing tool components from `/lib/tags/tool-*`
+
+## Components
+
+### Main Component
+
+- **ReferenceLayout.svelte** - Main layout orchestrator
+
+### Sub-Components
+
+- **AssessmentHeader.svelte** - Top bar with accommodations and assessment actions
+- **AssessmentNavigation.svelte** - Question selector and numbered navigation
+- **AssessmentContent.svelte** - Three-column content container
+  - **PassagePanel.svelte** - Left column for passages (optional)
+  - **ItemPanel.svelte** - Middle column for questions/items
+  - **NotesPanel.svelte** - Right sidebar for notes (optional)
+- **AssessmentToolsBar.svelte** - Bottom bar with item-level tools
+- **AssessmentFooter.svelte** - Footer with navigation and actions
+
+## Usage
+
+### Direct Usage
+
+```svelte
+<script>
+  import { AssessmentPlayer } from '$lib/assessment-toolkit/reference-implementation';
+  import { ReferenceLayout } from '$lib/assessment-toolkit/reference-layout';
+
+  const player = new AssessmentPlayer({
+    assessment,
+    organizationId,
+    bundleHost,
+    mode: 'gather',
+    role: 'student',
+    // ...
+  });
+</script>
+
+<ReferenceLayout {player} {assessment} />
+```
+
+### Via Reference Implementation
+
+The reference implementation provides a wrapper that uses this layout:
+
+```svelte
+<script>
+  import { ReferenceAssessmentLayout } from '$lib/assessment-toolkit/reference-implementation';
+</script>
+
+<ReferenceAssessmentLayout {assessment} {organizationId} />
+```
+
+## Key Features
+
+### Tool Placement
+
+Tools are visually grouped into different areas but use the same interface:
+
+1. **Accommodations (Top Right)**
+   - Audio (TTS)
+   - Translation
+   - Contrast (Color Scheme)
+   - Fullscreen
+
+2. **Assessment Actions (Top Center)**
+   - Overall Instructions
+   - Resources
+   - Review Summary
+   - Finish Later
+   - Flag Question
+
+3. **Item-Level Tools (Bottom Bar)**
+   - Calculator
+   - Graph
+   - Periodic Table
+   - Protractor
+   - Line Reader
+   - Text Magnifier
+   - Ruler
+
+4. **Item-Specific (Inline)**
+   - Answer Eliminator (inline with choices)
+   - Notes (right sidebar)
+
+### Passage Support
+
+- Automatically detects passages from items
+- Loads passages on demand
+- Renders passages in left column using `<pie-iife-player>`
+
+### Responsive Design
+
+- Desktop: Full three-column layout
+- Tablet: Hides notes column, two-column layout
+- Mobile: Single column with tools in menu
+
+## Dependencies
+
+This layout requires:
+
+- `AssessmentPlayer` from `reference-implementation`
+- Assessment Toolkit services (ToolCoordinator, TTSService, etc.)
+- Existing tool components from `/lib/tags/tool-*`
+- `<pie-iife-player>` for rendering items and passages
+
+## Status
+
+🚧 **Under development** - Implementation in progress. See [LAYOUT-PLAN.md](./LAYOUT-PLAN.md) for detailed implementation plan.
+
+## Related Documentation
+
+- [LAYOUT-PLAN.md](./LAYOUT-PLAN.md) - Detailed implementation plan
+- [../reference-implementation/README.md](../reference-implementation/README.md) - Reference implementation documentation
+- [../../docs/tools-high-level-architecture.md](../../docs/tools-high-level-architecture.md) - Tools architecture overview
+

package/src/reference-layout/ReferenceLayout.svelte

@@ -0,0 +1,209 @@
+<script lang="ts">
+	
+	import type { AssessmentEntity, ItemConfig, ItemEntity, PassageEntity, RubricBlock } from '@pie-players/pie-players-shared/types';
+	import ToolAnnotationToolbar from '@pie-players/pie-tool-annotation-toolbar';
+	import { onDestroy, onMount } from 'svelte';
+	import type { AssessmentPlayer } from '../player/AssessmentPlayer';
+	import AssessmentContent from './components/AssessmentContent.svelte';
+	import AssessmentFooter from './components/AssessmentFooter.svelte';
+	import AssessmentHeader from './components/AssessmentHeader.svelte';
+	import AssessmentNavigation from './components/AssessmentNavigation.svelte';
+	import AssessmentToolsBar from './components/AssessmentToolsBar.svelte';
+
+	let {
+		player,
+		assessment,
+		bundleHost,
+		organizationId,
+		userName
+	}: {
+		player: AssessmentPlayer;
+		assessment: AssessmentEntity;
+		bundleHost?: string;
+		organizationId?: string | null;
+		userName?: string;
+	} = $props();
+
+	// State from player
+	let currentItem = $state<ItemEntity | null>(null);
+	let currentConfig = $state<ItemConfig | null>(null);
+	let sessionState = $state<{ id: string; data: any[] }>({ id: '', data: [] });
+	let navigationState = $state({
+		currentIndex: 0,
+		totalItems: 0,
+		canNext: false,
+		canPrevious: false,
+		isLoading: true
+	});
+	let isLoadingItem = $state(true);
+	let passage = $state<PassageEntity | null>(null);
+	let rubricBlocks = $state<RubricBlock[]>([]);
+
+	// Picture Dictionary Modal state
+	let showPictureDictionaryModal = $state(false);
+	let pictureDictionaryWord = $state('');
+
+	// Annotation toolbar event handlers
+	function handleDictionaryLookup(detail: { text: string }) {
+		// TODO: Open dictionary modal
+		console.log('Dictionary lookup:', detail.text);
+	}
+
+	function handleTranslationRequest(detail: { text: string }) {
+		// TODO: Open translation modal
+		console.log('Translation request:', detail.text);
+	}
+
+	function handlePictureDictionaryLookup(detail: { text: string }) {
+		pictureDictionaryWord = detail.text;
+		showPictureDictionaryModal = true;
+	}
+
+	// Load passage when item changes
+	async function loadPassage(item: ItemEntity | null) {
+		if (!item?.passage) {
+			passage = null;
+			return;
+		}
+
+		// If passage is already a full entity, use it
+		if (typeof item.passage === 'object' && 'id' in item.passage) {
+			passage = item.passage as PassageEntity;
+			return;
+		}
+
+		// Otherwise load by ID
+		if (typeof item.passage === 'string') {
+			try {
+				const url = organizationId
+					? `/api/passage/${item.passage}?organizationId=${encodeURIComponent(organizationId)}`
+					: `/api/passage/${item.passage}`;
+				const response = await fetch(url);
+				if (response.ok) {
+					passage = await response.json();
+				} else {
+					passage = null;
+				}
+			} catch (error) {
+				console.error('[ReferenceLayout] Error loading passage:', error);
+				passage = null;
+			}
+		}
+	}
+
+	// Subscribe to player state changes
+	let unsubNav: (() => void) | null = null;
+	let unsubItem: (() => void) | null = null;
+	let unsubLoading: (() => void) | null = null;
+	let unsubSession: (() => void) | null = null;
+
+	onMount(() => {
+		unsubNav = player.onNavigationChange((state) => {
+			navigationState = state;
+			rubricBlocks =
+				player
+					.getCurrentSectionRubricBlocks()
+					.filter((b) => b.view === 'candidate');
+		});
+
+		unsubItem = player.onItemChange((item) => {
+			currentItem = item;
+			currentConfig = item?.config as ItemConfig | null;
+			loadPassage(item);
+		});
+
+		unsubLoading = player.onLoadingChange((loading) => {
+			isLoadingItem = loading;
+		});
+
+		unsubSession = player.onSessionChange((session) => {
+			sessionState = session;
+		});
+	});
+
+	onDestroy(() => {
+		unsubNav?.();
+		unsubItem?.();
+		unsubLoading?.();
+		unsubSession?.();
+	});
+</script>
+
+<div class="reference-layout">
+	<!-- Header -->
+	<AssessmentHeader
+		{player}
+		{assessment}
+		currentQuestion={navigationState.currentIndex + 1}
+		totalQuestions={navigationState.totalItems}
+		{userName}
+	/>
+
+	<!-- Navigation -->
+	<AssessmentNavigation
+		{player}
+		currentIndex={navigationState.currentIndex}
+		totalItems={navigationState.totalItems}
+	/>
+
+	<!-- Main Content -->
+	<AssessmentContent
+		{player}
+		currentItem={currentItem}
+		config={currentConfig}
+		{passage}
+		{rubricBlocks}
+		session={sessionState}
+		{bundleHost}
+		{organizationId}
+		isLoading={isLoadingItem}
+	/>
+
+	<!-- Tools Bar -->
+	<AssessmentToolsBar {player} />
+
+	<!-- Footer -->
+	<AssessmentFooter
+		{player}
+		currentQuestion={navigationState.currentIndex + 1}
+		totalQuestions={navigationState.totalItems}
+		canNext={navigationState.canNext}
+		canPrevious={navigationState.canPrevious}
+	/>
+</div>
+
+<!-- Annotation Toolbar (floating, appears on text selection) -->
+<!-- Outside layout container to avoid overflow: hidden affecting fixed positioning -->
+<ToolAnnotationToolbar
+	enabled={true}
+	ttsService={player.getTTSService()}
+	highlightCoordinator={player.getHighlightCoordinator()}
+	ondictionarylookup={handleDictionaryLookup}
+	ontranslationrequest={handleTranslationRequest}
+	onpicturedictionarylookup={handlePictureDictionaryLookup}
+/>
+
+<!-- Picture Dictionary Modal -->
+<PictureDictionaryModal
+	bind:visible={showPictureDictionaryModal}
+	word={pictureDictionaryWord}
+	organizationId={organizationId || undefined}
+/>
+
+<style>
+	.reference-layout {
+		display: grid;
+		grid-template-rows: auto auto 1fr auto auto;
+		grid-template-columns: 1fr;
+		height: 100%;
+		min-height: 0;
+		overflow: hidden;
+		background-color: var(--pie-background, #ffffff);
+	}
+
+	/* Ensure grid rows don't overflow */
+	:global(.reference-layout > *) {
+		min-height: 0;
+	}
+</style>
+

package/src/reference-layout/components/AssessmentContent.svelte

@@ -0,0 +1,259 @@
+<script lang="ts">
+	
+	import type { ItemConfig, ItemEntity, PassageEntity, RubricBlock } from '@pie-players/pie-players-shared/types';
+	import { onDestroy, onMount } from 'svelte';
+	import type { AssessmentPlayer } from '../../player/AssessmentPlayer';
+	import ItemPanel from './ItemPanel.svelte';
+	import NotesPanel from './NotesPanel.svelte';
+	import PassagePanel from './PassagePanel.svelte';
+
+	let {
+		player,
+		currentItem,
+		config,
+		passage,
+		rubricBlocks = [],
+		session,
+		bundleHost,
+		organizationId,
+		isLoading = false
+	}: {
+		player: AssessmentPlayer;
+		currentItem: ItemEntity | null;
+		config: ItemConfig | null;
+		passage: PassageEntity | null;
+		rubricBlocks?: RubricBlock[];
+		session: { id: string; data: any[] };
+		bundleHost?: string;
+		organizationId?: string | null;
+		isLoading?: boolean;
+	} = $props();
+
+	let containerEl = $state<HTMLDivElement | null>(null);
+	let passagePanelEl = $state<HTMLDivElement | null>(null);
+	let itemPanelEl = $state<HTMLDivElement | null>(null);
+	let dividerEl = $state<HTMLDivElement | null>(null);
+	let notesDividerEl = $state<HTMLDivElement | null>(null);
+
+	// Resize state
+	let isDragging = $state(false);
+	let startX = $state(0);
+	let passageWidth = $state(300); // Initial width in pixels
+	let minPassageWidth = 200;
+	let maxPassageWidth = 800;
+
+	const hasPassage = $derived(
+		(passage !== null) || (rubricBlocks?.length ?? 0) > 0,
+	);
+
+	// Notes sidebar
+	let showNotes = $state(true);
+	const notesWidth = 320;
+
+	// Calculate grid columns dynamically
+	const gridColumns = $derived.by(() => {
+		const parts: string[] = [];
+
+		if (hasPassage) {
+			parts.push(`${passageWidth}px`, 'auto');
+		}
+
+		// Item column always present
+		parts.push('1fr');
+
+		// Notes column (optional)
+		if (showNotes) {
+			parts.push('auto', `${notesWidth}px`);
+		}
+
+		return parts.join(' ');
+	});
+
+	function handleDividerMouseDown(e: MouseEvent) {
+		if (!hasPassage) return;
+		isDragging = true;
+		startX = e.clientX;
+		document.body.style.cursor = 'col-resize';
+		document.body.style.userSelect = 'none';
+
+		window.addEventListener('mousemove', handleMouseMove);
+		window.addEventListener('mouseup', handleMouseUp);
+	}
+
+	function handleMouseMove(e: MouseEvent) {
+		if (!isDragging || !containerEl) return;
+
+		const deltaX = e.clientX - startX;
+		const containerRect = containerEl.getBoundingClientRect();
+		const newWidth = passageWidth + deltaX;
+		const constrainedWidth = Math.max(
+			minPassageWidth,
+			Math.min(maxPassageWidth, newWidth)
+		);
+
+		passageWidth = constrainedWidth;
+		startX = e.clientX;
+	}
+
+	function handleMouseUp() {
+		isDragging = false;
+		document.body.style.cursor = '';
+		document.body.style.userSelect = '';
+
+		window.removeEventListener('mousemove', handleMouseMove);
+		window.removeEventListener('mouseup', handleMouseUp);
+	}
+
+	function handleKeyDown(e: KeyboardEvent) {
+		if (!hasPassage) return;
+		
+		const step = 10; // pixels per keypress
+		let deltaX = 0;
+		
+		if (e.key === 'ArrowLeft') {
+			deltaX = -step;
+		} else if (e.key === 'ArrowRight') {
+			deltaX = step;
+		} else {
+			return; // Ignore other keys
+		}
+		
+		e.preventDefault();
+		const newWidth = passageWidth + deltaX;
+		const constrainedWidth = Math.max(
+			minPassageWidth,
+			Math.min(maxPassageWidth, newWidth)
+		);
+		passageWidth = constrainedWidth;
+	}
+
+	onMount(() => {
+		// Persist width to localStorage
+		const savedWidth = localStorage.getItem('schoolcity-passage-width');
+		if (savedWidth) {
+			passageWidth = parseInt(savedWidth, 10);
+		}
+	});
+
+	onDestroy(() => {
+		// Save width to localStorage
+		localStorage.setItem('schoolcity-passage-width', String(passageWidth));
+		handleMouseUp(); // Clean up any active drag
+	});
+</script>
+
+<div class="assessment-content" bind:this={containerEl} style="grid-template-columns: {gridColumns}">
+	{#if hasPassage}
+		<!-- Passage Panel -->
+		<div class="passage-container" bind:this={passagePanelEl}>
+			<PassagePanel {passage} {rubricBlocks} {bundleHost} env={player.getEnv()} />
+		</div>
+
+		<!-- Resizable Divider -->
+		<div
+			class="divider"
+			class:dragging={isDragging}
+			bind:this={dividerEl}
+			onmousedown={handleDividerMouseDown}
+			onkeydown={handleKeyDown}
+			role="button"
+			aria-label="Resize passage panel"
+			tabindex="0"
+		>
+			<div class="divider-handle"></div>
+		</div>
+	{/if}
+
+	<!-- Item Panel -->
+	<div class="item-container" bind:this={itemPanelEl}>
+		<ItemPanel
+			{currentItem}
+			{config}
+			{session}
+			{bundleHost}
+			env={player.getEnv()}
+			toolCoordinator={player.getToolCoordinator()}
+			{isLoading}
+		/>
+	</div>
+
+	{#if showNotes}
+		<!-- Notes Divider (visual only for now) -->
+		<div class="divider notes-divider" bind:this={notesDividerEl} aria-hidden="true">
+			<div class="divider-handle"></div>
+		</div>
+
+		<!-- Notes Panel -->
+		<div class="notes-container">
+			<NotesPanel
+				itemId={currentItem?.id || ''}
+				itemLabel={currentItem?.name || ''}
+				onClose={() => (showNotes = false)}
+			/>
+		</div>
+	{/if}
+</div>
+
+<style>
+	.assessment-content {
+		display: grid;
+		gap: 0;
+		overflow: hidden;
+		position: relative;
+		min-height: 0;
+		height: 100%;
+	}
+
+	.passage-container,
+	.item-container,
+	.notes-container {
+		overflow-y: auto;
+		overflow-x: hidden;
+		background-color: var(--pie-background, #ffffff);
+	}
+
+	.divider {
+		position: relative;
+		width: 4px;
+		background-color: var(--pie-border, #e0e0e0);
+		cursor: col-resize;
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		transition: background-color 0.2s;
+	}
+
+	.divider:hover,
+	.divider.dragging {
+		background-color: var(--pie-primary, #3f51b5);
+	}
+
+	.divider-handle {
+		width: 2px;
+		height: 40px;
+		background-color: var(--pie-text-secondary, #666);
+		border-radius: 1px;
+	}
+
+	.divider.dragging .divider-handle {
+		background-color: var(--pie-primary, #3f51b5);
+	}
+
+	.divider:focus {
+		outline: 2px solid var(--pie-primary, #3f51b5);
+		outline-offset: -2px;
+	}
+
+	.notes-divider {
+		cursor: default;
+	}
+
+	/* On narrow screens, hide notes by default */
+	@media (max-width: 1100px) {
+		.notes-container,
+		.notes-divider {
+			display: none;
+		}
+	}
+</style>
+

package/src/reference-layout/components/AssessmentFooter.svelte

@@ -0,0 +1,89 @@
+<script lang="ts">
+	import type { AssessmentPlayer } from '../../player/AssessmentPlayer';
+
+	let {
+		player,
+		currentQuestion,
+		totalQuestions,
+		canNext,
+		canPrevious
+	}: {
+		player: AssessmentPlayer;
+		currentQuestion: number;
+		totalQuestions: number;
+		canNext: boolean;
+		canPrevious: boolean;
+	} = $props();
+
+	function handlePrevious() {
+		player.navigatePrevious();
+	}
+
+	function handleNext() {
+		player.navigateNext();
+	}
+</script>
+
+<footer class="assessment-footer">
+	<!-- Question Counter and Navigation -->
+	<div class="footer-content">
+		<span class="question-counter">Question {currentQuestion} of {totalQuestions}</span>
+		<div class="navigation-buttons">
+			<button class="nav-button" onclick={handlePrevious} disabled={!canPrevious}>
+				← Back
+			</button>
+			<button class="nav-button" onclick={handleNext} disabled={!canNext}>
+				Next →
+			</button>
+		</div>
+	</div>
+</footer>
+
+<style>
+	.assessment-footer {
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		padding: 0.75rem 1rem;
+		background-color: var(--pie-background, #ffffff);
+		border-top: 1px solid var(--pie-border, #e0e0e0);
+		min-height: 56px;
+	}
+
+	.footer-content {
+		display: flex;
+		align-items: center;
+		gap: 1rem;
+	}
+
+	.question-counter {
+		font-size: 0.875rem;
+		color: var(--pie-text, #000);
+		font-weight: 500;
+	}
+
+	.navigation-buttons {
+		display: flex;
+		gap: 0.5rem;
+	}
+
+	.nav-button {
+		padding: 0.5rem 1rem;
+		background-color: var(--pie-background, #ffffff);
+		border: 1px solid var(--pie-border, #e0e0e0);
+		border-radius: 4px;
+		cursor: pointer;
+		font-size: 0.875rem;
+		color: var(--pie-text, #000);
+	}
+
+	.nav-button:hover:not(:disabled) {
+		background-color: var(--pie-secondary-background, #f5f5f5);
+	}
+
+	.nav-button:disabled {
+		opacity: 0.5;
+		cursor: not-allowed;
+	}
+</style>
+