@longsightgroup/qti3-player 0.2.0 → 0.3.0

package/src/player-locale.ts

@@ -0,0 +1,232 @@
+import type { QtiPlayerMessages } from "./player-messages.js";
+import type { QtiPlayerMessageOverrides } from "./player-types.js";
+
+type QtiPlayerMessageCatalog = Readonly<Partial<QtiPlayerMessages>>;
+
+const defaultEnglishPlayerMessages: QtiPlayerMessages = {
+  remove: () => "Remove",
+  removePair: ({ label }) => `Remove ${label}`,
+  clearDrawing: () => "Clear drawing",
+  clearPoints: () => "Clear points",
+  endAttempt: () => "End attempt",
+  uploadResponse: () => "Upload response",
+  movableObject: () => "Movable object",
+  placeObject: () => "Place",
+  inlineChoicePrompt: () => "Choose...",
+  noPointSelected: () => "No point selected",
+  noRegionSelected: () => "No region selected",
+  noAssociationsMade: () => "No associations made",
+  associationsMade: ({ count }) => `${count} ${count === 1 ? "association" : "associations"} made.`,
+  associationPairLabel: ({ source, target }) => `${source} to ${target}`,
+  hotspotSelectedChooseAnother: ({ label }) => `${label} selected. Choose another hotspot.`,
+  moveChoice: ({ label, direction }) => `Move ${label} ${direction}`,
+  movePoint: ({ direction }) => `Move point ${direction}`,
+  moveObject: ({ direction }) => `Move object ${direction}`,
+};
+
+const playerMessages = {
+  defaultEnglish: defaultEnglishPlayerMessages,
+  spanish: {
+    remove: () => "Quitar",
+    removePair: ({ label }) => `Quitar ${label}`,
+    clearDrawing: () => "Borrar dibujo",
+    clearPoints: () => "Borrar puntos",
+    endAttempt: () => "Finalizar intento",
+    uploadResponse: () => "Subir respuesta",
+    movableObject: () => "Objeto movible",
+    placeObject: () => "Colocar",
+    inlineChoicePrompt: () => "Elija...",
+    noPointSelected: () => "Ningun punto seleccionado",
+    noRegionSelected: () => "Ninguna region seleccionada",
+    noAssociationsMade: () => "Ninguna asociacion realizada",
+    associationsMade: ({ count }) =>
+      `${count} ${count === 1 ? "asociacion realizada" : "asociaciones realizadas"}.`,
+    associationPairLabel: ({ source, target }) => `${source} con ${target}`,
+    hotspotSelectedChooseAnother: ({ label }) => `${label} seleccionado. Elija otro punto activo.`,
+    moveChoice: ({ label, direction }) => `Mover ${label} ${spanishDirection(direction)}`,
+    movePoint: ({ direction }) => `Mover punto ${spanishDirection(direction)}`,
+    moveObject: ({ direction }) => `Mover objeto ${spanishDirection(direction)}`,
+  },
+  swedish: {
+    remove: () => "Ta bort",
+    removePair: ({ label }) => `Ta bort ${label}`,
+    clearDrawing: () => "Rensa ritning",
+    clearPoints: () => "Rensa punkter",
+    endAttempt: () => "Avsluta forsok",
+    uploadResponse: () => "Ladda upp svar",
+    movableObject: () => "Flyttbart objekt",
+    placeObject: () => "Placera",
+    inlineChoicePrompt: () => "Valj...",
+    noPointSelected: () => "Ingen punkt vald",
+    noRegionSelected: () => "Ingen region vald",
+    noAssociationsMade: () => "Inga associationer gjorda",
+    associationsMade: ({ count }) =>
+      `${count} ${count === 1 ? "association gjord" : "associationer gjorda"}.`,
+    associationPairLabel: ({ source, target }) => `${source} med ${target}`,
+    hotspotSelectedChooseAnother: ({ label }) => `${label} valt. Valj en annan hotspot.`,
+    moveChoice: ({ label, direction }) => `Flytta ${label} ${swedishDirection(direction)}`,
+    movePoint: ({ direction }) => `Flytta punkt ${swedishDirection(direction)}`,
+    moveObject: ({ direction }) => `Flytta objekt ${swedishDirection(direction)}`,
+  },
+  german: {
+    remove: () => "Entfernen",
+    removePair: ({ label }) => `${label} entfernen`,
+    clearDrawing: () => "Zeichnung loeschen",
+    clearPoints: () => "Punkte loeschen",
+    endAttempt: () => "Versuch beenden",
+    uploadResponse: () => "Antwort hochladen",
+    movableObject: () => "Bewegliches Objekt",
+    placeObject: () => "Platzieren",
+    inlineChoicePrompt: () => "Waehlen...",
+    noPointSelected: () => "Kein Punkt ausgewaehlt",
+    noRegionSelected: () => "Keine Region ausgewaehlt",
+    noAssociationsMade: () => "Keine Zuordnungen erstellt",
+    associationsMade: ({ count }) =>
+      `${count} ${count === 1 ? "Zuordnung erstellt" : "Zuordnungen erstellt"}.`,
+    associationPairLabel: ({ source, target }) => `${source} mit ${target}`,
+    hotspotSelectedChooseAnother: ({ label }) =>
+      `${label} ausgewaehlt. Waehlen Sie einen weiteren Hotspot.`,
+    moveChoice: ({ label, direction }) => `${label} ${germanDirection(direction)} bewegen`,
+    movePoint: ({ direction }) => `Punkt ${germanDirection(direction)} bewegen`,
+    moveObject: ({ direction }) => `Objekt ${germanDirection(direction)} bewegen`,
+  },
+  portuguese: {
+    remove: () => "Remover",
+    removePair: ({ label }) => `Remover ${label}`,
+    clearDrawing: () => "Limpar desenho",
+    clearPoints: () => "Limpar pontos",
+    endAttempt: () => "Finalizar tentativa",
+    uploadResponse: () => "Enviar resposta",
+    movableObject: () => "Objeto movel",
+    placeObject: () => "Posicionar",
+    inlineChoicePrompt: () => "Escolha...",
+    noPointSelected: () => "Nenhum ponto selecionado",
+    noRegionSelected: () => "Nenhuma regiao selecionada",
+    noAssociationsMade: () => "Nenhuma associacao feita",
+    associationsMade: ({ count }) =>
+      `${count} ${count === 1 ? "associacao feita" : "associacoes feitas"}.`,
+    associationPairLabel: ({ source, target }) => `${source} com ${target}`,
+    hotspotSelectedChooseAnother: ({ label }) => `${label} selecionado. Escolha outro ponto ativo.`,
+    moveChoice: ({ label, direction }) => `Mover ${label} ${portugueseDirection(direction)}`,
+    movePoint: ({ direction }) => `Mover ponto ${portugueseDirection(direction)}`,
+    moveObject: ({ direction }) => `Mover objeto ${portugueseDirection(direction)}`,
+  },
+  french: {
+    remove: () => "Supprimer",
+    removePair: ({ label }) => `Supprimer ${label}`,
+    clearDrawing: () => "Effacer le dessin",
+    clearPoints: () => "Effacer les points",
+    endAttempt: () => "Terminer la tentative",
+    uploadResponse: () => "Televerser la reponse",
+    movableObject: () => "Objet mobile",
+    placeObject: () => "Placer",
+    inlineChoicePrompt: () => "Choisir...",
+    noPointSelected: () => "Aucun point selectionne",
+    noRegionSelected: () => "Aucune region selectionnee",
+    noAssociationsMade: () => "Aucune association effectuee",
+    associationsMade: ({ count }) =>
+      `${count} ${count === 1 ? "association effectuee" : "associations effectuees"}.`,
+    associationPairLabel: ({ source, target }) => `${source} avec ${target}`,
+    hotspotSelectedChooseAnother: ({ label }) =>
+      `${label} selectionne. Choisissez un autre point actif.`,
+    moveChoice: ({ label, direction }) => `Deplacer ${label} vers ${frenchDirection(direction)}`,
+    movePoint: ({ direction }) => `Deplacer le point vers ${frenchDirection(direction)}`,
+    moveObject: ({ direction }) => `Deplacer l'objet vers ${frenchDirection(direction)}`,
+  },
+} satisfies Record<string, QtiPlayerMessageCatalog>;
+
+const builtInPlayerMessageCatalogs: ReadonlyMap<string, QtiPlayerMessageCatalog> = new Map([
+  ["en", playerMessages.defaultEnglish],
+  ["es", playerMessages.spanish],
+  ["es-es", playerMessages.spanish],
+  ["es-mx", playerMessages.spanish],
+  ["sv", playerMessages.swedish],
+  ["sv-se", playerMessages.swedish],
+  ["de", playerMessages.german],
+  ["de-de", playerMessages.german],
+  ["pt", playerMessages.portuguese],
+  ["pt-br", playerMessages.portuguese],
+  ["pt-pt", playerMessages.portuguese],
+  ["fr", playerMessages.french],
+  ["fr-ca", playerMessages.french],
+  ["fr-fr", playerMessages.french],
+]);
+
+export function resolvePlayerMessages(
+  locale: string,
+  overrides: QtiPlayerMessageOverrides,
+): QtiPlayerMessages {
+  const catalog = builtInPlayerMessageCatalog(locale);
+  return { ...defaultEnglishPlayerMessages, ...catalog, ...overrides };
+}
+
+function spanishDirection(direction: "up" | "down" | "left" | "right"): string {
+  return { up: "arriba", down: "abajo", left: "a la izquierda", right: "a la derecha" }[direction];
+}
+
+function swedishDirection(direction: "up" | "down" | "left" | "right"): string {
+  return { up: "upp", down: "ned", left: "vanster", right: "hoger" }[direction];
+}
+
+function germanDirection(direction: "up" | "down" | "left" | "right"): string {
+  return { up: "nach oben", down: "nach unten", left: "nach links", right: "nach rechts" }[
+    direction
+  ];
+}
+
+function portugueseDirection(direction: "up" | "down" | "left" | "right"): string {
+  return { up: "para cima", down: "para baixo", left: "para a esquerda", right: "para a direita" }[
+    direction
+  ];
+}
+
+function frenchDirection(direction: "up" | "down" | "left" | "right"): string {
+  return { up: "le haut", down: "le bas", left: "la gauche", right: "la droite" }[direction];
+}
+
+function builtInPlayerMessageCatalog(locale: string): QtiPlayerMessageCatalog | undefined {
+  for (const candidate of localeFallbacks(locale)) {
+    const catalog = builtInPlayerMessageCatalogs.get(candidate);
+    if (catalog) return catalog;
+  }
+  return undefined;
+}
+
+function localeFallbacks(locale: string): string[] {
+  const normalized = normalizedLocale(locale)?.toLowerCase();
+  if (!normalized) return ["en"];
+  const parts = normalized.split("-");
+  const fallbacks: string[] = [];
+  for (let length = parts.length; length > 0; length -= 1) {
+    fallbacks.push(parts.slice(0, length).join("-"));
+  }
+  return fallbacks.includes("en") ? fallbacks : [...fallbacks, "en"];
+}
+
+export function normalizedLocale(value: string | undefined | null): string | undefined {
+  const trimmed = value?.trim();
+  if (!trimmed) return undefined;
+  try {
+    return Intl.getCanonicalLocales(trimmed)[0] ?? trimmed;
+  } catch {
+    return trimmed;
+  }
+}
+
+export function defaultPlayerLocale(host?: Element): string {
+  const elementLanguage = normalizedLocale(host?.getAttribute("lang"));
+  if (elementLanguage) return elementLanguage;
+
+  const navigatorLanguages = globalThis.navigator?.languages ?? [];
+  for (const language of navigatorLanguages) {
+    const normalized = normalizedLocale(language);
+    if (normalized) return normalized;
+  }
+  return (
+    normalizedLocale(globalThis.navigator?.language) ??
+    normalizedLocale(host?.closest("[lang]")?.getAttribute("lang")) ??
+    normalizedLocale(host?.ownerDocument?.documentElement.lang) ??
+    normalizedLocale(globalThis.document?.documentElement.lang) ??
+    "en"
+  );
+}

