@pie-players/pie-players-shared 0.3.73 → 0.3.75

package/dist/ui/overlay-placement.js

@@ -0,0 +1,222 @@
+/**
+ * Placement of a tool overlay the learner moves and turns: the ruler and the
+ * protractor. One controller holds where the tool sits and is the only writer of
+ * its `style.transform`, so a drag, an arrow key and a tap control always agree
+ * about where the tool is.
+ */
+import { clampOffsetOverlappingBlock, resolveContainingBlockRect, rotatedExtent, rotationCentreShift, uprightDockCentre, } from "./overlay-containment.js";
+import { createPointerDragController } from "./pointer-drag.js";
+import { createPointerGesture } from "./pointer-gesture.js";
+import { createPointerRotateController } from "./pointer-rotate.js";
+/** Pixels an arrow key or move button shifts the tool. */
+export const OVERLAY_PLACEMENT_MOVE_STEP = 10;
+/** Degrees Shift+arrow turns the tool. */
+export const OVERLAY_PLACEMENT_ROTATE_STEP = 5;
+/** Degrees Page Up/Down turns the tool. */
+export const OVERLAY_PLACEMENT_FINE_ROTATE_STEP = 1;
+/** Each move, with its tap control's glyph and label and its announcement. */
+export const OVERLAY_PLACEMENT_NUDGES = {
+    left: {
+        dx: -1,
+        dy: 0,
+        glyph: "←",
+        labelKey: "toolkit.window.moveLeftA11y",
+        announceKey: "toolkit.announce.movedLeft",
+    },
+    up: {
+        dx: 0,
+        dy: -1,
+        glyph: "↑",
+        labelKey: "toolkit.window.moveUpA11y",
+        announceKey: "toolkit.announce.movedUp",
+    },
+    down: {
+        dx: 0,
+        dy: 1,
+        glyph: "↓",
+        labelKey: "toolkit.window.moveDownA11y",
+        announceKey: "toolkit.announce.movedDown",
+    },
+    right: {
+        dx: 1,
+        dy: 0,
+        glyph: "→",
+        labelKey: "toolkit.window.moveRightA11y",
+        announceKey: "toolkit.announce.movedRight",
+    },
+};
+/** The tap controls' rotations, the keyboard's two steps each way. */
+export const OVERLAY_PLACEMENT_ROTATIONS = [
+    -OVERLAY_PLACEMENT_ROTATE_STEP,
+    -OVERLAY_PLACEMENT_FINE_ROTATE_STEP,
+    OVERLAY_PLACEMENT_FINE_ROTATE_STEP,
+    OVERLAY_PLACEMENT_ROTATE_STEP,
+];
+const ARROW_KEYS = {
+    ArrowLeft: "left",
+    ArrowUp: "up",
+    ArrowDown: "down",
+    ArrowRight: "right",
+};
+/** Pixels of the tool kept inside its containing block on each axis. */
+const MIN_VISIBLE = 100;
+/** Space between the tool's bottom edge and its tap controls. */
+const CONTROLS_GAP = 8;
+export function createOverlayPlacement(options) {
+    let placement = { x: 0, y: 0, rotation: 0 };
+    const sizeOf = (element) => ({
+        width: element.offsetWidth,
+        height: element.offsetHeight,
+    });
+    function dockControls(element) {
+        const controls = options.getControls();
+        if (!controls)
+            return;
+        // Counter-rotated, so each arrow points the way its button moves the tool.
+        const centre = uprightDockCentre(sizeOf(element), sizeOf(controls), placement.rotation, CONTROLS_GAP);
+        controls.style.transform = `translate(${centre.x}px, ${centre.y}px) translate(-50%, -50%) rotate(${-placement.rotation}deg)`;
+    }
+    function apply(next) {
+        const element = options.getElement();
+        if (!element)
+            return;
+        const block = resolveContainingBlockRect(element);
+        const size = sizeOf(element);
+        // A tool turning off its centre has its turned extent centred off its
+        // translate offset by this shift; the clamp bounds that centre.
+        const shift = options.pivot
+            ? rotationCentreShift(size, options.pivot(size), next.rotation)
+            : { x: 0, y: 0 };
+        const centre = { x: next.x + shift.x, y: next.y + shift.y };
+        const bounded = block
+            ? clampOffsetOverlappingBlock(centre, rotatedExtent(size, next.rotation), block, MIN_VISIBLE)
+            : centre;
+        placement = {
+            x: bounded.x - shift.x,
+            y: bounded.y - shift.y,
+            rotation: next.rotation,
+        };
+        element.style.transform = `translate(-50%, -50%) translate(${placement.x}px, ${placement.y}px) rotate(${placement.rotation}deg)`;
+        dockControls(element);
+    }
+    const dragController = createPointerDragController({
+        getPosition: () => ({ x: placement.x, y: placement.y }),
+        setPosition: (next) => apply({ ...placement, ...next }),
+    });
+    const rotateController = createPointerRotateController({
+        getRotation: () => placement.rotation,
+        setRotation: (rotation) => apply({ ...placement, rotation }),
+    });
+    const gesture = createPointerGesture({
+        onMove: (event) => {
+            dragController.handlePointerMove(event);
+            rotateController.handlePointerMove(event);
+        },
+        onEnd: () => {
+            dragController.endDragging();
+            rotateController.endRotating();
+        },
+    });
+    /**
+     * Claims a press for a drag or turn. The claim's `preventDefault` suppresses
+     * the press's default focus, so focus the tool here: the arrow-key
+     * alternatives act on it.
+     */
+    function claim(event, element, target) {
+        if (!gesture.begin(event, target))
+            return false;
+        element.focus({ preventScroll: true });
+        return true;
+    }
+    const screenPivot = () => {
+        if (options.getScreenPivot)
+            return options.getScreenPivot();
+        const rect = options.getElement()?.getBoundingClientRect();
+        return (rect && { x: rect.left + rect.width / 2, y: rect.top + rect.height / 2 });
+    };
+    function nudge(direction) {
+        const { dx, dy, announceKey } = OVERLAY_PLACEMENT_NUDGES[direction];
+        apply({
+            x: placement.x + dx * OVERLAY_PLACEMENT_MOVE_STEP,
+            y: placement.y + dy * OVERLAY_PLACEMENT_MOVE_STEP,
+            rotation: placement.rotation,
+        });
+        options.announce(announceKey, {
+            position: Math.round(dx ? placement.x : placement.y),
+        });
+    }
+    function rotateBy(degrees) {
+        const rotation = (((Math.round(placement.rotation) + degrees) % 360) + 360) % 360;
+        apply({ ...placement, rotation });
+        options.announce("toolkit.announce.rotatedTo", { degrees: rotation });
+    }
+    const reapply = () => apply(placement);
+    return {
+        get placement() {
+            return placement;
+        },
+        apply,
+        show() {
+            const element = options.getElement();
+            if (!element)
+                return;
+            options.bringToFront?.(element);
+            reapply();
+        },
+        reset() {
+            gesture.release();
+            placement = { x: 0, y: 0, rotation: 0 };
+        },
+        startDrag(event) {
+            const element = options.getElement();
+            if (!element)
+                return;
+            options.bringToFront?.(element);
+            if (!claim(event, element, element))
+                return;
+            dragController.startDragging(event, element);
+        },
+        startRotate(event, handle) {
+            event.stopPropagation();
+            const element = options.getElement();
+            const pivot = screenPivot();
+            if (!element || !pivot)
+                return;
+            options.bringToFront?.(element);
+            if (!claim(event, element, handle))
+                return;
+            rotateController.startRotating(event, handle, pivot);
+        },
+        nudge,
+        rotateBy,
+        handleKeyDown(event) {
+            const direction = ARROW_KEYS[event.key];
+            if (direction && event.shiftKey) {
+                rotateBy(direction === "up" || direction === "left"
+                    ? -OVERLAY_PLACEMENT_ROTATE_STEP
+                    : OVERLAY_PLACEMENT_ROTATE_STEP);
+            }
+            else if (direction) {
+                nudge(direction);
+            }
+            else if (event.key === "PageUp") {
+                rotateBy(-OVERLAY_PLACEMENT_FINE_ROTATE_STEP);
+            }
+            else if (event.key === "PageDown") {
+                rotateBy(OVERLAY_PLACEMENT_FINE_ROTATE_STEP);
+            }
+            else {
+                return false;
+            }
+            event.preventDefault();
+            return true;
+        },
+        connect() {
+            window.addEventListener("resize", reapply);
+            return () => {
+                gesture.release();
+                window.removeEventListener("resize", reapply);
+            };
+        },
+    };
+}

