@longsightgroup/qti3-player 0.2.1 → 0.3.0

package/src/reorder/a11y.ts

@@ -0,0 +1,40 @@
+import { choiceSelector } from "../interaction-support.js";
+
+export function createSelectionSummary(): HTMLParagraphElement {
+  const summary = document.createElement("p");
+  summary.className = "qti3-selection-summary";
+  summary.setAttribute("aria-live", "polite");
+  return summary;
+}
+
+export function orderedItemAccessibleName(label: string, index: number, total: number): string {
+  return `${label}, position ${index + 1} of ${total}`;
+}
+
+export function announceOrderedItemMove(
+  summary: HTMLElement,
+  label: string,
+  to: number,
+  total: number,
+  from?: number,
+): void {
+  if (from !== undefined && Math.abs(to - from) === 1) {
+    summary.textContent = `${label} moved ${to < from ? "up" : "down"}.`;
+    return;
+  }
+  summary.textContent = `${label} moved to position ${to + 1} of ${total}.`;
+}
+
+export function announceOrderedSelectionCount(
+  summary: HTMLElement,
+  count: number,
+  singular: string,
+  plural: string,
+): void {
+  summary.textContent =
+    count > 0 ? `${count} ${count === 1 ? singular : plural}.` : `No ${plural}.`;
+}
+
+export function focusReorderControl(container: ParentNode, identifier: string): void {
+  container.querySelector<HTMLButtonElement>(`button${choiceSelector(identifier)}`)?.focus();
+}

package/src/reorder/graphic-order-interaction.ts

