@pie-players/pie-players-shared 0.2.0

package/src/components/PiePreviewLayout.svelte

@@ -0,0 +1,144 @@
+<!--
+  PiePreviewLayout - Layout container for authoring with preview
+
+  Combines PiePreviewToggle with conditional rendering of PieItemPlayer instances.
+  Switches between authoring mode (configure elements) and preview mode (regular player elements).
+-->
+<script lang="ts">
+	import { tick } from 'svelte';
+	import type { LoaderConfig } from '../loader-config';
+	import { DEFAULT_LOADER_CONFIG } from '../loader-config';
+	import { createPieLogger, isGlobalDebugEnabled } from '../pie/logger';
+	import { BundleType } from '../pie/types';
+	import type { ConfigEntity, Env, ImageHandler, SoundHandler } from '../types';
+	import PieItemPlayer from './PieItemPlayer.svelte';
+	import PiePreviewToggle from './PiePreviewToggle.svelte';
+
+	const logger = createPieLogger('pie-preview-layout', () => isGlobalDebugEnabled());
+
+	// Props using Svelte 5 runes
+	let {
+		mode = $bindable('author' as 'author' | 'preview'),
+		itemConfig,
+		passageConfig = null,
+		configuration = {} as Record<string, any>,
+		env = { mode: 'gather', role: 'student' } as Env,
+		session = [] as any[],
+		addCorrectResponse = false,
+		customClassname = '',
+		passageContainerClass = '',
+		containerClass = '',
+		// Legacy: authoring uses editor.js, preview uses player/client-player.
+		// For backwards-compat, keep `bundleType` but allow per-mode overrides.
+		bundleType = BundleType.player,
+		bundleTypeAuthor = BundleType.editor,
+		bundleTypePreview = BundleType.player,
+		loaderConfig = DEFAULT_LOADER_CONFIG as LoaderConfig,
+		// Asset handler callbacks
+		onInsertImage,
+		onDeleteImage,
+		onInsertSound,
+		onDeleteSound,
+		// Event callbacks
+		onLoadComplete,
+		onPlayerError,
+		onSessionChanged,
+		onModelUpdated
+	}: {
+		mode?: 'author' | 'preview';
+		itemConfig: ConfigEntity;
+		passageConfig?: ConfigEntity | null;
+		configuration?: Record<string, any>;
+		env?: Env;
+		session?: any[];
+		addCorrectResponse?: boolean;
+		customClassname?: string;
+		passageContainerClass?: string;
+		containerClass?: string;
+		bundleType?: BundleType;
+		bundleTypeAuthor?: BundleType;
+		bundleTypePreview?: BundleType;
+		loaderConfig?: LoaderConfig;
+		// Asset handlers
+		onInsertImage?: (handler: ImageHandler) => void;
+		onDeleteImage?: (src: string, done: (err?: Error) => void) => void;
+		onInsertSound?: (handler: SoundHandler) => void;
+		onDeleteSound?: (src: string, done: (err?: Error) => void) => void;
+		// Event callbacks
+		onLoadComplete?: (detail?: any) => void;
+		onPlayerError?: (detail?: any) => void;
+		onSessionChanged?: (detail?: any) => void;
+		onModelUpdated?: (detail?: any) => void;
+	} = $props();
+
+	// Track current mode state
+	let currentMode = $state(mode);
+
+	// Handle mode changes from toggle
+	function handleModeChange(newMode: 'author' | 'preview') {
+		logger.debug('[PiePreviewLayout] Mode changed:', newMode);
+		currentMode = newMode;
+		mode = newMode; // Update parent via bindable
+	}
+
+	// Derive player mode from current mode
+	const playerMode = $derived.by(() => {
+		return currentMode === 'preview' ? 'view' : 'author';
+	});
+
+	// Derive bundle type from current mode (author vs preview).
+	// Prefer per-mode overrides; fall back to `bundleType` for older callers.
+	const effectiveBundleType = $derived.by(() => {
+		if (currentMode === 'preview') return bundleTypePreview ?? bundleType;
+		return bundleTypeAuthor ?? BundleType.editor;
+	});
+
+	// Key to force re-mount when switching modes
+	const playerKey = $derived.by(() => {
+		return `${currentMode}-${Date.now()}`;
+	});
+</script>
+
+<div class="pie-preview-layout">
+	<PiePreviewToggle mode={currentMode} onModeChange={handleModeChange} />
+
+	<div class="preview-content" role="tabpanel" id="{currentMode}-panel" aria-labelledby="{currentMode}-tab">
+		{#key playerKey}
+			<PieItemPlayer
+				{itemConfig}
+				{passageConfig}
+				{env}
+				{session}
+				{addCorrectResponse}
+				{customClassname}
+				{passageContainerClass}
+				{containerClass}
+				bundleType={effectiveBundleType}
+				{loaderConfig}
+				mode={playerMode}
+				{configuration}
+				{onInsertImage}
+				{onDeleteImage}
+				{onInsertSound}
+				{onDeleteSound}
+				{onLoadComplete}
+				{onPlayerError}
+				{onSessionChanged}
+				{onModelUpdated}
+			/>
+		{/key}
+	</div>
+</div>
+
+<style>
+	.pie-preview-layout {
+		display: block;
+		width: 100%;
+	}
+
+	.preview-content {
+		display: block;
+		width: 100%;
+		padding: 1rem 0;
+	}
+</style>

package/src/components/PiePreviewToggle.svelte

@@ -0,0 +1,110 @@
+<!--
+  PiePreviewToggle - Toggle between authoring and preview modes
+
+  Simple tab-based interface for switching between author and preview views.
+  Emits mode changes via callback prop.
+-->
+<script lang="ts">
+	import { createPieLogger, isGlobalDebugEnabled } from '../pie/logger';
+
+	const logger = createPieLogger('pie-preview-toggle', () => isGlobalDebugEnabled());
+
+	// Props using Svelte 5 runes
+	let {
+		mode = 'author' as 'author' | 'preview',
+		onModeChange
+	}: {
+		mode?: 'author' | 'preview';
+		onModeChange?: (mode: 'author' | 'preview') => void;
+	} = $props();
+
+	// Handle mode change
+	function handleModeChange(newMode: 'author' | 'preview') {
+		logger.debug('[PiePreviewToggle] Mode changed to:', newMode);
+
+		if (onModeChange) {
+			onModeChange(newMode);
+		}
+
+		// Also dispatch DOM event for backward compatibility
+		const event = new CustomEvent('mode-changed', {
+			detail: { mode: newMode },
+			bubbles: true,
+			composed: true
+		});
+		dispatchEvent(event);
+	}
+</script>
+
+<div class="pie-preview-toggle">
+	<div class="toggle-tabs" role="tablist">
+		<button
+			type="button"
+			role="tab"
+			class="toggle-tab"
+			class:active={mode === 'author'}
+			aria-selected={mode === 'author'}
+			aria-controls="author-panel"
+			onclick={() => handleModeChange('author')}
+		>
+			Author
+		</button>
+		<button
+			type="button"
+			role="tab"
+			class="toggle-tab"
+			class:active={mode === 'preview'}
+			aria-selected={mode === 'preview'}
+			aria-controls="preview-panel"
+			onclick={() => handleModeChange('preview')}
+		>
+			Preview
+		</button>
+	</div>
+</div>
+
+<style>
+	.pie-preview-toggle {
+		display: block;
+		width: 100%;
+		margin-bottom: 1rem;
+	}
+
+	.toggle-tabs {
+		display: flex;
+		border-bottom: 2px solid #e0e0e0;
+		gap: 0.5rem;
+	}
+
+	.toggle-tab {
+		padding: 0.75rem 1.5rem;
+		background: transparent;
+		border: none;
+		border-bottom: 3px solid transparent;
+		cursor: pointer;
+		font-size: 1rem;
+		font-weight: 500;
+		color: #666;
+		transition: all 0.2s ease;
+		margin-bottom: -2px;
+	}
+
+	.toggle-tab:hover {
+		color: #333;
+		background: rgba(0, 0, 0, 0.05);
+	}
+
+	.toggle-tab:focus {
+		outline: 2px solid #1976d2;
+		outline-offset: 2px;
+	}
+
+	.toggle-tab.active {
+		color: #1976d2;
+		border-bottom-color: #1976d2;
+	}
+
+	.toggle-tab:active {
+		transform: translateY(1px);
+	}
+</style>

package/src/components/PieSpinner.svelte

@@ -0,0 +1,85 @@
+<script lang="ts">
+	export let fixed: boolean = false;
+</script>
+
+<div class="pie-loading {fixed ? 'fixed' : ''}"></div>
+
+<style>
+    .pie-loading {
+        position: absolute;
+        height: 100%;
+        width: 100%;
+        background-color: #fff;
+        bottom: 0;
+        left: 0;
+        right: 0;
+        top: 0;
+        z-index: 9999;
+        opacity: 0.4;
+    }
+
+    .pie-loading.fixed {
+        position: fixed;
+    }
+
+    .pie-loading:before {
+        content: "";
+        background-color: rgba(0, 0, 0, 0);
+        border: 5px solid rgba(63, 81, 181, 0.9);
+        opacity: 0.9;
+        border-right: 5px solid rgba(0, 0, 0, 0);
+        border-left: 5px solid rgba(0, 0, 0, 0);
+        border-radius: 50px;
+        box-shadow: 0 0 35px rgba(63, 81, 181, 0.9);
+        width: 50px;
+        height: 50px;
+        animation: spinPulse 1s infinite linear;
+        margin: -25px 0 0 -25px;
+        position: absolute;
+        top: 50%;
+        left: 50%;
+    }
+
+    .pie-loading:after {
+        content: "";
+        background-color: rgba(0, 0, 0, 0);
+        border: 5px solid rgba(63, 81, 181, 0.9);
+        opacity: 0.9;
+        border-left: 5px solid rgba(0, 0, 0, 0);
+        border-right: 5px solid rgba(0, 0, 0, 0);
+        border-radius: 50px;
+        box-shadow: 0 0 15px rgba(63, 81, 181, 0.9);
+        width: 30px;
+        height: 30px;
+        animation: spinoffPulse 1s infinite linear;
+        margin: -15px 0 0 -15px;
+        position: absolute;
+        top: 50%;
+        left: 50%;
+    }
+
+    @keyframes spinPulse {
+        0% {
+            transform: rotate(160deg);
+            opacity: 0;
+            box-shadow: 0 0 1px rgba(63, 81, 181, 0.9);
+        }
+        50% {
+            transform: rotate(145deg);
+            opacity: 1;
+        }
+        100% {
+            transform: rotate(-320deg);
+            opacity: 0;
+        }
+    }
+
+    @keyframes spinoffPulse {
+        0% {
+            transform: rotate(0deg);
+        }
+        100% {
+            transform: rotate(360deg);
+        }
+    }
+</style>

package/src/components/ToolSettingsButton.svelte

@@ -0,0 +1,31 @@
+<script lang="ts">
+	let {
+		buttonEl = null as HTMLButtonElement | null,
+		onClick,
+		ariaLabel = 'Settings',
+		active = false
+	}: {
+		buttonEl?: HTMLButtonElement | null;
+		onClick: () => void;
+		ariaLabel?: string;
+		active?: boolean;
+	} = $props();
+</script>
+
+<button
+	bind:this={buttonEl}
+	type="button"
+	class="btn btn-ghost btn-sm btn-circle"
+	aria-label={ariaLabel}
+	aria-pressed={active}
+	onclick={onClick}
+>
+	<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor" class="w-5 h-5">
+		<path
+			stroke-linecap="round"
+			stroke-linejoin="round"
+			d="M9.594 3.94c.09-.542.56-.94 1.11-.94h2.593c.55 0 1.02.398 1.11.94l.213 1.281c.063.374.313.686.645.87.074.04.147.083.22.127.324.196.72.257 1.075.124l1.217-.456a1.125 1.125 0 011.37.49l1.296 2.247a1.125 1.125 0 01-.26 1.431l-1.003.827c-.293.24-.438.613-.431.992a6.759 6.759 0 010 .255c-.007.378.138.75.43.99l1.005.828c.424.35.534.954.26 1.43l-1.298 2.247a1.125 1.125 0 01-1.369.491l-1.217-.456c-.355-.133-.75-.072-1.076.124a6.57 6.57 0 01-.22.128c-.331.183-.581.495-.644.869l-.213 1.28c-.09.543-.56.941-1.11.941h-2.594c-.55 0-1.02-.398-1.11-.94l-.213-1.281c-.062-.374-.312-.686-.644-.87a6.52 6.52 0 01-.22-.127c-.325-.196-.72-.257-1.076-.124l-1.217.456a1.125 1.125 0 01-1.369-.49l-1.297-2.247a1.125 1.125 0 01.26-1.431l1.004-.827c.292-.24.437-.613.43-.992a6.932 6.932 0 010-.255c.007-.378-.138-.75-.43-.99l-1.004-.828a1.125 1.125 0 01-.26-1.43l1.297-2.247a1.125 1.125 0 011.37-.491l1.216.456c.356.133.751.072 1.076-.124.072-.044.146-.087.22-.128.332-.183.582-.495.644-.869l.214-1.281z"
+		/>
+		<path stroke-linecap="round" stroke-linejoin="round" d="M15 12a3 3 0 11-6 0 3 3 0 016 0z" />
+	</svg>
+</button>

package/src/components/ToolSettingsPanel.svelte

@@ -0,0 +1,90 @@
+<script lang="ts">
+	import { onMount } from 'svelte';
+
+	let {
+		open,
+		title = 'Settings',
+		onClose,
+		anchorEl = null
+	}: {
+		open: boolean;
+		title?: string;
+		onClose: () => void;
+		anchorEl?: HTMLElement | null;
+	} = $props();
+
+	let panelEl = $state<HTMLDivElement | null>(null);
+	let panelPosition = $state<{ top: number; left?: number; right?: number } | null>(null);
+
+	function onKeyDown(e: KeyboardEvent) {
+		if (e.key === 'Escape') onClose();
+	}
+
+	$effect(() => {
+		if (open) queueMicrotask(() => panelEl?.focus?.());
+	});
+
+	// Calculate position based on anchor element
+	$effect(() => {
+		if (open && anchorEl) {
+			const anchorRect = anchorEl.getBoundingClientRect();
+			const panelWidth = 320; // w-80 = 20rem = 320px
+			const spacing = 8; // Gap from anchor
+
+			// Try to position to the right of anchor first
+			const rightPosition = anchorRect.right + spacing;
+			const hasSpaceOnRight = rightPosition + panelWidth <= window.innerWidth;
+
+			if (hasSpaceOnRight) {
+				// Position to the right of anchor
+				panelPosition = {
+					top: anchorRect.top,
+					left: rightPosition
+				};
+			} else {
+				// Position to the left of anchor
+				panelPosition = {
+					top: anchorRect.top,
+					right: window.innerWidth - anchorRect.left + spacing
+				};
+			}
+		} else {
+			panelPosition = null;
+		}
+	});
+
+	onMount(() => {
+		const onDocClick = (e: MouseEvent) => {
+			if (!open) return;
+			const target = e.target as Node | null;
+			if (!target) return;
+			if (panelEl?.contains(target)) return;
+			if (anchorEl?.contains(target)) return;
+			onClose();
+		};
+
+		document.addEventListener('mousedown', onDocClick);
+		return () => document.removeEventListener('mousedown', onDocClick);
+	});
+</script>
+
+{#if open}
+	<div class="fixed inset-0" aria-hidden="true" onmousedown={onClose} style="z-index: 4000;"></div>
+	<div
+		bind:this={panelEl}
+		class="tool-settings-panel fixed w-80 rounded-box bg-base-100 shadow p-3 text-base-content"
+		role="dialog"
+		aria-label={title}
+		tabindex="-1"
+		onkeydown={onKeyDown}
+		style="z-index: 4100; {panelPosition ? `top: ${panelPosition.top}px; ${panelPosition.left !== undefined ? `left: ${panelPosition.left}px;` : `right: ${panelPosition.right}px;`}` : 'top: 4rem; right: 1rem;'}"
+	>
+		<div class="flex items-center justify-between gap-2 mb-2">
+			<h2 class="font-semibold text-sm">{title}</h2>
+			<button type="button" class="btn btn-ghost btn-xs" onclick={onClose} aria-label="Close settings">Close</button>
+		</div>
+		<div class="text-sm">
+			<slot />
+		</div>
+	</div>
+{/if}

package/src/components/index.ts

@@ -0,0 +1,6 @@
+export { default as PieItemPlayer } from "./PieItemPlayer.svelte";
+export { default as PiePreviewLayout } from "./PiePreviewLayout.svelte";
+export { default as PiePreviewToggle } from "./PiePreviewToggle.svelte";
+export { default as PieSpinner } from "./PieSpinner.svelte";
+export { default as ToolSettingsButton } from "./ToolSettingsButton.svelte";
+export { default as ToolSettingsPanel } from "./ToolSettingsPanel.svelte";

package/src/i18n/README.md

@@ -0,0 +1,223 @@
+# PIE Players i18n System
+
+Comprehensive internationalization system with support for English, Spanish, Chinese, and Arabic (RTL).
+
+## Usage Patterns
+
+### Pattern 1: Standalone Components (Recommended for Individual Components)
+
+Use `useI18nStandalone()` when building standalone components (tools, players) that don't require the full toolkit architecture.
+
+```svelte
+<script lang="ts">
+  import { useI18nStandalone } from '@pie-framework/pie-players-shared/i18n';
+
+  // Simple setup - no service injection needed
+  const i18n = useI18nStandalone({
+    locale: 'en',  // Optional: defaults to browser language
+    debug: false   // Optional: enable debug logging
+  });
+</script>
+
+<div dir={i18n.direction}>
+  <button>{i18n.t('common.save')}</button>
+  <span>{i18n.tn('assessment.questions', 10)}</span>
+
+  <!-- Change locale dynamically -->
+  <button onclick={() => i18n.setLocale('es')}>Español</button>
+  <button onclick={() => i18n.setLocale('ar')}>العربية</button>
+</div>
+```
+
+**Benefits:**
+- ✅ No service architecture required
+- ✅ Self-contained - manages its own I18nService instance
+- ✅ Full feature support (hybrid loading, RTL, pluralization)
+- ✅ Perfect for reusable components and tools
+
+### Pattern 2: Integrated with Assessment Toolkit
+
+Use `useI18n()` when working within the full assessment toolkit where centralized locale management is needed.
+
+```svelte
+<script lang="ts">
+  import { useI18n } from '@pie-framework/pie-players-shared/i18n';
+
+  // Receive service from parent/context
+  let { player } = $props();
+  const i18n = useI18n(() => player.getI18nService());
+</script>
+
+<div dir={i18n.direction}>
+  <button>{i18n.t('common.save')}</button>
+  <span>{i18n.tn('assessment.questions', totalQuestions)}</span>
+</div>
+```
+
+**Benefits:**
+- ✅ Centralized locale management across entire application
+- ✅ Locale preferences from student profile/IEP
+- ✅ Shared service instance - locale changes sync everywhere
+- ✅ Integration with accommodation system
+
+### Pattern 3: Direct Service Usage (Advanced)
+
+For non-Svelte contexts or advanced use cases:
+
+```typescript
+import { SimpleI18n, BUNDLED_TRANSLATIONS, loadTranslations } from '@pie-framework/pie-players-shared/i18n';
+
+const i18n = new SimpleI18n({
+  locale: 'en',
+  bundledTranslations: BUNDLED_TRANSLATIONS,
+  loadTranslations,
+});
+
+await i18n.initialize({ locale: 'es' });
+
+console.log(i18n.t('common.save')); // "Guardar"
+console.log(i18n.getDirection()); // "ltr"
+
+// Subscribe to changes
+const unsubscribe = i18n.subscribe(() => {
+  console.log('Locale changed to:', i18n.getLocale());
+});
+```
+
+## Translation Functions
+
+### `t(key, params?)` - Basic Translation
+
+```typescript
+i18n.t('common.save')  // "Save"
+i18n.t('common.cancel') // "Cancel"
+
+// With interpolation
+i18n.t('assessment.question_of', { current: 5, total: 20 })
+// "Question 5 of 20"
+```
+
+### `tn(key, count, params?)` - Pluralization
+
+```typescript
+i18n.tn('assessment.questions', 1)  // "1 Question"
+i18n.tn('assessment.questions', 10) // "10 Questions"
+
+// With additional params
+i18n.tn('common.item', count, { type: 'folder' })
+```
+
+## Available Translations
+
+### Common Namespace (`common.*`)
+- Buttons: `save`, `cancel`, `close`, `back`, `next`, `previous`, `submit`
+- States: `loading`, `error`, `retry`
+- Common words: `question`, `item`, `character` (all with pluralization)
+
+### Assessment Namespace (`assessment.*`)
+- `title` - Assessment title
+- `questions` - Question count (plural)
+- `question_of` - "Question X of Y"
+- `student_name` - Student name label
+- `fullscreen`, `exit_fullscreen` - Fullscreen controls
+
+### Accommodation Namespace (`accommodation.*`)
+- `audio`, `audio_aria` - Audio/TTS controls
+- `contrast`, `contrast_aria` - Contrast controls
+
+### Navigation Namespace (`navigation.*`)
+- `back`, `next`, `previous`, `submit` - Navigation buttons
+- `navigate_to` - "Navigate to question X"
+- `section` - Section label
+
+### Tool Namespace (`tool.*`)
+- Tool names: `calculator`, `graph`, `periodic_table`, etc.
+- TTS controls: `tts.speak`, `tts.pause`, `tts.stop`, `tts.rate`
+- Calculator types: `calculator.basic`, `calculator.scientific`, `calculator.graphing`
+- Color schemes: `color_scheme.default`, `color_scheme.high_contrast`, `color_scheme.dark`
+
+## Supported Languages
+
+- **English (en)** - Bundled (~15KB)
+- **Spanish (es)** - Lazy-loaded (~12KB)
+- **Chinese (zh)** - Lazy-loaded (~12KB)
+- **Arabic (ar)** - Lazy-loaded (~12KB) with RTL support
+
+## RTL Support
+
+Arabic automatically switches to RTL mode:
+
+```svelte
+<script>
+  const i18n = useI18nStandalone({ locale: 'ar' });
+</script>
+
+<!-- direction automatically set to "rtl" -->
+<div dir={i18n.direction}>
+  {i18n.t('assessment.title')} <!-- التقييم -->
+</div>
+```
+
+## API Reference
+
+### Composable Return Value
+
+```typescript
+{
+  // Reactive getters
+  locale: string;           // Current locale (e.g., 'en', 'es')
+  direction: 'ltr' | 'rtl'; // Text direction
+  isLoading: boolean;       // Locale loading state
+  availableLocales: string[]; // List of loaded locales
+
+  // Methods
+  t(key: string, params?: Record<string, any>): string;
+  tn(key: string, count: number, params?: Record<string, any>): string;
+  setLocale(locale: string): Promise<void>;
+  isLocaleLoaded(locale: string): boolean;
+  hasKey(key: string): boolean;
+}
+```
+
+## When to Use Each Pattern
+
+| Scenario | Use Pattern |
+|----------|-------------|
+| Standalone tool component | `useI18nStandalone()` |
+| Reusable UI component | `useI18nStandalone()` |
+| Individual player | `useI18nStandalone()` |
+| Full assessment application | `useI18n()` |
+| Student profile integration | `useI18n()` |
+| IEP/504 locale requirements | `useI18n()` |
+| Non-Svelte code | `SimpleI18n` class |
+
+## Performance
+
+- **Initial load**: ~15KB (English bundled)
+- **Lazy loading**: ~12KB per additional language (cached)
+- **Hybrid strategy**: Only loads languages when needed
+- **Service reuse**: `useI18nStandalone()` creates one service per component
+
+## Adding New Translations
+
+Translation files are located at:
+```
+packages/players-shared/src/i18n/translations/
+├── en/  (common.json, toolkit.json, tools.json)
+├── es/  (common.json, toolkit.json, tools.json)
+├── zh/  (common.json, toolkit.json, tools.json)
+└── ar/  (common.json, toolkit.json, tools.json)
+```
+
+Format:
+```json
+{
+  "common": {
+    "save": "Save",
+    "question": {
+      "one": "Question",
+      "other": "Questions"
+    }
+  }
+}
+```