@hydralms/components 0.1.0 → 0.1.2

package/src/modules/FlashcardLab/types.ts

@@ -0,0 +1,58 @@
+import type { FlashcardData } from "../../flashcards/types";
+
+/**
+ * FlashcardLab — a guided multi-step flashcard study session.
+ *
+ * Steps: Setup (deck selection) -> Study -> Completion
+ *
+ * Composes FlashcardStudySession, Card, Button, Badge, StatCard, ProgressRing.
+ *
+ * @example
+ * <FlashcardLab
+ *   decks={[
+ *     { uid: "d1", title: "React Basics", cards: reactCards },
+ *     { uid: "d2", title: "TypeScript", cards: tsCards },
+ *   ]}
+ *   onComplete={(result) => trackStudy(result)}
+ * />
+ */
+export interface FlashcardLabProps {
+  /** Available decks for the user to choose from */
+  decks: FlashcardDeckOption[];
+  /** Whether to show a shuffle toggle on the setup screen. @default true */
+  showShuffleToggle?: boolean;
+  /** Default shuffle setting. @default false */
+  defaultShuffled?: boolean;
+  /** Whether the user can select multiple decks to combine. @default true */
+  allowMultiSelect?: boolean;
+  /** Called when the user completes a study session */
+  onComplete?: (result: FlashcardLabResult) => void;
+  /** CSS class name for the root element */
+  className?: string;
+  /** Inline styles for the root element */
+  style?: React.CSSProperties;
+}
+
+export interface FlashcardDeckOption {
+  /** Unique deck identifier */
+  uid: string;
+  /** Deck title */
+  title: string;
+  /** Optional description */
+  description?: string;
+  /** The flashcard data */
+  cards: FlashcardData[];
+}
+
+export interface FlashcardLabResult {
+  /** Total cards studied */
+  totalCards: number;
+  /** Number of decks selected */
+  decksStudied: number;
+  /** UIDs of the decks that were studied */
+  deckUids: string[];
+  /** Whether cards were shuffled */
+  wasShuffled: boolean;
+  /** Total time spent studying in seconds */
+  timeElapsedSeconds: number;
+}

package/src/modules/QuizModule/QuizModule.tsx

