@conform-ed/qti-react 0.0.12 → 0.0.14

package/dist/test/types.d.ts

@@ -0,0 +1,194 @@
+/**
+ * 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[];
+}
+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[];
+}
+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/dist/types.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Runtime view types for the headless core. These are structural views of the
+ * `@conform-ed/contracts` QTI 3.0.1 shapes — the runtime validates items with the
+ * contract schemas, but works against these narrowed types because several contract
+ * 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[] | ResponseRecordValue | null;
+/** Narrow a ResponseValue to its record variant. */
+export declare function isResponseRecord(value: ResponseValue): value is ResponseRecordValue;
+export type Cardinality = "single" | "multiple" | "ordered" | "record";
+export interface CorrectResponseView {
+    readonly values: ReadonlyArray<{
+        readonly value: string;
+    }>;
+}
+export interface MapEntryView {
+    readonly mapKey: string;
+    readonly mappedValue: number;
+    readonly caseSensitive?: boolean;
+}
+export interface MappingView {
+    readonly mapEntries: readonly MapEntryView[];
+    readonly lowerBound?: number;
+    readonly upperBound?: number;
+    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. */
+export interface ScoreResult {
+    readonly identifier: string;
+    readonly score: number;
+    readonly maxScore: number;
+    readonly correct: boolean;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@conform-ed/qti-react",
-  "version": "0.0.12",
+  "version": "0.0.14",
   "files": [
     "src",
     "dist"
@@ -9,20 +9,22 @@
   "module": "src/index.ts",
   "exports": {
     ".": {
-      "types": "./src/index.ts",
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     }
   },
   "scripts": {
-    "build": "bun build ./src/index.ts --outdir dist --format esm --target browser --external react --external react-dom --external zod",
-    "typecheck": "tsgo --noEmit",
-    "lint": "oxlint --config ../../.oxlintrc.jsonc .",
+    "build": "bun build ./src/index.ts --outdir dist --format esm --target browser --external react --external react-dom --external zod && tsgo -p tsconfig.build.json",
     "format": "oxfmt --config ../../.oxfmtrc.jsonc --check .",
-    "test": "bun test"
+    "lint": "oxlint --config ../../.oxlintrc.jsonc .",
+    "test": "bun test",
+    "typecheck": "tsgo --noEmit"
   },
   "devDependencies": {
+    "@conform-ed/qti-xml": "0.0.13",
     "@types/react": "^19.2.17",
     "@types/react-dom": "^19",
+    "happy-dom": "^20.10.2",
     "react": "^19.2.7",
     "react-dom": "^19"
   },

package/src/capability.ts

@@ -0,0 +1,24 @@
+/**
+ * Capability Report types (ADR-0003): the runtime's answer to "can this content be
+ * delivered, and if not, why". In their own module so the RP interpreter can report
+ * issues without importing the React runtime.
+ */
+
+export type CapabilityIssueType =
+  | "unsupported-interaction"
+  | "invalid-interaction"
+  | "unsupported-element"
+  | "unsupported-rp";
+
+export interface CapabilityIssue {
+  readonly type: CapabilityIssueType;
+  /** The interaction kind, element name, or RP rule/operator/template at issue. */
+  readonly name: string;
+  readonly responseIdentifier?: string;
+  readonly detail?: string;
+}
+
+export interface CapabilityReport {
+  readonly deliverable: boolean;
+  readonly issues: readonly CapabilityIssue[];
+}

package/src/content-model.ts

@@ -13,8 +13,29 @@
  * HTML5 at once".
  */
 
-/** Interaction node kinds the v0 runtime can render. */
-export const v0InteractionKinds = ["choiceInteraction", "textEntryInteraction", "inlineChoiceInteraction"] as const;
+/** Interaction node kinds conform-ed ships descriptors and Reference Skins for. */
+export const v0InteractionKinds = [
+  "associateInteraction",
+  "choiceInteraction",
+  "drawingInteraction",
+  "endAttemptInteraction",
+  "extendedTextInteraction",
+  "gapMatchInteraction",
+  "graphicAssociateInteraction",
+  "graphicGapMatchInteraction",
+  "graphicOrderInteraction",
+  "hotspotInteraction",
+  "hottextInteraction",
+  "inlineChoiceInteraction",
+  "matchInteraction",
+  "mediaInteraction",
+  "orderInteraction",
+  "positionObjectStage",
+  "selectPointInteraction",
+  "sliderInteraction",
+  "textEntryInteraction",
+  "uploadInteraction",
+] as const;
 
 export type V0InteractionKind = (typeof v0InteractionKinds)[number];
 
@@ -26,16 +47,63 @@ const v0FlowElements = new Set<string>([
   "em",
   "b",
   "i",
+  "sub",
+  "sup",
   "br",
   "ul",
   "ol",
   "li",
   // language-critical
   "ruby",
+  "rb",
   "rt",
   "rp",
+  // media (the first media-milestone growth; src/poster route through the Asset Resolver)
+  "img",
+  "audio",
+  "video",
+  "source",
+  "track",
+  "picture",
+  "figure",
+  "figcaption",
+  // embedded media the corpus uses for stages and standalone assets
+  "object",
+  // structural vocabulary the official corpus uses (fixture-driven growth, ADR-0002)
+  "div",
+  "section",
+  "h1",
+  "h2",
+  "h3",
+  "h4",
+  "h5",
+  "h6",
+  "blockquote",
+  "hr",
+  // tables (gradebook-style content; conservative semantics)
+  "table",
+  "caption",
+  "thead",
+  "tbody",
+  "tfoot",
+  "tr",
+  "th",
+  "td",
 ]);
 
+/** Element-specific attribute allowlists, additive to the global set. */
+const v0ElementAttributes: ReadonlyMap<string, ReadonlySet<string>> = new Map([
+  ["img", new Set(["src", "alt", "width", "height"])],
+  ["audio", new Set(["src", "controls", "loop", "muted", "preload"])],
+  ["video", new Set(["src", "controls", "loop", "muted", "preload", "poster", "width", "height"])],
+  ["source", new Set(["src", "type"])],
+  ["track", new Set(["src", "kind", "srclang", "label", "default"])],
+  ["object", new Set(["data", "type", "width", "height"])],
+]);
+
+/** Attribute names treated as packaged-asset references (rewritten by the Asset Resolver). */
+const v0UrlAttributes = new Set<string>(["src", "poster", "data"]);
+
 /**
  * The MathML root. Its subtree is rendered structurally (presentation MathML) with the
  * same attribute hardening, but element names inside are not individually allowlisted
@@ -51,6 +119,10 @@ export interface ContentModel {
   readonly flowElements: ReadonlySet<string>;
   readonly mathRoot: string;
   readonly globalAttributes: ReadonlySet<string>;
+  /** Per-element attribute allowlists, additive to `globalAttributes`. */
+  readonly elementAttributes: ReadonlyMap<string, ReadonlySet<string>>;
+  /** Attributes whose values are asset references, routed through the Asset Resolver. */
+  readonly urlAttributes: ReadonlySet<string>;
 }
 
 export const v0ContentModel: ContentModel = {
@@ -58,6 +130,8 @@ export const v0ContentModel: ContentModel = {
   flowElements: v0FlowElements,
   mathRoot: v0MathRoot,
   globalAttributes: v0GlobalAttributes,
+  elementAttributes: v0ElementAttributes,
+  urlAttributes: v0UrlAttributes,
 };
 
 export function isAllowedFlowElement(model: ContentModel, name: string): boolean {
@@ -84,11 +158,13 @@ function isUnsafeAttribute(name: string, value: unknown): boolean {
 }
 
 /**
- * Reduce a raw attribute bag to the safe, allowlisted subset. Used by the body walk so
- * a node that validates against QTI structure still cannot carry script or handlers.
+ * Reduce a raw attribute bag to the safe, allowlisted subset for one element. Used by
+ * the body walk so a node that validates against QTI structure still cannot carry
+ * script or handlers. The allowlist is the global set plus the element's own entries.
  */
 export function sanitizeAttributes(
   model: ContentModel,
+  elementName: string,
   attributes: Record<string, unknown> | undefined,
 ): Record<string, string> {
   const safe: Record<string, string> = {};
@@ -97,12 +173,14 @@ export function sanitizeAttributes(
     return safe;
   }
 
+  const elementAllowed = model.elementAttributes.get(elementName);
+
   for (const [name, value] of Object.entries(attributes)) {
     if (isUnsafeAttribute(name, value)) {
       continue;
     }
 
-    if (!model.globalAttributes.has(name)) {
+    if (!model.globalAttributes.has(name) && !elementAllowed?.has(name)) {
       continue;
     }
 
@@ -113,3 +191,24 @@ export function sanitizeAttributes(
 
   return safe;
 }
+
+/**
+ * Attribute hardening for MathML subtrees: presentation attributes (mathvariant,
+ * linethickness, …) are not individually allowlisted — MathML has no scripting surface
+ * once event handlers and javascript: URLs are stripped.
+ */
+export function sanitizeMathAttributes(attributes: Record<string, unknown> | undefined): Record<string, string> {
+  const safe: Record<string, string> = {};
+
+  if (!attributes) {
+    return safe;
+  }
+
+  for (const [name, value] of Object.entries(attributes)) {
+    if (!isUnsafeAttribute(name, value) && typeof value === "string") {
+      safe[name] = value;
+    }
+  }
+
+  return safe;
+}

package/src/graphic.ts

@@ -0,0 +1,103 @@
+/**
+ * Graphic primitives shared by the graphic interaction family and areaMapping scoring:
+ * QTI shape/coords parsing and point-in-shape hit testing. Pure logic, no React.
+ *
+ * Shapes follow the QTI (HTML image-map) conventions:
+ * - `circle`:  center-x, center-y, radius
+ * - `rect`:    left-x, top-y, right-x, bottom-y
+ * - `poly`:    x1, y1, ..., xn, yn
+ * - `ellipse`: center-x, center-y, radius-x, radius-y
+ * - `default`: the entire image
+ */
+
+export type QtiShape = "circle" | "rect" | "poly" | "ellipse" | "default";
+
+export interface Point {
+  readonly x: number;
+  readonly y: number;
+}
+
+/** Parse a QTI coords attribute ("10,20,30") into numbers. */
+export function parseCoords(coords: string): number[] {
+  return coords
+    .split(",")
+    .map((entry) => Number(entry.trim()))
+    .filter((value) => !Number.isNaN(value));
+}
+
+/** Parse a QTI point value ("x y") or null when malformed. */
+export function parsePoint(value: string): Point | null {
+  const [x, y, ...rest] = value.trim().split(/\s+/u).map(Number);
+
+  if (x === undefined || y === undefined || rest.length > 0 || Number.isNaN(x) || Number.isNaN(y)) {
+    return null;
+  }
+
+  return { x, y };
+}
+
+export function formatPoint(point: Point): string {
+  return `${point.x} ${point.y}`;
+}
+
+function pointInPolygon(coords: readonly number[], point: Point): boolean {
+  let inside = false;
+
+  for (let i = 0, j = coords.length - 2; i < coords.length; j = i, i += 2) {
+    const xi = coords[i]!;
+    const yi = coords[i + 1]!;
+    const xj = coords[j]!;
+    const yj = coords[j + 1]!;
+    const intersects = yi > point.y !== yj > point.y && point.x < ((xj - xi) * (point.y - yi)) / (yj - yi) + xi;
+
+    if (intersects) {
+      inside = !inside;
+    }
+  }
+
+  return inside;
+}
+
+/** QTI hit test: is `point` inside the area described by (shape, coords)? */
+export function pointInShape(shape: string, coords: readonly number[], point: Point): boolean {
+  switch (shape) {
+    case "default":
+      return true;
+
+    case "circle": {
+      const [cx, cy, r] = coords;
+
+      if (cx === undefined || cy === undefined || r === undefined) {
+        return false;
+      }
+
+      return (point.x - cx) ** 2 + (point.y - cy) ** 2 <= r ** 2;
+    }
+
+    case "rect": {
+      const [left, top, right, bottom] = coords;
+
+      if (left === undefined || top === undefined || right === undefined || bottom === undefined) {
+        return false;
+      }
+
+      return point.x >= left && point.x <= right && point.y >= top && point.y <= bottom;
+    }
+
+    case "ellipse": {
+      const [cx, cy, rx, ry] = coords;
+
+      if (cx === undefined || cy === undefined || rx === undefined || ry === undefined || rx === 0 || ry === 0) {
+        return false;
+      }
+
+      return (point.x - cx) ** 2 / rx ** 2 + (point.y - cy) ** 2 / ry ** 2 <= 1;
+    }
+
+    case "poly":
+      return coords.length >= 6 && pointInPolygon(coords, point);
+
+    default:
+      return false;
+  }
+}