@hydralms/components 0.1.3 → 0.2.0

package/src/questions/inline-choice.tsx

@@ -0,0 +1,151 @@
+import { useState, useMemo } from "react";
+import { Alert, AlertDescription } from "../ui/alert";
+import { cn } from "../lib/utils";
+import type { QuestionProps, InlineBlank } from "./types";
+
+type ContentPart =
+  | { type: "text"; html: string }
+  | { type: "blank"; uid: string };
+
+function parseInlineContent(html: string): ContentPart[] {
+  const parts: ContentPart[] = [];
+  const regex = /\{\{blank:([\w-]+)\}\}/g;
+  let lastIndex = 0;
+  let match;
+  while ((match = regex.exec(html)) !== null) {
+    if (match.index > lastIndex) {
+      parts.push({ type: "text", html: html.slice(lastIndex, match.index) });
+    }
+    parts.push({ type: "blank", uid: match[1] });
+    lastIndex = regex.lastIndex;
+  }
+  if (lastIndex < html.length) {
+    parts.push({ type: "text", html: html.slice(lastIndex) });
+  }
+  return parts;
+}
+
+/**
+ * InlineChoice renders a cloze-style passage with embedded dropdown blanks.
+ *
+ * Content should contain `{{blank:uid}}` markers that correspond to entries in `question.inlineBlanks`.
+ *
+ * @example
+ * <InlineChoice
+ *   question={{
+ *     uid: "q1",
+ *     type: "inline_choice",
+ *     content: "The capital of France is {{blank:b1}}.",
+ *     inlineBlanks: [{ uid: "b1", sequence: 0, options: [
+ *       { uid: "o1", content: "Paris", isCorrect: true },
+ *       { uid: "o2", content: "London" },
+ *     ]}],
+ *   }}
+ *   onAnswer={(answers) => handleAnswer(answers)}
+ * />
+ */
+export const InlineChoice = ({
+  question,
+  sessionAnswers,
+  onAnswer,
+  readOnly = false,
+  showCorrectAnswers = false,
+  disabled = false,
+}: QuestionProps) => {
+  const blanksMap = useMemo(() => {
+    const map = new Map<string, InlineBlank>();
+    for (const blank of question.inlineBlanks ?? []) {
+      map.set(blank.uid, blank);
+    }
+    return map;
+  }, [question.inlineBlanks]);
+
+  const [selections, setSelections] = useState<Map<string, string>>(() => {
+    const map = new Map<string, string>();
+    for (const sa of sessionAnswers ?? []) {
+      if (sa.content) map.set(sa.answerUid, sa.content);
+    }
+    return map;
+  });
+
+  const parts = useMemo(
+    () => parseInlineContent(question.content),
+    [question.content],
+  );
+
+  const handleSelect = (blankUid: string, optionUid: string) => {
+    if (readOnly || disabled) return;
+
+    const next = new Map(selections);
+    next.set(blankUid, optionUid);
+    setSelections(next);
+
+    const answers = [...next.entries()].map(([uid, content]) => ({
+      uid,
+      content,
+    }));
+    onAnswer?.(answers);
+  };
+
+  const getSelectClasses = (blankUid: string) => {
+    if (!showCorrectAnswers) return "";
+    const blank = blanksMap.get(blankUid);
+    const selected = selections.get(blankUid);
+    if (!blank || !selected) return "";
+    const correctOption = blank.options.find((o) => o.isCorrect);
+    if (!correctOption) return "";
+    return selected === correctOption.uid
+      ? "border-success/50 bg-success/5 text-success"
+      : "border-destructive/50 bg-destructive/5 text-destructive";
+  };
+
+  return (
+    <div className="flex flex-col gap-4">
+      <div className="leading-relaxed text-foreground">
+        {parts.map((part, i) => {
+          if (part.type === "text") {
+            return (
+              <span
+                key={i}
+                dangerouslySetInnerHTML={{ __html: part.html }}
+              />
+            );
+          }
+
+          const blank = blanksMap.get(part.uid);
+          if (!blank) return null;
+
+          return (
+            <select
+              key={part.uid}
+              value={selections.get(part.uid) || ""}
+              onChange={(e) => handleSelect(part.uid, e.target.value)}
+              disabled={readOnly || disabled}
+              className={cn(
+                "inline-block mx-1 px-2 py-0.5 rounded border border-border bg-background text-foreground text-sm align-baseline",
+                "disabled:opacity-60 disabled:cursor-default",
+                getSelectClasses(part.uid),
+              )}
+            >
+              <option value="">Select...</option>
+              {blank.options.map((opt) => (
+                <option key={opt.uid} value={opt.uid}>
+                  {opt.content}
+                </option>
+              ))}
+            </select>
+          );
+        })}
+      </div>
+
+      {showCorrectAnswers && question.explanation && (
+        <Alert className="mt-2">
+          <AlertDescription>
+            <strong>Explanation:</strong>{" "}
+            <span dangerouslySetInnerHTML={{ __html: question.explanation }} />
+          </AlertDescription>
+        </Alert>
+      )}
+    </div>
+  );
+};

