@pie-players/pie-players-shared 1.0.0-beta.3 → 1.0.0-beta.5

package/dist/pie/math-rendering.js

@@ -8,6 +8,7 @@
  */
 /// <reference path="../shims.d.ts" />
 import { createPieLogger, isGlobalDebugEnabled } from "./logger.js";
+import { pageMathAssetRoot } from "./math-assets.js";
 const GLOBAL_KEY = "@pie-lib/math-rendering";
 const GLOBAL_DLL_KEY = "_dll_pie_lib__math_rendering";
 // Every copy of @pie-lib/math-rendering on a page typesets through the MathJax
@@ -15,6 +16,52 @@ const GLOBAL_DLL_KEY = "_dll_pie_lib__math_rendering";
 const SHARED_INSTANCE_KEY = "@pie-lib/math-rendering@2";
 let initPromise = null;
 const logger = createPieLogger("math-rendering", () => isGlobalDebugEnabled());
+/**
+ * The speech-rule-engine version the default renderer bundles, whose rules it
+ * loads from `speech-rule-engine@<version>/lib/mathmaps` under an npm root. A
+ * test pins it to the module.
+ * @internal
+ */
+export const DEFAULT_RENDERER_SRE_VERSION = "4.1.2";
+const SRE_FEATURE_KEY = "SREfeature";
+const pageNamesSpeechRules = () => {
+    const feature = window[SRE_FEATURE_KEY];
+    if (feature && typeof feature === "object" && feature.json)
+        return true;
+    return Array.from(document.querySelectorAll('script[type="text/x-sre-config"]')).some((block) => {
+        try {
+            return !!JSON.parse(block.textContent || "")?.json;
+        }
+        catch {
+            return false;
+        }
+    });
+};
+/**
+ * Points the module's speech-rule-engine at the rules under `root` and returns
+ * the undo. SRE reads `SREfeature` as it sets up, synchronously while the
+ * module evaluates, and its later setups keep the path, so the global is
+ * restored afterwards: another copy of SRE on the page, as a legacy bundle
+ * carries, keeps the rules of its own version.
+ */
+const pointSpeechRulesAt = (root) => {
+    if (!root || typeof document === "undefined" || pageNamesSpeechRules()) {
+        return () => { };
+    }
+    const host = window;
+    const had = Object.hasOwn(host, SRE_FEATURE_KEY);
+    const previous = host[SRE_FEATURE_KEY];
+    host[SRE_FEATURE_KEY] = {
+        ...(previous && typeof previous === "object" ? previous : {}),
+        json: `${root.replace(/\/+$/, "")}/speech-rule-engine@${DEFAULT_RENDERER_SRE_VERSION}/lib/mathmaps`,
+    };
+    return () => {
+        if (had)
+            host[SRE_FEATURE_KEY] = previous;
+        else
+            delete host[SRE_FEATURE_KEY];
+    };
+};
 /**
  * The page's renderer: the one `initializeMathRendering` installed, or a
  * host's. IIFE elements render with it, and so do ESM elements when the page
@@ -66,6 +113,8 @@ const createSharedInstance = (renderer) => {
  * - window["@pie-lib/math-rendering"] (standard key)
  * - window["_dll_pie_lib__math_rendering"] (SystemJS/DLL key for IIFE bundles)
  *
+ * The first call installs the renderer for the page, so its `options` apply.
+ *
  * @example
  * ```typescript
  * // Default MathJax
@@ -76,7 +125,7 @@ const createSharedInstance = (renderer) => {
  * await initializeMathRendering();
  * ```
  */