package/dist/ui/pointer-gesture.d.ts

@@ -0,0 +1,32 @@
+export interface PointerGestureArgs {
+    /** Receives every move of the pointer that began the gesture. */
+    onMove: (event: PointerEvent) => void;
+    /** Called once when the gesture ends, however it ends. */
+    onEnd: () => void;
+}
+export interface PointerGesture {
+    isActive: () => boolean;
+    /**
+     * Claims a pointerdown for a gesture on `target`, returning whether it did.
+     * Declines a non-primary button, and any pointer while another gesture is
+     * active, so a second finger landing mid-drag neither moves nor pinches.
+     * The caller starts its drag or rotate controller after a claim, which
+     * takes the pointer capture this listens on.
+     */
+    begin: (event: PointerEvent, target: HTMLElement) => boolean;
+    /** Ends the active gesture, if any, and releases its pointer capture. */
+    release: () => void;
+}
+/**
+ * The lifecycle of one pointer gesture on a tool overlay: which pointer drives
+ * it, the listeners on the element that captured it, and every way it can end.
+ * `pointercancel` and `lostpointercapture` end it as well as `pointerup`,
+ * because iPadOS cancels a touch it takes over for a system gesture, and a
+ * gesture that waited for `pointerup` would stay stuck to the next touch.
+ *
+ * The claim calls `preventDefault`, which keeps a touch from scrolling or
+ * zooming the page and a mouse press from selecting text, and also suppresses
+ * the press's default focus: a caller whose keyboard alternatives act on a
+ * focused element focuses it itself.
+ */
+export declare function createPointerGesture(args: PointerGestureArgs): PointerGesture;

