@hydralms/components 0.1.3 → 0.2.0

package/src/questions/question-renderer.tsx

@@ -4,6 +4,13 @@ import { Choice } from "./choice";
 import { TrueFalse } from "./true-false";
 import { FillInTheBlank } from "./fill-in-the-blank";
 import { Essay } from "./essay";
+import { Numeric } from "./numeric";
+import { Ordering } from "./ordering";
+import { Matching } from "./matching";
+import { Hotspot } from "./hotspot";
+import { InlineChoice } from "./inline-choice";
+import { Scenario } from "./scenario";
+import { Spreadsheet } from "./spreadsheet";
 
 /**
  * QuestionRenderer dispatches to the appropriate question component based on question type.
@@ -27,6 +34,20 @@ export const QuestionRenderer = (props: QuestionProps) => {
       return <FillInTheBlank {...props} />;
     case "essay":
       return <Essay {...props} />;
+    case "numeric":
+      return <Numeric {...props} />;
+    case "ordering":
+      return <Ordering {...props} />;
+    case "matching":
+      return <Matching {...props} />;
+    case "hotspot":
+      return <Hotspot {...props} />;
+    case "inline_choice":
+      return <InlineChoice {...props} />;
+    case "scenario":
+      return <Scenario {...props} />;
+    case "spreadsheet":
+      return <Spreadsheet {...props} />;
     default:
       return (
         <p className="text-muted-foreground">

package/src/questions/scenario.tsx

@@ -0,0 +1,140 @@
+import { useMemo, useRef } from "react";
+import { Alert, AlertDescription } from "../ui/alert";
+import { Separator } from "../ui/separator";
+import { cn } from "../lib/utils";
+import { QuestionRenderer } from "./question-renderer";
+import type { QuestionProps, SessionAnswer } from "./types";
+
+/**
+ * Scenario renders a shared context/stimulus with multiple sub-questions.
+ *
+ * Sub-questions can be any existing question type (choice, numeric, matching, etc.).
+ * The shared context is displayed prominently above all sub-questions.
+ *
+ * @example
+ * <Scenario
+ *   question={{
+ *     uid: "s1",
+ *     type: "scenario",
+ *     content: "<p>Read the following passage and answer the questions below.</p>",
+ *     scenarioQuestions: [
+ *       { uid: "sq1", type: "choice", content: "What is the main idea?", answers: [...] },
+ *       { uid: "sq2", type: "true_false", content: "The author agrees.", answers: [...] },
+ *     ],
+ *     scenarioScoringMode: "per_question",
+ *   }}
+ *   onAnswer={(answers) => handleAnswer(answers)}
+ * />
+ */
+export const Scenario = ({
+  question,
+  sessionAnswers,
+  onAnswer,
+  readOnly = false,
+  showCorrectAnswers = false,
+  disabled = false,
+}: QuestionProps) => {
+  const subQuestions = question.scenarioQuestions ?? [];
+
+  // Track the latest answers from each sub-question in a ref so
+  // handleSubAnswer always merges against the freshest state.
+  const latestBySubQ = useRef<Map<string, { uid: string; content?: string }[]>>(
+    new Map(),
+  );
+
+  // Parse session answers into per-sub-question groups.
+  // SessionAnswer.answerUid format: "subQUid::originalAnswerUid"
+  const answersBySubQ = useMemo(() => {
+    const map = new Map<string, SessionAnswer[]>();
+    for (const sa of sessionAnswers ?? []) {
+      const sepIdx = sa.answerUid.indexOf("::");
+      if (sepIdx === -1) continue;
+      const subQUid = sa.answerUid.slice(0, sepIdx);
+      const originalAnswerUid = sa.answerUid.slice(sepIdx + 2);
+      const list = map.get(subQUid) ?? [];
+      list.push({ ...sa, uid: subQUid, answerUid: originalAnswerUid });
+      map.set(subQUid, list);
+    }
+
+    // Sync the ref with what we parsed from props
+    latestBySubQ.current = new Map();
+    for (const [subQUid, answers] of map) {
+      latestBySubQ.current.set(
+        subQUid,
+        answers.map((a) => ({ uid: `${subQUid}::${a.answerUid}`, content: a.content })),
+      );
+    }
+
+    return map;
+  }, [sessionAnswers]);
+
+  const handleSubAnswer = (
+    subQuestionUid: string,
+    rawAnswers: { uid: string; content?: string }[],
+  ) => {
+    // Prefix each answer uid with the sub-question uid
+    const prefixed = rawAnswers.map((a) => ({
+      uid: `${subQuestionUid}::${a.uid}`,
+      content: a.content,
+    }));
+
+    // Update our ref
+    latestBySubQ.current.set(subQuestionUid, prefixed);
+
+    // Merge all sub-question answers into a single flat array
+    const merged: { uid: string; content?: string }[] = [];
+    for (const answers of latestBySubQ.current.values()) {
+      merged.push(...answers);
+    }
+
+    onAnswer?.(merged);
+  };
+
+  return (
+    <div className="flex flex-col gap-6">
+      {/* Shared context / stimulus */}
+      <div
+        className={cn(
+          "rounded-lg border border-border bg-muted/30 px-4 py-3",
+          "prose prose-sm max-w-none text-foreground",
+        )}
+      >
+        <div className="text-xs font-semibold uppercase tracking-wider text-muted-foreground mb-2">
+          Scenario
+        </div>
+        <div dangerouslySetInnerHTML={{ __html: question.content }} />
+      </div>
+
+      <Separator />
+
+      {/* Sub-questions */}
+      <div className="flex flex-col gap-5">
+        {subQuestions.map((sq, idx) => (
+          <div key={sq.uid} className="flex flex-col gap-1">
+            <span className="text-xs font-medium text-muted-foreground">
+              Part {String.fromCharCode(65 + idx)}
+            </span>
+            <QuestionRenderer
+              question={sq}
+              sessionAnswers={answersBySubQ.get(sq.uid) ?? []}
+              onAnswer={(answers) => handleSubAnswer(sq.uid, answers)}
+              readOnly={readOnly}
+              showCorrectAnswers={showCorrectAnswers}
+              disabled={disabled}
+            />
+          </div>
+        ))}
+      </div>
+
+      {/* Scenario-level explanation */}
+      {showCorrectAnswers && question.explanation && (
+        <Alert className="mt-2">
+          <AlertDescription>
+            <strong>Scenario Explanation:</strong>{" "}
+            <span dangerouslySetInnerHTML={{ __html: question.explanation }} />
+          </AlertDescription>
+        </Alert>
+      )}
+    </div>
+  );
+};

