@pie-players/pie-players-shared 1.0.0-beta.0 → 1.0.0-beta.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (122) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +18 -17
  3. package/dist/THIRD-PARTY-LICENSES.txt +51 -0
  4. package/dist/components/vendor/nds/README.md +43 -5
  5. package/dist/components/vendor/nds/nds-icon-button.d.ts +2 -2
  6. package/dist/components/vendor/nds/nds-icon-button.js +2 -2
  7. package/dist/i18n/catalogs.d.ts +25 -13
  8. package/dist/i18n/catalogs.js +30 -22
  9. package/dist/i18n/content-language.d.ts +77 -0
  10. package/dist/i18n/content-language.js +129 -0
  11. package/dist/i18n/index.d.ts +7 -2
  12. package/dist/i18n/index.js +5 -2
  13. package/dist/i18n/language-tags.d.ts +3 -55
  14. package/dist/i18n/language-tags.js +3 -90
  15. package/dist/i18n/locale-load-error.d.ts +35 -0
  16. package/dist/i18n/locale-load-error.js +30 -0
  17. package/dist/i18n/messages/en-US.d.ts +151 -7
  18. package/dist/i18n/messages/en-US.js +168 -7
  19. package/dist/i18n/provider.d.ts +122 -18
  20. package/dist/i18n/provider.js +315 -133
  21. package/dist/i18n/pseudo.d.ts +34 -0
  22. package/dist/i18n/pseudo.js +106 -0
  23. package/dist/i18n/types.d.ts +19 -3
  24. package/dist/index.d.ts +16 -20
  25. package/dist/index.js +19 -19
  26. package/dist/instrumentation/providers/CompositeInstrumentationProvider.js +2 -1
  27. package/dist/item-session-control/index.d.ts +16 -0
  28. package/dist/item-session-control/index.js +5 -0
  29. package/dist/{formative → item-session-control}/mastery.d.ts +5 -5
  30. package/dist/{formative → item-session-control}/mastery.js +3 -3
  31. package/dist/{formative → item-session-control}/outcome.d.ts +3 -3
  32. package/dist/{formative → item-session-control}/outcome.js +2 -2
  33. package/dist/{formative → item-session-control}/policy.d.ts +11 -11
  34. package/dist/{formative → item-session-control}/policy.js +12 -12
  35. package/dist/item-session-control/session.d.ts +19 -0
  36. package/dist/{formative → item-session-control}/session.js +12 -12
  37. package/dist/{formative → item-session-control}/state.d.ts +26 -26
  38. package/dist/{formative → item-session-control}/state.js +13 -13
  39. package/dist/{formative → item-session-control}/types.d.ts +38 -40
  40. package/dist/{formative → item-session-control}/types.js +2 -2
  41. package/dist/loaders/ElementLoader.d.ts +1 -1
  42. package/dist/loaders/element-loader.d.ts +4 -1
  43. package/dist/loaders/element-loader.js +74 -21
  44. package/dist/loaders/element-package-spec.d.ts +16 -0
  45. package/dist/loaders/element-package-spec.js +30 -0
  46. package/dist/loaders/esm-adapter.d.ts +12 -1
  47. package/dist/loaders/esm-adapter.js +113 -19
  48. package/dist/loaders/iife-adapter.d.ts +7 -0
  49. package/dist/loaders/iife-adapter.js +1 -1
  50. package/dist/loaders/index.d.ts +2 -1
  51. package/dist/loaders/index.js +2 -1
  52. package/dist/loaders/preloaded-registration.d.ts +18 -6
  53. package/dist/loaders/preloaded-registration.js +44 -9
  54. package/dist/object/index.d.ts +4 -1
  55. package/dist/object/index.js +8 -1
  56. package/dist/pie/config.d.ts +8 -0
  57. package/dist/pie/config.js +32 -1
  58. package/dist/pie/index.d.ts +2 -0
  59. package/dist/pie/index.js +1 -0
  60. package/dist/pie/math-rendering.d.ts +13 -1
  61. package/dist/pie/math-rendering.js +54 -1
  62. package/dist/pie/updates.d.ts +4 -1
  63. package/dist/pie/updates.js +21 -5
  64. package/dist/pie/versioned-tag.d.ts +10 -0
  65. package/dist/pie/versioned-tag.js +27 -0
  66. package/dist/promise/index.d.ts +10 -0
  67. package/dist/promise/index.js +16 -0
  68. package/dist/security/overwide-regions.js +65 -0
  69. package/dist/security/private-hosts.d.ts +27 -0
  70. package/dist/security/private-hosts.js +85 -0
  71. package/dist/security/validate-style-url.js +2 -2
  72. package/dist/security/wrap-overwide-images.d.ts +6 -2
  73. package/dist/security/wrap-overwide-images.js +5 -2
  74. package/dist/security/wrap-overwide-tables.d.ts +6 -2
  75. package/dist/security/wrap-overwide-tables.js +5 -2
  76. package/dist/security/wrap-overwide.d.ts +13 -0
  77. package/dist/security/wrap-overwide.js +68 -3
  78. package/dist/timed-media/index.d.ts +1 -1
  79. package/dist/timed-media/index.js +1 -1
  80. package/dist/timed-media/policy.d.ts +2 -2
  81. package/dist/timed-media/policy.js +2 -2
  82. package/dist/timed-media/session.d.ts +1 -1
  83. package/dist/timed-media/session.js +1 -1
  84. package/dist/timed-media/types.d.ts +11 -11
  85. package/dist/tools/term-lookup.d.ts +15 -0
  86. package/dist/tools/term-lookup.js +16 -0
  87. package/dist/types/index.d.ts +127 -47
  88. package/dist/types/interchange.d.ts +116 -0
  89. package/dist/types/interchange.js +1 -0
  90. package/dist/ui/content-styles-entry.d.ts +1 -0
  91. package/dist/ui/content-styles-entry.js +2 -0
  92. package/dist/ui/content-styles.d.ts +24 -3
  93. package/dist/ui/content-styles.js +114 -3
  94. package/dist/ui/focus-trap.d.ts +12 -0
  95. package/dist/ui/focus-trap.js +41 -1
  96. package/dist/ui/fontawesome.d.ts +51 -0
  97. package/dist/ui/fontawesome.js +122 -0
  98. package/dist/ui/ime.d.ts +6 -0
  99. package/dist/ui/ime.js +10 -0
  100. package/dist/ui/overlay-containment.d.ts +13 -0
  101. package/dist/ui/overlay-containment.js +23 -0
  102. package/dist/ui/overlay-placement.d.ts +28 -0
  103. package/dist/ui/overlay-placement.js +17 -2
  104. package/package.json +72 -36
  105. package/dist/formative/index.d.ts +0 -16
  106. package/dist/formative/index.js +0 -5
  107. package/dist/formative/session.d.ts +0 -19
  108. package/dist/i18n/messages/nl-NL.d.ts +0 -529
  109. package/dist/i18n/messages/nl-NL.js +0 -529
  110. package/dist/instrumentation/new-relic-agent.d.ts +0 -20
  111. package/dist/loaders/module-shim.d.ts +0 -12
  112. package/dist/pie/authoring-tag.d.ts +0 -6
  113. package/dist/pie/configure-initialization.d.ts +0 -21
  114. package/dist/pie/correct-response-env.d.ts +0 -3
  115. package/dist/pie/element-announcements.d.ts +0 -39
  116. package/dist/pie/elements-rendered.d.ts +0 -23
  117. package/dist/pie/initialize-element.d.ts +0 -26
  118. package/dist/pie/markup-math.d.ts +0 -20
  119. package/dist/pie/resource-monitor.d.ts +0 -217
  120. package/dist/security/sanitize-forbidden-lists.d.ts +0 -8
  121. package/dist/ui/pointer-rotate.d.ts +0 -29
  122. package/dist/ui/safe-storage.d.ts +0 -2
