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

package/dist/i18n/catalogs.d.ts

@@ -31,6 +31,11 @@ export declare const BUNDLED_LOCALES: readonly BundledLocaleCode[];
 /**
  * Load one shipped catalog.
  *
+ * `en-US` comes back without a load: it is statically resident, and a host
+ * composing this loader into a provider — the generated tier's README pattern,
+ * or a pseudo-localization of the English catalog — asks for it by name like
+ * any other locale.
+ *
  * Throws for a locale with no shipped catalog; the provider treats that as
  * "resolve through the fallback chain" rather than an error, so a host locale we
  * do not ship still renders.

package/dist/i18n/catalogs.js

@@ -20,6 +20,7 @@
  *
  * @module @pie-players/pie-players-shared/i18n/catalogs
  */
+import enUS from "./messages/en-US.js";
 const CATALOG_LOADERS = {
     "nl-NL": () => import("./messages/nl-NL.js"),
 };
@@ -33,11 +34,19 @@ export const BUNDLED_LOCALES = ["en-US", "nl-NL"];
 /**
  * Load one shipped catalog.
  *
+ * `en-US` comes back without a load: it is statically resident, and a host
+ * composing this loader into a provider — the generated tier's README pattern,
+ * or a pseudo-localization of the English catalog — asks for it by name like
+ * any other locale.
+ *
  * Throws for a locale with no shipped catalog; the provider treats that as
  * "resolve through the fallback chain" rather than an error, so a host locale we
  * do not ship still renders.
  */
 export async function loadBundledCatalog(locale) {
+    if (locale === "en-US") {
+        return enUS;
+    }
     const loader = CATALOG_LOADERS[locale];
     if (!loader) {
         throw new Error(`No bundled i18n catalog for locale: ${locale}`);

package/dist/i18n/content-language.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Content language on the delivery channel.
+ *
+ * Content language names the language the item's content is written in — a
+ * fact about the content, on a separate channel from the interface locale a
+ * player publishes to the elements inside it. It reaches the player in
+ * `env.locale`, the same channel `env.mode` travels: a delivery fact the
+ * container knows and content cannot. Authoring hosts emit it; a host that
+ * emits nothing leaves the content unstamped, and nothing is invented — there
+ * is no default language for content that names none.
+ *
+ * The player reflects the resolved language onto its content subtree's root as
+ * `lang` and `dir`, so a screen reader takes the content's voice rules and RTL
+ * content lays out right to left, independent of the chrome's locale.
+ */
+import type { TextDirection } from "./types.js";
+/** `lang` and `dir` for declared content, or `null` when nothing is declared. */
+export interface ContentLanguageAttributes {
+    lang: string;
+    dir: TextDirection;
+}
+/**
+ * `lang` and `dir` for the content an `env` describes, or `null` when it
+ * declares no usable language. Reads `env.locale` defensively — `env` is
+ * pass-through and load-bearing, so anything may arrive — and never invents a
+ * default: undeclared content stays unstamped and inherits whatever its
+ * context genuinely provides.
+ */
+export declare function contentLanguageAttributes(env: unknown): ContentLanguageAttributes | null;
+/**
+ * Stamps `contentLanguageAttributes(env)` onto `target`, removing both
+ * attributes when the env declares no language — a model set can drop the
+ * language a previous one declared. No-op without a target.
+ */
+export declare function stampContentLanguage(target: Element | null | undefined, env: unknown): void;

package/dist/i18n/content-language.js

@@ -0,0 +1,51 @@
+/**
+ * Content language on the delivery channel.
+ *
+ * Content language names the language the item's content is written in — a
+ * fact about the content, on a separate channel from the interface locale a
+ * player publishes to the elements inside it. It reaches the player in
+ * `env.locale`, the same channel `env.mode` travels: a delivery fact the
+ * container knows and content cannot. Authoring hosts emit it; a host that
+ * emits nothing leaves the content unstamped, and nothing is invented — there
+ * is no default language for content that names none.
+ *
+ * The player reflects the resolved language onto its content subtree's root as
+ * `lang` and `dir`, so a screen reader takes the content's voice rules and RTL
+ * content lays out right to left, independent of the chrome's locale.
+ */
+import { canonicalLanguageTag } from "./language-tags.js";
+import { localeDirection } from "./provider.js";
+/**
+ * `lang` and `dir` for the content an `env` describes, or `null` when it
+ * declares no usable language. Reads `env.locale` defensively — `env` is
+ * pass-through and load-bearing, so anything may arrive — and never invents a
+ * default: undeclared content stays unstamped and inherits whatever its
+ * context genuinely provides.
+ */
+export function contentLanguageAttributes(env) {
+    const locale = env?.locale;
+    if (typeof locale !== "string")
+        return null;
+    const lang = canonicalLanguageTag(locale);
+    if (!lang)
+        return null;
+    return { lang, dir: localeDirection(lang) };
+}
+/**
+ * Stamps `contentLanguageAttributes(env)` onto `target`, removing both
+ * attributes when the env declares no language — a model set can drop the
+ * language a previous one declared. No-op without a target.
+ */
+export function stampContentLanguage(target, env) {
+    if (!target)
+        return;
+    const attributes = contentLanguageAttributes(env);
+    if (attributes) {
+        target.setAttribute("lang", attributes.lang);
+        target.setAttribute("dir", attributes.dir);
+    }
+    else {
+        target.removeAttribute("lang");
+        target.removeAttribute("dir");
+    }
+}

package/dist/i18n/index.d.ts

@@ -28,6 +28,10 @@ import type { I18nConfig, I18nServiceApi } from "./types.js";
  */
 export declare function createPieI18n(config?: I18nConfig): I18nServiceApi;
 export { BUNDLED_LOCALES, loadBundledCatalog } from "./catalogs.js";
-export { findBestLanguageMatch, languageTagLookupSequence, languageTagsEqual, normalizeLanguageTag, toLanguageTag, } from "./language-tags.js";
-export { DEFAULT_LOCALE, detectBrowserLocale, dynamicMessageKey, getDefaultI18n, localeDirection, resolveInterfaceI18n, SimpleI18n, } from "./provider.js";
+export { canonicalLanguageTag, findBestLanguageMatch, languageTagLookupSequence, languageTagsEqual, normalizeLanguageTag, toLanguageTag, } from "./language-tags.js";
+export { DEFAULT_LOCALE, detectBrowserLocale, dynamicMessageKey, getDefaultI18n, localeDirection, resolveInterfaceI18n, SimpleI18n, stampInterfaceLocale, } from "./provider.js";
+export { type ContentLanguageAttributes, contentLanguageAttributes, stampContentLanguage, } from "./content-language.js";
+export { type InterfaceLocaleLoadErrorModel, reportInterfaceLocaleLoadError, } from "./locale-load-error.js";
+export { PSEUDO_LOCALE_EXPANDED, PSEUDO_LOCALE_RTL, pseudoLocalize, } from "./pseudo.js";
+export type { PseudoLocalizeOptions } from "./pseudo.js";
 export type { BundledLocaleCode, DynamicMessageKey, I18nConfig, I18nProvider, I18nServiceApi, InterpolationValues, LocaleCode, MessageCatalog, MessageKey, MessageKeyInput, MessageNode, PluralOptions, PluralTranslation, TextDirection, TranslationBundle, } from "./types.js";

package/dist/i18n/index.js

@@ -35,5 +35,8 @@ export function createPieI18n(config = {}) {
     });
 }
 export { BUNDLED_LOCALES, loadBundledCatalog } from "./catalogs.js";
