@hydralms/components 0.1.3 → 0.3.0

package/src/questions/ordering.tsx

@@ -0,0 +1,167 @@
+import { useState, useMemo, memo } from "react";
+import { ChevronUp, ChevronDown, GripVertical } from "lucide-react";
+import { Alert, AlertDescription } from "../ui/alert";
+import { cn } from "../lib/utils";
+import { useDragReorder } from "./use-drag-reorder";
+import type { QuestionProps, AnswerOption } from "./types";
+
+/**
+ * Ordering renders a drag-and-drop reorderable list of items.
+ * The correct order is determined by each answer's `sequence` field.
+ *
+ * @example
+ * <Ordering
+ *   question={question}
+ *   onAnswer={(answers) => handleAnswer(answers)}
+ * />
+ */
+export const Ordering = memo(function Ordering({
+  question,
+  sessionAnswers,
+  onAnswer,
+  readOnly = false,
+  showCorrectAnswers = false,
+  disabled = false,
+}: QuestionProps) {
+  const correctOrder = useMemo(
+    () =>
+      [...(question.answers || [])].sort((a, b) => a.sequence - b.sequence),
+    [question.answers],
+  );
+
+  const [announcement, setAnnouncement] = useState("");
+
+  const [items, setItems] = useState<AnswerOption[]>(() => {
+    if (sessionAnswers && sessionAnswers.length > 0) {
+      // Rebuild order from sessionAnswers position indices
+      const posMap = new Map<string, number>();
+      for (const sa of sessionAnswers) {
+        posMap.set(sa.answerUid, parseInt(sa.content || "0", 10));
+      }
+      return [...correctOrder].sort(
+        (a, b) => (posMap.get(a.uid) ?? 0) - (posMap.get(b.uid) ?? 0),
+      );
+    }
+    // Shuffle for initial display so correct order isn't given away
+    return [...correctOrder].sort(() => Math.random() - 0.5);
+  });
+
+  const emitAnswer = (orderedItems: AnswerOption[]) => {
+    onAnswer?.(
+      orderedItems.map((item, index) => ({
+        uid: item.uid,
+        content: String(index),
+      })),
+    );
+  };
+
+  const handleReorder = (next: AnswerOption[]) => {
+    setItems(next);
+    emitAnswer(next);
+  };
+
+  const moveItem = (fromIndex: number, toIndex: number) => {
+    if (readOnly || disabled) return;
+    if (toIndex < 0 || toIndex >= items.length) return;
+    const next = [...items];
+    const [moved] = next.splice(fromIndex, 1);
+    next.splice(toIndex, 0, moved);
+    setItems(next);
+    emitAnswer(next);
+    setAnnouncement(
+      `${moved.content.replace(/<[^>]+>/g, "")} moved to position ${toIndex + 1} of ${items.length}`,
+    );
+  };
+
+  const { getDragProps, dragIndex, dragOverIndex } = useDragReorder({
+    items,
+    onReorder: handleReorder,
+    disabled: readOnly || disabled,
+  });
+
+  const getItemClasses = (item: AnswerOption, index: number) => {
+    if (!showCorrectAnswers) return "";
+    const correctIndex = correctOrder.findIndex((a) => a.uid === item.uid);
+    return correctIndex === index
+      ? "bg-success/10 border-success/30"
+      : "bg-destructive/10 border-destructive/30";
+  };
+
+  return (
+    <div className="flex flex-col gap-4">
+      <div dangerouslySetInnerHTML={{ __html: question.content }} />
+      <span className="sr-only" aria-live="assertive" role="status">
+        {announcement}
+      </span>
+
+      <div className="flex flex-col gap-1.5">
+        {items.map((item, index) => (
+          <div
+            key={item.uid}
+            {...getDragProps(index)}
+            className={cn(
+              "flex items-center gap-2 rounded-md border px-3 py-2 transition-all select-none",
+              dragIndex === index && "opacity-50",
+              dragOverIndex === index &&
+                dragIndex !== index &&
+                "border-t-2 border-t-primary",
+              !(readOnly || disabled) && "cursor-grab active:cursor-grabbing",
+              getItemClasses(item, index),
+            )}
+          >
+            {!(readOnly || disabled) && (
+              <GripVertical className="size-4 text-muted-foreground shrink-0" />
+            )}
+
+            <span className="text-sm font-medium text-muted-foreground w-6 shrink-0">
+              {index + 1}.
+            </span>
+
+            <span
+              className="flex-1 text-foreground"
+              dangerouslySetInnerHTML={{ __html: item.content }}
+            />
+
+            {!(readOnly || disabled) && (
+              <div className="flex flex-col shrink-0">
+                <button
+                  type="button"
+                  onClick={() => moveItem(index, index - 1)}
+                  disabled={index === 0}
+                  className="p-0.5 text-muted-foreground hover:text-foreground disabled:opacity-30 disabled:cursor-default"
+                  aria-label={`Move ${item.content} up`}
+                >
+                  <ChevronUp className="size-4" />
+                </button>
+                <button
+                  type="button"
+                  onClick={() => moveItem(index, index + 1)}
+                  disabled={index === items.length - 1}
+                  className="p-0.5 text-muted-foreground hover:text-foreground disabled:opacity-30 disabled:cursor-default"
+                  aria-label={`Move ${item.content} down`}
+                >
+                  <ChevronDown className="size-4" />
+                </button>
+              </div>
+            )}
+
+            {showCorrectAnswers && (
+              <span className="text-xs text-muted-foreground shrink-0">
+                (correct: {correctOrder.findIndex((a) => a.uid === item.uid) + 1})
+              </span>
+            )}
+          </div>
+        ))}
+      </div>
+
+      {showCorrectAnswers && question.explanation && (
+        <Alert className="mt-2">
+          <AlertDescription>
+            <strong>Explanation:</strong>{" "}
+            <span dangerouslySetInnerHTML={{ __html: question.explanation }} />
+          </AlertDescription>
+        </Alert>
+      )}
+    </div>
+  );
+});

package/src/questions/question-renderer.tsx

@@ -1,9 +1,17 @@
+import { memo } from "react";
 import type { QuestionProps } from "./types";
 import { MultipleChoice } from "./multiple-choice";
 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.
@@ -15,7 +23,7 @@ import { Essay } from "./essay";
  *   onAnswer={handleAnswer}
  * />
  */
-export const QuestionRenderer = (props: QuestionProps) => {
+export const QuestionRenderer = memo(function QuestionRenderer(props: QuestionProps) {
   switch (props.question.type) {
     case "multiple_choice":
       return <MultipleChoice {...props} />;
@@ -27,6 +35,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">
@@ -34,4 +56,4 @@ export const QuestionRenderer = (props: QuestionProps) => {
         </p>
       );
   }
-};
+});

package/src/questions/scenario.tsx

@@ -0,0 +1,140 @@
+import { useMemo, useRef, memo } 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 = memo(function 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;
+}