@longsightgroup/qti3-player 0.2.0 → 0.3.0

package/src/interactions/hotspot-interaction.ts

@@ -0,0 +1,87 @@
+import type { QtiInteraction, QtiValue } from "@longsightgroup/qti3-core";
+import {
+  applyGraphicSurfaceLayout,
+  appendGraphicObjectImage,
+  interactionChoices,
+  missingChoicesMessage,
+  objectHeight,
+  objectWidth,
+  placeHotspotButton,
+  readableType,
+  responseGroup,
+  valueToStrings,
+} from "../interaction-support.js";
+import type { QtiPlayerMessages } from "../player-messages.js";
+
+export function renderHotspotResponse(
+  interaction: QtiInteraction,
+  update: (value: QtiValue) => void,
+  currentValue: QtiValue,
+  messages: QtiPlayerMessages,
+): HTMLElement {
+  const group = responseGroup();
+
+  const surface = document.createElement("div");
+  const width = objectWidth(interaction);
+  const height = objectHeight(interaction);
+  applyGraphicSurfaceLayout(surface, width, height, "qti3-hotspot-surface");
+
+  const choices = interactionChoices(interaction);
+  if (choices.length === 0) {
+    group.append(missingChoicesMessage(interaction));
+    return group;
+  }
+
+  const object = interaction.object;
+  if (object) {
+    appendGraphicObjectImage(
+      surface,
+      object,
+      object.text || `${readableType(interaction.type)} image`,
+    );
+  }
+
+  const selected = new Set(valueToStrings(currentValue));
+  const multiple = interaction.responseCardinality === "multiple";
+  const selectedSummary = document.createElement("p");
+  selectedSummary.className = "qti3-selection-summary";
+  selectedSummary.setAttribute("aria-live", "polite");
+  selectedSummary.textContent = messages.noRegionSelected();
+  const syncSelected = () => {
+    for (const button of surface.querySelectorAll<HTMLButtonElement>("button")) {
+      const isSelected = selected.has(button.dataset.choiceIdentifier ?? "");
+      button.setAttribute("aria-pressed", isSelected ? "true" : "false");
+      button.dataset.selected = isSelected ? "true" : "false";
+    }
+    selectedSummary.textContent =
+      selected.size > 0 ? `Selected ${[...selected].join(", ")}` : messages.noRegionSelected();
+  };
+  for (const choice of choices) {
+    const button = document.createElement("button");
+    button.type = "button";
+    button.className = "qti3-hotspot-button";
+    button.dataset.choiceIdentifier = choice.identifier;
+    button.textContent = choice.text;
+    button.title = choice.text;
+    button.setAttribute("aria-pressed", "false");
+    placeHotspotButton(button, choice, width, height);
+    button.addEventListener("click", () => {
+      if (multiple) {
+        if (selected.has(choice.identifier)) selected.delete(choice.identifier);
+        else selected.add(choice.identifier);
+        syncSelected();
+        update([...selected]);
+      } else {
+        selected.clear();
+        selected.add(choice.identifier);
+        syncSelected();
+        update(choice.identifier);
+      }
+    });
+    surface.append(button);
+  }
+
+  syncSelected();
+  group.append(surface, selectedSummary);
+  return group;
+}

package/src/interactions/hottext-interaction.ts

