@hydralms/components 0.1.3 → 0.3.0

package/src/modules/ExamModule/ExamModule.tsx

@@ -0,0 +1,151 @@
+import { useState, useRef, useEffect, useCallback } from "react";
+import { ShieldCheck } from "lucide-react";
+import { ExamSession } from "../../sections/ExamSession/ExamSession";
+import { Badge } from "../../ui/badge";
+import { Alert, AlertDescription } from "../../ui/alert";
+import { cn } from "../../lib/utils";
+import type { SessionAnswer } from "../../questions/types";
+import type { ExamSubmitMetadata } from "../../sections/ExamSession/types";
+import { scoreAssessment } from "../../questions/scoring";
+import { useTimer } from "../_shared/use-timer";
+import { AssessmentIntro } from "../_shared/assessment-intro";
+import { AssessmentResults } from "../_shared/assessment-results";
+import { withProGate } from "../../license/withProGate";
+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.
+ */
+function ExamModuleBase({
+  title,
+  description,
+  instructions,
+  questions = [],
+  timeLimitSeconds,
+  passingScore,
+  allowBackNavigation = true,
+  autoSubmitOnTimeout = true,
+  timeWarningThreshold,
+  allowRetake = false,
+  showReview = true,
+  onComplete,
+  readOnly = false,
+  className,
+  style,
+}: ExamModuleProps) {
+  const [step, setStep] = useState<InternalStep>({ tag: "intro" });
+  const contentRef = useRef<HTMLDivElement>(null);
+  const { timeElapsed, reset: resetTimer } = useTimer(step.tag === "exam");
+
+  const onCompleteRef = useRef(onComplete);
+  onCompleteRef.current = onComplete;
+
+  useEffect(() => {
+    contentRef.current?.focus({ preventScroll: true });
+  }, [step.tag]);
+
+  const handleSubmit = useCallback((answers: SessionAnswer[], metadata: ExamSubmitMetadata) => {
+    const { correct, total, percentage } = scoreAssessment(questions, answers);
+    const result: ExamModuleResult = {
+      answers,
+      correct,
+      total,
+      percentage,
+      passed: passingScore !== undefined ? percentage >= passingScore : true,
+      timeElapsedSeconds: metadata.timeElapsedSeconds,
+      wasAutoSubmitted: metadata.wasAutoSubmitted,
+    };
+    setStep({ tag: "results", result });
+    onCompleteRef.current?.(result);
+  }, [questions, passingScore]);
+
+  const handleRetake = useCallback(() => {
+    resetTimer();
+    setStep({ tag: "intro" });
+  }, [resetTimer]);
+
+  // ─── Intro Screen ───
+  if (step.tag === "intro") {
+    return (
+      <div ref={contentRef} tabIndex={-1} className={cn("max-w-2xl mx-auto outline-none", className)} style={style}>
+        <AssessmentIntro
+          icon={<ShieldCheck className="size-7 text-primary" />}
+          title={title}
+          description={description}
+          questionCount={questions.length}
+          timeLimitSeconds={timeLimitSeconds}
+          passingScore={passingScore}
+          startLabel="Begin Exam"
+          onStart={() => setStep({ tag: "exam" })}
+          readOnly={readOnly}
+        >
+          {instructions && (
+            <Alert className="text-left mb-6">
+              <AlertDescription>{instructions}</AlertDescription>
+            </Alert>
+          )}
+        </AssessmentIntro>
+      </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}
+          readOnly={readOnly}
+        />
+      </div>
+    );
+  }
+
+  // ─── Results Screen ───
+  const { result } = step;
+
+  return (
+    <div ref={contentRef} tabIndex={-1} className={cn("max-w-2xl mx-auto outline-none", className)} style={style}>
+      <AssessmentResults
+        title={title}
+        percentage={result.percentage}
+        passed={result.passed}
+        correct={result.correct}
+        total={result.total}
+        timeElapsedSeconds={result.timeElapsedSeconds}
+        answers={result.answers}
+        questions={questions}
+        allowRetake={allowRetake}
+        onRetake={handleRetake}
+        retakeLabel="Retake Exam"
+        showReview={showReview}
+        readOnly={readOnly}
+        extraBadges={
+          result.wasAutoSubmitted ? (
+            <Badge variant="outline" className="text-sm px-3 py-1 mb-2 ml-2">
+              Auto-submitted
+            </Badge>
+          ) : null
+        }
+      />
+    </div>
+  );
+}
+
+export const ExamModule = withProGate(ExamModuleBase, "ExamModule");

package/src/modules/ExamModule/types.ts

