@longsightgroup/qti3-core 0.7.2 → 0.8.0

package/src/shared-vocabulary-authoring.ts

@@ -0,0 +1,409 @@
+import { SHARED_VOCABULARY_CHOICE_WRITING_ORIENTATIONS } from "./shared-vocabulary-generated-families.js";
+import {
+  SHARED_VOCABULARY_CHOICE_AND_ORDER_INTERACTIONS,
+  SHARED_VOCABULARY_CHOICES_LAYOUT_INTERACTIONS,
+  SHARED_VOCABULARY_MEDIA_INTERACTIONS,
+  SHARED_VOCABULARY_SELECTION_PRESENTATION_INTERACTIONS,
+} from "./shared-vocabulary-interaction-sets.js";
+import {
+  SHARED_VOCABULARY_CHOICES_POSITIONS,
+  SHARED_VOCABULARY_CHOICES_STACKING,
+  SHARED_VOCABULARY_LABEL_STYLES,
+  SHARED_VOCABULARY_LABEL_SUFFIXES,
+  SHARED_VOCABULARY_MEDIA_PLAYER_CONTROLS,
+  SHARED_VOCABULARY_ORIENTATIONS,
+  SHARED_VOCABULARY_SELECTION_TONES,
+} from "./shared-vocabulary.js";
+import type { QtiInteractionType } from "./types.js";
+
+export type QtiSharedVocabularyFieldValue = string | number;
+
+export type QtiSharedVocabularyStateValue =
+  | QtiSharedVocabularyFieldValue
+  | boolean
+  | readonly string[]
+  | undefined;
+
+export type QtiSharedVocabularyState = Record<string, QtiSharedVocabularyStateValue>;
+
+export type QtiSharedVocabularyAttributeValueType = "string" | "number" | "token-list";
+
+export type QtiSharedVocabularyField =
+  | {
+      kind: "class-value";
+      id: string;
+      classPrefix: string;
+      values: readonly QtiSharedVocabularyFieldValue[];
+      interactions: readonly QtiInteractionType[];
+      precedence: "value-order" | "class-order";
+    }
+  | {
+      kind: "class-fixed";
+      id: string;
+      className: string;
+      interactions: readonly QtiInteractionType[];
+    }
+  | {
+      kind: "attribute";
+      id: string;
+      attributeName: string;
+      interactions: readonly QtiInteractionType[];
+      values?: readonly string[] | undefined;
+      valueType?: QtiSharedVocabularyAttributeValueType | undefined;
+      numberMinimum?: number | undefined;
+    };
+
+const choiceAndOrder = SHARED_VOCABULARY_CHOICE_AND_ORDER_INTERACTIONS;
+const choicesLayoutInteractions = SHARED_VOCABULARY_CHOICES_LAYOUT_INTERACTIONS;
+const selectionPresentationInteractions = SHARED_VOCABULARY_SELECTION_PRESENTATION_INTERACTIONS;
+const mediaInteraction = SHARED_VOCABULARY_MEDIA_INTERACTIONS;
+
+export const sharedVocabularyInteractionFields: readonly QtiSharedVocabularyField[] = [
+  {
+    kind: "class-value",
+    id: "labels-style",
+    classPrefix: "qti-labels-",
+    values: SHARED_VOCABULARY_LABEL_STYLES,
+    interactions: choiceAndOrder,
+    precedence: "value-order",
+  },
+  {
+    kind: "class-value",
+    id: "labels-suffix",
+    classPrefix: "qti-labels-suffix-",
+    values: SHARED_VOCABULARY_LABEL_SUFFIXES,
+    interactions: choiceAndOrder,
+    precedence: "value-order",
+  },
+  {
+    kind: "class-value",
+    id: "orientation",
+    classPrefix: "qti-orientation-",
+    values: SHARED_VOCABULARY_ORIENTATIONS,
+    interactions: choiceAndOrder,
+    precedence: "value-order",
+  },
+  {
+    kind: "class-value",
+    id: "choices-stacking",
+    classPrefix: "qti-choices-stacking-",
+    values: SHARED_VOCABULARY_CHOICES_STACKING,
+    interactions: ["choice"],
+    precedence: "class-order",
+  },
+  {
+    kind: "class-value",
+    id: "choices-position",
+    classPrefix: "qti-choices-",
+    values: SHARED_VOCABULARY_CHOICES_POSITIONS,
+    interactions: choicesLayoutInteractions,
+    precedence: "class-order",
+  },
+  {
+    kind: "class-value",
+    id: "selections-tone",
+    classPrefix: "qti-selections-",
+    values: SHARED_VOCABULARY_SELECTION_TONES,
+    interactions: selectionPresentationInteractions,
+    precedence: "value-order",
+  },
+  {
+    kind: "class-value",
+    id: "writing-orientation",
+    classPrefix: "qti-writing-orientation-",
+    values: SHARED_VOCABULARY_CHOICE_WRITING_ORIENTATIONS,
+    interactions: ["choice", "inlineChoice"],
+    precedence: "value-order",
+  },
+  {
+    kind: "class-fixed",
+    id: "input-control-hidden",
+    className: "qti-input-control-hidden",
+    interactions: ["choice", "hottext"],
+  },
+  {
+    kind: "class-fixed",
+    id: "unselected-hidden",
+    className: "qti-unselected-hidden",
+    interactions: selectionPresentationInteractions,
+  },
+  {
+    kind: "class-fixed",
+    id: "match-tabular",
+    className: "qti-match-tabular",
+    interactions: ["match"],
+  },
+  {
+    kind: "class-fixed",
+    id: "header-hidden",
+    className: "qti-header-hidden",
+    interactions: ["match"],
+  },
+  {
+    kind: "class-fixed",
+    id: "gap-placement",
+    className: "qti-gap-placement",
+    interactions: ["gapMatch"],
+  },
+  {
+    kind: "attribute",
+    id: "media-player-controls",
+    attributeName: "data-qti-media-player-controls",
+    values: SHARED_VOCABULARY_MEDIA_PLAYER_CONTROLS,
+    valueType: "token-list",
+    interactions: mediaInteraction,
+  },
+  {
+    kind: "attribute",
+    id: "media-player-pause-delay",
+    attributeName: "data-qti-media-player-pause-delay",
+    valueType: "number",
+    numberMinimum: 0,
+    interactions: mediaInteraction,
+  },
+  {
+    kind: "attribute",
+    id: "media-player-pause-duration",
+    attributeName: "data-qti-media-player-pause-duration",
+    valueType: "number",
+    numberMinimum: 0,
+    interactions: mediaInteraction,
+  },
+];
+
+export function sharedVocabularyFieldsForInteraction(
+  interaction: QtiInteractionType,
+): readonly QtiSharedVocabularyField[] {
+  return sharedVocabularyInteractionFields.filter((field) =>
+    field.interactions.includes(interaction),
+  );
+}
+
+export function sharedVocabularyFieldById(id: string): QtiSharedVocabularyField | undefined {
+  return sharedVocabularyInteractionFields.find((field) => field.id === id);
+}
+
+export function sharedVocabularyFixedClassName(fieldId: string): string | undefined {
+  const field = sharedVocabularyFieldById(fieldId);
+  return field?.kind === "class-fixed" ? field.className : undefined;
+}
+
+export function parseSharedVocabularyClasses(
+  className: string,
+  interaction?: QtiInteractionType,
+): QtiSharedVocabularyState {
+  const classNames = className.split(/\s+/).filter(Boolean);
+  const classNameSet = new Set(classNames);
+  const state: QtiSharedVocabularyState = {};
+
+  for (const field of fieldsForInteractionFilter(interaction)) {
+    if (field.kind === "attribute") continue;
+    if (field.kind === "class-fixed") {
+      if (classNameSet.has(field.className)) state[field.id] = true;
+      continue;
+    }
+
+    const value = parseClassValueField(field, classNames);
+    if (value !== undefined) state[field.id] = value;
+  }
+
+  return state;
+}
+
+export function serializeSharedVocabularyClassNames(
+  state: QtiSharedVocabularyState,
+  interaction?: QtiInteractionType,
+): string[] {
+  const classNames: string[] = [];
+
+  for (const field of fieldsForInteractionFilter(interaction)) {
+    if (field.kind === "attribute") continue;
+    const value = state[field.id];
+    if (field.kind === "class-fixed") {
+      if (value === true) classNames.push(field.className);
+      continue;
+    }
+    if (isOmittedStateValue(value)) continue;
+    if (!isAllowedFieldValue(field.values, value)) continue;
+    classNames.push(`${field.classPrefix}${String(value)}`);
+  }
+
+  return classNames;
+}
+
+export function parseSharedVocabularyAttributes(
+  attrs: Record<string, string | undefined>,
+  interaction?: QtiInteractionType,
+): QtiSharedVocabularyState {
+  const state: QtiSharedVocabularyState = {};
+
+  for (const field of fieldsForInteractionFilter(interaction)) {
+    if (field.kind !== "attribute") continue;
+    const value = attrs[field.attributeName];
+    if (value === undefined || value === "") continue;
+    const parsed = parseAttributeValue(field, value);
+    if (parsed !== undefined) state[field.id] = parsed;
+  }
+
+  return state;
+}
+
+export function serializeSharedVocabularyAttributes(
+  state: QtiSharedVocabularyState,
+  interaction?: QtiInteractionType,
+): Record<string, string> {
+  const attrs: Record<string, string> = {};
+
+  for (const field of fieldsForInteractionFilter(interaction)) {
+    if (field.kind !== "attribute") continue;
+    const value = state[field.id];
+    if (isOmittedStateValue(value)) continue;
+    const serialized = serializeAttributeValue(field, value);
+    if (serialized !== undefined) attrs[field.attributeName] = serialized;
+  }
+
+  return attrs;
+}
+
+function fieldsForInteractionFilter(
+  interaction: QtiInteractionType | undefined,
+): readonly QtiSharedVocabularyField[] {
+  return interaction === undefined
+    ? sharedVocabularyInteractionFields
+    : sharedVocabularyFieldsForInteraction(interaction);
+}
+
+export function sharedVocabularyClassNamesForField(
+  field: Extract<QtiSharedVocabularyField, { kind: "class-value" }>,
+): string[] {
+  return field.values.map((value) => `${field.classPrefix}${String(value)}`);
+}
+
+export function matchedSharedVocabularyClassNames(
+  field: Extract<QtiSharedVocabularyField, { kind: "class-value" }>,
+  classNames: readonly string[],
+): string[] {
+  const matched: string[] = [];
+  for (const className of classNames) {
+    if (parseClassValue(field, className) !== undefined) matched.push(className);
+  }
+  return matched;
+}
+
+export function describeSharedVocabularyPrecedence(
+  field: Extract<QtiSharedVocabularyField, { kind: "class-value" }>,
+  matchedClassNames: readonly string[],
+): string {
+  const matched = new Set(matchedClassNames);
+  if (field.precedence === "class-order") {
+    const ordered = matchedClassNames.filter((className) => matched.has(className));
+    if (ordered.length < 2) return `${ordered[0] ?? "The first matching class"} takes precedence`;
+    const [first, ...rest] = ordered;
+    return `${first} takes precedence over ${rest.join(", then ")}`;
+  }
+
+  const ordered = sharedVocabularyClassNamesForField(field).filter((className) =>
+    matched.has(className),
+  );
+  if (ordered.length < 2) return `${ordered[0] ?? "The first matching class"} takes precedence`;
+  const [first, ...rest] = ordered;
+  return `${first} takes precedence over ${rest.join(", then ")}`;
+}
+
+export function formatSharedVocabularyClassValueRange(
+  field: Extract<QtiSharedVocabularyField, { kind: "class-value" }>,
+): string {
+  const classNames = sharedVocabularyClassNamesForField(field);
+  if (classNames.length <= 1) return classNames[0] ?? "";
+  return `${classNames[0]} through ${classNames[classNames.length - 1]}`;
+}
+
+function parseClassValueField(
+  field: Extract<QtiSharedVocabularyField, { kind: "class-value" }>,
+  classNames: string[],
+): QtiSharedVocabularyFieldValue | undefined {
+  if (field.precedence === "class-order") {
+    for (const className of classNames) {
+      const value = parseClassValue(field, className);
+      if (value !== undefined) return value;
+    }
+    return undefined;
+  }
+
+  for (const value of field.values) {
+    const className = `${field.classPrefix}${String(value)}`;
+    if (classNames.includes(className)) return value;
+  }
+  return undefined;
+}
+
+export function parseClassValue(
+  field: Extract<QtiSharedVocabularyField, { kind: "class-value" }>,
+  className: string,
+): QtiSharedVocabularyFieldValue | undefined {
+  if (!className.startsWith(field.classPrefix)) return undefined;
+  const suffix = className.slice(field.classPrefix.length);
+  for (const value of field.values) {
+    if (String(value) === suffix) return value;
+  }
+  return undefined;
+}
+
+function parseAttributeValue(
+  field: Extract<QtiSharedVocabularyField, { kind: "attribute" }>,
+  value: string,
+): QtiSharedVocabularyStateValue {
+  if (field.valueType === "token-list") {
+    const allowed = new Set(field.values ?? []);
+    const tokens = value.split(/\s+/).filter((token) => allowed.has(token));
+    return tokens.length > 0 ? [...new Set(tokens)] : undefined;
+  }
+
+  if (field.valueType === "number") {
+    const parsed = Number(value);
+    const minimum = field.numberMinimum ?? Number.NEGATIVE_INFINITY;
+    return Number.isFinite(parsed) && parsed >= minimum ? parsed : undefined;
+  }
+
+  if (field.values !== undefined && !field.values.includes(value)) return undefined;
+  return value;
+}
+
+function serializeAttributeValue(
+  field: Extract<QtiSharedVocabularyField, { kind: "attribute" }>,
+  value: QtiSharedVocabularyStateValue,
+): string | undefined {
+  if (field.valueType === "token-list") {
+    const values = Array.isArray(value) ? value : String(value).split(/\s+/);
+    const allowed = new Set(field.values ?? []);
+    const tokens = values.filter((token): token is string => allowed.has(String(token)));
+    return tokens.length > 0 ? [...new Set(tokens)].join(" ") : undefined;
+  }
+
+  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;
+  }
+
+  if (typeof value !== "string" && typeof value !== "number") return undefined;
+  const serialized = String(value);
+  if (field.values !== undefined && !field.values.includes(serialized)) return undefined;
+  return serialized;
+}
+
+function isAllowedFieldValue(
+  values: readonly QtiSharedVocabularyFieldValue[],
+  value: QtiSharedVocabularyStateValue,
+): value is QtiSharedVocabularyFieldValue {
+  return values.some((allowed) => allowed === value);
+}
+
+function isOmittedStateValue(value: QtiSharedVocabularyStateValue): boolean {
+  return (
+    value === undefined ||
+    value === false ||
+    value === "" ||
+    (Array.isArray(value) && value.length === 0)
+  );
+}