-export async function initializeMathRendering() {
+export async function initializeMathRendering(options = {}) {
     // Only run in browser
     if (typeof window === "undefined") {
         return;
@@ -90,6 +139,7 @@ export async function initializeMathRendering() {
         return;
     }
     initPromise = (async () => {
+        const restoreSpeechRules = pointSpeechRulesAt(pageMathAssetRoot() ?? options.assetRoot);
         try {
             // The package has no exports map, so the file is named in full for
             // resolvers that do not complete a directory, such as webpack's
@@ -112,6 +162,9 @@ export async function initializeMathRendering() {
             logger.error("Failed to initialize math rendering:", error);
             throw error;
         }
+        finally {
+            restoreSpeechRules();
+        }
     })();
     try {
         await initPromise;

package/dist/types/index.d.ts

@@ -557,6 +557,10 @@ export interface ToolParameterMap {
         pitch?: number;
         volume?: number;
     };
+    /** `zoom` is the lens's starting magnification, 2 meaning twice the size. */
+    magnification: {
+        zoom?: number;
+    };
 }
 /** The parameter shape of tool `K`: its {@link ToolParameterMap} entry, else open. */
 export type ToolParametersFor<K extends string> = K extends keyof ToolParameterMap ? ToolParameterMap[K] : Record<string, unknown>;
@@ -582,6 +586,14 @@ export interface Env {
     mode: PlayerMode;
     role: PlayerRole;
     partialScoring?: boolean;
+    /**
+     * BCP 47 tag of the language the item's content is written in, when the
+     * delivery knows it. The player reflects it onto the content subtree as
+     * `lang`/`dir`; a host that emits nothing leaves the content unstamped.
+     * The interface locale never travels here — it is the player's `locale`
+     * attribute and the `pie.interfaceLocale` context.
+     */
+    locale?: string;
 }
 /** The `detail` of the `player-error` event `pie-item-player` dispatches. */
 export interface PieItemPlayerErrorDetail {

package/dist/ui/focus-trap.d.ts

@@ -24,4 +24,16 @@ type FocusTrapOptions = {
  * and restores prior focus when the trap is removed.
  */
 export declare function createFocusTrap(container: HTMLElement, options?: FocusTrapOptions): () => void;
+/**
+ * Returns focus to where it was before a tool took it, for a tool that closes
+ * itself: the tool's element leaves the DOM on close, which drops focus to the
+ * document body. `capture` runs as the tool takes focus and `restore` as it
+ * closes, before its element goes.
+ */
+export declare function createFocusReturn(): {
+    /** Records the focused element, unless focus is already inside `container`. */
+    capture: (container: Node) => void;
+    /** Focuses the recorded element, if it is still in the document. */
+    restore: () => void;
+};
 export {};

package/dist/ui/focus-trap.js

@@ -44,7 +44,11 @@ export function createFocusTrap(container, options = {}) {
     const wrap = options.wrap ?? true;
     const onKeydown = (event) => {
         if (event.key === "Escape") {
-            options.onEscape?.();
+            if (!options.onEscape)
+                return;
+            // Claimed, so a page-wide Escape listener does not also act on it.
+            event.preventDefault();
+            options.onEscape();
             return;
         }
         if (event.key !== "Tab")
@@ -94,3 +98,37 @@ export function createFocusTrap(container, options = {}) {
         }
     };
 }
+/**
+ * Returns focus to where it was before a tool took it, for a tool that closes
+ * itself: the tool's element leaves the DOM on close, which drops focus to the
+ * document body. `capture` runs as the tool takes focus and `restore` as it
+ * closes, before its element goes.
+ */
+export function createFocusReturn() {
+    let opener = null;
+    return {
+        capture(container) {
+            if (typeof document === "undefined")
+                return;
+            const active = getDeepActiveElement(document);
+            if (active && container.contains(active))
+                return;
+            opener =
+                active instanceof HTMLElement && active !== document.body
+                    ? active
+                    : null;
+        },
+        restore() {
+            const target = opener;
+            opener = null;
+            if (!target?.isConnected)
+                return;
+            try {
+                target.focus();
+            }
+            catch {
+                // ignore
+            }
+        },
+    };
+}

package/dist/ui/overlay-containment.d.ts

@@ -17,6 +17,11 @@ export interface Point {
     x: number;
     y: number;
 }
+/** A box on screen: its top-left corner and its extent, as a `DOMRect` gives them. */
+export interface ScreenBox extends Size {
+    left: number;
+    top: number;
+}
 /**
  * The box `element` resolves its `left`/`top` against: its containing block, or
  * the viewport when that is the initial containing block.
@@ -77,3 +82,11 @@ export declare function uprightDockCentre(box: Size, strip: Size, degrees: numbe
  * where a box exceeds its block and centres on the offending axis.
  */
 export declare function clampPointWithinBlock(point: Point, box: Size, block: Size, gutter?: number): Point;
+/**
+ * The top-left corner, in viewport coordinates, of a control strip docked
+ * beside an upright `tool`: centred below it, or above it when only the space
+ * above holds the strip, and slid along the tool's edge to stay inside the
+ * block. A strip that fits on neither side takes the roomier one; a strip wider
+ * than the block centres on it.
+ */
+export declare function uprightDockCorner(tool: ScreenBox, strip: Size, block: ScreenBox, gap: number, gutter?: number): Point;

package/dist/ui/overlay-containment.js

@@ -126,3 +126,26 @@ export function clampPointWithinBlock(point, box, block, gutter = DEFAULT_CONTAI
     const offset = clampOffsetWithinBlock({ x: point.x - centre.x, y: point.y - centre.y }, box, block, gutter);
     return { x: centre.x + offset.x, y: centre.y + offset.y };
 }
+/**
+ * The top-left corner, in viewport coordinates, of a control strip docked
+ * beside an upright `tool`: centred below it, or above it when only the space
+ * above holds the strip, and slid along the tool's edge to stay inside the
+ * block. A strip that fits on neither side takes the roomier one; a strip wider
+ * than the block centres on it.
+ */
+export function uprightDockCorner(tool, strip, block, gap, gutter = DEFAULT_CONTAINMENT_GUTTER) {
+    const top = block.top + gutter;
+    const bottom = block.top + block.height - gutter;
+    const below = tool.top + tool.height + gap;
+    const above = tool.top - gap - strip.height;
+    const roomBelow = bottom - below;
+    const roomAbove = tool.top - gap - top;
+    const y = roomBelow >= strip.height || (roomAbove < strip.height && roomBelow >= roomAbove)
+        ? below
+        : above;
+    const travel = block.width - gutter * 2 - strip.width;
+    const x = travel <= 0
+        ? block.left + (block.width - strip.width) / 2
+        : Math.max(block.left + gutter, Math.min(block.left + gutter + travel, tool.left + (tool.width - strip.width) / 2));
+    return { x, y };
+}

package/dist/ui/overlay-placement.d.ts

@@ -53,6 +53,34 @@ export type OverlayPlacementNudge = keyof typeof OVERLAY_PLACEMENT_NUDGES;
 export type OverlayPlacementAnnouncement = (typeof OVERLAY_PLACEMENT_NUDGES)[OverlayPlacementNudge]["announceKey"] | "toolkit.announce.rotatedTo";
 /** The tap controls' rotations, the keyboard's two steps each way. */
 export declare const OVERLAY_PLACEMENT_ROTATIONS: readonly [number, number, 1, 5];
+/**
+ * What the tap controls drive: a step for each arrow, and a turn for a tool
+ * that rotates. An `OverlayPlacementController` is one; an upright tool that
+ * keeps its own position supplies `nudge` alone.
+ */
+export interface OverlayTapTarget {
+    nudge: (direction: OverlayPlacementNudge) => void;
+    rotateBy?: (degrees: number) => void;
+}
+/** A shrink-and-grow pair on the tap controls, labelled by the tool. */
+export interface OverlaySizeControl {
+    shrink: {
+        glyph: string;
+        label: string;
+    };
+    grow: {
+        glyph: string;
+        label: string;
+    };
+    step: (direction: 1 | -1) => void;
+}
+/**
+ * Docks an upright tool's tap controls beside it, as `uprightDockCorner`
+ * places them. `OverlayPlacementControls` lays the controls out at the tool's
+ * top-left corner, so the offset is taken from there. A strip wider than the
+ * block wraps onto more rows, so a phone-width pane does not clip it.
+ */
+export declare function dockUprightControls(element: HTMLElement, controls: HTMLElement): void;
 export interface OverlayPlacementOptions {
     /** The tool's positioned element, which receives the transform. */
     getElement: () => HTMLElement | undefined;

package/dist/ui/overlay-placement.js

@@ -4,7 +4,7 @@
  * 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 { clampOffsetOverlappingBlock, DEFAULT_CONTAINMENT_GUTTER, resolveContainingBlockRect, rotatedExtent, rotationCentreShift, uprightDockCentre, uprightDockCorner, } from "./overlay-containment.js";
 import { createPointerDragController } from "./pointer-drag.js";
 import { createPointerGesture } from "./pointer-gesture.js";
 import { createPointerRotateController } from "./pointer-rotate.js";
@@ -60,8 +60,23 @@ const ARROW_KEYS = {
 };
 /** 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. */
+/** Space between the tool and its tap controls. */
 const CONTROLS_GAP = 8;
+/**
+ * Docks an upright tool's tap controls beside it, as `uprightDockCorner`
+ * places them. `OverlayPlacementControls` lays the controls out at the tool's
+ * top-left corner, so the offset is taken from there. A strip wider than the
+ * block wraps onto more rows, so a phone-width pane does not clip it.
+ */
+export function dockUprightControls(element, controls) {
+    const block = resolveContainingBlockRect(element);
+    if (!block)
+        return;
+    controls.style.maxWidth = `${Math.max(0, block.width - DEFAULT_CONTAINMENT_GUTTER * 2)}px`;
+    const tool = element.getBoundingClientRect();
+    const corner = uprightDockCorner(tool, { width: controls.offsetWidth, height: controls.offsetHeight }, block, CONTROLS_GAP);
+    controls.style.transform = `translate(${corner.x - tool.left - element.clientLeft}px, ${corner.y - tool.top - element.clientTop}px)`;
+}
 export function createOverlayPlacement(options) {
     let placement = { x: 0, y: 0, rotation: 0 };
     const sizeOf = (element) => ({

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@pie-players/pie-players-shared",
-	"version": "1.0.0-beta.3",
+	"version": "1.0.0-beta.5",
 	"type": "module",
 	"description": "Shared runtime + UI utilities for PIE players",
 	"license": "MIT",
@@ -106,9 +106,9 @@
 		"dist"
 	],
 	"dependencies": {
-		"@pie-element/shared-utils": "0.1.3",
+		"@pie-element/shared-utils": "0.1.4",
 		"@pie-lib/math-rendering-module": "6.0.0",
-		"dompurify": "^3.4.16",
+		"dompurify": "^3.4.17",
 		"semver": "^7.8.5"
 	},
 	"scripts": {
@@ -124,8 +124,8 @@
 	"devDependencies": {
 		"@biomejs/biome": "^2.5.15",
 		"@happy-dom/global-registrator": "^20.14.5",
-		"@pie-element/shared-math-rendering-mathjax": "0.1.4",
-		"@playwright/test": "^1.64.0",
+		"@pie-element/shared-math-rendering-mathjax": "0.1.7",
+		"@playwright/test": "^1.64.1",
 		"@types/semver": "^7.8.0",
 		"es-module-shims": "^2.8.4",
 		"esbuild": "^0.28.2",