package/src/player-messages.ts

@@ -0,0 +1,31 @@
+export interface QtiPlayerRemoveMessageParams {
+  label: string;
+}
+
+export interface QtiPlayerAssociationPairLabelParams {
+  source: string;
+  target: string;
+}
+
+export type QtiPlayerMovementDirection = "up" | "down" | "left" | "right";
+
+export interface QtiPlayerMessages {
+  remove: () => string;
+  removePair: (params: QtiPlayerRemoveMessageParams) => string;
+  clearDrawing: () => string;
+  clearPoints: () => string;
+  endAttempt: () => string;
+  uploadResponse: () => string;
+  movableObject: () => string;
+  placeObject: () => string;
+  inlineChoicePrompt: () => string;
+  noPointSelected: () => string;
+  noRegionSelected: () => string;
+  noAssociationsMade: () => string;
+  associationsMade: (params: { count: number }) => string;
+  associationPairLabel: (params: QtiPlayerAssociationPairLabelParams) => string;
+  hotspotSelectedChooseAnother: (params: { label: string }) => string;
+  moveChoice: (params: { label: string; direction: QtiPlayerMovementDirection }) => string;
+  movePoint: (params: { direction: QtiPlayerMovementDirection }) => string;
+  moveObject: (params: { direction: QtiPlayerMovementDirection }) => string;
+}

