@longsightgroup/qti3-player 0.2.1 → 0.3.0

package/src/interaction-support.ts

@@ -0,0 +1,263 @@
+import { qtiValueToIdentifierList } from "@longsightgroup/qti3-core";
+import type {
+  QtiChoice,
+  QtiInteraction,
+  QtiObjectAsset,
+  QtiValue,
+} from "@longsightgroup/qti3-core";
+import { errorView } from "./player-validation.js";
+
+export function responseGroup(className?: string): HTMLElement {
+  const group = document.createElement("div");
+  group.className = ["qti3-response-group", className].filter(Boolean).join(" ");
+  return group;
+}
+
+export function interactionChoices(interaction: QtiInteraction): QtiChoice[] {
+  return interaction.choices;
+}
+
+export function missingChoicesMessage(interaction: QtiInteraction): HTMLElement {
+  const identifier = interaction.responseIdentifier ? ` (${interaction.responseIdentifier})` : "";
+  return errorView(`No choices are defined for the ${interaction.type} interaction${identifier}.`);
+}
+
+export function applyGraphicSurfaceLayout(
+  surface: HTMLElement,
+  width: number,
+  height: number,
+  ...classNames: string[]
+): void {
+  surface.classList.add("qti3-graphic-surface", ...classNames);
+  applyResponsiveGraphicSize(surface, width, height);
+}
+
+export function applyResponsiveGraphicSize(
+  element: HTMLElement | SVGSVGElement,
+  width: number,
+  height: number,
+): void {
+  element.style.display = "block";
+  element.style.inlineSize = "100%";
+  element.style.maxInlineSize = `${width}px`;
+  element.style.aspectRatio = `${width} / ${height}`;
+}
+
+export function choiceSelector(identifier: string): string {
+  return `[data-choice-identifier="${CSS.escape(identifier)}"]`;
+}
+
+export function valueToStrings(value: QtiValue): string[] {
+  return qtiValueToIdentifierList(value);
+}
+
+export function orderChoicesFromValue(choices: QtiChoice[], value: QtiValue): QtiChoice[] {
+  const identifiers = valueToStrings(value);
+  if (identifiers.length === 0) return [...choices];
+  const byIdentifier = new Map(choices.map((choice) => [choice.identifier, choice]));
+  const ordered = identifiers
+    .map((identifier) => byIdentifier.get(identifier))
+    .filter((choice): choice is QtiChoice => Boolean(choice));
+  const used = new Set(ordered.map((choice) => choice.identifier));
+  ordered.push(...choices.filter((choice) => !used.has(choice.identifier)));
+  return ordered;
+}
+
+export function readableType(type: string): string {
+  return type
+    .replace(/[A-Z]/g, (letter) => ` ${letter.toLowerCase()}`)
+    .replace(/^./, (letter) => letter.toUpperCase());
+}
+
+function dimension(value: string | undefined, fallback: number): number {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+export function objectWidth(interaction: QtiInteraction): number {
+  return dimension(interaction.object?.width, 160);
+}
+
+export function objectHeight(interaction: QtiInteraction): number {
+  return dimension(interaction.object?.height, 120);
+}
+
+export function objectIsImage(object: QtiObjectAsset): boolean {
+  return Boolean(
+    object.type?.startsWith("image/") ||
+    object.data?.startsWith("data:image/") ||
+    /\.(svg|png|jpg|jpeg|gif|webp)(?:[?#].*)?$/i.test(object.data ?? ""),
+  );
+}
+
+export function appendGraphicObjectImage(
+  surface: HTMLElement,
+  object: QtiObjectAsset,
+  alt: string,
+): void {
+  if (!object.data || !objectIsImage(object)) return;
+  const image = document.createElement("img");
+  image.className = "qti3-graphic-object-image";
+  image.src = object.data;
+  image.alt = alt;
+  surface.append(image);
+}
+
+function percent(value: number, total: number): number {
+  if (total <= 0) return 0;
+  return (value / total) * 100;
+}
+
+export { percent };
+
+function hotspotCoords(choice: QtiChoice): number[] {
+  return (choice.attributes.coords ?? "")
+    .split(",")
+    .map((value) => Number(value.trim()))
+    .filter((value) => Number.isFinite(value));
+}
+
+export function applyGraphicRegionPlacement(
+  element: HTMLElement,
+  placement: {
+    insetInlineStart: string;
+    insetBlockStart: string;
+    inlineSize?: string;
+    blockSize?: string;
+    shape?: string;
+  },
+): void {
+  element.style.setProperty("--qti3-graphic-region-inline-start", placement.insetInlineStart);
+  element.style.setProperty("--qti3-graphic-region-block-start", placement.insetBlockStart);
+  if (placement.inlineSize !== undefined) {
+    element.style.setProperty("--qti3-graphic-region-inline-size", placement.inlineSize);
+  } else {
+    element.style.removeProperty("--qti3-graphic-region-inline-size");
+  }
+  if (placement.blockSize !== undefined) {
+    element.style.setProperty("--qti3-graphic-region-block-size", placement.blockSize);
+  } else {
+    element.style.removeProperty("--qti3-graphic-region-block-size");
+  }
+  if (placement.shape) element.dataset.shape = placement.shape;
+  else delete element.dataset.shape;
+}
+
+export function applyPointMarkerPlacement(
+  marker: HTMLElement,
+  insetInlineStart: string,
+  insetBlockStart: string,
+): void {
+  marker.style.setProperty("--qti3-point-marker-inline-start", insetInlineStart);
+  marker.style.setProperty("--qti3-point-marker-block-start", insetBlockStart);
+}
+
+export function applyPositionObjectMarkerSize(
+  marker: HTMLElement,
+  inlineSize: number,
+  blockSize: number,
+): void {
+  marker.style.setProperty("--qti3-position-object-marker-inline-size", `${inlineSize}px`);
+  marker.style.setProperty("--qti3-position-object-marker-block-size", `${blockSize}px`);
+}
+
+export function applyPositionObjectMarkerPlacement(
+  marker: HTMLElement,
+  insetInlineStart: string,
+  insetBlockStart: string,
+): void {
+  marker.style.setProperty("--qti3-position-object-marker-inline-start", insetInlineStart);
+  marker.style.setProperty("--qti3-position-object-marker-block-start", insetBlockStart);
+}
+
+export function placeHotspotButton(
+  button: HTMLButtonElement,
+  choice: QtiChoice,
+  width: number,
+  height: number,
+): void {
+  const coords = hotspotCoords(choice);
+  const shape = choice.attributes.shape;
+
+  if (shape === "circle" && coords.length >= 3) {
+    const [x, y, radius] = coords as [number, number, number];
+    applyGraphicRegionPlacement(button, {
+      insetInlineStart: `${percent(x - radius, width)}%`,
+      insetBlockStart: `${percent(y - radius, height)}%`,
+      inlineSize: `${percent(radius * 2, width)}%`,
+      blockSize: `${percent(radius * 2, height)}%`,
+      shape: "circle",
+    });
+    return;
+  }
+
+  if (shape === "rect" && coords.length >= 4) {
+    const [left, top, right, bottom] = coords as [number, number, number, number];
+    applyGraphicRegionPlacement(button, {
+      insetInlineStart: `${percent(left, width)}%`,
+      insetBlockStart: `${percent(top, height)}%`,
+      inlineSize: `${percent(Math.max(1, right - left), width)}%`,
+      blockSize: `${percent(Math.max(1, bottom - top), height)}%`,
+      shape: "rect",
+    });
+    return;
+  }
+
+  if (shape === "poly" && coords.length >= 6) {
+    const xs = coords.filter((_, index) => index % 2 === 0);
+    const ys = coords.filter((_, index) => index % 2 === 1);
+    const left = Math.min(...xs);
+    const top = Math.min(...ys);
+    const right = Math.max(...xs);
+    const bottom = Math.max(...ys);
+    applyGraphicRegionPlacement(button, {
+      insetInlineStart: `${percent(left, width)}%`,
+      insetBlockStart: `${percent(top, height)}%`,
+      inlineSize: `${percent(Math.max(1, right - left), width)}%`,
+      blockSize: `${percent(Math.max(1, bottom - top), height)}%`,
+      shape: "poly",
+    });
+    return;
+  }
+
+  applyGraphicRegionPlacement(button, {
+    insetInlineStart: "0",
+    insetBlockStart: "0",
+  });
+}
+
+export function hotspotCenter(
+  choice: QtiChoice,
+  width: number,
+  height: number,
+): { x: number; y: number } {
+  const coords = hotspotCoords(choice);
+  const shape = choice.attributes.shape;
+  if ((shape === "circle" || shape === "ellipse") && coords.length >= 2) {
+    const [x, y] = coords as [number, number];
+    return { x, y };
+  }
+  if (shape === "rect" && coords.length >= 4) {
+    const [left, top, right, bottom] = coords as [number, number, number, number];
+    return { x: (left + right) / 2, y: (top + bottom) / 2 };
+  }
+  if (shape === "poly" && coords.length >= 6) {
+    const xs = coords.filter((_, index) => index % 2 === 0);
+    const ys = coords.filter((_, index) => index % 2 === 1);
+    return {
+      x: (Math.min(...xs) + Math.max(...xs)) / 2,
+      y: (Math.min(...ys) + Math.max(...ys)) / 2,
+    };
+  }
+  return { x: width / 2, y: height / 2 };
+}
+
+export function hotspotDisplayLabel(choice: QtiChoice, choices: QtiChoice[]): string {
+  return choice.attributes["hotspot-label"] || `Region ${choices.indexOf(choice) + 1}`;
+}
+
+export function hotspotAccessibleLabel(choice: QtiChoice, index: number): string {
+  return (
+    choice.attributes["aria-label"] || choice.attributes["hotspot-label"] || `Region ${index + 1}`
+  );
+}

package/src/interactions/choice-interaction.ts

@@ -0,0 +1,92 @@
+import type { QtiInteraction, QtiValue } from "@longsightgroup/qti3-core";
+import {
+  interactionChoices,
+  missingChoicesMessage,
+  readableType,
+  responseGroup,
+  valueToStrings,
+} from "../interaction-support.js";
+
+function choicePresentationLabel(interaction: QtiInteraction, index: number): string {
+  const classNames = new Set((interaction.attributes.class ?? "").split(/\s+/).filter(Boolean));
+  if (classNames.has("qti-labels-none")) return "";
+
+  const labels = classNames.has("qti-labels-decimal")
+    ? Array.from({ length: 26 }, (_, item) => `${item + 1}`)
+    : classNames.has("qti-labels-lower-alpha")
+      ? "abcdefghijklmnopqrstuvwxyz".split("")
+      : "ABCDEFGHIJKLMNOPQRSTUVWXYZ".split("");
+  const suffix = classNames.has("qti-labels-suffix-none")
+    ? ""
+    : classNames.has("qti-labels-suffix-parenthesis")
+      ? ")"
+      : ".";
+  return `${labels[index] ?? `${index + 1}`}${suffix}`;
+}
+
+export function renderChoice(
+  interaction: QtiInteraction,
+  update: (value: QtiValue) => void,
+  currentValue: QtiValue,
+): HTMLElement {
+  const group = responseGroup("qti3-choice-group");
+
+  const multiple =
+    interaction.responseCardinality === "multiple" || interaction.responseCardinality === "ordered";
+  const selected = new Set(valueToStrings(currentValue));
+  const list = document.createElement("div");
+  list.className = "qti3-choice-list";
+  list.role = "group";
+  list.setAttribute("aria-label", `${readableType(interaction.type)} options`);
+  const syncSelected = () => {
+    for (const label of list.querySelectorAll<HTMLElement>(".qti3-choice-option")) {
+      const identifier = label.dataset.choiceIdentifier ?? "";
+      label.dataset.selected = selected.has(identifier) ? "true" : "false";
+    }
+  };
+  const choices = interactionChoices(interaction);
+  if (choices.length === 0) {
+    group.append(missingChoicesMessage(interaction));
+    return group;
+  }
+  for (const [index, choice] of choices.entries()) {
+    const label = document.createElement("label");
+    label.className = "qti3-choice-option";
+    label.dataset.choiceIdentifier = choice.identifier;
+    const input = document.createElement("input");
+    input.type = multiple ? "checkbox" : "radio";
+    input.name = interaction.responseIdentifier ?? interaction.type;
+    input.value = choice.identifier;
+    input.checked = selected.has(choice.identifier);
+    input.addEventListener("change", () => {
+      if (multiple) {
+        if (input.checked) selected.add(choice.identifier);
+        else selected.delete(choice.identifier);
+        update([...selected]);
+      } else {
+        selected.clear();
+        selected.add(choice.identifier);
+        syncSelected();
+        update(input.value);
+      }
+      syncSelected();
+    });
+    const visibleLabel = choicePresentationLabel(interaction, index);
+    const optionParts: HTMLElement[] = [input];
+    if (visibleLabel) {
+      const labelText = document.createElement("span");
+      labelText.className = "qti3-choice-label";
+      labelText.textContent = visibleLabel;
+      optionParts.push(labelText);
+    }
+    const text = document.createElement("span");
+    text.className = "qti3-choice-text";
+    text.textContent = choice.text;
+    optionParts.push(text);
+    label.append(...optionParts);
+    list.append(label);
+  }
+  syncSelected();
+  group.append(list);
+  return group;
+}