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

package/dist/loaders/preloaded-registration.d.ts

@@ -11,6 +11,11 @@
  * define the ones content names under another base tag
  * (`defineAuthoredPreloadedTags`) and assert them (`assertRegistered`).
  *
+ * pie-elements-ng's `./browser/*` modules export `piePackage`, the
+ * `{ name, version }` of the package they were built from, so an entry can
+ * give its modules alone. A `package` or `version` it also gives must match,
+ * which catches a registration an upgrade left behind.
+ *
  * A hosted player takes models from the server and resolves no controller. A
  * player that is not hosted runs the controller's `model()` in the browser, so
  * it needs the `controller` an entry registers; the item player warns about
@@ -29,13 +34,20 @@ export interface PreloadedElement {
     /**
      * Base tag to register, e.g. `pie-element-multiple-choice`. Content can
      * author another base tag for the package, which the players define from
-     * this registration.
+     * this registration. Defaults to the package name without its `@`, with
+     * `-` for `/`.
+     */
+    tag?: string;
+    /**
+     * npm package name, e.g. `@pie-element/multiple-choice`. Defaults to the
+     * name in the modules' `piePackage`.
+     */
+    package?: string;
+    /**
+     * The installed version, exact, e.g. `13.4.4`. Defaults to the version in
+     * the modules' `piePackage`.
      */
-    tag: string;
-    /** npm package name, e.g. `@pie-element/multiple-choice`. */
-    package: string;
-    /** The installed version, exact, e.g. `13.4.4`. */
-    version: string;
+    version?: string;
     /** The package's `./browser/delivery` module, or its default export. */
     element: CustomElementConstructor | {
         readonly default: CustomElementConstructor;

package/dist/loaders/preloaded-registration.js

@@ -11,6 +11,11 @@
  * define the ones content names under another base tag
  * (`defineAuthoredPreloadedTags`) and assert them (`assertRegistered`).
  *
+ * pie-elements-ng's `./browser/*` modules export `piePackage`, the
+ * `{ name, version }` of the package they were built from, so an entry can
+ * give its modules alone. A `package` or `version` it also gives must match,
+ * which catches a registration an upgrade left behind.
+ *
  * A hosted player takes models from the server and resolves no controller. A
  * player that is not hosted runs the controller's `model()` in the browser, so
  * it needs the `controller` an entry registers; the item player warns about
@@ -23,6 +28,7 @@
 import { defineCustomElementSafely } from "../pie/custom-element-define.js";
 import { mathAssetOptionsError, setMathAssetOptions, } from "../pie/math-assets.js";
 import { writeRegistryEntry } from "../pie/registry.js";
+import { validateCustomElementTag } from "../pie/tag-names.js";
 import { BundleType, isCustomElementConstructor, Status } from "../pie/types.js";
 import { parsePackageName } from "../pie/utils.js";
 import { toPackageVersionedTag } from "../pie/versioned-tag.js";
@@ -69,15 +75,24 @@ export function registerPreloadedElements(elements, options = {}) {
 function resolveElement(element, index) {
     const at = `[registerPreloadedElements] entry ${index}`;
     if (!element || typeof element !== "object") {
-        throw new Error(`${at}: expected { tag, package, version, element }`);
+        throw new Error(`${at}: expected { element, controller?, tag?, package?, version? }`);
+    }
+    const identity = moduleIdentity(element, at);
+    if (!identity && element.package === undefined && element.version === undefined) {
+        throw new Error(`${at}: package and version are required for modules that export no piePackage`);
     }
-    const { package: packageName, version, tag } = element;
+    const packageName = element.package ?? identity?.name;
+    const version = element.version ?? identity?.version;
     if (!isBarePackageName(packageName)) {
         throw new Error(`${at}: package must be a bare package name, got ${JSON.stringify(packageName)}`);
     }
     if (typeof version !== "string" || !isExactSemver(version)) {
         throw new Error(`${at} (${packageName}): version must be the installed version, exact, such as 1.2.3; got ${JSON.stringify(version)}`);
     }
+    if (identity && (identity.name !== packageName || identity.version !== version)) {
+        throw new Error(`${at}: the modules were built from ${identity.name}@${identity.version}, not ${packageName}@${version}`);
+    }
+    const tag = element.tag ?? packageName.replace(/^@/, "").replace("/", "-");
     if (typeof tag !== "string" || !tag) {
         throw new Error(`${at} (${packageName}): tag must be the base tag to register, got ${JSON.stringify(tag)}`);
     }
@@ -95,13 +110,33 @@ function resolveElement(element, index) {
         }
     }
     const spec = `${packageName}@${version}`;
-    return {
-        packageName,
-        spec,
-        tagName: toPackageVersionedTag(tag, spec),
-        elementClass: candidate,
-        controller,
-    };
+    const tagName = validateCustomElementTag(toPackageVersionedTag(tag, spec), element.tag === undefined
+        ? `${at} (${packageName}) tag derived from the package name; give tag`
+        : `${at} (${packageName}) tag`);
+    return { packageName, spec, tagName, elementClass: candidate, controller };
+}
+/** The `piePackage` of the entry's modules, which agree when both export one. */
+function moduleIdentity(element, at) {
+    const fromElement = readPackageIdentity(element.element, `${at}: element`);
+    const fromController = readPackageIdentity(element.controller, `${at}: controller`);
+    if (fromElement &&
+        fromController &&
+        (fromElement.name !== fromController.name ||
+            fromElement.version !== fromController.version)) {
+        throw new Error(`${at}: the element module is ${fromElement.name}@${fromElement.version}, ` +
+            `but the controller module is ${fromController.name}@${fromController.version}`);
+    }
+    return fromElement ?? fromController;
+}
+function readPackageIdentity(module, at) {
+    if (!module || typeof module !== "object" || !("piePackage" in module)) {
+        return undefined;
+    }
+    const identity = module.piePackage;
+    if (typeof identity?.name !== "string" || typeof identity.version !== "string") {
+        throw new Error(`${at} module's piePackage must be { name, version }`);
+    }
+    return { name: identity.name, version: identity.version };
 }
 function resolveController(value) {
     if (!value || typeof value !== "object")

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

@@ -0,0 +1,20 @@
+/**
+ * Keeps the image and table scroll wrappers under a live root in step with
+ * whether they scroll. See {@link syncOverwideRegions}.
+ *
+ * Overflow changes without any mutation: zoom and a resized column change the
+ * wrapper's width, an image load or a dropped drag tile changes its content's.
+ * A `ResizeObserver` on each wrapper and its content catches both, and its first
+ * delivery for a newly observed target is the initial sync. A wrapper that is
+ * not laid out measures zero and syncs as non-scrolling; showing it resizes it,
+ * which syncs it again.
+ *
+ * Without `ResizeObserver` nothing is synced, so every wrapper stays a region —
+ * the reachable default.
+ */
+export interface OverwideRegionTracker {
+    /** Starts observing every wrapper under the root not yet observed. */
+    track(): void;
+    disconnect(): void;
+}
+export declare function createOverwideRegionTracker(root: Element): OverwideRegionTracker;

package/dist/security/overwide-regions.js

@@ -0,0 +1,65 @@
+/**
+ * Keeps the image and table scroll wrappers under a live root in step with
+ * whether they scroll. See {@link syncOverwideRegions}.
+ *
+ * Overflow changes without any mutation: zoom and a resized column change the
+ * wrapper's width, an image load or a dropped drag tile changes its content's.
+ * A `ResizeObserver` on each wrapper and its content catches both, and its first
+ * delivery for a newly observed target is the initial sync. A wrapper that is
+ * not laid out measures zero and syncs as non-scrolling; showing it resizes it,
+ * which syncs it again.
+ *
+ * Without `ResizeObserver` nothing is synced, so every wrapper stays a region —
+ * the reachable default.
+ */
+import { IMAGE_SPEC } from "./wrap-overwide-images.js";
+import { TABLE_SPEC } from "./wrap-overwide-tables.js";
+import { syncOverwideRegions } from "./wrap-overwide.js";
+const SPECS = [IMAGE_SPEC, TABLE_SPEC];
+const WRAPPER_SELECTOR = SPECS.map((spec) => `.${spec.wrapperClass}`).join(",");
+export function createOverwideRegionTracker(root) {
+    if (typeof ResizeObserver === "undefined") {
+        return { track() { }, disconnect() { } };
+    }
+    // Wrapper to the content observed with it. Held strongly, as the observer
+    // holds its targets, so each `track()` releases wrappers that have left the
+    // document — an element re-rendering over its subtree drops them every time.
+    const observed = new Map();
+    const observer = new ResizeObserver((entries) => {
+        const wrappers = new Set();
+        for (const { target } of entries) {
+            const wrapper = target.matches(WRAPPER_SELECTOR)
+                ? target
+                : target.parentElement;
+            if (wrapper)
+                wrappers.add(wrapper);
+        }
+        for (const spec of SPECS)
+            syncOverwideRegions(wrappers, spec);
+    });
+    return {
+        track() {
+            for (const [wrapper, content] of observed) {
+                if (wrapper.isConnected)
+                    continue;
+                observer.unobserve(wrapper);
+                if (content)
+                    observer.unobserve(content);
+                observed.delete(wrapper);
+            }
+            for (const wrapper of Array.from(root.querySelectorAll(WRAPPER_SELECTOR))) {
+                if (observed.has(wrapper))
+                    continue;
+                const content = wrapper.firstElementChild;
+                observed.set(wrapper, content);
+                observer.observe(wrapper);
+                if (content)
+                    observer.observe(content);
+            }
+        },
+        disconnect() {
+            observer.disconnect();
+            observed.clear();
+        },
+    };
+}

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

@@ -5,7 +5,9 @@
  *
  * The wrapper is rendered as
  * `<span class="pie-image-scroll" tabindex="0" role="region" aria-label="...">`
- * and receives the accompanying CSS from `@pie-players/pie-theme`. The CSS uses
+ * and receives the accompanying CSS from `@pie-players/pie-theme`.
+ * The live player keeps the region attributes only while the wrapper actually
+ * scrolls (see `./overwide-regions.js`), so a image that fits adds no tab stop. The CSS uses
  * `overflow-x: auto` so small images stay visually unchanged: a scrollbar only
  * appears when the image's intrinsic width exceeds the wrapper's available
  * space (including at higher browser-zoom levels, which is the original driver
@@ -26,7 +28,9 @@
  * The wrapping itself lives in `./wrap-overwide.js`, shared with the table
  * wrapper: only the spec below differs.
  */
-import { type WrapOverwideOptions } from "./wrap-overwide.js";
+import { type OverwideWrapSpec, type WrapOverwideOptions } from "./wrap-overwide.js";
+/** Internal: shared with the region tracker, not re-exported. */
+export declare const IMAGE_SPEC: OverwideWrapSpec;
 export type WrapOverwideImagesInElementOptions = WrapOverwideOptions;
 /**
  * Wrap every unwrapped `<img>` descendant of `root` with the shared

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

@@ -5,7 +5,9 @@
  *
  * The wrapper is rendered as
  * `<span class="pie-image-scroll" tabindex="0" role="region" aria-label="...">`
- * and receives the accompanying CSS from `@pie-players/pie-theme`. The CSS uses
+ * and receives the accompanying CSS from `@pie-players/pie-theme`.
+ * The live player keeps the region attributes only while the wrapper actually
+ * scrolls (see `./overwide-regions.js`), so a image that fits adds no tab stop. The CSS uses
  * `overflow-x: auto` so small images stay visually unchanged: a scrollbar only
  * appears when the image's intrinsic width exceeds the wrapper's available
  * space (including at higher browser-zoom levels, which is the original driver
@@ -50,7 +52,8 @@ function imageLayoutClass(image) {
         display !== "contents";
     return blockLevel ? "pie-image-scroll-block" : null;
 }
-const IMAGE_SPEC = {
+/** Internal: shared with the region tracker, not re-exported. */
+export const IMAGE_SPEC = {
     selector: "img",
     wrapperTag: "span",
     wrapperClass: "pie-image-scroll",

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

@@ -5,7 +5,9 @@
  *
  * The wrapper is rendered as
  * `<div class="pie-table-scroll" tabindex="0" role="region" aria-label="...">`
- * and receives the accompanying CSS from `@pie-players/pie-theme`. The CSS uses
+ * and receives the accompanying CSS from `@pie-players/pie-theme`.
+ * The live player keeps the region attributes only while the wrapper actually
+ * scrolls (see `./overwide-regions.js`), so a table that fits adds no tab stop. The CSS uses
  * `overflow-x: auto` so narrow tables stay visually unchanged: a scrollbar only
  * appears when the table's intrinsic width exceeds the wrapper's available
  * space (including at higher browser-zoom levels — WCAG 1.4.10 Reflow at 400%
@@ -26,7 +28,9 @@
  * The wrapping itself lives in `./wrap-overwide.js`, shared with the image
  * wrapper: only the four values below and the accessible name differ.
  */
-import { type WrapOverwideOptions } from "./wrap-overwide.js";
+import { type OverwideWrapSpec, type WrapOverwideOptions } from "./wrap-overwide.js";
+/** Internal: shared with the region tracker, not re-exported. */
+export declare const TABLE_SPEC: OverwideWrapSpec;
 export type WrapOverwideTablesInElementOptions = WrapOverwideOptions;
 /**
  * Wrap every unwrapped `<table>` descendant of `root` with the shared

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

@@ -5,7 +5,9 @@
  *
  * The wrapper is rendered as
  * `<div class="pie-table-scroll" tabindex="0" role="region" aria-label="...">`
- * and receives the accompanying CSS from `@pie-players/pie-theme`. The CSS uses
+ * and receives the accompanying CSS from `@pie-players/pie-theme`.
+ * The live player keeps the region attributes only while the wrapper actually
+ * scrolls (see `./overwide-regions.js`), so a table that fits adds no tab stop. The CSS uses
  * `overflow-x: auto` so narrow tables stay visually unchanged: a scrollbar only
  * appears when the table's intrinsic width exceeds the wrapper's available
  * space (including at higher browser-zoom levels — WCAG 1.4.10 Reflow at 400%
@@ -57,7 +59,8 @@ function buildAriaLabel(table) {
     }
     return "Scrollable table";
 }
-const TABLE_SPEC = {
+/** Internal: shared with the region tracker, not re-exported. */
+export const TABLE_SPEC = {
     selector: "table",
     wrapperTag: "div",
     wrapperClass: "pie-table-scroll",

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

@@ -55,6 +55,19 @@ export interface WrapOverwideOptions {
  * the layout class this pass would have given it.
  */
 export declare function wrapOverwideInElement(root: Element, spec: OverwideWrapSpec, options?: WrapOverwideOptions): number;
+/**
+ * Makes each wrapper a named, focusable region while its content overflows it
+ * horizontally, and a plain container otherwise.
+ *
+ * A wrapper is built as a region, because a wrapper that scrolls must be
+ * reachable by keyboard (WCAG 2.1.1) and markup wrapped off-document cannot be
+ * measured. Most never scroll: a table that fits its column, a drag tile, a
+ * layout table. Left as regions they add a tab stop and a landmark each, so the
+ * live player measures every wrapper and keeps the region only where there is
+ * something to scroll. Measurements are read for every wrapper before the first
+ * write. A wrapper holding focus keeps its region, so a sync never drops focus.
+ */
+export declare function syncOverwideRegions(wrappers: Iterable<Element>, spec: OverwideWrapSpec): void;
 /**
  * String-in / string-out wrapping, for the post-sanitization step.
  *

package/dist/security/wrap-overwide.js

@@ -40,6 +40,29 @@ function isInsidePieCustomElement(node, root) {
     }
     return false;
 }
+const VERTICAL_MARGINS = ["margin-top", "margin-bottom"];
+/**
+ * Moves the node's inline vertical margins onto its wrapper. The wrapper clips
+ * vertically — `overflow-x: auto` forces `overflow-y` off `visible` — so a
+ * negative margin left on the node pulls its edge into the clipped band, and
+ * the wrapper's own block formatting context stops a positive one collapsing
+ * with its neighbours. On the wrapper, both lay out as they did unwrapped.
+ * Horizontal margins stay: `margin: 0 auto` centres the node inside the wrapper.
+ */
+function liftVerticalMargins(node, wrapper) {
+    const style = node.style;
+    if (!style)
+        return;
+    for (const property of VERTICAL_MARGINS) {
+        const value = style.getPropertyValue(property);
+        if (!value)
+            continue;
+        wrapper.style.setProperty(property, value, style.getPropertyPriority(property));
+        style.removeProperty(property);
+    }
+    if (!style.length)
+        node.removeAttribute("style");
+}
 /**
  * Wrappers whose layout class was read from the live cascade. A wrapper built
  * off-document saw only its node's inline style, so the first live pass to meet
@@ -109,17 +132,59 @@ export function wrapOverwideInElement(root, spec, options = {}) {
         wrapper.className = layoutClass
             ? `${spec.wrapperClass} ${layoutClass}`
             : spec.wrapperClass;
-        wrapper.setAttribute("tabindex", "0");
-        wrapper.setAttribute("role", "region");
-        wrapper.setAttribute("aria-label", spec.buildAriaLabel(node));
+        setRegion(wrapper, node, spec);
         if (readsLiveLayout)
             liveLayoutRead.add(wrapper);
+        liftVerticalMargins(node, wrapper);
         parent.insertBefore(wrapper, node);
         wrapper.appendChild(node);
         wrapped += 1;
     }
     return wrapped;
 }
+function setRegion(wrapper, node, spec) {
+    wrapper.setAttribute("tabindex", "0");
+    wrapper.setAttribute("role", "region");
+    wrapper.setAttribute("aria-label", spec.buildAriaLabel(node));
+}
+function clearRegion(wrapper) {
+    wrapper.removeAttribute("tabindex");
+    wrapper.removeAttribute("role");
+    wrapper.removeAttribute("aria-label");
+}
+/**
+ * Makes each wrapper a named, focusable region while its content overflows it
+ * horizontally, and a plain container otherwise.
+ *
+ * A wrapper is built as a region, because a wrapper that scrolls must be
+ * reachable by keyboard (WCAG 2.1.1) and markup wrapped off-document cannot be
+ * measured. Most never scroll: a table that fits its column, a drag tile, a
+ * layout table. Left as regions they add a tab stop and a landmark each, so the
+ * live player measures every wrapper and keeps the region only where there is
+ * something to scroll. Measurements are read for every wrapper before the first
+ * write. A wrapper holding focus keeps its region, so a sync never drops focus.
+ */
+export function syncOverwideRegions(wrappers, spec) {
+    const measured = [];
+    for (const wrapper of wrappers) {
+        if (!wrapper.isConnected)
+            continue;
+        if (!wrapper.classList.contains(spec.wrapperClass))
+            continue;
+        measured.push([wrapper, wrapper.scrollWidth > wrapper.clientWidth]);
+    }
+    for (const [wrapper, scrolls] of measured) {
+        const node = wrapper.firstElementChild;
+        if (scrolls && node?.matches(spec.selector))
+            setRegion(wrapper, node, spec);
+        else if (!scrolls && !isFocused(wrapper))
+            clearRegion(wrapper);
+    }
+}
+function isFocused(element) {
+    const root = element.getRootNode();
+    return root.activeElement === element;
+}
 /**
  * String-in / string-out wrapping, for the post-sanitization step.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@pie-players/pie-players-shared",
-	"version": "1.0.0-beta.2",
+	"version": "1.0.0-beta.3",
 	"type": "module",
 	"description": "Shared runtime + UI utilities for PIE players",
 	"license": "MIT",