package/src/questions/scoring.ts

@@ -0,0 +1,201 @@
+import type { QuestionData, SessionAnswer } from "./types";
+
+/**
+ * Scores a single question against the user's answers.
+ *
+ * @returns `true` if correct, `false` if incorrect, `null` if the question is not auto-gradable.
+ */
+export function scoreQuestion(
+  question: QuestionData,
+  userAnswers: SessionAnswer[],
+): boolean | null {
+  switch (question.type) {
+    case "choice":
+    case "multiple_choice":
+    case "true_false": {
+      const correctUids = new Set(
+        (question.answers ?? []).filter((a) => a.isCorrect).map((a) => a.uid),
+      );
+      const userUids = new Set(userAnswers.map((a) => a.answerUid));
+      if (correctUids.size === 0) return null;
+      return (
+        correctUids.size === userUids.size &&
+        [...correctUids].every((uid) => userUids.has(uid))
+      );
+    }
+
+    case "fill_in_the_blank":
+    case "essay":
+      return null;
+
+    case "ordering": {
+      const answers = question.answers ?? [];
+      if (answers.length === 0) return null;
+      const sorted = [...answers].sort((a, b) => a.sequence - b.sequence);
+      return sorted.every((answer, correctIndex) => {
+        const ua = userAnswers.find((a) => a.answerUid === answer.uid);
+        return ua?.content === String(correctIndex);
+      });
+    }
+
+    case "matching": {
+      const pairs = question.matchingPairs ?? [];
+      if (pairs.length === 0) return null;
+      return pairs.every((pair) => {
+        const ua = userAnswers.find((a) => a.answerUid === pair.uid);
+        return ua?.content === pair.uid;
+      });
+    }
+
+    case "numeric": {
+      if (question.numericAnswer === undefined) return null;
+      const raw = userAnswers[0]?.content;
+      if (raw === undefined || raw === "") return false;
+      const userNum = parseFloat(raw);
+      if (isNaN(userNum)) return false;
+      const tolerance = question.numericTolerance ?? 0;
+      return Math.abs(userNum - question.numericAnswer) <= tolerance;
+    }
+
+    case "hotspot": {
+      const regions = question.hotspotRegions ?? [];
+      const correctUids = new Set(
+        regions.filter((r) => r.isCorrect).map((r) => r.uid),
+      );
+      if (correctUids.size === 0) return null;
+      const userUids = new Set(userAnswers.map((a) => a.answerUid));
+      return (
+        correctUids.size === userUids.size &&
+        [...correctUids].every((uid) => userUids.has(uid))
+      );
+    }
+
+    case "inline_choice": {
+      const blanks = question.inlineBlanks ?? [];
+      if (blanks.length === 0) return null;
+      return blanks.every((blank) => {
+        const correctOption = blank.options.find((o) => o.isCorrect);
+        if (!correctOption) return true;
+        const ua = userAnswers.find((a) => a.answerUid === blank.uid);
+        return ua?.content === correctOption.uid;
+      });
+    }
+
+    case "spreadsheet": {
+      const rows = question.spreadsheetRows ?? [];
+      const cols = question.spreadsheetColumns ?? [];
+      const colMap = new Map(cols.map((c) => [c.uid, c]));
+      const editableCells = rows.flatMap((r) =>
+        r.cells.filter((c) => !c.locked && c.correctAnswer !== undefined),
+      );
+      if (editableCells.length === 0) return null;
+      return editableCells.every((cell) => {
+        const ua = userAnswers.find((a) => a.answerUid === cell.uid);
+        const userValue = ua?.content?.trim() ?? "";
+        if (!userValue) return false;
+        const col = colMap.get(cell.columnUid);
+        if (!col || col.type === "text") {
+          return userValue.toLowerCase() === cell.correctAnswer!.trim().toLowerCase();
+        }
+        const userNum = parseFloat(userValue.replace(/,/g, ""));
+        const correctNum = parseFloat(cell.correctAnswer!.replace(/,/g, ""));
+        if (isNaN(userNum) || isNaN(correctNum)) return false;
+        const tol = cell.tolerance ?? 0;
+        return Math.abs(userNum - correctNum) <= tol;
+      });
+    }
+
+    case "scenario": {
+      const subQuestions = question.scenarioQuestions ?? [];
+      if (subQuestions.length === 0) return null;
+
+      const mode = question.scenarioScoringMode ?? "per_question";
+
+      if (mode === "all_or_nothing") {
+        const grouped = groupScenarioAnswers(userAnswers);
+        const results = subQuestions.map((sq) => {
+          const sqAnswers = grouped.get(sq.uid) ?? [];
+          return scoreQuestion(sq, sqAnswers);
+        });
+        if (results.some((r) => r === null)) return null;
+        return results.every((r) => r === true);
+      }
+
+      // "per_question" mode has no single aggregate score
+      return null;
+    }
+
+    default:
+      return null;
+  }
+}
+
+/**
+ * Scores an entire set of questions against user answers.
+ *
+ * @returns An object with correct count, total gradable, and percentage.
+ */
+export function scoreAssessment(
+  questions: QuestionData[],
+  answers: SessionAnswer[],
+): { correct: number; total: number; percentage: number } {
+  let correct = 0;
+  let gradable = 0;
+  for (const q of questions) {
+    const userAnswers = answers.filter((a) => a.uid === q.uid);
+    if (q.type === "scenario" && q.scenarioScoringMode !== "all_or_nothing") {
+      const subResults = scoreScenarioSubQuestions(q, userAnswers);
+      for (const [, result] of subResults) {
+        if (result !== null) {
+          gradable++;
+          if (result) correct++;
+        }
+      }
+      continue;
+    }
+    const result = scoreQuestion(q, userAnswers);
+    if (result !== null) {
+      gradable++;
+      if (result) correct++;
+    }
+  }
+  const total = gradable > 0 ? gradable : questions.length;
+  const percentage = total > 0 ? Math.round((correct / total) * 100) : 0;
+  return { correct, total, percentage };
+}
+
+/** Parse scenario answer UIDs (format "subQUid::originalAnswerUid") and group by sub-question. */
+function groupScenarioAnswers(
+  userAnswers: SessionAnswer[],
+): Map<string, SessionAnswer[]> {
+  const map = new Map<string, SessionAnswer[]>();
+  for (const ua of userAnswers) {
+    const sepIdx = ua.answerUid.indexOf("::");
+    if (sepIdx === -1) continue;
+    const subQUid = ua.answerUid.slice(0, sepIdx);
+    const originalAnswerUid = ua.answerUid.slice(sepIdx + 2);
+    const list = map.get(subQUid) ?? [];
+    list.push({ ...ua, answerUid: originalAnswerUid });
+    map.set(subQUid, list);
+  }
+  return map;
+}
+
+/**
+ * Scores individual sub-questions within a scenario.
+ * Returns a Map of sub-question UID to score (`true`/`false`/`null`).
+ */
+export function scoreScenarioSubQuestions(
+  question: QuestionData,
+  userAnswers: SessionAnswer[],
+): Map<string, boolean | null> {
+  const results = new Map<string, boolean | null>();
+  const subQuestions = question.scenarioQuestions ?? [];
+  const grouped = groupScenarioAnswers(userAnswers);
+
+  for (const sq of subQuestions) {
+    const sqAnswers = grouped.get(sq.uid) ?? [];
+    results.set(sq.uid, scoreQuestion(sq, sqAnswers));
+  }
+  return results;
+}