@@ -0,0 +1,260 @@
+import type { QtiChoice, QtiInteraction, QtiValue } from "@longsightgroup/qti3-core";
+import { removeButton } from "../controls/remove-button.js";
+import {
+  applyGraphicSurfaceLayout,
+  appendGraphicObjectImage,
+  choiceSelector,
+  hotspotAccessibleLabel,
+  hotspotCenter,
+  hotspotDisplayLabel,
+  interactionChoices,
+  missingChoicesMessage,
+  objectHeight,
+  objectWidth,
+  placeHotspotButton,
+  readableType,
+  responseGroup,
+  valueToStrings,
+} from "../interaction-support.js";
+import { movementButton } from "../movement.js";
+import type { QtiPlayerMessages } from "../player-messages.js";
+import {
+  announceOrderedItemMove,
+  announceOrderedSelectionCount,
+  createSelectionSummary,
+  focusReorderControl,
+  orderedItemAccessibleName,
+} from "./a11y.js";
+
+export function renderGraphicOrderResponse(
+  interaction: QtiInteraction,
+  update: (value: QtiValue) => void,
+  currentValue: QtiValue,
+  messages: QtiPlayerMessages,
+): HTMLElement {
+  const group = responseGroup();
+  const width = objectWidth(interaction);
+  const height = objectHeight(interaction);
+  const choices = interactionChoices(interaction).filter((choice) => choice.role === "hotspot");
+  if (choices.length === 0) {
+    group.append(missingChoicesMessage(interaction));
+    return group;
+  }
+  const orderedIdentifiers = valueToStrings(currentValue).filter((identifier) =>
+    choices.some((choice) => choice.identifier === identifier),
+  );
+
+  const surface = document.createElement("div");
+  applyGraphicSurfaceLayout(surface, width, height, "qti3-graphic-order-surface");
+  surface.role = "group";
+  surface.setAttribute("aria-label", `${readableType(interaction.type)} hotspots`);
+
+  const object = interaction.object;
+  if (object) {
+    appendGraphicObjectImage(
+      surface,
+      object,
+      object.text || `${readableType(interaction.type)} image`,
+    );
+  }
+
+  const sequenceLines = document.createElementNS("http://www.w3.org/2000/svg", "svg");
+  sequenceLines.classList.add("qti3-graphic-sequence-lines");
+  sequenceLines.setAttribute("viewBox", `0 0 ${width} ${height}`);
+  sequenceLines.setAttribute("aria-hidden", "true");
+  const markerId = `qti3-graphic-order-marker-${(interaction.responseIdentifier ?? interaction.type).replace(/[^a-zA-Z0-9_-]/g, "-")}`;
+  const defs = document.createElementNS("http://www.w3.org/2000/svg", "defs");
+  const marker = document.createElementNS("http://www.w3.org/2000/svg", "marker");
+  marker.setAttribute("id", markerId);
+  marker.setAttribute("viewBox", "0 0 10 10");
+  marker.setAttribute("refX", "8");
+  marker.setAttribute("refY", "5");
+  marker.setAttribute("markerWidth", "5");
+  marker.setAttribute("markerHeight", "5");
+  marker.setAttribute("orient", "auto-start-reverse");
+  const arrow = document.createElementNS("http://www.w3.org/2000/svg", "path");
+  arrow.setAttribute("d", "M 0 0 L 10 5 L 0 10 z");
+  marker.append(arrow);
+  defs.append(marker);
+  sequenceLines.append(defs);
+  surface.append(sequenceLines);
+
+  const summary = createSelectionSummary();
+  const list = document.createElement("ol");
+  list.className = "qti3-graphic-order-list";
+  list.setAttribute("aria-label", `${readableType(interaction.type)} selected order`);
+
+  const orderedChoices = () =>
+    orderedIdentifiers
+      .map((identifier) => choices.find((choice) => choice.identifier === identifier))
+      .filter((choice): choice is QtiChoice => Boolean(choice));
+  const commit = () => update([...orderedIdentifiers]);
+  const updateSelectionCountSummary = () => {
+    announceOrderedSelectionCount(
+      summary,
+      orderedIdentifiers.length,
+      "region ordered",
+      "regions ordered",
+    );
+  };
+  const focusHotspot = (identifier: string) => {
+    surface
+      .querySelector<HTMLButtonElement>(`.qti3-hotspot-button${choiceSelector(identifier)}`)
+      ?.focus();
+  };
+  const focusRelativeHotspot = (choice: QtiChoice, delta: number) => {
+    const index = choices.findIndex((entry) => entry.identifier === choice.identifier);
+    const next = choices[(index + delta + choices.length) % choices.length];
+    if (next) focusHotspot(next.identifier);
+  };
+  const chooseHotspot = (choice: QtiChoice) => {
+    const existingIndex = orderedIdentifiers.indexOf(choice.identifier);
+    if (existingIndex >= 0) orderedIdentifiers.splice(existingIndex, 1);
+    orderedIdentifiers.push(choice.identifier);
+    renderState();
+    updateSelectionCountSummary();
+    commit();
+    focusHotspot(choice.identifier);
+  };
+  const removeHotspot = (identifier: string) => {
+    const index = orderedIdentifiers.indexOf(identifier);
+    if (index < 0) return;
+    orderedIdentifiers.splice(index, 1);
+    renderState();
+    updateSelectionCountSummary();
+    commit();
+    focusHotspot(identifier);
+  };
+  const moveHotspot = (identifier: string, delta: number) => {
+    const index = orderedIdentifiers.indexOf(identifier);
+    const targetIndex = index + delta;
+    if (index < 0 || targetIndex < 0 || targetIndex >= orderedIdentifiers.length) return;
+    const choice = choices.find((entry) => entry.identifier === identifier);
+    const choiceLabel = choice ? hotspotDisplayLabel(choice, choices) : identifier;
+    const [entry] = orderedIdentifiers.splice(index, 1);
+    if (!entry) return;
+    orderedIdentifiers.splice(targetIndex, 0, entry);
+    renderState();
+    announceOrderedItemMove(summary, choiceLabel, targetIndex, orderedIdentifiers.length, index);
+    commit();
+    focusReorderControl(list, identifier);
+  };
+  const renderState = () => {
+    for (const line of sequenceLines.querySelectorAll("line")) line.remove();
+    const currentChoices = orderedChoices();
+    for (let index = 0; index < currentChoices.length - 1; index += 1) {
+      const current = currentChoices[index];
+      const next = currentChoices[index + 1];
+      if (!current || !next) continue;
+      const start = hotspotCenter(current, width, height);
+      const end = hotspotCenter(next, width, height);
+      const line = document.createElementNS("http://www.w3.org/2000/svg", "line");
+      line.setAttribute("x1", String(start.x));
+      line.setAttribute("y1", String(start.y));
+      line.setAttribute("x2", String(end.x));
+      line.setAttribute("y2", String(end.y));
+      line.setAttribute("marker-end", `url(#${markerId})`);
+      sequenceLines.append(line);
+    }
+
+    for (const button of surface.querySelectorAll<HTMLButtonElement>(".qti3-hotspot-button")) {
+      const identifier = button.dataset.choiceIdentifier ?? "";
+      const index = orderedIdentifiers.indexOf(identifier);
+      const isSelected = index >= 0;
+      button.dataset.selected = isSelected ? "true" : "false";
+      button.setAttribute("aria-pressed", isSelected ? "true" : "false");
+      button.dataset.order = isSelected ? String(index + 1) : "";
+      const badge = button.querySelector<HTMLElement>(".qti3-graphic-order-number");
+      if (badge) badge.textContent = isSelected ? String(index + 1) : "";
+    }
+
+    list.replaceChildren(
+      ...currentChoices.map((choice, index) => {
+        const item = document.createElement("li");
+        item.className = "qti3-graphic-order-item";
+        item.dataset.choiceIdentifier = choice.identifier;
+        const choiceLabel = hotspotDisplayLabel(choice, choices);
+
+        const label = document.createElement("button");
+        label.type = "button";
+        label.className = "qti3-token";
+        label.dataset.choiceIdentifier = choice.identifier;
+        label.textContent = `${index + 1}. ${choiceLabel}`;
+        label.setAttribute(
+          "aria-label",
+          orderedItemAccessibleName(choiceLabel, index, currentChoices.length),
+        );
+        label.addEventListener("click", () => focusHotspot(choice.identifier));
+        label.addEventListener("keydown", (event) => {
+          if (event.key === "ArrowUp" || event.key === "ArrowLeft") {
+            event.preventDefault();
+            moveHotspot(choice.identifier, -1);
+          } else if (event.key === "ArrowDown" || event.key === "ArrowRight") {
+            event.preventDefault();
+            moveHotspot(choice.identifier, 1);
+          } else if (event.key === "Delete" || event.key === "Backspace") {
+            event.preventDefault();
+            removeHotspot(choice.identifier);
+          }
+        });
+
+        const up = movementButton(
+          "up",
+          messages.moveChoice({ label: choiceLabel, direction: "up" }),
+          () => moveHotspot(choice.identifier, -1),
+        );
+        up.disabled = index === 0;
+
+        const down = movementButton(
+          "down",
+          messages.moveChoice({ label: choiceLabel, direction: "down" }),
+          () => moveHotspot(choice.identifier, 1),
+        );
+        down.disabled = index === currentChoices.length - 1;
+
+        const remove = removeButton(choiceLabel, messages);
+        remove.addEventListener("click", () => removeHotspot(choice.identifier));
+
+        item.append(label, up, down, remove);
+        return item;
+      }),
+    );
+  };
+
+  for (const [index, choice] of choices.entries()) {
+    const button = document.createElement("button");
+    button.type = "button";
+    button.className = "qti3-hotspot-button qti3-graphic-order-hotspot";
+    button.dataset.choiceIdentifier = choice.identifier;
+    button.title = hotspotAccessibleLabel(choice, index);
+    button.setAttribute("aria-label", hotspotAccessibleLabel(choice, index));
+    button.setAttribute("aria-pressed", "false");
+    placeHotspotButton(button, choice, width, height);
+    const text = document.createElement("span");
+    text.className = "qti3-hotspot-label";
+    text.textContent = hotspotDisplayLabel(choice, choices);
+    const order = document.createElement("span");
+    order.className = "qti3-graphic-order-number";
+    order.setAttribute("aria-hidden", "true");
+    button.append(text, order);
+    button.addEventListener("click", () => chooseHotspot(choice));
+    button.addEventListener("keydown", (event) => {
+      if (event.key === "ArrowRight" || event.key === "ArrowDown") {
+        event.preventDefault();
+        focusRelativeHotspot(choice, 1);
+      } else if (event.key === "ArrowLeft" || event.key === "ArrowUp") {
+        event.preventDefault();
+        focusRelativeHotspot(choice, -1);
+      } else if (event.key === "Delete" || event.key === "Backspace") {
+        event.preventDefault();
+        removeHotspot(choice.identifier);
+      }
+    });
+    surface.append(button);
+  }
+
+  renderState();
+  updateSelectionCountSummary();
+  group.append(surface, list, summary);
+  return group;
+}

