@hydralms/components 0.1.0 → 0.1.2

package/src/questions/choice.tsx

@@ -0,0 +1,90 @@
+import { useState, useEffect } from "react";
+import type { QuestionProps } from "./types";
+import { Alert, AlertDescription } from "../ui/alert";
+import { cn } from "../lib/utils";
+
+/**
+ * Choice renders a single-answer question using radio buttons.
+ *
+ * @example
+ * <Choice
+ *   question={question}
+ *   onAnswer={(answers) => handleAnswer(answers)}
+ * />
+ */
+export const Choice = ({
+  question,
+  sessionAnswers,
+  onAnswer,
+  readOnly = false,
+  showCorrectAnswers = false,
+  disabled = false,
+}: QuestionProps) => {
+  const [selectedAnswer, setSelectedAnswer] = useState<string>("");
+
+  const sortedAnswers = [...(question.answers || [])].sort(
+    (a, b) => a.sequence - b.sequence,
+  );
+
+  const handleChange = (uid: string) => {
+    if (readOnly || disabled) return;
+
+    setSelectedAnswer(uid);
+    onAnswer?.([{ uid }]);
+  };
+
+  useEffect(() => {
+    const current = sessionAnswers?.[0]?.answerUid || "";
+    setSelectedAnswer(current);
+  }, [sessionAnswers]);
+
+  const getAnswerClasses = (answerUid: string) => {
+    if (!showCorrectAnswers) return "px-2";
+
+    const answer = question.answers?.find((a) => a.uid === answerUid);
+    if (answer?.isCorrect) {
+      return "bg-success/10 border border-success/30 px-2";
+    }
+    if (selectedAnswer === answerUid && !answer?.isCorrect) {
+      return "bg-destructive/10 border border-destructive/30 px-2";
+    }
+    return "px-2";
+  };
+
+  return (
+    <div className="flex flex-col gap-4">
+      <div dangerouslySetInnerHTML={{ __html: question.content }} />
+
+      <div className="flex flex-col gap-2">
+        {sortedAnswers.map((answer) => (
+          <div
+            key={answer.uid}
+            className={cn("rounded-md transition-colors", getAnswerClasses(answer.uid))}
+          >
+            <label className="flex items-center gap-2 cursor-pointer py-1 has-[input:disabled]:cursor-default has-[input:disabled]:opacity-60">
+              <input
+                type="radio"
+                name={question.uid}
+                value={answer.uid}
+                checked={selectedAnswer === answer.uid}
+                onChange={() => handleChange(answer.uid)}
+                disabled={readOnly || disabled}
+                className="accent-primary m-0 shrink-0"
+              />
+              <span dangerouslySetInnerHTML={{ __html: answer.content }} />
+            </label>
+          </div>
+        ))}
+      </div>
+
+      {showCorrectAnswers && question.explanation && (
+        <Alert className="mt-2">
+          <AlertDescription>
+            <strong>Explanation:</strong>{" "}
+            <span dangerouslySetInnerHTML={{ __html: question.explanation }} />
+          </AlertDescription>
+        </Alert>
+      )}
+    </div>
+  );
+};

package/src/questions/essay.tsx

@@ -0,0 +1,59 @@
+import { useState, useEffect, useCallback } from "react";
+import { debounce } from "../utils/debounce";
+import { Textarea } from "../ui/textarea";
+import type { QuestionProps } from "./types";
+
+/**
+ * Essay renders a long-form text input question with a multiline textarea.
+ *
+ * @example
+ * <Essay
+ *   question={question}
+ *   onAnswer={(answers) => handleAnswer(answers)}
+ * />
+ */
+export const Essay = ({
+  question,
+  sessionAnswers,
+  onAnswer,
+  readOnly = false,
+  disabled = false,
+}: QuestionProps) => {
+  const [value, setValue] = useState("");
+
+  const debouncedAnswer = useCallback(
+    debounce((content: string) => {
+      onAnswer?.([
+        {
+          uid: question.answers?.[0]?.uid || question.uid,
+          content,
+        },
+      ]);
+    }, 500),
+    [onAnswer, question.answers, question.uid],
+  );
+
+  const handleChange = (e: React.ChangeEvent<HTMLTextAreaElement>) => {
+    const newValue = e.target.value;
+    setValue(newValue);
+    debouncedAnswer(newValue);
+  };
+
+  useEffect(() => {
+    setValue(sessionAnswers?.[0]?.content || "");
+  }, [sessionAnswers]);
+
+  return (
+    <div className="flex flex-col gap-2">
+      <div dangerouslySetInnerHTML={{ __html: question.content }} />
+
+      <Textarea
+        className="min-h-30 resize-y"
+        value={value}
+        onChange={handleChange}
+        placeholder="Write your response here..."
+        disabled={readOnly || disabled}
+      />
+    </div>
+  );
+};