package/src/questions/matching.tsx

@@ -0,0 +1,228 @@
+import { useState, useMemo, useCallback } from "react";
+import { Alert, AlertDescription } from "../ui/alert";
+import { cn } from "../lib/utils";
+import type { QuestionProps } from "./types";
+
+/**
+ * Matching renders a two-column matching question with dropdown selects and optional drag-and-drop.
+ *
+ * Each item (left column) must be matched to its correct target (right column).
+ * The dropdown is the primary accessible interaction; drag-and-drop is progressive enhancement.
+ *
+ * @example
+ * <Matching
+ *   question={{
+ *     uid: "q1",
+ *     type: "matching",
+ *     content: "Match each country to its capital.",
+ *     matchingPairs: [
+ *       { uid: "p1", item: "France", target: "Paris", sequence: 0 },
+ *       { uid: "p2", item: "Germany", target: "Berlin", sequence: 1 },
+ *     ],
+ *   }}
+ *   onAnswer={(answers) => handleAnswer(answers)}
+ * />
+ */
+export const Matching = ({
+  question,
+  sessionAnswers,
+  onAnswer,
+  readOnly = false,
+  showCorrectAnswers = false,
+  disabled = false,
+}: QuestionProps) => {
+  const sortedPairs = useMemo(
+    () =>
+      [...(question.matchingPairs ?? [])].sort(
+        (a, b) => a.sequence - b.sequence,
+      ),
+    [question.matchingPairs],
+  );
+
+  // Shuffled targets for display
+  const shuffledTargets = useMemo(
+    () => [...sortedPairs].sort(() => Math.random() - 0.5),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [sortedPairs.map((p) => p.uid).join()],
+  );
+
+  // Map: item pair uid → selected target pair uid
+  const [matches, setMatches] = useState<Map<string, string>>(() => {
+    const map = new Map<string, string>();
+    for (const sa of sessionAnswers ?? []) {
+      if (sa.content) map.set(sa.answerUid, sa.content);
+    }
+    return map;
+  });
+
+  const [dragItemUid, setDragItemUid] = useState<string | null>(null);
+  const [dragOverTargetUid, setDragOverTargetUid] = useState<string | null>(
+    null,
+  );
+
+  const emitAnswer = useCallback(
+    (next: Map<string, string>) => {
+      onAnswer?.(
+        [...next.entries()].map(([uid, content]) => ({ uid, content })),
+      );
+    },
+    [onAnswer],
+  );
+
+  const handleSelect = (itemUid: string, targetUid: string) => {
+    if (readOnly || disabled) return;
+    const next = new Map(matches);
+    if (targetUid) {
+      next.set(itemUid, targetUid);
+    } else {
+      next.delete(itemUid);
+    }
+    setMatches(next);
+    emitAnswer(next);
+  };
+
+  // Drag-and-drop handlers (progressive enhancement)
+  const handleDragStartItem = (pairUid: string) => (e: React.DragEvent) => {
+    if (readOnly || disabled) {
+      e.preventDefault();
+      return;
+    }
+    setDragItemUid(pairUid);
+    e.dataTransfer.effectAllowed = "link";
+    e.dataTransfer.setData("text/plain", pairUid);
+  };
+
+  const handleDragOverTarget = (targetUid: string) => (e: React.DragEvent) => {
+    e.preventDefault();
+    e.dataTransfer.dropEffect = "link";
+    setDragOverTargetUid(targetUid);
+  };
+
+  const handleDropTarget = (targetUid: string) => (e: React.DragEvent) => {
+    e.preventDefault();
+    if (dragItemUid) {
+      handleSelect(dragItemUid, targetUid);
+    }
+    setDragItemUid(null);
+    setDragOverTargetUid(null);
+  };
+
+  const handleDragEnd = () => {
+    setDragItemUid(null);
+    setDragOverTargetUid(null);
+  };
+
+  const getMatchClasses = (pairUid: string) => {
+    if (!showCorrectAnswers) return "";
+    const selected = matches.get(pairUid);
+    if (!selected) return "";
+    return selected === pairUid
+      ? "bg-success/10 border-success/30"
+      : "bg-destructive/10 border-destructive/30";
+  };
+
+  // Find which item is matched to a given target
+  const getTargetMatchedBy = (targetUid: string): string | undefined => {
+    for (const [itemUid, matchedTarget] of matches) {
+      if (matchedTarget === targetUid) return itemUid;
+    }
+    return undefined;
+  };
+
+  return (
+    <div className="flex flex-col gap-4">
+      <div dangerouslySetInnerHTML={{ __html: question.content }} />
+
+      <div className="grid grid-cols-1 sm:grid-cols-2 gap-4">
+        {/* Left column: items */}
+        <div className="flex flex-col gap-2">
+          <div className="text-xs font-medium text-muted-foreground uppercase tracking-wider mb-1">
+            Items
+          </div>
+          {sortedPairs.map((pair) => (
+            <div
+              key={pair.uid}
+              draggable={!(readOnly || disabled)}
+              onDragStart={handleDragStartItem(pair.uid)}
+              onDragEnd={handleDragEnd}
+              className={cn(
+                "rounded-md border px-3 py-2 transition-colors",
+                dragItemUid === pair.uid && "opacity-50",
+                !(readOnly || disabled) && "cursor-grab active:cursor-grabbing",
+                getMatchClasses(pair.uid),
+              )}
+            >
+              <div className="flex items-center gap-2">
+                <span
+                  className="flex-1 text-foreground"
+                  dangerouslySetInnerHTML={{ __html: pair.item }}
+                />
+                <select
+                  value={matches.get(pair.uid) || ""}
+                  onChange={(e) => handleSelect(pair.uid, e.target.value)}
+                  disabled={readOnly || disabled}
+                  className={cn(
+                    "px-2 py-1 rounded border border-border bg-background text-foreground text-sm",
+                    "disabled:opacity-60 disabled:cursor-default",
+                  )}
+                >
+                  <option value="">—</option>
+                  {shuffledTargets.map((target) => (
+                    <option key={target.uid} value={target.uid}>
+                      {target.target.replace(/<[^>]+>/g, "")}
+                    </option>
+                  ))}
+                </select>
+              </div>
+            </div>
+          ))}
+        </div>
+
+        {/* Right column: targets (drop zones) */}
+        <div className="flex flex-col gap-2">
+          <div className="text-xs font-medium text-muted-foreground uppercase tracking-wider mb-1">
+            Targets
+          </div>
+          {shuffledTargets.map((pair) => {
+            const matchedBy = getTargetMatchedBy(pair.uid);
+            const matchedPair = matchedBy
+              ? sortedPairs.find((p) => p.uid === matchedBy)
+              : null;
+
+            return (
+              <div
+                key={pair.uid}
+                onDragOver={handleDragOverTarget(pair.uid)}
+                onDrop={handleDropTarget(pair.uid)}
+                className={cn(
+                  "rounded-md border border-dashed px-3 py-2 transition-colors min-h-10",
+                  dragOverTargetUid === pair.uid && "ring-2 ring-primary",
+                  matchedBy && "border-solid",
+                )}
+              >
+                <span
+                  className="text-foreground"
+                  dangerouslySetInnerHTML={{ __html: pair.target }}
+                />
+                {matchedPair && (
+                  <div className="mt-1 text-xs text-muted-foreground">
+                    ← matched
+                  </div>
+                )}
+              </div>
+            );
+          })}
+        </div>
+      </div>
+
+      {showCorrectAnswers && question.explanation && (
+        <Alert className="mt-2">
+          <AlertDescription>
+            <strong>Explanation:</strong>{" "}
+            <span dangerouslySetInnerHTML={{ __html: question.explanation }} />
+          </AlertDescription>
+        </Alert>
+      )}
+    </div>
+  );
+};