@@ -0,0 +1,81 @@
+import type { QtiInteraction, QtiValue } from "@longsightgroup/qti3-core";
+import {
+  interactionChoices,
+  missingChoicesMessage,
+  valueToStrings,
+} from "../interaction-support.js";
+import { appendInlineControl, normalizeInlineSegmentText } from "./inline-controls.js";
+
+export function renderHottextResponse(
+  interaction: QtiInteraction,
+  update: (value: QtiValue) => void,
+  currentValue: QtiValue,
+): HTMLElement {
+  const group = document.createElement("div");
+  group.className = "qti3-hottext-group";
+  group.role = "group";
+  group.setAttribute("aria-label", "Hottext options");
+
+  const selected = new Set(valueToStrings(currentValue));
+  const multiple =
+    interaction.responseCardinality === "multiple" || interaction.responseCardinality === "ordered";
+  const passage = document.createElement("p");
+  passage.className = "qti3-hottext-passage";
+
+  const syncSelected = () => {
+    for (const button of passage.querySelectorAll<HTMLButtonElement>(".qti3-hottext-token")) {
+      const identifier = button.dataset.choiceIdentifier ?? "";
+      const isSelected = selected.has(identifier);
+      button.dataset.selected = isSelected ? "true" : "false";
+      button.setAttribute("aria-pressed", String(isSelected));
+    }
+  };
+
+  const segments =
+    interaction.hottextSegments && interaction.hottextSegments.length > 0
+      ? interaction.hottextSegments
+      : interactionChoices(interaction).map((choice) => ({
+          kind: "hottext" as const,
+          identifier: choice.identifier,
+          text: choice.text,
+          attributes: choice.attributes,
+          source: choice.source,
+        }));
+
+  if (segments.length === 0) {
+    group.append(missingChoicesMessage(interaction));
+    return group;
+  }
+
+  const content: Array<Node | string> = [];
+  for (const [segmentIndex, segment] of segments.entries()) {
+    if (segment.kind === "text") {
+      content.push(document.createTextNode(normalizeInlineSegmentText(segment.text)));
+      continue;
+    }
+
+    const button = document.createElement("button");
+    button.type = "button";
+    button.className = "qti3-hottext-token";
+    button.dataset.choiceIdentifier = segment.identifier;
+    button.textContent = segment.text;
+    button.addEventListener("click", () => {
+      if (multiple) {
+        if (selected.has(segment.identifier)) selected.delete(segment.identifier);
+        else selected.add(segment.identifier);
+        update([...selected]);
+      } else {
+        selected.clear();
+        selected.add(segment.identifier);
+        update(segment.identifier);
+      }
+      syncSelected();
+    });
+    appendInlineControl(content, button, segments[segmentIndex + 1]);
+  }
+
+  passage.append(...content);
+  syncSelected();
+  group.append(passage);
+  return group;
+}

package/src/interactions/inline-choice-interaction.ts

@@ -0,0 +1,45 @@
+import type { QtiChoice, QtiInteraction, QtiValue } from "@longsightgroup/qti3-core";
+import {
+  interactionChoices,
+  missingChoicesMessage,
+  valueToStrings,
+} from "../interaction-support.js";
+import type { QtiPlayerMessages } from "../player-messages.js";
+import { interactionLabel } from "./interaction-label.js";
+
+function appendOptions(
+  select: HTMLSelectElement,
+  choices: QtiChoice[],
+  messages: QtiPlayerMessages,
+): void {
+  const empty = document.createElement("option");
+  empty.value = "";
+  empty.textContent = messages.inlineChoicePrompt();
+  select.append(empty);
+  for (const choice of choices) {
+    const option = document.createElement("option");
+    option.value = choice.identifier;
+    option.textContent = choice.text;
+    select.append(option);
+  }
+}
+
+export function renderSelect(
+  interaction: QtiInteraction,
+  update: (value: QtiValue) => void,
+  currentValue: QtiValue,
+  messages: QtiPlayerMessages,
+): HTMLElement {
+  const choices = interactionChoices(interaction);
+  if (choices.length === 0) return missingChoicesMessage(interaction);
+
+  const select = document.createElement("select");
+  select.className = "qti3-inline-select";
+  if (interaction.responseIdentifier) select.name = interaction.responseIdentifier;
+  select.setAttribute("aria-label", interactionLabel(interaction));
+  appendOptions(select, choices, messages);
+  const [selected] = valueToStrings(currentValue);
+  if (selected) select.value = selected;
+  select.addEventListener("change", () => update(select.value === "" ? null : select.value));
+  return select;
+}

package/src/interactions/inline-controls.ts