package/src/player-styles.ts

@@ -0,0 +1,25 @@
+import { BASE_PLAYER_STYLES } from "./styles/base-styles.js";
+import { CHOICE_HOTTEXT_PLAYER_STYLES } from "./styles/choice-hottext-styles.js";
+import { CONTROL_PLAYER_STYLES } from "./styles/control-styles.js";
+import { DRAWING_PLAYER_STYLES } from "./styles/drawing-styles.js";
+import { GAP_MATCH_PLAYER_STYLES } from "./styles/gap-match-styles.js";
+import { GRAPHIC_PLAYER_STYLES } from "./styles/graphic-styles.js";
+import { MATCH_PAIR_PLAYER_STYLES } from "./styles/match-pair-styles.js";
+import { TEXT_SLIDER_PLAYER_STYLES } from "./styles/text-slider-styles.js";
+
+export const PLAYER_STYLES = [
+  BASE_PLAYER_STYLES,
+  CONTROL_PLAYER_STYLES,
+  MATCH_PAIR_PLAYER_STYLES,
+  GAP_MATCH_PLAYER_STYLES,
+  CHOICE_HOTTEXT_PLAYER_STYLES,
+  TEXT_SLIDER_PLAYER_STYLES,
+  DRAWING_PLAYER_STYLES,
+  GRAPHIC_PLAYER_STYLES,
+].join("\n\n");
+
+export function playerStyleElement(): HTMLStyleElement {
+  const style = document.createElement("style");
+  style.textContent = PLAYER_STYLES;
+  return style;
+}

