@conform-ed/qti-react 0.0.12 → 0.0.14

package/src/reference-skin/associate.ts

@@ -0,0 +1,98 @@
+/**
+ * Reference Skin for `associateInteraction` (ADR-0001): a pair builder — two selects
+ * over the same choice set, an "Add pair" button, and a removable list of the pairs
+ * built so far. Pairs are unordered (`pair` baseType); scoring handles reversal.
+ */
+
+import { createElement, useState, type ChangeEvent, type ReactNode } from "react";
+
+import type { BodyNode, InteractionRenderProps } from "../runtime";
+import { textOf } from "./content";
+
+interface AssociableChoiceView {
+  identifier: string;
+  content?: readonly BodyNode[];
+}
+
+interface AssociateNodeView {
+  prompt?: { content?: readonly BodyNode[] };
+  simpleAssociableChoices?: readonly AssociableChoiceView[];
+}
+
+export function AssociateReferenceSkin(props: InteractionRenderProps): ReactNode {
+  const node = props.node as unknown as AssociateNodeView;
+  const choices = node.simpleAssociableChoices ?? [];
+  const pairs = Array.isArray(props.value) ? props.value : [];
+  // Ephemeral picker state only; the response itself lives in the core store.
+  const [first, setFirst] = useState("");
+  const [second, setSecond] = useState("");
+
+  function labelFor(identifier: string): string {
+    const choice = choices.find((candidate) => candidate.identifier === identifier);
+
+    return choice ? textOf(choice.content) || choice.identifier : identifier;
+  }
+
+  function addPair(): void {
+    if (first === "" || second === "" || first === second) {
+      return;
+    }
+
+    const pair = `${first} ${second}`;
+
+    if (!pairs.includes(pair) && !pairs.includes(`${second} ${first}`)) {
+      props.setValue([...pairs, pair]);
+    }
+
+    setFirst("");
+    setSecond("");
+  }
+
+  function picker(value: string, setValue: (next: string) => void, label: string): ReactNode {
+    return createElement(
+      "select",
+      {
+        value,
+        disabled: props.disabled,
+        "aria-label": label,
+        onChange: (event: ChangeEvent<HTMLSelectElement>) => setValue(event.target.value),
+      },
+      createElement("option", { key: "", value: "" }, ""),
+      choices.map((choice) =>
+        createElement("option", { key: choice.identifier, value: choice.identifier }, labelFor(choice.identifier)),
+      ),
+    );
+  }
+
+  return createElement(
+    "div",
+    { "data-qti-interaction": "associateInteraction", "data-status": props.status },
+    node.prompt ? createElement("div", { "data-qti-prompt": true }, props.renderContent(node.prompt.content)) : null,
+    picker(first, setFirst, "First member"),
+    picker(second, setSecond, "Second member"),
+    createElement("button", { type: "button", disabled: props.disabled, onClick: addPair }, "Add pair"),
+    createElement(
+      "ul",
+      null,
+      pairs.map((pair) => {
+        const [a, b] = pair.split(/\s+/u);
+
+        return createElement(
+          "li",
+          { key: pair, "data-qti-pair": pair },
+          `${labelFor(a ?? "")} ↔ ${labelFor(b ?? "")} `,
+          createElement(
+            "button",
+            {
+              type: "button",
+              disabled: props.disabled,
+              "aria-label": `Remove pair ${pair}`,
+              onClick: () => props.setValue(pairs.filter((entry) => entry !== pair)),
+            },
+            "×",
+          ),
+        );
+      }),
+    ),
+  );
+}

package/src/reference-skin/choice.ts

