@longsightgroup/qti3-player 0.4.0 → 0.5.4

package/src/interactions/select-point-interaction.ts

@@ -5,11 +5,10 @@ import {
   appendGraphicObjectImage,
   objectHeight,
   objectWidth,
-  readableType,
   responseGroup,
 } from "../interaction-support.js";
 import { movementButton } from "../movement.js";
-import type { QtiPlayerMessages } from "../player-messages.js";
+import type { PlayerMessageResolver } from "../player-message-resolver.js";
 import { maximumAllowedResponses } from "../response-limits.js";
 import { parsePointValues, pointToString } from "./point-value.js";
 
@@ -17,11 +16,14 @@ export function renderSelectPointResponse(
   interaction: QtiInteraction,
   update: (value: QtiValue) => void,
   currentValue: QtiValue,
-  messages: QtiPlayerMessages,
+  messages: PlayerMessageResolver,
 ): HTMLElement {
   const group = responseGroup();
   group.role = "group";
-  group.setAttribute("aria-label", `${readableType(interaction.type)} coordinate response`);
+  group.setAttribute(
+    "aria-label",
+    messages.message("interactionCoordinateResponse", { type: interaction.type }),
+  );
   const isMultiple = interaction.responseCardinality === "multiple";
   const maxPoints = isMultiple ? maximumAllowedResponses(interaction) : 1;
 
@@ -33,7 +35,10 @@ export function renderSelectPointResponse(
     objectHeight(interaction),
     "qti3-point-surface",
   );
-  surface.setAttribute("aria-label", `${readableType(interaction.type)} coordinate area`);
+  surface.setAttribute(
+    "aria-label",
+    messages.message("interactionCoordinateArea", { type: interaction.type }),
+  );
 
   const object = interaction.object;
   if (object) {
@@ -45,7 +50,8 @@ export function renderSelectPointResponse(
   let points = parsePointValues(currentValue);
   let activeIndex = points.length > 0 ? points.length - 1 : -1;
   const coordinate = document.createElement("output");
-  coordinate.className = "qti3-coordinate-output";
+  coordinate.className = "qti3-coordinate-output qti-visually-hidden";
+  coordinate.setAttribute("aria-live", "polite");
   const initialPoint = () => ({
     x: Math.round(width / 2),
     y: Math.round(height / 2),
@@ -62,8 +68,11 @@ export function renderSelectPointResponse(
     surface.querySelectorAll(".qti3-point-marker").forEach((marker) => marker.remove());
     if (points.length === 0) {
       coordinate.value = "";
-      coordinate.textContent = messages.noPointSelected();
-      surface.setAttribute("aria-label", `${readableType(interaction.type)} coordinate area`);
+      coordinate.textContent = messages.message("noPointSelected");
+      surface.setAttribute(
+        "aria-label",
+        messages.message("interactionCoordinateArea", { type: interaction.type }),
+      );
       return;
     }
     points.forEach((point, index) => {
@@ -83,11 +92,14 @@ export function renderSelectPointResponse(
       ? points.map(pointToString).join(" | ")
       : pointToString(points[0]);
     coordinate.textContent = isMultiple
-      ? `${points.length} selected point${points.length === 1 ? "" : "s"}: ${text}`
-      : `Selected point ${pointToString(points[0])}`;
+      ? messages.message("selectedPointsSummary", { count: points.length, coordinates: text })
+      : messages.message("selectedPointAt", { coordinates: pointToString(points[0]) });
     surface.setAttribute(
       "aria-label",
-      `${readableType(interaction.type)} coordinate area, selected ${text}`,
+      messages.message("interactionCoordinateAreaSelected", {
+        type: interaction.type,
+        coordinates: text,
+      }),
     );
   };
   const clampPoint = (point: { x: number; y: number }) => {
@@ -158,7 +170,7 @@ export function renderSelectPointResponse(
     ["down", 0, 1],
   ] as const) {
     controls.append(
-      movementButton(direction, messages.movePoint({ direction }), () => {
+      movementButton(direction, messages.message("movePoint", { direction }), () => {
         const point = mutableActivePoint();
         point.x += dx;
         point.y += dy;
@@ -171,7 +183,7 @@ export function renderSelectPointResponse(
   if (isMultiple) {
     const clear = document.createElement("button");
     clear.type = "button";
-    clear.textContent = messages.clearPoints();
+    clear.textContent = messages.message("clearPoints");
     clear.addEventListener("click", () => {
       points = [];
       activeIndex = -1;

package/src/interactions/shared.ts

@@ -1,4 +1,5 @@
 import type { QtiChoice, QtiInteraction } from "@longsightgroup/qti3-core";
+import type { PlayerMessageResolver } from "../player-message-resolver.js";
 import { interactionChoices } from "../interaction-support.js";
 
 export function tokenRegion(label: string, visibleLabel?: string): HTMLElement {
@@ -49,8 +50,24 @@ export function targetChoices(interaction: QtiInteraction): QtiChoice[] {
   return targets.length > 0 ? targets : choices;
 }
 
-export function pairRegionLabels(interaction: QtiInteraction): { source: string; target: string } {
-  if (interaction.type === "associate") return { source: "First concept", target: "Pair with" };
-  if (interaction.type === "match") return { source: "Prompt", target: "Match" };
-  return { source: "Source", target: "Target" };
+export function pairRegionLabels(
+  interaction: QtiInteraction,
+  messages: PlayerMessageResolver,
+): { source: string; target: string } {
+  if (interaction.type === "associate") {
+    return {
+      source: messages.message("associateFirstConceptRegion"),
+      target: messages.message("associatePairWithRegion"),
+    };
+  }
+  if (interaction.type === "match") {
+    return {
+      source: messages.message("matchPromptRegion"),
+      target: messages.message("matchMatchRegion"),
+    };
+  }
+  return {
+    source: messages.message("genericSourceRegion"),
+    target: messages.message("genericTargetRegion"),
+  };
 }

package/src/interactions/text-interaction.ts

@@ -1,4 +1,5 @@
 import type { QtiInteraction, QtiValue } from "@longsightgroup/qti3-core";
+import type { PlayerMessageResolver } from "../player-message-resolver.js";
 
 function scalarString(value: QtiValue): string {
   if (value === null || Array.isArray(value) || typeof value === "object") return "";
@@ -32,6 +33,7 @@ export function renderTextResponse(
   update: (value: QtiValue) => void,
   mode: "entry" | "extended",
   currentValue: QtiValue,
+  messages: PlayerMessageResolver,
 ): HTMLElement {
   const group = document.createElement("div");
   group.className = "qti3-text-response";
@@ -43,7 +45,10 @@ export function renderTextResponse(
   control.value = scalarString(currentValue);
   control.setAttribute(
     "aria-label",
-    interaction.prompt ?? (mode === "extended" ? "Extended text response" : "Text response"),
+    interaction.prompt ??
+      (mode === "extended"
+        ? messages.message("extendedTextResponseLabel")
+        : messages.message("textResponseLabel")),
   );
   if (mode === "extended" && expectedLines > 0) {
     (control as HTMLTextAreaElement).rows = expectedLines;
@@ -60,7 +65,10 @@ export function renderTextResponse(
     const value = control.value;
     if (counter) {
       const words = value.trim().length > 0 ? value.trim().split(/\s+/).length : 0;
-      counter.textContent = `${value.length} characters, ${words} words`;
+      counter.textContent = messages.message("extendedTextCounter", {
+        characters: value.length,
+        words,
+      });
     }
     if (emitResponse) update(value);
   };
@@ -76,6 +84,7 @@ export function renderInlineTextEntry(
   interaction: QtiInteraction,
   update: (value: QtiValue) => void,
   currentValue: QtiValue,
+  messages: PlayerMessageResolver,
 ): HTMLElement {
   const group = document.createElement("span");
   group.className = "qti3-inline-text-response";
@@ -84,7 +93,7 @@ export function renderInlineTextEntry(
   input.value = scalarString(currentValue);
   input.setAttribute(
     "aria-label",
-    interaction.prompt ?? interaction.contextText ?? "Text response",
+    interaction.prompt ?? interaction.contextText ?? messages.message("textResponseLabel"),
   );
   const expectedLength = Number(interaction.attributes["expected-length"] ?? 0);
   applyExpectedTextEntryWidth(input, expectedLength);
@@ -102,6 +111,7 @@ export function renderSliderResponse(
   interaction: QtiInteraction,
   update: (value: QtiValue) => void,
   currentValue: QtiValue,
+  messages: PlayerMessageResolver,
 ): HTMLElement {
   const group = document.createElement("div");
   group.className = "qti3-slider-response";
@@ -111,7 +121,7 @@ export function renderSliderResponse(
   input.max = interaction.attributes["upper-bound"] ?? "100";
   input.step = interaction.attributes.step ?? "1";
   input.value = scalarString(currentValue) || interaction.attributes["lower-bound"] || "0";
-  input.setAttribute("aria-label", interaction.prompt ?? "Slider response");
+  input.setAttribute("aria-label", interaction.prompt ?? messages.message("sliderResponseLabel"));
   const output = document.createElement("output");
   output.className = "qti3-slider-output";
   output.value = input.value;

package/src/interactions/upload-interaction.ts

@@ -1,16 +1,19 @@
 import type { QtiInteraction, QtiValue } from "@longsightgroup/qti3-core";
-import type { QtiPlayerMessages } from "../player-messages.js";
+import type { PlayerMessageResolver } from "../player-message-resolver.js";
 import { interactionLabel } from "./interaction-label.js";
 
 export function renderUploadResponse(
   interaction: QtiInteraction,
   update: (value: QtiValue) => void,
-  messages: QtiPlayerMessages,
+  messages: PlayerMessageResolver,
 ): HTMLElement {
   const input = document.createElement("input");
   input.type = "file";
   input.className = "qti3-upload-input";
-  input.setAttribute("aria-label", interactionLabel(interaction) || messages.uploadResponse());
+  input.setAttribute(
+    "aria-label",
+    interactionLabel(interaction) || messages.message("uploadResponse"),
+  );
   input.addEventListener("change", () => update(input.files?.[0]?.name ?? ""));
   return input;
 }

package/src/player/interaction-render.ts

@@ -5,12 +5,12 @@ import { interactionLabel, qtiSharedClassNames } from "../interactions/interacti
 import { renderSelect } from "../interactions/inline-choice-interaction.js";
 import { renderInlineTextEntry } from "../interactions/text-interaction.js";
 import { renderUnsupportedEmbeddedInteraction } from "../interactions/unsupported-interaction.js";
-import type { QtiPlayerMessages } from "../player-messages.js";
+import type { PlayerMessageResolver } from "../player-message-resolver.js";
 import { inlineValidationMessageElement, validationMessageElement } from "../player-validation.js";
 
 export interface BlockInteractionRenderOptions {
   interaction: QtiInteraction;
-  messages: QtiPlayerMessages;
+  messages: PlayerMessageResolver;
   update: (value: QtiValue) => void;
   currentValue: QtiValue;
   isCompleted: () => boolean;
@@ -65,7 +65,7 @@ export function renderEmbeddedInteractionSection(
   interaction: QtiInteraction,
   update: (value: QtiValue) => void,
   currentValue: QtiValue,
-  messages: QtiPlayerMessages,
+  messages: PlayerMessageResolver,
 ): HTMLElement {
   if (interaction.type !== "inlineChoice" && interaction.type !== "textEntry") {
     return renderUnsupportedEmbeddedInteraction(interaction);
@@ -83,7 +83,7 @@ export function renderEmbeddedInteractionSection(
   wrapper.append(
     interaction.type === "inlineChoice"
       ? renderSelect(interaction, update, currentValue, messages)
-      : renderInlineTextEntry(interaction, update, currentValue),
+      : renderInlineTextEntry(interaction, update, currentValue, messages),
   );
   return wrapper;
 }

package/src/player-adapter.ts

@@ -0,0 +1,253 @@
+import type {
+  QtiAttemptStateV1,
+  QtiCatalogSupportResolution,
+  QtiCatalogSupportResolutionOptions,
+  QtiScoreResult,
+  QtiTextToSpeechTraversal,
+} from "@longsightgroup/qti3-core";
+import type { PlayerMessageCatalog } from "./player-message-catalog.js";
+import type { QtiAssessmentItemPlayer } from "./player-element.js";
+import type { QtiPlayerMessageOverrides } from "./player-message-resolver.js";
+import type {
+  QtiAssessmentItemPlayerEventDetailMap,
+  QtiAssessmentItemPlayerEventName,
+  QtiPlayerFetchXml,
+  QtiPlayerLoadOptions,
+  QtiPlayerResolveAsset,
+  QtiScoreAttemptOptions,
+} from "./player-types.js";
+
+export type QtiAssessmentItemPlayerAdapterEventPropName =
+  | "onReady"
+  | "onResponseChange"
+  | "onStateChange"
+  | "onScore"
+  | "onValidation"
+  | "onSuspend"
+  | "onEndAttempt"
+  | "onPortableCustomMount"
+  | "onDiagnostics"
+  | "onReset"
+  | "onRestore";
+
+export type QtiAssessmentItemPlayerAdapterPropName =
+  | "xml"
+  | "loadOptions"
+  | "languageOfInterface"
+  | "messageCatalog"
+  | "messages"
+  | "onLoadError"
+  | QtiAssessmentItemPlayerAdapterEventPropName;
+
+export type QtiAssessmentItemPlayerAdapterEventCallback<
+  T extends QtiAssessmentItemPlayerEventName,
+> = (detail: QtiAssessmentItemPlayerEventDetailMap[T]) => void;
+
+export type QtiAssessmentItemPlayerAdapterEventHandlerProps = {
+  [K in (typeof qtiAssessmentItemPlayerAdapterEventEntries)[number] as K[1]]?: QtiAssessmentItemPlayerAdapterEventCallback<
+    K[0]
+  >;
+};
+
+export interface QtiAssessmentItemPlayerAdapterProps extends QtiAssessmentItemPlayerAdapterEventHandlerProps {
+  /** Already-prepared candidate-safe XML for delivery, or authoring/preview XML in preview tools. */
+  xml?: string | undefined;
+  loadOptions?: QtiPlayerLoadOptions | undefined;
+  languageOfInterface?: string | undefined;
+  messageCatalog?: PlayerMessageCatalog | undefined;
+  messages?: QtiPlayerMessageOverrides | undefined;
+  onLoadError?: ((error: Error) => void) | undefined;
+}
+
+export interface QtiAssessmentItemPlayerHandle {
+  readonly element: QtiAssessmentItemPlayer;
+  loadXml(xml: string, options?: QtiPlayerLoadOptions): Promise<void>;
+  loadUrl(url: string, options?: QtiPlayerLoadOptions): Promise<void>;
+  scoreAttempt(options?: QtiScoreAttemptOptions): QtiScoreResult | undefined;
+  restore(state: QtiAttemptStateV1): void;
+  suspend(): void;
+  endAttempt(options?: QtiScoreAttemptOptions): void;
+  reset(): void;
+  clearItem(): void;
+  serialize(): QtiAttemptStateV1 | undefined;
+  getTextToSpeechTraversal(): QtiTextToSpeechTraversal | undefined;
+  getCatalogSupportResolution(
+    options?: QtiCatalogSupportResolutionOptions,
+  ): QtiCatalogSupportResolution | undefined;
+}
+
+export const qtiAssessmentItemPlayerAdapterEventEntries = [
+  ["qti-ready", "onReady"],
+  ["qti-responsechange", "onResponseChange"],
+  ["qti-statechange", "onStateChange"],
+  ["qti-score", "onScore"],
+  ["qti-validation", "onValidation"],
+  ["qti-suspend", "onSuspend"],
+  ["qti-endattempt", "onEndAttempt"],
+  ["qti-portable-custom-mount", "onPortableCustomMount"],
+  ["qti-diagnostics", "onDiagnostics"],
+  ["qti-reset", "onReset"],
+  ["qti-restore", "onRestore"],
+] as const satisfies readonly (readonly [
+  QtiAssessmentItemPlayerEventName,
+  QtiAssessmentItemPlayerAdapterEventPropName,
+])[];
+
+export const qtiAssessmentItemPlayerAdapterPropNames = [
+  "xml",
+  "loadOptions",
+  "languageOfInterface",
+  "messageCatalog",
+  "messages",
+  "onLoadError",
+  ...qtiAssessmentItemPlayerAdapterEventEntries.map((entry) => entry[1]),
+] as const satisfies readonly QtiAssessmentItemPlayerAdapterPropName[];
+
+const qtiAssessmentItemPlayerAdapterPropNameSet = new Set<string>(
+  qtiAssessmentItemPlayerAdapterPropNames,
+);
+
+export function isQtiAssessmentItemPlayerAdapterPropName(name: string): boolean {
+  return qtiAssessmentItemPlayerAdapterPropNameSet.has(name);
+}
+
+export type QtiAssessmentItemPlayerLoadDependencies = readonly [
+  string | undefined,
+  QtiPlayerLoadOptions["status"] | undefined,
+  boolean | undefined,
+  boolean | undefined,
+  QtiPlayerFetchXml | undefined,
+  QtiPlayerResolveAsset | undefined,
+];
+
+export function qtiAssessmentItemPlayerLoadStateKey(
+  state: QtiAttemptStateV1 | undefined,
+): string | undefined {
+  if (!state) return undefined;
+  // JSON key order follows insertion order; in-place mutation without reload is not detected.
+  return JSON.stringify(state);
+}
+
+export function qtiAssessmentItemPlayerLoadDependencies(
+  loadOptions: QtiPlayerLoadOptions | undefined,
+): QtiAssessmentItemPlayerLoadDependencies {
+  return [
+    qtiAssessmentItemPlayerLoadStateKey(loadOptions?.state),
+    loadOptions?.status,
+    loadOptions?.sessionControl?.validateResponses,
+    loadOptions?.sessionControl?.showFeedback,
+    loadOptions?.fetchXml,
+    loadOptions?.resolveAsset,
+  ];
+}
+
+export function bindQtiAssessmentItemPlayerAdapterEvents(
+  element: QtiAssessmentItemPlayer,
+  getProps: () => QtiAssessmentItemPlayerAdapterProps,
+): () => void {
+  const removers = qtiAssessmentItemPlayerAdapterEventEntries.map(([eventName, propName]) => {
+    const listener = (event: Event) => {
+      const callback = getProps()[propName] as
+        | QtiAssessmentItemPlayerAdapterEventCallback<typeof eventName>
+        | undefined;
+      callback?.(
+        (event as CustomEvent<QtiAssessmentItemPlayerEventDetailMap[typeof eventName]>).detail,
+      );
+    };
+    element.addEventListener(eventName, listener);
+    return () => element.removeEventListener(eventName, listener);
+  });
+  return () => {
+    for (const remove of removers) remove();
+  };
+}
+
+export function syncQtiAssessmentItemPlayerAdapterChrome(
+  element: QtiAssessmentItemPlayer,
+  props: Pick<
+    QtiAssessmentItemPlayerAdapterProps,
+    "languageOfInterface" | "messageCatalog" | "messages"
+  >,
+): void {
+  element.languageOfInterface = props.languageOfInterface;
+  element.messageCatalog = props.messageCatalog;
+  element.messages = props.messages;
+}
+
+/** @deprecated Use {@link syncQtiAssessmentItemPlayerAdapterChrome}. */
+export const syncQtiAssessmentItemPlayerAdapterMessages = syncQtiAssessmentItemPlayerAdapterChrome;
+
+export interface QtiAssessmentItemPlayerAdapterLoadSyncInput {
+  xml?: string | undefined;
+  loadOptions?: QtiPlayerLoadOptions | undefined;
+  onLoadError?: ((error: Error) => void) | undefined;
+}
+
+export function createQtiAssessmentItemPlayerAdapterLoadSync(): {
+  run(
+    element: QtiAssessmentItemPlayer,
+    input: QtiAssessmentItemPlayerAdapterLoadSyncInput,
+  ): () => void;
+} {
+  let loadSequence = 0;
+
+  return {
+    run(element, input) {
+      if (input.xml === undefined) {
+        loadSequence += 1;
+        element.clearItem();
+        return () => {};
+      }
+
+      let active = true;
+      const sequence = (loadSequence += 1);
+      void element
+        .loadXml(input.xml, input.loadOptions)
+        .then(() => {
+          if (!active || sequence !== loadSequence) return;
+        })
+        .catch((error: unknown) => {
+          if (!active || sequence !== loadSequence) return;
+          input.onLoadError?.(normalizeQtiAssessmentItemPlayerLoadError(error));
+        });
+
+      return () => {
+        active = false;
+      };
+    },
+  };
+}
+
+export function createQtiAssessmentItemPlayerHandle(
+  getElement: () => QtiAssessmentItemPlayer | null,
+): QtiAssessmentItemPlayerHandle {
+  return {
+    get element() {
+      return requiredElement(getElement);
+    },
+    loadXml: (xml, options) => requiredElement(getElement).loadXml(xml, options),
+    loadUrl: (url, options) => requiredElement(getElement).loadUrl(url, options),
+    scoreAttempt: (options) => requiredElement(getElement).scoreAttempt(options),
+    restore: (state) => requiredElement(getElement).restore(state),
+    suspend: () => requiredElement(getElement).suspend(),
+    endAttempt: (options) => requiredElement(getElement).endAttempt(options),
+    reset: () => requiredElement(getElement).reset(),
+    clearItem: () => requiredElement(getElement).clearItem(),
+    serialize: () => requiredElement(getElement).serialize(),
+    getTextToSpeechTraversal: () => requiredElement(getElement).getTextToSpeechTraversal(),
+    getCatalogSupportResolution: (options) =>
+      requiredElement(getElement).getCatalogSupportResolution(options),
+  };
+}
+
+export function normalizeQtiAssessmentItemPlayerLoadError(error: unknown): Error {
+  return error instanceof Error ? error : new Error(String(error));
+}
+
+function requiredElement(
+  getElement: () => QtiAssessmentItemPlayer | null,
+): QtiAssessmentItemPlayer {
+  const element = getElement();
+  if (!element) throw new Error("QTI assessment item player element is not mounted.");
+  return element;
+}

package/src/player-dev.ts

@@ -0,0 +1,14 @@
+/** True when dev warnings are enabled (non-production Node, or browser without NODE_ENV). */
+export function playerDevWarningsEnabled(): boolean {
+  const nodeEnv = (globalThis as { process?: { env?: { NODE_ENV?: string } } }).process?.env
+    ?.NODE_ENV;
+  return nodeEnv !== "production";
+}
+
+const warnedKeys = new Set<string>();
+
+export function warnPlayerMessageOnce(code: string, message: string): void {
+  if (!playerDevWarningsEnabled() || warnedKeys.has(code)) return;
+  warnedKeys.add(code);
+  console.warn(`[qti3-player] ${message}`);
+}