@longsightgroup/qti3-core 0.8.0 → 0.8.2

package/src/parser-item-metadata.ts

@@ -9,10 +9,16 @@ import type {
   QtiCompanionMaterialsUnparsedChild,
   QtiContentNode,
   QtiDiagnostic,
+  QtiDigitalMaterial,
   QtiModalFeedback,
   QtiPhysicalMaterial,
   QtiStylesheet,
 } from "./types.js";
+import {
+  PARSED_COMPANION_MATERIAL_CHILD_NAMES,
+  type ParsedCompanionMaterialChildQtiName,
+  pushCompanionMaterialParseWarning,
+} from "./companion-materials.js";
 import { childElements, descendants, textContent, type XmlNode } from "./xml.js";
 
 export function firstChildElement(
@@ -146,12 +152,23 @@ export function parseCompanionMaterialsInfo(
   if (!node) return undefined;
 
   const physicalMaterials: QtiPhysicalMaterial[] = [];
+  const digitalMaterials: QtiDigitalMaterial[] = [];
   const unparsedChildren: QtiCompanionMaterialsUnparsedChild[] = [];
 
-  for (const child of childElements(node)) {
-    if (child.localName === "qti-physical-material") {
+  const companionMaterialHandlers = {
+    "qti-physical-material": (child) => {
       const material = parsePhysicalMaterial(child, diagnostics);
       if (material) physicalMaterials.push(material);
+    },
+    "qti-digital-material": (child) => {
+      const material = parseDigitalMaterial(child, diagnostics);
+      if (material) digitalMaterials.push(material);
+    },
+  } satisfies Record<ParsedCompanionMaterialChildQtiName, (child: XmlNode) => void>;
+
+  for (const child of childElements(node)) {
+    if (isParsedCompanionMaterialChildQtiName(child.localName)) {
+      companionMaterialHandlers[child.localName](child);
       continue;
     }
 
@@ -167,6 +184,7 @@ export function parseCompanionMaterialsInfo(
 
   return {
     physicalMaterials,
+    digitalMaterials,
     unparsedChildren,
     source: node.source,
   };
@@ -178,17 +196,68 @@ function parsePhysicalMaterial(
 ): QtiPhysicalMaterial | undefined {
   const text = textContent(node).trim();
   if (text.length === 0) {
-    diagnostics.push({
-      code: "companionMaterials.physicalMaterial.empty",
-      severity: "warning",
-      message: "qti-physical-material requires non-empty text content.",
-      path: node.source?.path,
-      source: node.source,
-    });
-    return undefined;
+    return pushCompanionMaterialParseWarning(
+      diagnostics,
+      "companionMaterials.physicalMaterial.empty",
+      "qti-physical-material requires non-empty text content.",
+      node.source?.path,
+      node.source,
+    );
   }
   return {
     text,
     source: node.source,
   };
 }
+
+function parseDigitalMaterial(
+  node: XmlNode,
+  diagnostics: QtiDiagnostic[],
+): QtiDigitalMaterial | undefined {
+  const fileHrefNode = firstChildElement(
+    node,
+    "qti-file-href",
+    diagnostics,
+    "companionMaterials.digitalMaterial.fileHref.duplicate",
+  );
+  if (!fileHrefNode) {
+    return pushCompanionMaterialParseWarning(
+      diagnostics,
+      "companionMaterials.digitalMaterial.fileHref.missing",
+      "qti-digital-material requires a qti-file-href child.",
+      node.source?.path,
+      node.source,
+    );
+  }
+
+  const fileHref = textContent(fileHrefNode).trim();
+  if (fileHref.length === 0) {
+    return pushCompanionMaterialParseWarning(
+      diagnostics,
+      "companionMaterials.digitalMaterial.fileHref.empty",
+      "qti-digital-material qti-file-href requires non-empty text content.",
+      fileHrefNode.source?.path,
+      fileHrefNode.source,
+    );
+  }
+
+  const resourceIconNode = firstChildElement(
+    node,
+    "qti-resource-icon",
+    diagnostics,
+    "companionMaterials.digitalMaterial.resourceIcon.duplicate",
+  );
+  const resourceIcon = resourceIconNode ? textContent(resourceIconNode).trim() : "";
+  return {
+    fileHref,
+    resourceIcon: resourceIcon.length > 0 ? resourceIcon : undefined,
+    attributes: node.attributes,
+    source: node.source,
+  };
+}
+
+function isParsedCompanionMaterialChildQtiName(
+  localName: string,
+): localName is ParsedCompanionMaterialChildQtiName {
+  return PARSED_COMPANION_MATERIAL_CHILD_NAMES.has(localName);
+}

package/src/shared-vocabulary-authoring.ts

@@ -28,6 +28,12 @@ export type QtiSharedVocabularyState = Record<string, QtiSharedVocabularyStateVa
 
 export type QtiSharedVocabularyAttributeValueType = "string" | "number" | "token-list";
 
+export function parsePositiveNumber(value: string | undefined): number | undefined {
+  if (value === undefined || value === "") return undefined;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined;
+}
+
 export type QtiSharedVocabularyField =
   | {
       kind: "class-value";
@@ -51,6 +57,7 @@ export type QtiSharedVocabularyField =
       values?: readonly string[] | undefined;
       valueType?: QtiSharedVocabularyAttributeValueType | undefined;
       numberMinimum?: number | undefined;
+      numberExclusiveMinimum?: number | undefined;
     };
 
 const choiceAndOrder = SHARED_VOCABULARY_CHOICE_AND_ORDER_INTERACTIONS;
@@ -145,6 +152,20 @@ export const sharedVocabularyInteractionFields: readonly QtiSharedVocabularyFiel
     className: "qti-gap-placement",
     interactions: ["gapMatch"],
   },
+  {
+    kind: "attribute",
+    id: "choices-container-width",
+    attributeName: "data-choices-container-width",
+    valueType: "number",
+    numberExclusiveMinimum: 0,
+    interactions: choicesLayoutInteractions,
+  },
+  {
+    kind: "attribute",
+    id: "first-column-header",
+    attributeName: "data-first-column-header",
+    interactions: ["match"],
+  },
   {
     kind: "attribute",
     id: "media-player-controls",
@@ -361,8 +382,7 @@ function parseAttributeValue(
 
   if (field.valueType === "number") {
     const parsed = Number(value);
-    const minimum = field.numberMinimum ?? Number.NEGATIVE_INFINITY;
-    return Number.isFinite(parsed) && parsed >= minimum ? parsed : undefined;
+    return isValidRegistryNumber(field, parsed) ? parsed : undefined;
   }
 
   if (field.values !== undefined && !field.values.includes(value)) return undefined;
@@ -382,8 +402,7 @@ function serializeAttributeValue(
 
   if (field.valueType === "number") {
     if (typeof value !== "number") return undefined;
-    const minimum = field.numberMinimum ?? Number.NEGATIVE_INFINITY;
-    return Number.isFinite(value) && value >= minimum ? String(value) : undefined;
+    return isValidRegistryNumber(field, value) ? String(value) : undefined;
   }
 
   if (typeof value !== "string" && typeof value !== "number") return undefined;
@@ -392,6 +411,16 @@ function serializeAttributeValue(
   return serialized;
 }
 
+function isValidRegistryNumber(
+  field: Extract<QtiSharedVocabularyField, { kind: "attribute" }>,
+  value: number,
+): boolean {
+  if (!Number.isFinite(value)) return false;
+  const minimum = field.numberMinimum ?? Number.NEGATIVE_INFINITY;
+  const exclusiveMinimum = field.numberExclusiveMinimum;
+  return value >= minimum && (exclusiveMinimum === undefined || value > exclusiveMinimum);
+}
+
 function isAllowedFieldValue(
   values: readonly QtiSharedVocabularyFieldValue[],
   value: QtiSharedVocabularyStateValue,

package/src/shared-vocabulary-registry-validation.ts

@@ -3,6 +3,7 @@ import {
   formatSharedVocabularyClassValueRange,
   matchedSharedVocabularyClassNames,
   parseClassValue,
+  parseSharedVocabularyAttributes,
   sharedVocabularyFieldById,
   sharedVocabularyFieldsForInteraction,
   sharedVocabularyFixedClassName,
@@ -130,16 +131,18 @@ export function validateChoicesContainerWidthSharedVocabulary(
 ): void {
   const width = interaction.attributes["data-choices-container-width"];
   if (width === undefined) return;
-  const parsed = Number(width);
-  if (!Number.isFinite(parsed) || parsed <= 0) {
-    diagnostics.push({
-      code: "interaction.sharedVocabulary.orderChoicesContainerWidth",
-      severity: "warning",
-      message: `${interaction.qtiName} data-choices-container-width must be a positive pixel value; the invalid value is ignored at runtime.`,
-      path: interaction.source?.path,
-      source: interaction.source,
-    });
-  }
+  const parsed = parseSharedVocabularyAttributes(
+    { "data-choices-container-width": width },
+    interaction.type,
+  )["choices-container-width"];
+  if (parsed !== undefined) return;
+  diagnostics.push({
+    code: "interaction.sharedVocabulary.orderChoicesContainerWidth",
+    severity: "warning",
+    message: `${interaction.qtiName} data-choices-container-width must be a positive pixel value; the invalid value is ignored at runtime.`,
+    path: interaction.source?.path,
+    source: interaction.source,
+  });
 }
 
 export function validateMatchInteractionSharedVocabulary(

package/src/shared-vocabulary-support.ts

@@ -163,6 +163,78 @@ function registryClassFixedSupportEntries(): SharedVocabularyClassSupport[] {
   });
 }
 
+function registryAttributeSupportProfile(fieldId: string): {
+  fixtures: string[];
+  tests: string[];
+  notes?: string;
+} {
+  switch (fieldId) {
+    case "choices-container-width":
+      return {
+        fixtures: sharedVocabularyFixture,
+        tests: [
+          "packages/core/src/core.test.ts",
+          "packages/player/src/interactions/shared-vocabulary.test.ts",
+          ...browserBehaviorTests,
+          ...graphicBrowserTests,
+        ],
+        notes:
+          "Sets the authored choices-bank width for interactions that support qti-choices-* layout classes.",
+      };
+    case "first-column-header":
+      return {
+        fixtures: sharedVocabularyFixture,
+        tests: [
+          "packages/core/src/core.test.ts",
+          ...browserBehaviorTests,
+          "tests/browser/player-keyboard-a11y.spec.ts",
+        ],
+        notes: "Provides the top-left header text for qti-match-tabular table rendering.",
+      };
+    case "media-player-controls":
+      return {
+        fixtures: [mediaPlayerFixture],
+        tests: [...mediaBrowserTests, "packages/core/src/shared-vocabulary-validation.test.ts"],
+        notes:
+          "Supports tokens none, default, play, rewind, captions, and audioDescription on media interactions and rendered media assets.",
+      };
+    case "media-player-pause-delay":
+      return {
+        fixtures: [mediaPlayerFixture],
+        tests: mediaBrowserTests,
+        notes:
+          "Reflects authored pause-delay values on rendered media assets. Pause timer behavior is covered in tests/browser/player.spec.ts.",
+      };
+    case "media-player-pause-duration":
+      return {
+        fixtures: [mediaPlayerFixture],
+        tests: mediaBrowserTests,
+        notes:
+          "Reflects authored pause-duration values on rendered media assets. Pause timer behavior is covered in tests/browser/player.spec.ts.",
+      };
+    default:
+      return {
+        fixtures: sharedVocabularyFixture,
+        tests: [...sharedVocabularyUnitTests, ...browserBehaviorTests],
+      };
+  }
+}
+
+function registryAttributeSupportEntries(): SharedVocabularyClassSupport[] {
+  return sharedVocabularyInteractionFields.flatMap((field) => {
+    if (field.kind !== "attribute") return [];
+    const profile = registryAttributeSupportProfile(field.id);
+    return [
+      svEntry(field.attributeName, "interaction", "full", {
+        interactions: [...field.interactions],
+        fixtures: profile.fixtures,
+        tests: profile.tests,
+        ...(profile.notes === undefined ? {} : { notes: profile.notes }),
+      }),
+    ];
+  });
+}
+
 function svEntry(
   className: string,
   scope: SharedVocabularyClassSupport["scope"],
@@ -213,19 +285,6 @@ function interactionStylesheetEntry(
   });
 }
 
-function mediaPlayerSvEntry(
-  className: string,
-  notes: string,
-  tests: string[] = mediaBrowserTests,
-): SharedVocabularyClassSupport {
-  return svEntry(className, "interaction", "full", {
-    interactions: ["media"],
-    fixtures: [mediaPlayerFixture],
-    tests,
-    notes,
-  });
-}
-
 export const sharedVocabularyClassSupport: SharedVocabularyClassSupport[] = [
   contentStylesheetEntry(
     "qti-layout-row",
@@ -285,6 +344,7 @@ export const sharedVocabularyClassSupport: SharedVocabularyClassSupport[] = [
 
   ...registryClassValueSupportEntries(),
   ...registryClassFixedSupportEntries(),
+  ...registryAttributeSupportEntries(),
   svEntry("data-min-selections-message", "interaction", "full", {
     interactions: ["order"],
     fixtures: [orderMinMaxMessagesFixture],
@@ -353,17 +413,4 @@ export const sharedVocabularyClassSupport: SharedVocabularyClassSupport[] = [
       ],
     ),
   ),
-  mediaPlayerSvEntry(
-    "data-qti-media-player-controls",
-    "Supports tokens none, default, play, rewind, captions, and audioDescription on media interactions and rendered media assets.",
-    [...mediaBrowserTests, "packages/core/src/shared-vocabulary-validation.test.ts"],
-  ),
-  mediaPlayerSvEntry(
-    "data-qti-media-player-pause-delay",
-    "Reflects authored pause-delay values on rendered media assets. Pause timer behavior is covered in tests/browser/player.spec.ts.",
-  ),
-  mediaPlayerSvEntry(
-    "data-qti-media-player-pause-duration",
-    "Reflects authored pause-duration values on rendered media assets. Pause timer behavior is covered in tests/browser/player.spec.ts.",
-  ),
 ];

package/src/support.ts

@@ -255,7 +255,7 @@ export const itemMetadataSupport: QtiItemMetadataElementSupport[] = [
       "packages/core/src/parser-item-metadata.test.ts",
     ],
     notes:
-      "Parses qti-physical-material text only. qti-digital-material is preserved in unparsedChildren and emits companionMaterials.child.unsupported at parse time.",
+      "Parses qti-physical-material text and qti-digital-material file references. Digital materials require non-empty qti-file-href text and may include label, mime-type, and qti-resource-icon metadata. Hosts read resolved materials through createCompanionMaterialsResolution() or player.getCompanionMaterialsResolution().",
   },
   {
     qtiName: "qti-physical-material",
@@ -277,10 +277,10 @@ export const itemMetadataSupport: QtiItemMetadataElementSupport[] = [
   {
     qtiName: "qti-digital-material",
     category: "itemMetadata",
-    support: "unsupported",
+    support: "parsed",
     specReference: "QTI 3.0.1 ASI",
-    parse: false,
-    validate: false,
+    parse: true,
+    validate: true,
     render: false,
     process: false,
     fixtures: [
@@ -291,7 +291,7 @@ export const itemMetadataSupport: QtiItemMetadataElementSupport[] = [
       "packages/core/src/parser-item-metadata.test.ts",
     ],
     notes:
-      "Recognized as an unparsed child of qti-companion-materials-info. Full digital material parsing is not implemented yet.",
+      "Child of qti-companion-materials-info. Parsed from qti-file-href with optional label, mime-type, and qti-resource-icon metadata. Element attributes are preserved on the parsed model. Missing or empty qti-file-href emits companionMaterials.digitalMaterial.fileHref.* diagnostics.",
   },
 ];
 

package/src/types.ts

@@ -456,6 +456,7 @@ export interface QtiAssessmentItem {
 
 export interface QtiCompanionMaterialsInfo {
   physicalMaterials: QtiPhysicalMaterial[];
+  digitalMaterials: QtiDigitalMaterial[];
   unparsedChildren: QtiCompanionMaterialsUnparsedChild[];
   source?: QtiSourceLocation | undefined;
 }
@@ -470,6 +471,13 @@ export interface QtiPhysicalMaterial {
   source?: QtiSourceLocation | undefined;
 }
 
+export interface QtiDigitalMaterial {
+  fileHref: string;
+  resourceIcon?: string | undefined;
+  attributes: Record<string, string>;
+  source?: QtiSourceLocation | undefined;
+}
+
 export interface QtiModalFeedback {
   identifier: string;
   outcomeIdentifier: string;

package/src/validation-companion-materials.ts

@@ -0,0 +1,48 @@
+import type { QtiAssessmentItem, QtiDiagnostic } from "./types.js";
+import { PARSED_COMPANION_MATERIAL_CHILD_NAMES } from "./companion-materials.js";
+
+export function validateCompanionMaterials(
+  item: QtiAssessmentItem,
+  diagnostics: QtiDiagnostic[],
+): void {
+  const companionMaterials = item.companionMaterials;
+  if (!companionMaterials) return;
+
+  for (const child of companionMaterials.unparsedChildren) {
+    if (!PARSED_COMPANION_MATERIAL_CHILD_NAMES.has(child.qtiName)) continue;
+
+    diagnostics.push({
+      code: "companionMaterials.model.inconsistent",
+      severity: "error",
+      message: `${child.qtiName} must be represented in the parsed companion materials model, not as an unparsed child.`,
+      path: child.source?.path,
+      source: child.source,
+    });
+  }
+
+  for (const material of companionMaterials.physicalMaterials) {
+    if (material.text.trim().length === 0) {
+      diagnostics.push({
+        code: "companionMaterials.physicalMaterial.empty.model",
+        severity: "error",
+        message:
+          "qti-physical-material requires non-empty text content in the parsed companion materials model.",
+        path: material.source?.path,
+        source: material.source,
+      });
+    }
+  }
+
+  for (const material of companionMaterials.digitalMaterials) {
+    if (material.fileHref.trim().length === 0) {
+      diagnostics.push({
+        code: "companionMaterials.digitalMaterial.fileHref.empty.model",
+        severity: "error",
+        message:
+          "qti-digital-material requires non-empty qti-file-href text content in the parsed companion materials model.",
+        path: material.source?.path,
+        source: material.source,
+      });
+    }
+  }
+}

package/src/validation.ts

@@ -25,6 +25,7 @@ import { validateInteractionSharedVocabulary } from "./shared-vocabulary-interac
 import { isValidQtiPatternMask } from "./pattern-mask.js";
 import { validateQtiDataSsmlMetadata } from "./tts.js";
 import { qtiValueToStringList } from "./value-format.js";
+import { validateCompanionMaterials } from "./validation-companion-materials.js";
 
 const BUILT_IN_COMPLETION_STATUS = "completionStatus";
 
@@ -713,37 +714,6 @@ function validateOutcomeLookupTables(item: QtiAssessmentItem, diagnostics: QtiDi
   }
 }
 
-function validateCompanionMaterials(item: QtiAssessmentItem, diagnostics: QtiDiagnostic[]): void {
-  const companionMaterials = item.companionMaterials;
-  if (!companionMaterials) return;
-
-  for (const child of companionMaterials.unparsedChildren) {
-    if (child.qtiName === "qti-physical-material") {
-      diagnostics.push({
-        code: "companionMaterials.model.inconsistent",
-        severity: "error",
-        message:
-          "Empty qti-physical-material must be represented as a parse warning, not an unparsed child.",
-        path: child.source?.path,
-        source: child.source,
-      });
-    }
-  }
-
-  for (const material of companionMaterials.physicalMaterials) {
-    if (material.text.trim().length === 0) {
-      diagnostics.push({
-        code: "companionMaterials.physicalMaterial.empty.model",
-        severity: "error",
-        message:
-          "qti-physical-material requires non-empty text content in the parsed companion materials model.",
-        path: material.source?.path,
-        source: material.source,
-      });
-    }
-  }
-}
-
 function validateStylesheets(item: QtiAssessmentItem, diagnostics: QtiDiagnostic[]): void {
   for (const stylesheet of item.stylesheets) {
     if (stylesheet.href.trim().length > 0) continue;