@@ -0,0 +1,21 @@
+export function appendInlineControl(
+  content: Array<Node | string>,
+  control: HTMLElement,
+  nextSegment: { kind: string; text?: string } | undefined,
+): void {
+  const previous = content.at(-1);
+  if (previous instanceof Text && !/\s$/.test(previous.data)) {
+    content.push(document.createTextNode(" "));
+  }
+  content.push(control);
+
+  const nextText =
+    nextSegment?.kind === "text" ? normalizeInlineSegmentText(nextSegment.text) : undefined;
+  if (nextText && !/^\s|^[,.;:!?]/.test(nextText)) {
+    content.push(document.createTextNode(" "));
+  }
+}
+
+export function normalizeInlineSegmentText(value: string | undefined): string {
+  return (value ?? "").replace(/\s+([,.;:!?])/g, "$1");
+}

package/src/interactions/interaction-diagnostics.ts

@@ -0,0 +1,159 @@
+import type {
+  QtiAssessmentItem,
+  QtiContentNode,
+  QtiDiagnostic,
+  QtiInteraction,
+} from "@longsightgroup/qti3-core";
+import { contentElementName } from "../content/content-dom.js";
+import { interactionChoices } from "../interaction-support.js";
+import { sourceChoices, targetChoices } from "./shared.js";
+import { isInteractionSupported } from "./interaction-registry.js";
+
+function diagnosticPath(interaction: QtiInteraction): string | undefined {
+  return interaction.responseIdentifier ?? undefined;
+}
+
+export function interactionMissingChoiceDiagnostics(interaction: QtiInteraction): QtiDiagnostic[] {
+  if (!interactionRequiresChoices(interaction) || interactionHasRequiredChoices(interaction)) {
+    return [];
+  }
+  const path = diagnosticPath(interaction);
+  return [
+    {
+      code: "interaction.choices.missing",
+      severity: "error",
+      message: `No choices are defined for the ${interaction.type} interaction${path ? ` (${path})` : ""}.`,
+      path,
+    },
+  ];
+}
+
+export function interactionUnsupportedDiagnostics(interaction: QtiInteraction): QtiDiagnostic[] {
+  if (isInteractionSupported(interaction)) return [];
+  const path = diagnosticPath(interaction);
+  return [
+    {
+      code: "interaction.unsupported",
+      severity: "error",
+      message: path
+        ? `Interaction type "${interaction.type}" (${path}) is not supported.`
+        : `Interaction type "${interaction.type}" is not supported.`,
+      path,
+    },
+  ];
+}
+
+export function collectInteractionRenderDiagnostics(
+  interactions: QtiInteraction[],
+): QtiDiagnostic[] {
+  return interactions.flatMap((interaction) => [
+    ...interactionUnsupportedDiagnostics(interaction),
+    ...interactionMissingChoiceDiagnostics(interaction),
+  ]);
+}
+
+const embeddableInteractionTypes = new Set<QtiInteraction["type"]>(["inlineChoice", "textEntry"]);
+
+export function interactionEmbeddedDiagnostics(interaction: QtiInteraction): QtiDiagnostic[] {
+  if (embeddableInteractionTypes.has(interaction.type)) return [];
+  const path = diagnosticPath(interaction);
+  return [
+    {
+      code: "interaction.embed.unsupported",
+      severity: "error",
+      message: path
+        ? `Interaction type "${interaction.type}" (${path}) cannot be embedded inline in item body.`
+        : `Interaction type "${interaction.type}" cannot be embedded inline in item body.`,
+      path,
+    },
+  ];
+}
+
+export function collectEmbeddedInteractionDiagnostics(item: QtiAssessmentItem): QtiDiagnostic[] {
+  const embeddedIndices = findEmbeddedInteractionIndices(item.body);
+  return embeddedIndices.flatMap((index) => {
+    const interaction = item.interactions[index];
+    return interaction ? interactionEmbeddedDiagnostics(interaction) : [];
+  });
+}
+
+function findEmbeddedInteractionIndices(nodes: QtiContentNode[]): number[] {
+  return nodes.flatMap((node) => findEmbeddedInteractionIndicesInContext(node, false));
+}
+
+function findEmbeddedInteractionIndicesInContext(
+  node: QtiContentNode,
+  insideInlineFlow: boolean,
+): number[] {
+  if (node.kind === "interaction") {
+    return insideInlineFlow ? [node.interactionIndex] : [];
+  }
+  if ("children" in node) {
+    const childInsideInlineFlow = insideInlineFlow || isInlineFlowContainer(node);
+    return node.children.flatMap((child) =>
+      findEmbeddedInteractionIndicesInContext(child, childInsideInlineFlow),
+    );
+  }
+  return [];
+}
+
+function isInlineFlowContainer(node: QtiContentNode): boolean {
+  if (node.kind !== "element") return false;
+  if (node.qtiName === "qti-template-inline") return true;
+  if (node.qtiName === "p") return true;
+  const tag = contentElementName(node.qtiName);
+  if (!tag) return false;
+  return new Set(["span", "label", "a", "em", "strong", "b", "i", "sub", "sup", "small"]).has(tag);
+}
+
+function interactionRequiresChoices(interaction: QtiInteraction): boolean {
+  switch (interaction.type) {
+    case "choice":
+    case "order":
+    case "graphicOrder":
+    case "hotspot":
+    case "hottext":
+    case "inlineChoice":
+    case "match":
+    case "associate":
+    case "gapMatch":
+    case "graphicGapMatch":
+    case "graphicAssociate":
+      return true;
+    default:
+      return false;
+  }
+}
+
+function interactionHasRequiredChoices(interaction: QtiInteraction): boolean {
+  switch (interaction.type) {
+    case "choice":
+    case "inlineChoice":
+      return interactionChoices(interaction).length > 0;
+    case "order":
+      return interactionChoices(interaction).some((choice) => choice.role !== "gap");
+    case "graphicOrder":
+    case "hotspot":
+    case "graphicAssociate":
+      return interactionChoices(interaction).some((choice) => choice.role === "hotspot");
+    case "hottext":
+      return (
+        Boolean(interaction.hottextSegments?.length) || interactionChoices(interaction).length > 0
+      );
+    case "match":
+    case "associate":
+      return sourceChoices(interaction).length > 0 && targetChoices(interaction).length > 0;
+    case "gapMatch":
+      return sourceChoices(interaction).length > 0 && targetChoices(interaction).length > 0;
+    case "graphicGapMatch":
+      if (interaction.object && interaction.choices.some((choice) => choice.role === "hotspot")) {
+        return (
+          sourceChoices(interaction).length > 0 &&
+          targetChoices(interaction).filter((choice) => choice.role === "hotspot").length > 0
+        );
+      }
+      return sourceChoices(interaction).length > 0 && targetChoices(interaction).length > 0;
+    default:
+      return true;
+  }
+}