-export { findBestLanguageMatch, languageTagLookupSequence, languageTagsEqual, normalizeLanguageTag, toLanguageTag, } from "./language-tags.js";
-export { DEFAULT_LOCALE, detectBrowserLocale, dynamicMessageKey, getDefaultI18n, localeDirection, resolveInterfaceI18n, SimpleI18n, } from "./provider.js";
+export { canonicalLanguageTag, findBestLanguageMatch, languageTagLookupSequence, languageTagsEqual, normalizeLanguageTag, toLanguageTag, } from "./language-tags.js";
+export { DEFAULT_LOCALE, detectBrowserLocale, dynamicMessageKey, getDefaultI18n, localeDirection, resolveInterfaceI18n, SimpleI18n, stampInterfaceLocale, } from "./provider.js";
+export { contentLanguageAttributes, stampContentLanguage, } from "./content-language.js";
+export { reportInterfaceLocaleLoadError, } from "./locale-load-error.js";
+export { PSEUDO_LOCALE_EXPANDED, PSEUDO_LOCALE_RTL, pseudoLocalize, } from "./pseudo.js";

package/dist/i18n/language-tags.d.ts

@@ -57,3 +57,12 @@ export declare function languageTagLookupSequence(tag: string | null | undefined
  * however they were authored.
  */
 export declare function findBestLanguageMatch(requested: string | null | undefined, available: readonly (string | null | undefined)[]): string | undefined;
+/**
+ * The canonical form of a usable language tag, or `undefined` for anything a
+ * language in use would not be: `es_MX` normalizes to `es-MX`, `NL-nl` to
+ * `nl-NL`, and `Spanish` or an empty string are not tags. One rule for every
+ * `lang` this repository writes — content and chrome alike — and the same rule
+ * the PIE elements apply to `model.language`, so every stamped attribute on a
+ * page carries the same shape.
+ */
+export declare function canonicalLanguageTag(language: string | null | undefined): string | undefined;

package/dist/i18n/language-tags.js

@@ -92,3 +92,24 @@ export function findBestLanguageMatch(requested, available) {
     }
     return undefined;
 }