@@ -0,0 +1,241 @@
+import { useState, useRef, useEffect } from "react";
+import {
+  Play,
+  RotateCcw,
+  Clock,
+  HelpCircle,
+  CheckCircle2,
+  XCircle,
+  Trophy,
+} from "lucide-react";
+import { QuizSession } from "../../sections/QuizSession/QuizSession";
+import { AssessmentReview } from "../../sections/AssessmentReview/AssessmentReview";
+import { ProgressRing } from "../../progress/progress-ring";
+import { StatCard } from "../../progress/stat-card";
+import { Button } from "../../ui/button";
+import { Badge } from "../../ui/badge";
+import { Card, CardContent } from "../../ui/card";
+import { formatDuration } from "../../utils/format-duration";
+import { cn } from "../../lib/utils";
+import type { SessionAnswer } from "../../questions/types";
+import type { QuizModuleProps, QuizModuleResult } from "./types";
+
+type InternalStep =
+  | { tag: "intro" }
+  | { tag: "quiz" }
+  | { tag: "results"; result: QuizModuleResult };
+
+export function QuizModule({
+  title,
+  description,
+  questions,
+  timeLimitSeconds,
+  passingScore,
+  allowRetake = true,
+  onComplete,
+  showReview = true,
+  className,
+  style,
+}: QuizModuleProps) {
+  const [step, setStep] = useState<InternalStep>({ tag: "intro" });
+  const [timeElapsed, setTimeElapsed] = useState(0);
+  const startTimeRef = useRef<number | null>(null);
+  const intervalRef = useRef<ReturnType<typeof setInterval> | null>(null);
+
+  // Timer for quiz step
+  useEffect(() => {
+    if (step.tag === "quiz") {
+      startTimeRef.current = Date.now();
+      intervalRef.current = setInterval(() => {
+        if (startTimeRef.current) {
+          setTimeElapsed(Math.floor((Date.now() - startTimeRef.current) / 1000));
+        }
+      }, 1000);
+    } else {
+      if (intervalRef.current) {
+        clearInterval(intervalRef.current);
+        intervalRef.current = null;
+      }
+    }
+    return () => {
+      if (intervalRef.current) clearInterval(intervalRef.current);
+    };
+  }, [step.tag]);
+
+  function scoreAnswers(answers: SessionAnswer[]): QuizModuleResult {
+    let correct = 0;
+    for (const q of questions) {
+      const userAnswers = answers.filter((a) => a.uid === q.uid);
+      const correctUids = new Set(
+        (q.answers ?? []).filter((a) => a.isCorrect).map((a) => a.uid),
+      );
+      const userUids = new Set(userAnswers.map((a) => a.answerUid));
+
+      if (
+        correctUids.size > 0 &&
+        correctUids.size === userUids.size &&
+        [...correctUids].every((uid) => userUids.has(uid))
+      ) {
+        correct++;
+      }
+    }
+
+    const total = questions.length;
+    const percentage = total > 0 ? Math.round((correct / total) * 100) : 0;
+    const elapsed = startTimeRef.current
+      ? Math.floor((Date.now() - startTimeRef.current) / 1000)
+      : timeElapsed;
+
+    return {
+      answers,
+      correct,
+      total,
+      percentage,
+      passed: passingScore !== undefined ? percentage >= passingScore : true,
+      timeElapsedSeconds: elapsed,
+    };
+  }
+
+  function handleSubmit(answers: SessionAnswer[]) {
+    const result = scoreAnswers(answers);
+    setStep({ tag: "results", result });
+    onComplete?.(result);
+  }
+
+  function handleRetake() {
+    setTimeElapsed(0);
+    startTimeRef.current = null;
+    setStep({ tag: "intro" });
+  }
+
+  // ─── Intro Screen ───
+  if (step.tag === "intro") {
+    return (
+      <div className={cn("max-w-2xl mx-auto", className)} style={style}>
+        <Card>
+          <CardContent className="pt-8 pb-8 text-center">
+            <div className="mx-auto mb-4 w-14 h-14 rounded-full bg-primary/10 flex items-center justify-center">
+              <Trophy className="size-7 text-primary" />
+            </div>
+            <h2 className="text-2xl font-bold text-foreground mb-2">{title}</h2>
+            {description && (
+              <p className="text-muted-foreground mb-6 max-w-md mx-auto">
+                {description}
+              </p>
+            )}
+            <div className="flex flex-wrap justify-center gap-4 mb-8">
+              <div className="flex items-center gap-2 text-sm text-muted-foreground">
+                <HelpCircle className="size-4" />
+                <span>{questions.length} questions</span>
+              </div>
+              {timeLimitSeconds && (
+                <div className="flex items-center gap-2 text-sm text-muted-foreground">
+                  <Clock className="size-4" />
+                  <span>{formatDuration(timeLimitSeconds)} time limit</span>
+                </div>
+              )}
+              {passingScore !== undefined && (
+                <div className="flex items-center gap-2 text-sm text-muted-foreground">
+                  <CheckCircle2 className="size-4" />
+                  <span>{passingScore}% to pass</span>
+                </div>
+              )}
+            </div>
+            <Button size="lg" onClick={() => setStep({ tag: "quiz" })}>
+              <Play className="size-4 mr-2" />
+              Start Quiz
+            </Button>
+          </CardContent>
+        </Card>
+      </div>
+    );
+  }
+
+  // ─── Quiz Screen ───
+  if (step.tag === "quiz") {
+    return (
+      <div className={cn(className)} style={style}>
+        <QuizSession
+          questions={questions}
+          onSubmit={handleSubmit}
+          timeElapsedSeconds={timeElapsed}
+          timeLimitSeconds={timeLimitSeconds}
+        />
+      </div>
+    );
+  }
+
+  // ─── Results Screen ───
+  const { result } = step;
+  const passed = result.passed;
+
+  return (
+    <div className={cn(className)} style={style}>
+      {/* Score summary */}
+      <div className="text-center mb-8">
+        <ProgressRing
+          value={result.percentage}
+          size={140}
+          strokeWidth={10}
+          color={passed ? "var(--success)" : "var(--destructive)"}
+          className="mx-auto mb-4 text-foreground"
+        />
+        <Badge
+          variant={passed ? "success" : "destructive"}
+          className="text-sm px-3 py-1 mb-2"
+        >
+          {passed ? "Passed" : "Failed"}
+        </Badge>
+        <h2 className="text-xl font-bold text-foreground">{title}</h2>
+      </div>
+
+      {/* Stats grid */}
+      <div className="grid grid-cols-2 sm:grid-cols-4 gap-3 mb-8">
+        <StatCard
+          icon={<CheckCircle2 />}
+          label="Correct"
+          value={`${result.correct}/${result.total}`}
+        />
+        <StatCard
+          icon={<XCircle />}
+          label="Incorrect"
+          value={`${result.total - result.correct}/${result.total}`}
+        />
+        <StatCard
+          icon={<Trophy />}
+          label="Score"
+          value={`${result.percentage}%`}
+        />
+        <StatCard
+          icon={<Clock />}
+          label="Time"
+          value={formatDuration(result.timeElapsedSeconds)}
+        />
+      </div>
+
+      {/* Actions */}
+      {allowRetake && (
+        <div className="flex justify-center mb-8">
+          <Button variant="outline" onClick={handleRetake}>
+            <RotateCcw className="size-4 mr-2" />
+            Retake Quiz
+          </Button>
+        </div>
+      )}
+
+      {/* Per-question review */}
+      {showReview && (
+        <div>
+          <h3 className="text-lg font-semibold text-foreground mb-4">
+            Question Review
+          </h3>
+          <AssessmentReview
+            questions={questions}
+            sessionAnswers={result.answers}
+            showCorrectAnswers
+          />
+        </div>
+      )}
+    </div>
+  );
+}

