@pie-players/pie-players-shared 0.3.68 → 0.3.70

package/dist/security/wrap-overwide-tables.js

@@ -26,7 +26,7 @@
  * The wrapping itself lives in `./wrap-overwide.js`, shared with the image
  * wrapper: only the four values below and the accessible name differ.
  */
-import { wrapOverwideInElement, wrapOverwideMarkup, } from "./wrap-overwide.js";
+import { isOverwideWrapMutation, wrapOverwideInElement, wrapOverwideMarkup, } from "./wrap-overwide.js";
 function buildAriaLabel(table) {
     // Authors commonly label tables via <caption>, aria-label, or aria-labelledby.
     // Prefer the most explicit signal and fall back to the generic label so
@@ -75,3 +75,12 @@ export function wrapOverwideTablesInElement(root, options = {}) {
 export function wrapOverwideTables(markup) {
     return wrapOverwideMarkup(markup, TABLE_SPEC);
 }
+/**
+ * True when `record` mentions nothing but the output of
+ * {@link wrapOverwideTablesInElement} — a `pie-table-scroll` wrapper, or a
+ * `<table>` moving inside one. An observer-driven caller ignores such a record
+ * so its own wrap does not schedule a second pass.
+ */
+export function isOverwideTableWrapMutation(record) {
+    return isOverwideWrapMutation(record, TABLE_SPEC);
+}

package/dist/security/wrap-overwide.d.ts

@@ -49,3 +49,19 @@ export declare function wrapOverwideInElement(root: Element, spec: OverwideWrapS
  * is returned unchanged and the browser re-run on hydrate performs the wrap.
  */
 export declare function wrapOverwideMarkup(markup: string, spec: OverwideWrapSpec): string;
+/**
+ * True when `record` mentions nothing but this module's own live-DOM output for
+ * `spec`: a wrapper landing beside the node it wraps, or that node moving inside
+ * it.
+ *
+ * An observer-driven caller re-runs {@link wrapOverwideInElement} on every
+ * mutation tick, and the wrap itself inserts elements — so without this test the
+ * pass retriggers the observer that scheduled it, converging only because the
+ * wrap is idempotent. Ignoring the pass's own records is what removes the
+ * retrigger; a PIE element that re-renders over its own subtree and drops the
+ * wrapper is the case where absorbing it instead becomes a sustained loop.
+ *
+ * Conservative in the safe direction: anything it cannot account for reads as
+ * foreign, which costs one extra pass and never a missed wrap.
+ */
+export declare function isOverwideWrapMutation(record: MutationRecord, spec: OverwideWrapSpec): boolean;

package/dist/security/wrap-overwide.js

@@ -89,3 +89,55 @@ export function wrapOverwideMarkup(markup, spec) {
     });
     return wrapped > 0 ? body.innerHTML : markup;
 }
+function isElement(node) {
+    return node.nodeType === 1;
+}
+/** A `spec` wrapper holding nothing but the nodes `spec` wraps. */
+function isWrapperFor(node, spec) {
+    if (!isElement(node))
+        return false;
+    if (!node.classList?.contains(spec.wrapperClass))
+        return false;
+    for (const child of Array.from(node.children)) {
+        if (!child.matches(spec.selector))
+            return false;
+    }
+    return true;
+}
+/** A node `spec` wraps, currently held by a `spec` wrapper. */
+function isWrappedBy(node, spec) {
+    if (!isElement(node))
+        return false;
+    const parent = node.parentElement;
+    if (!parent?.classList?.contains(spec.wrapperClass))
+        return false;
+    return node.matches(spec.selector);
+}
+function everyNodeIsWrapOutput(nodes, spec) {
+    for (const node of Array.from(nodes)) {
+        if (!isWrapperFor(node, spec) && !isWrappedBy(node, spec))
+            return false;
+    }
+    return true;
+}
+/**
+ * True when `record` mentions nothing but this module's own live-DOM output for
+ * `spec`: a wrapper landing beside the node it wraps, or that node moving inside
+ * it.
+ *
+ * An observer-driven caller re-runs {@link wrapOverwideInElement} on every
+ * mutation tick, and the wrap itself inserts elements — so without this test the
+ * pass retriggers the observer that scheduled it, converging only because the
+ * wrap is idempotent. Ignoring the pass's own records is what removes the
+ * retrigger; a PIE element that re-renders over its own subtree and drops the
+ * wrapper is the case where absorbing it instead becomes a sustained loop.
+ *
+ * Conservative in the safe direction: anything it cannot account for reads as
+ * foreign, which costs one extra pass and never a missed wrap.
+ */
+export function isOverwideWrapMutation(record, spec) {
+    if (record.type !== "childList")
+        return false;
+    return (everyNodeIsWrapOutput(record.addedNodes, spec) &&
+        everyNodeIsWrapOutput(record.removedNodes, spec));
+}

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

@@ -0,0 +1,48 @@
+/**
+ * Containment for tool overlays that position themselves.
+ *
+ * An overlay that draws its own surface computes its own coordinates, and those
+ * coordinates are only meaningful against the box the browser resolved as its
+ * containing block. Reading that box from the element rather than from
+ * `window` is what keeps a tool correct wherever a host mounts it: the same
+ * numbers that centre a tool in the viewport put it outside a pane.
+ */
+/** Distance kept clear of the block's edges so an overlay's controls stay reachable. */
+export declare const DEFAULT_CONTAINMENT_GUTTER = 4;
+export interface Size {
+    width: number;
+    height: number;
+}
+export interface Point {
+    x: number;
+    y: number;
+}
+/**
+ * The box `element` resolves its `left`/`top` against: its containing block, or
+ * the viewport when that is the initial containing block.
+ *
+ * `offsetParent` is the containing block as the browser resolved it, including
+ * across a shadow boundary, which is what makes this correct for a tool mounted
+ * by a host it knows nothing about. Returns `undefined` outside a browser.
+ */
+export declare function resolveContainingBlockRect(element: HTMLElement | undefined | null): DOMRect | undefined;
+/**
+ * Clamps a translate offset applied to a box that is already centred in its
+ * containing block, so the box stays inside it.
+ *
+ * The travel available on each axis is symmetric about the centre: half the
+ * block, less half the box and the gutter. A box wider or taller than its block
+ * cannot satisfy that on the offending axis, so it stays centred there rather
+ * than clamping to an inverted range.
+ */
+export declare function clampOffsetWithinBlock(offset: Point, box: Size, block: Size, gutter?: number): Point;
+/**
+ * Clamps an absolute centre point, in containing-block coordinates, so the box
+ * it positions stays inside that block.
+ *
+ * The same invariant as `clampOffsetWithinBlock` in the coordinate system an
+ * overlay uses when it writes `left`/`top` instead of translating: the two are
+ * conjugate by a translation of half the block, including the degenerate case
+ * 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;

package/dist/ui/overlay-containment.js

@@ -0,0 +1,65 @@
+/**
+ * Containment for tool overlays that position themselves.
+ *
+ * An overlay that draws its own surface computes its own coordinates, and those
+ * coordinates are only meaningful against the box the browser resolved as its
+ * containing block. Reading that box from the element rather than from
+ * `window` is what keeps a tool correct wherever a host mounts it: the same
+ * numbers that centre a tool in the viewport put it outside a pane.
+ */
+/** Distance kept clear of the block's edges so an overlay's controls stay reachable. */
+export const DEFAULT_CONTAINMENT_GUTTER = 4;
+/**
+ * The box `element` resolves its `left`/`top` against: its containing block, or
+ * the viewport when that is the initial containing block.
+ *
+ * `offsetParent` is the containing block as the browser resolved it, including
+ * across a shadow boundary, which is what makes this correct for a tool mounted
+ * by a host it knows nothing about. Returns `undefined` outside a browser.
+ */
+export function resolveContainingBlockRect(element) {
+    if (typeof window === "undefined" || !element)
+        return undefined;
+    const parent = element.offsetParent;
+    if (parent instanceof HTMLElement) {
+        const rect = parent.getBoundingClientRect();
+        if (rect.width > 0 && rect.height > 0)
+            return rect;
+    }
+    return new DOMRect(0, 0, window.innerWidth, window.innerHeight);
+}
+/**
+ * Clamps a translate offset applied to a box that is already centred in its
+ * containing block, so the box stays inside it.
+ *
+ * The travel available on each axis is symmetric about the centre: half the
+ * block, less half the box and the gutter. A box wider or taller than its block
+ * cannot satisfy that on the offending axis, so it stays centred there rather
+ * than clamping to an inverted range.
+ */
+export function clampOffsetWithinBlock(offset, box, block, gutter = DEFAULT_CONTAINMENT_GUTTER) {
+    const clampAxis = (value, boxExtent, blockExtent) => {
+        const travel = blockExtent / 2 - boxExtent / 2 - gutter;
+        if (travel <= 0)
+            return 0;
+        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),
+    };
+}
+/**
+ * Clamps an absolute centre point, in containing-block coordinates, so the box
+ * it positions stays inside that block.
+ *
+ * The same invariant as `clampOffsetWithinBlock` in the coordinate system an
+ * overlay uses when it writes `left`/`top` instead of translating: the two are
+ * conjugate by a translation of half the block, including the degenerate case
+ * where a box exceeds its block and centres on the offending axis.
+ */
+export function clampPointWithinBlock(point, box, block, gutter = DEFAULT_CONTAINMENT_GUTTER) {
+    const centre = { x: block.width / 2, y: block.height / 2 };
+    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 };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@pie-players/pie-players-shared",
-	"version": "0.3.68",
+	"version": "0.3.70",
 	"type": "module",
 	"description": "Shared runtime + UI utilities for PIE players",
 	"license": "MIT",
@@ -106,8 +106,8 @@
 		"dist"
 	],
 	"dependencies": {
-		"@pie-lib/math-rendering-module": "5.1.2",
-		"dompurify": "^3.4.13",
+		"@pie-lib/math-rendering-module": "6.0.0",
+		"dompurify": "^3.4.14",
 		"semver": "^7.8.5"
 	},
 	"scripts": {
@@ -116,18 +116,18 @@
 		"typecheck": "tsc -p tsconfig.json --noEmit",
 		"lint": "biome check .",
 		"check": "tsc -p tsconfig.json --noEmit",
-		"test": "bun test '.test.ts'",
+		"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.8",
-		"@happy-dom/global-registrator": "^20.11.1",
+		"@biomejs/biome": "^2.5.11",
+		"@happy-dom/global-registrator": "^20.11.15",
 		"@playwright/test": "^1.62.1",
 		"@types/semver": "^7.8.0",
 		"esbuild": "^0.28.2",
 		"glob": "^13.0.0",
-		"svelte": "^5.56.8",
+		"svelte": "^5.57.0",
 		"typescript": "^5.9.3"
 	},
 	"homepage": "https://github.com/pie-framework/pie-players/tree/master/packages/players-shared#readme",