@hydralms/components 0.1.1 → 0.1.2

package/src/modules/FlashcardLab/FlashcardLab.tsx

@@ -0,0 +1,275 @@
+import { useState, useRef } from "react";
+import {
+  BookOpen,
+  Shuffle,
+  RotateCcw,
+  CheckCircle2,
+  Layers,
+  Clock,
+  ArrowLeft,
+} from "lucide-react";
+import { FlashcardStudySession } from "../../sections/FlashcardStudySession/FlashcardStudySession";
+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 { FlashcardData } from "../../flashcards/types";
+import type {
+  FlashcardLabProps,
+  FlashcardLabResult,
+} from "./types";
+
+type InternalStep =
+  | { tag: "setup" }
+  | { tag: "study"; cards: FlashcardData[]; deckUids: string[]; shuffled: boolean }
+  | { tag: "completion"; result: FlashcardLabResult };
+
+export function FlashcardLab({
+  decks,
+  showShuffleToggle = true,
+  defaultShuffled = false,
+  allowMultiSelect = true,
+  onComplete,
+  className,
+  style,
+}: FlashcardLabProps) {
+  const [step, setStep] = useState<InternalStep>({ tag: "setup" });
+  const [selectedUids, setSelectedUids] = useState<Set<string>>(new Set());
+  const [shuffled, setShuffled] = useState(defaultShuffled);
+  const startTimeRef = useRef<number | null>(null);
+
+  function toggleDeck(uid: string) {
+    setSelectedUids((prev) => {
+      const next = new Set(prev);
+      if (next.has(uid)) {
+        next.delete(uid);
+      } else {
+        if (!allowMultiSelect) next.clear();
+        next.add(uid);
+      }
+      return next;
+    });
+  }
+
+  function startStudying() {
+    const selected = decks.filter((d) => selectedUids.has(d.uid));
+    const cards = selected.flatMap((d) => d.cards);
+    startTimeRef.current = Date.now();
+    setStep({
+      tag: "study",
+      cards,
+      deckUids: selected.map((d) => d.uid),
+      shuffled,
+    });
+  }
+
+  function handleStudyComplete() {
+    if (step.tag !== "study") return;
+    const elapsed = startTimeRef.current
+      ? Math.floor((Date.now() - startTimeRef.current) / 1000)
+      : 0;
+
+    const result: FlashcardLabResult = {
+      totalCards: step.cards.length,
+      decksStudied: step.deckUids.length,
+      deckUids: step.deckUids,
+      wasShuffled: step.shuffled,
+      timeElapsedSeconds: elapsed,
+    };
+    setStep({ tag: "completion", result });
+    onComplete?.(result);
+  }
+
+  function handleStudyAgain() {
+    if (step.tag !== "completion") return;
+    const selected = decks.filter((d) => step.result.deckUids.includes(d.uid));
+    const cards = selected.flatMap((d) => d.cards);
+    startTimeRef.current = Date.now();
+    setStep({
+      tag: "study",
+      cards,
+      deckUids: step.result.deckUids,
+      shuffled: step.result.wasShuffled,
+    });
+  }
+
+  function handlePickNewDeck() {
+    setSelectedUids(new Set());
+    setShuffled(defaultShuffled);
+    setStep({ tag: "setup" });
+  }
+
+  // ─── Setup Screen ───
+  if (step.tag === "setup") {
+    return (
+      <div className={cn(className)} style={style}>
+        <div className="text-center mb-6">
+          <div className="mx-auto mb-3 w-14 h-14 rounded-full bg-primary/10 flex items-center justify-center">
+            <BookOpen className="size-7 text-primary" />
+          </div>
+          <h2 className="text-2xl font-bold text-foreground mb-1">
+            Choose Your Decks
+          </h2>
+          <p className="text-muted-foreground text-sm">
+            {allowMultiSelect
+              ? "Select one or more decks to study"
+              : "Select a deck to study"}
+          </p>
+        </div>
+
+        {/* Deck grid */}
+        <div className="grid sm:grid-cols-2 lg:grid-cols-3 gap-3 mb-6">
+          {decks.map((deck) => {
+            const isSelected = selectedUids.has(deck.uid);
+            return (
+              <Card
+                key={deck.uid}
+                className={cn(
+                  "cursor-pointer transition-all py-0",
+                  isSelected
+                    ? "border-primary ring-1 ring-primary"
+                    : "hover:border-muted-foreground/30",
+                )}
+                onClick={() => toggleDeck(deck.uid)}
+              >
+                <CardContent className="py-4">
+                  <div className="flex items-start justify-between mb-2">
+                    <h3 className="font-semibold text-foreground text-sm">
+                      {deck.title}
+                    </h3>
+                    <Badge variant="secondary" className="text-xs shrink-0">
+                      {deck.cards.length} cards
+                    </Badge>
+                  </div>
+                  {deck.description && (
+                    <p className="text-xs text-muted-foreground line-clamp-2">
+                      {deck.description}
+                    </p>
+                  )}
+                </CardContent>
+              </Card>
+            );
+          })}
+        </div>
+
+        {/* Options + start */}
+        <div className="flex items-center justify-between">
+          <div className="flex items-center gap-3">
+            {showShuffleToggle && (
+              <button
+                type="button"
+                className={cn(
+                  "flex items-center gap-1.5 text-sm px-3 py-1.5 rounded-md border transition-colors",
+                  shuffled
+                    ? "border-primary bg-primary/10 text-primary"
+                    : "border-border text-muted-foreground hover:text-foreground",
+                )}
+                onClick={() => setShuffled((s) => !s)}
+              >
+                <Shuffle className="size-3.5" />
+                Shuffle
+              </button>
+            )}
+            {selectedUids.size > 0 && (
+              <span className="text-xs text-muted-foreground">
+                {decks
+                  .filter((d) => selectedUids.has(d.uid))
+                  .reduce((sum, d) => sum + d.cards.length, 0)}{" "}
+                cards selected
+              </span>
+            )}
+          </div>
+          <Button
+            onClick={startStudying}
+            disabled={selectedUids.size === 0}
+          >
+            Start Studying
+          </Button>
+        </div>
+      </div>
+    );
+  }
+
+  // ─── Study Screen ───
+  if (step.tag === "study") {
+    const deckNames = decks
+      .filter((d) => step.deckUids.includes(d.uid))
+      .map((d) => d.title)
+      .join(", ");
+
+    return (
+      <div className={cn(className)} style={style}>
+        <FlashcardStudySession
+          cards={step.cards}
+          title={deckNames}
+          shuffled={step.shuffled}
+          onComplete={handleStudyComplete}
+        />
+      </div>
+    );
+  }
+
+  // ─── Completion Screen ───
+  const { result } = step;
+
+  return (
+    <div className={cn(className)} style={style}>
+      <div className="text-center mb-8">
+        <div className="relative mx-auto mb-4">
+          <ProgressRing
+            value={100}
+            size={120}
+            strokeWidth={10}
+            color="var(--success)"
+            className="text-foreground"
+            label=""
+          />
+          <CheckCircle2 className="size-8 text-success absolute inset-0 m-auto" />
+        </div>
+        <h2 className="text-xl font-bold text-foreground mb-1">
+          Study Session Complete
+        </h2>
+        <p className="text-muted-foreground text-sm">
+          Great work! Here's your session summary.
+        </p>
+      </div>
+
+      <div className="grid grid-cols-2 sm:grid-cols-4 gap-3 mb-8">
+        <StatCard
+          icon={<Layers />}
+          label="Cards Studied"
+          value={String(result.totalCards)}
+        />
+        <StatCard
+          icon={<BookOpen />}
+          label="Decks"
+          value={String(result.decksStudied)}
+        />
+        <StatCard
+          icon={<Clock />}
+          label="Time Spent"
+          value={formatDuration(result.timeElapsedSeconds)}
+        />
+        <StatCard
+          icon={<Shuffle />}
+          label="Shuffled"
+          value={result.wasShuffled ? "Yes" : "No"}
+        />
+      </div>
+
+      <div className="flex justify-center gap-3">
+        <Button variant="outline" onClick={handlePickNewDeck}>
+          <ArrowLeft className="size-4 mr-2" />
+          Pick New Deck
+        </Button>
+        <Button onClick={handleStudyAgain}>
+          <RotateCcw className="size-4 mr-2" />
+          Study Again
+        </Button>
+      </div>
+    </div>
+  );
+}

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