package/src/shared-vocabulary-interaction-sets.ts

@@ -0,0 +1,28 @@
+import type { QtiInteractionType } from "./types.js";
+
+export const SHARED_VOCABULARY_CHOICE_INTERACTIONS = [
+  "choice",
+] as const satisfies readonly QtiInteractionType[];
+
+export const SHARED_VOCABULARY_CHOICE_AND_ORDER_INTERACTIONS = [
+  "choice",
+  "order",
+] as const satisfies readonly QtiInteractionType[];
+
+export const SHARED_VOCABULARY_CHOICES_LAYOUT_INTERACTIONS = [
+  "match",
+  "gapMatch",
+  "graphicGapMatch",
+  "order",
+] as const satisfies readonly QtiInteractionType[];
+
+export const SHARED_VOCABULARY_SELECTION_PRESENTATION_INTERACTIONS = [
+  "choice",
+  "hottext",
+  "hotspot",
+  "graphicGapMatch",
+] as const satisfies readonly QtiInteractionType[];
+
+export const SHARED_VOCABULARY_MEDIA_INTERACTIONS = [
+  "media",
+] as const satisfies readonly QtiInteractionType[];

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

@@ -0,0 +1,143 @@
+import {
+  validateChoicesContainerWidthSharedVocabulary,
+  validateMatchInteractionSharedVocabulary,
+  validateRegistrySharedVocabularyClasses,
+} from "./shared-vocabulary-registry-validation.js";
+import {
+  validateSharedVocabularyExtendedText,
+  validateSharedVocabularyInputWidth,
+  validateSharedVocabularyMediaPlayerControls,
+} from "./shared-vocabulary-validation.js";
+import type { QtiDiagnostic, QtiInteraction } from "./types.js";
+
+const SHARED_VOCABULARY_INTERACTION_TYPES = new Set<QtiInteraction["type"]>([
+  "choice",
+  "match",
+  "gapMatch",
+  "graphicGapMatch",
+  "inlineChoice",
+  "textEntry",
+  "extendedText",
+  "media",
+  "order",
+]);
+
+export function validateInteractionSharedVocabulary(
+  interaction: QtiInteraction,
+  diagnostics: QtiDiagnostic[],
+): void {
+  if (!SHARED_VOCABULARY_INTERACTION_TYPES.has(interaction.type)) return;
+
+  const classNames = sharedClassNames(interaction.attributes);
+  if (interaction.type === "media") {
+    validateMediaInteractionSharedVocabulary(interaction, diagnostics);
+    return;
+  }
+
+  if (interaction.type === "inlineChoice" || interaction.type === "textEntry") {
+    validateInteractionInputWidthSharedVocabulary(interaction, classNames, diagnostics);
+    return;
+  }
+
+  if (interaction.type === "extendedText") {
+    diagnostics.push(
+      ...validateSharedVocabularyExtendedText({
+        classNames,
+        subjectQtiName: interaction.qtiName,
+        expectedLength: interaction.attributes["expected-length"],
+        path: interaction.source?.path,
+        source: interaction.source,
+      }),
+    );
+    return;
+  }
+
+  if (
+    interaction.type === "match" ||
+    interaction.type === "gapMatch" ||
+    interaction.type === "graphicGapMatch"
+  ) {
+    if (interaction.type === "match") {
+      validateMatchInteractionSharedVocabulary(interaction, classNames, diagnostics);
+    }
+    validateRegistrySharedVocabularyClasses(interaction, classNames, diagnostics);
+    validateChoicesContainerWidthSharedVocabulary(interaction, diagnostics);
+    if (interaction.type === "gapMatch") {
+      validateGapInputWidthSharedVocabulary(interaction, diagnostics);
+    }
+    return;
+  }
+
+  if (interaction.type === "order") {
+    validateRegistrySharedVocabularyClasses(interaction, classNames, diagnostics);
+    validateChoicesContainerWidthSharedVocabulary(interaction, diagnostics);
+    return;
+  }
+
+  if (interaction.type === "choice") {
+    validateRegistrySharedVocabularyClasses(interaction, classNames, diagnostics);
+  }
+}
+
+function validateGapInputWidthSharedVocabulary(
+  interaction: QtiInteraction,
+  diagnostics: QtiDiagnostic[],
+): void {
+  for (const gap of interaction.choices.filter((choice) => choice.qtiName === "qti-gap")) {
+    diagnostics.push(
+      ...validateSharedVocabularyInputWidth({
+        classNames: sharedClassNames(gap.attributes),
+        subjectQtiName: "qti-gap",
+        path: gap.source?.path ?? interaction.source?.path,
+        source: gap.source ?? interaction.source,
+        conflictCode: "interaction.sharedVocabulary.gapInputWidthConflict",
+        invalidCode: "interaction.sharedVocabulary.gapInputWidthInvalid",
+      }),
+    );
+  }
+}
+
+function validateInteractionInputWidthSharedVocabulary(
+  interaction: QtiInteraction,
+  classNames: string[],
+  diagnostics: QtiDiagnostic[],
+): void {
+  diagnostics.push(
+    ...validateSharedVocabularyInputWidth({
+      classNames,
+      subjectQtiName: interaction.qtiName,
+      path: interaction.source?.path,
+      source: interaction.source,
+      conflictCode: "interaction.sharedVocabulary.inputWidthConflict",
+      invalidCode: "interaction.sharedVocabulary.inputWidthInvalid",
+    }),
+  );
+}
+
+function validateMediaInteractionSharedVocabulary(
+  interaction: QtiInteraction,
+  diagnostics: QtiDiagnostic[],
+): void {
+  diagnostics.push(
+    ...validateSharedVocabularyMediaPlayerControls({
+      value: interaction.attributes["data-qti-media-player-controls"],
+      subjectQtiName: interaction.qtiName,
+      path: interaction.source?.path,
+      source: interaction.source,
+    }),
+  );
+
+  if (!interaction.object) return;
+  diagnostics.push(
+    ...validateSharedVocabularyMediaPlayerControls({
+      value: interaction.object.attributes["data-qti-media-player-controls"],
+      subjectQtiName: `${interaction.qtiName} media object`,
+      path: interaction.object.source?.path ?? interaction.source?.path,
+      source: interaction.object.source ?? interaction.source,
+    }),
+  );
+}
+
+function sharedClassNames(attributes: Record<string, string>): string[] {
+  return (attributes.class ?? "").split(/\s+/).filter(Boolean);
+}