@conform-ed/qti-react 0.0.14 → 0.0.16

package/src/test/index.ts

@@ -1,4 +1,21 @@
 export { createTestController, type TestControllerOptions } from "./controller";
+export {
+  assessmentResultFromNormalized,
+  buildAssessmentResult,
+  type AssessmentResultDocumentView,
+  type AssessmentResultInput,
+  type AssessmentResultItemDetails,
+  type AssessmentResultView,
+  type ItemResultView,
+  type ResultContextView,
+  type ResultOutcomeVariableView,
+  type ResultResponseVariableView,
+  type ResultSessionIdentifierView,
+  type ResultSessionStatus,
+  type ResultSupportView,
+  type ResultValueView,
+  type TestResultView,
+} from "./results";
 export {
   createTestSessionStore,
   type TestSessionSnapshot,
@@ -7,12 +24,15 @@ export {
 } from "./session-store";
 export type {
   AssessmentItemRefView,
+  RecordedAttempt,
   AssessmentSectionView,
   AssessmentTestView,
   BranchRuleView,
   ItemSessionControlView,
   OutcomeConditionBranch,
   OutcomeRuleView,
+  RejectedSubmission,
+  TemplateDefaultView,
   TestController,
   TestFeedbackView,
   TestItemResult,
@@ -20,6 +40,9 @@ export type {
   TestPlan,
   TestPlanItem,
   TestPlanPart,
+  TestPlanSection,
   TestSessionState,
+  TestTimingState,
   TimeLimitsView,
+  TimingScopeRef,
 } from "./types";

package/src/test/results.ts

@@ -0,0 +1,378 @@
+/**
+ * QTI Results Reporting — the export builder. Maps a session (test view + resolved
+ * plan + persisted state) onto the AssessmentResult model: one final itemResult per
+ * recorded attempt ("A report may contain multiple results for the same instance of
+ * an item representing multiple attempts … each item result must have a different
+ * datestamp"), pendingResponseProcessing for unflushed simultaneous submissions,
+ * and initial entries for everything else — "all items selected for presentation
+ * should be reported with a corresponding itemResult". The shapes mirror the
+ * contracts result schema structurally; serialization to XML lives in qti-xml.
+ */
+
+import { pnpFeaturePreference, resolvePnpActivation, type PnpView } from "../pnp";
+import type { OutcomeDeclarationView, OutcomeValue } from "../rp";
+import type { ResponseDeclarationView, ResponseValue } from "../types";
+import type { AssessmentTestView, RecordedAttempt, TestPlan, TestPlanItem, TestSessionState } from "./types";
+
+export interface ResultValueView {
+  readonly value: string;
+  /** Required for record-cardinality members, invalid otherwise (schema rule). */
+  readonly fieldIdentifier?: string;
+  readonly baseType?: string;
+}
+
+export interface ResultResponseVariableView {
+  readonly identifier: string;
+  readonly cardinality: string;
+  readonly baseType?: string;
+  readonly candidateResponse: { readonly values: readonly ResultValueView[] };
+  readonly correctResponse?: { readonly values: readonly ResultValueView[] };
+}
+
+export interface ResultOutcomeVariableView {
+  readonly identifier: string;
+  readonly cardinality: string;
+  readonly baseType?: string;
+  readonly values: readonly ResultValueView[];
+}
+
+export type ResultSessionStatus =
+  | "final"
+  | "initial"
+  | "pendingExternalScoring"
+  | "pendingResponseProcessing"
+  | "pendingSubmission";
+
+export interface ItemResultView {
+  readonly identifier: string;
+  readonly sequenceIndex?: number;
+  readonly datestamp: string;
+  readonly sessionStatus: ResultSessionStatus;
+  readonly responseVariables?: readonly ResultResponseVariableView[];
+  readonly outcomeVariables?: readonly ResultOutcomeVariableView[];
+  readonly candidateComment?: string;
+}
+
+/**
+ * RR Support (§2.6.4): a feature "aligned to the QTI profile of the 1EdTech Access
+ * for All Personal Needs and Preferences (AfA PNP)".
+ */
+export interface ResultSupportView {
+  readonly name: string;
+  readonly assignment: "assigned" | "universal" | "prohibited" | "inherit";
+  readonly value?: string;
+  readonly xmlLang?: string;
+}
+
+export interface TestResultView {
+  readonly identifier: string;
+  readonly datestamp: string;
+  readonly responseVariables?: readonly ResultResponseVariableView[];
+  readonly outcomeVariables?: readonly ResultOutcomeVariableView[];
+  readonly supports?: readonly ResultSupportView[];
+}
+
+export interface ResultSessionIdentifierView {
+  readonly sourceId: string;
+  readonly identifier: string;
+}
+
+export interface ResultContextView {
+  readonly sourcedId?: string;
+  readonly sessionIdentifiers?: readonly ResultSessionIdentifierView[];
+}
+
+export interface AssessmentResultView {
+  readonly context: ResultContextView;
+  readonly testResult?: TestResultView;
+  readonly itemResults?: readonly ItemResultView[];
+}
+
+export interface AssessmentResultDocumentView {
+  readonly assessmentResult: AssessmentResultView;
+}
+
+export interface AssessmentResultItemDetails {
+  readonly responseDeclarations?: readonly ResponseDeclarationView[];
+  readonly outcomeDeclarations?: readonly OutcomeDeclarationView[];
+  /** The clone's resolved correct responses (`AttemptSnapshot.correctResponses`). */
+  readonly correctResponses?: Readonly<Record<string, ResponseValue>>;
+}
+
+export interface AssessmentResultInput {
+  readonly test: AssessmentTestView;
+  readonly plan: TestPlan;
+  readonly state: TestSessionState;
+  /** Result context (`sourcedId`, session identifiers); the consumer's identifiers. */
+  readonly context?: ResultContextView;
+  /** Export instant for the testResult datestamp (epoch ms; default Date.now()). */
+  readonly nowMs?: number;
+  /** Per-item typing and correct responses; omit (or return null) when unresolvable. */
+  readonly itemDetails?: (item: TestPlanItem) => AssessmentResultItemDetails | null;
+  /** The candidate's AfA PNP the session ran with — reported as testResult supports. */
+  readonly pnp?: PnpView | undefined;
+}
+
+function iso(ms: number): string {
+  return new Date(ms).toISOString();
+}
+
+/**
+ * The supports the session ran with, from the PNP's activation policy: assigned
+ * features carry their stated detail (language; the additional-testing-time value);
+ * prohibited features carry none — "A value MUST NOT be present when
+ * 'assignment=prohibited'" (RR §2.6.4.3).
+ */
+function pnpSupports(pnp: PnpView | undefined): ResultSupportView[] {
+  if (!pnp) {
+    return [];
+  }
+
+  const activation = resolvePnpActivation(pnp);
+  const names = [...new Set([...activation.active, ...activation.optional, ...activation.prohibited])].sort();
+
+  return names.map((name): ResultSupportView => {
+    if (activation.prohibited.has(name)) {
+      return { name, assignment: "prohibited" };
+    }
+
+    const preference = pnpFeaturePreference(pnp, name);
+    const xmlLang = typeof preference?.["xmlLang"] === "string" ? preference["xmlLang"] : undefined;
+
+    let value: string | undefined;
+    if (name === "additional-testing-time") {
+      const time = pnp.additionalTestingTime;
+      value =
+        time?.unlimited === true
+          ? "unlimited"
+          : time?.timeMultiplier !== undefined
+            ? String(time.timeMultiplier)
+            : time?.fixedMinutes !== undefined
+              ? String(time.fixedMinutes)
+              : undefined;
+    }
+
+    return {
+      name,
+      assignment: "assigned",
+      ...(value !== undefined ? { value } : {}),
+      ...(xmlLang !== undefined ? { xmlLang } : {}),
+    };
+  });
+}
+
+/** Flatten a stored value into result `value` entries (record members keep fields). */
+function valueViews(value: OutcomeValue | ResponseValue): ResultValueView[] {
+  if (value === null || value === undefined || value === "") {
+    return [];
+  }
+
+  if (Array.isArray(value)) {
+    return value.filter((member) => member !== null && member !== "").map((member) => ({ value: String(member) }));
+  }
+
+  if (typeof value === "object") {
+    // Record values (arrays were handled above): members keep their field names.
+    return Object.entries(value)
+      .filter(([, member]) => member !== null && member !== "")
+      .map(([fieldIdentifier, member]) => ({ fieldIdentifier, value: String(member) }));
+  }
+
+  return [{ value: String(value) }];
+}
+
+function inferBaseType(value: OutcomeValue | ResponseValue, identifier: string): string | undefined {
+  const sample = Array.isArray(value) ? value[0] : value;
+
+  if (typeof sample === "number") {
+    return "float";
+  }
+
+  if (typeof sample === "boolean") {
+    return "boolean";
+  }
+
+  if (identifier === "completionStatus" || identifier === "completion_status") {
+    return "identifier"; // the built-in's declared type (§2.2.2.3)
+  }
+
+  return typeof sample === "string" ? "string" : undefined;
+}
+
+function outcomeVariablesOf(
+  outcomes: Readonly<Record<string, OutcomeValue>>,
+  declarations: readonly OutcomeDeclarationView[] | undefined,
+): ResultOutcomeVariableView[] {
+  return Object.entries(outcomes).map(([identifier, value]) => {
+    const declaration = declarations?.find((entry) => entry.identifier === identifier);
+    const cardinality = declaration?.cardinality ?? (Array.isArray(value) ? "multiple" : "single");
+    const baseType = declaration?.baseType ?? inferBaseType(value, identifier);
+
+    return {
+      identifier,
+      cardinality,
+      // baseType must be omitted for record cardinality (schema rule).
+      ...(baseType !== undefined && cardinality !== "record" ? { baseType } : {}),
+      values: valueViews(value),
+    };
+  });
+}
+
+/** Durations are "a single float that records time in seconds" (RR base types). */
+function durationVariable(identifier: string, seconds: number): ResultResponseVariableView {
+  return {
+    identifier,
+    cardinality: "single",
+    baseType: "duration",
+    candidateResponse: { values: [{ value: String(seconds) }] },
+  };
+}
+
+/** numAttempts is reported as the built-in response variable it is. */
+function numAttemptsVariable(count: number): ResultResponseVariableView {
+  return {
+    identifier: "numAttempts",
+    cardinality: "single",
+    baseType: "integer",
+    candidateResponse: { values: [{ value: String(count) }] },
+  };
+}
+
+function responseVariablesOf(
+  responses: Readonly<Record<string, ResponseValue>> | undefined,
+  details: AssessmentResultItemDetails | null,
+): ResultResponseVariableView[] {
+  return Object.entries(responses ?? {}).map(([identifier, value]) => {
+    const declaration = details?.responseDeclarations?.find((entry) => entry.identifier === identifier);
+    const cardinality = declaration?.cardinality ?? (Array.isArray(value) ? "multiple" : "single");
+    const baseType = declaration?.baseType;
+    const correct = details?.correctResponses?.[identifier];
+    const correctValues = correct === undefined ? [] : valueViews(correct);
+
+    return {
+      identifier,
+      cardinality,
+      ...(baseType !== undefined && cardinality !== "record" ? { baseType } : {}),
+      candidateResponse: { values: valueViews(value) },
+      // correctResponse requires at least one value (schema); omit when empty.
+      ...(correctValues.length > 0 ? { correctResponse: { values: correctValues } } : {}),
+    };
+  });
+}
+
+export function buildAssessmentResult(input: AssessmentResultInput): AssessmentResultDocumentView {
+  const { test, plan, state } = input;
+  const nowMs = input.nowMs ?? Date.now();
+  const timing = state.timing;
+
+  const scopeDurations: ResultResponseVariableView[] = timing
+    ? [
+        durationVariable("duration", timing.testSeconds),
+        ...plan.parts
+          .filter((part) => timing.partSeconds[part.identifier] !== undefined)
+          .map((part) => durationVariable(`${part.identifier}.duration`, timing.partSeconds[part.identifier]!)),
+        ...Object.keys(plan.sections)
+          .filter((identifier) => timing.sectionSeconds[identifier] !== undefined)
+          .map((identifier) => durationVariable(`${identifier}.duration`, timing.sectionSeconds[identifier]!)),
+      ]
+    : [];
+  const testOutcomes = outcomeVariablesOf(state.testOutcomes, test.outcomeDeclarations);
+  const supports = pnpSupports(input.pnp);
+  const testResult: TestResultView = {
+    identifier: test.identifier,
+    datestamp: iso(nowMs),
+    ...(scopeDurations.length > 0 ? { responseVariables: scopeDurations } : {}),
+    ...(testOutcomes.length > 0 ? { outcomeVariables: testOutcomes } : {}),
+    ...(supports.length > 0 ? { supports } : {}),
+  };
+
+  const itemResults: ItemResultView[] = [];
+  let sequenceIndex = 0;
+
+  for (const part of plan.parts) {
+    for (const item of part.items) {
+      sequenceIndex += 1;
+
+      const details = input.itemDetails?.(item) ?? null;
+      const entries: ItemResultView[] = [];
+
+      // One final itemResult per committed attempt, stamped with its submit instant.
+      (state.attemptHistory?.[item.key] ?? []).forEach((attempt: RecordedAttempt, index) => {
+        const outcomeVariables = outcomeVariablesOf(attempt.outcomes, details?.outcomeDeclarations);
+
+        entries.push({
+          identifier: item.key,
+          sequenceIndex,
+          datestamp: iso(attempt.atMs),
+          sessionStatus: "final",
+          responseVariables: [
+            numAttemptsVariable(index + 1),
+            ...(attempt.durationSeconds !== undefined ? [durationVariable("duration", attempt.durationSeconds)] : []),
+            ...responseVariablesOf(attempt.responses, details),
+          ],
+          ...(outcomeVariables.length > 0 ? { outcomeVariables } : {}),
+        });
+      });
+
+      // An unflushed simultaneous submission: responses are in, outcomes are not
+      // committed until the part flushes — "after submission but before response
+      // processing" (SessionStatusEnum).
+      const pending = state.pendingItemResults?.[item.key];
+
+      if (pending) {
+        entries.push({
+          identifier: item.key,
+          sequenceIndex,
+          datestamp: iso(pending.submittedAtMs ?? nowMs),
+          sessionStatus: "pendingResponseProcessing",
+          responseVariables: [
+            numAttemptsVariable(1),
+            ...(pending.durationSeconds !== undefined ? [durationVariable("duration", pending.durationSeconds)] : []),
+            ...responseVariablesOf(pending.responses, details),
+          ],
+        });
+      }
+
+      if (entries.length === 0) {
+        // "initial … can only be used to describe sessions for which the response
+        // variable numAttempts is 0" — selected (in the plan) but never attempted.
+        const itemSeconds = timing?.itemSeconds[item.key];
+
+        entries.push({
+          identifier: item.key,
+          sequenceIndex,
+          datestamp: iso(nowMs),
+          sessionStatus: "initial",
+          responseVariables: [
+            numAttemptsVariable(0),
+            ...(itemSeconds !== undefined ? [durationVariable("duration", itemSeconds)] : []),
+          ],
+        });
+      }
+
+      // The candidate's comment (allowComment) rides the item's latest result.
+      const comment = state.itemComments?.[item.key];
+
+      if (comment !== undefined) {
+        entries[entries.length - 1] = { ...entries[entries.length - 1]!, candidateComment: comment };
+      }
+
+      itemResults.push(...entries);
+    }
+  }
+
+  return {
+    assessmentResult: {
+      context: input.context ?? {},
+      testResult,
+      ...(itemResults.length > 0 ? { itemResults } : {}),
+    },
+  };
+}
+
+/** Reshape a normalized assessmentResult document into the typed view (import side). */
+export function assessmentResultFromNormalized(document: unknown): AssessmentResultView | null {
+  const root = (document as { assessmentResult?: AssessmentResultView } | null)?.assessmentResult;
+
+  return root && typeof root === "object" ? root : null;
+}

package/src/test/session-store.ts

@@ -7,11 +7,15 @@
  * persistence stays with the consumer (store the seed and `snapshot.state`).
  */
 
+import type { PnpView } from "../pnp";
+import { collectInteractionConstraints } from "../response-validity";
 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 { buildAssessmentResult } from "./results";
+import type { AssessmentResultDocumentView, ResultContextView } from "./results";
 import type { AssessmentItemRefView, TestController, TestFeedbackView, TestPlanItem, TestSessionState } from "./types";
 
 export interface TestSessionStoreOptions {
@@ -27,6 +31,16 @@ export interface TestSessionStoreOptions {
   readonly normalization?: ResponseNormalization;
   /** Registered vendor `customOperator` implementations by class (opt-in). */
   readonly customOperators?: Readonly<Record<string, CustomOperatorImplementation>>;
+  /**
+   * Millisecond clock for the item-session duration clocks (pair it with the
+   * controller's `now` for coherent timing). Defaults to Date.now.
+   */
+  readonly now?: () => number;
+  /**
+   * The candidate's AfA PNP — pair it with the controller's `pnp` (time-limit
+   * accommodations live there). The store reports it as result supports.
+   */
+  readonly pnp?: PnpView;
 }
 
 export interface TestSessionSnapshot {
@@ -48,6 +62,26 @@ export interface TestSessionStore {
   readonly canMoveTo: (itemKey: string) => boolean;
   readonly moveTo: (itemKey: string) => void;
   readonly end: () => void;
+  /** Fold elapsed time and apply time-limit expiries; consumers drive the cadence. */
+  readonly tick: () => void;
+  /** Post-end review navigation (allowReview); a no-op where review is barred. */
+  readonly review: (itemKey: string) => void;
+  /** Record a candidate comment (allowComment); a no-op where comments are barred. */
+  readonly setItemComment: (itemKey: string, comment: string) => void;
+  /** Suspend the session: every scope clock and the current item's clock stop. */
+  readonly suspend: () => void;
+  /** Resume a suspended session; the gap never accrues to any duration. */
+  readonly resume: () => void;
+  /**
+   * Build the QTI Results Reporting document for the session as it stands:
+   * per-attempt final itemResults, pending submissions, initial entries for
+   * everything else, typed by the resolved item views and the clones' correct
+   * responses. Serialize with qti-xml's `serializeQtiAssessmentResult`.
+   */
+  readonly assessmentResult: (options?: {
+    readonly context?: ResultContextView;
+    readonly nowMs?: number;
+  }) => AssessmentResultDocumentView;
 }
 
 /** Identifiers whose correct response arrives via `setCorrectResponse` in templates. */
@@ -153,10 +187,33 @@ export function createTestSessionStore(controller: TestController, options: Test
     };
   }
 
+  /** The item whose session clock should be running: current, in an open session. */
+  function activeKeyOf(sessionState: TestSessionState): string | null {
+    return sessionState.status === "in-progress" ? sessionState.currentItemKey : null;
+  }
+
   function emit(next: TestSessionState): void {
+    const previousActive = activeKeyOf(state);
+
     state = next;
     snapshot = buildSnapshot();
 
+    // Item sessions suspend on navigation and resume on return — "candidates may
+    // change their responses for an item and then leave it in the suspended state by
+    // navigating to a different item in the same part of the test" — and the whole
+    // session's suspended/ended states stop the current clock too.
+    const nextActive = activeKeyOf(next);
+
+    if (previousActive !== nextActive) {
+      if (previousActive !== null) {
+        itemStores.get(previousActive)?.suspend();
+      }
+
+      if (nextActive !== null) {
+        itemStores.get(nextActive)?.resume();
+      }
+    }
+
     for (const listener of listeners) {
       listener();
     }
@@ -177,16 +234,25 @@ export function createTestSessionStore(controller: TestController, options: Test
     }
 
     const view = itemView(itemKey);
+    const planItem = planItemsByKey.get(itemKey);
 
-    if (!view) {
+    if (!view || !planItem) {
       itemStores.set(itemKey, null);
       return null;
     }
 
+    // validate-responses is "only applicable when the item is in a qti-test-part
+    // with individual submission mode".
+    const individual = controller.plan.parts.some(
+      (part) => part.identifier === planItem.partIdentifier && part.submissionMode === "individual",
+    );
+
     const store = createAttemptStore(
       view.responseDeclarations,
       {},
       {
+        constraints: collectInteractionConstraints(view.itemBody.content),
+        validateResponses: planItem.sessionControl.validateResponses && individual,
         outcomeDeclarations: view.outcomeDeclarations,
         responseProcessing: view.responseProcessing,
         templateDeclarations: view.templateDeclarations,
@@ -195,9 +261,18 @@ export function createTestSessionStore(controller: TestController, options: Test
         seed: deriveItemSeed(options.seed, itemKey),
         normalization: options.normalization,
         customOperators: options.customOperators,
+        // Test-level templateDefault values recorded by the controller (§5.152).
+        templateDefaultValues: state.templateDefaultValues?.[itemKey],
+        now: options.now,
       },
     );
 
+    // A store created for an item that is not the running current item starts with
+    // its session clock suspended; navigation (emit) resumes it when it is reached.
+    if (activeKeyOf(state) !== itemKey) {
+      store.suspend();
+    }
+
     const scorable = scorableIdentifiers(view);
 
     // Every submitted snapshot flows into the controller, which decides what it means:
@@ -213,6 +288,11 @@ export function createTestSessionStore(controller: TestController, options: Test
           outcomes: attempt.outcomes,
           ...resultFlags(attempt, scorable),
           ...(view.adaptive === true ? { adaptive: true } : {}),
+          // The item session's elapsed seconds feed the built-in ITEM.duration.
+          ...(attempt.durationSeconds !== null ? { durationSeconds: attempt.durationSeconds } : {}),
+          valid: attempt.responseViolations.length === 0,
+          // Recorded into the attempt history: candidateResponse in results reporting.
+          responses: attempt.responses,
         });
 
         if (next !== state) {
@@ -239,5 +319,33 @@ export function createTestSessionStore(controller: TestController, options: Test
     canMoveTo: (itemKey) => controller.canMoveTo(state, itemKey),
     moveTo: (itemKey) => emit(controller.moveTo(state, itemKey)),
     end: () => emit(controller.end(state)),
+    tick: () => emit(controller.tick(state)),
+    review: (itemKey) => emit(controller.review(state, itemKey)),
+    setItemComment: (itemKey, comment) => emit(controller.setItemComment(state, itemKey, comment)),
+    suspend: () => emit(controller.suspend(state)),
+    resume: () => emit(controller.resume(state)),
+    assessmentResult: (resultOptions) =>
+      buildAssessmentResult({
+        test: controller.test,
+        plan: controller.plan,
+        state,
+        ...(resultOptions?.context !== undefined ? { context: resultOptions.context } : {}),
+        nowMs: resultOptions?.nowMs ?? (options.now ?? Date.now)(),
+        ...(options.pnp !== undefined ? { pnp: options.pnp } : {}),
+        itemDetails: (item) => {
+          const view = itemView(item.key);
+
+          if (!view) {
+            return null;
+          }
+
+          return {
+            responseDeclarations: view.responseDeclarations,
+            ...(view.outcomeDeclarations !== undefined ? { outcomeDeclarations: view.outcomeDeclarations } : {}),
+            // The clone's template-resolved correct responses back `correctResponse`.
+            correctResponses: itemStore(item.key)?.getSnapshot().correctResponses ?? {},
+          };
+        },
+      }),
   };
 }