package/src/player-types.ts

@@ -0,0 +1,99 @@
+import type {
+  QtiAssessmentItem,
+  QtiAttemptStateV1,
+  QtiAttemptStatus,
+  QtiDiagnostic,
+  QtiInteraction,
+  QtiPortableCustomDefinition,
+  QtiPortableCustomStateValue,
+  QtiScoreResult,
+  QtiValue,
+} from "@longsightgroup/qti3-core";
+import type { QtiPlayerMessages } from "./player-messages.js";
+
+export interface QtiPlayerSessionControl {
+  validateResponses?: boolean | undefined;
+  showFeedback?: boolean | undefined;
+}
+
+export interface QtiScoreAttemptOptions {
+  validateResponses?: boolean | undefined;
+}
+
+export type QtiPlayerFetchXml = (url: string) => Promise<string>;
+export type QtiPlayerResolveAsset = (url: string) => string;
+
+export interface QtiPlayerLoadOptions {
+  state?: QtiAttemptStateV1 | undefined;
+  status?: QtiAttemptStatus | undefined;
+  sessionControl?: QtiPlayerSessionControl | undefined;
+  fetchXml?: QtiPlayerFetchXml | undefined;
+  resolveAsset?: QtiPlayerResolveAsset | undefined;
+}
+
+export type QtiPlayerMessageOverrides = Partial<QtiPlayerMessages>;
+
+export interface QtiReadyEventDetail {
+  item: QtiAssessmentItem;
+}
+
+export interface QtiStateChangeEventDetail {
+  /**
+   * Attempt snapshot. `state.validationMessages` combines load-time authoring diagnostics
+   * (unsupported interactions, missing choices, illegal embeds) with response validation
+   * messages. After `restore()`, response messages are reapplied separately from authoring
+   * diagnostics captured at `loadXml`.
+   */
+  state: QtiAttemptStateV1;
+}
+
+export interface QtiResponseChangeEventDetail {
+  responseIdentifier: string;
+  value: QtiValue;
+}
+
+export interface QtiPortableCustomMountEventDetail {
+  responseIdentifier: string;
+  interaction: QtiInteraction;
+  definition: QtiPortableCustomDefinition;
+  host: HTMLElement;
+  value: QtiValue;
+  state?: QtiPortableCustomStateValue | undefined;
+}
+
+export type QtiScoreEventDetail = QtiScoreResult;
+
+export interface QtiValidationEventDetail {
+  /** Authoring and response validation messages currently visible to the candidate. */
+  validationMessages: QtiDiagnostic[];
+  state: QtiAttemptStateV1;
+}
+
+export interface QtiSuspendEventDetail {
+  state: QtiAttemptStateV1;
+}
+
+export interface QtiEndAttemptEventDetail {
+  state: QtiAttemptStateV1;
+}
+
+export interface QtiAssessmentItemPlayerEventDetailMap {
+  "qti-ready": QtiReadyEventDetail;
+  "qti-statechange": QtiStateChangeEventDetail;
+  "qti-responsechange": QtiResponseChangeEventDetail;
+  "qti-portable-custom-mount": QtiPortableCustomMountEventDetail;
+  "qti-score": QtiScoreEventDetail;
+  "qti-validation": QtiValidationEventDetail;
+  "qti-suspend": QtiSuspendEventDetail;
+  "qti-endattempt": QtiEndAttemptEventDetail;
+}
+
+export type QtiAssessmentItemPlayerEventName = keyof QtiAssessmentItemPlayerEventDetailMap;
+
+export type QtiAssessmentItemPlayerEvent<
+  T extends QtiAssessmentItemPlayerEventName = QtiAssessmentItemPlayerEventName,
+> = CustomEvent<QtiAssessmentItemPlayerEventDetailMap[T]>;
+
+export type QtiAssessmentItemPlayerCustomEventMap = {
+  [T in QtiAssessmentItemPlayerEventName]: CustomEvent<QtiAssessmentItemPlayerEventDetailMap[T]>;
+};

