@hydralms/components 0.1.3 → 0.3.0

package/src/questions/spreadsheet.tsx

@@ -0,0 +1,260 @@
+import { useState, useMemo, useRef, useEffect, memo } 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 = memo(function 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),
+    [],
+  );
+  useEffect(() => () => debouncedEmit.cancel(), [debouncedEmit]);
+
+  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, memo } from "react";
 import type { QuestionProps } from "./types";
 import { Alert, AlertDescription } from "../ui/alert";
 import { cn } from "../lib/utils";
@@ -12,18 +12,21 @@ import { cn } from "../lib/utils";
  *   onAnswer={(answers) => handleAnswer(answers)}
  * />
  */
-export const TrueFalse = ({
+export const TrueFalse = memo(function TrueFalse({
   question,
   sessionAnswers,
   onAnswer,
   readOnly = false,
   showCorrectAnswers = false,
   disabled = false,
-}: QuestionProps) => {
-  const [selectedAnswer, setSelectedAnswer] = useState<string>("");
+}: QuestionProps) {
+  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";
 
@@ -55,7 +53,8 @@ export const TrueFalse = ({
     <div className="flex flex-col gap-4">
       <div dangerouslySetInnerHTML={{ __html: question.content }} />
 
-      <div className="flex flex-col gap-2">
+      <fieldset className="flex flex-col gap-2 border-0 p-0 m-0">
+        <legend className="sr-only">True or False</legend>
         {sortedAnswers.map((answer) => (
           <div
             key={answer.uid}
@@ -72,10 +71,16 @@ export const TrueFalse = ({
                 className="accent-primary m-0 shrink-0"
               />
               <span dangerouslySetInnerHTML={{ __html: answer.content }} />
+              {showCorrectAnswers && answer.isCorrect && (
+                <span className="sr-only">(Correct answer)</span>
+              )}
+              {showCorrectAnswers && selectedAnswer === answer.uid && !answer.isCorrect && (
+                <span className="sr-only">(Your answer — incorrect)</span>
+              )}
             </label>
           </div>
         ))}
-      </div>
+      </fieldset>
 
       {showCorrectAnswers && question.explanation && (
         <Alert className="mt-2">
@@ -87,4 +92,4 @@ export const TrueFalse = ({
       )}
     </div>
   );
-};
+});

package/src/questions/types.ts

@@ -3,7 +3,17 @@ export type QuestionTypeEnum =
   | "choice"
   | "true_false"
   | "fill_in_the_blank"
-  | "essay";
+  | "essay"
+  | "matching"
+  | "ordering"
+  | "numeric"
+  | "hotspot"
+  | "inline_choice"
+  | "scenario"
+  | "spreadsheet";
+
+/** Scoring strategy for scenario questions. */
+export type ScenarioScoringMode = "per_question" | "all_or_nothing";
 
 export interface AnswerOption {
   uid: string;
@@ -20,12 +30,124 @@ export interface SessionAnswer {
   confidence?: string;
 }
 
+/** A pair linking a left-side item to its correct right-side target. */
+export interface MatchingPair {
+  uid: string;
+  /** Left-side item content (HTML) */
+  item: string;
+  /** Right-side target content (HTML) */
+  target: string;
+  sequence: number;
+}
+
+/** A clickable region on a hotspot image. Coordinates are percentages (0–100). */
+export interface HotspotRegion {
+  uid: string;
+  shape: "rect" | "circle";
+  /** rect: [x, y, width, height]; circle: [centerX, centerY, radius] */
+  coords: number[];
+  isCorrect?: boolean;
+  label?: string;
+}
+
+/** A dropdown blank embedded in an inline-choice (cloze) passage. */
+export interface InlineBlank {
+  uid: string;
+  options: { uid: string; content: string; isCorrect?: boolean }[];
+  sequence: number;
+}
+
+/** A column definition for a spreadsheet question. */
+export interface SpreadsheetColumn {
+  uid: string;
+  /** Column header text */
+  label: string;
+  /** Data type hint for input rendering and scoring */
+  type: "text" | "numeric" | "currency";
+  /** Column width in rems (default 8) */
+  width?: number;
+}
+
+/** A single cell in a spreadsheet row. */
+export interface SpreadsheetCell {
+  /** Unique identifier — becomes the answerUid in SessionAnswer */
+  uid: string;
+  /** Which column this cell belongs to */
+  columnUid: string;
+  /** When true, cell is pre-filled and not editable */
+  locked: boolean;
+  /** Display value for locked cells, or pre-fill for editable cells */
+  value?: string;
+  /** Expected answer for grading (editable cells only) */
+  correctAnswer?: string;
+  /** Acceptable numeric deviation (default 0 = exact match) */
+  tolerance?: number;
+  /** Hint shown in review mode (e.g., "= Revenue – Expenses") */
+  formula?: string;
+}
+
+/** A row in a spreadsheet question grid. */
+export interface SpreadsheetRow {
+  uid: string;
+  /** Optional row header label (e.g., "Cash", "Accounts Receivable") */
+  label?: string;
+  /** Ordered cells — one per column */
+  cells: SpreadsheetCell[];
+  /** Renders as a bold section divider row */
+  isHeader?: boolean;
+  /** Renders in table footer with top border */
+  isTotals?: boolean;
+}
+
+/** Content blocks associated with a question for open-book reference. */
+export interface QuestionMaterial {
+  /** UID of the question this material is linked to */
+  questionUid: string;
+  /** Display label for the material group (e.g., "Chapter 3: Bonds") */
+  label?: string;
+  /** Content blocks to render in the materials drawer */
+  blocks: import("../content/types").LessonBlock[];
+}
+
 export interface QuestionData {
   uid: string;
   type: QuestionTypeEnum;
+  /** Question prompt (HTML) */
   content: string;
+  /** Explanation shown in review mode (HTML) */
   explanation?: string;
+  /** Answer options for choice / multiple_choice / true_false / ordering */
   answers?: AnswerOption[];
+
+  /** Matching-specific: pairs of items and targets */
+  matchingPairs?: MatchingPair[];
+
+  /** Numeric-specific: correct answer */
+  numericAnswer?: number;
+  /** Numeric-specific: acceptable deviation (default 0 = exact) */
+  numericTolerance?: number;
+  /** Numeric-specific: unit label displayed after input */
+  numericUnit?: string;
+
+  /** Hotspot-specific: image URL */
+  hotspotImageUrl?: string;
+  /** Hotspot-specific: clickable regions */
+  hotspotRegions?: HotspotRegion[];
+  /** Hotspot-specific: allow selecting multiple regions */
+  hotspotMultiSelect?: boolean;
+
+  /** InlineChoice-specific: dropdown blanks embedded in content */
+  inlineBlanks?: InlineBlank[];
+
+  /** Scenario-specific: sub-questions grouped under this scenario's shared context */
+  scenarioQuestions?: QuestionData[];
+  /** Scenario-specific: how the scenario is scored (default "per_question") */
+  scenarioScoringMode?: ScenarioScoringMode;
+
+  /** Spreadsheet-specific: column definitions */
+  spreadsheetColumns?: SpreadsheetColumn[];
+  /** Spreadsheet-specific: row data with cells */
+  spreadsheetRows?: SpreadsheetRow[];
 }
 
 /**

package/src/questions/use-drag-reorder.ts

@@ -0,0 +1,80 @@
+import { useState, useCallback, useRef } from "react";
+
+interface UseDragReorderOptions<T> {
+  items: T[];
+  onReorder: (items: T[]) => void;
+  disabled?: boolean;
+}
+
+export function useDragReorder<T>({
+  items,
+  onReorder,
+  disabled = false,
+}: UseDragReorderOptions<T>) {
+  const [dragIndex, setDragIndex] = useState<number | null>(null);
+  const [dragOverIndex, setDragOverIndex] = useState<number | null>(null);
+  const dragIndexRef = useRef<number | null>(null);
+
+  const handleDragStart = useCallback(
+    (index: number) => (e: React.DragEvent) => {
+      if (disabled) {
+        e.preventDefault();
+        return;
+      }
+      dragIndexRef.current = index;
+      setDragIndex(index);
+      e.dataTransfer.effectAllowed = "move";
+      e.dataTransfer.setData("text/plain", String(index));
+    },
+    [disabled],
+  );
+
+  const handleDragOver = useCallback(
+    (index: number) => (e: React.DragEvent) => {
+      e.preventDefault();
+      e.dataTransfer.dropEffect = "move";
+      setDragOverIndex(index);
+    },
+    [],
+  );
+
+  const handleDrop = useCallback(
+    (index: number) => (e: React.DragEvent) => {
+      e.preventDefault();
+      const fromIndex = dragIndexRef.current;
+      if (fromIndex === null || fromIndex === index) {
+        setDragIndex(null);
+        setDragOverIndex(null);
+        return;
+      }
+
+      const next = [...items];
+      const [moved] = next.splice(fromIndex, 1);
+      next.splice(index, 0, moved);
+
+      setDragIndex(null);
+      setDragOverIndex(null);
+      onReorder(next);
+    },
+    [items, onReorder],
+  );
+
+  const handleDragEnd = useCallback(() => {
+    setDragIndex(null);
+    setDragOverIndex(null);
+    dragIndexRef.current = null;
+  }, []);
+
+  const getDragProps = useCallback(
+    (index: number) => ({
+      draggable: !disabled,
+      onDragStart: handleDragStart(index),
+      onDragOver: handleDragOver(index),
+      onDrop: handleDrop(index),
+      onDragEnd: handleDragEnd,
+    }),
+    [disabled, handleDragStart, handleDragOver, handleDrop, handleDragEnd],
+  );
+
+  return { getDragProps, dragIndex, dragOverIndex };
+}