@pie-players/pie-tool-magnifier 0.1.8 → 1.0.0-beta.2

package/README.md

@@ -1,135 +1,112 @@
-# PIE Magnifier Tool
+# @pie-players/pie-tool-magnifier
 
-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.
+Magnifying lens tool for PIE assessment players.
 
-## 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
+## Overview
 
-- **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)
+A movable, resizable lens that shows the content under it enlarged. The lens is a
+window with a bar on top: zoom out, the current zoom, zoom in, and close. Its
+viewport shows a scaled copy of the page around the point beneath the lens, so
+moving the lens moves what it magnifies. The shown point travels the lens's block
+in step with the lens, so at the block's edges the view reaches the edge content
+the lens stops short of.
 
-### Key Architectural Improvements
+The tool serves the AfA PNP 3.0 `magnification` support. Its tool id is that term,
+`magnification`.
 
-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
+## Custom Element
 
-## Usage
+Tag: `pie-tool-magnifier`
 
-### As a Custom Element
+| Attribute | Type | Default | Description |
+|---|---|---|---|
+| `visible` | `boolean` | `false` | Controls visibility |
+| `tool-id` | `string` | `'magnification'` | Identifier used by the ToolCoordinator |
+| `zoom` | `number` | `2` | Starting magnification, 2 meaning twice the size. Clamped to 1.25–8; a value of 1 or less, or none, is the default |
 
