@hydralms/components 0.1.1 → 0.1.2

package/src/progress/grade-indicator.tsx

@@ -0,0 +1,65 @@
+import { ProgressRing } from "./progress-ring";
+import type { GradeIndicatorProps } from "./types";
+import { cn } from "../lib/utils";
+
+const SIZES = { small: 48, medium: 64, large: 96 };
+const FONT_SIZES = { small: "0.75rem", medium: "0.875rem", large: "1rem" };
+const TRACK_HEIGHTS = { small: "4px", medium: "6px", large: "8px" };
+
+const COLOR_MAP: Record<string, string> = {
+  primary: "var(--primary)",
+  success: "var(--success)",
+  warning: "var(--warning)",
+  destructive: "var(--destructive)",
+};
+
+function getColor(percentage: number, threshold?: number): string {
+  if (threshold == null) return "primary";
+  if (percentage >= threshold) return "success";
+  if (percentage >= threshold * 0.7) return "warning";
+  return "destructive";
+}
+
+export function GradeIndicator({
+  percentage,
+  letterGrade,
+  variant = "circular",
+  size = "medium",
+  passingThreshold,
+  showLabel = true,
+  className,
+  style,
+}: GradeIndicatorProps) {
+  const colorKey = getColor(percentage, passingThreshold);
+  const color = COLOR_MAP[colorKey] ?? "var(--primary)";
+
+  if (variant === "linear") {
+    return (
+      <div className={cn("flex flex-row items-center gap-1", className)} style={style}>
+        <div className="flex-1 bg-muted rounded-full overflow-hidden" style={{ height: TRACK_HEIGHTS[size] }}>
+          <div
+            className="h-full rounded-full transition-[width] duration-300 ease-in-out"
+            style={{ width: `${percentage}%`, background: color }}
+          />
+        </div>
+        {showLabel && (
+          <span className="font-semibold min-w-9" style={{ fontSize: FONT_SIZES[size] }}>
+            {letterGrade ?? `${Math.round(percentage)}%`}
+          </span>
+        )}
+      </div>
+    );
+  }
+
+  return (
+    <div className={cn("inline-flex flex-col items-center", className)} style={style}>
+      <ProgressRing
+        value={percentage}
+        size={SIZES[size]}
+        strokeWidth={size === "small" ? 4 : 6}
+        color={color}
+        label={letterGrade ?? `${Math.round(percentage)}%`}
+      />
+    </div>
+  );
+}

package/src/progress/index.ts

@@ -0,0 +1,8 @@
+export { ProgressRing } from "./progress-ring";
+export { GradeIndicator } from "./grade-indicator";
+export { StatCard } from "./stat-card";
+export type {
+  ProgressRingProps,
+  GradeIndicatorProps,
+  StatCardProps,
+} from "./types";

package/src/progress/progress-ring.tsx

@@ -0,0 +1,56 @@
+import type { ProgressRingProps } from "./types";
+import { cn } from "../lib/utils";
+
+export function ProgressRing({
+  value,
+  size = 120,
+  strokeWidth = 8,
+  label,
+  color,
+  className,
+  style,
+}: ProgressRingProps) {
+  const radius = (size - strokeWidth) / 2;
+  const circumference = 2 * Math.PI * radius;
+  const offset =
+    circumference - (Math.min(Math.max(value, 0), 100) / 100) * circumference;
+  const center = size / 2;
+
+  return (
+    <div
+      className={cn("relative inline-flex", className)}
+      style={{ width: `${size}px`, height: `${size}px`, ...style }}
+    >
+      <svg width={size} height={size}>
+        <circle
+          cx={center}
+          cy={center}
+          r={radius}
+          fill="none"
+          stroke="currentColor"
+          strokeWidth={strokeWidth}
+          opacity={0.15}
+        />
+        <circle
+          cx={center}
+          cy={center}
+          r={radius}
+          fill="none"
+          stroke={color ?? "currentColor"}
+          strokeWidth={strokeWidth}
+          strokeDasharray={circumference}
+          strokeDashoffset={offset}
+          strokeLinecap="round"
+          transform={`rotate(-90 ${center} ${center})`}
+          style={{ transition: "stroke-dashoffset 0.4s ease" }}
+        />
+      </svg>
+      <span
+        className="absolute inset-0 flex items-center justify-center font-bold text-foreground"
+        style={{ fontSize: `${size * 0.2}px` }}
+      >
+        {label ?? `${Math.round(value)}%`}
+      </span>
+    </div>
+  );
+}

package/src/progress/stat-card.tsx