@@ -0,0 +1,57 @@
+import type { ReactNode } from "react";
+import type { QuestionData } from "../../questions/types";
+import type { AssessmentResult } from "../_shared/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;
+  /** When true, disables interactions for preview/demo mode. @default false */
+  readOnly?: boolean;
+  /** CSS class name for the root element */
+  className?: string;
+  /** Inline styles for the root element */
+  style?: React.CSSProperties;
+}
+
+export interface ExamModuleResult extends AssessmentResult {
+  /** 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,
@@ -17,6 +17,7 @@ import { Card, CardContent } from "../../ui/card";
 import { formatDuration } from "../../utils/format-duration";
 import { cn } from "../../lib/utils";
 import type { FlashcardData } from "../../flashcards/types";
+import { withProGate } from "../../license/withProGate";
 import type {
   FlashcardLabProps,
   FlashcardLabResult,
@@ -27,12 +28,13 @@ type InternalStep =
   | { tag: "study"; cards: FlashcardData[]; deckUids: string[]; shuffled: boolean }
   | { tag: "completion"; result: FlashcardLabResult };
 
-export function FlashcardLab({
-  decks,
+function FlashcardLabBase({
+  decks = [],
   showShuffleToggle = true,
   defaultShuffled = false,
   allowMultiSelect = true,
   onComplete,
+  readOnly = false,
   className,
   style,
 }: FlashcardLabProps) {
@@ -40,6 +42,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 +112,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 +168,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">
@@ -184,11 +189,13 @@ export function FlashcardLab({
           </div>
           <Button
             onClick={startStudying}
-            disabled={selectedUids.size === 0}
+            disabled={selectedUids.size === 0 || readOnly}
           >
             Start Studying
           </Button>
         </div>
+          </CardContent>
+        </Card>
       </div>
     );
   }
@@ -201,12 +208,13 @@ 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}
           shuffled={step.shuffled}
           onComplete={handleStudyComplete}
+          readOnly={readOnly}
         />
       </div>
     );
@@ -216,7 +224,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 +239,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,35 +251,43 @@ 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>
 
       <div className="flex justify-center gap-3">
-        <Button variant="outline" onClick={handlePickNewDeck}>
+        <Button variant="outline" onClick={handlePickNewDeck} disabled={readOnly}>
           <ArrowLeft className="size-4 mr-2" />
           Pick New Deck
         </Button>
-        <Button onClick={handleStudyAgain}>
+        <Button onClick={handleStudyAgain} disabled={readOnly}>
           <RotateCcw className="size-4 mr-2" />
           Study Again
         </Button>
       </div>
+        </CardContent>
+      </Card>
     </div>
   );
 }
+
+export const FlashcardLab = withProGate(FlashcardLabBase, "FlashcardLab");

package/src/modules/FlashcardLab/types.ts

@@ -27,6 +27,8 @@ export interface FlashcardLabProps {
   allowMultiSelect?: boolean;
   /** Called when the user completes a study session */
   onComplete?: (result: FlashcardLabResult) => void;
+  /** When true, disables interactions for preview/demo mode. @default false */
+  readOnly?: boolean;
   /** CSS class name for the root element */
   className?: string;
   /** Inline styles for the root element */

package/src/modules/GradeCenterModule/GradeCenterModule.tsx

@@ -0,0 +1,174 @@
+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 { withProGate } from "../../license/withProGate";
+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.
+ */
+function GradeCenterModuleBase({
+  courseTitle,
+  gradeItems = [],
+  categories,
+  overallGrade,
+  showWeights,
+  progressData,
+  reviewData,
+  readOnly = false,
+  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}
+              readOnly={readOnly}
+            />
+          </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>
+  );
+}
+
+export const GradeCenterModule = withProGate(GradeCenterModuleBase, "GradeCenterModule");

package/src/modules/GradeCenterModule/types.ts

@@ -0,0 +1,65 @@
+import type {
+  GradeItem,
+  GradeCategory,
+  OverallGrade,
+} from "../../sections/GradebookTable/types";
+import type {
+  ModuleProgress,
+  ActivityItem,
+  Achievement,
+} from "../../sections/ProgressDashboard/types";
+import type { AssessmentScore } from "../../sections/AssessmentReview/types";
+import type { QuestionData, SessionAnswer } from "../../questions/types";
+
+/**
+ * GradeCenterModule — a tabbed grade center with gradebook, progress dashboard,
+ * and drill-down into individual assessment reviews.
+ *
+ * Combines GradebookTable, ProgressDashboard, and AssessmentReview sections
+ * in a master-detail layout with tab navigation.
+ *
+ * @example
+ * <GradeCenterModule
+ *   courseTitle="React Fundamentals"
+ *   gradeItems={items}
+ *   overallGrade={overallGrade}
+ *   progressData={{ overallProgress: 75, totalTimeSpent: 45000, modules: [] }}
+ *   reviewData={{ quiz1: { questions, sessionAnswers, score } }}
+ * />
+ */
+export interface GradeCenterModuleProps {
+  /** Course title shown in the header */
+  courseTitle?: string;
+  /** Grade items (assignments, quizzes, etc.) */
+  gradeItems: GradeItem[];
+  /** Optional category grouping */
+  categories?: GradeCategory[];
+  /** Overall course grade summary */
+  overallGrade?: OverallGrade;
+  /** Whether to show the weight column in the gradebook */
+  showWeights?: boolean;
+  /** Data for the progress tab — tab is hidden if not provided */
+  progressData?: {
+    overallProgress: number;
+    totalTimeSpent: number;
+    modules: ModuleProgress[];
+    recentActivity?: ActivityItem[];
+    streak?: { currentDays: number; longestDays: number };
+    achievements?: Achievement[];
+  };
+  /** Review data keyed by grade item UID — enables drill-down on click */
+  reviewData?: Record<
+    string,
+    {
+      questions: QuestionData[];
+      sessionAnswers: SessionAnswer[];
+      score?: AssessmentScore;
+    }
+  >;
+  /** When true, disables interactions for preview/demo mode. @default false */
+  readOnly?: boolean;
+  /** CSS class name for the root element */
+  className?: string;
+  /** Inline styles for the root element */
+  style?: React.CSSProperties;
+}