@@ -8,6 +8,7 @@
8
8
  */
9
9
  /// <reference path="../shims.d.ts" />
10
10
  import { createPieLogger, isGlobalDebugEnabled } from "./logger.js";
11
+ import { pageMathAssetRoot } from "./math-assets.js";
11
12
  const GLOBAL_KEY = "@pie-lib/math-rendering";
12
13
  const GLOBAL_DLL_KEY = "_dll_pie_lib__math_rendering";
13
14
  // Every copy of @pie-lib/math-rendering on a page typesets through the MathJax
@@ -15,6 +16,52 @@ const GLOBAL_DLL_KEY = "_dll_pie_lib__math_rendering";
15
16
  const SHARED_INSTANCE_KEY = "@pie-lib/math-rendering@2";
16
17
  let initPromise = null;
17
18
  const logger = createPieLogger("math-rendering", () => isGlobalDebugEnabled());
19
+ /**
20
+ * The speech-rule-engine version the default renderer bundles, whose rules it
21
+ * loads from `speech-rule-engine@<version>/lib/mathmaps` under an npm root. A
22
+ * test pins it to the module.
23
+ * @internal
24
+ */
25
+ export const DEFAULT_RENDERER_SRE_VERSION = "4.1.2";
26
+ const SRE_FEATURE_KEY = "SREfeature";
27
+ const pageNamesSpeechRules = () => {
28
+ const feature = window[SRE_FEATURE_KEY];
29
+ if (feature && typeof feature === "object" && feature.json)
30
+ return true;
31
+ return Array.from(document.querySelectorAll('script[type="text/x-sre-config"]')).some((block) => {
32
+ try {
33
+ return !!JSON.parse(block.textContent || "")?.json;
34
+ }
35
+ catch {
36
+ return false;
37
+ }
38
+ });
39
+ };
40
+ /**
41
+ * Points the module's speech-rule-engine at the rules under `root` and returns
42
+ * the undo. SRE reads `SREfeature` as it sets up, synchronously while the
43
+ * module evaluates, and its later setups keep the path, so the global is
44
+ * restored afterwards: another copy of SRE on the page, as a legacy bundle
45
+ * carries, keeps the rules of its own version.
46
+ */
47
+ const pointSpeechRulesAt = (root) => {
48
+ if (!root || typeof document === "undefined" || pageNamesSpeechRules()) {
49
+ return () => { };
50
+ }
51
+ const host = window;
52
+ const had = Object.hasOwn(host, SRE_FEATURE_KEY);
53
+ const previous = host[SRE_FEATURE_KEY];
54
+ host[SRE_FEATURE_KEY] = {
55
+ ...(previous && typeof previous === "object" ? previous : {}),
56
+ json: `${root.replace(/\/+$/, "")}/speech-rule-engine@${DEFAULT_RENDERER_SRE_VERSION}/lib/mathmaps`,
57
+ };
58
+ return () => {
59
+ if (had)
60
+ host[SRE_FEATURE_KEY] = previous;
61
+ else
62
+ delete host[SRE_FEATURE_KEY];
63
+ };
64
+ };
18
65
  /**
19
66
  * The page's renderer: the one `initializeMathRendering` installed, or a
20
67
  * host's. IIFE elements render with it, and so do ESM elements when the page
@@ -66,6 +113,8 @@ const createSharedInstance = (renderer) => {
66
113
  * - window["@pie-lib/math-rendering"] (standard key)
67
114
  * - window["_dll_pie_lib__math_rendering"] (SystemJS/DLL key for IIFE bundles)
68
115
  *
116
+ * The first call installs the renderer for the page, so its `options` apply.
117
+ *
69
118
  * @example
70
119
  * ```typescript
71
120
  * // Default MathJax
@@ -76,7 +125,7 @@ const createSharedInstance = (renderer) => {
76
125
  * await initializeMathRendering();
77
126
  * ```
78
127
  */