package/src/questions/fill-in-the-blank.tsx

@@ -0,0 +1,69 @@
+import { useState, useEffect, useCallback } from "react";
+import { debounce } from "../utils/debounce";
+import { Input } from "../ui/input";
+import { Alert, AlertDescription } from "../ui/alert";
+import type { QuestionProps } from "./types";
+
+/**
+ * FillInTheBlank renders a short text input question with debounced answer submission.
+ *
+ * @example
+ * <FillInTheBlank
+ *   question={question}
+ *   onAnswer={(answers) => handleAnswer(answers)}
+ * />
+ */
+export const FillInTheBlank = ({
+  question,
+  sessionAnswers,
+  onAnswer,
+  readOnly = false,
+  showCorrectAnswers = false,
+  disabled = false,
+}: QuestionProps) => {
+  const [value, setValue] = useState("");
+
+  const debouncedAnswer = useCallback(
+    debounce((content: string) => {
+      onAnswer?.([
+        {
+          uid: question.answers?.[0]?.uid || "",
+          content,
+        },
+      ]);
+    }, 300),
+    [onAnswer, question.answers],
+  );
+
+  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    const newValue = e.target.value;
+    setValue(newValue);
+    debouncedAnswer(newValue);
+  };
+
+  useEffect(() => {
+    setValue(sessionAnswers?.[0]?.content || "");
+  }, [sessionAnswers]);
+
+  return (
+    <div className="flex flex-col gap-2">
+      <div dangerouslySetInnerHTML={{ __html: question.content }} />
+
+      <Input
+        value={value}
+        onChange={handleChange}
+        placeholder="Type your answer here..."
+        disabled={readOnly || disabled}
+      />
+
+      {showCorrectAnswers && question.explanation && (
+        <Alert className="mt-1">
+          <AlertDescription>
+            <strong>Explanation:</strong>{" "}
+            <span dangerouslySetInnerHTML={{ __html: question.explanation }} />
+          </AlertDescription>
+        </Alert>
+      )}
+    </div>
+  );
+};

package/src/questions/index.ts

@@ -0,0 +1,14 @@
+export { QuestionRenderer } from "./question-renderer";
+export { MultipleChoice } from "./multiple-choice";
+export { Choice } from "./choice";
+export { TrueFalse } from "./true-false";
+export { FillInTheBlank } from "./fill-in-the-blank";
+export { Essay } from "./essay";
+
+export type {
+  QuestionProps,
+  QuestionData,
+  QuestionTypeEnum,
+  AnswerOption,
+  SessionAnswer,
+} from "./types";

package/src/questions/multiple-choice.test.tsx