+/**
+ * The canonical form of a usable language tag, or `undefined` for anything a
+ * language in use would not be: `es_MX` normalizes to `es-MX`, `NL-nl` to
+ * `nl-NL`, and `Spanish` or an empty string are not tags. One rule for every
+ * `lang` this repository writes — content and chrome alike — and the same rule
+ * the PIE elements apply to `model.language`, so every stamped attribute on a
+ * page carries the same shape.
+ */
+export function canonicalLanguageTag(language) {
+    const tag = toLanguageTag(language).split(/[.@]/)[0];
+    // `Intl` accepts any 5-8 letter primary subtag, `Spanish` included; a
+    // language in use has an ISO 639 code of two or three letters.
+    if (!/^[a-z]{2,3}(-|$)/i.test(tag))
+        return undefined;
+    try {
+        return Intl.getCanonicalLocales(tag)[0];
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/i18n/locale-load-error.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The `framework-error` report for a failed interface-locale catalog load.
+ *
+ * Every locale driver — the toolkit through its error bus, the standalone item
+ * player and the reference assembly through this helper — reports the same
+ * failure the same way: a `framework-error` DOM event whose detail carries the
+ * `i18n-locale-load` kind with `recoverable: true`, because every key still
+ * resolves through the English fallback chain and the player renders — in the
+ * wrong language, which a host wants to know about.
+ *
+ * The shape mirrors the toolkit's `FrameworkErrorModel` field for field. It is
+ * declared here, narrowly, because the standalone item player does not depend
+ * on the toolkit and a type-only import would still drag it into the published
+ * declarations; what this module commits to is the fields below, which is what
+ * a host reading `.kind` and `.recoverable` consumes.
+ */
+export interface InterfaceLocaleLoadErrorModel {
+    kind: "i18n-locale-load";
+    source: string;
+    message: string;
+    details: string[];
+    recoverable: true;
+    scope: "runtime";
+    cause?: unknown;
+}
+/**
+ * Dispatches the recoverable load-failure report on `target` as a
+ * `bubbles`/`composed` `framework-error` event. No-op without a target, so a
+ * caller mounted as a plain component rather than an element stays silent.
+ *
+ * Failed loads are not cached: re-setting the `locale` attribute, or
+ * recomposing the `i18n` provider, drives `setLocale` again and so retries.
+ */
+export declare function reportInterfaceLocaleLoadError(target: Element | null | undefined, source: string, cause: unknown): void;

package/dist/i18n/locale-load-error.js

@@ -0,0 +1,29 @@
+/**
+ * Dispatches the recoverable load-failure report on `target` as a
+ * `bubbles`/`composed` `framework-error` event. No-op without a target, so a
+ * caller mounted as a plain component rather than an element stays silent.
+ *
+ * Failed loads are not cached: re-setting the `locale` attribute, or
+ * recomposing the `i18n` provider, drives `setLocale` again and so retries.
+ */
+export function reportInterfaceLocaleLoadError(target, source, cause) {
+    if (!target)
+        return;
+    const message = cause instanceof Error && cause.message.trim().length > 0
+        ? cause.message
+        : String(cause ?? "Unknown catalog load failure");
+    const detail = {
+        kind: "i18n-locale-load",
+        source,
+        message,
+        details: [],
+        recoverable: true,
+        scope: "runtime",
+        cause,
+    };
+    target.dispatchEvent(new CustomEvent("framework-error", {
+        detail,
+        bubbles: true,
+        composed: true,
+    }));
+}

package/dist/i18n/messages/en-US.d.ts

@@ -57,6 +57,8 @@ declare const enUS: {
         apply: string;
         enabled: string;
         disabled: string;
+        lookUp: string;
+        wordOrPhrase: string;
         closeA11y: string;
         settingsA11y: string;
     };
@@ -89,6 +91,14 @@ declare const enUS: {
         resizeMediaRegion: string;
         resizeQuestionAndMediaA11y: string;
         resizePassageAndMediaA11y: string;
+        resizePassageAndQuestionA11y: string;
+        passageWidthA11y: string;
+        /**
+         * The section player's navigation live region, announced when the active
+         * item changes; `{label}` is the item's own label when it has one.
+         */
+        questionPositionA11y: string;
+        questionPositionLabeledA11y: string;
         /**
          * The assessment player's own section-to-section navigation. Its Back and
          * Next controls take `common.back` / `common.next`.
@@ -139,6 +149,29 @@ declare const enUS: {
             playbackAdvisory: string;
             playbackReleased: string;
         };
+        /**
+         * `<pie-item-summary>`: an item described as a list row, without loading its
+         * elements. The correct marker's glyph is hidden from assistive technology,
+         * which reads `correctA11y` instead.
+         */
+        summary: {
+            correctA11y: string;
+            answer: string;
+            manualScoring: string;
+            audio: string;
+            video: string;
+        };
+        /** `<pie-item-list>`. */
+        list: {
+            /** The row toggle, a disclosure button whose `aria-expanded` carries the state, so its label stays the same either way. */
+            expandA11y: string;
+            /** Names the block of an entry's search matches below its summary. */
+            highlights: string;
+            /** The row toggle's tooltip while the row is expanded: collapsing returns it to the summary. */
+            collapse: string;
+            /** Shown in an expanded row whose player failed to load; the summary keeps showing above it. */
+            playerError: string;
+        };
     };
     /** Toolbar and tool-shell chrome owned by the assessment toolkit. */
     toolkit: {
@@ -159,17 +192,20 @@ declare const enUS: {
             moveRightA11y: string;
             moveUpA11y: string;
             moveDownA11y: string;
-            shrinkA11y: string;
-            growA11y: string;
+            narrowerA11y: string;
+            widerA11y: string;
+            shorterA11y: string;
+            tallerA11y: string;
             centerA11y: string;
             closeA11y: string;
         };
         /**
-         * The tap controls that move and turn the ruler and protractor without a
+         * The tap controls that move, turn and resize a placed tool without a
          * drag. The move buttons reuse the `window` labels above.
          */
         placement: {
             controlsA11y: string;
+            moveAndResizeA11y: string;
             rotateClockwiseA11y: string;
             rotateCounterclockwiseA11y: string;
         };
@@ -209,6 +245,7 @@ declare const enUS: {
             toolA11y: string;
             loading: string;
             providerUnavailable: string;
+            initFailed: string;
         };
         graph: {
             name: string;
@@ -302,6 +339,15 @@ declare const enUS: {
             buttonA11y: string;
             tooltip: string;
             toolA11y: string;
+            notConfigured: string;
+            idleHint: string;
+            lookingUp: string;
+            noEntryFor: string;
+            entriesCount: {
+                one: string;
+                other: string;
+            };
+            noEntryStatusFor: string;
         };
         pictureDictionary: {
             name: string;
@@ -309,6 +355,15 @@ declare const enUS: {
             buttonA11y: string;
             tooltip: string;
             toolA11y: string;
+            notConfigured: string;
+            idleHint: string;
+            lookingUp: string;
+            noEntryFor: string;
+            entriesCount: {
+                one: string;
+                other: string;
+            };
+            noEntryStatusFor: string;
         };
         /**
          * The Spanish variants. Named in the interface locale like every other tool label —
@@ -341,10 +396,36 @@ declare const enUS: {
             windowHeightAnnounce: string;
             frameHeightAnnounce: string;
             widthAnnounce: string;
+            shorterWindowA11y: string;
+            tallerWindowA11y: string;
+            shorterFrameA11y: string;
+            tallerFrameA11y: string;
+            narrowerA11y: string;
+            widerA11y: string;
             applicationA11y: string;
             resizeWindowFullA11y: string;
             resizeFrameFullA11y: string;
         };
+        magnification: {
+            name: string;
+            description: string;
+            buttonA11y: string;
+            tooltip: string;
+            roleA11y: string;
+            applicationA11y: string;
+            zoomIn: string;
+            zoomOut: string;
+            zoomLevel: string;
+            zoomAnnounce: string;
+            close: string;
+            resizeA11y: string;
+            resizeFullA11y: string;
+            sizeAnnounce: string;
+            narrowerA11y: string;
+            widerA11y: string;
+            shorterA11y: string;
+            tallerA11y: string;
+        };
         answerEliminator: {
             name: string;
             description: string;
@@ -498,6 +579,30 @@ declare const enUS: {
         toggleEventPanelA11y: string;
         toggleDatabasePanelA11y: string;
         toggleInstrumentationPanelA11y: string;
+        clear: string;
+        pause: string;
+        resume: string;
+        controllerUnavailable: string;
+        noMatchingEvents: string;
+        noSectionSessionYet: string;
+        eventLevelItem: string;
+        eventLevelSection: string;
+        instrumentationKindAll: string;
+        instrumentationKindEvent: string;
+        instrumentationKindError: string;
+        instrumentationKindMetric: string;
+        instrumentationKindUserContext: string;
+        instrumentationKindGlobalAttributes: string;
+        instrumentationFieldName: string;
+        instrumentationFieldKind: string;
+        instrumentationFieldProvider: string;
+        instrumentationFieldTimestamp: string;
+        instrumentationFieldValue: string;
+        instrumentationFieldError: string;
+        sessionDbAssessmentId: string;
+        sessionDbSectionId: string;
+        sessionDbAttemptId: string;
+        sessionDbMode: string;
         /** PNP debugger. */
         pnp: {
             title: string;
@@ -517,6 +622,12 @@ declare const enUS: {
             perToolDecisions: string;
             policyDiagnostics: string;
             profileReadOnly: string;
+            on: string;
+            effective: string;
+            needs: string;
+            hostSurfaceNotPlaced: string;
+            support: string;
+            prohibit: string;
         };
         /** TTS settings panel. */
         tts: {
@@ -612,6 +723,16 @@ declare const enUS: {
             previewHintGoogleSsml: string;
             previewHintCustom: string;
             previewHintTracking: string;
+            formatMp3: string;
+            formatOgg: string;
+            formatPcm: string;
+            sampleRate8000: string;
+            sampleRate16000: string;
+            sampleRate22050: string;
+            sampleRate24000: string;
+            apiEndpointPlaceholder: string;
+            languagePlaceholder: string;
+            ssml: string;
         };
     };
 };