@@ -0,0 +1,44 @@
+/**
+ * Reference Skin for `choiceInteraction` (ADR-0001): unstyled, semantic, a11y-correct.
+ * Native `<button>` elements carry the option prop-getters so Space/Enter activation is
+ * free; all visual state is exposed as data attributes for downstream styling.
+ */
+
+import { createElement, type ReactNode } from "react";
+
+import type { BodyNode, InteractionRenderProps } from "../runtime";
+
+interface SimpleChoiceView {
+  identifier: string;
+  content?: readonly BodyNode[];
+}
+
+interface ChoiceNodeView {
+  prompt?: { content?: readonly BodyNode[] };
+  simpleChoices?: readonly SimpleChoiceView[];
+}
+
+export function ChoiceReferenceSkin(props: InteractionRenderProps): ReactNode {
+  const node = props.node as unknown as ChoiceNodeView;
+  const choices = node.simpleChoices ?? [];
+  const isRadio = choices.length > 0 && props.getOptionProps(choices[0]!.identifier).role === "radio";
+
+  return createElement(
+    "div",
+    {
+      role: isRadio ? "radiogroup" : "group",
+      "data-qti-interaction": "choiceInteraction",
+      "data-status": props.status,
+    },
+    node.prompt ? createElement("div", { "data-qti-prompt": true }, props.renderContent(node.prompt.content)) : null,
+    choices.map((choice) => {
+      const optionProps = props.getOptionProps(choice.identifier);
+
+      return createElement(
+        "button",
+        { key: choice.identifier, type: "button", disabled: props.disabled, ...optionProps },
+        props.renderContent(choice.content) ?? choice.identifier,
+      );
+    }),
+  );
+}

package/src/reference-skin/content.ts

@@ -0,0 +1,30 @@
+/**
+ * Plain-text extraction for places where the DOM only accepts text (e.g. `<option>`
+ * children). Walks a BodyNode fragment and concatenates its text values.
+ */
+
+import type { BodyNode } from "../runtime";
+
+export function textOf(nodes: readonly BodyNode[] | undefined): string {
+  if (!nodes) {
+    return "";
+  }
+
+  let text = "";
+
+  for (const node of nodes) {
+    const value = (node as { value?: string }).value;
+
+    if (typeof value === "string") {
+      text += value;
+    }
+
+    const children = (node as { children?: readonly BodyNode[] }).children;
+
+    if (children) {
+      text += textOf(children);
+    }
+  }
+
+  return text;
+}

package/src/reference-skin/drawing.ts