@@ -0,0 +1,104 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { MultipleChoice } from "./multiple-choice";
+import type { QuestionData } from "./types";
+
+const mockQuestion: QuestionData = {
+  uid: "q1",
+  type: "multiple_choice",
+  content: "<p>Select all prime numbers.</p>",
+  explanation: "<p>2 and 7 are prime.</p>",
+  answers: [
+    { uid: "a1", content: "2", isCorrect: true, sequence: 1 },
+    { uid: "a2", content: "4", isCorrect: false, sequence: 2 },
+    { uid: "a3", content: "7", isCorrect: true, sequence: 3 },
+    { uid: "a4", content: "9", isCorrect: false, sequence: 4 },
+  ],
+};
+
+describe("MultipleChoice", () => {
+  it("renders question content and all choices", () => {
+    render(<MultipleChoice question={mockQuestion} />);
+    expect(screen.getByText("Select all prime numbers.")).toBeInTheDocument();
+    expect(screen.getByText("2")).toBeInTheDocument();
+    expect(screen.getByText("4")).toBeInTheDocument();
+    expect(screen.getByText("7")).toBeInTheDocument();
+    expect(screen.getByText("9")).toBeInTheDocument();
+  });
+
+  it("renders checkboxes", () => {
+    render(<MultipleChoice question={mockQuestion} />);
+    const checkboxes = screen.getAllByRole("checkbox");
+    expect(checkboxes).toHaveLength(4);
+  });
+
+  it("calls onAnswer when selecting an option", async () => {
+    const onAnswer = vi.fn();
+    const user = userEvent.setup();
+
+    render(<MultipleChoice question={mockQuestion} onAnswer={onAnswer} />);
+    await user.click(screen.getByText("2"));
+
+    expect(onAnswer).toHaveBeenCalledWith([{ uid: "a1" }]);
+  });
+
+  it("supports selecting multiple options", async () => {
+    const onAnswer = vi.fn();
+    const user = userEvent.setup();
+
+    render(<MultipleChoice question={mockQuestion} onAnswer={onAnswer} />);
+    await user.click(screen.getByText("2"));
+    await user.click(screen.getByText("7"));
+
+    expect(onAnswer).toHaveBeenLastCalledWith([
+      { uid: "a1" },
+      { uid: "a3" },
+    ]);
+  });
+
+  it("deselects an answer on second click", async () => {
+    const onAnswer = vi.fn();
+    const user = userEvent.setup();
+
+    render(<MultipleChoice question={mockQuestion} onAnswer={onAnswer} />);
+    await user.click(screen.getByText("2"));
+    await user.click(screen.getByText("2"));
+
+    expect(onAnswer).toHaveBeenLastCalledWith([]);
+  });
+
+  it("disables inputs when readOnly", () => {
+    render(<MultipleChoice question={mockQuestion} readOnly />);
+    const checkboxes = screen.getAllByRole("checkbox");
+    checkboxes.forEach((cb) => expect(cb).toBeDisabled());
+  });
+
+  it("disables inputs when disabled", () => {
+    render(<MultipleChoice question={mockQuestion} disabled />);
+    const checkboxes = screen.getAllByRole("checkbox");
+    checkboxes.forEach((cb) => expect(cb).toBeDisabled());
+  });
+
+  it("shows explanation when showCorrectAnswers is true", () => {
+    render(<MultipleChoice question={mockQuestion} showCorrectAnswers />);
+    expect(screen.getByText("Explanation:")).toBeInTheDocument();
+    expect(screen.getByText("2 and 7 are prime.")).toBeInTheDocument();
+  });
+
+  it("pre-selects answers from sessionAnswers", () => {
+    render(
+      <MultipleChoice
+        question={mockQuestion}
+        sessionAnswers={[
+          { uid: "sa1", answerUid: "a1" },
+          { uid: "sa2", answerUid: "a3" },
+        ]}
+      />,
+    );
+    const checkboxes = screen.getAllByRole("checkbox");
+    expect(checkboxes[0]).toBeChecked();
+    expect(checkboxes[1]).not.toBeChecked();
+    expect(checkboxes[2]).toBeChecked();
+    expect(checkboxes[3]).not.toBeChecked();
+  });
+});

package/src/questions/multiple-choice.tsx

