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

package/dist/ui/attribute-coercion.js

@@ -17,3 +17,36 @@ export function coerceBooleanLike(value, defaultValue = false) {
     }
     return Boolean(normalizedValue);
 }
+/**
+ * Reads a boolean attribute value: present is true and absent is false, as in
+ * HTML, except that the words `coerceBooleanLike` reads as false stay false.
+ */
+export function coerceBooleanAttribute(value) {
+    return value !== null && coerceBooleanLike(value, true);
+}
+const isBooleanProp = (element, attribute) => {
+    const definitions = element.$$p_d;
+    if (!definitions)
+        return false;
+    return Object.entries(definitions).some(([prop, definition]) => definition.type === "Boolean" &&
+        (definition.attribute ?? prop.toLowerCase()) === attribute);
+};
+/**
+ * `customElement.extend` hook for a Svelte element with `type: "Boolean"`
+ * props. Svelte reads those by presence, so `show-bottom-border="false"` sets
+ * the prop to `true`; this passes Svelte a removed attribute whenever
+ * `coerceBooleanAttribute` reads the value as false.
+ */
+export function coerceBooleanAttributes(ElementClass) {
+    const baseCallback = ElementClass.prototype.attributeChangedCallback;
+    return class extends ElementClass {
+        attributeChangedCallback(name, oldValue, newValue) {
+            const value = newValue !== null &&
+                isBooleanProp(this, name) &&
+                !coerceBooleanAttribute(newValue)
+                ? null
+                : newValue;
+            baseCallback?.call(this, name, oldValue, value);
+        }
+    };
+}

package/dist/ui/content-styles.d.ts

@@ -19,7 +19,7 @@
  * plain `tsc`, so it cannot inline a stylesheet. Bundler-built player packages
  * import it with Vite's `?raw` and hand the text over.
  */
-export type ContentStylesResult = "installed" | "already-installed" | "opted-out" | "no-document";
+export type ContentStylesResult = "installed" | "already-installed" | "host-supplied" | "opted-out" | "no-document";
 /**
  * True when the host declared `<html data-pie-content-styles="host">`, i.e. it
  * takes ownership of loading the stylesheet.
@@ -42,7 +42,16 @@ export declare function contentStylesOptedOut(): boolean;
  */
 export declare function contentStylesPresent(): boolean;
 /**
- * Installs `cssText` as a document-level stylesheet, once per document.
+ * Installs `cssText` as a document-level stylesheet, once per document, unless
+ * the host already supplies one.
+ *
+ * A host copy is recognised by the sentinel wherever it sits, including one
+ * confined to the host's player subtree with `@scope`. Such a host scoped its
+ * copy because the stylesheet's bare element selectors would otherwise reach
+ * its own UI, so a global copy from the player would reintroduce exactly that.
+ * A host copy can also land after this runs — a lazily injected `<style>`, a
+ * `<link>` still loading — so the installed copy keeps watching and removes
+ * itself when one appears, as it does when the host sets the opt-out late.
  *
  * The stylesheet is **prepended** to `<head>` and deliberately left out of a
  * cascade layer. Prepending reproduces the placement hosts were told to use by
@@ -60,22 +69,15 @@ export declare function contentStylesPresent(): boolean;
  */
 export declare function installContentStyles(cssText: string, source: string): ContentStylesResult;
 /**
- * Reports, once per page, the two ways content styling can go wrong. Neither is
- * detectable synchronously — a host copy may still be in flight as an async
- * `<link>` — so the check is deferred.
- *
- * - **Missing**: the host opted out and then loaded nothing, so authored content
- *   renders unstyled. This is the failure the old host-import contract produced
- *   silently.
- * - **Duplicated**: the host still imports `components.css` itself *and* the
- *   player installed a copy. Rendering is correct while the two agree, but the
- *   host's copy loads later and therefore wins ties at equal specificity — so a
- *   host copy pinned to an older `@pie-players/pie-theme` silently overrides the
- *   player's newer rules. Harmless today, a confusing override tomorrow.
+ * Reports, once per page, a host that opted out and then loaded no content
+ * stylesheet, so authored content renders unstyled — the failure the old
+ * host-import contract produced silently. Not detectable synchronously — a host
+ * copy may still be in flight as an async `<link>` — so the check is deferred.
  */
 export declare function auditContentStyles(source: string): void;
 /**
- * Test-only: clears the once-per-page warning latch and cancels any pending
- * deferred check, so a timer scheduled by one test cannot warn during the next.
+ * Test-only: clears the once-per-page warning latch, cancels any pending
+ * deferred check and stops watching for a host copy, so state from one test
+ * cannot act during the next.
  */
 export declare function resetContentStylesWarningForTesting(): void;

