@conform-ed/qti-react 0.0.12 → 0.0.14

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

@@ -0,0 +1,142 @@
+/**
+ * Shared scaffolding for the graphic Reference Skins (ADR-0001): a stage (the image
+ * with an SVG overlay in image coordinates) plus QTI shape → SVG element mapping.
+ */
+
+import { createElement, type MouseEvent, type ReactNode, type SVGProps } from "react";
+
+import type { Point } from "../graphic";
+
+export interface ObjectView {
+  data: string;
+  width?: number;
+  height?: number;
+  type?: string;
+}
+
+export interface HotspotView {
+  identifier: string;
+  shape: string;
+  coords: readonly number[];
+  matchMax?: number;
+}
+
+/** The geometric center of a shape, for badges, lines, and placed images. */
+export function shapeCenter(shape: string, coords: readonly number[]): Point {
+  switch (shape) {
+    case "circle":
+    case "ellipse":
+      return { x: coords[0] ?? 0, y: coords[1] ?? 0 };
+
+    case "rect":
+      return { x: ((coords[0] ?? 0) + (coords[2] ?? 0)) / 2, y: ((coords[1] ?? 0) + (coords[3] ?? 0)) / 2 };
+
+    case "poly": {
+      let x = 0;
+      let y = 0;
+      const pointCount = Math.floor(coords.length / 2);
+
+      for (let i = 0; i < pointCount * 2; i += 2) {
+        x += coords[i] ?? 0;
+        y += coords[i + 1] ?? 0;
+      }
+
+      return pointCount === 0 ? { x: 0, y: 0 } : { x: x / pointCount, y: y / pointCount };
+    }
+
+    default:
+      return { x: 0, y: 0 };
+  }
+}
+
+/** Extra props a shape may carry, including data-* attributes. */
+export type ShapeProps = SVGProps<SVGElement> & { [dataAttribute: `data-${string}`]: string | number | boolean };
+
+/** Map a QTI (shape, coords) to an SVG element with the given extra props. */
+export function shapeElement(shape: string, coords: readonly number[], key: string, props: ShapeProps): ReactNode {
+  const base = { key, fill: "transparent", stroke: "currentColor", strokeWidth: 1, ...props };
+
+  switch (shape) {
+    case "circle":
+      return createElement("circle", { ...base, cx: coords[0], cy: coords[1], r: coords[2] });
+
+    case "rect":
+      return createElement("rect", {
+        ...base,
+        x: coords[0],
+        y: coords[1],
+        width: (coords[2] ?? 0) - (coords[0] ?? 0),
+        height: (coords[3] ?? 0) - (coords[1] ?? 0),
+      });
+
+    case "ellipse":
+      return createElement("ellipse", { ...base, cx: coords[0], cy: coords[1], rx: coords[2], ry: coords[3] });
+
+    case "poly": {
+      const points: string[] = [];
+
+      for (let i = 0; i + 1 < coords.length; i += 2) {
+        points.push(`${coords[i]},${coords[i + 1]}`);
+      }
+
+      return createElement("polygon", { ...base, points: points.join(" ") });
+    }
+
+    default:
+      // `default` (whole image) renders as a full-stage rect; the stage passes 100%.
+      return createElement("rect", { ...base, x: 0, y: 0, width: "100%", height: "100%" });
+  }
+}
+
+export interface GraphicStageProps {
+  object: ObjectView;
+  resolveAsset: (href: string) => string;
+  interaction: string;
+  status: string;
+  /** Stage click in image coordinates (from the SVG overlay). */
+  onStageClick?: (point: Point) => void;
+  prompt?: ReactNode;
+  overlay?: ReactNode;
+  after?: ReactNode;
+}
+
+/** The image + coordinate-space SVG overlay every graphic interaction shares. */
+export function GraphicStage(props: GraphicStageProps): ReactNode {
+  const width = props.object.width ?? 0;
+  const height = props.object.height ?? 0;
+
+  return createElement(
+    "div",
+    { "data-qti-interaction": props.interaction, "data-status": props.status },
+    props.prompt,
+    createElement(
+      "div",
+      { style: { position: "relative", display: "inline-block", lineHeight: 0 } },
+      createElement("img", {
+        src: props.resolveAsset(props.object.data),
+        width: width || undefined,
+        height: height || undefined,
+        alt: "",
+      }),
+      createElement(
+        "svg",
+        {
+          viewBox: `0 0 ${width || 100} ${height || 100}`,
+          width: width || undefined,
+          height: height || undefined,
+          style: { position: "absolute", inset: 0 },
+          onClick: props.onStageClick
+            ? (event: MouseEvent<SVGSVGElement>) => {
+                props.onStageClick?.({
+                  x: Math.round(event.nativeEvent.offsetX),
+                  y: Math.round(event.nativeEvent.offsetY),
+                });
+              }
+            : undefined,
+        },
+        props.overlay,
+      ),
+    ),
+    props.after,
+  );
+}

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

