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

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.4",
 	"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": {
@@ -125,7 +125,7 @@
 		"@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",
+		"@playwright/test": "^1.64.1",
 		"@types/semver": "^7.8.0",
 		"es-module-shims": "^2.8.4",
 		"esbuild": "^0.28.2",