@pie-players/pie-tool-magnifier 0.1.1

package/Magnifier.svelte

@@ -0,0 +1,340 @@
+<!-- Magnifier.svelte - Modern Svelte 5 implementation of HTML magnifier -->
+<script lang="ts">
+	import { onMount, untrack } from 'svelte';
+
+	interface MagnifierProps {
+		zoom?: number;
+		width?: number;
+		height?: number;
+		shape?: 'square' | 'circle';
+		visible?: boolean;
+		onPrepareContent?: (clonedContent: HTMLElement) => void;
+		onContentUpdated?: (bodyElement: HTMLElement) => void;
+	}
+
+	let {
+		zoom = 2,
+		width = 420,
+		height = 280,
+		shape = 'square',
+		visible = $bindable(false),
+		onPrepareContent,
+		onContentUpdated
+	}: MagnifierProps = $props();
+
+	// Reactive state
+	let magnifierEl = $state<HTMLDivElement | null>(null);
+	let contentEl = $state<HTMLDivElement | null>(null);
+	let clonedBody = $state<HTMLElement | null>(null);
+	let position = $state({ x: 200, y: 200 });
+	let isDragging = $state(false);
+	let dragOffset = $state({ x: 0, y: 0 });
+
+	// MutationObserver to sync content changes
+	let observer: MutationObserver | null = null;
+	let syncTimeoutHandle: number | null = null;
+
+	// Derived styles
+	let magnifierStyle = $derived(`
+		left: ${position.x}px;
+		top: ${position.y}px;
+		width: ${width}px;
+		height: ${height}px;
+		${shape === 'circle' ? 'border-radius: 50%;' : ''}
+		display: ${visible ? 'block' : 'none'};
+	`);
+
+	let contentStyle = $derived(`
+		transform: scale(${zoom});
+		left: ${-position.x * zoom - window.scrollX * zoom}px;
+		top: ${-position.y * zoom - window.scrollY * zoom}px;
+		width: ${document.body.scrollWidth}px;
+		height: ${document.body.scrollHeight}px;
+	`);
+
+	function cloneDocumentBody() {
+		const bodyOriginal = document.body;
+		const bodyCopy = bodyOriginal.cloneNode(true) as HTMLElement;
+
+		// Copy background color
+		const bgColor = getComputedStyle(bodyOriginal).backgroundColor;
+		if (bgColor && magnifierEl) {
+			magnifierEl.style.backgroundColor = bgColor;
+		}
+
+		// Reset styles
+		bodyCopy.style.cursor = 'auto';
+		bodyCopy.style.paddingTop = '0px';
+		bodyCopy.setAttribute('unselectable', 'on');
+
+		// Copy canvas contents
+		const canvasOriginal = bodyOriginal.querySelectorAll('canvas');
+		const canvasCopy = bodyCopy.querySelectorAll('canvas');
+		if (canvasOriginal.length > 0 && canvasOriginal.length === canvasCopy.length) {
+			for (let i = 0; i < canvasOriginal.length; i++) {
+				const ctx = canvasCopy[i].getContext('2d');
+				if (ctx) {
+					try {
+						ctx.drawImage(canvasOriginal[i], 0, 0);
+					} catch (error) {
+						// Silent fail - likely CORS issue
+					}
+				}
+			}
+		}
+
+		// Remove elements that shouldn't be magnified
+		const elementsToRemove = [
+			...bodyCopy.querySelectorAll('script'),
+			...bodyCopy.querySelectorAll('audio'),
+			...bodyCopy.querySelectorAll('video'),
+			...bodyCopy.querySelectorAll('.magnifier'),
+			...bodyCopy.querySelectorAll('.magnifier-clone-ignore'),
+			...bodyCopy.querySelectorAll('[data-magnifier-ignore]')
+		];
+		elementsToRemove.forEach(el => el.remove());
+
+		// Custom content preparation
+		if (onPrepareContent) {
+			onPrepareContent(bodyCopy);
+		}
+
+		return bodyCopy;
+	}
+
+	function updateContent() {
+		if (!visible || !contentEl) return;
+
+		// Clear existing content
+		contentEl.innerHTML = '';
+
+		// Clone and prepare content
+		clonedBody = cloneDocumentBody();
+		contentEl.appendChild(clonedBody);
+
+		// Sync scroll positions
+		syncScrollPositions();
+
+		// Notify content update
+		if (onContentUpdated && clonedBody) {
+			const bodyInClone = clonedBody.querySelector('body');
+			if (bodyInClone) {
+				onContentUpdated(bodyInClone as HTMLElement);
+			}
+		}
+	}
+
+	function syncScrollPositions() {
+		if (!clonedBody) return;
+
+		// Find all scrolled divs in the original document
+		const scrolledDivs = Array.from(document.querySelectorAll('div')).filter(
+			div => div.scrollTop > 0 && !magnifierEl?.contains(div)
+		);
+
+		// Sync scroll positions to cloned elements
+		scrolledDivs.forEach(div => {
+			const selectors: string[] = [];
+
+			if (div.id) {
+				selectors.push('#' + div.id);
+			}
+			if (div.className) {
+				selectors.push('.' + div.className.split(' ').join('.'));
+			}
+
+			selectors.forEach(selector => {
+				const targets = clonedBody!.querySelectorAll(selector);
+				if (targets.length === 1) {
+					const target = targets[0] as HTMLElement;
+					target.scrollTop = div.scrollTop;
+					target.scrollLeft = div.scrollLeft;
+				}
+			});
+		});
+	}
+
+	function queueContentUpdate() {
+		if (syncTimeoutHandle !== null) {
+			clearTimeout(syncTimeoutHandle);
+		}
+		syncTimeoutHandle = window.setTimeout(() => {
+			updateContent();
+		}, 100);
+	}
+
+	function startObserving() {
+		if (observer) return;
+
+		observer = new MutationObserver((mutations) => {
+			for (const mutation of mutations) {
+				// Skip mutations within the magnifier itself
+				if (magnifierEl && magnifierEl.contains(mutation.target as Node)) {
+					continue;
+				}
+				queueContentUpdate();
+				break;
+			}
+		});
+
+		observer.observe(document.body, {
+			childList: true,
+			subtree: true,
+			attributes: true,
+			attributeFilter: ['class', 'width', 'height', 'style'],
+			attributeOldValue: true
+		});
+	}
+
+	function stopObserving() {
+		if (observer) {
+			observer.disconnect();
+			observer = null;
+		}
+		if (syncTimeoutHandle !== null) {
+			clearTimeout(syncTimeoutHandle);
+			syncTimeoutHandle = null;
+		}
+	}
+
+	// Drag handlers
+	function handlePointerDown(e: PointerEvent) {
+		// Don't start drag on interactive elements or their children
+		const target = e.target as HTMLElement;
+
+		// Check if the target or any parent is an interactive element
+		const interactiveTags = ['INPUT', 'TEXTAREA', 'SELECT', 'BUTTON', 'A'];
+		let element: HTMLElement | null = target;
+		while (element && element !== magnifierEl) {
+			if (interactiveTags.includes(element.tagName.toUpperCase())) {
+				return;
+			}
+			element = element.parentElement;
+		}
+
+		isDragging = true;
+		dragOffset = {
+			x: e.clientX - position.x,
+			y: e.clientY - position.y
+		};
+
+		if (magnifierEl) {
+			magnifierEl.setPointerCapture(e.pointerId);
+		}
+	}
+
+	function handlePointerMove(e: PointerEvent) {
+		if (!isDragging) return;
+
+		position = {
+			x: e.clientX - dragOffset.x,
+			y: e.clientY - dragOffset.y
+		};
+	}
+
+	function handlePointerUp(e: PointerEvent) {
+		if (isDragging && magnifierEl) {
+			magnifierEl.releasePointerCapture(e.pointerId);
+		}
+		isDragging = false;
+	}
+
+	// Scroll sync handler
+	function handleScroll(e: Event) {
+		if (!visible) return;
+
+		const target = e.target as HTMLElement;
+		if (magnifierEl?.contains(target)) return;
+
+		// Queue a content update to sync scroll positions
+		queueContentUpdate();
+	}
+
+	// Update content when becoming visible
+	$effect(() => {
+		if (visible) {
+			untrack(() => {
+				updateContent();
+				startObserving();
+			});
+		} else {
+			untrack(() => {
+				stopObserving();
+			});
+		}
+	});
+
+	// Update content when zoom changes
+	$effect(() => {
+		// Track zoom dependency
+		zoom;
+		if (visible) {
+			untrack(() => {
+				updateContent();
+			});
+		}
+	});
+
+	// Lifecycle
+	onMount(() => {
+		// Listen for scroll events
+		window.addEventListener('scroll', handleScroll, true);
+		window.addEventListener('resize', queueContentUpdate);
+
+		return () => {
+			stopObserving();
+			window.removeEventListener('scroll', handleScroll, true);
+			window.removeEventListener('resize', queueContentUpdate);
+		};
+	});
+</script>
+
+<div
+	bind:this={magnifierEl}
+	class="magnifier"
+	style={magnifierStyle}
+	onpointerdown={handlePointerDown}
+	onpointermove={handlePointerMove}
+	onpointerup={handlePointerUp}
+	role="region"
+	aria-label="Content magnifier"
+>
+	<div bind:this={contentEl} class="magnifier-content" style={contentStyle}></div>
+	<div class="magnifier-glass"></div>
+	<slot />
+</div>
+
+<style>
+	.magnifier {
+		position: fixed;
+		overflow: hidden;
+		background-color: white;
+		border: 1px solid #555;
+		border-radius: 4px;
+		z-index: 10000;
+		cursor: move;
+		touch-action: none;
+	}
+
+	.magnifier-content {
+		position: absolute;
+		top: 0;
+		left: 0;
+		overflow: visible;
+		display: block;
+		transform-origin: left top;
+		user-select: none;
+		pointer-events: none;
+	}
+
+	.magnifier-glass {
+		position: absolute;
+		top: 0;
+		left: 0;
+		width: 100%;
+		height: 100%;
+		opacity: 0;
+		background-color: transparent;
+		pointer-events: all;
+	}
+</style>