package/src/reorder/list-controls.ts

@@ -0,0 +1,114 @@
+import { movementButton } from "../movement.js";
+import type { QtiPlayerMessages } from "../player-messages.js";
+import { orderedItemAccessibleName } from "./a11y.js";
+
+export interface ReorderHandleOptions {
+  identifier: string;
+  label: string;
+  index: number;
+  total: number;
+  handleClassName: string;
+  visibleText: string;
+  messages: QtiPlayerMessages;
+  onMoveBy: (delta: number) => void;
+}
+
+export function createReorderHandleControls(options: ReorderHandleOptions): {
+  handle: HTMLButtonElement;
+  up: HTMLButtonElement;
+  down: HTMLButtonElement;
+} {
+  const { identifier, label, index, total, handleClassName, visibleText, messages, onMoveBy } =
+    options;
+
+  const handle = document.createElement("button");
+  handle.type = "button";
+  handle.className = handleClassName;
+  handle.dataset.choiceIdentifier = identifier;
+  handle.setAttribute("aria-label", orderedItemAccessibleName(label, index, total));
+  handle.textContent = visibleText;
+  handle.addEventListener("keydown", (event) => {
+    if (event.key === "ArrowUp" || event.key === "ArrowLeft") {
+      event.preventDefault();
+      onMoveBy(-1);
+    } else if (event.key === "ArrowDown" || event.key === "ArrowRight") {
+      event.preventDefault();
+      onMoveBy(1);
+    }
+  });
+
+  const up = movementButton("up", messages.moveChoice({ label, direction: "up" }), () =>
+    onMoveBy(-1),
+  );
+  up.disabled = index === 0;
+
+  const down = movementButton("down", messages.moveChoice({ label, direction: "down" }), () =>
+    onMoveBy(1),
+  );
+  down.disabled = index === total - 1;
+
+  return { handle, up, down };
+}
+
+export interface OrderDragState {
+  draggedIdentifier?: string;
+  pointerDraggedIdentifier?: string;
+}
+
+export function bindOrderListItemDrag(
+  item: HTMLLIElement,
+  choiceIdentifier: string,
+  index: number,
+  dragState: OrderDragState,
+  moveChoice: (from: number, to: number) => void,
+  findIndex: (identifier: string) => number,
+): void {
+  item.draggable = true;
+  item.dataset.choiceIdentifier = choiceIdentifier;
+
+  item.addEventListener("pointerdown", (event) => {
+    if (event.button !== 0 || (event.target as Element).closest("button")) return;
+    dragState.pointerDraggedIdentifier = choiceIdentifier;
+    try {
+      item.setPointerCapture(event.pointerId);
+    } catch {
+      // Synthetic pointer events and some browser drag paths do not create a capturable pointer.
+    }
+  });
+
+  item.addEventListener("pointerup", (event) => {
+    if (!dragState.pointerDraggedIdentifier) return;
+    const target = document
+      .elementFromPoint(event.clientX, event.clientY)
+      ?.closest<HTMLElement>(".qti3-reorder-item");
+    const targetIdentifier = target?.dataset.choiceIdentifier;
+    delete dragState.pointerDraggedIdentifier;
+    if (!targetIdentifier) return;
+    moveChoice(findIndex(choiceIdentifier), findIndex(targetIdentifier));
+  });
+
+  item.addEventListener("pointercancel", () => {
+    delete dragState.pointerDraggedIdentifier;
+  });
+
+  item.addEventListener("dragstart", (event) => {
+    dragState.draggedIdentifier = choiceIdentifier;
+    event.dataTransfer?.setData("text/plain", choiceIdentifier);
+    event.dataTransfer?.setDragImage(item, 12, 12);
+  });
+
+  item.addEventListener("dragover", (event) => {
+    event.preventDefault();
+    item.classList.add("qti3-drop-target");
+  });
+
+  item.addEventListener("dragleave", () => item.classList.remove("qti3-drop-target"));
+
+  item.addEventListener("drop", (event) => {
+    event.preventDefault();
+    item.classList.remove("qti3-drop-target");
+    const dragged = event.dataTransfer?.getData("text/plain") || dragState.draggedIdentifier;
+    if (!dragged) return;
+    moveChoice(findIndex(dragged), index);
+  });
+}

