@longsightgroup/qti3-player 0.2.1 → 0.3.0

package/src/interactions/portable-custom-interaction.ts

@@ -0,0 +1,139 @@
+import type {
+  QtiContentNode,
+  QtiDiagnostic,
+  QtiInteraction,
+  QtiPortableCustomDefinition,
+  QtiPortableCustomStateValue,
+  QtiValue,
+} from "@longsightgroup/qti3-core";
+import type { QtiPortableCustomMountEventDetail } from "../player-types.js";
+import {
+  portableCustomDefinitionFromAttributes,
+  portableCustomEventState,
+  portableCustomEventValidity,
+  portableCustomEventValue,
+  scalarString,
+} from "../portable-custom-support.js";
+
+export interface PortableCustomResponseContext {
+  interaction: QtiInteraction;
+  update: (value: QtiValue) => void;
+  currentValue: QtiValue;
+  currentState?: QtiPortableCustomStateValue | undefined;
+  renderMarkup: (nodes: QtiContentNode[]) => Node[];
+  setInteractionState: (responseIdentifier: string, state: QtiPortableCustomStateValue) => void;
+  setValidity: (responseIdentifier: string, valid: boolean, message?: string) => void;
+  emitStateChange: () => void;
+  onMount: (detail: QtiPortableCustomMountEventDetail) => void;
+}
+
+export function portableCustomValidityDiagnostic(
+  responseIdentifier: string,
+  valid: boolean,
+  message: string | undefined,
+): QtiDiagnostic | undefined {
+  if (valid) return undefined;
+  return {
+    code: "response.portableCustom.validity",
+    severity: "error",
+    message: message?.trim() || `${responseIdentifier} is not valid.`,
+    path: responseIdentifier,
+  };
+}
+
+export function renderPortableCustomResponse(context: PortableCustomResponseContext): HTMLElement {
+  const { interaction, update, currentValue } = context;
+  const definition =
+    interaction.portableCustom ?? portableCustomDefinitionFromAttributes(interaction);
+  const responseIdentifier = interaction.responseIdentifier ?? definition.responseIdentifier ?? "";
+  const currentState = context.currentState;
+
+  const group = document.createElement("div");
+  group.role = "group";
+  group.setAttribute("aria-label", interaction.prompt ?? "Portable custom interaction");
+
+  const host = createPortableCustomHost(interaction, definition, responseIdentifier, currentState);
+  if (definition.interactionMarkup.length > 0) {
+    const markup = document.createElement("div");
+    markup.className = "qti3-portable-custom-markup";
+    markup.append(...context.renderMarkup(definition.interactionMarkup));
+    host.append(markup);
+  } else {
+    host.textContent = "Portable custom interaction host";
+  }
+
+  const fallback = document.createElement("input");
+  fallback.type = "hidden";
+  fallback.className = "qti3-portable-custom-response";
+  fallback.hidden = true;
+  fallback.tabIndex = -1;
+  fallback.setAttribute("aria-hidden", "true");
+  fallback.value = scalarString(currentValue);
+
+  const handlePortableCustomEvent = (event: Event) => {
+    const state = portableCustomEventState(event);
+    const value = portableCustomEventValue(event);
+    const validity = portableCustomEventValidity(event);
+    if (state !== undefined && responseIdentifier) {
+      context.setInteractionState(responseIdentifier, state);
+      host.dataset.state = JSON.stringify(state);
+    }
+    if (value !== undefined) {
+      fallback.value = scalarString(value ?? null);
+      update(value);
+    }
+    if (validity && responseIdentifier) {
+      context.setValidity(responseIdentifier, validity.valid, validity.message);
+      context.emitStateChange();
+    }
+    if (value === undefined && state !== undefined && !validity) context.emitStateChange();
+  };
+
+  for (const eventName of [
+    "qti3-portable-custom-response",
+    "qti3-pci-response",
+    "qti3-portable-custom-state",
+    "qti3-portable-custom-validity",
+  ] as const) {
+    host.addEventListener(eventName, handlePortableCustomEvent);
+  }
+
+  queueMicrotask(() => {
+    context.onMount({
+      responseIdentifier,
+      interaction,
+      definition,
+      host,
+      value: currentValue,
+      state: currentState,
+    });
+  });
+
+  group.append(host, fallback);
+  return group;
+}
+
+function createPortableCustomHost(
+  interaction: QtiInteraction,
+  definition: QtiPortableCustomDefinition,
+  responseIdentifier: string,
+  currentState: QtiPortableCustomStateValue | undefined,
+): HTMLElement {
+  const host = document.createElement("div");
+  host.className = "qti3-portable-custom-host";
+  host.tabIndex = 0;
+  host.dataset.responseIdentifier = responseIdentifier;
+  host.dataset.typeIdentifier = definition.customInteractionTypeIdentifier ?? "";
+  host.dataset.module = definition.module ?? "";
+  host.dataset.qtiName = interaction.qtiName;
+  if (definition.interactionModules?.primaryConfiguration) {
+    host.dataset.primaryConfiguration = definition.interactionModules.primaryConfiguration;
+  }
+  if (definition.interactionModules?.secondaryConfiguration) {
+    host.dataset.secondaryConfiguration = definition.interactionModules.secondaryConfiguration;
+  }
+  if (currentState !== undefined) host.dataset.state = JSON.stringify(currentState);
+  host.setAttribute("role", "application");
+  host.setAttribute("aria-label", interaction.prompt ?? "Portable custom interaction host");
+  return host;
+}

