@longsightgroup/qti3-core 0.7.2 → 0.8.0

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

@@ -0,0 +1,207 @@
+import {
+  describeSharedVocabularyPrecedence,
+  formatSharedVocabularyClassValueRange,
+  matchedSharedVocabularyClassNames,
+  parseClassValue,
+  sharedVocabularyFieldById,
+  sharedVocabularyFieldsForInteraction,
+  sharedVocabularyFixedClassName,
+  type QtiSharedVocabularyField,
+} from "./shared-vocabulary-authoring.js";
+import type { QtiDiagnostic, QtiInteraction } from "./types.js";
+
+const LEGACY_CLASS_VALUE_CONFLICT_CODES: Record<string, string> = {
+  "labels-style": "interaction.sharedVocabulary.labelsConflict",
+  "labels-suffix": "interaction.sharedVocabulary.labelSuffixConflict",
+  orientation: "interaction.sharedVocabulary.orientationConflict",
+  "choices-stacking": "interaction.sharedVocabulary.stackingConflict",
+  "choices-position": "interaction.sharedVocabulary.orderChoicesPositionConflict",
+};
+
+const LEGACY_CLASS_VALUE_INVALID_CODES: Record<string, string> = {
+  "choices-stacking": "interaction.sharedVocabulary.stackingInvalid",
+};
+
+export function validateRegistrySharedVocabularyClasses(
+  interaction: QtiInteraction,
+  classNames: string[],
+  diagnostics: QtiDiagnostic[],
+): void {
+  for (const field of sharedVocabularyFieldsForInteraction(interaction.type)) {
+    if (field.kind !== "class-value") continue;
+    validateClassValueFieldConflicts(interaction, field, classNames, diagnostics);
+    validateUnsupportedClassValueClasses(interaction, field, classNames, diagnostics);
+  }
+}
+
+function validateClassValueFieldConflicts(
+  interaction: QtiInteraction,
+  field: Extract<QtiSharedVocabularyField, { kind: "class-value" }>,
+  classNames: string[],
+  diagnostics: QtiDiagnostic[],
+): void {
+  const matched = matchedSharedVocabularyClassNames(field, classNames);
+  if (new Set(matched).size <= 1) return;
+
+  diagnostics.push({
+    code: classValueConflictCode(field.id),
+    severity: "warning",
+    message: conflictMessage(interaction, field, matched),
+    path: interaction.source?.path,
+    source: interaction.source,
+  });
+}
+
+function classValueConflictCode(fieldId: string): string {
+  return (
+    LEGACY_CLASS_VALUE_CONFLICT_CODES[fieldId] ??
+    `interaction.sharedVocabulary.${fieldIdToDiagnosticSuffix(fieldId)}Conflict`
+  );
+}
+
+function classValueInvalidCode(fieldId: string): string {
+  return (
+    LEGACY_CLASS_VALUE_INVALID_CODES[fieldId] ??
+    `interaction.sharedVocabulary.${fieldIdToDiagnosticSuffix(fieldId)}Invalid`
+  );
+}
+
+function fieldIdToDiagnosticSuffix(fieldId: string): string {
+  return fieldId.replace(/-([a-z])/g, (_, letter: string) => letter.toUpperCase());
+}
+
+function conflictMessage(
+  interaction: QtiInteraction,
+  field: Extract<QtiSharedVocabularyField, { kind: "class-value" }>,
+  matchedClassNames: string[],
+): string {
+  const uniqueMatched = [...new Set(matchedClassNames)];
+  const precedence = describeSharedVocabularyPrecedence(field, uniqueMatched);
+
+  switch (field.id) {
+    case "labels-style":
+      return `${interaction.qtiName} should not include multiple qti-labels-* style classes: ${uniqueMatched.join(", ")}. ${precedence} at runtime.`;
+    case "labels-suffix":
+      return `${interaction.qtiName} should not include multiple qti-labels-suffix-* classes: ${uniqueMatched.join(", ")}. ${precedence} at runtime.`;
+    case "orientation":
+      return `${interaction.qtiName} should not include both qti-orientation-horizontal and qti-orientation-vertical; ${precedence} at runtime.`;
+    case "choices-stacking":
+      return `qti-choice-interaction should not include multiple qti-choices-stacking-* classes: ${uniqueMatched.join(", ")}. The first valid stacking class in class attribute order takes precedence at runtime.`;
+    case "choices-position":
+      return `${interaction.qtiName} should not include multiple qti-choices-* position classes: ${uniqueMatched.join(", ")}. The first position class in class attribute order takes precedence at runtime.`;
+    default:
+      return `${interaction.qtiName} should not include multiple ${field.classPrefix}* classes: ${uniqueMatched.join(", ")}. ${precedence} at runtime.`;
+  }
+}
+
+function validateUnsupportedClassValueClasses(
+  interaction: QtiInteraction,
+  field: Extract<QtiSharedVocabularyField, { kind: "class-value" }>,
+  classNames: string[],
+  diagnostics: QtiDiagnostic[],
+): void {
+  for (const className of classNames) {
+    if (!className.startsWith(field.classPrefix)) continue;
+    if (parseClassValue(field, className) !== undefined) continue;
+    diagnostics.push({
+      code: classValueInvalidCode(field.id),
+      severity: "warning",
+      message: unsupportedClassValueMessage(interaction, field, className),
+      path: interaction.source?.path,
+      source: interaction.source,
+    });
+  }
+}
+
+function unsupportedClassValueMessage(
+  interaction: QtiInteraction,
+  field: Extract<QtiSharedVocabularyField, { kind: "class-value" }>,
+  className: string,
+): string {
+  if (field.id === "choices-stacking") {
+    return `qti-choice-interaction shared vocabulary class ${className} is not supported; expected ${formatSharedVocabularyClassValueRange(field)}.`;
+  }
+  return `${interaction.qtiName} shared vocabulary class ${className} is not supported; expected ${formatSharedVocabularyClassValueRange(field)}.`;
+}
+
+export function validateChoicesContainerWidthSharedVocabulary(
+  interaction: QtiInteraction,
+  diagnostics: QtiDiagnostic[],
+): 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,
+    });
+  }
+}
+
+export function validateMatchInteractionSharedVocabulary(
+  interaction: QtiInteraction,
+  classNames: string[],
+  diagnostics: QtiDiagnostic[],
+): void {
+  const matchTabularClass = sharedVocabularyFixedClassName("match-tabular");
+  const headerHiddenClass = sharedVocabularyFixedClassName("header-hidden");
+  const hasTabular =
+    matchTabularClass === undefined ? false : classNames.includes(matchTabularClass);
+  const hasHeaderHidden =
+    headerHiddenClass === undefined ? false : classNames.includes(headerHiddenClass);
+  const firstColumnHeader = interaction.attributes["data-first-column-header"];
+  if (!hasTabular && (hasHeaderHidden || firstColumnHeader !== undefined)) {
+    diagnostics.push({
+      code: "interaction.sharedVocabulary.matchTabularContext",
+      severity: "warning",
+      message:
+        "qti-match-interaction shared vocabulary class qti-header-hidden and data-first-column-header are only relevant when qti-match-tabular is specified; they are ignored at runtime.",
+      path: interaction.source?.path,
+      source: interaction.source,
+    });
+  }
+  if (hasTabular && hasHeaderHidden && firstColumnHeader !== undefined) {
+    diagnostics.push({
+      code: "interaction.sharedVocabulary.matchTabularHeaderHidden",
+      severity: "warning",
+      message:
+        "qti-match-interaction data-first-column-header is ignored when qti-header-hidden suppresses the tabular header row.",
+      path: interaction.source?.path,
+      source: interaction.source,
+    });
+  }
+  if (!hasTabular) return;
+
+  const choicesPositionField = sharedVocabularyFieldById("choices-position");
+  const choicesPositionClasses =
+    choicesPositionField?.kind === "class-value"
+      ? matchedSharedVocabularyClassNames(choicesPositionField, classNames)
+      : [];
+  if (
+    choicesPositionClasses.length > 0 ||
+    interaction.attributes["data-choices-container-width"] !== undefined
+  ) {
+    diagnostics.push({
+      code: "interaction.sharedVocabulary.matchTabularChoicesConflict",
+      severity: "warning",
+      message:
+        "qti-match-interaction qti-match-tabular uses a matrix layout; qti-choices-* position classes and data-choices-container-width are ignored at runtime.",
+      path: interaction.source?.path,
+      source: interaction.source,
+    });
+  }
+  if (!hasHeaderHidden && (firstColumnHeader === undefined || firstColumnHeader === "")) {
+    diagnostics.push({
+      code: "interaction.sharedVocabulary.matchTabularFirstColumnHeader",
+      severity: "warning",
+      message:
+        "qti-match-interaction with qti-match-tabular should specify data-first-column-header for the top-left table header when the tabular header row is shown.",
+      path: interaction.source?.path,
+      source: interaction.source,
+    });
+  }
+}

