@hydralms/components 0.1.3 → 0.3.0

package/src/questions/inline-choice.tsx

@@ -0,0 +1,152 @@
+import { useState, useMemo, memo } 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 = memo(function 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}
+              aria-label={`Blank ${blank.sequence + 1}`}
+              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,229 @@
+import { useState, useMemo, useCallback, memo } 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 = memo(function 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
+                  aria-label={`Match for: ${pair.item.replace(/<[^>]+>/g, "")}`}
+                  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, 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 MultipleChoice = ({
+export const MultipleChoice = memo(function MultipleChoice({
   question,
   sessionAnswers,
   onAnswer,
   readOnly = false,
   showCorrectAnswers = false,
   disabled = false,
-}: QuestionProps) => {
-  const [selectedAnswers, setSelectedAnswers] = useState<string[]>([]);
+}: QuestionProps) {
+  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 "";
 
@@ -61,7 +59,8 @@ export const MultipleChoice = ({
     <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">Select all correct answers</legend>
         {sortedAnswers.map((answer) => (
           <div
             key={answer.uid}
@@ -79,10 +78,16 @@ export const MultipleChoice = ({
                 className="text-sm"
                 dangerouslySetInnerHTML={{ __html: answer.content }}
               />
+              {showCorrectAnswers && answer.isCorrect && (
+                <span className="sr-only">(Correct answer)</span>
+              )}
+              {showCorrectAnswers && selectedAnswers.includes(answer.uid) && !answer.isCorrect && (
+                <span className="sr-only">(Your answer — incorrect)</span>
+              )}
             </label>
           </div>
         ))}
-      </div>
+      </fieldset>
 
       {showCorrectAnswers && question.explanation && (
         <Alert className="mt-2">
@@ -94,4 +99,4 @@ export const MultipleChoice = ({
       )}
     </div>
   );
-};
+});

package/src/questions/numeric.tsx

@@ -0,0 +1,106 @@
+import { useState, useMemo, useRef, useId, useEffect, memo } 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 = memo(function Numeric({
+  question,
+  sessionAnswers,
+  onAnswer,
+  readOnly = false,
+  showCorrectAnswers = false,
+  disabled = false,
+}: QuestionProps) {
+  const inputId = useId();
+  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),
+    [],
+  );
+  useEffect(() => () => debouncedAnswer.cancel(), [debouncedAnswer]);
+
+  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">
+        <label htmlFor={inputId} className="sr-only">Numeric answer</label>
+        <Input
+          id={inputId}
+          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>
+  );
+});