@longsightgroup/qti3-core 0.1.2 → 0.2.0

package/src/catalog.ts

@@ -0,0 +1,193 @@
+import type {
+  QtiAssessmentItem,
+  QtiCatalog,
+  QtiCatalogCard,
+  QtiCatalogCardEntry,
+  QtiCatalogFileHref,
+  QtiCatalogHtmlContent,
+  QtiDocument,
+  QtiSourceLocation,
+} from "./types.js";
+
+export interface QtiCatalogSupportResolutionOptions {
+  supports?: string | readonly string[] | undefined;
+  languages?: string | readonly string[] | undefined;
+  includeDefaultFallback?: boolean | undefined;
+}
+
+export interface QtiCatalogSupportResolution {
+  itemIdentifier: string;
+  references: QtiResolvedCatalogReference[];
+}
+
+export interface QtiResolvedCatalogReference {
+  idref: string;
+  catalog?: QtiCatalog | undefined;
+  matches: QtiResolvedCatalogSupport[];
+  source?: QtiSourceLocation | undefined;
+}
+
+export interface QtiResolvedCatalogSupport {
+  catalogId: string;
+  support: string;
+  default: boolean;
+  fileHrefs: QtiCatalogFileHref[];
+  attributes: Record<string, string>;
+  cardAttributes: Record<string, string>;
+  catalogAttributes: Record<string, string>;
+  language?: string | undefined;
+  htmlContent?: QtiCatalogHtmlContent | undefined;
+  source?: QtiSourceLocation | undefined;
+  cardSource?: QtiSourceLocation | undefined;
+  catalogSource?: QtiSourceLocation | undefined;
+}
+
+interface Candidate {
+  card: QtiCatalogCard;
+  default: boolean;
+  fileHrefs: QtiCatalogFileHref[];
+  attributes: Record<string, string>;
+  language?: string | undefined;
+  htmlContent?: QtiCatalogHtmlContent | undefined;
+  source?: QtiSourceLocation | undefined;
+}
+
+export function createCatalogSupportResolution(
+  model: QtiDocument | QtiAssessmentItem,
+  options: QtiCatalogSupportResolutionOptions = {},
+): QtiCatalogSupportResolution {
+  const item = "item" in model ? model.item : model;
+  const supportFilter = stringFilter(options.supports);
+  const languages = stringList(options.languages).map((language) => language.toLowerCase());
+  const catalogById = new Map(
+    item.catalogInfo?.catalogs.map((catalog) => [catalog.id, catalog] as const) ?? [],
+  );
+
+  return {
+    itemIdentifier: item.identifier,
+    references: item.catalogReferences.map((reference) => {
+      const catalog = catalogById.get(reference.idref);
+      const resolved: QtiResolvedCatalogReference = {
+        idref: reference.idref,
+        matches: catalog ? matchingCatalogSupports(catalog, supportFilter, languages, options) : [],
+      };
+      if (catalog) resolved.catalog = catalog;
+      if (reference.source) resolved.source = reference.source;
+      return resolved;
+    }),
+  };
+}
+
+function matchingCatalogSupports(
+  catalog: QtiCatalog,
+  supportFilter: Set<string> | undefined,
+  languages: string[],
+  options: QtiCatalogSupportResolutionOptions,
+): QtiResolvedCatalogSupport[] {
+  return catalog.cards.flatMap((card) => {
+    if (supportFilter && !supportFilter.has(card.support.toLowerCase())) return [];
+    return selectedCandidates(card, languages, options).map((candidate) =>
+      resolvedSupport(catalog, candidate),
+    );
+  });
+}
+
+function selectedCandidates(
+  card: QtiCatalogCard,
+  languages: string[],
+  options: QtiCatalogSupportResolutionOptions,
+): Candidate[] {
+  const candidates = catalogCandidates(card);
+  if (languages.length === 0) {
+    const defaults = candidates.filter((candidate) => candidate.default);
+    return defaults.length > 0 ? defaults : candidates;
+  }
+
+  const languageMatches = candidates
+    .map((candidate, index) => ({
+      candidate,
+      index,
+      rank: languageMatchRank(candidate.language, languages),
+    }))
+    .filter((entry): entry is { candidate: Candidate; index: number; rank: number } =>
+      Number.isInteger(entry.rank),
+    )
+    .sort((a, b) => a.rank - b.rank || a.index - b.index);
+  if (languageMatches.length > 0) return languageMatches.map((entry) => entry.candidate);
+  if (options.includeDefaultFallback === false) return [];
+  const defaults = candidates.filter((candidate) => candidate.default);
+  return defaults.length > 0 ? defaults : candidates.filter((candidate) => !candidate.language);
+}
+
+function catalogCandidates(card: QtiCatalogCard): Candidate[] {
+  if (card.entries.length > 0) {
+    return card.entries.map((entry) => entryCandidate(card, entry));
+  }
+  return [
+    {
+      card,
+      default: true,
+      fileHrefs: card.fileHrefs,
+      attributes: card.attributes,
+      htmlContent: card.htmlContent,
+      source: card.source,
+    },
+  ];
+}
+
+function entryCandidate(card: QtiCatalogCard, entry: QtiCatalogCardEntry): Candidate {
+  const candidate: Candidate = {
+    card,
+    default: entry.default,
+    fileHrefs: entry.fileHrefs,
+    attributes: entry.attributes,
+  };
+  if (entry.language) candidate.language = entry.language;
+  if (entry.htmlContent) candidate.htmlContent = entry.htmlContent;
+  if (entry.source) candidate.source = entry.source;
+  return candidate;
+}
+
+function resolvedSupport(catalog: QtiCatalog, candidate: Candidate): QtiResolvedCatalogSupport {
+  const resolved: QtiResolvedCatalogSupport = {
+    catalogId: catalog.id,
+    support: candidate.card.support,
+    default: candidate.default,
+    fileHrefs: candidate.fileHrefs,
+    attributes: candidate.attributes,
+    cardAttributes: candidate.card.attributes,
+    catalogAttributes: catalog.attributes,
+  };
+  if (candidate.language) resolved.language = candidate.language;
+  if (candidate.htmlContent) resolved.htmlContent = candidate.htmlContent;
+  if (candidate.source) resolved.source = candidate.source;
+  if (candidate.card.source) resolved.cardSource = candidate.card.source;
+  if (catalog.source) resolved.catalogSource = catalog.source;
+  return resolved;
+}
+
+function languageMatchRank(
+  language: string | undefined,
+  requestedLanguages: string[],
+): number | undefined {
+  if (!language) return undefined;
+  const normalizedLanguage = language.toLowerCase();
+  const primaryLanguage = normalizedLanguage.split("-")[0] ?? normalizedLanguage;
+  for (const [index, requestedLanguage] of requestedLanguages.entries()) {
+    if (normalizedLanguage === requestedLanguage) return index * 2;
+    const requestedPrimary = requestedLanguage.split("-")[0] ?? requestedLanguage;
+    if (primaryLanguage === requestedPrimary) return index * 2 + 1;
+  }
+  return undefined;
+}
+
+function stringFilter(value: string | readonly string[] | undefined): Set<string> | undefined {
+  const values = stringList(value).map((entry) => entry.toLowerCase());
+  return values.length > 0 ? new Set(values) : undefined;
+}
+
+function stringList(value: string | readonly string[] | undefined): string[] {
+  if (value === undefined) return [];
+  const entries = Array.isArray(value) ? value : [value];
+  return entries.map((entry) => entry.trim()).filter((entry) => entry.length > 0);
+}