package/src/shared-vocabulary-support.ts

@@ -1,5 +1,4 @@
 import {
-  SHARED_VOCABULARY_CHOICE_WRITING_ORIENTATIONS,
   SHARED_VOCABULARY_CONTENT_ALIGNMENTS,
   SHARED_VOCABULARY_CONTENT_FLOAT_SUFFIXES,
   SHARED_VOCABULARY_CONTENT_LIST_STYLE_TYPES,
@@ -9,11 +8,17 @@ import {
   SHARED_VOCABULARY_LAYOUT_COLUMN_SPAN_COUNT,
   SHARED_VOCABULARY_LAYOUT_OFFSET_COUNT,
 } from "./shared-vocabulary-generated-families.js";
+import {
+  sharedVocabularyFixedClassName,
+  sharedVocabularyInteractionFields,
+  type QtiSharedVocabularyField,
+} from "./shared-vocabulary-authoring.js";
 import {
   SHARED_VOCABULARY_EXTENDED_TEXT_COUNTER_CLASSES,
   SHARED_VOCABULARY_EXTENDED_TEXT_HEIGHT_LINES,
   SHARED_VOCABULARY_INPUT_WIDTHS,
 } from "./shared-vocabulary.js";
+import { SHARED_VOCABULARY_CHOICE_AND_ORDER_INTERACTIONS } from "./shared-vocabulary-interaction-sets.js";
 import type { QtiInteractionType, SharedVocabularyClassSupport } from "./types.js";
 
 const sharedVocabularyFixture = [
@@ -34,7 +39,10 @@ const sharedVocabularyUnitTests = [
 const sharedVocabularyValidationTests = [
   "packages/core/src/core.test.ts",
   "packages/core/src/shared-vocabulary-validation.test.ts",
+  "packages/core/src/shared-vocabulary-registry-validation.test.ts",
+  "packages/core/src/shared-vocabulary-interaction-validation.test.ts",
 ];
+const choiceLayoutTests = ["packages/player/src/interactions/choice-layout.test.ts"];
 const browserBehaviorTests = [
   "tests/browser/player-dom-behavior.spec.ts",
   ...sharedVocabularyMatrixTests,
@@ -53,19 +61,107 @@ const interactionInputWidthFixtures = [
 const orderMinMaxMessagesFixture =
   "packages/fixtures/packages/sv-matrix/items/order-min-max-messages.xml";
 
-const choiceAndOrder: QtiInteractionType[] = ["choice", "order"];
-const choicesLayoutInteractions: QtiInteractionType[] = [
-  "match",
-  "gapMatch",
-  "graphicGapMatch",
-  "order",
-];
-const selectionPresentationInteractions: QtiInteractionType[] = [
-  "choice",
-  "hottext",
-  "hotspot",
-  "graphicGapMatch",
-];
+const choiceAndOrder = SHARED_VOCABULARY_CHOICE_AND_ORDER_INTERACTIONS;
+
+function registryClassValueSupportProfile(fieldId: string): {
+  level: "full" | "stylesheet";
+  tests: string[];
+} {
+  switch (fieldId) {
+    case "labels-style":
+    case "labels-suffix":
+      return { level: "full", tests: [...sharedVocabularyUnitTests, ...browserBehaviorTests] };
+    case "orientation":
+      return {
+        level: "full",
+        tests: [...choiceLayoutTests, ...sharedVocabularyUnitTests, ...browserBehaviorTests],
+      };
+    case "choices-stacking":
+      return {
+        level: "full",
+        tests: [...choiceLayoutTests, "packages/core/src/core.test.ts", ...browserBehaviorTests],
+      };
+    case "choices-position":
+      return {
+        level: "full",
+        tests: [...sharedVocabularyUnitTests, ...browserBehaviorTests, ...graphicBrowserTests],
+      };
+    case "selections-tone":
+      return { level: "stylesheet", tests: [...browserBehaviorTests, ...graphicBrowserTests] };
+    case "writing-orientation":
+      return { level: "stylesheet", tests: [...browserBehaviorTests] };
+    default:
+      return { level: "full", tests: [...sharedVocabularyUnitTests, ...browserBehaviorTests] };
+  }
+}
+
+function registryClassValueSupportEntries(): SharedVocabularyClassSupport[] {
+  return sharedVocabularyInteractionFields.flatMap((field) => {
+    if (field.kind !== "class-value") return [];
+    const profile = registryClassValueSupportProfile(field.id);
+    const createEntry =
+      profile.level === "stylesheet" ? interactionStylesheetEntry : interactionFullEntry;
+    return field.values.map((value) =>
+      createEntry(`${field.classPrefix}${String(value)}`, field.interactions, profile.tests),
+    );
+  });
+}
+
+function registryClassFixedSupportProfile(fieldId: string): {
+  level: "full" | "stylesheet";
+  tests: string[];
+} {
+  switch (fieldId) {
+    case "input-control-hidden":
+      return {
+        level: "stylesheet",
+        tests: [...browserBehaviorTests, "tests/browser/player-keyboard-a11y.spec.ts"],
+      };
+    case "unselected-hidden":
+      return { level: "stylesheet", tests: [...browserBehaviorTests, ...graphicBrowserTests] };
+    case "match-tabular":
+      return {
+        level: "full",
+        tests: [
+          "packages/core/src/core.test.ts",
+          ...browserBehaviorTests,
+          "tests/browser/player-keyboard-a11y.spec.ts",
+        ],
+      };
+    case "gap-placement":
+      return {
+        level: "full",
+        tests: [
+          ...sharedVocabularyUnitTests,
+          "packages/core/src/core.test.ts",
+          ...browserBehaviorTests,
+        ],
+      };
+    default:
+      return { level: "full", tests: [...browserBehaviorTests] };
+  }
+}
+
+const registryClassFixedSupportIds = [
+  "input-control-hidden",
+  "unselected-hidden",
+  "match-tabular",
+  "gap-placement",
+] as const;
+
+function registryClassFixedSupportEntries(): SharedVocabularyClassSupport[] {
+  return registryClassFixedSupportIds.flatMap((fieldId) => {
+    const field = sharedVocabularyInteractionFields.find(
+      (candidate): candidate is Extract<QtiSharedVocabularyField, { kind: "class-fixed" }> =>
+        candidate.kind === "class-fixed" && candidate.id === fieldId,
+    );
+    if (field === undefined) return [];
+    const profile = registryClassFixedSupportProfile(field.id);
+    const createEntry =
+      profile.level === "stylesheet" ? interactionStylesheetEntry : interactionFullEntry;
+    return [createEntry(field.className, field.interactions, profile.tests)];
+  });
+}
 
 function svEntry(
   className: string,
@@ -91,12 +187,12 @@ function contentStylesheetEntry(className: string, notes?: string): SharedVocabu
 
 function interactionFullEntry(
   className: string,
-  interactions: QtiInteractionType[],
+  interactions: readonly QtiInteractionType[],
   tests: string[],
   notes?: string,
 ): SharedVocabularyClassSupport {
   return svEntry(className, "interaction", "full", {
-    interactions,
+    interactions: [...interactions],
     fixtures: sharedVocabularyFixture,
     tests,
     notes,
@@ -105,12 +201,12 @@ function interactionFullEntry(
 
 function interactionStylesheetEntry(
   className: string,
-  interactions: QtiInteractionType[],
+  interactions: readonly QtiInteractionType[],
   tests: string[],
   notes?: string,
 ): SharedVocabularyClassSupport {
   return svEntry(className, "interaction", "stylesheet", {
-    interactions,
+    interactions: [...interactions],
     fixtures: sharedVocabularyFixture,
     tests,
     notes,
@@ -187,69 +283,8 @@ export const sharedVocabularyClassSupport: SharedVocabularyClassSupport[] = [
   contentStylesheetEntry("qti-italic"),
   contentStylesheetEntry("qti-display-inline-block"),
 
-  ...["none", "decimal", "cjk-ideographic", "lower-alpha", "upper-alpha"].map((labelStyle) =>
-    interactionFullEntry(`qti-labels-${labelStyle}`, choiceAndOrder, [
-      ...sharedVocabularyUnitTests,
-      ...browserBehaviorTests,
-    ]),
-  ),
-  ...["none", "period", "parenthesis"].map((suffix) =>
-    interactionFullEntry(`qti-labels-suffix-${suffix}`, choiceAndOrder, [
-      ...sharedVocabularyUnitTests,
-      ...browserBehaviorTests,
-    ]),
-  ),
-  ...["horizontal", "vertical"].map((orientation) =>
-    interactionFullEntry(
-      `qti-orientation-${orientation}`,
-      ["choice", "order"],
-      [
-        "packages/player/src/interactions/choice-layout.test.ts",
-        ...sharedVocabularyUnitTests,
-        ...browserBehaviorTests,
-      ],
-    ),
-  ),
-  ...Array.from({ length: 5 }, (_, index) => index + 1).map((stacking) =>
-    interactionFullEntry(
-      `qti-choices-stacking-${stacking}`,
-      ["choice"],
-      [
-        "packages/player/src/interactions/choice-layout.test.ts",
-        "packages/core/src/core.test.ts",
-        ...browserBehaviorTests,
-      ],
-    ),
-  ),
-  interactionStylesheetEntry(
-    "qti-input-control-hidden",
-    ["choice", "hottext"],
-    [...browserBehaviorTests, "tests/browser/player-keyboard-a11y.spec.ts"],
-  ),
-  ...SHARED_VOCABULARY_CHOICE_WRITING_ORIENTATIONS.map((orientation) =>
-    interactionStylesheetEntry(
-      `qti-writing-orientation-${orientation}`,
-      ["choice", "inlineChoice"],
-      [...browserBehaviorTests],
-    ),
-  ),
-  ...["light", "dark"].map((tone) =>
-    interactionStylesheetEntry(`qti-selections-${tone}`, selectionPresentationInteractions, [
-      ...browserBehaviorTests,
-      ...graphicBrowserTests,
-    ]),
-  ),
-  interactionStylesheetEntry("qti-unselected-hidden", selectionPresentationInteractions, [
-    ...browserBehaviorTests,
-    ...graphicBrowserTests,
-  ]),
-  ...["top", "bottom", "left", "right"].map((position) =>
-    interactionFullEntry(`qti-choices-${position}`, choicesLayoutInteractions, [
-      ...sharedVocabularyUnitTests,
-      ...browserBehaviorTests,
-      ...graphicBrowserTests,
-    ]),
-  ),
+  ...registryClassValueSupportEntries(),
+  ...registryClassFixedSupportEntries(),
   svEntry("data-min-selections-message", "interaction", "full", {
     interactions: ["order"],
     fixtures: [orderMinMaxMessagesFixture],
@@ -257,30 +292,21 @@ export const sharedVocabularyClassSupport: SharedVocabularyClassSupport[] = [
     notes: "Overrides minimum response validation text for order interactions.",
   }),
   svEntry("data-max-selections-message", "interaction", "full", {
-    interactions: ["choice", "order"],
+    interactions: [...choiceAndOrder],
     fixtures: [orderMinMaxMessagesFixture],
     tests: ["tests/browser/player-validation.spec.ts", ...sharedVocabularyMatrixTests],
     notes: "Overrides maximum response validation text for choice and order interactions.",
   }),
-  interactionFullEntry(
-    "qti-match-tabular",
-    ["match"],
-    [
-      "packages/core/src/core.test.ts",
-      ...browserBehaviorTests,
-      "tests/browser/player-keyboard-a11y.spec.ts",
-    ],
-  ),
-  svEntry("qti-header-hidden", "interaction", "conditional", {
-    interactions: ["match"],
-    fixtures: sharedVocabularyFixture,
-    tests: ["packages/core/src/core.test.ts", ...browserBehaviorTests],
-    notes: "Applied when qti-match-tabular selects the tabular match renderer.",
-  }),
-  interactionFullEntry(
-    "qti-gap-placement",
-    ["gapMatch"],
-    [...sharedVocabularyUnitTests, "packages/core/src/core.test.ts", ...browserBehaviorTests],
+  svEntry(
+    sharedVocabularyFixedClassName("header-hidden") ?? "qti-header-hidden",
+    "interaction",
+    "conditional",
+    {
+      interactions: ["match"],
+      fixtures: sharedVocabularyFixture,
+      tests: ["packages/core/src/core.test.ts", ...browserBehaviorTests],
+      notes: "Applied when qti-match-tabular selects the tabular match renderer.",
+    },
   ),
   ...SHARED_VOCABULARY_INPUT_WIDTHS.map((width) =>
     svEntry(`qti-input-width-${width}`, "interaction", "full", {

package/src/shared-vocabulary.ts

@@ -7,6 +7,24 @@ export const SHARED_VOCABULARY_INPUT_WIDTHS = [
 
 export const SHARED_VOCABULARY_GAP_INPUT_WIDTHS = SHARED_VOCABULARY_INPUT_WIDTHS;
 
+export const SHARED_VOCABULARY_LABEL_STYLES = [
+  "none",
+  "decimal",
+  "cjk-ideographic",
+  "lower-alpha",
+  "upper-alpha",
+] as const;
+
+export const SHARED_VOCABULARY_LABEL_SUFFIXES = ["none", "period", "parenthesis"] as const;
+
+export const SHARED_VOCABULARY_ORIENTATIONS = ["horizontal", "vertical"] as const;
+
+export const SHARED_VOCABULARY_CHOICES_STACKING = [1, 2, 3, 4, 5] as const;
+
+export const SHARED_VOCABULARY_CHOICES_POSITIONS = ["top", "bottom", "left", "right"] as const;
+
+export const SHARED_VOCABULARY_SELECTION_TONES = ["light", "dark"] as const;
+
 /** Normative QTI 3 shared vocabulary extended text height token values (1EdTech vocab). */
 export const SHARED_VOCABULARY_EXTENDED_TEXT_HEIGHT_LINES = [3, 6, 15] as const;