package/src/player-validation-dom.ts

@@ -0,0 +1,31 @@
+import type { QtiDiagnostic } from "@longsightgroup/qti3-core";
+
+export function syncValidationMessages(root: ParentNode, messages: QtiDiagnostic[]): void {
+  const messagesByIdentifier = new Map(
+    messages.filter((message) => message.path).map((message) => [message.path!, message]),
+  );
+  for (const section of root.querySelectorAll<HTMLElement>("[data-response-identifier]")) {
+    const responseIdentifier = section.dataset.responseIdentifier;
+    if (!responseIdentifier) continue;
+    const message = messagesByIdentifier.get(responseIdentifier);
+    const messageElement = section.querySelector<HTMLElement>(
+      `[data-validation-for="${responseIdentifier}"]`,
+    );
+    const controls = section.querySelectorAll<HTMLElement>("input, select, textarea, button");
+    if (message && messageElement) {
+      messageElement.textContent = message.message;
+      messageElement.hidden = false;
+      for (const control of controls) {
+        control.setAttribute("aria-invalid", "true");
+        control.setAttribute("aria-describedby", messageElement.id);
+      }
+    } else if (messageElement) {
+      messageElement.textContent = "";
+      messageElement.hidden = true;
+      for (const control of controls) {
+        control.removeAttribute("aria-invalid");
+        control.removeAttribute("aria-describedby");
+      }
+    }
+  }
+}

package/src/player-validation.ts