package/dist/ui/pointer-gesture.js

@@ -0,0 +1,56 @@
+/**
+ * The lifecycle of one pointer gesture on a tool overlay: which pointer drives
+ * it, the listeners on the element that captured it, and every way it can end.
+ * `pointercancel` and `lostpointercapture` end it as well as `pointerup`,
+ * because iPadOS cancels a touch it takes over for a system gesture, and a
+ * gesture that waited for `pointerup` would stay stuck to the next touch.
+ *
+ * The claim calls `preventDefault`, which keeps a touch from scrolling or
+ * zooming the page and a mouse press from selecting text, and also suppresses
+ * the press's default focus: a caller whose keyboard alternatives act on a
+ * focused element focuses it itself.
+ */
+export function createPointerGesture(args) {
+    let pointerId = null;
+    let target = null;
+    const handleMove = (event) => {
+        if (event.pointerId === pointerId)
+            args.onMove(event);
+    };
+    const handleEnd = (event) => {
+        if (event.pointerId === pointerId)
+            release();
+    };
+    function release() {
+        const releasedTarget = target;
+        const releasedPointerId = pointerId;
+        pointerId = null;
+        target = null;
+        if (!releasedTarget || releasedPointerId === null)
+            return;
+        releasedTarget.removeEventListener("pointermove", handleMove);
+        releasedTarget.removeEventListener("pointerup", handleEnd);
+        releasedTarget.removeEventListener("pointercancel", handleEnd);
+        releasedTarget.removeEventListener("lostpointercapture", handleEnd);
+        if (releasedTarget.hasPointerCapture(releasedPointerId)) {
+            releasedTarget.releasePointerCapture(releasedPointerId);
+        }
+        args.onEnd();
+    }
+    return {
+        isActive: () => pointerId !== null,
+        begin(event, nextTarget) {
+            if (event.button !== 0 || pointerId !== null)
+                return false;
+            pointerId = event.pointerId;
+            target = nextTarget;
+            nextTarget.addEventListener("pointermove", handleMove);
+            nextTarget.addEventListener("pointerup", handleEnd);
+            nextTarget.addEventListener("pointercancel", handleEnd);
+            nextTarget.addEventListener("lostpointercapture", handleEnd);
+            event.preventDefault();
+            return true;
+        },
+        release,
+    };
+}