@@ -0,0 +1,160 @@
+/**
+ * Reference Skin for `drawingInteraction` (ADR-0001): a canvas drawing surface over
+ * the stage image. The candidate draws freehand strokes with the pointer; the result
+ * is captured as a PNG data URL into the `file` response (the upload convention).
+ * Items using drawing are typically scored externally, not by client RP.
+ */
+
+import {
+  createElement,
+  useCallback,
+  useEffect,
+  useRef,
+  type PointerEvent as ReactPointerEvent,
+  type ReactNode,
+} from "react";
+
+import type { BodyNode, InteractionRenderProps } from "../runtime";
+import type { ObjectView } from "./graphic-base";
+
+interface DrawingNodeView {
+  prompt?: { content?: readonly BodyNode[] };
+  object: ObjectView;
+}
+
+const strokeStyle = "#c2410c";
+const strokeWidth = 3;
+
+export function DrawingReferenceSkin(props: InteractionRenderProps): ReactNode {
+  const node = props.node as unknown as DrawingNodeView;
+  const width = node.object.width ?? 400;
+  const height = node.object.height ?? 300;
+
+  const canvasRef = useRef<HTMLCanvasElement | null>(null);
+  const drawingRef = useRef(false);
+  const propsRef = useRef(props);
+  propsRef.current = props;
+
+  // Paint the stage image as the drawing background (and again after a clear).
+  const stageData = node.object.data;
+  const paintBackground = useCallback(
+    (canvas: HTMLCanvasElement): void => {
+      const context = canvas.getContext("2d");
+
+      if (!context) {
+        return;
+      }
+
+      context.clearRect(0, 0, canvas.width, canvas.height);
+
+      const image = new Image();
+
+      image.onload = () => {
+        context.drawImage(image, 0, 0, canvas.width, canvas.height);
+      };
+      image.src = propsRef.current.resolveAsset(stageData);
+    },
+    [stageData],
+  );
+
+  useEffect(() => {
+    if (canvasRef.current) {
+      paintBackground(canvasRef.current);
+    }
+  }, [paintBackground]);
+
+  const pointerPosition = (event: ReactPointerEvent<HTMLCanvasElement>): { x: number; y: number } => {
+    const canvas = event.currentTarget;
+    const rect = canvas.getBoundingClientRect();
+
+    return {
+      x: ((event.clientX - rect.left) / rect.width) * canvas.width,
+      y: ((event.clientY - rect.top) / rect.height) * canvas.height,
+    };
+  };
+
+  const handlePointerDown = (event: ReactPointerEvent<HTMLCanvasElement>): void => {
+    if (props.disabled) {
+      return;
+    }
+
+    const context = event.currentTarget.getContext("2d");
+
+    if (!context) {
+      return;
+    }
+
+    drawingRef.current = true;
+    event.currentTarget.setPointerCapture(event.pointerId);
+
+    const { x, y } = pointerPosition(event);
+
+    context.strokeStyle = strokeStyle;
+    context.lineWidth = strokeWidth;
+    context.lineCap = "round";
+    context.beginPath();
+    context.moveTo(x, y);
+  };
+
+  const handlePointerMove = (event: ReactPointerEvent<HTMLCanvasElement>): void => {
+    if (!drawingRef.current) {
+      return;
+    }
+
+    const context = event.currentTarget.getContext("2d");
+
+    if (!context) {
+      return;
+    }
+
+    const { x, y } = pointerPosition(event);
+
+    context.lineTo(x, y);
+    context.stroke();
+  };
+
+  const handlePointerUp = (event: ReactPointerEvent<HTMLCanvasElement>): void => {
+    if (!drawingRef.current) {
+      return;
+    }
+
+    drawingRef.current = false;
+    // The committed response is the canvas content as a PNG data URL (file base type).
+    props.setValue(event.currentTarget.toDataURL("image/png"));
+  };
+
+  const handleClear = (): void => {
+    if (props.disabled) {
+      return;
+    }
+
+    props.setValue(null);
+
+    if (canvasRef.current) {
+      paintBackground(canvasRef.current);
+    }
+  };
+
+  return createElement(
+    "div",
+    { "data-qti-interaction": "drawingInteraction", "data-status": props.status },
+    node.prompt ? createElement("div", { "data-qti-prompt": true }, props.renderContent(node.prompt.content)) : null,
+    createElement("canvas", {
+      ref: canvasRef,
+      width,
+      height,
+      role: "img",
+      "aria-label": "Drawing surface",
+      "data-qti-drawing-stage": "",
+      style: { touchAction: "none", border: "1px solid #d1d5db", maxWidth: "100%" },
+      onPointerDown: handlePointerDown,
+      onPointerMove: handlePointerMove,
+      onPointerUp: handlePointerUp,
+    }),
+    createElement(
+      "button",
+      { type: "button", onClick: handleClear, disabled: props.disabled, "aria-disabled": props.disabled },
+      "Clear",
+    ),
+  );
+}

package/src/reference-skin/end-attempt.ts

@@ -0,0 +1,27 @@
+/**
+ * Reference Skin for `endAttemptInteraction` (ADR-0001): a titled button that sets its
+ * boolean response true and ends the current attempt (hints, give-up, adaptive moves).
+ */
+
+import { createElement, type ReactNode } from "react";
+
+import type { InteractionRenderProps } from "../runtime";
+
+interface EndAttemptNodeView {
+  title?: string;
+}
+
+export function EndAttemptReferenceSkin(props: InteractionRenderProps): ReactNode {
+  const node = props.node as unknown as EndAttemptNodeView;
+
+  return createElement(
+    "button",
+    {
+      type: "button",
+      disabled: props.disabled,
+      "data-qti-interaction": "endAttemptInteraction",
+      onClick: () => props.endAttempt(),
+    },
+    node.title ?? "End attempt",
+  );
+}

package/src/reference-skin/extended-text.ts