package/src/interactions/interaction-dispatch.ts

@@ -0,0 +1,9 @@
+export {
+  interactionRegistry,
+  isInteractionSupported,
+  matchInteractionRegistryEntry,
+  renderInteractionResponse,
+  type InteractionRegistryEntry,
+  type InteractionRendererId,
+  type InteractionResponseContext,
+} from "./interaction-registry.js";

package/src/interactions/interaction-label.ts

@@ -0,0 +1,10 @@
+import type { QtiInteraction } from "@longsightgroup/qti3-core";
+import { readableType } from "../interaction-support.js";
+
+export function interactionLabel(interaction: QtiInteraction): string {
+  return interaction.prompt ?? interaction.contextText ?? readableType(interaction.type);
+}
+
+export function qtiSharedClassNames(value: string | undefined): string[] {
+  return (value ?? "").split(/\s+/).filter((className) => className.startsWith("qti-"));
+}

package/src/interactions/interaction-registry.ts

@@ -0,0 +1,209 @@
+import type { QtiInteraction, QtiValue } from "@longsightgroup/qti3-core";
+import type { QtiPlayerMessages } from "../player-messages.js";
+import { renderGraphicOrderResponse } from "../reorder/graphic-order-interaction.js";
+import { renderOrderedResponse } from "../reorder/order-interaction.js";
+import { renderChoice } from "./choice-interaction.js";
+import { renderDrawingResponse } from "./drawing-interaction.js";
+import { renderEndAttemptResponse } from "./end-attempt-interaction.js";
+import { renderGapMatchResponse } from "./gap-match-interaction.js";
+import { renderGraphicAssociateResponse } from "./graphic-associate-interaction.js";
+import { renderHotspotResponse } from "./hotspot-interaction.js";
+import { renderHottextResponse } from "./hottext-interaction.js";
+import { renderSelect } from "./inline-choice-interaction.js";
+import { renderMatchResponse } from "./match-interaction.js";
+import { renderObjectAsset } from "./object-asset.js";
+import { renderPairResponse } from "./pair-interaction.js";
+import { renderPositionObjectResponse } from "./position-object-interaction.js";
+import { usesChoiceSet, usesOrderedResponse, usesPairResponse } from "./routing.js";
+import { renderSelectPointResponse } from "./select-point-interaction.js";
+import { renderSliderResponse, renderTextResponse } from "./text-interaction.js";
+import { renderUnsupportedInteraction } from "./unsupported-interaction.js";
+import { renderUploadResponse } from "./upload-interaction.js";
+
+export interface InteractionResponseContext {
+  interaction: QtiInteraction;
+  update: (value: QtiValue) => void;
+  currentValue: QtiValue;
+  messages: QtiPlayerMessages;
+  isCompleted: () => boolean;
+  endAttempt: () => void;
+  renderPortableCustom: (
+    interaction: QtiInteraction,
+    update: (value: QtiValue) => void,
+    currentValue: QtiValue,
+  ) => HTMLElement;
+}
+
+export type InteractionRendererId =
+  | "graphicOrder"
+  | "ordered"
+  | "gapMatch"
+  | "graphicAssociate"
+  | "match"
+  | "pair"
+  | "hotspot"
+  | "hottext"
+  | "choice"
+  | "inlineChoice"
+  | "extendedText"
+  | "selectPoint"
+  | "positionObject"
+  | "drawing"
+  | "portableCustom"
+  | "textEntry"
+  | "slider"
+  | "upload"
+  | "endAttempt"
+  | "media";
+
+type InteractionRenderer = (context: InteractionResponseContext) => HTMLElement;
+
+export interface InteractionRegistryEntry {
+  id: InteractionRendererId;
+  matches: (interaction: QtiInteraction) => boolean;
+  render: InteractionRenderer;
+}
+
+export const interactionRegistry: InteractionRegistryEntry[] = [
+  {
+    id: "graphicOrder",
+    matches: (interaction) => interaction.type === "graphicOrder",
+    render: ({ interaction, update, currentValue, messages }) =>
+      renderGraphicOrderResponse(interaction, update, currentValue, messages),
+  },
+  {
+    id: "ordered",
+    matches: usesOrderedResponse,
+    render: ({ interaction, update, currentValue, messages }) =>
+      renderOrderedResponse(interaction, update, currentValue, messages),
+  },
+  {
+    id: "gapMatch",
+    matches: (interaction) =>
+      interaction.type === "gapMatch" || interaction.type === "graphicGapMatch",
+    render: ({ interaction, update, currentValue }) =>
+      renderGapMatchResponse(interaction, update, currentValue),
+  },
+  {
+    id: "graphicAssociate",
+    matches: (interaction) => interaction.type === "graphicAssociate",
+    render: ({ interaction, update, currentValue, messages }) =>
+      renderGraphicAssociateResponse(interaction, update, currentValue, messages),
+  },
+  {
+    id: "match",
+    matches: (interaction) => interaction.type === "match",
+    render: ({ interaction, update, currentValue, messages }) =>
+      renderMatchResponse(interaction, update, currentValue, messages),
+  },
+  {
+    id: "pair",
+    matches: usesPairResponse,
+    render: ({ interaction, update, currentValue, messages }) =>
+      renderPairResponse(interaction, update, currentValue, messages),
+  },
+  {
+    id: "hotspot",
+    matches: (interaction) => interaction.type === "hotspot" && Boolean(interaction.object),
+    render: ({ interaction, update, currentValue, messages }) =>
+      renderHotspotResponse(interaction, update, currentValue, messages),
+  },
+  {
+    id: "hottext",
+    matches: (interaction) => interaction.type === "hottext",
+    render: ({ interaction, update, currentValue }) =>
+      renderHottextResponse(interaction, update, currentValue),
+  },
+  {
+    id: "choice",
+    matches: usesChoiceSet,
+    render: ({ interaction, update, currentValue }) =>
+      renderChoice(interaction, update, currentValue),
+  },
+  {
+    id: "inlineChoice",
+    matches: (interaction) => interaction.type === "inlineChoice",
+    render: ({ interaction, update, currentValue, messages }) =>
+      renderSelect(interaction, update, currentValue, messages),
+  },
+  {
+    id: "extendedText",
+    matches: (interaction) => interaction.type === "extendedText",
+    render: ({ interaction, update, currentValue }) =>
+      renderTextResponse(interaction, update, "extended", currentValue),
+  },
+  {
+    id: "selectPoint",
+    matches: (interaction) => interaction.type === "selectPoint",
+    render: ({ interaction, update, currentValue, messages }) =>
+      renderSelectPointResponse(interaction, update, currentValue, messages),
+  },
+  {
+    id: "positionObject",
+    matches: (interaction) => interaction.type === "positionObject",
+    render: ({ interaction, update, currentValue, messages }) =>
+      renderPositionObjectResponse(interaction, update, currentValue, messages),
+  },
+  {
+    id: "drawing",
+    matches: (interaction) => interaction.type === "drawing",
+    render: ({ interaction, update, currentValue, messages }) =>
+      renderDrawingResponse(interaction, update, currentValue, messages),
+  },
+  {
+    id: "portableCustom",
+    matches: (interaction) => interaction.type === "portableCustom",
+    render: ({ interaction, update, currentValue, renderPortableCustom }) =>
+      renderPortableCustom(interaction, update, currentValue),
+  },
+  {
+    id: "textEntry",
+    matches: (interaction) => interaction.type === "textEntry",
+    render: ({ interaction, update, currentValue }) =>
+      renderTextResponse(interaction, update, "entry", currentValue),
+  },
+  {
+    id: "slider",
+    matches: (interaction) => interaction.type === "slider",
+    render: ({ interaction, update, currentValue }) =>
+      renderSliderResponse(interaction, update, currentValue),
+  },
+  {
+    id: "upload",
+    matches: (interaction) => interaction.type === "upload",
+    render: ({ interaction, update, messages }) =>
+      renderUploadResponse(interaction, update, messages),
+  },
+  {
+    id: "endAttempt",
+    matches: (interaction) => interaction.type === "endAttempt",
+    render: ({ interaction, update, endAttempt, messages }) =>
+      renderEndAttemptResponse(interaction, update, endAttempt, messages),
+  },
+  {
+    id: "media",
+    matches: (interaction) => interaction.type === "media",
+    render: ({ interaction, update, currentValue, isCompleted }) =>
+      renderObjectAsset(interaction, {
+        currentValue,
+        update,
+        isCompleted,
+      }),
+  },
+];
+
+export function matchInteractionRegistryEntry(
+  interaction: QtiInteraction,
+): InteractionRegistryEntry | undefined {
+  return interactionRegistry.find((entry) => entry.matches(interaction));
+}
+
+export function isInteractionSupported(interaction: QtiInteraction): boolean {
+  return matchInteractionRegistryEntry(interaction) !== undefined;
+}
+
+export function renderInteractionResponse(context: InteractionResponseContext): HTMLElement {
+  const entry = matchInteractionRegistryEntry(context.interaction);
+  if (entry) return entry.render(context);
+  return renderUnsupportedInteraction(context.interaction);
+}