package/README.md

@@ -0,0 +1,135 @@
+# PIE Magnifier Tool
+
+A draggable magnification tool that allows students to zoom in on any content on the assessment page. This tool is an accessibility accommodation for students with visual impairments.
+
+## Features
+
+- **Multiple Zoom Levels**: 1.5x, 2x, and 3x magnification
+- **Draggable**: Can be moved anywhere on the screen using mouse or keyboard
+- **Content Cloning**: Creates a live clone of page content with accurate scroll positions
+- **Keyboard Accessible**: Full keyboard navigation support
+- **Zero DOM Mutation**: Does not modify the original content
+
+## Architecture
+
+This tool follows PIE's custom element (Web Component) architecture:
+
+- Built with Svelte 5
+- Registered as a custom element `<pie-tool-magnifier>`
+- Integrates with PIE's ToolCoordinator for z-index management
+- Uses Moveable.js for drag functionality
+
+## Comparison to Production Implementations
+
+### Similarities
+
+- **Visual Design**: Same zoom levels (1.5x, 2x, 3x), button layout, and frame dimensions
+- **Core Functionality**: DOM cloning, scroll position preservation, mouse tracking
+- **UX Patterns**: Frozen view on mouse leave, continuous update on drag
+
+### Differences
+
+- **Framework**: Svelte 5 (with runes) instead of Vue 3 (Composition API)
+- **Architecture**: Web Component (custom element) instead of Vue SFC
+- **Dependencies**: Uses Moveable.js directly instead of VueUse composables
+- **Coordination**: Integrates with PIE's ToolCoordinator for z-index management
+- **Styling**: Uses PIE CSS variables for consistency
+- **DOM Mutation**: Zero mutation approach (clones only, never modifies original)
+
+### Key Architectural Improvements
+
+1. **Web Component Standard**: Framework-agnostic, can be used in any context
+2. **Modern Svelte 5**: Uses runes (`$state`, `$derived`, `$effect`) for reactive state
+3. **Cleaner Separation**: Tool coordination is handled by external coordinator, not internal store
+4. **Accessibility First**: ARIA labels, keyboard navigation, screen reader announcements
+
+## Usage
+
+### As a Custom Element
+
+```html
+<pie-tool-magnifier
+  visible="true"
+  tool-id="magnifier"
+  magnify-root-selector="body"
+></pie-tool-magnifier>
+```
+
+### With Coordinator
+
+```typescript
+import { ToolMagnifier } from '@pie-api-aws/pieoneer-tool-magnifier';
+import { ToolCoordinator } from '$lib/assessment-toolkit';
+
+const coordinator = new ToolCoordinator();
+
+// The tool will auto-register when visible=true
+```
+
+## Props
+
+- `visible` (Boolean): Show/hide the tool
+- `toolId` (String): Unique identifier for this tool instance (default: 'magnifier')
+- `coordinator` (Object): ToolCoordinator instance for z-index management
+- `magnifyRootSelector` (String): CSS selector for root element to magnify (default: 'body')
+
+## Keyboard Navigation
+
+- **Arrow Keys**: Move the magnifier frame (10px steps)
+- **1 / 2 / 3**: Set zoom level to 1.5x / 2x / 3x
+- **+ / =**: Cycle to next zoom level
+- **-**: Cycle to previous zoom level
+
+## Accessibility Features
+
+- Full keyboard navigation
+- ARIA labels and roles
+- Screen reader announcements for state changes
+- Focus visible indicators
+- High contrast focus rings
+
+## Implementation Notes
+
+### Content Cloning
+
+The tool creates a deep clone of the content specified by `magnifyRootSelector` and:
+
+1. Preserves scroll positions of all scrollable elements
+2. Removes elements with `.magnifier-clone-ignore` class or `[data-magnifier-ignore]` attribute
+3. Applies scaling and positioning transforms
+4. Updates on scroll events (debounced)
+
+### Performance
+
+- Uses `requestAnimationFrame` for smooth updates
+- Debounces scroll event handlers (100ms)
+- Cleans up all listeners and RAF loops on unmount
+- Only updates during drag or mouse-inside states
+
+### Z-Index Management
+
+The tool uses PIE's ZIndexLayer system:
+
+- Tool frame: `ZIndexLayer.MODAL` (2002)
+- Moveable controls: `ZIndexLayer.CONTROL` (2003)
+
+### Preventing Self-Magnification
+
+The tool adds `.magnifier-clone-ignore` class and `[data-magnifier-ignore]` attribute to its own frame to prevent recursive magnification.
+
+## Browser Compatibility
+
+- Chrome/Edge 90+
+- Firefox 90+
+- Safari 14+
+
+Requires:
+- Custom Elements (Web Components)
+- CSS Transform
+- RequestAnimationFrame
+- DOMMatrix
+
+## Related Documentation
+
+- [PIE Tools Architecture](../../docs/tools-high-level-architecture.md)
+- [ToolCoordinator](../../tools/tool-coordinator.ts)

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * pie-tool-magnifier - PIE Assessment Tool
+ *
+ * This package exports a web component built from Svelte.
+ * Import the built version for CDN usage, or the .svelte source for Svelte projects.
+ */
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}