package/src/reorder/order-interaction.ts

@@ -0,0 +1,75 @@
+import type { QtiInteraction, QtiValue } from "@longsightgroup/qti3-core";
+import type { QtiPlayerMessages } from "../player-messages.js";
+import {
+  interactionChoices,
+  missingChoicesMessage,
+  orderChoicesFromValue,
+  readableType,
+  responseGroup,
+} from "../interaction-support.js";
+import { announceOrderedItemMove, createSelectionSummary, focusReorderControl } from "./a11y.js";
+import {
+  bindOrderListItemDrag,
+  createReorderHandleControls,
+  type OrderDragState,
+} from "./list-controls.js";
+
+export function renderOrderedResponse(
+  interaction: QtiInteraction,
+  update: (value: QtiValue) => void,
+  currentValue: QtiValue,
+  messages: QtiPlayerMessages,
+): HTMLElement {
+  const group = responseGroup();
+  const choices = interactionChoices(interaction).filter((choice) => choice.role !== "gap");
+  if (choices.length === 0) {
+    group.append(missingChoicesMessage(interaction));
+    return group;
+  }
+  const ordered = orderChoicesFromValue(choices, currentValue);
+  const list = document.createElement("ol");
+  list.className = "qti3-reorder-list";
+  list.setAttribute("aria-label", `${readableType(interaction.type)} current order`);
+  const summary = createSelectionSummary();
+  const dragState: OrderDragState = {};
+
+  const commit = () => update(ordered.map((choice) => choice.identifier));
+  const findIndex = (identifier: string) =>
+    ordered.findIndex((entry) => entry.identifier === identifier);
+  const moveChoice = (from: number, to: number) => {
+    if (from === to || from < 0 || from >= ordered.length || to < 0 || to >= ordered.length) return;
+    const [choice] = ordered.splice(from, 1);
+    if (!choice) return;
+    ordered.splice(to, 0, choice);
+    renderList();
+    announceOrderedItemMove(summary, choice.text, to, ordered.length, from);
+    commit();
+    focusReorderControl(list, choice.identifier);
+  };
+  const renderList = () => {
+    list.replaceChildren(
+      ...ordered.map((choice, index) => {
+        const item = document.createElement("li");
+        item.className = "qti3-reorder-item";
+        bindOrderListItemDrag(item, choice.identifier, index, dragState, moveChoice, findIndex);
+
+        const { handle, up, down } = createReorderHandleControls({
+          identifier: choice.identifier,
+          label: choice.text,
+          index,
+          total: ordered.length,
+          handleClassName: "qti3-token qti3-reorder-handle",
+          visibleText: choice.text,
+          messages,
+          onMoveBy: (delta) => moveChoice(index, index + delta),
+        });
+
+        item.append(handle, up, down);
+        return item;
+      }),
+    );
+  };
+  renderList();
+  group.append(list, summary);
+  return group;
+}