package/src/interactions/position-object-interaction.ts

@@ -0,0 +1,210 @@
+import type { QtiInteraction, QtiValue } from "@longsightgroup/qti3-core";
+import {
+  applyGraphicSurfaceLayout,
+  applyPositionObjectMarkerPlacement,
+  applyPositionObjectMarkerSize,
+  appendGraphicObjectImage,
+  objectIsImage,
+  percent,
+  readableType,
+  responseGroup,
+} from "../interaction-support.js";
+import { movementButton } from "../movement.js";
+import type { QtiPlayerMessages } from "../player-messages.js";
+import {
+  objectAssetHeight,
+  objectAssetWidth,
+  parsePointValue,
+  pointToString,
+} from "./point-value.js";
+
+export function renderPositionObjectResponse(
+  interaction: QtiInteraction,
+  update: (value: QtiValue) => void,
+  currentValue: QtiValue,
+  messages: QtiPlayerMessages,
+): HTMLElement {
+  const group = responseGroup();
+  group.role = "group";
+  group.setAttribute("aria-label", `${readableType(interaction.type)} object placement response`);
+
+  const stageObject = interaction.positionObjectStage ?? interaction.object;
+  const movableObject = interaction.positionObjectStage ? interaction.object : undefined;
+  const width = objectAssetWidth(stageObject, 480);
+  const height = objectAssetHeight(stageObject, 300);
+  const movableWidth = objectAssetWidth(movableObject, Math.max(32, Math.round(width * 0.12)));
+  const movableHeight = objectAssetHeight(movableObject, Math.max(32, Math.round(height * 0.12)));
+  const parsedPoint = parsePointValue(currentValue);
+  let point = parsedPoint ?? { x: 0, y: 0 };
+  let isPlaced = Boolean(parsedPoint);
+
+  const stage = document.createElement("div");
+  applyGraphicSurfaceLayout(stage, width, height, "qti3-position-object-stage");
+  stage.style.setProperty("--qti3-position-object-marker-block-size", `${movableHeight}px`);
+  stage.tabIndex = 0;
+  stage.role = "group";
+  stage.setAttribute("aria-label", `${readableType(interaction.type)} placement stage`);
+
+  if (stageObject?.data && objectIsImage(stageObject)) {
+    appendGraphicObjectImage(stage, stageObject, stageObject.text || "");
+  }
+
+  const marker = document.createElement("button");
+  marker.type = "button";
+  marker.className = "qti3-position-object-marker";
+  marker.setAttribute("aria-label", messages.movableObject());
+  applyPositionObjectMarkerSize(marker, movableWidth, movableHeight);
+  marker.draggable = false;
+
+  if (movableObject?.data && objectIsImage(movableObject)) {
+    const image = document.createElement("img");
+    image.src = movableObject.data;
+    image.alt = "";
+    marker.append(image);
+  } else {
+    marker.textContent = messages.placeObject();
+  }
+  stage.append(marker);
+
+  const coordinate = document.createElement("output");
+  coordinate.className = "qti3-coordinate-output";
+  const clamp = () => {
+    point.x = Math.max(0, Math.min(width, point.x));
+    point.y = Math.max(0, Math.min(height, point.y));
+  };
+  const commit = () => {
+    if (!isPlaced) return;
+    update(pointToString(point));
+  };
+  const syncMarker = () => {
+    if (!isPlaced) {
+      marker.dataset.placed = "false";
+      marker.style.removeProperty("insetInlineStart");
+      marker.style.removeProperty("insetBlockStart");
+      marker.style.setProperty(
+        "--qti3-position-object-unplaced-inline-start",
+        `${Math.round(movableWidth / 2)}px`,
+      );
+      marker.style.setProperty(
+        "--qti3-position-object-unplaced-block-start",
+        `calc(100% + ${Math.round(movableHeight / 2 + 8)}px)`,
+      );
+      coordinate.value = "";
+      coordinate.textContent = "Object not placed";
+      stage.setAttribute(
+        "aria-label",
+        `${readableType(interaction.type)} placement stage, object not placed`,
+      );
+      return;
+    }
+    clamp();
+    marker.dataset.placed = "true";
+    marker.style.removeProperty("--qti3-position-object-unplaced-inline-start");
+    marker.style.removeProperty("--qti3-position-object-unplaced-block-start");
+    applyPositionObjectMarkerPlacement(
+      marker,
+      `${percent(point.x, width)}%`,
+      `${percent(point.y, height)}%`,
+    );
+    coordinate.value = pointToString(point);
+    coordinate.textContent = `Object positioned at ${pointToString(point)}`;
+    stage.setAttribute(
+      "aria-label",
+      `${readableType(interaction.type)} placement stage, object at ${pointToString(point)}`,
+    );
+  };
+  const pointFromPointer = (event: MouseEvent | PointerEvent) => {
+    const rect = stage.getBoundingClientRect();
+    point = {
+      x: Math.round(((event.clientX - rect.left) / rect.width) * width),
+      y: Math.round(((event.clientY - rect.top) / rect.height) * height),
+    };
+    isPlaced = true;
+    clamp();
+  };
+  const ensureKeyboardPoint = () => {
+    if (isPlaced) return;
+    point = { x: 0, y: 0 };
+    isPlaced = true;
+  };
+  const moveBy = (dx: number, dy: number, emit = true) => {
+    ensureKeyboardPoint();
+    point.x += dx;
+    point.y += dy;
+    syncMarker();
+    if (emit) commit();
+  };
+  const handleKey = (event: KeyboardEvent) => {
+    const step = event.shiftKey ? 10 : 1;
+    if (event.key === "ArrowLeft") moveBy(-step, 0, false);
+    else if (event.key === "ArrowRight") moveBy(step, 0, false);
+    else if (event.key === "ArrowUp") moveBy(0, -step, false);
+    else if (event.key === "ArrowDown") moveBy(0, step, false);
+    else if (event.key === "Enter" || event.key === " ") {
+      ensureKeyboardPoint();
+      syncMarker();
+      commit();
+    } else return;
+    event.preventDefault();
+  };
+
+  let dragging = false;
+  let dragMoved = false;
+  marker.addEventListener("pointerdown", (event) => {
+    dragging = true;
+    dragMoved = false;
+    marker.dataset.dragging = "true";
+    marker.setPointerCapture(event.pointerId);
+    if (isPlaced) {
+      pointFromPointer(event);
+      syncMarker();
+    }
+    event.preventDefault();
+  });
+  marker.addEventListener("pointermove", (event) => {
+    if (!dragging) return;
+    dragMoved = true;
+    pointFromPointer(event);
+    syncMarker();
+  });
+  marker.addEventListener("pointerup", (event) => {
+    if (!dragging) return;
+    dragging = false;
+    delete marker.dataset.dragging;
+    marker.releasePointerCapture(event.pointerId);
+    if (dragMoved || isPlaced) {
+      pointFromPointer(event);
+      syncMarker();
+      commit();
+    }
+  });
+  marker.addEventListener("pointercancel", () => {
+    dragging = false;
+    delete marker.dataset.dragging;
+  });
+  stage.addEventListener("click", (event) => {
+    if (event.target === marker) return;
+    pointFromPointer(event);
+    syncMarker();
+    commit();
+  });
+  stage.addEventListener("keydown", handleKey);
+  marker.addEventListener("keydown", handleKey);
+
+  const controls = document.createElement("div");
+  controls.className = "qti3-point-controls";
+  for (const [direction, dx, dy] of [
+    ["up", 0, -1],
+    ["left", -1, 0],
+    ["right", 1, 0],
+    ["down", 0, 1],
+  ] as const) {
+    controls.append(
+      movementButton(direction, messages.moveObject({ direction }), () => moveBy(dx, dy)),
+    );
+  }
+
+  syncMarker();
+  group.append(stage, coordinate, controls);
+  return group;
+}