@@ -0,0 +1,97 @@
+import { useState, useEffect } from "react";
+import type { QuestionProps } from "./types";
+import { Alert, AlertDescription } from "../ui/alert";
+import { cn } from "../lib/utils";
+
+/**
+ * MultipleChoice renders a question with multiple correct answers using checkboxes.
+ *
+ * @example
+ * <MultipleChoice
+ *   question={question}
+ *   onAnswer={(answers) => handleAnswer(answers)}
+ * />
+ */
+export const MultipleChoice = ({
+  question,
+  sessionAnswers,
+  onAnswer,
+  readOnly = false,
+  showCorrectAnswers = false,
+  disabled = false,
+}: QuestionProps) => {
+  const [selectedAnswers, setSelectedAnswers] = useState<string[]>([]);
+
+  const sortedAnswers = [...(question.answers || [])].sort(
+    (a, b) => a.sequence - b.sequence,
+  );
+
+  const handleChange = (uid: string) => {
+    if (readOnly || disabled) return;
+
+    setSelectedAnswers((prev) => {
+      const newSelected = prev.includes(uid)
+        ? prev.filter((id) => id !== uid)
+        : [...prev, uid];
+
+      onAnswer?.(newSelected.map((id) => ({ uid: id })));
+      return newSelected;
+    });
+  };
+
+  useEffect(() => {
+    const current = sessionAnswers?.map((sa) => sa.answerUid) || [];
+    setSelectedAnswers(current);
+  }, [sessionAnswers]);
+
+  const getAnswerClasses = (answerUid: string) => {
+    if (!showCorrectAnswers) return "";
+
+    const answer = question.answers?.find((a) => a.uid === answerUid);
+    if (answer?.isCorrect) {
+      return "bg-success/10 border border-success/30 px-2";
+    }
+    if (selectedAnswers.includes(answerUid) && !answer?.isCorrect) {
+      return "bg-destructive/10 border border-destructive/30 px-2";
+    }
+    return "";
+  };
+
+  return (
+    <div className="flex flex-col gap-4">
+      <div dangerouslySetInnerHTML={{ __html: question.content }} />
+
+      <div className="flex flex-col gap-2">
+        {sortedAnswers.map((answer) => (
+          <div
+            key={answer.uid}
+            className={cn("rounded-md transition-colors", getAnswerClasses(answer.uid))}
+          >
+            <label className="flex items-center gap-2 cursor-pointer py-1 has-[input:disabled]:cursor-default has-[input:disabled]:opacity-60">
+              <input
+                type="checkbox"
+                checked={selectedAnswers.includes(answer.uid)}
+                onChange={() => handleChange(answer.uid)}
+                disabled={readOnly || disabled}
+                className="accent-primary m-0 shrink-0"
+              />
+              <span
+                className="text-sm"
+                dangerouslySetInnerHTML={{ __html: answer.content }}
+              />
+            </label>
+          </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

@@ -0,0 +1,37 @@
+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";
+
+/**
+ * QuestionRenderer dispatches to the appropriate question component based on question type.
+ *
+ * @example
+ * <QuestionRenderer
+ *   question={question}
+ *   sessionAnswers={answers}
+ *   onAnswer={handleAnswer}
+ * />
+ */
+export const QuestionRenderer = (props: QuestionProps) => {
+  switch (props.question.type) {
+    case "multiple_choice":
+      return <MultipleChoice {...props} />;
+    case "choice":
+      return <Choice {...props} />;
+    case "true_false":
+      return <TrueFalse {...props} />;
+    case "fill_in_the_blank":
+      return <FillInTheBlank {...props} />;
+    case "essay":
+      return <Essay {...props} />;
+    default:
+      return (
+        <p className="text-muted-foreground">
+          Question type &ldquo;{props.question.type}&rdquo; is not supported yet.
+        </p>
+      );
+  }
+};

package/src/questions/true-false.test.tsx

@@ -0,0 +1,89 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { TrueFalse } from "./true-false";
+import type { QuestionData } from "./types";
+
+const mockQuestion: QuestionData = {
+  uid: "q1",
+  type: "true_false",
+  content: "<p>The sky is blue.</p>",
+  explanation: "<p>Due to Rayleigh scattering.</p>",
+  answers: [
+    { uid: "a1", content: "True", isCorrect: true, sequence: 1 },
+    { uid: "a2", content: "False", isCorrect: false, sequence: 2 },
+  ],
+};
+
+describe("TrueFalse", () => {
+  it("renders question content and both options", () => {
+    render(<TrueFalse question={mockQuestion} />);
+    expect(screen.getByText("The sky is blue.")).toBeInTheDocument();
+    expect(screen.getByText("True")).toBeInTheDocument();
+    expect(screen.getByText("False")).toBeInTheDocument();
+  });
+
+  it("renders radio inputs", () => {
+    render(<TrueFalse question={mockQuestion} />);
+    const radios = screen.getAllByRole("radio");
+    expect(radios).toHaveLength(2);
+  });
+
+  it("calls onAnswer when an option is selected", async () => {
+    const onAnswer = vi.fn();
+    const user = userEvent.setup();
+
+    render(<TrueFalse question={mockQuestion} onAnswer={onAnswer} />);
+    await user.click(screen.getByText("True"));
+
+    expect(onAnswer).toHaveBeenCalledWith([{ uid: "a1" }]);
+  });
+
+  it("disables inputs when readOnly is true", () => {
+    render(<TrueFalse question={mockQuestion} readOnly />);
+    const radios = screen.getAllByRole("radio");
+    radios.forEach((radio) => expect(radio).toBeDisabled());
+  });
+
+  it("disables inputs when disabled is true", () => {
+    render(<TrueFalse question={mockQuestion} disabled />);
+    const radios = screen.getAllByRole("radio");
+    radios.forEach((radio) => expect(radio).toBeDisabled());
+  });
+
+  it("shows explanation when showCorrectAnswers is true", () => {
+    render(<TrueFalse question={mockQuestion} showCorrectAnswers />);
+    expect(screen.getByText("Explanation:")).toBeInTheDocument();
+    expect(screen.getByText("Due to Rayleigh scattering.")).toBeInTheDocument();
+  });
+
+  it("does not show explanation when showCorrectAnswers is false", () => {
+    render(<TrueFalse question={mockQuestion} showCorrectAnswers={false} />);
+    expect(screen.queryByText("Explanation:")).not.toBeInTheDocument();
+  });
+
+  it("pre-selects answer from sessionAnswers", () => {
+    render(
+      <TrueFalse
+        question={mockQuestion}
+        sessionAnswers={[{ uid: "sa1", answerUid: "a1" }]}
+      />,
+    );
+    const radios = screen.getAllByRole("radio");
+    expect(radios[0]).toBeChecked();
+  });
+
+  it("sorts answers by sequence", () => {
+    const reversed: QuestionData = {
+      ...mockQuestion,
+      answers: [
+        { uid: "a2", content: "False", isCorrect: false, sequence: 2 },
+        { uid: "a1", content: "True", isCorrect: true, sequence: 1 },
+      ],
+    };
+
+    render(<TrueFalse question={reversed} />);
+    const radios = screen.getAllByRole("radio");
+    const labels = radios.map((r) => r.closest("label")?.textContent);
+    expect(labels).toEqual(["True", "False"]);
+  });
+});

package/src/questions/true-false.tsx

@@ -0,0 +1,90 @@
+import { useState, useEffect } from "react";
+import type { QuestionProps } from "./types";
+import { Alert, AlertDescription } from "../ui/alert";
+import { cn } from "../lib/utils";
+
+/**
+ * TrueFalse renders a true/false question with two radio button options.
+ *
+ * @example
+ * <TrueFalse
+ *   question={question}
+ *   onAnswer={(answers) => handleAnswer(answers)}
+ * />
+ */
+export const TrueFalse = ({
+  question,
+  sessionAnswers,
+  onAnswer,
+  readOnly = false,
+  showCorrectAnswers = false,
+  disabled = false,
+}: QuestionProps) => {
+  const [selectedAnswer, setSelectedAnswer] = useState<string>("");
+
+  const sortedAnswers = [...(question.answers || [])].sort(
+    (a, b) => a.sequence - b.sequence,
+  );
+
+  const handleChange = (uid: string) => {
+    if (readOnly || disabled) return;
+
+    setSelectedAnswer(uid);
+    onAnswer?.([{ uid }]);
+  };
+
+  useEffect(() => {
+    const current = sessionAnswers?.[0]?.answerUid || "";
+    setSelectedAnswer(current);
+  }, [sessionAnswers]);
+
+  const getAnswerClasses = (answerUid: string) => {
+    if (!showCorrectAnswers) return "px-2";
+
+    const answer = question.answers?.find((a) => a.uid === answerUid);
+    if (answer?.isCorrect) {
+      return "bg-success/10 border border-success/30 px-2";
+    }
+    if (selectedAnswer === answerUid && !answer?.isCorrect) {
+      return "bg-destructive/10 border border-destructive/30 px-2";
+    }
+    return "px-2";
+  };
+
+  return (
+    <div className="flex flex-col gap-4">
+      <div dangerouslySetInnerHTML={{ __html: question.content }} />
+
+      <div className="flex flex-col gap-2">
+        {sortedAnswers.map((answer) => (
+          <div
+            key={answer.uid}
+            className={cn("rounded-md transition-colors", getAnswerClasses(answer.uid))}
+          >
+            <label className="flex items-center gap-2 cursor-pointer py-1 has-[input:disabled]:cursor-default has-[input:disabled]:opacity-60">
+              <input
+                type="radio"
+                name={question.uid}
+                value={answer.uid}
+                checked={selectedAnswer === answer.uid}
+                onChange={() => handleChange(answer.uid)}
+                disabled={readOnly || disabled}
+                className="accent-primary m-0 shrink-0"
+              />
+              <span dangerouslySetInnerHTML={{ __html: answer.content }} />
+            </label>
+          </div>
+        ))}
+      </div>
+
+      {showCorrectAnswers && question.explanation && (
+        <Alert className="mt-2">
+          <AlertDescription>
+            <strong>Explanation:</strong>{" "}
+            <span dangerouslySetInnerHTML={{ __html: question.explanation }} />
+          </AlertDescription>
+        </Alert>
+      )}
+    </div>
+  );
+};