package/src/questions/spreadsheet.tsx

@@ -0,0 +1,259 @@
+import { useState, useMemo, useRef } from "react";
+import { debounce } from "../utils/debounce";
+import { Input } from "../ui/input";
+import {
+  Table,
+  TableHeader,
+  TableBody,
+  TableFooter,
+  TableRow,
+  TableHead,
+  TableCell,
+} from "../ui/table";
+import { Alert, AlertDescription } from "../ui/alert";
+import { cn } from "../lib/utils";
+import type {
+  QuestionProps,
+  SpreadsheetColumn,
+  SpreadsheetCell as SpreadsheetCellType,
+} from "./types";
+
+function getCellStatus(
+  cell: SpreadsheetCellType,
+  col: SpreadsheetColumn,
+  userValue: string,
+): "correct" | "incorrect" | "empty" | null {
+  if (cell.locked || !cell.correctAnswer) return null;
+  if (!userValue || userValue.trim() === "") return "empty";
+
+  if (col.type === "numeric" || col.type === "currency") {
+    const user = parseFloat(userValue.replace(/,/g, ""));
+    const correct = parseFloat(cell.correctAnswer);
+    if (isNaN(user) || isNaN(correct)) return "incorrect";
+    const tol = cell.tolerance ?? 0;
+    return Math.abs(user - correct) <= tol ? "correct" : "incorrect";
+  }
+
+  return userValue.trim().toLowerCase() === cell.correctAnswer.trim().toLowerCase()
+    ? "correct"
+    : "incorrect";
+}
+
+/**
+ * Spreadsheet renders a grid-based question for accounting and tabular data entry.
+ * Students fill in editable cells while locked cells display pre-filled values.
+ * Each cell is graded independently with support for numeric tolerance.
+ *
+ * @example
+ * <Spreadsheet
+ *   question={{
+ *     uid: "q1",
+ *     type: "spreadsheet",
+ *     content: "Complete the trial balance:",
+ *     spreadsheetColumns: [
+ *       { uid: "col-acct", label: "Account", type: "text", width: 14 },
+ *       { uid: "col-dr", label: "Debit ($)", type: "currency", width: 9 },
+ *       { uid: "col-cr", label: "Credit ($)", type: "currency", width: 9 },
+ *     ],
+ *     spreadsheetRows: [
+ *       { uid: "r1", cells: [
+ *         { uid: "r1-acct", columnUid: "col-acct", locked: true, value: "Cash" },
+ *         { uid: "r1-dr", columnUid: "col-dr", locked: false, correctAnswer: "5000" },
+ *         { uid: "r1-cr", columnUid: "col-cr", locked: true, value: "" },
+ *       ]},
+ *     ],
+ *   }}
+ *   onAnswer={(answers) => handleAnswer(answers)}
+ * />
+ */
+export const Spreadsheet = ({
+  question,
+  sessionAnswers,
+  onAnswer,
+  readOnly = false,
+  showCorrectAnswers = false,
+  disabled = false,
+}: QuestionProps) => {
+  const columns = question.spreadsheetColumns ?? [];
+  const rows = question.spreadsheetRows ?? [];
+
+  const colMap = useMemo(() => {
+    const m = new Map<string, SpreadsheetColumn>();
+    for (const col of columns) m.set(col.uid, col);
+    return m;
+  }, [columns]);
+
+  const editableCellUids = useMemo(
+    () => rows.flatMap((r) => r.cells.filter((c) => !c.locked).map((c) => c.uid)),
+    [rows],
+  );
+
+  const hasRowLabels = useMemo(() => rows.some((r) => r.label != null), [rows]);
+  const bodyRows = useMemo(() => rows.filter((r) => !r.isTotals), [rows]);
+  const totalsRows = useMemo(() => rows.filter((r) => r.isTotals), [rows]);
+
+  const onAnswerRef = useRef(onAnswer);
+  onAnswerRef.current = onAnswer;
+
+  const debouncedEmit = useMemo(
+    () =>
+      debounce((next: Map<string, string>) => {
+        onAnswerRef.current?.(
+          [...next.entries()].map(([uid, content]) => ({ uid, content })),
+        );
+      }, 300),
+    [],
+  );
+
+  const [values, setValues] = useState<Map<string, string>>(() => {
+    const map = new Map<string, string>();
+    for (const sa of sessionAnswers ?? []) {
+      if (sa.content !== undefined) map.set(sa.answerUid, sa.content);
+    }
+    for (const row of rows) {
+      for (const cell of row.cells) {
+        if (!cell.locked && !map.has(cell.uid)) {
+          map.set(cell.uid, cell.value ?? "");
+        }
+      }
+    }
+    return map;
+  });
+
+  const handleCellChange = (cellUid: string, raw: string) => {
+    if (readOnly || disabled) return;
+    const next = new Map(values);
+    next.set(cellUid, raw);
+    setValues(next);
+    debouncedEmit(next);
+  };
+
+  const handleKeyDown = (cellUid: string, e: React.KeyboardEvent<HTMLInputElement>) => {
+    if (e.key !== "Tab") return;
+    const idx = editableCellUids.indexOf(cellUid);
+    const nextIdx = e.shiftKey ? idx - 1 : idx + 1;
+    if (nextIdx < 0 || nextIdx >= editableCellUids.length) return;
+    e.preventDefault();
+    const nextUid = editableCellUids[nextIdx];
+    const nextInput = document.querySelector<HTMLInputElement>(
+      `[data-cell-uid="${nextUid}"]`,
+    );
+    nextInput?.focus();
+  };
+
+  const renderCell = (cell: SpreadsheetCellType) => {
+    const col = colMap.get(cell.columnUid);
+    if (!col) return null;
+
+    const userValue = values.get(cell.uid) ?? "";
+    const status = showCorrectAnswers ? getCellStatus(cell, col, userValue) : null;
+
+    const statusClasses =
+      status === "correct"
+        ? "bg-success/10 border-l-2 border-l-success/50"
+        : status === "incorrect" || status === "empty"
+          ? "bg-destructive/10 border-l-2 border-l-destructive/50"
+          : "";
+
+    if (cell.locked) {
+      return (
+        <TableCell
+          key={cell.uid}
+          className={cn(
+            "px-2 py-1.5 text-sm text-muted-foreground bg-muted/30",
+            col.type !== "text" && "text-right tabular-nums",
+          )}
+        >
+          {cell.value ?? ""}
+        </TableCell>
+      );
+    }
+
+    return (
+      <TableCell
+        key={cell.uid}
+        className={cn("p-0 relative", statusClasses)}
+      >
+        <Input
+          type={col.type === "numeric" ? "number" : "text"}
+          inputMode={col.type === "currency" ? "decimal" : undefined}
+          step={col.type === "numeric" ? "any" : undefined}
+          value={userValue}
+          onChange={(e) => handleCellChange(cell.uid, e.target.value)}
+          onKeyDown={(e) => handleKeyDown(cell.uid, e)}
+          disabled={readOnly || disabled}
+          data-cell-uid={cell.uid}
+          placeholder={col.type === "text" ? "" : "0.00"}
+          className={cn(
+            "h-8 rounded-none border-0 shadow-none focus-visible:ring-1 focus-visible:ring-inset focus-visible:ring-ring",
+            col.type !== "text" && "text-right tabular-nums",
+          )}
+        />
+        {showCorrectAnswers && status !== "correct" && status !== null && cell.correctAnswer && (
+          <div className="px-2 pb-1 text-xs">
+            <span className="text-success">{cell.correctAnswer}</span>
+            {cell.formula && (
+              <span className="ml-1 text-muted-foreground/70">({cell.formula})</span>
+            )}
+          </div>
+        )}
+      </TableCell>
+    );
+  };
+
+  const renderRow = (row: (typeof rows)[number]) => (
+    <TableRow
+      key={row.uid}
+      className={cn(
+        row.isHeader && "bg-muted/50 font-semibold hover:bg-muted/50",
+      )}
+    >
+      {hasRowLabels && (
+        <TableCell className="px-2 py-1.5 font-medium text-sm text-muted-foreground whitespace-nowrap">
+          {row.label ?? ""}
+        </TableCell>
+      )}
+      {row.cells.map(renderCell)}
+    </TableRow>
+  );
+
+  return (
+    <div className="flex flex-col gap-3">
+      <div dangerouslySetInnerHTML={{ __html: question.content }} />
+
+      <div className="rounded-md border border-border overflow-auto">
+        <Table>
+          <TableHeader>
+            <TableRow className="hover:bg-transparent">
+              {hasRowLabels && <TableHead className="w-auto" />}
+              {columns.map((col) => (
+                <TableHead
+                  key={col.uid}
+                  style={{ width: col.width ? `${col.width}rem` : undefined }}
+                  className={cn(
+                    col.type !== "text" && "text-right",
+                  )}
+                >
+                  {col.label}
+                </TableHead>
+              ))}
+            </TableRow>
+          </TableHeader>
+          <TableBody>{bodyRows.map(renderRow)}</TableBody>
+          {totalsRows.length > 0 && (
+            <TableFooter>{totalsRows.map(renderRow)}</TableFooter>
+          )}
+        </Table>
+      </div>
+
+      {showCorrectAnswers && question.explanation && (
+        <Alert className="mt-1">
+          <AlertDescription>
+            <strong>Explanation:</strong>{" "}
+            <span dangerouslySetInnerHTML={{ __html: question.explanation }} />
+          </AlertDescription>
+        </Alert>
+      )}
+    </div>
+  );
+};