@@ -0,0 +1,35 @@
+/**
+ * Reference Skin for `extendedTextInteraction` (ADR-0001): a controlled textarea.
+ */
+
+import { createElement, type ChangeEvent, type ReactNode } from "react";
+
+import type { BodyNode, InteractionRenderProps } from "../runtime";
+
+interface ExtendedTextNodeView {
+  prompt?: { content?: readonly BodyNode[] };
+  expectedLength?: number;
+  expectedLines?: number;
+  placeholderText?: string;
+}
+
+export function ExtendedTextReferenceSkin(props: InteractionRenderProps): ReactNode {
+  const node = props.node as unknown as ExtendedTextNodeView;
+  const value = typeof props.value === "string" ? props.value : "";
+
+  return createElement(
+    "div",
+    { "data-qti-interaction": "extendedTextInteraction", "data-status": props.status },
+    node.prompt ? createElement("div", { "data-qti-prompt": true }, props.renderContent(node.prompt.content)) : null,
+    createElement("textarea", {
+      value,
+      rows: node.expectedLines ?? 4,
+      placeholder: node.placeholderText,
+      disabled: props.disabled,
+      "aria-disabled": props.disabled,
+      onChange: (event: ChangeEvent<HTMLTextAreaElement>) => {
+        props.setValue(event.target.value === "" ? null : event.target.value);
+      },
+    }),
+  );
+}

package/src/reference-skin/gap-match.ts

@@ -0,0 +1,69 @@
+/**
+ * Reference Skin for `gapMatchInteraction` (ADR-0001): the interaction's flow content
+ * renders through the core walk with a `gap` override — each gap becomes a select over
+ * the gap texts. Choosing a gap text records the directedPair "GAPTEXT GAP".
+ */
+
+import { createElement, type ChangeEvent, type ReactNode } from "react";
+
+import type { BodyNode, InteractionRenderProps } from "../runtime";
+import { textOf } from "./content";
+
+interface GapTextView {
+  identifier: string;
+  content?: readonly BodyNode[];
+}
+
+interface GapMatchNodeView {
+  prompt?: { content?: readonly BodyNode[] };
+  gapTexts?: readonly GapTextView[];
+  content?: readonly BodyNode[];
+}
+
+interface GapChildView {
+  identifier?: string;
+}
+
+export function GapMatchReferenceSkin(props: InteractionRenderProps): ReactNode {
+  const node = props.node as unknown as GapMatchNodeView;
+  const gapTexts = node.gapTexts ?? [];
+  const pairs = Array.isArray(props.value) ? props.value : [];
+
+  function fillGap(gapIdentifier: string, gapTextIdentifier: string): void {
+    const kept = pairs.filter((pair) => pair.split(/\s+/u)[1] !== gapIdentifier);
+
+    props.setValue(gapTextIdentifier === "" ? kept : [...kept, `${gapTextIdentifier} ${gapIdentifier}`]);
+  }
+
+  return createElement(
+    "div",
+    { "data-qti-interaction": "gapMatchInteraction", "data-status": props.status },
+    node.prompt ? createElement("div", { "data-qti-prompt": true }, props.renderContent(node.prompt.content)) : null,
+    props.renderContent(node.content, {
+      gap: (child, key) => {
+        const gapIdentifier = (child as GapChildView).identifier ?? "";
+        const filledBy = pairs.find((pair) => pair.split(/\s+/u)[1] === gapIdentifier)?.split(/\s+/u)[0] ?? "";
+
+        return createElement(
+          "select",
+          {
+            key,
+            value: filledBy,
+            disabled: props.disabled,
+            "aria-label": `Gap ${gapIdentifier}`,
+            "data-qti-gap": gapIdentifier,
+            onChange: (event: ChangeEvent<HTMLSelectElement>) => fillGap(gapIdentifier, event.target.value),
+          },
+          createElement("option", { key: "", value: "" }, ""),
+          gapTexts.map((gapText) =>
+            createElement(
+              "option",
+              { key: gapText.identifier, value: gapText.identifier },
+              textOf(gapText.content) || gapText.identifier,
+            ),
+          ),
+        );
+      },
+    }),
+  );
+}