package/src/response-limits.ts

@@ -0,0 +1,47 @@
+import type { QtiChoice, QtiInteraction, QtiValue } from "@longsightgroup/qti3-core";
+
+export function maximumAllowedResponses(
+  interaction: QtiInteraction | undefined,
+): number | undefined {
+  if (!interaction) return undefined;
+  if (interaction.type === "media") return maximumMediaPlays(interaction);
+  const explicit =
+    interaction.attributes["max-choices"] ?? interaction.attributes["max-associations"];
+  if (explicit === undefined) return undefined;
+  const parsed = Number(explicit);
+  if (!Number.isInteger(parsed) || parsed <= 0) return undefined;
+  return parsed;
+}
+
+function maximumMediaPlays(interaction: QtiInteraction): number | undefined {
+  const parsed = Number(interaction.attributes["max-plays"] ?? "0");
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : undefined;
+}
+
+export function minimumMediaPlays(interaction: QtiInteraction): number {
+  const parsed = Number(interaction.attributes["min-plays"] ?? "0");
+  return Number.isInteger(parsed) && parsed >= 0 ? parsed : 0;
+}
+
+export { maximumMediaPlays };
+
+export function mediaPlayCount(value: QtiValue): number {
+  const parsed = typeof value === "number" ? value : typeof value === "string" ? Number(value) : 0;
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : 0;
+}
+
+export function exceedsHotspotMatchMax(choice: QtiChoice, selectedPairs: string[]): boolean {
+  const maximum = parseUnlimitedMaximum(choice.attributes["match-max"]);
+  if (maximum === undefined) return false;
+  const currentUseCount = selectedPairs
+    .flatMap((pair) => pair.split(" "))
+    .filter((identifier) => identifier === choice.identifier).length;
+  return currentUseCount + 1 > maximum;
+}
+
+export function parseUnlimitedMaximum(value: string | undefined): number | undefined {
+  if (value === undefined) return undefined;
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed <= 0) return undefined;
+  return parsed;
+}