@@ -0,0 +1,143 @@
+/**
+ * Reference Skin for `graphicGapMatchInteraction` (ADR-0001): pick a gap image from
+ * the tray, then click a hotspot to place it — no drag-and-drop. Placed images draw
+ * at the hotspot center; responses are directedPairs gapImg→hotspot.
+ */
+
+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 GapImgView {
+  identifier: string;
+  object?: ObjectView;
+  /** Plain-text tray label for gapText choices (no image). */
+  label?: string;
+  matchMax?: number;
+}
+
+interface GraphicGapMatchNodeView {
+  prompt?: { content?: readonly BodyNode[] };
+  object?: ObjectView;
+  gapImgs?: readonly GapImgView[];
+  associableHotspots?: readonly HotspotView[];
+}
+
+export function GraphicGapMatchReferenceSkin(props: InteractionRenderProps): ReactNode {
+  const node = props.node as unknown as GraphicGapMatchNodeView;
+  const pairs = Array.isArray(props.value) ? [...props.value] : [];
+  // Ephemeral tray selection only; the response itself lives in the core store.
+  const [selectedGapImg, setSelectedGapImg] = useState<string | null>(null);
+  const gapImgs = node.gapImgs ?? [];
+  const gapImgsById = new Map(gapImgs.map((gapImg) => [gapImg.identifier, gapImg]));
+
+  if (!node.object) {
+    return null;
+  }
+
+  function placedIn(hotspotIdentifier: string): string | null {
+    const pair = pairs.find((entry) => entry.split(/\s+/u)[1] === hotspotIdentifier);
+
+    return pair?.split(/\s+/u)[0] ?? null;
+  }
+
+  function clickHotspot(hotspotIdentifier: string): void {
+    if (props.disabled) {
+      return;
+    }
+
+    const kept = pairs.filter((entry) => entry.split(/\s+/u)[1] !== hotspotIdentifier);
+
+    if (selectedGapImg === null) {
+      // No tray selection: clicking a filled hotspot clears it.
+      if (kept.length !== pairs.length) {
+        props.setValue(kept.length === 0 ? null : kept);
+      }
+
+      return;
+    }
+
+    props.setValue([...kept, `${selectedGapImg} ${hotspotIdentifier}`]);
+    setSelectedGapImg(null);
+  }
+
+  return createElement(GraphicStage, {
+    object: node.object,
+    resolveAsset: props.resolveAsset,
+    interaction: "graphicGapMatchInteraction",
+    status: props.status,
+    prompt: createElement(
+      Fragment,
+      null,
+      node.prompt ? createElement("div", { "data-qti-prompt": true }, props.renderContent(node.prompt.content)) : null,
+      createElement(
+        "div",
+        { role: "group", "aria-label": "Gap images" },
+        gapImgs.map((gapImg) =>
+          createElement(
+            "button",
+            {
+              key: gapImg.identifier,
+              type: "button",
+              disabled: props.disabled,
+              "aria-pressed": selectedGapImg === gapImg.identifier,
+              "data-status": selectedGapImg === gapImg.identifier ? "selected" : "idle",
+              "data-qti-gap-img": gapImg.identifier,
+              onClick: () => setSelectedGapImg(selectedGapImg === gapImg.identifier ? null : gapImg.identifier),
+            },
+            gapImg.object
+              ? createElement("img", {
+                  src: props.resolveAsset(gapImg.object.data),
+                  width: gapImg.object.width,
+                  height: gapImg.object.height,
+                  alt: gapImg.identifier,
+                })
+              : (gapImg.label ?? gapImg.identifier),
+          ),
+        ),
+      ),
+    ),
+    overlay: (node.associableHotspots ?? []).map((hotspot) => {
+      const placed = placedIn(hotspot.identifier);
+      const placedEntry = placed === null ? undefined : gapImgsById.get(placed);
+      const placedObject = placedEntry?.object;
+      const center = shapeCenter(hotspot.shape, hotspot.coords);
+
+      return createElement(
+        Fragment,
+        { key: hotspot.identifier },
+        shapeElement(hotspot.shape, hotspot.coords, `${hotspot.identifier}-shape`, {
+          role: "button",
+          tabIndex: 0,
+          "aria-label": `${hotspot.identifier}${placed === null ? "" : `, contains ${placed}`}`,
+          "data-status": placed === null ? "idle" : "selected",
+          onClick: () => clickHotspot(hotspot.identifier),
+          style: { cursor: props.disabled ? "default" : "pointer" },
+        }),
+        placedObject
+          ? createElement("image", {
+              href: props.resolveAsset(placedObject.data),
+              x: center.x - (placedObject.width ?? 0) / 2,
+              y: center.y - (placedObject.height ?? 0) / 2,
+              width: placedObject.width,
+              height: placedObject.height,
+              style: { pointerEvents: "none" },
+            })
+          : placedEntry
+            ? createElement(
+                "text",
+                {
+                  x: center.x,
+                  y: center.y,
+                  textAnchor: "middle",
+                  dominantBaseline: "middle",
+                  style: { pointerEvents: "none" },
+                },
+                placedEntry.label ?? placedEntry.identifier,
+              )
+            : null,
+      );
+    }),
+  });
+}

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