@@ -0,0 +1,42 @@
+import { TrendingUp, TrendingDown, Minus } from "lucide-react";
+import type { StatCardProps } from "./types";
+import { cn } from "../lib/utils";
+
+const TREND_COLORS = {
+  up: "var(--success)",
+  down: "var(--destructive)",
+  flat: "var(--muted-foreground)",
+};
+const TREND_ICONS = { up: TrendingUp, down: TrendingDown, flat: Minus };
+
+export function StatCard({
+  icon,
+  label,
+  value,
+  subtitle,
+  trend,
+  className,
+  style,
+}: StatCardProps) {
+  const TrendIcon = trend ? TREND_ICONS[trend.direction] : null;
+
+  return (
+    <div className={cn("rounded-md border border-border p-4", className)} style={style}>
+      {icon && <div className="mb-1 text-primary [&>svg]:size-6">{icon}</div>}
+      <span className="text-xs text-muted-foreground">{label}</span>
+      <div className="flex flex-row items-baseline gap-1">
+        <span className="text-2xl font-bold">{value}</span>
+        {trend && TrendIcon && (
+          <span className="flex flex-row items-center gap-px" style={{ color: TREND_COLORS[trend.direction] }}>
+            <TrendIcon size={14} />
+            <span className="text-xs font-semibold">
+              {trend.value > 0 ? "+" : ""}
+              {trend.value}%
+            </span>
+          </span>
+        )}
+      </div>
+      {subtitle && <span className="text-xs text-muted-foreground">{subtitle}</span>}
+    </div>
+  );
+}

package/src/progress/types.ts

@@ -0,0 +1,73 @@
+import type { ReactNode } from "react";
+
+/**
+ * ProgressRing renders a circular SVG progress indicator with a centered label.
+ *
+ * @example
+ * <ProgressRing value={75} size={120} />
+ */
+export interface ProgressRingProps {
+  /** Progress value from 0 to 100 */
+  value: number;
+  /** Diameter of the ring in pixels */
+  size?: number;
+  /** Stroke width in pixels */
+  strokeWidth?: number;
+  /** Override text in the center of the ring */
+  label?: string;
+  /** Ring color — defaults to the theme primary */
+  color?: string;
+  /** CSS class name for the root element */
+  className?: string;
+  /** Inline styles for the root element */
+  style?: React.CSSProperties;
+}
+
+/**
+ * GradeIndicator displays a grade as a circular or linear percentage badge
+ * with pass/fail coloring based on a configurable threshold.
+ *
+ * @example
+ * <GradeIndicator percentage={85} letterGrade="B+" passingThreshold={70} />
+ */
+export interface GradeIndicatorProps {
+  /** Grade percentage from 0 to 100 */
+  percentage: number;
+  /** Optional letter grade label */
+  letterGrade?: string;
+  /** Display variant */
+  variant?: "circular" | "linear";
+  /** Component size */
+  size?: "small" | "medium" | "large";
+  /** Below this percentage the indicator shows warning/error colors */
+  passingThreshold?: number;
+  /** Whether to show the percentage label */
+  showLabel?: boolean;
+  /** CSS class name for the root element */
+  className?: string;
+  /** Inline styles for the root element */
+  style?: React.CSSProperties;
+}
+
+/**
+ * StatCard displays a single key-value statistic with an icon and optional trend indicator.
+ *
+ * @example
+ * <StatCard label="Lessons Completed" value={12} />
+ */
+export interface StatCardProps {
+  /** Optional icon displayed at the top */
+  icon?: ReactNode;
+  /** Stat label */
+  label: string;
+  /** Stat value */
+  value: string | number;
+  /** Secondary text below the value */
+  subtitle?: string;
+  /** Optional trend data */
+  trend?: { value: number; direction: "up" | "down" | "flat" };
+  /** CSS class name for the root element */
+  className?: string;
+  /** Inline styles for the root element */
+  style?: React.CSSProperties;
+}

package/src/provider/HydraProvider.tsx

@@ -0,0 +1,26 @@
+import "../styles/globals.css";
+import type { ReactNode } from "react";
+
+export interface HydraProviderProps {
+  children: ReactNode;
+  /** Controls color mode. Defaults to `"dark"`. Set to `"light"` to use the light theme. */
+  colorMode?: "light" | "dark";
+  className?: string;
+  style?: React.CSSProperties;
+}
+
+export function HydraProvider({
+  children,
+  colorMode = "dark",
+  className,
+  style,
+}: HydraProviderProps) {
+  return (
+    <div
+      className={`hydra-root${colorMode === "dark" ? " dark" : ""}${className ? ` ${className}` : ""}`}
+      style={style}
+    >
+      {children}
+    </div>
+  );
+}

package/src/provider/index.ts

@@ -0,0 +1,2 @@
+export { HydraProvider } from "./HydraProvider";
+export type { HydraProviderProps } from "./HydraProvider";

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();
+  });
+});