package/src/questions/multiple-choice.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 MultipleChoice = ({
   showCorrectAnswers = false,
   disabled = false,
 }: QuestionProps) => {
-  const [selectedAnswers, setSelectedAnswers] = useState<string[]>([]);
+  const [selectedAnswers, setSelectedAnswers] = useState<string[]>(
+    () => sessionAnswers?.map((sa) => sa.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) => {
@@ -39,11 +42,6 @@ export const MultipleChoice = ({
     });
   };
 
-  useEffect(() => {
-    const current = sessionAnswers?.map((sa) => sa.answerUid) || [];
-    setSelectedAnswers(current);
-  }, [sessionAnswers]);
-
   const getAnswerClasses = (answerUid: string) => {
     if (!showCorrectAnswers) return "";
 

package/src/questions/numeric.tsx

@@ -0,0 +1,102 @@
+import { useState, useMemo, useRef } from "react";
+import { debounce } from "../utils/debounce";
+import { Input } from "../ui/input";
+import { Alert, AlertDescription } from "../ui/alert";
+import { cn } from "../lib/utils";
+import type { QuestionProps } from "./types";
+
+/**
+ * Numeric renders a number input question with optional tolerance and unit display.
+ *
+ * @example
+ * <Numeric
+ *   question={{ uid: "q1", type: "numeric", content: "What is pi to 2 decimal places?", numericAnswer: 3.14, numericTolerance: 0.01 }}
+ *   onAnswer={(answers) => handleAnswer(answers)}
+ * />
+ */
+export const Numeric = ({
+  question,
+  sessionAnswers,
+  onAnswer,
+  readOnly = false,
+  showCorrectAnswers = false,
+  disabled = false,
+}: QuestionProps) => {
+  const [value, setValue] = useState(() => sessionAnswers?.[0]?.content || "");
+
+  const onAnswerRef = useRef(onAnswer);
+  onAnswerRef.current = onAnswer;
+  const questionUidRef = useRef(question.uid);
+  questionUidRef.current = question.uid;
+
+  const debouncedAnswer = useMemo(
+    () =>
+      debounce((content: string) => {
+        onAnswerRef.current?.([{ uid: questionUidRef.current, content }]);
+      }, 300),
+    [],
+  );
+
+  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    const newValue = e.target.value;
+    setValue(newValue);
+    debouncedAnswer(newValue);
+  };
+
+  const isCorrect = (() => {
+    if (!showCorrectAnswers || question.numericAnswer === undefined) return null;
+    if (value === "") return false;
+    const userNum = parseFloat(value);
+    if (isNaN(userNum)) return false;
+    const tolerance = question.numericTolerance ?? 0;
+    return Math.abs(userNum - question.numericAnswer) <= tolerance;
+  })();
+
+  const inputClasses = (() => {
+    if (!showCorrectAnswers || isCorrect === null) return "";
+    return isCorrect
+      ? "border-success/50 bg-success/5"
+      : "border-destructive/50 bg-destructive/5";
+  })();
+
+  return (
+    <div className="flex flex-col gap-2">
+      <div dangerouslySetInnerHTML={{ __html: question.content }} />
+
+      <div className="flex items-center gap-2">
+        <Input
+          type="number"
+          value={value}
+          onChange={handleChange}
+          placeholder="Enter a number..."
+          disabled={readOnly || disabled}
+          className={cn("max-w-48", inputClasses)}
+          step="any"
+        />
+        {question.numericUnit && (
+          <span className="text-muted-foreground text-sm">
+            {question.numericUnit}
+          </span>
+        )}
+      </div>
+
+      {showCorrectAnswers && question.numericAnswer !== undefined && (
+        <p className="text-sm text-muted-foreground">
+          Correct answer: {question.numericAnswer}
+          {(question.numericTolerance ?? 0) > 0 && (
+            <span> (± {question.numericTolerance})</span>
+          )}
+        </p>
+      )}
+
+      {showCorrectAnswers && question.explanation && (
+        <Alert className="mt-1">
+          <AlertDescription>
+            <strong>Explanation:</strong>{" "}
+            <span dangerouslySetInnerHTML={{ __html: question.explanation }} />
+          </AlertDescription>
+        </Alert>
+      )}
+    </div>
+  );
+};

package/src/questions/ordering.tsx

@@ -0,0 +1,159 @@
+import { useState, useMemo } 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 = ({
+  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 [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);
+  };
+
+  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 }} />
+
+      <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>
+  );
+};