@@ -0,0 +1,158 @@
+import { qtiValueToIdentifierList } from "@longsightgroup/qti3-core";
+import type {
+  QtiAttemptStateV1,
+  QtiDiagnostic,
+  QtiDocument,
+  QtiInteraction,
+  QtiValue,
+} from "@longsightgroup/qti3-core";
+import {
+  maximumAllowedResponses,
+  mediaPlayCount,
+  minimumMediaPlays,
+  parseUnlimitedMaximum,
+} from "./response-limits.js";
+
+export function errorView(message: string): HTMLElement {
+  const element = document.createElement("p");
+  element.role = "alert";
+  element.textContent = message;
+  return element;
+}
+
+export function validationMessageElement(responseIdentifier: string): HTMLElement {
+  const element = document.createElement("p");
+  element.id = validationMessageId(responseIdentifier);
+  element.dataset.validationFor = responseIdentifier;
+  element.hidden = true;
+  element.role = "alert";
+  return element;
+}
+
+export function inlineValidationMessageElement(responseIdentifier: string): HTMLElement {
+  const element = document.createElement("span");
+  element.id = validationMessageId(responseIdentifier);
+  element.dataset.validationFor = responseIdentifier;
+  element.hidden = true;
+  element.role = "alert";
+  return element;
+}
+
+export function validationMessageId(responseIdentifier: string): string {
+  return `qti3-validation-${responseIdentifier}`;
+}
+
+export function cloneDiagnostics(diagnostics: QtiDiagnostic[]): QtiDiagnostic[] {
+  return diagnostics.map((diagnostic) => ({
+    ...diagnostic,
+    source: diagnostic.source ? { ...diagnostic.source } : undefined,
+  }));
+}
+
+export function responseIsEmpty(value: QtiValue): boolean {
+  return value === null || value === "" || (Array.isArray(value) && value.length === 0);
+}
+
+export function responseCount(value: QtiValue): number {
+  return responseIsEmpty(value) ? 0 : Array.isArray(value) ? value.length : 1;
+}
+
+export function minimumRequiredResponses(interaction: QtiInteraction | undefined): number {
+  if (!interaction) return 1;
+  if (interaction.type === "media") return minimumMediaPlays(interaction);
+  const explicit =
+    interaction.attributes["min-choices"] ?? interaction.attributes["min-associations"];
+  if (explicit === undefined) return 1;
+  const parsed = Number(explicit);
+  return Number.isInteger(parsed) && parsed >= 0 ? parsed : 1;
+}
+
+export function matchMaxDiagnostics(
+  responseIdentifier: string,
+  interaction: QtiInteraction,
+  response: QtiValue,
+): QtiDiagnostic[] {
+  const identifiers = responseChoiceIdentifiers(response);
+  if (identifiers.length === 0) return [];
+  const counts = new Map<string, number>();
+  for (const identifier of identifiers) {
+    counts.set(identifier, (counts.get(identifier) ?? 0) + 1);
+  }
+
+  const diagnostics: QtiDiagnostic[] = [];
+  for (const choice of interaction.choices) {
+    const maximum = parseUnlimitedMaximum(choice.attributes["match-max"]);
+    if (maximum === undefined) continue;
+    const count = counts.get(choice.identifier) ?? 0;
+    if (count <= maximum) continue;
+    diagnostics.push({
+      code: "response.matchMax",
+      severity: "error",
+      message: `${choice.text || choice.identifier} may be used at most ${maximum} time${maximum === 1 ? "" : "s"}.`,
+      path: responseIdentifier,
+    });
+  }
+  return diagnostics;
+}
+
+export function responseChoiceIdentifiers(response: QtiValue): string[] {
+  return qtiValueToIdentifierList(response).flatMap((value) => value.split(/\s+/).filter(Boolean));
+}
+
+export function validateItemResponses(
+  document: QtiDocument,
+  state: QtiAttemptStateV1,
+): QtiDiagnostic[] {
+  const interactionsByResponse = new Map(
+    document.item.interactions
+      .filter((interaction) => interaction.responseIdentifier)
+      .map((interaction) => [interaction.responseIdentifier!, interaction]),
+  );
+  const diagnostics: QtiDiagnostic[] = [];
+  for (const declaration of document.item.responseDeclarations) {
+    const interaction = interactionsByResponse.get(declaration.identifier);
+    if (declaration.correctResponse === null && interaction?.type !== "media") continue;
+    const minimum = minimumRequiredResponses(interaction);
+    const count =
+      interaction?.type === "media"
+        ? mediaPlayCount(state.responses[declaration.identifier] ?? null)
+        : responseCount(state.responses[declaration.identifier] ?? null);
+    const maximum = maximumAllowedResponses(interaction);
+    if (count < minimum) {
+      diagnostics.push({
+        code: "response.required",
+        severity: "error",
+        message:
+          interaction?.attributes["data-min-selections-message"] ??
+          (interaction?.type === "media"
+            ? `${declaration.identifier} requires at least ${minimum} play${minimum === 1 ? "" : "s"}.`
+            : minimum === 1
+              ? `${declaration.identifier} requires a response.`
+              : `${declaration.identifier} requires at least ${minimum} responses.`),
+        path: declaration.identifier,
+      });
+    }
+    if (maximum !== undefined && count > maximum) {
+      diagnostics.push({
+        code: "response.maximum",
+        severity: "error",
+        message:
+          interaction?.attributes["data-max-selections-message"] ??
+          (interaction?.type === "media"
+            ? `${declaration.identifier} allows at most ${maximum} play${maximum === 1 ? "" : "s"}.`
+            : `${declaration.identifier} allows at most ${maximum} response${maximum === 1 ? "" : "s"}.`),
+        path: declaration.identifier,
+      });
+    }
+    if (interaction) {
+      diagnostics.push(
+        ...matchMaxDiagnostics(
+          declaration.identifier,
+          interaction,
+          state.responses[declaration.identifier] ?? null,
+        ),
+      );
+    }
+  }
+  return diagnostics;
+}