package/src/questions/true-false.tsx

@@ -1,4 +1,4 @@
-import { useState, useEffect } from "react";
+import { useState, useMemo } from "react";
 import type { QuestionProps } from "./types";
 import { Alert, AlertDescription } from "../ui/alert";
 import { cn } from "../lib/utils";
@@ -20,10 +20,13 @@ export const TrueFalse = ({
   showCorrectAnswers = false,
   disabled = false,
 }: QuestionProps) => {
-  const [selectedAnswer, setSelectedAnswer] = useState<string>("");
+  const [selectedAnswer, setSelectedAnswer] = useState<string>(
+    () => sessionAnswers?.[0]?.answerUid || "",
+  );
 
-  const sortedAnswers = [...(question.answers || [])].sort(
-    (a, b) => a.sequence - b.sequence,
+  const sortedAnswers = useMemo(
+    () => [...(question.answers || [])].sort((a, b) => a.sequence - b.sequence),
+    [question.answers],
   );
 
   const handleChange = (uid: string) => {
@@ -33,11 +36,6 @@ export const TrueFalse = ({
     onAnswer?.([{ uid }]);
   };
 
-  useEffect(() => {
-    const current = sessionAnswers?.[0]?.answerUid || "";
-    setSelectedAnswer(current);
-  }, [sessionAnswers]);
-
   const getAnswerClasses = (answerUid: string) => {
     if (!showCorrectAnswers) return "px-2";