package/dist/ui/content-styles.js

@@ -23,9 +23,8 @@
 const MARKER_ATTRIBUTE = "data-pie-content-styles";
 /**
  * Declared by `components.css` itself, so it is observable no matter how the
- * stylesheet arrived — our injection or a host import. Diagnostics only: it
- * tells a host that opted out and then shipped nothing, and it spots a host copy
- * sitting alongside ours.
+ * stylesheet arrived — our injection or a host import. A host copy carrying it
+ * makes the player stand down, and an opted-out host with no copy is warned.
  */
 const SENTINEL_PROPERTY = "--pie-content-styles";
 // Svelte's dev-mode custom-element reset expands `all: unset` into individual
@@ -100,7 +99,16 @@ export function contentStylesPresent() {
     return countContentStyleSheets({ excludeInstalled: false }) > 0;
 }
 /**
- * Installs `cssText` as a document-level stylesheet, once per document.
+ * Installs `cssText` as a document-level stylesheet, once per document, unless
+ * the host already supplies one.
+ *
+ * A host copy is recognised by the sentinel wherever it sits, including one
+ * confined to the host's player subtree with `@scope`. Such a host scoped its
+ * copy because the stylesheet's bare element selectors would otherwise reach
+ * its own UI, so a global copy from the player would reintroduce exactly that.
+ * A host copy can also land after this runs — a lazily injected `<style>`, a
+ * `<link>` still loading — so the installed copy keeps watching and removes
+ * itself when one appears, as it does when the host sets the opt-out late.
  *
  * The stylesheet is **prepended** to `<head>` and deliberately left out of a
  * cascade layer. Prepending reproduces the placement hosts were told to use by
@@ -126,14 +134,58 @@ export function installContentStyles(cssText, source) {
         // the same stylesheet. Duplicating it would be harmless but pointless.
         return "already-installed";
     }
+    if (countHostContentStyleSheets() > 0)
+        return "host-supplied";
     if (!cssText)
         return "no-document";
     const style = document.createElement("style");
     style.setAttribute(MARKER_ATTRIBUTE, source);
     style.textContent = cssText;
     document.head.prepend(style);
+    watchForHostOwnership(style);
     return "installed";
 }
+let stopWatchingHostOwnership = null;
+const watchForHostOwnership = (installed) => {
+    stopWatchingHostOwnership?.();
+    if (typeof MutationObserver === "undefined")
+        return;
+    const stop = () => {
+        observer.disconnect();
+        document.removeEventListener("load", onLoad, true);
+        if (stopWatchingHostOwnership === stop)
+            stopWatchingHostOwnership = null;
+    };
+    const reconcile = () => {
+        if (!installed.isConnected) {
+            stop();
+            return;
+        }
+        if (contentStylesOptedOut() || countHostContentStyleSheets() > 0) {
+            installed.remove();
+            stop();
+        }
+    };
+    const observer = new MutationObserver((records) => {
+        const relevant = records.some((record) => record.type === "attributes" ||
+            Array.from(record.addedNodes).some((node) => node.nodeName === "STYLE" || node.nodeName === "LINK"));
+        if (relevant)
+            reconcile();
+    });
+    // `load` does not bubble, so a capturing listener is what sees a host
+    // `<link>` finish, including one already in flight when this runs.
+    const onLoad = (event) => {
+        if (event.target?.nodeName === "LINK")
+            reconcile();
+    };
+    observer.observe(document.head, { childList: true });
+    observer.observe(document.documentElement, {
+        attributes: true,
+        attributeFilter: [OPT_OUT_ATTRIBUTE],
+    });
+    document.addEventListener("load", onLoad, true);
+    stopWatchingHostOwnership = stop;
+};
 /**
  * Counts content stylesheets in the document, detected by the sentinel property
  * rather than by URL, so a copy arriving as a `<link>`, a bundler-injected
@@ -141,8 +193,8 @@ export function installContentStyles(cssText, source) {
  * count to copies the host loaded itself.
  *
  * Cross-origin sheets throw on `cssRules` access and are skipped; a host copy
- * served from another origin therefore reads as absent. That only costs a
- * diagnostic, never correctness.
+ * served from another origin therefore reads as absent, and the player installs
+ * its own copy alongside it. Such a host sets the opt-out attribute instead.
  */
 const countContentStyleSheets = ({ excludeInstalled, }) => {
     // Walks the owning elements rather than document.styleSheets: the marker
@@ -176,18 +228,10 @@ const countHostContentStyleSheets = () => countContentStyleSheets({ excludeInsta
 let auditWarningIssued = false;
 const pendingChecks = [];
 /**
- * Reports, once per page, the two ways content styling can go wrong. Neither is
- * detectable synchronously — a host copy may still be in flight as an async
- * `<link>` — so the check is deferred.
- *
- * - **Missing**: the host opted out and then loaded nothing, so authored content
- *   renders unstyled. This is the failure the old host-import contract produced
- *   silently.
- * - **Duplicated**: the host still imports `components.css` itself *and* the
- *   player installed a copy. Rendering is correct while the two agree, but the
- *   host's copy loads later and therefore wins ties at equal specificity — so a
- *   host copy pinned to an older `@pie-players/pie-theme` silently overrides the
- *   player's newer rules. Harmless today, a confusing override tomorrow.
+ * Reports, once per page, a host that opted out and then loaded no content
+ * stylesheet, so authored content renders unstyled — the failure the old
+ * host-import contract produced silently. Not detectable synchronously — a host
+ * copy may still be in flight as an async `<link>` — so the check is deferred.
  */
 export function auditContentStyles(source) {
     if (!isBrowser() || auditWarningIssued)
@@ -195,9 +239,7 @@ export function auditContentStyles(source) {
     const check = () => {
         if (auditWarningIssued)
             return;
-        if (contentStylesOptedOut()) {
-            if (contentStylesPresent())
-                return;
+        if (contentStylesOptedOut() && !contentStylesPresent()) {
             auditWarningIssued = true;
             console.warn(`[${source}] No PIE content stylesheet found. This document sets ` +
                 `${OPT_OUT_ATTRIBUTE}="${OPT_OUT_VALUE}", so ${source} did not install ` +
@@ -206,19 +248,6 @@ export function auditContentStyles(source) {
                 `families, answer-eliminator styles) will render unstyled. Either ` +
                 `import "@pie-players/pie-theme/components.css" in the host app, or ` +
                 `drop the ${OPT_OUT_ATTRIBUTE} attribute to let the player install it.`);
-            return;
-        }
-        if (countHostContentStyleSheets() > 0) {
-            auditWarningIssued = true;
-            console.warn(`[${source}] The PIE content stylesheet is loaded twice: ${source} ` +
-                `installs it, and this host also imports ` +
-                `"@pie-players/pie-theme/components.css". Rendering is unaffected ` +
-                `while both copies match, but the host copy loads later and wins ` +
-                `ties at equal specificity, so a copy pinned to an older ` +
-                `@pie-players/pie-theme will silently override newer player styles. ` +
-                `Remove the host import, or set ` +
-                `${OPT_OUT_ATTRIBUTE}="${OPT_OUT_VALUE}" on <html> to own the ` +
-                `stylesheet deliberately.`);
         }
     };
     // A host stylesheet can land well after the module graph evaluates, and a
@@ -240,10 +269,12 @@ export function auditContentStyles(source) {
     }
 }
 /**
- * Test-only: clears the once-per-page warning latch and cancels any pending
- * deferred check, so a timer scheduled by one test cannot warn during the next.
+ * Test-only: clears the once-per-page warning latch, cancels any pending
+ * deferred check and stops watching for a host copy, so state from one test
+ * cannot act during the next.
  */
 export function resetContentStylesWarningForTesting() {
+    stopWatchingHostOwnership?.();
     auditWarningIssued = false;
     for (const handle of pendingChecks)
         clearTimeout(handle);

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

@@ -36,6 +36,37 @@ export declare function resolveContainingBlockRect(element: HTMLElement | undefi
  * than clamping to an inverted range.
  */
 export declare function clampOffsetWithinBlock(offset: Point, box: Size, block: Size, gutter?: number): Point;
+/**
+ * Clamps a translate offset applied to a box centred in its containing block so
+ * that at least `visible` pixels of the box stay inside the block on each axis.
+ *
+ * For an overlay that has to overhang its block to be useful — a ruler lined up
+ * against content near a card's edge — without ever being dragged out of reach
+ * behind that edge. A box or block narrower than `visible` keeps all of the
+ * smaller extent.
+ */
+export declare function clampOffsetOverlappingBlock(offset: Point, box: Size, block: Size, visible: number): Point;
+/** The axis-aligned extent of a `size` box turned by `degrees` about its centre. */
+export declare function rotatedExtent(size: Size, degrees: number): Size;
+/**
+ * How far a `size` box's centre moves when the box turns by `degrees` about
+ * `origin`, given in the box's own coordinates from its top-left corner.
+ *
+ * Zero for a box turned about its centre. An overlay turned about another
+ * point adds this to its translate offset to get the offset of its rotated
+ * extent's centre, which is what the centred clamps above bound.
+ */
+export declare function rotationCentreShift(size: Size, origin: Point, degrees: number): Point;
+/**
+ * Where to centre a control strip docked past the bottom edge of a `box`
+ * turned by `degrees`, in the box's own coordinates from its top-left corner.
+ *
+ * The strip is drawn counter-rotated so it stays level on screen. Its reach
+ * along the box's downward normal is its projection onto that normal, which
+ * grows from its height at no turn to its width at a quarter turn, so a strip
+ * placed that far out clears the box at any rotation.
+ */
+export declare function uprightDockCentre(box: Size, strip: Size, degrees: number, gap: number): Point;
 /**
  * Clamps an absolute centre point, in containing-block coordinates, so the box
  * it positions stays inside that block.

package/dist/ui/overlay-containment.js

@@ -49,6 +49,69 @@ export function clampOffsetWithinBlock(offset, box, block, gutter = DEFAULT_CONT
         y: clampAxis(offset.y, box.height, block.height),
     };
 }
+/**
+ * Clamps a translate offset applied to a box centred in its containing block so
+ * that at least `visible` pixels of the box stay inside the block on each axis.
+ *
+ * For an overlay that has to overhang its block to be useful — a ruler lined up
+ * against content near a card's edge — without ever being dragged out of reach
+ * behind that edge. A box or block narrower than `visible` keeps all of the
+ * smaller extent.
+ */
+export function clampOffsetOverlappingBlock(offset, box, block, visible) {
+    const clampAxis = (value, boxExtent, blockExtent) => {
+        const keep = Math.min(visible, boxExtent, blockExtent);
+        const travel = blockExtent / 2 + boxExtent / 2 - keep;
+        return Math.max(-travel, Math.min(travel, value));
+    };
+    return {
+        x: clampAxis(offset.x, box.width, block.width),
+        y: clampAxis(offset.y, box.height, block.height),
+    };
+}
+/** The axis-aligned extent of a `size` box turned by `degrees` about its centre. */
+export function rotatedExtent(size, degrees) {
+    const radians = (degrees * Math.PI) / 180;
+    const cos = Math.abs(Math.cos(radians));
+    const sin = Math.abs(Math.sin(radians));
+    return {
+        width: size.width * cos + size.height * sin,
+        height: size.width * sin + size.height * cos,
+    };
+}
+/**
+ * How far a `size` box's centre moves when the box turns by `degrees` about
+ * `origin`, given in the box's own coordinates from its top-left corner.
+ *
+ * Zero for a box turned about its centre. An overlay turned about another
+ * point adds this to its translate offset to get the offset of its rotated
+ * extent's centre, which is what the centred clamps above bound.
+ */
+export function rotationCentreShift(size, origin, degrees) {
+    const radians = (degrees * Math.PI) / 180;
+    const cos = Math.cos(radians);
+    const sin = Math.sin(radians);
+    const dx = size.width / 2 - origin.x;
+    const dy = size.height / 2 - origin.y;
+    return {
+        x: dx * cos - dy * sin - dx,
+        y: dx * sin + dy * cos - dy,
+    };
+}
+/**
+ * Where to centre a control strip docked past the bottom edge of a `box`
+ * turned by `degrees`, in the box's own coordinates from its top-left corner.
+ *
+ * The strip is drawn counter-rotated so it stays level on screen. Its reach
+ * along the box's downward normal is its projection onto that normal, which
+ * grows from its height at no turn to its width at a quarter turn, so a strip
+ * placed that far out clears the box at any rotation.
+ */
+export function uprightDockCentre(box, strip, degrees, gap) {
+    const radians = (degrees * Math.PI) / 180;
+    const reach = strip.width * Math.abs(Math.sin(radians)) + strip.height * Math.abs(Math.cos(radians));
+    return { x: box.width / 2, y: box.height + gap + reach / 2 };
+}
 /**
  * Clamps an absolute centre point, in containing-block coordinates, so the box
  * it positions stays inside that block.

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

@@ -0,0 +1,110 @@
+/**
+ * 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 { type Point, type Size } from "./overlay-containment.js";
+/** An offset from the tool's centred position, and its turn about its pivot. */
+export interface OverlayPlacement {
+    x: number;
+    y: number;
+    rotation: number;
+}
+/** Pixels an arrow key or move button shifts the tool. */
+export declare const OVERLAY_PLACEMENT_MOVE_STEP = 10;
+/** Degrees Shift+arrow turns the tool. */
+export declare const OVERLAY_PLACEMENT_ROTATE_STEP = 5;
+/** Degrees Page Up/Down turns the tool. */
+export declare const OVERLAY_PLACEMENT_FINE_ROTATE_STEP = 1;
+/** Each move, with its tap control's glyph and label and its announcement. */
+export declare const OVERLAY_PLACEMENT_NUDGES: {
+    readonly left: {
+        readonly dx: -1;
+        readonly dy: 0;
+        readonly glyph: "←";
+        readonly labelKey: "toolkit.window.moveLeftA11y";
+        readonly announceKey: "toolkit.announce.movedLeft";
+    };
+    readonly up: {
+        readonly dx: 0;
+        readonly dy: -1;
+        readonly glyph: "↑";
+        readonly labelKey: "toolkit.window.moveUpA11y";
+        readonly announceKey: "toolkit.announce.movedUp";
+    };
+    readonly down: {
+        readonly dx: 0;
+        readonly dy: 1;
+        readonly glyph: "↓";
+        readonly labelKey: "toolkit.window.moveDownA11y";
+        readonly announceKey: "toolkit.announce.movedDown";
+    };
+    readonly right: {
+        readonly dx: 1;
+        readonly dy: 0;
+        readonly glyph: "→";
+        readonly labelKey: "toolkit.window.moveRightA11y";
+        readonly announceKey: "toolkit.announce.movedRight";
+    };
+};
+export type OverlayPlacementNudge = keyof typeof OVERLAY_PLACEMENT_NUDGES;
+/** The interface-catalog keys a move or turn is announced with. */
+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];
+export interface OverlayPlacementOptions {
+    /** The tool's positioned element, which receives the transform. */
+    getElement: () => HTMLElement | undefined;
+    /** The tap controls, docked level past the tool's bottom edge. */
+    getControls: () => HTMLElement | undefined;
+    /**
+     * The point the tool turns about, from its top-left corner at no turn.
+     * Defaults to its centre, and must match the stylesheet's `transform-origin`.
+     */
+    pivot?: (size: Size) => Point;
+    /**
+     * That pivot on screen when a pointer rotation starts, or `undefined` to
+     * decline it. Defaults to the centre of the tool's bounding box, which a turn
+     * about the centre leaves in place.
+     */
+    getScreenPivot?: () => Point | undefined;
+    /** Raises the tool above its peers when a gesture starts or it is shown. */
+    bringToFront?: (element: HTMLElement) => void;
+    /** Speaks a move or turn; the tool resolves the key in its interface catalog. */
+    announce: (key: OverlayPlacementAnnouncement, params: Record<string, number>) => void;
+}
+export interface OverlayPlacementController {
+    readonly placement: OverlayPlacement;
+    /**
+     * Writes `next` to `style.transform`, first keeping part of the turned tool
+     * inside the box it is positioned against. The bound lets the tool overhang:
+     * an item card is barely wider than a ruler, and full containment would pin
+     * its zero mark to the card's edge. The card clips what overhangs, and 100px
+     * stays in view to grab it back.
+     */
+    apply: (next: OverlayPlacement) => void;
+    /** Raises the tool and re-applies its placement, as a fresh reveal does. */
+    show: () => void;
+    /** Ends any gesture and returns the tool to its centred, upright position. */
+    reset: () => void;
+    /** Starts a drag from a press on the tool. */
+    startDrag: (event: PointerEvent) => void;
+    /** Starts a turn from a press on `handle`, which must not also start a drag. */
+    startRotate: (event: PointerEvent, handle: HTMLElement) => void;
+    /** Moves the tool one step, as an arrow key or a move button does. */
+    nudge: (direction: OverlayPlacementNudge) => void;
+    /** Turns the tool by `degrees`, clockwise when positive, to a whole degree. */
+    rotateBy: (degrees: number) => void;
+    /**
+     * Arrows move, Shift+arrows turn 5°, Page Up/Down turn 1°. Returns whether
+     * it handled the key, having prevented its default.
+     */
+    handleKeyDown: (event: KeyboardEvent) => boolean;
+    /**
+     * Re-applies the placement on window resize, which can leave the tool outside
+     * its shrunken containing block. Returns a cleanup that also ends any gesture.
+     */
+    connect: () => () => void;
+}
+export declare function createOverlayPlacement(options: OverlayPlacementOptions): OverlayPlacementController;