79
- export async function initializeMathRendering() {
128
+ export async function initializeMathRendering(options = {}) {
80
129
  // Only run in browser
81
130
  if (typeof window === "undefined") {
82
131
  return;
@@ -90,6 +139,7 @@ export async function initializeMathRendering() {
90
139
  return;
91
140
  }
92
141
  initPromise = (async () => {
142
+ const restoreSpeechRules = pointSpeechRulesAt(pageMathAssetRoot() ?? options.assetRoot);
93
143
  try {
94
144
  // The package has no exports map, so the file is named in full for
95
145
  // resolvers that do not complete a directory, such as webpack's
@@ -112,6 +162,9 @@ export async function initializeMathRendering() {
112
162
  logger.error("Failed to initialize math rendering:", error);
113
163
  throw error;
114
164
  }
165
+ finally {
166
+ restoreSpeechRules();
167
+ }
115
168
  })();
116
169
  try {
117
170
  await initPromise;
@@ -10,7 +10,10 @@ import type { BundleType, UpdatePieElementOptions } from "./types.js";
10
10
  */
11
11
  export declare const updatePieElementWithRef: (el: Element, opts: UpdatePieElementOptions) => Promise<void>;
12
12
  /**
13
- * Update a PIE element by name (finds all matching elements in DOM)
13
+ * Update a PIE element by name (finds all matching elements in DOM).
14
+ *
15
+ * Updates every matching element even when some fail, then rejects with one
16
+ * aggregated error naming each failed element.
14
17
  */
15
18
  export declare const updatePieElement: (elName: string, opts: UpdatePieElementOptions) => Promise<void>;
16
19
  /**
@@ -4,6 +4,7 @@
4
4
  * Functions for updating PIE elements with new models, sessions, and env.
5
5
  */
6
6
  import { mergeObjectsIgnoringNullUndefined } from "../object/index.js";
7
+ import { settleAll } from "../promise/index.js";
7
8
  import { createPieLogger, isGlobalDebugEnabled } from "./logger.js";
8
9
  import { findPieController } from "./scoring.js";
9
10
  import { defaultPieElementOptions } from "./types.js";
@@ -148,7 +149,7 @@ const updateSinglePieElement = async (pieElement, controllerLookupTag, options,
148
149
  const model = config.models?.find((m) => m.id === pieElement.id);
149
150
  if (!model) {
150
151
  logger.error(`${logContext} Model not found for`, controllerLookupTag);
151
- throw new Error(`model not found for ${controllerLookupTag}`);
152
+ throw new Error(`model not found for ${controllerLookupTag}#${pieElement.id}`);
152
153
  }
153
154
  const elementSession = findOrAddSession(session, model.id, model.element);
154
155
  // Always attach event listeners (don't skip them for no-controller case)
@@ -216,9 +217,12 @@ export const updatePieElementWithRef = (el, opts) => {
216
217
  return updateSinglePieElement(pieElement, elName, options, "[updatePieElementWithRef]");
217
218
  };
218
219
  /**
219
- * Update a PIE element by name (finds all matching elements in DOM)
220
+ * Update a PIE element by name (finds all matching elements in DOM).
221
+ *
222
+ * Updates every matching element even when some fail, then rejects with one
223
+ * aggregated error naming each failed element.
220
224
  */
221
- export const updatePieElement = (elName, opts) => {
225
+ export const updatePieElement = async (elName, opts) => {
222
226
  const options = resolveAndValidateUpdateOptions(opts);
223
227
  const { container } = mergeObjectsIgnoringNullUndefined(defaultPieElementOptions, opts);
224
228
  // Use container for scoped query or fallback to document for global query
@@ -226,9 +230,21 @@ export const updatePieElement = (elName, opts) => {
226
230
  const pieElements = searchRoot.querySelectorAll(elName);
227
231
  if (!pieElements || pieElements.length === 0) {
228
232
  logger.debug(`no elements found for ${elName}`);
229
- return Promise.resolve();
233
+ return;
234
+ }
235
+ const results = await settleAll(Array.from(pieElements, (el) => updateSinglePieElement(el, elName, options, "[updatePieElement]")));
236
+ const failures = results.filter((result) => result.status === "rejected");
237
+ if (failures.length === 0)
238
+ return;
239
+ if (failures.length === 1) {
240
+ const [failure] = failures;
241
+ if (failure?.reason instanceof Error)
242
+ throw failure.reason;
230
243
  }
231
- return Promise.all(Array.from(pieElements, (el) => updateSinglePieElement(el, elName, options, "[updatePieElement]"))).then(() => undefined);
244
+ const reasons = failures.map((failure) => failure.reason instanceof Error
245
+ ? failure.reason.message
246
+ : String(failure.reason));
247
+ throw new Error(`${failures.length} of ${pieElements.length} elements failed to update: ${reasons.join(" | ")}`);
232
248
  };
233
249
  /**
234
250
  * Update all PIE elements in a config
@@ -17,3 +17,13 @@ export declare function parseVersionedTagName(tagName: string): {
17
17
  export declare function toPackageVersionedTag(tagName: string, packageSpec: string, options?: {
18
18
  preserveUnversionedTag?: boolean;
19
19
  }): string;
20
+ /**
21
+ * The tags a player can define an authored element under, most specific first:
22
+ * the versioned tag for its package spec, aligned to the page's preloaded
23
+ * registration, then the authored tag, which an unversioned spec keeps. With no
24
+ * spec the authored tag is the only candidate.
25
+ *
26
+ * For code that looks an element's class up by tag without rendering it, such as
27
+ * reading what the class declares before the element is in the DOM.
28
+ */
29
+ export declare function runtimeElementTags(tagName: string, packageSpec?: string): string[];
@@ -1,3 +1,4 @@
1
+ import { alignPreloadedElementVersions } from "../loaders/preloaded-alignment.js";
1
2
  import { parsePackageName } from "./utils.js";
2
3
  const VERSION_DELIMITER = "--version-";
3
4
  const TAG_VERSION_PATTERN = "[0-9A-Za-z-]+";
@@ -45,3 +46,29 @@ export function toPackageVersionedTag(tagName, packageSpec, options = {}) {
45
46
  // package versions at runtime, which requires updating the cloned runtime tag.
46
47
  return `${baseName}${VERSION_DELIMITER}${targetEncodedVersion}`;
47
48
  }
49
+ /**
50
+ * The tags a player can define an authored element under, most specific first:
51
+ * the versioned tag for its package spec, aligned to the page's preloaded
52
+ * registration, then the authored tag, which an unversioned spec keeps. With no
53
+ * spec the authored tag is the only candidate.
54
+ *
55
+ * For code that looks an element's class up by tag without rendering it, such as
56
+ * reading what the class declares before the element is in the DOM.
57
+ */
58
+ export function runtimeElementTags(tagName, packageSpec) {
59
+ if (!packageSpec)
60
+ return [tagName];
61
+ let versioned;
62
+ try {
63
+ const { elements } = alignPreloadedElementVersions({
64
+ elements: { [tagName]: packageSpec },
65
+ });
66
+ versioned = toPackageVersionedTag(tagName, elements[tagName], {
67
+ preserveUnversionedTag: true,
68
+ });
69
+ }
70
+ catch {
71
+ return [tagName];
72
+ }
73
+ return versioned === tagName ? [tagName] : [versioned, tagName];
74
+ }
@@ -0,0 +1,10 @@
1
+ /**
2
+ * Waits for every value to settle and resolves with each outcome in input
3
+ * order, as the `allSettled` static does. Built on `Promise.all` and `then` alone:
4
+ * a host page can replace the global `Promise` with an implementation that
5
+ * predates `allSettled` (zone.js 0.9.1 does), so published code calls no
6
+ * `Promise` static beyond `all`, `race`, `resolve` and `reject`.
7
+ * `bun run check:bundle-safety` enforces that on every built bundle.
8
+ * @param values The promises or plain values to settle.
9
+ */
10
+ export declare const settleAll: <T>(values: Iterable<T | PromiseLike<T>>) => Promise<PromiseSettledResult<Awaited<T>>[]>;
@@ -0,0 +1,16 @@
1
+ /**
2
+ * Waits for every value to settle and resolves with each outcome in input
3
+ * order, as the `allSettled` static does. Built on `Promise.all` and `then` alone:
4
+ * a host page can replace the global `Promise` with an implementation that
5
+ * predates `allSettled` (zone.js 0.9.1 does), so published code calls no
6
+ * `Promise` static beyond `all`, `race`, `resolve` and `reject`.
7
+ * `bun run check:bundle-safety` enforces that on every built bundle.
8
+ * @param values The promises or plain values to settle.
9
+ */
10
+ export const settleAll = (values) => Promise.all(Array.from(values, (value) => Promise.resolve(value).then((result) => ({
11
+ status: "fulfilled",
12
+ value: result,
13
+ }), (reason) => ({
14
+ status: "rejected",
15
+ reason,
16
+ }))));
@@ -0,0 +1,65 @@
1
+ /**
2
+ * Keeps the image and table scroll wrappers under a live root in step with
3
+ * whether they scroll. See {@link syncOverwideRegions}.
4
+ *
5
+ * Overflow changes without any mutation: zoom and a resized column change the
6
+ * wrapper's width, an image load or a dropped drag tile changes its content's.
7
+ * A `ResizeObserver` on each wrapper and its content catches both, and its first
8
+ * delivery for a newly observed target is the initial sync. A wrapper that is
9
+ * not laid out measures zero and syncs as non-scrolling; showing it resizes it,
10
+ * which syncs it again.
11
+ *
12
+ * Without `ResizeObserver` nothing is synced, so every wrapper stays a region —
13
+ * the reachable default.
14
+ */
15
+ import { IMAGE_SPEC } from "./wrap-overwide-images.js";
16
+ import { TABLE_SPEC } from "./wrap-overwide-tables.js";
17
+ import { syncOverwideRegions } from "./wrap-overwide.js";
18
+ const SPECS = [IMAGE_SPEC, TABLE_SPEC];
19
+ const WRAPPER_SELECTOR = SPECS.map((spec) => `.${spec.wrapperClass}`).join(",");
20
+ export function createOverwideRegionTracker(root) {
21
+ if (typeof ResizeObserver === "undefined") {
22
+ return { track() { }, disconnect() { } };
23
+ }
24
+ // Wrapper to the content observed with it. Held strongly, as the observer
25
+ // holds its targets, so each `track()` releases wrappers that have left the
26
+ // document — an element re-rendering over its subtree drops them every time.
27
+ const observed = new Map();
28
+ const observer = new ResizeObserver((entries) => {
29
+ const wrappers = new Set();
30
+ for (const { target } of entries) {
31
+ const wrapper = target.matches(WRAPPER_SELECTOR)
32
+ ? target
33
+ : target.parentElement;
34
+ if (wrapper)
35
+ wrappers.add(wrapper);
36
+ }
37
+ for (const spec of SPECS)
38
+ syncOverwideRegions(wrappers, spec);
39
+ });
40
+ return {
41
+ track() {
42
+ for (const [wrapper, content] of observed) {
43
+ if (wrapper.isConnected)
44
+ continue;
45
+ observer.unobserve(wrapper);
46
+ if (content)
47
+ observer.unobserve(content);
48
+ observed.delete(wrapper);
49
+ }
50
+ for (const wrapper of Array.from(root.querySelectorAll(WRAPPER_SELECTOR))) {
51
+ if (observed.has(wrapper))
52
+ continue;
53
+ const content = wrapper.firstElementChild;
54
+ observed.set(wrapper, content);
55
+ observer.observe(wrapper);
56
+ if (content)
57
+ observer.observe(content);
58
+ }
59
+ },
60
+ disconnect() {
61
+ observer.disconnect();
62
+ observed.clear();
63
+ },
64
+ };
65
+ }
@@ -0,0 +1,27 @@
1
+ /**
2
+ * Hostname classification for a URL a server fetches on someone else's behalf,
3
+ * such as an SSML `<audio src>` a TTS provider will request or an asset URL an
4
+ * upstream service returns. Every such check reads this module, so no two
5
+ * copies of it can drift apart.
6
+ *
7
+ * IP literals are classified by `ipaddr.js`, whose ranges follow the IANA IPv4
8
+ * and IPv6 Special-Purpose Address Registries (RFC 6890). A host is private
9
+ * unless it is a public unicast address or a name: loopback, private, link-local,
10
+ * unique-local, carrier-grade NAT, multicast, broadcast, documentation and
11
+ * reserved ranges, and the IPv6 forms that embed an IPv4 address (NAT64, 6to4,
12
+ * Teredo), all count. `ipaddr.js` also reads the numeric IPv4 forms (`2130706433`,
13
+ * `0x7f000001`, `0177.0.0.1`) and unmaps IPv4-mapped IPv6.
14
+ *
15
+ * Only the literal is checked. A public name that resolves to a private address
16
+ * passes; guarding that takes a check of the resolved address at connect time.
17
+ *
18
+ * @module
19
+ */
20
+ /** Whether `hostname` is a cloud instance-metadata endpoint. */
21
+ export declare function isCloudMetadataHostname(hostname: string): boolean;
22
+ /**
23
+ * Whether `hostname` is anything other than a public unicast address or a
24
+ * public name: `localhost` and its subdomains (RFC 6761), or an IP literal in
25
+ * any special-purpose range.
26
+ */
27
+ export declare function isPrivateHostname(hostname: string): boolean;
@@ -0,0 +1,85 @@
1
+ /**
2
+ * Hostname classification for a URL a server fetches on someone else's behalf,
3
+ * such as an SSML `<audio src>` a TTS provider will request or an asset URL an
4
+ * upstream service returns. Every such check reads this module, so no two
5
+ * copies of it can drift apart.
6
+ *
7
+ * IP literals are classified by `ipaddr.js`, whose ranges follow the IANA IPv4
8
+ * and IPv6 Special-Purpose Address Registries (RFC 6890). A host is private
9
+ * unless it is a public unicast address or a name: loopback, private, link-local,
10
+ * unique-local, carrier-grade NAT, multicast, broadcast, documentation and
11
+ * reserved ranges, and the IPv6 forms that embed an IPv4 address (NAT64, 6to4,
12
+ * Teredo), all count. `ipaddr.js` also reads the numeric IPv4 forms (`2130706433`,
13
+ * `0x7f000001`, `0177.0.0.1`) and unmaps IPv4-mapped IPv6.
14
+ *
15
+ * Only the literal is checked. A public name that resolves to a private address
16
+ * passes; guarding that takes a check of the resolved address at connect time.
17
+ *
18
+ * @module
19
+ */
20
+ import ipaddr from "ipaddr.js";
21
+ /**
22
+ * Cloud instance-metadata hostnames. They hand out credentials. No registry
23
+ * lists them; each is the provider's documented name.
24
+ */
25
+ const CLOUD_METADATA_HOSTNAMES = new Set([
26
+ "metadata.google.internal",
27
+ "metadata.azure.internal",
28
+ "metadata.packet.net",
29
+ "metadata.oci.oraclecloud.com",
30
+ ]);
31
+ /** Cloud instance-metadata addresses: the link-local one most clouds use, and AWS's IPv6 one. */
32
+ const CLOUD_METADATA_ADDRESSES = ["169.254.169.254", "fd00:ec2::254"].map((address) => ipaddr.parse(address));
33
+ /** Lower-cased, without brackets or a trailing dot. */
34
+ function normalizeHostname(hostname) {
35
+ return hostname
36
+ .replace(/^\[|\]$/g, "")
37
+ .replace(/\.$/, "")
38
+ .toLowerCase();
39
+ }
40
+ /**
41
+ * The address `host` is a literal for, IPv4-mapped (`::ffff:a.b.c.d`) and
42
+ * IPv4-compatible (`::a.b.c.d`) IPv6 reduced to IPv4, or `null` for a name.
43
+ */
44
+ function parseAddress(host) {
45
+ if (!ipaddr.isValid(host))
46
+ return null;
47
+ const address = ipaddr.process(host);
48
+ if (address.kind() !== "ipv6")
49
+ return address;
50
+ // `ipaddr.js` classifies deprecated IPv4-compatible addresses as unicast;
51
+ // read the IPv4 address in their low 32 bits instead.
52
+ const { parts } = address;
53
+ const isIpv4Compatible = parts.slice(0, 6).every((part) => part === 0) &&
54
+ (parts[6] !== 0 || parts[7] > 1);
55
+ return isIpv4Compatible
56
+ ? new ipaddr.IPv4([
57
+ parts[6] >> 8,
58
+ parts[6] & 0xff,
59
+ parts[7] >> 8,
60
+ parts[7] & 0xff,
61
+ ])
62
+ : address;
63
+ }
64
+ /** Whether `hostname` is a cloud instance-metadata endpoint. */
65
+ export function isCloudMetadataHostname(hostname) {
66
+ const host = normalizeHostname(hostname);
67
+ if (CLOUD_METADATA_HOSTNAMES.has(host))
68
+ return true;
69
+ const address = parseAddress(host);
70
+ return (address !== null &&
71
+ CLOUD_METADATA_ADDRESSES.some((metadata) => metadata.kind() === address.kind() &&
72
+ metadata.toNormalizedString() === address.toNormalizedString()));
73
+ }
74
+ /**
75
+ * Whether `hostname` is anything other than a public unicast address or a
76
+ * public name: `localhost` and its subdomains (RFC 6761), or an IP literal in
77
+ * any special-purpose range.
78
+ */
79
+ export function isPrivateHostname(hostname) {
80
+ const host = normalizeHostname(hostname);
81
+ if (host === "localhost" || host.endsWith(".localhost"))
82
+ return true;
83
+ const address = parseAddress(host);
84
+ return address !== null && address.range() !== "unicast";
85
+ }
@@ -30,11 +30,11 @@ export function validateExternalStyleUrl(url, options = {}) {
30
30
  ? new URL(url, options.baseUrl)
31
31
  : new URL(url);
32
32
  }
33
- catch (err) {
33
+ catch {
34
34
  return {
35
35
  ok: false,
36
36
  reason: "invalid-url",
37
- message: `External stylesheet URL could not be parsed: ${String(err)}`,
37
+ message: "External stylesheet URL could not be parsed.",
38
38
  };
39
39
  }
40
40
  if (resolvedUrl.protocol !== "http:" && resolvedUrl.protocol !== "https:") {
@@ -5,7 +5,9 @@
5
5
  *
6
6
  * The wrapper is rendered as
7
7
  * `<span class="pie-image-scroll" tabindex="0" role="region" aria-label="...">`
8
- * and receives the accompanying CSS from `@pie-players/pie-theme`. The CSS uses
8
+ * and receives the accompanying CSS from `@pie-players/pie-theme`.
9
+ * The live player keeps the region attributes only while the wrapper actually
10
+ * scrolls (see `./overwide-regions.js`), so a image that fits adds no tab stop. The CSS uses
9
11
  * `overflow-x: auto` so small images stay visually unchanged: a scrollbar only
10
12
  * appears when the image's intrinsic width exceeds the wrapper's available
11
13
  * space (including at higher browser-zoom levels, which is the original driver
@@ -26,7 +28,9 @@
26
28
  * The wrapping itself lives in `./wrap-overwide.js`, shared with the table
27
29
  * wrapper: only the spec below differs.
28
30
  */
29
- import { type WrapOverwideOptions } from "./wrap-overwide.js";
31
+ import { type OverwideWrapSpec, type WrapOverwideOptions } from "./wrap-overwide.js";
32
+ /** Internal: shared with the region tracker, not re-exported. */
33
+ export declare const IMAGE_SPEC: OverwideWrapSpec;
30
34
  export type WrapOverwideImagesInElementOptions = WrapOverwideOptions;
31
35
  /**
32
36
  * Wrap every unwrapped `<img>` descendant of `root` with the shared
@@ -5,7 +5,9 @@
5
5
  *
6
6
  * The wrapper is rendered as
7
7
  * `<span class="pie-image-scroll" tabindex="0" role="region" aria-label="...">`
8
- * and receives the accompanying CSS from `@pie-players/pie-theme`. The CSS uses
8
+ * and receives the accompanying CSS from `@pie-players/pie-theme`.
9
+ * The live player keeps the region attributes only while the wrapper actually
10
+ * scrolls (see `./overwide-regions.js`), so a image that fits adds no tab stop. The CSS uses
9
11
  * `overflow-x: auto` so small images stay visually unchanged: a scrollbar only
10
12
  * appears when the image's intrinsic width exceeds the wrapper's available
11
13
  * space (including at higher browser-zoom levels, which is the original driver
@@ -50,7 +52,8 @@ function imageLayoutClass(image) {
50
52
  display !== "contents";
51
53
  return blockLevel ? "pie-image-scroll-block" : null;
52
54
  }
53
- const IMAGE_SPEC = {
55
+ /** Internal: shared with the region tracker, not re-exported. */
56
+ export const IMAGE_SPEC = {
54
57
  selector: "img",
55
58
  wrapperTag: "span",
56
59
  wrapperClass: "pie-image-scroll",
@@ -5,7 +5,9 @@
5
5
  *
6
6
  * The wrapper is rendered as
7
7
  * `<div class="pie-table-scroll" tabindex="0" role="region" aria-label="...">`
8
- * and receives the accompanying CSS from `@pie-players/pie-theme`. The CSS uses
8
+ * and receives the accompanying CSS from `@pie-players/pie-theme`.
9
+ * The live player keeps the region attributes only while the wrapper actually
10
+ * scrolls (see `./overwide-regions.js`), so a table that fits adds no tab stop. The CSS uses
9
11
  * `overflow-x: auto` so narrow tables stay visually unchanged: a scrollbar only
10
12
  * appears when the table's intrinsic width exceeds the wrapper's available
11
13
  * space (including at higher browser-zoom levels — WCAG 1.4.10 Reflow at 400%
@@ -26,7 +28,9 @@
26
28
  * The wrapping itself lives in `./wrap-overwide.js`, shared with the image
27
29
  * wrapper: only the four values below and the accessible name differ.
28
30
  */
29
- import { type WrapOverwideOptions } from "./wrap-overwide.js";
31
+ import { type OverwideWrapSpec, type WrapOverwideOptions } from "./wrap-overwide.js";
32
+ /** Internal: shared with the region tracker, not re-exported. */
33
+ export declare const TABLE_SPEC: OverwideWrapSpec;
30
34
  export type WrapOverwideTablesInElementOptions = WrapOverwideOptions;
31
35
  /**
32
36
  * Wrap every unwrapped `<table>` descendant of `root` with the shared
@@ -5,7 +5,9 @@
5
5
  *
6
6
  * The wrapper is rendered as
7
7
  * `<div class="pie-table-scroll" tabindex="0" role="region" aria-label="...">`
8
- * and receives the accompanying CSS from `@pie-players/pie-theme`. The CSS uses
8
+ * and receives the accompanying CSS from `@pie-players/pie-theme`.
9
+ * The live player keeps the region attributes only while the wrapper actually
10
+ * scrolls (see `./overwide-regions.js`), so a table that fits adds no tab stop. The CSS uses
9
11
  * `overflow-x: auto` so narrow tables stay visually unchanged: a scrollbar only
10
12
  * appears when the table's intrinsic width exceeds the wrapper's available
11
13
  * space (including at higher browser-zoom levels — WCAG 1.4.10 Reflow at 400%
@@ -57,7 +59,8 @@ function buildAriaLabel(table) {
57
59
  }
58
60
  return "Scrollable table";
59
61
  }
60
- const TABLE_SPEC = {
62
+ /** Internal: shared with the region tracker, not re-exported. */
63
+ export const TABLE_SPEC = {
61
64
  selector: "table",
62
65
  wrapperTag: "div",
63
66
  wrapperClass: "pie-table-scroll",
@@ -55,6 +55,19 @@ export interface WrapOverwideOptions {
55
55
  * the layout class this pass would have given it.
56
56
  */
57
57
  export declare function wrapOverwideInElement(root: Element, spec: OverwideWrapSpec, options?: WrapOverwideOptions): number;
58
+ /**
59
+ * Makes each wrapper a named, focusable region while its content overflows it
60
+ * horizontally, and a plain container otherwise.
61
+ *
62
+ * A wrapper is built as a region, because a wrapper that scrolls must be
63
+ * reachable by keyboard (WCAG 2.1.1) and markup wrapped off-document cannot be
64
+ * measured. Most never scroll: a table that fits its column, a drag tile, a
65
+ * layout table. Left as regions they add a tab stop and a landmark each, so the
66
+ * live player measures every wrapper and keeps the region only where there is
67
+ * something to scroll. Measurements are read for every wrapper before the first
68
+ * write. A wrapper holding focus keeps its region, so a sync never drops focus.
69
+ */
70
+ export declare function syncOverwideRegions(wrappers: Iterable<Element>, spec: OverwideWrapSpec): void;
58
71
  /**
59
72
  * String-in / string-out wrapping, for the post-sanitization step.
60
73
  *
@@ -40,6 +40,29 @@ function isInsidePieCustomElement(node, root) {
40
40
  }
41
41
  return false;
42
42
  }
43
+ const VERTICAL_MARGINS = ["margin-top", "margin-bottom"];
44
+ /**
45
+ * Moves the node's inline vertical margins onto its wrapper. The wrapper clips
46
+ * vertically — `overflow-x: auto` forces `overflow-y` off `visible` — so a
47
+ * negative margin left on the node pulls its edge into the clipped band, and
48
+ * the wrapper's own block formatting context stops a positive one collapsing
49
+ * with its neighbours. On the wrapper, both lay out as they did unwrapped.
50
+ * Horizontal margins stay: `margin: 0 auto` centres the node inside the wrapper.
51
+ */
52
+ function liftVerticalMargins(node, wrapper) {
53
+ const style = node.style;
54
+ if (!style)
55
+ return;
56
+ for (const property of VERTICAL_MARGINS) {
57
+ const value = style.getPropertyValue(property);
58
+ if (!value)
59
+ continue;
60
+ wrapper.style.setProperty(property, value, style.getPropertyPriority(property));
61
+ style.removeProperty(property);
62
+ }
63
+ if (!style.length)
64
+ node.removeAttribute("style");
65
+ }
43
66
  /**
44
67
  * Wrappers whose layout class was read from the live cascade. A wrapper built
45
68
  * 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 = {}) {
109
132
  wrapper.className = layoutClass
110
133
  ? `${spec.wrapperClass} ${layoutClass}`
111
134
  : spec.wrapperClass;
112
- wrapper.setAttribute("tabindex", "0");
113
- wrapper.setAttribute("role", "region");
114
- wrapper.setAttribute("aria-label", spec.buildAriaLabel(node));
135
+ setRegion(wrapper, node, spec);
115
136
  if (readsLiveLayout)
116
137
  liveLayoutRead.add(wrapper);
138
+ liftVerticalMargins(node, wrapper);
117
139
  parent.insertBefore(wrapper, node);
118
140
  wrapper.appendChild(node);
119
141
  wrapped += 1;
120
142
  }
121
143
  return wrapped;
122
144
  }
145
+ function setRegion(wrapper, node, spec) {
146
+ wrapper.setAttribute("tabindex", "0");
147
+ wrapper.setAttribute("role", "region");
148
+ wrapper.setAttribute("aria-label", spec.buildAriaLabel(node));
149
+ }
150
+ function clearRegion(wrapper) {
151
+ wrapper.removeAttribute("tabindex");
152
+ wrapper.removeAttribute("role");
153
+ wrapper.removeAttribute("aria-label");
154
+ }
155
+ /**
156
+ * Makes each wrapper a named, focusable region while its content overflows it
157
+ * horizontally, and a plain container otherwise.
158
+ *
159
+ * A wrapper is built as a region, because a wrapper that scrolls must be
160
+ * reachable by keyboard (WCAG 2.1.1) and markup wrapped off-document cannot be
161
+ * measured. Most never scroll: a table that fits its column, a drag tile, a
162
+ * layout table. Left as regions they add a tab stop and a landmark each, so the
163
+ * live player measures every wrapper and keeps the region only where there is
164
+ * something to scroll. Measurements are read for every wrapper before the first
165
+ * write. A wrapper holding focus keeps its region, so a sync never drops focus.
166
+ */
167
+ export function syncOverwideRegions(wrappers, spec) {
168
+ const measured = [];
169
+ for (const wrapper of wrappers) {
170
+ if (!wrapper.isConnected)
171
+ continue;
172
+ if (!wrapper.classList.contains(spec.wrapperClass))
173
+ continue;
174
+ measured.push([wrapper, wrapper.scrollWidth > wrapper.clientWidth]);
175
+ }
176
+ for (const [wrapper, scrolls] of measured) {
177
+ const node = wrapper.firstElementChild;
178
+ if (scrolls && node?.matches(spec.selector))
179
+ setRegion(wrapper, node, spec);
180
+ else if (!scrolls && !isFocused(wrapper))
181
+ clearRegion(wrapper);
182
+ }
183
+ }
184
+ function isFocused(element) {
185
+ const root = element.getRootNode();
186
+ return root.activeElement === element;
187
+ }
123
188
  /**
124
189
  * String-in / string-out wrapping, for the post-sanitization step.
125
190
  *
@@ -5,7 +5,7 @@
5
5
  * Pure apart from one adapter factory that is inert until called, so the contract
6
6
  * is testable without a browser and an adapter can import it without pulling in a
7
7
  * player. Live cue state belongs to `SectionController` in
8
- * `@pie-players/pie-section-player`, which is where the equivalent formative state
8
+ * `@pie-players/pie-section-player`, which is where the equivalent Try state
9
9
  * lives — one rollup over one item set, in one package.
10
10
  *
11
11
  * Contract: `docs/prds/timed-media-section-contract.md`.
@@ -5,7 +5,7 @@
5
5
  * Pure apart from one adapter factory that is inert until called, so the contract
6
6
  * is testable without a browser and an adapter can import it without pulling in a
7
7
  * player. Live cue state belongs to `SectionController` in
8
- * `@pie-players/pie-section-player`, which is where the equivalent formative state
8
+ * `@pie-players/pie-section-player`, which is where the equivalent Try state
9
9
  * lives — one rollup over one item set, in one package.
10
10
  *
11
11
  * Contract: `docs/prds/timed-media-section-contract.md`.