@@ -0,0 +1,76 @@
+/**
+ * Reference Skin for `graphicOrderInteraction` (ADR-0001): click hotspots in sequence;
+ * each selected hotspot shows its position badge. Clicking a selected hotspot removes
+ * it (and renumbers the rest).
+ */
+
+import { Fragment, createElement, type ReactNode } from "react";
+
+import type { BodyNode, InteractionRenderProps } from "../runtime";
+import { GraphicStage, shapeCenter, shapeElement, type HotspotView, type ObjectView } from "./graphic-base";
+
+interface GraphicOrderNodeView {
+  prompt?: { content?: readonly BodyNode[] };
+  object?: ObjectView;
+  hotspotChoices?: readonly HotspotView[];
+}
+
+export function GraphicOrderReferenceSkin(props: InteractionRenderProps): ReactNode {
+  const node = props.node as unknown as GraphicOrderNodeView;
+  const order = Array.isArray(props.value) ? [...props.value] : [];
+
+  if (!node.object) {
+    return null;
+  }
+
+  function toggle(identifier: string): void {
+    if (props.disabled) {
+      return;
+    }
+
+    const next = order.includes(identifier) ? order.filter((entry) => entry !== identifier) : [...order, identifier];
+
+    props.setValue(next.length === 0 ? null : next);
+  }
+
+  return createElement(GraphicStage, {
+    object: node.object,
+    resolveAsset: props.resolveAsset,
+    interaction: "graphicOrderInteraction",
+    status: props.status,
+    prompt: node.prompt
+      ? createElement("div", { "data-qti-prompt": true }, props.renderContent(node.prompt.content))
+      : null,
+    overlay: (node.hotspotChoices ?? []).map((hotspot) => {
+      const position = order.indexOf(hotspot.identifier);
+      const center = shapeCenter(hotspot.shape, hotspot.coords);
+
+      return createElement(
+        Fragment,
+        { key: hotspot.identifier },
+        shapeElement(hotspot.shape, hotspot.coords, `${hotspot.identifier}-shape`, {
+          role: "button",
+          tabIndex: 0,
+          "aria-label": `${hotspot.identifier}${position === -1 ? "" : `, position ${position + 1}`}`,
+          "data-status": position === -1 ? "idle" : "selected",
+          onClick: () => toggle(hotspot.identifier),
+          style: { cursor: props.disabled ? "default" : "pointer" },
+        }),
+        position === -1
+          ? null
+          : createElement(
+              "text",
+              {
+                x: center.x,
+                y: center.y,
+                textAnchor: "middle",
+                dominantBaseline: "central",
+                "data-qti-order-badge": hotspot.identifier,
+                style: { pointerEvents: "none" },
+              },
+              String(position + 1),
+            ),
+      );
+    }),
+  });
+}