package/src/interactions/routing.ts

@@ -0,0 +1,27 @@
+import type { QtiInteraction } from "@longsightgroup/qti3-core";
+
+export function usesChoiceSet(interaction: QtiInteraction): boolean {
+  if (interaction.type === "choice") return true;
+  return (
+    interaction.responseCardinality === "multiple" && interaction.responseBaseType === "identifier"
+  );
+}
+
+export function usesOrderedResponse(interaction: QtiInteraction): boolean {
+  return interaction.responseCardinality === "ordered" || interaction.type === "order";
+}
+
+const explicitNonPairInteractionTypes = new Set<QtiInteraction["type"]>([
+  "match",
+  "gapMatch",
+  "graphicGapMatch",
+  "graphicAssociate",
+  "graphicOrder",
+  "order",
+]);
+
+export function usesPairResponse(interaction: QtiInteraction): boolean {
+  if (interaction.type === "associate") return true;
+  if (explicitNonPairInteractionTypes.has(interaction.type)) return false;
+  return interaction.responseBaseType === "pair" || interaction.responseBaseType === "directedPair";
+}

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

@@ -0,0 +1,185 @@
+import type { QtiInteraction, QtiValue } from "@longsightgroup/qti3-core";
+import {
+  applyGraphicSurfaceLayout,
+  applyPointMarkerPlacement,
+  appendGraphicObjectImage,
+  objectHeight,
+  objectWidth,
+  readableType,
+  responseGroup,
+} from "../interaction-support.js";
+import { movementButton } from "../movement.js";
+import type { QtiPlayerMessages } from "../player-messages.js";
+import { maximumAllowedResponses } from "../response-limits.js";
+import { parsePointValues, pointToString } from "./point-value.js";
+
+export function renderSelectPointResponse(
+  interaction: QtiInteraction,
+  update: (value: QtiValue) => void,
+  currentValue: QtiValue,
+  messages: QtiPlayerMessages,
+): HTMLElement {
+  const group = responseGroup();
+  group.role = "group";
+  group.setAttribute("aria-label", `${readableType(interaction.type)} coordinate response`);
+  const isMultiple = interaction.responseCardinality === "multiple";
+  const maxPoints = isMultiple ? maximumAllowedResponses(interaction) : 1;
+
+  const surface = document.createElement("button");
+  surface.type = "button";
+  applyGraphicSurfaceLayout(
+    surface,
+    objectWidth(interaction),
+    objectHeight(interaction),
+    "qti3-point-surface",
+  );
+  surface.setAttribute("aria-label", `${readableType(interaction.type)} coordinate area`);
+
+  const object = interaction.object;
+  if (object) {
+    appendGraphicObjectImage(surface, object, "");
+  }
+
+  const width = objectWidth(interaction);
+  const height = objectHeight(interaction);
+  let points = parsePointValues(currentValue);
+  let activeIndex = points.length > 0 ? points.length - 1 : -1;
+  const coordinate = document.createElement("output");
+  coordinate.className = "qti3-coordinate-output";
+  const initialPoint = () => ({
+    x: Math.round(width / 2),
+    y: Math.round(height / 2),
+  });
+  const emitValue = (): QtiValue => {
+    const values = points.map(pointToString);
+    if (isMultiple) return values;
+    return values[0] ?? "";
+  };
+  const commit = () => {
+    update(emitValue());
+  };
+  const syncMarker = () => {
+    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`);
+      return;
+    }
+    points.forEach((point, index) => {
+      const marker = document.createElement("span");
+      marker.className = "qti3-point-marker";
+      marker.setAttribute("aria-hidden", "true");
+      applyPointMarkerPlacement(
+        marker,
+        `${(point.x / width) * 100}%`,
+        `${(point.y / height) * 100}%`,
+      );
+      if (index === activeIndex) marker.dataset.active = "true";
+      surface.append(marker);
+    });
+    const text = points.map(pointToString).join("; ");
+    coordinate.value = isMultiple
+      ? points.map(pointToString).join(" | ")
+      : pointToString(points[0]);
+    coordinate.textContent = isMultiple
+      ? `${points.length} selected point${points.length === 1 ? "" : "s"}: ${text}`
+      : `Selected point ${pointToString(points[0])}`;
+    surface.setAttribute(
+      "aria-label",
+      `${readableType(interaction.type)} coordinate area, selected ${text}`,
+    );
+  };
+  const clampPoint = (point: { x: number; y: number }) => {
+    point.x = Math.max(0, Math.min(width, point.x));
+    point.y = Math.max(0, Math.min(height, point.y));
+  };
+  const setActivePoint = (point: { x: number; y: number }) => {
+    clampPoint(point);
+    if (!isMultiple) {
+      points = [point];
+      activeIndex = 0;
+      return;
+    }
+    if (maxPoints !== undefined && points.length >= maxPoints) {
+      points[points.length - 1] = point;
+      activeIndex = points.length - 1;
+      return;
+    }
+    points.push(point);
+    activeIndex = points.length - 1;
+  };
+  const mutableActivePoint = () => {
+    if (points.length === 0) setActivePoint(initialPoint());
+    if (activeIndex < 0 || activeIndex >= points.length) activeIndex = points.length - 1;
+    const point = points[activeIndex];
+    if (point) return point;
+    const fallback = initialPoint();
+    points = [fallback];
+    activeIndex = 0;
+    return fallback;
+  };
+
+  surface.addEventListener("click", (event) => {
+    if (event.detail === 0) return;
+    const rect = surface.getBoundingClientRect();
+    setActivePoint({
+      x: Math.round(((event.clientX - rect.left) / rect.width) * width),
+      y: Math.round(((event.clientY - rect.top) / rect.height) * height),
+    });
+    syncMarker();
+    commit();
+  });
+  surface.addEventListener("keydown", (event) => {
+    const point = mutableActivePoint();
+    const step = event.shiftKey ? 10 : 1;
+    if (event.key === "ArrowLeft") point.x -= step;
+    else if (event.key === "ArrowRight") point.x += step;
+    else if (event.key === "ArrowUp") point.y -= step;
+    else if (event.key === "ArrowDown") point.y += step;
+    else if (event.key === "Enter" || event.key === " ") {
+      event.preventDefault();
+      commit();
+      return;
+    } else return;
+
+    event.preventDefault();
+    clampPoint(point);
+    syncMarker();
+  });
+
+  syncMarker();
+  const controls = document.createElement("div");
+  controls.className = "qti3-point-controls";
+  for (const [direction, dx, dy] of [
+    ["up", 0, -1],
+    ["left", -1, 0],
+    ["right", 1, 0],
+    ["down", 0, 1],
+  ] as const) {
+    controls.append(
+      movementButton(direction, messages.movePoint({ direction }), () => {
+        const point = mutableActivePoint();
+        point.x += dx;
+        point.y += dy;
+        clampPoint(point);
+        syncMarker();
+        commit();
+      }),
+    );
+  }
+  if (isMultiple) {
+    const clear = document.createElement("button");
+    clear.type = "button";
+    clear.textContent = messages.clearPoints();
+    clear.addEventListener("click", () => {
+      points = [];
+      activeIndex = -1;
+      syncMarker();
+      commit();
+    });
+    controls.append(clear);
+  }
+  group.append(surface, coordinate, controls);
+  return group;
+}

package/src/interactions/shared.ts

@@ -0,0 +1,56 @@
+import type { QtiChoice, QtiInteraction } from "@longsightgroup/qti3-core";
+import { interactionChoices } from "../interaction-support.js";
+
+export function tokenRegion(label: string, visibleLabel?: string): HTMLElement {
+  const region = document.createElement("div");
+  region.className = "qti3-token-region";
+  region.role = "group";
+  region.setAttribute("aria-label", label);
+  if (visibleLabel) {
+    const heading = document.createElement("strong");
+    heading.className = "qti3-region-label";
+    heading.textContent = visibleLabel;
+    region.append(heading);
+  }
+  return region;
+}
+
+export function tokenButton(choice: QtiChoice): HTMLButtonElement {
+  const button = document.createElement("button");
+  button.type = "button";
+  button.className = "qti3-token";
+  button.dataset.choiceIdentifier = choice.identifier;
+  button.setAttribute("aria-pressed", "false");
+  button.textContent = choice.text;
+  return button;
+}
+
+export function choiceText(choices: QtiChoice[], identifier: string | undefined): string {
+  if (!identifier) return "";
+  return choices.find((choice) => choice.identifier === identifier)?.text ?? identifier;
+}
+
+export function sourceChoices(interaction: QtiInteraction): QtiChoice[] {
+  const choices = interactionChoices(interaction);
+  if (interaction.type === "gapMatch" || interaction.type === "graphicGapMatch") {
+    const gapChoices = choices.filter((choice) => choice.role === "gapChoice");
+    return gapChoices.length > 0 ? gapChoices : choices;
+  }
+  const sourceRoles = new Set(["associableChoice", "matchSource", "gapChoice", "hotspot"]);
+  const sources = choices.filter((choice) => sourceRoles.has(choice.role));
+  return sources.length > 0 ? sources : choices;
+}
+
+export function targetChoices(interaction: QtiInteraction): QtiChoice[] {
+  const choices = interactionChoices(interaction);
+  if (interaction.type === "associate" || interaction.type === "graphicAssociate") return choices;
+  const targetRoles = new Set(["matchTarget", "gap", "hotspot"]);
+  const targets = choices.filter((choice) => targetRoles.has(choice.role));
+  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" };
+}