@longsightgroup/qti3-player 0.2.0 → 0.3.0

package/src/interactions/text-interaction.ts

@@ -0,0 +1,127 @@
+import type { QtiInteraction, QtiValue } from "@longsightgroup/qti3-core";
+
+function scalarString(value: QtiValue): string {
+  if (value === null || Array.isArray(value) || typeof value === "object") return "";
+  return String(value);
+}
+
+function coerceResponseInputValue(
+  value: string,
+  baseType: QtiInteraction["responseBaseType"],
+): QtiValue {
+  if (baseType === "integer") return Number.parseInt(value, 10);
+  if (baseType === "float") return Number.parseFloat(value);
+  if (baseType === "boolean") {
+    if (value === "true") return true;
+    if (value === "false") return false;
+  }
+  return value;
+}
+
+function applyExpectedTextEntryWidth(
+  control: HTMLInputElement | HTMLTextAreaElement,
+  expectedLength: number,
+): void {
+  if (!(control instanceof HTMLInputElement) || expectedLength <= 0) return;
+  const width = Math.max(8, Math.min(expectedLength + 2, 72));
+  control.style.inlineSize = `${width}ch`;
+}
+
+export function renderTextResponse(
+  interaction: QtiInteraction,
+  update: (value: QtiValue) => void,
+  mode: "entry" | "extended",
+  currentValue: QtiValue,
+): HTMLElement {
+  const group = document.createElement("div");
+  group.className = "qti3-text-response";
+  const expectedLength = Number(interaction.attributes["expected-length"] ?? 0);
+  const expectedLines = Number(interaction.attributes["expected-lines"] ?? 0);
+  const control =
+    mode === "extended" ? document.createElement("textarea") : document.createElement("input");
+  control.className = mode === "extended" ? "qti3-textarea" : "qti3-text-input";
+  control.value = scalarString(currentValue);
+  control.setAttribute(
+    "aria-label",
+    interaction.prompt ?? (mode === "extended" ? "Extended text response" : "Text response"),
+  );
+  if (mode === "extended" && expectedLines > 0) {
+    (control as HTMLTextAreaElement).rows = expectedLines;
+  }
+  if (mode === "entry") {
+    applyExpectedTextEntryWidth(control, expectedLength);
+  }
+  const counter = mode === "extended" ? document.createElement("p") : undefined;
+  if (counter) {
+    counter.className = "qti3-counter";
+    counter.setAttribute("aria-live", "polite");
+  }
+  const sync = (emitResponse = true) => {
+    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`;
+    }
+    if (emitResponse) update(value);
+  };
+  control.addEventListener("input", () => sync());
+  control.addEventListener("change", () => sync());
+  sync(false);
+  group.append(control);
+  if (counter) group.append(counter);
+  return group;
+}
+
+export function renderInlineTextEntry(
+  interaction: QtiInteraction,
+  update: (value: QtiValue) => void,
+  currentValue: QtiValue,
+): HTMLElement {
+  const group = document.createElement("span");
+  group.className = "qti3-inline-text-response";
+  const input = document.createElement("input");
+  input.className = "qti3-text-input qti3-inline-text-input";
+  input.value = scalarString(currentValue);
+  input.setAttribute(
+    "aria-label",
+    interaction.prompt ?? interaction.contextText ?? "Text response",
+  );
+  const expectedLength = Number(interaction.attributes["expected-length"] ?? 0);
+  applyExpectedTextEntryWidth(input, expectedLength);
+  const sync = (emitResponse = true) => {
+    if (emitResponse) update(input.value);
+  };
+  input.addEventListener("input", () => sync());
+  input.addEventListener("change", () => sync());
+  sync(false);
+  group.append(input);
+  return group;
+}
+
+export function renderSliderResponse(
+  interaction: QtiInteraction,
+  update: (value: QtiValue) => void,
+  currentValue: QtiValue,
+): HTMLElement {
+  const group = document.createElement("div");
+  group.className = "qti3-slider-response";
+  const input = document.createElement("input");
+  input.type = "range";
+  input.min = interaction.attributes["lower-bound"] ?? "0";
+  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");
+  const output = document.createElement("output");
+  output.className = "qti3-slider-output";
+  output.value = input.value;
+  output.textContent = input.value;
+  const sync = () => {
+    output.value = input.value;
+    output.textContent = input.value;
+    update(coerceResponseInputValue(input.value, interaction.responseBaseType));
+  };
+  input.addEventListener("input", sync);
+  group.append(input, output);
+  return group;
+}

package/src/interactions/unsupported-interaction.ts

@@ -0,0 +1,25 @@
+import type { QtiInteraction } from "@longsightgroup/qti3-core";
+import { errorView } from "../player-validation.js";
+
+export function renderUnsupportedInteraction(interaction: QtiInteraction): HTMLElement {
+  const message = interaction.responseIdentifier
+    ? `Interaction type "${interaction.type}" (${interaction.responseIdentifier}) is not supported.`
+    : `Interaction type "${interaction.type}" is not supported.`;
+  const alert = errorView(message);
+  alert.className = "qti3-unsupported-interaction";
+  return alert;
+}
+
+export function renderUnsupportedEmbeddedInteraction(interaction: QtiInteraction): HTMLElement {
+  const message = interaction.responseIdentifier
+    ? `Interaction type "${interaction.type}" (${interaction.responseIdentifier}) cannot be embedded inline in item body.`
+    : `Interaction type "${interaction.type}" cannot be embedded inline in item body.`;
+  const alert = document.createElement("span");
+  alert.className = "qti3-embedded-interaction qti3-embedded-interaction-unsupported";
+  alert.role = "alert";
+  alert.textContent = message;
+  if (interaction.responseIdentifier) {
+    alert.dataset.responseIdentifier = interaction.responseIdentifier;
+  }
+  return alert;
+}

package/src/interactions/upload-interaction.ts

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

package/src/movement.ts

@@ -0,0 +1,29 @@
+import { inlineIcon } from "./icons.js";
+
+export type MovementDirection = "up" | "down" | "left" | "right";
+
+const movementIconPaths: Record<MovementDirection, string[]> = {
+  up: ["M12 5l0 14", "M18 11l-6 -6", "M6 11l6 -6"],
+  down: ["M12 5l0 14", "M18 13l-6 6", "M6 13l6 6"],
+  left: ["M5 12l14 0", "M5 12l6 6", "M5 12l6 -6"],
+  right: ["M5 12l14 0", "M13 18l6 -6", "M13 6l6 6"],
+};
+
+function movementIcon(direction: MovementDirection): SVGSVGElement {
+  return inlineIcon("qti3-movement-icon", movementIconPaths[direction]);
+}
+
+export function movementButton(
+  direction: MovementDirection,
+  accessibleName: string,
+  onClick: () => void,
+): HTMLButtonElement {
+  const button = document.createElement("button");
+  button.type = "button";
+  button.className = "qti3-icon-button qti3-move-button";
+  button.dataset.moveDirection = direction;
+  button.setAttribute("aria-label", accessibleName);
+  button.append(movementIcon(direction));
+  button.addEventListener("click", onClick);
+  return button;
+}

package/src/player/attempt-availability.ts

@@ -0,0 +1,36 @@
+export function syncAttemptAvailability(
+  root: ParentNode,
+  options: { completed: boolean; status: string; host?: HTMLElement },
+): void {
+  if (options.host) {
+    options.host.dataset.status = options.status;
+  }
+
+  const article = root.querySelector<HTMLElement>(".qti3-player");
+  if (article) article.dataset.status = options.status;
+
+  for (const control of root.querySelectorAll<
+    HTMLButtonElement | HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement
+  >(
+    ".qti3-interaction button, .qti3-interaction input, .qti3-interaction select, .qti3-interaction textarea",
+  )) {
+    control.disabled = options.completed;
+  }
+
+  for (const element of root.querySelectorAll<HTMLElement>(
+    ".qti3-interaction [tabindex]:not(button):not(input):not(select):not(textarea)",
+  )) {
+    if (options.completed) {
+      element.dataset.previousTabIndex = element.getAttribute("tabindex") ?? "0";
+      element.tabIndex = -1;
+      element.setAttribute("aria-disabled", "true");
+    } else {
+      const previous = element.dataset.previousTabIndex;
+      if (previous !== undefined) {
+        element.tabIndex = Number(previous);
+        delete element.dataset.previousTabIndex;
+      }
+      element.removeAttribute("aria-disabled");
+    }
+  }
+}

package/src/player/content-state.ts

@@ -0,0 +1,63 @@
+import {
+  qtiValueToString,
+  type QtiAttemptStateV1,
+  type QtiContentNode,
+  type QtiDocument,
+  type QtiValue,
+} from "@longsightgroup/qti3-core";
+import { contentNodeText } from "../content/content-dom.js";
+
+export function currentVariableValue(
+  state: QtiAttemptStateV1 | undefined,
+  identifier: string,
+): QtiValue {
+  return (
+    state?.outcomes[identifier] ??
+    state?.templateValues?.[identifier] ??
+    state?.responses[identifier] ??
+    null
+  );
+}
+
+export function currentTemplateValue(
+  state: QtiAttemptStateV1 | undefined,
+  identifier: string,
+): QtiValue {
+  return state?.templateValues?.[identifier] ?? null;
+}
+
+export function isFeedbackVisible(
+  node: Extract<QtiContentNode, { kind: "feedback" }>,
+  value: QtiValue,
+): boolean {
+  const hasIdentifier = Array.isArray(value)
+    ? value.map(String).includes(node.identifier)
+    : qtiValueToString(value) === node.identifier;
+  return node.showHide === "show" ? hasIdentifier : !hasIdentifier;
+}
+
+export function isTemplateContentVisible(element: HTMLElement, value: QtiValue): boolean {
+  const templateIdentifier = element.dataset.templateIdentifier;
+  const identifier = element.dataset.templateValueIdentifier;
+  if (!templateIdentifier || !identifier) return true;
+  const hasIdentifier = Array.isArray(value)
+    ? value.map(String).includes(identifier)
+    : qtiValueToString(value) === identifier;
+  return element.dataset.showHide === "hide" ? !hasIdentifier : hasIdentifier;
+}
+
+export function mathTemplateValue(
+  node: Extract<QtiContentNode, { kind: "element" }>,
+  documentModel: QtiDocument | undefined,
+  templateValue: QtiValue,
+): string | undefined {
+  if (node.qtiName !== "mi" && node.qtiName !== "mo") return undefined;
+  const identifier = contentNodeText(node).trim();
+  if (!identifier) return undefined;
+  const declaration = documentModel?.item.templateDeclarations.find(
+    (template) =>
+      template.identifier === identifier && template.attributes["math-variable"] === "true",
+  );
+  if (!declaration) return undefined;
+  return qtiValueToString(templateValue);
+}

package/src/player/dynamic-body.ts

@@ -0,0 +1,40 @@
+import { qtiValueToString, type QtiValue } from "@longsightgroup/qti3-core";
+import { formatPrintedValue } from "../content/content-dom.js";
+import { isTemplateContentVisible } from "./content-state.js";
+
+export interface DynamicBodyContext {
+  variableValue(identifier: string): QtiValue;
+  templateValue(identifier: string): QtiValue;
+}
+
+export function syncDynamicBodyState(root: ParentNode, context: DynamicBodyContext): void {
+  for (const output of root.querySelectorAll<HTMLOutputElement>(".qti3-printed-variable")) {
+    const identifier = output.dataset.identifier;
+    if (!identifier) continue;
+    output.value = formatPrintedValue(context.variableValue(identifier), output.dataset.format);
+    output.textContent = output.value;
+  }
+
+  for (const element of root.querySelectorAll<HTMLElement>(
+    ".qti3-feedback-block, .qti3-feedback-inline",
+  )) {
+    const identifier = element.dataset.feedbackIdentifier;
+    const outcomeIdentifier = element.dataset.outcomeIdentifier;
+    if (!identifier || !outcomeIdentifier) continue;
+    const value = context.variableValue(outcomeIdentifier);
+    const hasIdentifier = Array.isArray(value)
+      ? value.map(String).includes(identifier)
+      : qtiValueToString(value) === identifier;
+    element.hidden = element.dataset.showHide === "hide" ? hasIdentifier : !hasIdentifier;
+  }
+
+  for (const element of root.querySelectorAll<HTMLElement>(
+    ".qti3-template-block, .qti3-template-inline",
+  )) {
+    const templateIdentifier = element.dataset.templateIdentifier;
+    element.hidden = !isTemplateContentVisible(
+      element,
+      templateIdentifier ? context.templateValue(templateIdentifier) : null,
+    );
+  }
+}

package/src/player/feedback-panel.ts

@@ -0,0 +1,23 @@
+import {
+  visibleModalFeedback,
+  type QtiAssessmentItem,
+  type QtiValue,
+} from "@longsightgroup/qti3-core";
+
+export function syncFeedbackPanel(
+  feedback: HTMLElement | null,
+  item: QtiAssessmentItem,
+  outcomes: Record<string, QtiValue>,
+): void {
+  if (!feedback) return;
+  const visibleFeedback = visibleModalFeedback(item, outcomes);
+  feedback.replaceChildren(
+    ...visibleFeedback.map((entry) => {
+      const element = document.createElement("p");
+      element.dataset.feedbackIdentifier = entry.identifier;
+      element.textContent = entry.text;
+      return element;
+    }),
+  );
+  feedback.hidden = visibleFeedback.length === 0;
+}

package/src/player/fetch-xml.ts

@@ -0,0 +1,8 @@
+export async function defaultFetchXml(url: string): Promise<string> {
+  if (!globalThis.fetch) {
+    throw new Error("No fetch implementation is available. Provide loadUrl(url, { fetchXml }).");
+  }
+  const response = await globalThis.fetch(url);
+  if (!response.ok) throw new Error(`Failed to load QTI XML from ${url}: ${response.status}.`);
+  return response.text();
+}

package/src/player/interaction-render.ts

@@ -0,0 +1,89 @@
+import type { QtiInteraction, QtiValue } from "@longsightgroup/qti3-core";
+import { copySafeAttributes } from "../content/content-dom.js";
+import { renderInteractionResponse } from "../interactions/interaction-dispatch.js";
+import { interactionLabel, qtiSharedClassNames } from "../interactions/interaction-label.js";
+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 { inlineValidationMessageElement, validationMessageElement } from "../player-validation.js";
+
+export interface BlockInteractionRenderOptions {
+  interaction: QtiInteraction;
+  messages: QtiPlayerMessages;
+  update: (value: QtiValue) => void;
+  currentValue: QtiValue;
+  isCompleted: () => boolean;
+  endAttempt: () => void;
+  renderPortableCustom: (
+    interaction: QtiInteraction,
+    update: (value: QtiValue) => void,
+    currentValue: QtiValue,
+  ) => HTMLElement;
+}
+
+export function renderBlockInteractionSection(options: BlockInteractionRenderOptions): HTMLElement {
+  const {
+    interaction,
+    messages,
+    update,
+    currentValue,
+    isCompleted,
+    endAttempt,
+    renderPortableCustom,
+  } = options;
+  const field = document.createElement("section");
+  field.className = `qti3-interaction qti3-${interaction.type}`;
+  field.classList.add(...qtiSharedClassNames(interaction.attributes.class));
+  field.dataset.interactionType = interaction.type;
+  if (interaction.responseIdentifier)
+    field.dataset.responseIdentifier = interaction.responseIdentifier;
+
+  const heading = document.createElement("h3");
+  copySafeAttributes(heading, interaction.promptAttributes ?? {});
+  heading.textContent = interactionLabel(interaction);
+  field.append(heading);
+  if (interaction.responseIdentifier) {
+    field.append(validationMessageElement(interaction.responseIdentifier));
+  }
+
+  field.append(
+    renderInteractionResponse({
+      interaction,
+      update,
+      currentValue,
+      messages,
+      isCompleted,
+      endAttempt,
+      renderPortableCustom,
+    }),
+  );
+  return field;
+}
+
+export function renderEmbeddedInteractionSection(
+  interaction: QtiInteraction,
+  update: (value: QtiValue) => void,
+  currentValue: QtiValue,
+  messages: QtiPlayerMessages,
+): HTMLElement {
+  if (interaction.type !== "inlineChoice" && interaction.type !== "textEntry") {
+    return renderUnsupportedEmbeddedInteraction(interaction);
+  }
+
+  const wrapper = document.createElement("span");
+  wrapper.className = `qti3-interaction qti3-${interaction.type} qti3-embedded-interaction`;
+  wrapper.dataset.interactionType = interaction.type;
+  if (interaction.responseIdentifier)
+    wrapper.dataset.responseIdentifier = interaction.responseIdentifier;
+
+  if (interaction.responseIdentifier) {
+    wrapper.append(inlineValidationMessageElement(interaction.responseIdentifier));
+  }
+  wrapper.append(
+    interaction.type === "inlineChoice"
+      ? renderSelect(interaction, update, currentValue, messages)
+      : renderInlineTextEntry(interaction, update, currentValue),
+  );
+  return wrapper;
+}

package/src/player/render-shell.ts

@@ -0,0 +1,44 @@
+import type { QtiDocument, QtiInteraction } from "@longsightgroup/qti3-core";
+import { renderContentNodes, type PlayerContentContext } from "../content/content-renderer.js";
+import { playerStyleElement } from "../player-styles.js";
+
+export function renderPlayerShell(options: {
+  documentModel: QtiDocument;
+  contentContext: PlayerContentContext;
+  renderStandaloneInteraction: (interaction: QtiInteraction) => HTMLElement;
+}): HTMLElement {
+  const { documentModel, contentContext, renderStandaloneInteraction } = options;
+  const root = document.createElement("article");
+  root.className = "qti3-player";
+  if (documentModel.item.language) {
+    root.lang = documentModel.item.language;
+    root.setAttribute("xml:lang", documentModel.item.language);
+  }
+  root.append(playerStyleElement());
+
+  if (documentModel.item.prompt && documentModel.item.body.length === 0) {
+    const prompt = document.createElement("p");
+    prompt.className = "qti3-item-prompt";
+    prompt.textContent = documentModel.item.prompt;
+    root.append(prompt);
+  }
+
+  if (documentModel.item.body.length > 0) {
+    const body = document.createElement("div");
+    body.className = "qti3-item-body";
+    body.append(...renderContentNodes(documentModel.item.body, contentContext));
+    root.append(body);
+  } else {
+    for (const interaction of documentModel.item.interactions) {
+      root.append(renderStandaloneInteraction(interaction));
+    }
+  }
+
+  const feedback = document.createElement("section");
+  feedback.className = "qti3-feedback";
+  feedback.role = "status";
+  feedback.setAttribute("aria-live", "polite");
+  feedback.hidden = true;
+  root.append(feedback);
+  return root;
+}

package/src/player/resolve-assets.ts

@@ -0,0 +1,12 @@
+import { isResolvableAssetUrl } from "../content/content-dom.js";
+import type { QtiPlayerResolveAsset } from "../player-types.js";
+
+export function resolveRenderedAssets(root: ParentNode, resolveAsset: QtiPlayerResolveAsset): void {
+  for (const element of root.querySelectorAll("[src], [href], [data]")) {
+    for (const attribute of ["src", "href", "data"]) {
+      const value = element.getAttribute(attribute);
+      if (!value || !isResolvableAssetUrl(value)) continue;
+      element.setAttribute(attribute, resolveAsset(value));
+    }
+  }
+}

package/src/player/validation-messages.ts

@@ -0,0 +1,42 @@
+import type { QtiDiagnostic } from "@longsightgroup/qti3-core";
+
+/** Load-time item structure problems emitted during `loadXml` and mirrored into validation UI. */
+export const AUTHORING_DIAGNOSTIC_CODES = new Set<string>([
+  "interaction.unsupported",
+  "interaction.choices.missing",
+  "interaction.embed.unsupported",
+]);
+
+export function isAuthoringDiagnostic(diagnostic: QtiDiagnostic): boolean {
+  return AUTHORING_DIAGNOSTIC_CODES.has(diagnostic.code);
+}
+
+/** Response-scoring and attempt validation messages persisted separately from authoring diagnostics. */
+export function responseValidationMessages(messages: QtiDiagnostic[]): QtiDiagnostic[] {
+  return messages.filter((message) => !isAuthoringDiagnostic(message));
+}
+
+export function mergeVisibleValidationMessages(
+  authoringDiagnostics: QtiDiagnostic[],
+  validationMessages: QtiDiagnostic[],
+): QtiDiagnostic[] {
+  return [...authoringDiagnostics, ...validationMessages];
+}
+
+/**
+ * Serialized attempt state stores both authoring and response validation messages together.
+ * After restore, split response messages back out so they are not duplicated against
+ * load-time `authoringDiagnostics`.
+ */
+export function splitSerializedValidationMessages(messages: QtiDiagnostic[]): {
+  authoringDiagnostics: QtiDiagnostic[];
+  validationMessages: QtiDiagnostic[];
+} {
+  const authoringDiagnostics: QtiDiagnostic[] = [];
+  const validationMessages: QtiDiagnostic[] = [];
+  for (const message of messages) {
+    if (isAuthoringDiagnostic(message)) authoringDiagnostics.push(message);
+    else validationMessages.push(message);
+  }
+  return { authoringDiagnostics, validationMessages };
+}