package/dist/ui/pointer-rotate.d.ts

@@ -0,0 +1,29 @@
+import type { PointerDragPosition } from "./pointer-drag.js";
+export interface PointerRotateControllerArgs {
+    /** Current rotation in degrees. */
+    getRotation: () => number;
+    /** Receives the next rotation in degrees, normalised to `[0, 360)`. */
+    setRotation: (degrees: number) => void;
+}
+export interface PointerRotateController {
+    isRotating: () => boolean;
+    /**
+     * Begin tracking a rotation from a pointerdown on a rotation handle. `pivot`
+     * is the point the element turns about, in client coordinates. As with
+     * `createPointerDragController`, callers own pointer-capture release and
+     * listener attach/detach.
+     */
+    startRotating: (event: PointerEvent, container: Element, pivot: PointerDragPosition) => void;
+    /** No-ops when a rotation isn't in progress. */
+    handlePointerMove: (event: PointerEvent) => void;
+    endRotating: () => void;
+}
+/** Normalises an angle in degrees to `[0, 360)`. */
+export declare function normalizeDegrees(degrees: number): number;
+/**
+ * Tracks a pointer-capture-based rotation about a fixed pivot: the element
+ * turns by the angle the pointer sweeps around the pivot since the press, so
+ * grabbing the handle anywhere on its hit area causes no initial jump. The
+ * rotation counterpart of `createPointerDragController`.
+ */
+export declare function createPointerRotateController(args: PointerRotateControllerArgs): PointerRotateController;

package/dist/ui/pointer-rotate.js

