@hydralms/components 0.1.3 → 0.2.0

package/src/modules/ExamModule/ExamModule.tsx

@@ -0,0 +1,285 @@
+import { useState, useRef, useEffect } from "react";
+import {
+  ShieldCheck,
+  RotateCcw,
+  Clock,
+  HelpCircle,
+  CheckCircle2,
+  XCircle,
+  Trophy,
+  Play,
+} from "lucide-react";
+import { ExamSession } from "../../sections/ExamSession/ExamSession";
+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 { Alert, AlertDescription } from "../../ui/alert";
+import { Separator } from "../../ui/separator";
+import { formatDuration } from "../../utils/format-duration";
+import { cn } from "../../lib/utils";
+import type { SessionAnswer } from "../../questions/types";
+import type { ExamSubmitMetadata } from "../../sections/ExamSession/types";
+import { scoreAssessment } from "../../questions/scoring";
+import type { ExamModuleProps, ExamModuleResult } from "./types";
+
+type InternalStep =
+  | { tag: "intro" }
+  | { tag: "exam" }
+  | { tag: "results"; result: ExamModuleResult };
+
+/**
+ * ExamModule — a complete formal exam experience.
+ *
+ * Steps: Intro (rules/instructions) → Exam (timed ExamSession) → Results (score + review).
+ * Manages an external timer that feeds elapsed time to ExamSession.
+ */
+export function ExamModule({
+  title,
+  description,
+  instructions,
+  questions,
+  timeLimitSeconds,
+  passingScore,
+  allowBackNavigation = true,
+  autoSubmitOnTimeout = true,
+  timeWarningThreshold,
+  allowRetake = false,
+  showReview = true,
+  onComplete,
+  className,
+  style,
+}: ExamModuleProps) {
+  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);
+  const contentRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    contentRef.current?.focus({ preventScroll: true });
+  }, [step.tag]);
+
+  // Timer for exam step
+  useEffect(() => {
+    if (step.tag === "exam") {
+      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[],
+    metadata: ExamSubmitMetadata
+  ): ExamModuleResult {
+    const { correct, total, percentage } = scoreAssessment(questions, answers);
+    return {
+      answers,
+      correct,
+      total,
+      percentage,
+      passed: passingScore !== undefined ? percentage >= passingScore : true,
+      timeElapsedSeconds: metadata.timeElapsedSeconds,
+      wasAutoSubmitted: metadata.wasAutoSubmitted,
+    };
+  }
+
+  function handleSubmit(answers: SessionAnswer[], metadata: ExamSubmitMetadata) {
+    const result = scoreAnswers(answers, metadata);
+    setStep({ tag: "results", result });
+    onComplete?.(result);
+  }
+
+  function handleRetake() {
+    setTimeElapsed(0);
+    startTimeRef.current = null;
+    setStep({ tag: "intro" });
+  }
+
+  // ─── Intro Screen ───
+  if (step.tag === "intro") {
+    return (
+      <div
+        ref={contentRef}
+        tabIndex={-1}
+        className={cn("max-w-2xl mx-auto outline-none", 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">
+              <ShieldCheck 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>
+            )}
+
+            {/* Instructions */}
+            {instructions && (
+              <Alert className="text-left mb-6">
+                <AlertDescription>{instructions}</AlertDescription>
+              </Alert>
+            )}
+
+            {/* Metadata chips */}
+            <div className="flex flex-wrap justify-center gap-2 mb-8">
+              <Badge variant="outline" className="gap-1.5">
+                <HelpCircle className="size-3.5" />
+                {questions.length} questions
+              </Badge>
+              <Badge variant="outline" className="gap-1.5">
+                <Clock className="size-3.5" />
+                {formatDuration(timeLimitSeconds)} time limit
+              </Badge>
+              {passingScore !== undefined && (
+                <Badge variant="outline" className="gap-1.5">
+                  <CheckCircle2 className="size-3.5" />
+                  {passingScore}% to pass
+                </Badge>
+              )}
+            </div>
+
+            <Button size="lg" onClick={() => setStep({ tag: "exam" })}>
+              <Play className="size-4 mr-2" />
+              Begin Exam
+            </Button>
+          </CardContent>
+        </Card>
+      </div>
+    );
+  }
+
+  // ─── Exam Screen ───
+  if (step.tag === "exam") {
+    return (
+      <div
+        ref={contentRef}
+        tabIndex={-1}
+        className={cn("outline-none", className)}
+        style={style}
+      >
+        <ExamSession
+          questions={questions}
+          timeLimitSeconds={timeLimitSeconds}
+          timeElapsedSeconds={timeElapsed}
+          autoSubmitOnTimeout={autoSubmitOnTimeout}
+          timeWarningThreshold={timeWarningThreshold}
+          allowBackNavigation={allowBackNavigation}
+          confirmBeforeSubmit
+          examTitle={title}
+          onSubmit={handleSubmit}
+        />
+      </div>
+    );
+  }
+
+  // ─── Results Screen ───
+  const { result } = step;
+  const passed = result.passed;
+
+  return (
+    <div
+      ref={contentRef}
+      tabIndex={-1}
+      className={cn("max-w-2xl mx-auto outline-none", className)}
+      style={style}
+    >
+      <Card>
+        <CardContent className="pt-8 pb-8">
+          {/* 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>
+            {result.wasAutoSubmitted && (
+              <Badge variant="outline" className="text-sm px-3 py-1 mb-2 ml-2">
+                Auto-submitted
+              </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"
+              description="Questions answered right"
+              value={`${result.correct}/${result.total}`}
+            />
+            <StatCard
+              icon={<XCircle />}
+              label="Incorrect"
+              description="Questions to review"
+              value={`${result.total - result.correct}/${result.total}`}
+            />
+            <StatCard
+              icon={<Trophy />}
+              label="Score"
+              description="Overall percentage"
+              value={`${result.percentage}%`}
+            />
+            <StatCard
+              icon={<Clock />}
+              label="Time"
+              description="Total elapsed"
+              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 Exam
+              </Button>
+            </div>
+          )}
+        </CardContent>
+      </Card>
+
+      {/* Per-question review */}
+      {showReview && (
+        <>
+          <Separator className="my-6" />
+          <h3 className="text-lg font-semibold text-foreground mb-4">
+            Question Review
+          </h3>
+          <AssessmentReview
+            questions={questions}
+            sessionAnswers={result.answers}
+            showCorrectAnswers
+          />
+        </>
+      )}
+    </div>
+  );
+}

package/src/modules/ExamModule/types.ts

@@ -0,0 +1,66 @@
+import type { ReactNode } from "react";
+import type { QuestionData, SessionAnswer } from "../../questions/types";
+
+/**
+ * ExamModule — a formal timed exam experience with intro, exam, and results steps.
+ *
+ * Wraps ExamSession with an intro screen showing rules/instructions and a
+ * results screen with scoring, stats, and optional answer review.
+ *
+ * @example
+ * <ExamModule
+ *   title="Midterm Exam"
+ *   instructions={<p>You have 60 minutes. No notes allowed.</p>}
+ *   questions={questions}
+ *   timeLimitSeconds={3600}
+ *   passingScore={70}
+ *   onComplete={(result) => saveResult(result)}
+ * />
+ */
+export interface ExamModuleProps {
+  /** Exam title displayed on the intro screen */
+  title: string;
+  /** Exam description displayed on the intro screen */
+  description?: string;
+  /** Exam rules/instructions rendered on the intro screen */
+  instructions?: ReactNode;
+  /** Ordered list of questions */
+  questions: QuestionData[];
+  /** Time limit in seconds (required for exams) */
+  timeLimitSeconds: number;
+  /** Passing threshold as a percentage (e.g. 70 means 70%) */
+  passingScore?: number;
+  /** Whether the user can go back to previous questions. @default true */
+  allowBackNavigation?: boolean;
+  /** Auto-submit when time runs out. @default true */
+  autoSubmitOnTimeout?: boolean;
+  /** Seconds remaining at which to show a time warning */
+  timeWarningThreshold?: number;
+  /** Whether to allow retaking the exam from the results screen. @default false */
+  allowRetake?: boolean;
+  /** Whether to show correct/incorrect answer highlighting in the review. @default true */
+  showReview?: boolean;
+  /** Called when the exam is completed (submitted) */
+  onComplete?: (result: ExamModuleResult) => void;
+  /** CSS class name for the root element */
+  className?: string;
+  /** Inline styles for the root element */
+  style?: React.CSSProperties;
+}
+
+export interface ExamModuleResult {
+  /** The user's submitted answers */
+  answers: SessionAnswer[];
+  /** Number of correct answers */
+  correct: number;
+  /** Total number of gradable 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;
+  /** Whether the submission was triggered by timeout */
+  wasAutoSubmitted: boolean;
+}

package/src/modules/FlashcardLab/FlashcardLab.tsx

@@ -1,4 +1,4 @@
-import { useState, useRef } from "react";
+import { useState, useRef, useEffect } from "react";
 import {
   BookOpen,
   Shuffle,
@@ -40,6 +40,11 @@ export function FlashcardLab({
   const [selectedUids, setSelectedUids] = useState<Set<string>>(new Set());
   const [shuffled, setShuffled] = useState(defaultShuffled);
   const startTimeRef = useRef<number | null>(null);
+  const contentRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    contentRef.current?.focus({ preventScroll: true });
+  }, [step.tag]);
 
   function toggleDeck(uid: string) {
     setSelectedUids((prev) => {
@@ -105,12 +110,14 @@ export function FlashcardLab({
   // ─── Setup Screen ───
   if (step.tag === "setup") {
     return (
-      <div className={cn(className)} style={style}>
+      <div ref={contentRef} tabIndex={-1} className={cn("max-w-2xl mx-auto outline-none", className)} style={style}>
+        <Card>
+          <CardContent className="pt-8 pb-8">
         <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">
+          <div className="mx-auto mb-4 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">
+          <h2 className="text-2xl font-bold text-foreground mb-2">
             Choose Your Decks
           </h2>
           <p className="text-muted-foreground text-sm">
@@ -159,19 +166,15 @@ export function FlashcardLab({
         <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",
-                )}
+              <Button
+                variant={shuffled ? "secondary" : "outline"}
+                size="sm"
+                className="gap-1.5"
                 onClick={() => setShuffled((s) => !s)}
               >
                 <Shuffle className="size-3.5" />
                 Shuffle
-              </button>
+              </Button>
             )}
             {selectedUids.size > 0 && (
               <span className="text-xs text-muted-foreground">
@@ -189,6 +192,8 @@ export function FlashcardLab({
             Start Studying
           </Button>
         </div>
+          </CardContent>
+        </Card>
       </div>
     );
   }
@@ -201,7 +206,7 @@ export function FlashcardLab({
       .join(", ");
 
     return (
-      <div className={cn(className)} style={style}>
+      <div ref={contentRef} tabIndex={-1} className={cn("outline-none", className)} style={style}>
         <FlashcardStudySession
           cards={step.cards}
           title={deckNames}
@@ -216,7 +221,9 @@ export function FlashcardLab({
   const { result } = step;
 
   return (
-    <div className={cn(className)} style={style}>
+    <div ref={contentRef} tabIndex={-1} className={cn("max-w-2xl mx-auto outline-none", className)} style={style}>
+      <Card>
+        <CardContent className="pt-8 pb-8">
       <div className="text-center mb-8">
         <div className="relative mx-auto mb-4">
           <ProgressRing
@@ -229,7 +236,7 @@ export function FlashcardLab({
           />
           <CheckCircle2 className="size-8 text-success absolute inset-0 m-auto" />
         </div>
-        <h2 className="text-xl font-bold text-foreground mb-1">
+        <h2 className="text-xl font-bold text-foreground mb-2">
           Study Session Complete
         </h2>
         <p className="text-muted-foreground text-sm">
@@ -241,21 +248,25 @@ export function FlashcardLab({
         <StatCard
           icon={<Layers />}
           label="Cards Studied"
+          description="Total cards reviewed"
           value={String(result.totalCards)}
         />
         <StatCard
           icon={<BookOpen />}
           label="Decks"
+          description="Decks completed"
           value={String(result.decksStudied)}
         />
         <StatCard
           icon={<Clock />}
           label="Time Spent"
+          description="Session duration"
           value={formatDuration(result.timeElapsedSeconds)}
         />
         <StatCard
           icon={<Shuffle />}
           label="Shuffled"
+          description="Card order randomized"
           value={result.wasShuffled ? "Yes" : "No"}
         />
       </div>
@@ -270,6 +281,8 @@ export function FlashcardLab({
           Study Again
         </Button>
       </div>
+        </CardContent>
+      </Card>
     </div>
   );
 }

package/src/modules/GradeCenterModule/GradeCenterModule.tsx

@@ -0,0 +1,169 @@
+import { useState, useRef, useEffect } from "react";
+import { ArrowLeft, BookOpen, BarChart3 } from "lucide-react";
+import { GradebookTable } from "../../sections/GradebookTable/GradebookTable";
+import { ProgressDashboard } from "../../sections/ProgressDashboard/ProgressDashboard";
+import { AssessmentReview } from "../../sections/AssessmentReview/AssessmentReview";
+import { GradeIndicator } from "../../progress/grade-indicator";
+import { Button } from "../../ui/button";
+import { Card, CardContent } from "../../ui/card";
+import { Tabs, TabsList, TabsTrigger, TabsContent } from "../../ui/tabs";
+import { Separator } from "../../ui/separator";
+import { cn } from "../../lib/utils";
+import type { GradeItem } from "../../sections/GradebookTable/types";
+import type { GradeCenterModuleProps } from "./types";
+
+/**
+ * GradeCenterModule — a tabbed grade center with gradebook, progress dashboard,
+ * and drill-down into individual assessment reviews.
+ *
+ * Uses a panel-based layout (like CoursePlayer) with tabs for Grades and Progress,
+ * and a slide-in detail panel for reviewing individual assessments.
+ */
+export function GradeCenterModule({
+  courseTitle,
+  gradeItems,
+  categories,
+  overallGrade,
+  showWeights,
+  progressData,
+  reviewData,
+  className,
+  style,
+}: GradeCenterModuleProps) {
+  const [drillDownUid, setDrillDownUid] = useState<string | null>(null);
+  const contentRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    contentRef.current?.focus({ preventScroll: true });
+  }, [drillDownUid]);
+
+  function handleItemClick(item: GradeItem) {
+    if (reviewData?.[item.uid]) {
+      setDrillDownUid(item.uid);
+    }
+  }
+
+  function handleBack() {
+    setDrillDownUid(null);
+  }
+
+  const drillDownItem = drillDownUid
+    ? gradeItems.find((i) => i.uid === drillDownUid)
+    : null;
+  const drillDownData = drillDownUid ? reviewData?.[drillDownUid] : null;
+
+  return (
+    <div
+      ref={contentRef}
+      tabIndex={-1}
+      className={cn("outline-none", className)}
+      style={style}
+    >
+      {/* Header */}
+      <div className="flex items-center justify-between mb-6">
+        <div>
+          {courseTitle && (
+            <h2 className="text-xl font-bold text-foreground">{courseTitle}</h2>
+          )}
+          <p className="text-sm text-muted-foreground">Grade Center</p>
+        </div>
+        {overallGrade && (
+          <div className="flex items-center gap-3">
+            <GradeIndicator
+              percentage={overallGrade.percentage}
+              letterGrade={overallGrade.letterGrade}
+              size="medium"
+            />
+            <div className="text-right">
+              <div className="text-sm font-medium text-foreground">
+                {overallGrade.pointsEarned}/{overallGrade.pointsPossible} pts
+              </div>
+              {overallGrade.letterGrade && (
+                <div className="text-xs text-muted-foreground">
+                  {overallGrade.letterGrade}
+                </div>
+              )}
+            </div>
+          </div>
+        )}
+      </div>
+
+      <Separator className="mb-6" />
+
+      {/* Drill-down view */}
+      {drillDownItem && drillDownData ? (
+        <div>
+          <Button
+            variant="ghost"
+            size="sm"
+            onClick={handleBack}
+            className="mb-4"
+          >
+            <ArrowLeft className="size-4 mr-1.5" />
+            Back to Grades
+          </Button>
+          <Card className="mb-4">
+            <CardContent className="py-3 px-4">
+              <h3 className="font-semibold text-foreground">
+                {drillDownItem.name}
+              </h3>
+              {drillDownItem.score !== null && (
+                <p className="text-sm text-muted-foreground">
+                  Score: {drillDownItem.score}/{drillDownItem.maxScore} (
+                  {Math.round(
+                    (drillDownItem.score / drillDownItem.maxScore) * 100
+                  )}
+                  %)
+                </p>
+              )}
+            </CardContent>
+          </Card>
+          <AssessmentReview
+            questions={drillDownData.questions}
+            sessionAnswers={drillDownData.sessionAnswers}
+            score={drillDownData.score}
+            showCorrectAnswers
+          />
+        </div>
+      ) : (
+        <Tabs defaultValue="grades">
+          {progressData && (
+            <TabsList className="mb-6">
+              <TabsTrigger value="grades">
+                <BookOpen className="size-4 mr-1.5" />
+                Grades
+              </TabsTrigger>
+              <TabsTrigger value="progress">
+                <BarChart3 className="size-4 mr-1.5" />
+                Progress
+              </TabsTrigger>
+            </TabsList>
+          )}
+
+          <TabsContent value="grades">
+            <GradebookTable
+              items={gradeItems}
+              categories={categories}
+              overallGrade={overallGrade}
+              showWeights={showWeights}
+              onItemClick={handleItemClick}
+            />
+          </TabsContent>
+
+          {progressData && (
+            <TabsContent value="progress">
+              <ProgressDashboard
+                overallProgress={progressData.overallProgress}
+                totalTimeSpent={progressData.totalTimeSpent}
+                modules={progressData.modules}
+                recentActivity={progressData.recentActivity}
+                streak={progressData.streak}
+                achievements={progressData.achievements}
+              />
+            </TabsContent>
+          )}
+        </Tabs>
+      )}
+    </div>
+  );
+}