package/src/reference-skin/hotspot.ts

@@ -0,0 +1,43 @@
+/**
+ * Reference Skin for `hotspotInteraction` (ADR-0001): SVG hotspot shapes over the
+ * stage image, wired through the option prop-getters (selection semantics identical
+ * to choiceInteraction).
+ */
+
+import { createElement, type ReactNode } from "react";
+
+import type { BodyNode, InteractionRenderProps } from "../runtime";
+import { GraphicStage, shapeElement, type HotspotView, type ObjectView } from "./graphic-base";
+
+interface HotspotNodeView {
+  prompt?: { content?: readonly BodyNode[] };
+  object?: ObjectView;
+  hotspotChoices?: readonly HotspotView[];
+}
+
+export function HotspotReferenceSkin(props: InteractionRenderProps): ReactNode {
+  const node = props.node as unknown as HotspotNodeView;
+
+  if (!node.object) {
+    return null;
+  }
+
+  return createElement(GraphicStage, {
+    object: node.object,
+    resolveAsset: props.resolveAsset,
+    interaction: "hotspotInteraction",
+    status: props.status,
+    prompt: node.prompt
+      ? createElement("div", { "data-qti-prompt": true }, props.renderContent(node.prompt.content))
+      : null,
+    overlay: (node.hotspotChoices ?? []).map((hotspot) => {
+      const optionProps = props.getOptionProps(hotspot.identifier);
+
+      return shapeElement(hotspot.shape, hotspot.coords, hotspot.identifier, {
+        ...optionProps,
+        "aria-label": hotspot.identifier,
+        style: { cursor: props.disabled ? "default" : "pointer" },
+      });
+    }),
+  });
+}

package/src/reference-skin/hottext.ts

@@ -0,0 +1,42 @@
+/**
+ * Reference Skin for `hottextInteraction` (ADR-0001): the interaction's flow content is
+ * rendered through the core walk with a `hottext` override, so selectable spans nested
+ * anywhere in the prose become toggle buttons wired through the option prop-getters.
+ */
+
+import { createElement, type ReactNode } from "react";
+
+import type { BodyNode, InteractionRenderProps } from "../runtime";
+
+interface HottextNodeView {
+  prompt?: { content?: readonly BodyNode[] };
+  content?: readonly BodyNode[];
+}
+
+interface HottextChildView {
+  identifier?: string;
+  content?: readonly BodyNode[];
+}
+
+export function HottextReferenceSkin(props: InteractionRenderProps): ReactNode {
+  const node = props.node as unknown as HottextNodeView;
+
+  return createElement(
+    "div",
+    { "data-qti-interaction": "hottextInteraction", "data-status": props.status },
+    node.prompt ? createElement("div", { "data-qti-prompt": true }, props.renderContent(node.prompt.content)) : null,
+    props.renderContent(node.content, {
+      hottext: (child, key) => {
+        const view = child as HottextChildView;
+        const identifier = view.identifier ?? "";
+        const optionProps = props.getOptionProps(identifier);
+
+        return createElement(
+          "button",
+          { key, type: "button", disabled: props.disabled, "data-qti-hottext": identifier, ...optionProps },
+          props.renderContent(view.content) ?? identifier,
+        );
+      },
+    }),
+  );
+}

package/src/reference-skin/index.ts