@@ -0,0 +1,39 @@
+/** Normalises an angle in degrees to `[0, 360)`. */
+export function normalizeDegrees(degrees) {
+    const turned = degrees % 360;
+    return turned < 0 ? turned + 360 : turned;
+}
+function angleDegrees(pivot, x, y) {
+    return (Math.atan2(y - pivot.y, x - pivot.x) * 180) / Math.PI;
+}
+/**
+ * Tracks a pointer-capture-based rotation about a fixed pivot: the element
+ * turns by the angle the pointer sweeps around the pivot since the press, so
+ * grabbing the handle anywhere on its hit area causes no initial jump. The
+ * rotation counterpart of `createPointerDragController`.
+ */
+export function createPointerRotateController(args) {
+    let rotating = false;
+    let pivot = { x: 0, y: 0 };
+    let startAngle = 0;
+    let startRotation = 0;
+    return {
+        isRotating: () => rotating,
+        startRotating(event, container, nextPivot) {
+            container.setPointerCapture(event.pointerId);
+            rotating = true;
+            pivot = nextPivot;
+            startAngle = angleDegrees(pivot, event.clientX, event.clientY);
+            startRotation = args.getRotation();
+        },
+        handlePointerMove(event) {
+            if (!rotating)
+                return;
+            const swept = angleDegrees(pivot, event.clientX, event.clientY) - startAngle;
+            args.setRotation(normalizeDegrees(startRotation + swept));
+        },
+        endRotating() {
+            rotating = false;
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@pie-players/pie-players-shared",
-	"version": "0.3.73",
+	"version": "0.3.75",
 	"type": "module",
 	"description": "Shared runtime + UI utilities for PIE players",
 	"license": "MIT",
@@ -45,6 +45,10 @@
 			"types": "./dist/timed-media/index.d.ts",
 			"import": "./dist/timed-media/index.js"
 		},
+		"./media": {
+			"types": "./dist/media/index.d.ts",
+			"import": "./dist/media/index.js"
+		},
 		"./pie": {
 			"types": "./dist/pie/index.d.ts",
 			"import": "./dist/pie/index.js"
@@ -57,14 +61,6 @@
 			"types": "./dist/loaders/index.d.ts",
 			"import": "./dist/loaders/index.js"
 		},
-		"./server/npm-registry": {
-			"types": "./dist/server/npm-registry.d.ts",
-			"import": "./dist/server/npm-registry.js"
-		},
-		"./server/npm-auth-env": {
-			"types": "./dist/server/npm-auth-env.d.ts",
-			"import": "./dist/server/npm-auth-env.js"
-		},
 		"./i18n": {
 			"types": "./dist/i18n/index.d.ts",
 			"import": "./dist/i18n/index.js"
@@ -89,6 +85,10 @@
 			"types": "./dist/components/vendor/nds/nds-icon-button.d.ts",
 			"import": "./dist/components/vendor/nds/nds-icon-button.js"
 		},
+		"./ui/attribute-coercion": {
+			"types": "./dist/ui/attribute-coercion.d.ts",
+			"import": "./dist/ui/attribute-coercion.js"
+		},
 		"./ui/content-styles": {
 			"types": "./dist/ui/content-styles.d.ts",
 			"import": "./dist/ui/content-styles.js"
@@ -102,28 +102,31 @@
 		"dist"
 	],
 	"dependencies": {
+		"@pie-element/shared-utils": "0.1.3",
 		"@pie-lib/math-rendering-module": "6.0.0",
-		"dompurify": "^3.4.14",
+		"dompurify": "^3.4.16",
 		"semver": "^7.8.5"
 	},
 	"scripts": {
-		"build": "rm -rf dist tsconfig.tsbuildinfo && tsc -p tsconfig.json && mkdir -p dist/components && cp -R src/components/vendor dist/components/vendor",
+		"build": "rm -rf dist tsconfig.tsbuildinfo && tsc -p tsconfig.json && node scripts/bundle-vendored-modules.mjs && mkdir -p dist/components && cp -R src/components/vendor dist/components/vendor",
 		"dev": "tsc -p tsconfig.json --watch",
-		"typecheck": "tsc -p tsconfig.json --noEmit",
-		"lint": "biome check .",
+		"typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.tests.json",
+		"lint": "biome lint .",
 		"check": "tsc -p tsconfig.json --noEmit",
 		"test": "bun test",
 		"check-i18n": "bun run src/i18n/scripts/check-coverage.ts",
 		"scan-hardcoded": "bun run src/i18n/scripts/scan-hardcoded.ts"
 	},
 	"devDependencies": {
-		"@biomejs/biome": "^2.5.13",
-		"@happy-dom/global-registrator": "^20.11.15",
-		"@playwright/test": "^1.62.1",
+		"@biomejs/biome": "^2.5.15",
+		"@happy-dom/global-registrator": "^20.14.5",
+		"@pie-element/shared-math-rendering-mathjax": "0.1.4",
+		"@playwright/test": "^1.63.0",
 		"@types/semver": "^7.8.0",
+		"es-module-shims": "^2.8.4",
 		"esbuild": "^0.28.2",
 		"glob": "^13.0.0",
-		"svelte": "^5.57.0",
+		"svelte": "^5.57.1",
 		"typescript": "^5.9.3"
 	},
 	"homepage": "https://github.com/pie-framework/pie-players/tree/master/packages/players-shared#readme",
@@ -133,5 +136,7 @@
 	"engines": {
 		"node": ">=20.0.0"
 	},
-	"sideEffects": true
+	"sideEffects": [
+		"./dist/components/vendor/nds/*.js"
+	]
 }

package/dist/pie/component-context.d.ts

@@ -1,21 +0,0 @@
-/**
- * Component context stack for PIE mini-players.
- *
- * Used to attribute resource load failures (fonts/images/etc.) to the currently
- * active mini-player component.
- */
-export type ComponentContext = {
-    componentName: string;
-    elementType?: string;
-    itemId?: string;
-    timestamp: number;
-};
-/**
- * Register a component as active (call when component mounts).
- * Returns a cleanup function to call when the component unmounts.
- */
-export declare function registerActiveComponent(context: ComponentContext): () => void;
-/**
- * Get the current active component context (top of the stack).
- */
-export declare function getCurrentComponentContext(): ComponentContext | null;

package/dist/pie/component-context.js

@@ -1,29 +0,0 @@
-/**
- * Component context stack for PIE mini-players.
- *
- * Used to attribute resource load failures (fonts/images/etc.) to the currently
- * active mini-player component.
- */
-// Track active components (stack-based for nested components)
-const activeComponents = [];
-/**
- * Register a component as active (call when component mounts).
- * Returns a cleanup function to call when the component unmounts.
- */
-export function registerActiveComponent(context) {
-    activeComponents.push(context);
-    return () => {
-        const index = activeComponents.indexOf(context);
-        if (index > -1) {
-            activeComponents.splice(index, 1);
-        }
-    };
-}
-/**
- * Get the current active component context (top of the stack).
- */
-export function getCurrentComponentContext() {
-    return activeComponents.length > 0
-        ? activeComponents[activeComponents.length - 1]
-        : null;
-}

package/dist/pie/player-initializer.d.ts

@@ -1,54 +0,0 @@
-/**
- * Shared PIE player initialization logic
- * Used by preloaded static player runtimes
- */
-export interface PiePlayerConfig {
-    env: any;
-    addCorrectResponse: boolean;
-    session: any[];
-    externalStyleUrls?: string;
-    customClassName?: string;
-    containerClass?: string;
-    passageContainerClass?: string;
-}
-export interface ItemData {
-    item: {
-        config: any;
-    };
-    passage?: {
-        config: {
-            markup?: string;
-        };
-    };
-}
-export interface PiePlayerElements {
-    playerEl: HTMLElement;
-    passageMarkup: string | null;
-}
-/**
- * Initialize PIE player with item data
- * Shared initialization for preloaded/static player entrypoints.
- */
-export declare function initializePiePlayer(itemData: ItemData, config: PiePlayerConfig, elements: PiePlayerElements): Promise<void>;
-/**
- * Extract passage markup from item data
- */
-export declare function extractPassageMarkup(itemData: ItemData): string | null;
-/**
- * Ensure pie-player web component is loaded
- */
-export declare function ensurePiePlayerLoaded(): Promise<void>;
-/**
- * Build event listeners map for PIE elements
- */
-export declare function buildEventListenersMap(config: any, onSessionChanged: (detail: any) => void): Record<string, Record<string, (e: CustomEvent) => void>> | undefined;
-/**
- * Build URL parameters for API request
- * Shared by preloaded/static player entrypoints.
- */
-export declare function buildApiParams(env: any, addCorrectResponse: boolean): URLSearchParams;
-/**
- * Fetch item data from API
- * Shared by preloaded/static player entrypoints.
- */
-export declare function fetchItemData(apiBaseUrl: string, itemId: string, token: string, endpoint: "packaged" | "data-only", env: any, addCorrectResponse: boolean, signal?: AbortSignal): Promise<any>;