package/src/portable-custom-support.ts

@@ -0,0 +1,74 @@
+import type {
+  QtiInteraction,
+  QtiPortableCustomDefinition,
+  QtiPortableCustomStateValue,
+  QtiValue,
+} from "@longsightgroup/qti3-core";
+
+export function scalarString(value: QtiValue): string {
+  if (value === null || Array.isArray(value) || typeof value === "object") return "";
+  return String(value);
+}
+
+export function portableCustomDefinitionFromAttributes(
+  interaction: QtiInteraction,
+): QtiPortableCustomDefinition {
+  return {
+    responseIdentifier: interaction.responseIdentifier,
+    customInteractionTypeIdentifier: interaction.attributes["custom-interaction-type-identifier"],
+    module: interaction.attributes.module,
+    interactionMarkup: [],
+    templateVariables: [],
+    contextVariables: [],
+    stylesheets: [],
+    dataAttributes: Object.fromEntries(
+      Object.entries(interaction.attributes).filter(([name]) => name.startsWith("data-")),
+    ),
+    attributes: interaction.attributes,
+    source: interaction.source,
+  };
+}
+
+export function portableCustomEventValue(event: Event): QtiValue | undefined {
+  if (!("detail" in event)) return undefined;
+  const detail = event.detail as { value?: QtiValue; response?: QtiValue } | QtiValue | undefined;
+  if (detail === undefined) return undefined;
+  if (typeof detail === "object" && detail !== null && !Array.isArray(detail)) {
+    if ("value" in detail) return detail.value ?? null;
+    if ("response" in detail) return detail.response ?? null;
+    if ("state" in detail || "valid" in detail) return undefined;
+  }
+  return detail as QtiValue;
+}
+
+export function portableCustomEventState(event: Event): QtiPortableCustomStateValue | undefined {
+  if (!("detail" in event)) return undefined;
+  const detail = event.detail as { state?: unknown } | undefined;
+  if (typeof detail !== "object" || detail === null || !("state" in detail)) return undefined;
+  return isPortableCustomStateValue(detail.state) ? detail.state : undefined;
+}
+
+export function portableCustomEventValidity(
+  event: Event,
+): { valid: boolean; message?: string | undefined } | undefined {
+  if (!("detail" in event)) return undefined;
+  const detail = event.detail as { valid?: unknown; message?: unknown } | undefined;
+  if (typeof detail !== "object" || detail === null || typeof detail.valid !== "boolean") {
+    return undefined;
+  }
+  return {
+    valid: detail.valid,
+    message: typeof detail.message === "string" ? detail.message : undefined,
+  };
+}
+
+export function isPortableCustomStateValue(value: unknown): value is QtiPortableCustomStateValue {
+  if (value === null) return true;
+  if (typeof value === "string" || typeof value === "boolean") return true;
+  if (typeof value === "number") return Number.isFinite(value);
+  if (Array.isArray(value)) return value.every(isPortableCustomStateValue);
+  if (typeof value === "object") {
+    return Object.values(value as Record<string, unknown>).every(isPortableCustomStateValue);
+  }
+  return false;
+}