-```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();
+## Features
 
-// The tool will auto-register when visible=true
+- Zoom steps of 1.5×, 2×, 2.5×, 3×, 4×, 5×, 6× and 8× from the bar's buttons or
+  the keyboard
+- Drag the bar or the viewport to move the lens; drag the corner grip to resize it
+  around its centre
+- Full keyboard support:
+  - On the lens: arrow keys to move, `+`/`-` to zoom
+  - On the resize grip: arrow keys change the width and height
+  - Anywhere on the page: `Escape` closes the lens, unless something else there
+    handles the key. Pressed on the lens it also returns focus to where it was
+    before the lens opened
+- Keyboard focus on the page beneath the lens shows as a ring in the magnified view
+- Tap controls beside the focused lens move it and change its width and height
+  without a drag (WCAG 2.5.7), and every control meets the 24×24 minimum target
+  size (WCAG 2.5.8). On a narrow pane they wrap onto a second row
+- Screen reader announcements for zoom, size and position changes
+- Stays inside its containing block, and opens over the part of it on screen
+- Connects to `AssessmentToolkitRuntimeContext` for ToolCoordinator integration
+
+## Profile and policy
+
+A personal needs profile grants the tool by listing `magnification` in `supports`.
+The starting zoom is the `zoom` tool parameter, which the registration in
+`@pie-players/pie-default-tool-loaders` reads through the toolbar and sets as the
+`zoom` attribute. `createPersonalNeedsProfileFromAfa` maps an AfA record's
+`magnification` `zoom-amount` to it, taking the `text` amount when the record sets
+text and non-text apart:
+
+```ts
+createPersonalNeedsProfileFromAfa({ magnification: { "all-content": { "zoom-amount": 2.5 } } });
+// { supports: ["magnification"], toolParameters: { magnification: { zoom: 2.5 } } }
 ```
 
-## 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)
+The learner changes the zoom from there; a new host value replaces theirs.
+
+The packaged registration places the tool at section level by default and supports
+section, passage, rubric and item placement. Placement puts it on a toolbar; a
+profile's `prohibitedSupports`, a district block or a test-administration override
+withdraws it. It is not universal: magnification is a granted accommodation, so
+`createUniversalPersonalNeedsProfile()` leaves it out.
+
+## How the lens draws
+
+CSS cannot paint one part of a document inside another, so the lens shows a copy.
+The live document is serialized without scripts or event-handler attributes into a
+sandboxed `srcdoc` iframe: open shadow roots become declarative shadow roots, every
+style sheet is written out from its CSSOM, and form state, scroll offsets, canvas
+pixels and video frames are copied across after the copy loads. The lens scales and
+offsets the iframe with a transform, which follows its position, size, the zoom and
+page scrolling every frame.
+
+A mutation observer marks the copy stale, and it is re-rendered at most every
+200 ms, or every four times the main-thread time the last render took when that is
+longer, so copying a large page keeps to about a quarter of the main thread. Two
+iframes alternate, so the new copy paints in the hidden one and swaps in when it has
+loaded. Every lens is left out of the copy.
+
+Highlights painted through the CSS Custom Highlight API, text-to-speech word and
+sentence highlighting and annotation-toolbar highlights among them, are mapped onto
+the copy's nodes and registered in its frame under the same names, where the copy's
+own `::highlight()` rules paint them. They follow the page every frame, without
+waiting for a re-render.
+
+The copy is inert: it takes no input and runs no script, so the lens is a viewing
+aid and the learner answers on the page beneath it.
+
+## Limitations
+
+- Closed shadow roots, cross-origin iframes and WebGL canvases without a preserved
+  drawing buffer appear empty.
+- A highlight over markup the HTML parser restructures, such as a block element a
+  script placed inside a `<p>`, does not show.
+- Top-layer content is not carried: a modal dialog shows as a non-modal one in
+  place, and an open popover does not show.
+- A custom element that renders its content only from script, with no open shadow
+  root or light-DOM children, appears as it does before it upgrades.
+- Changes to the page reach the lens a render or two late: well under a second on a
+  typical section, and up to about five seconds on a page of 40,000 elements, whose
+  copy takes over a second to render.
+
+## Theming
+
+The lens reads canonical theme tokens and defines none of its own: `--pie-primary`
+for the border, `--pie-background` and `--pie-text` for the lens, and
+`--pie-secondary-background` and `--pie-border` for the bar.

package/custom-elements.json

@@ -0,0 +1,83 @@
+{
+	"schemaVersion": "2.1.0",
+	"modules": [
+		{
+			"kind": "javascript-module",
+			"path": "dist/tool-magnifier.js",
+			"declarations": [
+				{
+					"kind": "class",
+					"description": "Magnifying lens: a movable, resizable window that shows the content under it enlarged, with controls on its bar to change the zoom and close. The host shows it with `visible` and sets the starting magnification with `zoom` (the AfA PNP `magnification` amount; 2 when absent). Inside a toolkit runtime context it registers `tool-id` with the tool coordinator on the tool layer, and the close control hides it there. Arrow keys move it, `+` and `-` change the zoom, and Escape closes it, wherever on the page it is pressed.",
+					"name": "ToolMagnifier",
+					"tagName": "pie-tool-magnifier",
+					"customElement": true,
+					"members": [
+						{
+							"kind": "field",
+							"name": "visible",
+							"type": {
+								"text": "boolean"
+							},
+							"default": "false",
+							"attribute": "visible"
+						},
+						{
+							"kind": "field",
+							"name": "toolId",
+							"type": {
+								"text": "string"
+							},
+							"default": "'magnification'",
+							"attribute": "tool-id"
+						},
+						{
+							"kind": "field",
+							"name": "zoom",
+							"type": {
+								"text": "number"
+							},
+							"attribute": "zoom"
+						}
+					],
+					"attributes": [
+						{
+							"name": "visible",
+							"type": {
+								"text": "boolean"
+							},
+							"default": "false",
+							"fieldName": "visible"
+						},
+						{
+							"name": "tool-id",
+							"type": {
+								"text": "string"
+							},
+							"default": "'magnification'",
+							"fieldName": "toolId"
+						},
+						{
+							"name": "zoom",
+							"type": {
+								"text": "number"
+							},
+							"fieldName": "zoom"
+						}
+					],
+					"x-pie": {
+						"shadow": "open"
+					}
+				}
+			],
+			"exports": [
+				{
+					"kind": "custom-element-definition",
+					"name": "pie-tool-magnifier",
+					"declaration": {
+						"name": "ToolMagnifier"
+					}
+				}
+			]
+		}
+	]
+}

package/dist/index.d.ts

@@ -1,8 +1 @@
-/**
- * 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.
- */
-export {};
-//# sourceMappingURL=index.d.ts.map
+export {}