@conform-ed/qti-react 0.0.12 → 0.0.13

package/src/test/index.ts

@@ -0,0 +1,25 @@
+export { createTestController, type TestControllerOptions } from "./controller";
+export {
+  createTestSessionStore,
+  type TestSessionSnapshot,
+  type TestSessionStore,
+  type TestSessionStoreOptions,
+} from "./session-store";
+export type {
+  AssessmentItemRefView,
+  AssessmentSectionView,
+  AssessmentTestView,
+  BranchRuleView,
+  ItemSessionControlView,
+  OutcomeConditionBranch,
+  OutcomeRuleView,
+  TestController,
+  TestFeedbackView,
+  TestItemResult,
+  TestPartView,
+  TestPlan,
+  TestPlanItem,
+  TestPlanPart,
+  TestSessionState,
+  TimeLimitsView,
+} from "./types";

package/src/test/session-store.ts

@@ -0,0 +1,244 @@
+/**
+ * The Test Session Store: glue between the headless Test Controller (ADR-0005) and
+ * per-item Attempt Stores. It holds the controller's JSON session state, creates item
+ * stores lazily with key-derived seeds (so every clone is replayable from the test
+ * seed alone), and feeds item submissions back into the controller so test outcome
+ * processing stays current. React-free — UI layers subscribe like any external store;
+ * persistence stays with the consumer (store the seed and `snapshot.state`).
+ */
+
+import type { CustomOperatorImplementation, ResponseNormalization, TemplateRuleView } from "../rp";
+import type { AssessmentItemView } from "../runtime";
+import { createAttemptStore, type AttemptSnapshot, type AttemptStore } from "../store";
+import { isResponseRecord } from "../types";
+import type { ResponseValue } from "../types";
+
+import type { AssessmentItemRefView, TestController, TestFeedbackView, TestPlanItem, TestSessionState } from "./types";
+
+export interface TestSessionStoreOptions {
+  /**
+   * Resolve an item ref to its view. Synchronous by design: load the package's items
+   * before mounting the session; return null for refs that cannot be delivered.
+   */
+  readonly resolveItem: (ref: AssessmentItemRefView) => AssessmentItemView | null;
+  /** The test seed: drives plan resolution replay and derives per-item clone seeds. */
+  readonly seed: number;
+  /** Resume a persisted session (item responses are session-local, not part of it). */
+  readonly initialState?: TestSessionState;
+  readonly normalization?: ResponseNormalization;
+  /** Registered vendor `customOperator` implementations by class (opt-in). */
+  readonly customOperators?: Readonly<Record<string, CustomOperatorImplementation>>;
+}
+
+export interface TestSessionSnapshot {
+  readonly state: TestSessionState;
+  readonly currentItem: TestPlanItem | null;
+  /** The resolved view for the current item, or null when unresolvable. */
+  readonly currentItemView: AssessmentItemView | null;
+  readonly visibleFeedbacks: readonly TestFeedbackView[];
+}
+
+export interface TestSessionStore {
+  readonly controller: TestController;
+  readonly subscribe: (listener: () => void) => () => void;
+  readonly getSnapshot: () => TestSessionSnapshot;
+  /** The item's Attempt Store — created once per key, reused across navigation. */
+  readonly itemStore: (itemKey: string) => AttemptStore | null;
+  readonly itemView: (itemKey: string) => AssessmentItemView | null;
+  readonly next: () => void;
+  readonly canMoveTo: (itemKey: string) => boolean;
+  readonly moveTo: (itemKey: string) => void;
+  readonly end: () => void;
+}
+
+/** Identifiers whose correct response arrives via `setCorrectResponse` in templates. */
+function collectCorrectResponseTargets(rules: readonly TemplateRuleView[] | undefined, into: Set<string>): void {
+  for (const rule of rules ?? []) {
+    if (rule.kind === "setCorrectResponse" && rule.identifier !== undefined) {
+      into.add(rule.identifier);
+    }
+
+    for (const branch of [rule.templateIf, ...(rule.templateElseIfs ?? [])]) {
+      if (branch) {
+        collectCorrectResponseTargets(branch.rules, into);
+      }
+    }
+
+    if (rule.templateElse) {
+      collectCorrectResponseTargets(rule.templateElse.rules, into);
+    }
+  }
+}
+
+/** The response declarations an attempt can be "correct" about (incl. templated ones). */
+function scorableIdentifiers(view: AssessmentItemView): Set<string> {
+  const templated = new Set<string>();
+
+  collectCorrectResponseTargets(view.templateProcessing?.rules, templated);
+
+  return new Set(
+    view.responseDeclarations
+      .filter(
+        (declaration) =>
+          declaration.correctResponse !== undefined ||
+          declaration.mapping !== undefined ||
+          declaration.areaMapping !== undefined ||
+          templated.has(declaration.identifier),
+      )
+      .map((declaration) => declaration.identifier),
+  );
+}
+
+function hasResponse(value: ResponseValue): boolean {
+  if (value === null || value === undefined || value === "") {
+    return false;
+  }
+
+  if (isResponseRecord(value)) {
+    return Object.values(value).some((member) => member !== null && member !== "");
+  }
+
+  return !Array.isArray(value) || value.length > 0;
+}
+
+/** Derive the controller-facing correctness flags from a submitted attempt. */
+function resultFlags(
+  attempt: AttemptSnapshot,
+  scorable: ReadonlySet<string>,
+): { correct?: boolean; responded: boolean } {
+  const relevant = attempt.scores.filter((score) => scorable.has(score.identifier));
+
+  return {
+    ...(relevant.length > 0 ? { correct: relevant.every((score) => score.correct) } : {}),
+    responded: Object.values(attempt.responses).some(hasResponse),
+  };
+}
+
+/** FNV-1a over the item key, mixed with the test seed: stable per-item clone seeds. */
+function deriveItemSeed(seed: number, itemKey: string): number {
+  let hash = (0x811c9dc5 ^ seed) >>> 0;
+
+  for (let index = 0; index < itemKey.length; index += 1) {
+    hash = Math.imul(hash ^ itemKey.charCodeAt(index), 0x01000193) >>> 0;
+  }
+
+  return hash;
+}
+
+export function createTestSessionStore(controller: TestController, options: TestSessionStoreOptions): TestSessionStore {
+  const listeners = new Set<() => void>();
+  const planItemsByKey = new Map<string, TestPlanItem>();
+
+  for (const part of controller.plan.parts) {
+    for (const item of part.items) {
+      planItemsByKey.set(item.key, item);
+    }
+  }
+
+  const itemViews = new Map<string, AssessmentItemView | null>();
+  const itemStores = new Map<string, AttemptStore | null>();
+  /** The last attempt snapshot forwarded per item — dedupes subscription firings. */
+  const forwardedAttempts = new Map<string, unknown>();
+
+  let state = options.initialState ?? controller.start();
+  let snapshot = buildSnapshot();
+
+  function buildSnapshot(): TestSessionSnapshot {
+    const currentItem = controller.currentItem(state);
+
+    return {
+      state,
+      currentItem,
+      currentItemView: currentItem === null ? null : itemView(currentItem.key),
+      visibleFeedbacks: controller.visibleTestFeedbacks(state),
+    };
+  }
+
+  function emit(next: TestSessionState): void {
+    state = next;
+    snapshot = buildSnapshot();
+
+    for (const listener of listeners) {
+      listener();
+    }
+  }
+
+  function itemView(itemKey: string): AssessmentItemView | null {
+    if (!itemViews.has(itemKey)) {
+      const planItem = planItemsByKey.get(itemKey);
+      itemViews.set(itemKey, planItem ? options.resolveItem(planItem.ref) : null);
+    }
+
+    return itemViews.get(itemKey) ?? null;
+  }
+
+  function itemStore(itemKey: string): AttemptStore | null {
+    if (itemStores.has(itemKey)) {
+      return itemStores.get(itemKey) ?? null;
+    }
+
+    const view = itemView(itemKey);
+
+    if (!view) {
+      itemStores.set(itemKey, null);
+      return null;
+    }
+
+    const store = createAttemptStore(
+      view.responseDeclarations,
+      {},
+      {
+        outcomeDeclarations: view.outcomeDeclarations,
+        responseProcessing: view.responseProcessing,
+        templateDeclarations: view.templateDeclarations,
+        templateProcessing: view.templateProcessing,
+        adaptive: view.adaptive,
+        seed: deriveItemSeed(options.seed, itemKey),
+        normalization: options.normalization,
+        customOperators: options.customOperators,
+      },
+    );
+
+    const scorable = scorableIdentifiers(view);
+
+    // Every submitted snapshot flows into the controller, which decides what it means:
+    // an attempt (individual), a pending revision (simultaneous), or a refusal
+    // (maxAttempts spent) — refused results never reach session state.
+    store.subscribe(() => {
+      const attempt = store.getSnapshot();
+
+      if (attempt.submitted && forwardedAttempts.get(itemKey) !== attempt) {
+        forwardedAttempts.set(itemKey, attempt);
+
+        const next = controller.submitItem(state, itemKey, {
+          outcomes: attempt.outcomes,
+          ...resultFlags(attempt, scorable),
+          ...(view.adaptive === true ? { adaptive: true } : {}),
+        });
+
+        if (next !== state) {
+          emit(next);
+        }
+      }
+    });
+
+    itemStores.set(itemKey, store);
+
+    return store;
+  }
+
+  return {
+    controller,
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    getSnapshot: () => snapshot,
+    itemStore,
+    itemView,
+    next: () => emit(controller.next(state)),
+    canMoveTo: (itemKey) => controller.canMoveTo(state, itemKey),
+    moveTo: (itemKey) => emit(controller.moveTo(state, itemKey)),
+    end: () => emit(controller.end(state)),
+  };
+}

