@pie-players/pie-players-shared 1.0.0-beta.7 → 1.0.0-beta.8

package/dist/types/interchange.d.ts

@@ -1,7 +1,9 @@
 /**
- * Language-variant interchange types (PIE-1393). Backends and authoring tools
- * exchange them; no player reads `AdaptationLink` or `LanguagePolicy`.
+ * Interchange types: backends and authoring tools exchange them, and no player
+ * reads them. Their tier is listed on the content-model page.
  *
+ * Language variants (PIE-1393): no player reads `AdaptationLink` or
+ * `LanguagePolicy`.
  * A language variant is its own item or passage version that declares
  * `language` and, when it is a translation, `isAdaptationOf`. Its family is
  * `isAdaptationOf.baseId ?? baseId`.
@@ -40,8 +42,13 @@ export interface LanguagePolicy {
      */
     staleness: "serve" | "require-current";
 }
-/** Why the served content differs from what was requested. */
-export type ContentSubstitution = "fallback" | "stale";
+/**
+ * Why the served content differs from what was requested: `"fallback"`, not
+ * in a requested language; `"variety"`, in another variety of a requested
+ * language, such as `es-ES` for `es-MX`; `"stale"`, a translation of an older
+ * source release.
+ */
+export type ContentSubstitution = "fallback" | "stale" | "variety";
 /** The content version a backend served, and the language it served it in. */
 export interface ServedContentIdentity {
     baseId: string;
@@ -52,3 +59,58 @@ export interface ServedContentIdentity {
     servedLanguage?: string;
     substitution?: ContentSubstitution;
 }
+/**
+ * One curriculum standard, skill or competency the content is aligned to
+ * (PIE-1381). QTI 3 Curriculum Standards Metadata (CSM 1.1), one entry per
+ * `labelledGUID`. Content records direct links only; a framework provider
+ * resolves parents, crosswalks and successors on read.
+ */
+export interface CurriculumStandard {
+    /**
+     * CSM `curriculumStandardsMetadata@providerId`: who issued `guid`, from the
+     * provider-id registry on the content-model page, or a host value. Absent
+     * means `"AB"` (Academic Benchmarks).
+     */
+    providerId?: string;
+    /**
+     * CSM `labelledGUID/GUID`, as the provider issued it. Stored with its case
+     * and compared case-insensitively.
+     */
+    guid: string;
+    /** CSM `labelledGUID/caseItemURI`, for a CASE framework item. */
+    caseItemURI?: string;
+    /** CSM `labelledGUID/label`: a display code. Never a key. */
+    label?: string;
+    /** LOM classification purpose. Absent means `"educational objective"`. */
+    purpose?: "educational objective" | "prerequisite" | (string & {});
+    /** The record's main standard for this provider. At most one per `providerId`. */
+    primary?: boolean;
+    /** How the link was made. */
+    provenance?: "authored" | "derived" | "imported";
+    /**
+     * For a derived link: the link it was generated from. An absent
+     * `providerId` means `"AB"`.
+     */
+    derivedFrom?: {
+        providerId?: string;
+        guid: string;
+    };
+}
+/**
+ * A cognitive-complexity classification of the content (PIE-1381). LOM
+ * classification purpose "skill level".
+ */
+export interface SkillLevel {
+    /**
+     * LOM `taxonPath/source`: `"webb-dok"`, `"blooms-revised"`,
+     * `"blooms-original"`, or a host taxonomy.
+     */
+    source: string;
+    /**
+     * LOM `taxon/id`: `"1"` to `"4"` for `webb-dok`; `"remember"` to `"create"`
+     * for `blooms-revised`.
+     */
+    id: string;
+    /** PIE extension: the author's justification. */
+    rationale?: string;
+}

package/dist/ui/fontawesome.d.ts

@@ -0,0 +1,51 @@
+/**
+ * FontAwesome for `<nds-icon-button>`, which renders its glyph as
+ * `<i class="fa-light fa-${name}">` and ships no font of its own.
+ *
+ * FontAwesome comes from the host page when it links any FA stylesheet.
+ * Otherwise `ensureFontAwesome` adds FA Free from the ESM CDN the item player's
+ * `loaderOptions` name, jsDelivr by default. Pro is never fetched from here:
+ * ui.renaissance.com serves its font files to Renaissance origins only, so a
+ * host that licenses it links it itself, as section-demos does through its dev
+ * proxy.
+ *
+ * `fa-light` is a weight only Pro carries. Free has no `.fa-light` rule and its
+ * Regular font lacks most toolbar glyphs, so without Pro `applyNdsGlyphVariant`
+ * renders every glyph in Solid, the one Free weight that has them all.
+ *
+ * Roboto comes from the vendored button: its connectedCallback links
+ * ui.renaissance.com's Roboto unless the page links a stylesheet whose URL
+ * contains `Roboto`.
+ */
+export type NdsGlyphVariant = "fa-light" | "fa-regular" | "fa-solid";
+/**
+ * Adds FA Free to `<head>` unless the page already links a FontAwesome
+ * stylesheet. Appending Free after a host's Pro would override Pro's
+ * `.fa-regular` / `.fa-solid` font-family rules page-wide.
+ *
+ * A stylesheet that fails to load stays in `<head>` marked
+ * `data-pie-load-failed`: no later call requests it again, and no shadow root
+ * copies it.
+ */
+export declare function ensureFontAwesome(loaderOptions: {
+    esmCdnUrl?: unknown;
+    esmCdnProvider?: unknown;
+} | null | undefined): void;
+/**
+ * Copies the page's FontAwesome `<link>`s into the shadow root `node` renders
+ * in, since `<head>` stylesheets do not cross a shadow boundary. Does nothing
+ * when `node` is in the document tree, and runs once per shadow root.
+ *
+ * A stylesheet still loading is copied once it loads, so the copy comes from
+ * the cache; one that fails is not copied, since every copy would request it
+ * again. Chromium gives a link a `sheet` even when its load fails, so a failed
+ * one is known by its mark.
+ */
+export declare function installFontAwesomeInShadow(node: Node): void;
+/**
+ * Renders the `fa-light` glyphs inside `button` in `preferred` when the page
+ * links Pro, and in Solid otherwise. Re-applies whenever Lit renders or
+ * rewrites the icon's class; the class edit removes `fa-light`, so the
+ * callback it triggers is a no-op. Returns the observer's disconnect.
+ */
+export declare function applyNdsGlyphVariant(button: HTMLElement, preferred: NdsGlyphVariant): () => void;

package/dist/ui/fontawesome.js

@@ -0,0 +1,122 @@
+/**
+ * FontAwesome for `<nds-icon-button>`, which renders its glyph as
+ * `<i class="fa-light fa-${name}">` and ships no font of its own.
+ *
+ * FontAwesome comes from the host page when it links any FA stylesheet.
+ * Otherwise `ensureFontAwesome` adds FA Free from the ESM CDN the item player's
+ * `loaderOptions` name, jsDelivr by default. Pro is never fetched from here:
+ * ui.renaissance.com serves its font files to Renaissance origins only, so a
+ * host that licenses it links it itself, as section-demos does through its dev
+ * proxy.
+ *
+ * `fa-light` is a weight only Pro carries. Free has no `.fa-light` rule and its
+ * Regular font lacks most toolbar glyphs, so without Pro `applyNdsGlyphVariant`
+ * renders every glyph in Solid, the one Free weight that has them all.
+ *
+ * Roboto comes from the vendored button: its connectedCallback links
+ * ui.renaissance.com's Roboto unless the page links a stylesheet whose URL
+ * contains `Roboto`.
+ */
+import { resolveEsmPackageFileUrl } from "../loaders/esm-adapter.js";
+/** The one FA Free build the players add; `<package>@<version>/<path>`. */
+const FONTAWESOME_FREE_FILE = "@fortawesome/fontawesome-free@6.5.2/css/all.min.css";
+// Matches any FA stylesheet the host page links: `fontawesome.min.css`,
+// `font-awesome.css`, a `/_fa-pro/` proxy, `fontawesome-free@…`.
+const FA_HREF_PATTERN = /font.?awesome|fa-?pro/i;
+const FA_FREE_HREF_PATTERN = /fontawesome-free/i;
+const documentStylesheetLinks = () => Array.from(document.querySelectorAll('link[rel="stylesheet"][href]'));
+const documentFontAwesomeLinks = () => documentStylesheetLinks().filter((link) => FA_HREF_PATTERN.test(link.href));
+/** Whether the page links a FontAwesome build other than Free. */
+const pageLinksFontAwesomePro = () => documentFontAwesomeLinks().some((link) => !FA_FREE_HREF_PATTERN.test(link.href));
+/**
+ * Adds FA Free to `<head>` unless the page already links a FontAwesome
+ * stylesheet. Appending Free after a host's Pro would override Pro's
+ * `.fa-regular` / `.fa-solid` font-family rules page-wide.
+ *
+ * A stylesheet that fails to load stays in `<head>` marked
+ * `data-pie-load-failed`: no later call requests it again, and no shadow root
+ * copies it.
+ */
+export function ensureFontAwesome(loaderOptions) {
+    if (typeof document === "undefined")
+        return;
+    if (documentFontAwesomeLinks().length > 0)
+        return;
+    const href = resolveEsmPackageFileUrl(loaderOptions, FONTAWESOME_FREE_FILE);
+    const link = document.createElement("link");
+    link.rel = "stylesheet";
+    link.href = href;
+    link.addEventListener("error", () => {
+        link.dataset.pieLoadFailed = "";
+    }, { once: true });
+    document.head.appendChild(link);
+}
+const mirroredShadowRoots = new WeakSet();
+/**
+ * Copies the page's FontAwesome `<link>`s into the shadow root `node` renders
+ * in, since `<head>` stylesheets do not cross a shadow boundary. Does nothing
+ * when `node` is in the document tree, and runs once per shadow root.
+ *
+ * A stylesheet still loading is copied once it loads, so the copy comes from
+ * the cache; one that fails is not copied, since every copy would request it
+ * again. Chromium gives a link a `sheet` even when its load fails, so a failed
+ * one is known by its mark.
+ */
+export function installFontAwesomeInShadow(node) {
+    const shadow = node.getRootNode();
+    if (!(shadow instanceof ShadowRoot) || mirroredShadowRoots.has(shadow)) {
+        return;
+    }
+    mirroredShadowRoots.add(shadow);
+    const appendLink = (href) => {
+        const present = Array.from(shadow.querySelectorAll('link[rel="stylesheet"]')).some((link) => link.href === href);
+        if (!href || present)
+            return;
+        const link = document.createElement("link");
+        link.rel = "stylesheet";
+        link.href = href;
+        shadow.appendChild(link);
+    };
+    for (const link of documentFontAwesomeLinks()) {
+        if ("pieLoadFailed" in link.dataset)
+            continue;
+        if (link.sheet) {
+            appendLink(link.href);
+            continue;
+        }
+        const settle = (event) => {
+            link.removeEventListener("load", settle);
+            link.removeEventListener("error", settle);
+            if (event.type === "load")
+                appendLink(link.href);
+        };
+        link.addEventListener("load", settle);
+        link.addEventListener("error", settle);
+    }
+}
+/**
+ * Renders the `fa-light` glyphs inside `button` in `preferred` when the page
+ * links Pro, and in Solid otherwise. Re-applies whenever Lit renders or
+ * rewrites the icon's class; the class edit removes `fa-light`, so the
+ * callback it triggers is a no-op. Returns the observer's disconnect.
+ */
+export function applyNdsGlyphVariant(button, preferred) {
+    const variant = pageLinksFontAwesomePro() ? preferred : "fa-solid";
+    if (variant === "fa-light")
+        return () => { };
+    const apply = () => {
+        for (const icon of button.querySelectorAll("i.fa-light")) {
+            icon.classList.remove("fa-light");
+            icon.classList.add(variant);
+        }
+    };
+    apply();
+    const observer = new MutationObserver(apply);
+    observer.observe(button, {
+        childList: true,
+        subtree: true,
+        attributes: true,
+        attributeFilter: ["class"],
+    });
+    return () => observer.disconnect();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@pie-players/pie-players-shared",
-	"version": "1.0.0-beta.7",
+	"version": "1.0.0-beta.8",
 	"type": "module",
 	"description": "Shared runtime + UI utilities for PIE players",
 	"license": "MIT",
@@ -29,6 +29,10 @@
 			"types": "./dist/security/index.d.ts",
 			"import": "./dist/security/index.js"
 		},
+		"./security/private-hosts": {
+			"types": "./dist/security/private-hosts.d.ts",
+			"import": "./dist/security/private-hosts.js"
+		},
 		"./object": {
 			"types": "./dist/object/index.d.ts",
 			"import": "./dist/object/index.js"
@@ -97,6 +101,10 @@
 			"types": "./dist/ui/content-styles.d.ts",
 			"import": "./dist/ui/content-styles.js"
 		},
+		"./ui/fontawesome": {
+			"types": "./dist/ui/fontawesome.d.ts",
+			"import": "./dist/ui/fontawesome.js"
+		},
 		"./tools/term-lookup": {
 			"types": "./dist/tools/term-lookup.d.ts",
 			"import": "./dist/tools/term-lookup.js"
@@ -109,6 +117,7 @@
 		"@pie-element/shared-utils": "0.1.6",
 		"@pie-lib/math-rendering-module": "6.0.0",
 		"dompurify": "^3.4.17",
+		"ipaddr.js": "^2.5.0",
 		"semver": "^7.8.5"
 	},
 	"scripts": {
@@ -122,7 +131,7 @@
 		"scan-hardcoded": "bun run src/i18n/scripts/scan-hardcoded.ts"
 	},
 	"devDependencies": {
-		"@biomejs/biome": "^2.6.2",
+		"@biomejs/biome": "^2.6.4",
 		"@happy-dom/global-registrator": "^21.0.4",
 		"@pie-element/shared-math-rendering-mathjax": "0.1.8",
 		"@playwright/test": "^1.64.1",
@@ -130,7 +139,7 @@
 		"es-module-shims": "^2.8.4",
 		"esbuild": "^0.28.2",
 		"glob": "^13.0.0",
-		"svelte": "^5.57.2",
+		"svelte": "^5.57.3",
 		"svelte-check": "^4.7.6",
 		"typescript": "^5.9.3"
 	},