@@ -0,0 +1,74 @@
+/**
+ * The Reference Skin (ADR-0001): the unstyled, semantic-HTML, a11y-correct Skin set
+ * conform-ed ships so every interaction can be exercised, demoed, and conformance-
+ * tested without a downstream product. Deliberately not a product UI: no styling
+ * beyond data attributes (`data-qti-interaction`, `data-status`) as styling hooks.
+ */
+
+import type { SkinRegistry } from "../runtime";
+import { AssociateReferenceSkin } from "./associate";
+import { ChoiceReferenceSkin } from "./choice";
+import { DrawingReferenceSkin } from "./drawing";
+import { EndAttemptReferenceSkin } from "./end-attempt";
+import { ExtendedTextReferenceSkin } from "./extended-text";
+import { GapMatchReferenceSkin } from "./gap-match";
+import { GraphicAssociateReferenceSkin } from "./graphic-associate";
+import { GraphicGapMatchReferenceSkin } from "./graphic-gap-match";
+import { GraphicOrderReferenceSkin } from "./graphic-order";
+import { HotspotReferenceSkin } from "./hotspot";
+import { HottextReferenceSkin } from "./hottext";
+import { InlineChoiceReferenceSkin } from "./inline-choice";
+import { MatchReferenceSkin } from "./match";
+import { MediaReferenceSkin } from "./media";
+import { OrderReferenceSkin } from "./order";
+import { PositionObjectReferenceSkin } from "./position-object";
+import { SelectPointReferenceSkin } from "./select-point";
+import { SliderReferenceSkin } from "./slider";
+import { TextEntryReferenceSkin } from "./text-entry";
+import { UploadReferenceSkin } from "./upload";
+
+export { textOf } from "./content";
+export { AssociateReferenceSkin } from "./associate";
+export { ChoiceReferenceSkin } from "./choice";
+export { DrawingReferenceSkin } from "./drawing";
+export { EndAttemptReferenceSkin } from "./end-attempt";
+export { ExtendedTextReferenceSkin } from "./extended-text";
+export { GapMatchReferenceSkin } from "./gap-match";
+export { GraphicAssociateReferenceSkin } from "./graphic-associate";
+export { GraphicGapMatchReferenceSkin } from "./graphic-gap-match";
+export { GraphicOrderReferenceSkin } from "./graphic-order";
+export { GraphicStage, shapeCenter, shapeElement } from "./graphic-base";
+export { HotspotReferenceSkin } from "./hotspot";
+export { PositionObjectReferenceSkin } from "./position-object";
+export { SelectPointReferenceSkin } from "./select-point";
+export { HottextReferenceSkin } from "./hottext";
+export { InlineChoiceReferenceSkin } from "./inline-choice";
+export { MatchReferenceSkin } from "./match";
+export { MediaReferenceSkin } from "./media";
+export { OrderReferenceSkin } from "./order";
+export { SliderReferenceSkin } from "./slider";
+export { TextEntryReferenceSkin } from "./text-entry";
+export { UploadReferenceSkin } from "./upload";
+
+export const referenceSkin: SkinRegistry = {
+  associateInteraction: AssociateReferenceSkin,
+  choiceInteraction: ChoiceReferenceSkin,
+  drawingInteraction: DrawingReferenceSkin,
+  endAttemptInteraction: EndAttemptReferenceSkin,
+  extendedTextInteraction: ExtendedTextReferenceSkin,
+  gapMatchInteraction: GapMatchReferenceSkin,
+  graphicAssociateInteraction: GraphicAssociateReferenceSkin,
+  graphicGapMatchInteraction: GraphicGapMatchReferenceSkin,
+  graphicOrderInteraction: GraphicOrderReferenceSkin,
+  hotspotInteraction: HotspotReferenceSkin,
+  hottextInteraction: HottextReferenceSkin,
+  inlineChoiceInteraction: InlineChoiceReferenceSkin,
+  matchInteraction: MatchReferenceSkin,
+  mediaInteraction: MediaReferenceSkin,
+  orderInteraction: OrderReferenceSkin,
+  positionObjectStage: PositionObjectReferenceSkin,
+  selectPointInteraction: SelectPointReferenceSkin,
+  sliderInteraction: SliderReferenceSkin,
+  textEntryInteraction: TextEntryReferenceSkin,
+  uploadInteraction: UploadReferenceSkin,
+};

package/src/reference-skin/inline-choice.ts