package/src/test/types.ts

@@ -0,0 +1,203 @@
+/**
+ * Structural views of QTI 3 `assessmentTest` and the Test Controller's session state
+ * (ADR-0005). The controller owns the rules; everything in `TestSessionState` is plain
+ * JSON so the consumer owns persistence — store the seed and the state, replay the
+ * test.
+ */
+
+import type { CapabilityIssue } from "../capability";
+import type { OutcomeDeclarationView, OutcomeValue, RpExpressionView } from "../rp";
+import type { BodyNode } from "../runtime";
+
+export interface BranchRuleView {
+  /** A target identifier in the same test part, or EXIT_TEST / EXIT_TESTPART / EXIT_SECTION. */
+  readonly target: string;
+  readonly expression: RpExpressionView;
+}
+
+/**
+ * QTI `itemSessionControl`: per-level overrides cascading testPart → section → itemRef.
+ * The controller enforces `maxAttempts` and `allowSkipping`; the rest is surfaced for
+ * delivery chrome (review/solution/comment affordances are UI concerns).
+ */
+export interface ItemSessionControlView {
+  /** Attempts allowed per item; 0 means unlimited. Spec default: 1. */
+  readonly maxAttempts?: number;
+  readonly showFeedback?: boolean;
+  readonly allowReview?: boolean;
+  readonly showSolution?: boolean;
+  readonly allowComment?: boolean;
+  /** When false, the candidate must attempt the item before moving past it. */
+  readonly allowSkipping?: boolean;
+  readonly validateResponses?: boolean;
+}
+
+/**
+ * QTI `timeLimits` (seconds). The controller is clock-free by design (ADR-0005): these
+ * are data for the consumer's timers, which call `next()`/`end()` when time runs out.
+ */
+export interface TimeLimitsView {
+  readonly minTime?: number;
+  readonly maxTime?: number;
+  readonly allowLateSubmission?: boolean;
+}
+
+export interface AssessmentItemRefView {
+  readonly kind: "assessmentItemRef";
+  readonly identifier: string;
+  readonly href?: string;
+  readonly categories?: readonly string[];
+  readonly fixed?: boolean;
+  readonly required?: boolean;
+  readonly preConditions?: readonly RpExpressionView[];
+  readonly branchRules?: readonly BranchRuleView[];
+  readonly itemSessionControl?: ItemSessionControlView;
+  readonly timeLimits?: TimeLimitsView;
+  /** Named weights for `testVariables`/aggregate weighting (missing names weigh 1). */
+  readonly weights?: ReadonlyArray<{ readonly identifier: string; readonly value: number }>;
+}
+
+export interface AssessmentSectionView {
+  readonly kind: "assessmentSection";
+  readonly identifier: string;
+  readonly title?: string;
+  readonly visible?: boolean;
+  readonly fixed?: boolean;
+  readonly required?: boolean;
+  readonly selection?: { readonly select: number; readonly withReplacement?: boolean };
+  readonly ordering?: { readonly shuffle?: boolean };
+  readonly preConditions?: readonly RpExpressionView[];
+  readonly branchRules?: readonly BranchRuleView[];
+  readonly itemSessionControl?: ItemSessionControlView;
+  readonly timeLimits?: TimeLimitsView;
+  readonly children: ReadonlyArray<AssessmentSectionView | AssessmentItemRefView>;
+}
+
+export interface TestPartView {
+  readonly identifier: string;
+  readonly navigationMode: "linear" | "nonlinear";
+  readonly submissionMode: "individual" | "simultaneous";
+  readonly preConditions?: readonly RpExpressionView[];
+  readonly branchRules?: readonly BranchRuleView[];
+  readonly itemSessionControl?: ItemSessionControlView;
+  readonly timeLimits?: TimeLimitsView;
+  readonly assessmentSections: readonly AssessmentSectionView[];
+}
+
+export interface TestFeedbackView {
+  readonly access?: "atEnd" | "during";
+  readonly outcomeIdentifier: string;
+  readonly identifier: string;
+  readonly showHide?: "show" | "hide";
+  readonly content?: readonly BodyNode[];
+}
+
+export interface OutcomeConditionBranch {
+  readonly expression: RpExpressionView;
+  readonly rules: readonly OutcomeRuleView[];
+}
+
+/** One outcome rule: outcomeCondition, setOutcomeValue, or exitTest. */
+export interface OutcomeRuleView {
+  readonly kind: string;
+  readonly identifier?: string;
+  readonly expression?: RpExpressionView;
+  readonly outcomeIf?: OutcomeConditionBranch;
+  readonly outcomeElseIfs?: readonly OutcomeConditionBranch[];
+  readonly outcomeElse?: { readonly rules: readonly OutcomeRuleView[] };
+}
+
+export interface AssessmentTestView {
+  readonly identifier: string;
+  readonly title?: string;
+  readonly outcomeDeclarations?: readonly OutcomeDeclarationView[];
+  readonly timeLimits?: TimeLimitsView;
+  readonly testParts: readonly TestPartView[];
+  readonly outcomeProcessing?: { readonly rules: readonly OutcomeRuleView[] };
+  readonly testFeedbacks?: readonly TestFeedbackView[];
+}
+
+// ---------- The resolved delivery plan (selection + ordering applied) ----------
+
+export interface TestPlanItem {
+  /** The item ref identifier — unique within the test, used as the session key. */
+  readonly key: string;
+  readonly ref: AssessmentItemRefView;
+  readonly partIdentifier: string;
+  readonly sectionPath: readonly string[];
+  /** The item's own preconditions plus its ancestor sections' (all must pass). */
+  readonly preConditions: readonly RpExpressionView[];
+  /** Effective session control: part → section → itemRef cascade over spec defaults. */
+  readonly sessionControl: Required<ItemSessionControlView>;
+  /** The item ref's own time limits (part/test limits live on their own levels). */
+  readonly timeLimits?: TimeLimitsView;
+}
+
+export interface TestPlanPart {
+  readonly identifier: string;
+  readonly navigationMode: "linear" | "nonlinear";
+  readonly submissionMode: "individual" | "simultaneous";
+  readonly timeLimits?: TimeLimitsView;
+  readonly items: readonly TestPlanItem[];
+}
+
+export interface TestPlan {
+  readonly timeLimits?: TimeLimitsView;
+  readonly parts: readonly TestPlanPart[];
+}
+
+// ---------- Session state (consumer-persisted, plain JSON) ----------
+
+export interface TestItemResult {
+  readonly outcomes: Readonly<Record<string, OutcomeValue>>;
+  /**
+   * Whether every scorable response variable matched (feeds numberCorrect /
+   * numberIncorrect). Omit when the item has nothing to be correct about.
+   */
+  readonly correct?: boolean;
+  /** The candidate gave at least one non-empty response (feeds numberResponded). */
+  readonly responded?: boolean;
+  /** Adaptive items manage their own attempt lifecycle, so maxAttempts is ignored (spec). */
+  readonly adaptive?: boolean;
+}
+
+export interface TestSessionState {
+  readonly status: "in-progress" | "ended";
+  readonly currentItemKey: string | null;
+  readonly itemOutcomes: Readonly<Record<string, Readonly<Record<string, OutcomeValue>>>>;
+  readonly attemptedItems: readonly string[];
+  readonly attemptCounts: Readonly<Record<string, number>>;
+  /** Items that have been the current item at least once (feeds numberPresented). */
+  readonly presentedItems: readonly string[];
+  /** Items whose latest attempt carried a response (feeds numberResponded). */
+  readonly respondedItems: readonly string[];
+  /** Items whose latest attempt was correct / incorrect (feeds numberCorrect/Incorrect). */
+  readonly correctItems: readonly string[];
+  readonly incorrectItems: readonly string[];
+  /**
+   * Results held back in simultaneous-submission parts (QTI: the part's responses are
+   * submitted together). They commit when the part is left or the test ends; until
+   * then they are invisible to outcome processing and feedback.
+   */
+  readonly pendingItemResults: Readonly<Record<string, TestItemResult>>;
+  readonly testOutcomes: Readonly<Record<string, OutcomeValue>>;
+}
+
+export interface TestController {
+  readonly plan: TestPlan;
+  /** Static capability issues found in outcome processing, preconditions, and branch rules. */
+  readonly issues: readonly CapabilityIssue[];
+  readonly start: () => TestSessionState;
+  readonly currentItem: (state: TestSessionState) => TestPlanItem | null;
+  readonly canMoveTo: (state: TestSessionState, itemKey: string) => boolean;
+  readonly moveTo: (state: TestSessionState, itemKey: string) => TestSessionState;
+  /** Whether `next()` would change state (false when allowSkipping blocks the move). */
+  readonly canNext: (state: TestSessionState) => boolean;
+  readonly next: (state: TestSessionState) => TestSessionState;
+  /** Attempts left for the item under its effective maxAttempts (Infinity when unlimited). */
+  readonly remainingAttempts: (state: TestSessionState, itemKey: string) => number;
+  readonly canSubmitItem: (state: TestSessionState, itemKey: string) => boolean;
+  readonly submitItem: (state: TestSessionState, itemKey: string, result: TestItemResult) => TestSessionState;
+  readonly end: (state: TestSessionState) => TestSessionState;
+  readonly visibleTestFeedbacks: (state: TestSessionState) => readonly TestFeedbackView[];
+}