package/src/modules/QuizModule/types.ts

@@ -0,0 +1,56 @@
+import type { QuestionData, SessionAnswer } from "../../questions/types";
+
+/**
+ * QuizModule — a complete multi-step assessment experience.
+ *
+ * Steps: Intro -> Quiz -> Results/Review
+ *
+ * Composes QuizSession, AssessmentReview, ProgressRing, StatCard, Card, and Button.
+ *
+ * @example
+ * <QuizModule
+ *   title="React Hooks Quiz"
+ *   description="Test your knowledge of React hooks"
+ *   questions={questions}
+ *   passingScore={70}
+ *   timeLimitSeconds={600}
+ *   onComplete={(result) => saveResult(result)}
+ * />
+ */
+export interface QuizModuleProps {
+  /** Quiz title displayed on the intro screen */
+  title: string;
+  /** Quiz description displayed on the intro screen */
+  description?: string;
+  /** Ordered list of questions */
+  questions: QuestionData[];
+  /** Time limit in seconds — when provided, shows countdown info on intro and enables timer */
+  timeLimitSeconds?: number;
+  /** Passing threshold as a percentage (e.g. 70 means 70%). Determines pass/fail on results. */
+  passingScore?: number;
+  /** Whether to allow retaking the quiz from the results screen. @default true */
+  allowRetake?: boolean;
+  /** Called when the user completes the quiz (submits answers) */
+  onComplete?: (result: QuizModuleResult) => void;
+  /** Whether to show correct/incorrect answer highlighting in the review. @default true */
+  showReview?: boolean;
+  /** CSS class name for the root element */
+  className?: string;
+  /** Inline styles for the root element */
+  style?: React.CSSProperties;
+}
+
+export interface QuizModuleResult {
+  /** The user's submitted answers */
+  answers: SessionAnswer[];
+  /** Number of correct answers */
+  correct: number;
+  /** Total number of questions */
+  total: number;
+  /** Score as a percentage (0-100) */
+  percentage: number;
+  /** Whether the user passed (only meaningful when passingScore is set) */
+  passed: boolean;
+  /** Total time taken in seconds */
+  timeElapsedSeconds: number;
+}

package/src/modules/index.ts

@@ -0,0 +1,12 @@
+export { QuizModule } from "./QuizModule/QuizModule";
+export type { QuizModuleProps, QuizModuleResult } from "./QuizModule/types";
+
+export { FlashcardLab } from "./FlashcardLab/FlashcardLab";
+export type {
+  FlashcardLabProps,
+  FlashcardDeckOption,
+  FlashcardLabResult,
+} from "./FlashcardLab/types";
+
+export { CoursePlayer } from "./CoursePlayer/CoursePlayer";
+export type { CoursePlayerProps, CoursePlayerItem } from "./CoursePlayer/types";

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";