package/src/index.ts

@@ -1,4 +1,27 @@
+export {
+  createCatalogSupportResolution,
+  type QtiCatalogSupportResolution,
+  type QtiCatalogSupportResolutionOptions,
+  type QtiResolvedCatalogReference,
+  type QtiResolvedCatalogSupport,
+} from "./catalog.js";
 export { parseQtiXml } from "./parser.js";
+export {
+  createTextToSpeechTraversal,
+  parseQtiDataSsml,
+  validateQtiDataSsmlMetadata,
+  type QtiDataSsml,
+  type QtiDataSsmlBreak,
+  type QtiDataSsmlBreakStrength,
+  type QtiDataSsmlParseResult,
+  type QtiDataSsmlPhoneme,
+  type QtiDataSsmlProsody,
+  type QtiDataSsmlSayAs,
+  type QtiDataSsmlSub,
+  type QtiTextToSpeechSegment,
+  type QtiTextToSpeechSegmentKind,
+  type QtiTextToSpeechTraversal,
+} from "./tts.js";
 export {
   assertQtiAttemptStateV1,
   createItemSession,
@@ -23,6 +46,13 @@ export type {
   QtiAssessmentItem,
   QtiAttemptStatus,
   QtiAttemptStateV1,
+  QtiCatalog,
+  QtiCatalogCard,
+  QtiCatalogCardEntry,
+  QtiCatalogFileHref,
+  QtiCatalogHtmlContent,
+  QtiCatalogInfo,
+  QtiCatalogReference,
   QtiChoice,
   QtiChoiceRole,
   QtiContentNode,
@@ -38,6 +68,11 @@ export type {
   QtiObjectAsset,
   QtiParseResult,
   QtiProcessingElementSupport,
+  QtiPortableCustomDefinition,
+  QtiPortableCustomInteractionModule,
+  QtiPortableCustomInteractionModules,
+  QtiPortableCustomStateValue,
+  QtiPortableCustomVariableBinding,
   QtiResponseBranch,
   QtiScoreResult,
   QtiSupportStatus,

package/src/parser.ts

@@ -24,6 +24,10 @@ import type {
   QtiOutcomeDeclaration,
   QtiParseResult,
   QtiProcessingExpression,
+  QtiPortableCustomDefinition,
+  QtiPortableCustomInteractionModule,
+  QtiPortableCustomInteractionModules,
+  QtiPortableCustomVariableBinding,
   QtiRecordValue,
   QtiResponseCondition,
   QtiResponseDeclaration,
@@ -140,6 +144,7 @@ function parseAssessmentItem(node: XmlNode, diagnostics: QtiDiagnostic[]): QtiAs
   return {
     identifier,
     title: node.attributes.title,
+    language: node.attributes["xml:lang"] ?? node.attributes.lang,
     adaptive: node.attributes.adaptive === "true",
     prompt: prompt ? textContent(prompt) : undefined,
     responseDeclarations,
@@ -468,12 +473,18 @@ function parseInteraction(
     responseCardinality: responseDeclaration?.cardinality,
     responseBaseType: responseDeclaration?.baseType,
     prompt: prompt ? textContent(prompt) : undefined,
+    promptAttributes: prompt?.attributes,
+    promptSource: prompt?.source,
     contextText: inlineInteractionContext(node, interactionType),
     object: parseObjectAsset(objectNode),
     positionObjectStage:
       interactionType === "positionObject"
         ? parseObjectAsset(positionObjectStageObject(node))
         : undefined,
+    portableCustom:
+      interactionType === "portableCustom"
+        ? parsePortableCustomDefinition(node, diagnostics)
+        : undefined,
     choices: parseChoices(node),
     hottextSegments: interactionType === "hottext" ? parseHottextSegments(node) : undefined,
     gapMatchSegments:
@@ -490,6 +501,172 @@ function parseInteraction(
   };
 }
 
+function parsePortableCustomDefinition(
+  node: XmlNode,
+  diagnostics: QtiDiagnostic[],
+): QtiPortableCustomDefinition {
+  const markup = firstChildElement(node, "qti-interaction-markup", diagnostics);
+  const modules = firstChildElement(node, "qti-interaction-modules", diagnostics);
+  return {
+    responseIdentifier: node.attributes["response-identifier"],
+    customInteractionTypeIdentifier: node.attributes["custom-interaction-type-identifier"],
+    module: node.attributes.module,
+    interactionModules: modules ? parsePortableCustomInteractionModules(modules) : undefined,
+    interactionMarkup: markup ? parsePortableCustomMarkupChildren(markup, diagnostics) : [],
+    interactionMarkupRaw: markup ? serializeXmlContent(markup) : undefined,
+    templateVariables: childElements(node, "qti-template-variable").map((variable) =>
+      parsePortableCustomVariableBinding(variable, "template"),
+    ),
+    contextVariables: childElements(node, "qti-context-variable").map((variable) =>
+      parsePortableCustomVariableBinding(variable, "context"),
+    ),
+    stylesheets: childElements(node, "qti-stylesheet").map(parseStylesheet),
+    catalogInfo: parseCatalogInfo(childElements(node, "qti-catalog-info")[0]),
+    dataAttributes: Object.fromEntries(
+      Object.entries(node.attributes).filter(([name]) => name.startsWith("data-")),
+    ),
+    attributes: node.attributes,
+    source: node.source,
+  };
+}
+
+function firstChildElement(
+  node: XmlNode,
+  name: string,
+  diagnostics: QtiDiagnostic[],
+): XmlNode | undefined {
+  const matches = childElements(node, name);
+  if (matches.length > 1) {
+    diagnostics.push({
+      code: "interaction.portableCustom.child.duplicate",
+      severity: "error",
+      message: `${node.localName} allows at most one ${name} child.`,
+      path: matches[1]?.source?.path ?? node.source?.path,
+      source: matches[1]?.source ?? node.source,
+    });
+  }
+  return matches[0];
+}
+
+function parsePortableCustomMarkupChildren(
+  node: XmlNode,
+  diagnostics: QtiDiagnostic[],
+): QtiContentNode[] {
+  const content: QtiContentNode[] = [];
+  for (const entry of node.content) {
+    if (typeof entry === "string") {
+      if (entry.length > 0) content.push({ kind: "text", text: entry, source: node.source });
+      continue;
+    }
+    content.push(parsePortableCustomMarkupNode(entry, diagnostics));
+  }
+  return content;
+}
+
+function parsePortableCustomMarkupNode(
+  node: XmlNode,
+  diagnostics: QtiDiagnostic[],
+): QtiContentNode {
+  if (isInteractionElement(node)) {
+    diagnostics.push({
+      code: "interaction.portableCustom.markupInteraction",
+      severity: "error",
+      message: `qti-interaction-markup must not contain nested QTI interaction ${node.localName}.`,
+      path: node.source?.path,
+      source: node.source,
+    });
+  }
+
+  if (node.localName === "qti-printed-variable") {
+    return {
+      kind: "printedVariable",
+      identifier: node.attributes.identifier ?? "",
+      format: node.attributes.format,
+      attributes: node.attributes,
+      source: node.source,
+    };
+  }
+
+  if (node.localName === "qti-feedback-block" || node.localName === "qti-feedback-inline") {
+    return {
+      kind: "feedback",
+      feedbackType: node.localName === "qti-feedback-block" ? "block" : "inline",
+      identifier: node.attributes.identifier ?? "",
+      outcomeIdentifier: node.attributes["outcome-identifier"] ?? "",
+      showHide: node.attributes["show-hide"] === "hide" ? "hide" : "show",
+      attributes: node.attributes,
+      children: parsePortableCustomMarkupChildren(node, diagnostics),
+      source: node.source,
+    };
+  }
+
+  return {
+    kind: "element",
+    qtiName: node.localName,
+    attributes: node.attributes,
+    children: parsePortableCustomMarkupChildren(node, diagnostics),
+    source: node.source,
+  };
+}
+
+function parsePortableCustomInteractionModules(node: XmlNode): QtiPortableCustomInteractionModules {
+  return {
+    primaryConfiguration: node.attributes["primary-configuration"],
+    secondaryConfiguration:
+      node.attributes["secondary-configuration"] ?? node.attributes["fallback-configuration"],
+    modules: childElements(node, "qti-interaction-module").map(
+      parsePortableCustomInteractionModule,
+    ),
+    attributes: node.attributes,
+    source: node.source,
+  };
+}
+
+function parsePortableCustomInteractionModule(node: XmlNode): QtiPortableCustomInteractionModule {
+  return {
+    id: node.attributes.id,
+    primaryPath: node.attributes["primary-path"],
+    fallbackPath: node.attributes["fallback-path"],
+    attributes: node.attributes,
+    source: node.source,
+  };
+}
+
+function parsePortableCustomVariableBinding(
+  node: XmlNode,
+  kind: QtiPortableCustomVariableBinding["kind"],
+): QtiPortableCustomVariableBinding {
+  return {
+    kind,
+    identifier: node.attributes.identifier ?? node.attributes["template-identifier"],
+    variableIdentifier: node.attributes["variable-identifier"],
+    attributes: node.attributes,
+    source: node.source,
+  };
+}
+
+function serializeXmlContent(node: XmlNode): string {
+  return node.content
+    .map((entry) => (typeof entry === "string" ? escapeXmlText(entry) : serializeXmlNode(entry)))
+    .join("");
+}
+
+function serializeXmlNode(node: XmlNode): string {
+  const attributes = Object.entries(node.attributes)
+    .map(([name, value]) => ` ${name}="${escapeXmlAttribute(value)}"`)
+    .join("");
+  if (node.content.length === 0) return `<${node.name}${attributes}/>`;
+  return `<${node.name}${attributes}>${serializeXmlContent(node)}</${node.name}>`;
+}
+
+function escapeXmlText(value: string): string {
+  return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
+
+function escapeXmlAttribute(value: string): string {
+  return escapeXmlText(value).replaceAll('"', "&quot;");
+}
+
 function positionObjectInteractionObject(node: XmlNode): XmlNode | undefined {
   return childElements(node).find(
     (child) => child.localName === "object" || child.localName === "img",
@@ -620,6 +797,7 @@ function parseObjectAsset(node: XmlNode | undefined): QtiObjectAsset | undefined
   const data = node.attributes.data ?? node.attributes.src ?? pictureImage?.attributes.src;
   const sources = parseMediaSources(node);
   const tracks = parseMediaTracks(node);
+  const inferredSvgDimensions = inlineSvgDimensions(data);
   return {
     data,
     type:
@@ -627,16 +805,101 @@ function parseObjectAsset(node: XmlNode | undefined): QtiObjectAsset | undefined
       pictureImage?.attributes.type ??
       assetTypeFromData(data) ??
       firstSourceType(sources),
-    width: node.attributes.width ?? pictureImage?.attributes.width,
-    height: node.attributes.height ?? pictureImage?.attributes.height,
+    width: node.attributes.width ?? pictureImage?.attributes.width ?? inferredSvgDimensions?.width,
+    height:
+      node.attributes.height ?? pictureImage?.attributes.height ?? inferredSvgDimensions?.height,
     sources,
     tracks,
-    text: textContent(node) || pictureImage?.attributes.alt || "",
+    text: textContent(node) || node.attributes.alt || pictureImage?.attributes.alt || "",
     attributes: node.attributes,
     source: node.source,
   };
 }
 
+function inlineSvgDimensions(
+  data: string | undefined,
+): { width: string; height: string } | undefined {
+  const svgText = decodeInlineSvgData(data);
+  if (!svgText) return undefined;
+  const tree = parseXmlTree(svgText);
+  const svg = tree.root;
+  if (!svg || svg.localName !== "svg") return undefined;
+
+  const width = svgLength(svg.attributes.width);
+  const height = svgLength(svg.attributes.height);
+  if (width !== undefined && height !== undefined) {
+    return { width: formatDimension(width), height: formatDimension(height) };
+  }
+
+  const viewBox = svgViewBoxDimensions(svg.attributes.viewBox);
+  if (!viewBox) return undefined;
+  const inferredWidth = width ?? viewBox.width;
+  const inferredHeight = height ?? viewBox.height;
+  if (inferredWidth <= 0 || inferredHeight <= 0) return undefined;
+  return { width: formatDimension(inferredWidth), height: formatDimension(inferredHeight) };
+}
+
+function decodeInlineSvgData(data: string | undefined): string | undefined {
+  if (!data) return undefined;
+  const comma = data.indexOf(",");
+  if (comma < 0) return undefined;
+  const metadata = data.slice(0, comma);
+  if (!/^data:image\/svg\+xml(?:[;,]|$)/i.test(metadata)) return undefined;
+  const payload = data.slice(comma + 1);
+  if (/;base64(?:[;,]|$)/i.test(metadata)) return decodeBase64Ascii(payload);
+  try {
+    return decodeURIComponent(payload);
+  } catch {
+    return payload;
+  }
+}
+
+function decodeBase64Ascii(value: string): string | undefined {
+  const alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+  const cleaned = value.replace(/\s+/g, "").replace(/=+$/, "");
+  let bits = 0;
+  let buffer = 0;
+  let output = "";
+  for (const char of cleaned) {
+    const digit = alphabet.indexOf(char);
+    if (digit < 0) return undefined;
+    buffer = (buffer << 6) | digit;
+    bits += 6;
+    if (bits < 8) continue;
+    bits -= 8;
+    output += String.fromCharCode((buffer >> bits) & 0xff);
+  }
+  return output;
+}
+
+function svgLength(value: string | undefined): number | undefined {
+  if (!value || value.trim().endsWith("%")) return undefined;
+  const match = value.trim().match(/^(\d+(?:\.\d+)?|\.\d+)(?:px)?$/i);
+  if (!match?.[1]) return undefined;
+  const parsed = Number(match[1]);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined;
+}
+
+function svgViewBoxDimensions(
+  value: string | undefined,
+): { width: number; height: number } | undefined {
+  const parts = value
+    ?.trim()
+    .split(/[\s,]+/)
+    .map((part) => Number(part));
+  if (!parts || parts.length !== 4 || parts.some((part) => !Number.isFinite(part))) {
+    return undefined;
+  }
+  const width = parts[2];
+  const height = parts[3];
+  if (width === undefined || height === undefined || width <= 0 || height <= 0) return undefined;
+  return { width, height };
+}
+
+function formatDimension(value: number): string {
+  return Number.isInteger(value) ? String(value) : String(Number(value.toFixed(4)));
+}
+
 function parseMediaSources(node: XmlNode): QtiMediaSource[] {
   return childElements(node, "source").map((source) => {
     const src = source.attributes.src ?? firstSrcsetCandidate(source.attributes.srcset);