package/src/types.ts

@@ -5,8 +5,19 @@
  * schemas are `z.lazy` (statically `any`). No React or Mantine here.
  */
 
+/** One field of a record response; fields keep their runtime type (PCI JSON typing). */
+export type ResponseFieldValue = string | number | boolean | null;
+
+/** A record-cardinality response: named, individually-typed fields (PCI contracts). */
+export type ResponseRecordValue = Readonly<Record<string, ResponseFieldValue>>;
+
 /** A candidate response for one interaction, keyed in state by `responseIdentifier`. */
-export type ResponseValue = string | readonly string[] | null;
+export type ResponseValue = string | readonly string[] | ResponseRecordValue | null;
+
+/** Narrow a ResponseValue to its record variant. */
+export function isResponseRecord(value: ResponseValue): value is ResponseRecordValue {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 
 export type Cardinality = "single" | "multiple" | "ordered" | "record";
 
@@ -27,12 +38,27 @@ export interface MappingView {
   readonly defaultValue?: number;
 }
 
+/** One scored area for point responses (QTI `areaMapEntry`). */
+export interface AreaMapEntryView {
+  readonly shape: string;
+  readonly coords: readonly number[];
+  readonly mappedValue: number;
+}
+
+export interface AreaMappingView {
+  readonly areaMapEntries: readonly AreaMapEntryView[];
+  readonly lowerBound?: number;
+  readonly upperBound?: number;
+  readonly defaultValue?: number;
+}
+
 export interface ResponseDeclarationView {
   readonly identifier: string;
   readonly cardinality: Cardinality;
   readonly baseType?: string;
   readonly correctResponse?: CorrectResponseView;
   readonly mapping?: MappingView;
+  readonly areaMapping?: AreaMappingView;
 }
 
 /** The scored outcome for one response variable. */