@@ -0,0 +1,42 @@
+/**
+ * Reference Skin for `inlineChoiceInteraction` (ADR-0001): a controlled native select.
+ * Option labels must be text, so choice content goes through plain-text extraction.
+ */
+
+import { createElement, type ChangeEvent, type ReactNode } from "react";
+
+import type { BodyNode, InteractionRenderProps } from "../runtime";
+import { textOf } from "./content";
+
+interface InlineChoiceView {
+  identifier: string;
+  content?: readonly BodyNode[];
+}
+
+interface InlineChoiceNodeView {
+  inlineChoices?: readonly InlineChoiceView[];
+}
+
+export function InlineChoiceReferenceSkin(props: InteractionRenderProps): ReactNode {
+  const node = props.node as unknown as InlineChoiceNodeView;
+  const choices = node.inlineChoices ?? [];
+  const value = typeof props.value === "string" ? props.value : "";
+
+  return createElement(
+    "select",
+    {
+      value,
+      disabled: props.disabled,
+      "aria-disabled": props.disabled,
+      "data-qti-interaction": "inlineChoiceInteraction",
+      "data-status": props.status,
+      onChange: (event: ChangeEvent<HTMLSelectElement>) => {
+        props.setValue(event.target.value === "" ? null : event.target.value);
+      },
+    },
+    createElement("option", { key: "", value: "" }, ""),
+    choices.map((choice) =>
+      createElement("option", { key: choice.identifier, value: choice.identifier }, textOf(choice.content)),
+    ),
+  );
+}

package/src/reference-skin/match.ts

@@ -0,0 +1,80 @@
+/**
+ * Reference Skin for `matchInteraction` (ADR-0001): a table grid — rows are the first
+ * match set, columns the second; each cell is a checkbox toggling the directedPair
+ * "ROW COL". Conservative and screen-reader friendly; no drag-and-drop.
+ */
+
+import { createElement, type ReactNode } from "react";
+
+import type { BodyNode, InteractionRenderProps } from "../runtime";
+import { textOf } from "./content";
+
+interface AssociableChoiceView {
+  identifier: string;
+  content?: readonly BodyNode[];
+}
+
+interface MatchNodeView {
+  prompt?: { content?: readonly BodyNode[] };
+  simpleMatchSets?: ReadonlyArray<{ simpleAssociableChoices?: readonly AssociableChoiceView[] }>;
+}
+
+export function MatchReferenceSkin(props: InteractionRenderProps): ReactNode {
+  const node = props.node as unknown as MatchNodeView;
+  const rows = node.simpleMatchSets?.[0]?.simpleAssociableChoices ?? [];
+  const columns = node.simpleMatchSets?.[1]?.simpleAssociableChoices ?? [];
+  const pairs = Array.isArray(props.value) ? props.value : [];
+
+  function togglePair(pair: string): void {
+    props.setValue(pairs.includes(pair) ? pairs.filter((entry) => entry !== pair) : [...pairs, pair]);
+  }
+
+  return createElement(
+    "div",
+    { "data-qti-interaction": "matchInteraction", "data-status": props.status },
+    node.prompt ? createElement("div", { "data-qti-prompt": true }, props.renderContent(node.prompt.content)) : null,
+    createElement(
+      "table",
+      null,
+      createElement(
+        "thead",
+        null,
+        createElement(
+          "tr",
+          null,
+          createElement("td", null),
+          columns.map((column) =>
+            createElement("th", { key: column.identifier, scope: "col" }, textOf(column.content) || column.identifier),
+          ),
+        ),
+      ),
+      createElement(
+        "tbody",
+        null,
+        rows.map((row) =>
+          createElement(
+            "tr",
+            { key: row.identifier },
+            createElement("th", { scope: "row" }, textOf(row.content) || row.identifier),
+            columns.map((column) => {
+              const pair = `${row.identifier} ${column.identifier}`;
+
+              return createElement(
+                "td",
+                { key: column.identifier },
+                createElement("input", {
+                  type: "checkbox",
+                  checked: pairs.includes(pair),
+                  disabled: props.disabled,
+                  "aria-label": `${textOf(row.content) || row.identifier} — ${textOf(column.content) || column.identifier}`,
+                  "data-qti-pair": pair,
+                  onChange: () => togglePair(pair),
+                }),
+              );
+            }),
+          ),
+        ),
+      ),
+    ),
+  );
+}