package/src/styles/base-styles.ts

@@ -0,0 +1,117 @@
+export const BASE_PLAYER_STYLES = `
+.qti3-embedded-interaction-unsupported {
+  color: CanvasText;
+}
+
+.qti3-portable-custom-host {
+  border: 1px solid CanvasText;
+  padding: 0.5rem;
+  margin-block-end: 0.5rem;
+}
+
+.qti3-player {
+  --qti3-match-accent: #2f6fca;
+  --qti3-match-target-bg: #f5f6f7;
+  --qti3-match-target-border: #6f7782;
+
+  display: grid;
+  gap: 1rem;
+  max-inline-size: 72rem;
+  font: 16px/1.45 system-ui, sans-serif;
+}
+
+@supports (color: light-dark(#000, #fff)) {
+  .qti3-player {
+    --qti3-match-accent: light-dark(#2f6fca, #8ab4f8);
+    --qti3-match-target-bg: light-dark(#f5f6f7, #202124);
+    --qti3-match-target-border: light-dark(#6f7782, #9aa0a6);
+  }
+}
+
+.qti3-interaction {
+  display: grid;
+  gap: 0.75rem;
+  min-inline-size: 0;
+  max-inline-size: 100%;
+}
+
+.qti3-item-body {
+  display: grid;
+  gap: 1rem;
+}
+
+.qti3-item-body > * {
+  margin-block: 0;
+}
+
+.qti3-player .qti-hidden {
+  display: none !important;
+}
+
+.qti3-player .qti-visually-hidden {
+  position: absolute !important;
+  overflow: hidden !important;
+  clip: rect(1px, 1px, 1px, 1px) !important;
+  clip-path: inset(50%) !important;
+  inline-size: 1px !important;
+  block-size: 1px !important;
+  margin: -1px !important;
+  padding: 0 !important;
+  border: 0 !important;
+  white-space: nowrap !important;
+}
+
+.qti3-embedded-interaction {
+  display: inline-flex;
+  gap: 0.35rem;
+  margin-inline: 0.18rem;
+  align-items: baseline;
+  vertical-align: baseline;
+}
+
+.qti3-inline-text-input {
+  inline-size: auto;
+  min-inline-size: 8ch;
+  max-inline-size: 18ch;
+  margin-inline: 0.25rem;
+}
+
+.qti3-printed-variable {
+  font-weight: 700;
+}
+
+.qti3-feedback-block {
+  padding: 0.75rem;
+  border-inline-start: 4px solid Highlight;
+  background: Canvas;
+  color: CanvasText;
+}
+
+.qti3-response-group {
+  min-inline-size: 0;
+}
+
+.qti3-response-group > * + * {
+  margin-block-start: 0.75rem;
+}
+
+.qti3-selection-summary {
+  margin: 0;
+}
+
+.qti3-token:focus,
+.qti3-hotspot-button:focus,
+.qti3-player button:focus-visible,
+.qti3-player select:focus-visible,
+.qti3-player input:focus-visible,
+.qti3-player textarea:focus-visible {
+  outline: 3px solid Highlight;
+  outline-offset: 2px;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .qti3-player * {
+    scroll-behavior: auto;
+  }
+}
+`.trim();