package/src/reference-skin/graphic-associate.ts

@@ -0,0 +1,123 @@
+/**
+ * Reference Skin for `graphicAssociateInteraction` (ADR-0001): click two hotspots to
+ * connect them; connections draw as lines and list below with remove buttons. Pairs
+ * are unordered (`pair` baseType).
+ */
+
+import { Fragment, createElement, useState, type ReactNode } from "react";
+
+import type { BodyNode, InteractionRenderProps } from "../runtime";
+import { GraphicStage, shapeCenter, shapeElement, type HotspotView, type ObjectView } from "./graphic-base";
+
+interface GraphicAssociateNodeView {
+  prompt?: { content?: readonly BodyNode[] };
+  object?: ObjectView;
+  associableHotspots?: readonly HotspotView[];
+}
+
+export function GraphicAssociateReferenceSkin(props: InteractionRenderProps): ReactNode {
+  const node = props.node as unknown as GraphicAssociateNodeView;
+  const pairs = Array.isArray(props.value) ? [...props.value] : [];
+  // Ephemeral picker state only; the response itself lives in the core store.
+  const [pending, setPending] = useState<string | null>(null);
+  const hotspots = node.associableHotspots ?? [];
+  const centersById = new Map(
+    hotspots.map((hotspot) => [hotspot.identifier, shapeCenter(hotspot.shape, hotspot.coords)]),
+  );
+
+  if (!node.object) {
+    return null;
+  }
+
+  function clickHotspot(identifier: string): void {
+    if (props.disabled) {
+      return;
+    }
+
+    if (pending === null) {
+      setPending(identifier);
+      return;
+    }
+
+    if (pending === identifier) {
+      setPending(null);
+      return;
+    }
+
+    const pair = `${pending} ${identifier}`;
+    const reversed = `${identifier} ${pending}`;
+
+    if (!pairs.includes(pair) && !pairs.includes(reversed)) {
+      props.setValue([...pairs, pair]);
+    }
+
+    setPending(null);
+  }
+
+  return createElement(GraphicStage, {
+    object: node.object,
+    resolveAsset: props.resolveAsset,
+    interaction: "graphicAssociateInteraction",
+    status: props.status,
+    prompt: node.prompt
+      ? createElement("div", { "data-qti-prompt": true }, props.renderContent(node.prompt.content))
+      : null,
+    overlay: createElement(
+      Fragment,
+      null,
+      pairs.map((pair) => {
+        const [a, b] = pair.split(/\s+/u);
+        const from = centersById.get(a ?? "");
+        const to = centersById.get(b ?? "");
+
+        if (!from || !to) {
+          return null;
+        }
+
+        return createElement("line", {
+          key: pair,
+          x1: from.x,
+          y1: from.y,
+          x2: to.x,
+          y2: to.y,
+          stroke: "currentColor",
+          strokeWidth: 2,
+          "data-qti-pair": pair,
+          style: { pointerEvents: "none" },
+        });
+      }),
+      hotspots.map((hotspot) =>
+        shapeElement(hotspot.shape, hotspot.coords, hotspot.identifier, {
+          role: "button",
+          tabIndex: 0,
+          "aria-label": hotspot.identifier,
+          "aria-pressed": pending === hotspot.identifier,
+          "data-status": pending === hotspot.identifier ? "selected" : "idle",
+          onClick: () => clickHotspot(hotspot.identifier),
+          style: { cursor: props.disabled ? "default" : "pointer" },
+        }),
+      ),
+    ),
+    after: createElement(
+      "ul",
+      null,
+      pairs.map((pair) =>
+        createElement(
+          "li",
+          { key: pair },
+          pair.replace(/\s+/u, " ↔ "),
+          createElement(
+            "button",
+            {
+              type: "button",
+              disabled: props.disabled,
+              "aria-label": `Remove association ${pair}`,
+              onClick: () => props.setValue(pairs.filter((entry) => entry !== pair)),
+            },
+            "×",
+          ),
+        ),
+      ),
+    ),
+  });
+}