@hydralms/components 0.1.3 → 0.3.0

package/src/modules/QuizModule/QuizModule.tsx

@@ -1,23 +1,13 @@
-import { useState, useRef, useEffect } from "react";
-import {
-  Play,
-  RotateCcw,
-  Clock,
-  HelpCircle,
-  CheckCircle2,
-  XCircle,
-  Trophy,
-} from "lucide-react";
+import { useState, useRef, useEffect, useCallback } from "react";
+import { 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 { 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 { QuizModuleProps, QuizModuleResult } from "./types";
 
 type InternalStep =
@@ -25,7 +15,7 @@ type InternalStep =
   | { tag: "quiz" }
   | { tag: "results"; result: QuizModuleResult };
 
-export function QuizModule({
+function QuizModuleBase({
   title,
   description,
   questions,
@@ -34,119 +24,56 @@ export function QuizModule({
   allowRetake = true,
   onComplete,
   showReview = true,
+  questionMaterials,
+  readOnly = false,
   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);
+  const contentRef = useRef<HTMLDivElement>(null);
+  const { timeElapsed, getFinalElapsed, reset: resetTimer } = useTimer(step.tag === "quiz");
+
+  const onCompleteRef = useRef(onComplete);
+  onCompleteRef.current = onComplete;
 
-  // 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);
-    };
+    contentRef.current?.focus({ preventScroll: true });
   }, [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 {
+  const handleSubmit = useCallback((answers: SessionAnswer[]) => {
+    const { correct, total, percentage } = scoreAssessment(questions, answers);
+    const result: QuizModuleResult = {
       answers,
       correct,
       total,
       percentage,
       passed: passingScore !== undefined ? percentage >= passingScore : true,
-      timeElapsedSeconds: elapsed,
+      timeElapsedSeconds: getFinalElapsed(),
     };
-  }
-
-  function handleSubmit(answers: SessionAnswer[]) {
-    const result = scoreAnswers(answers);
     setStep({ tag: "results", result });
-    onComplete?.(result);
-  }
+    onCompleteRef.current?.(result);
+  }, [questions, passingScore, getFinalElapsed]);
 
-  function handleRetake() {
-    setTimeElapsed(0);
-    startTimeRef.current = null;
+  const handleRetake = useCallback(() => {
+    resetTimer();
     setStep({ tag: "intro" });
-  }
+  }, [resetTimer]);
 
   // ─── 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 ref={contentRef} tabIndex={-1} className={cn("max-w-2xl mx-auto outline-none", className)} style={style}>
+        <AssessmentIntro
+          icon={<Trophy className="size-7 text-primary" />}
+          title={title}
+          description={description}
+          questionCount={questions.length}
+          timeLimitSeconds={timeLimitSeconds}
+          passingScore={passingScore}
+          startLabel="Start Quiz"
+          onStart={() => setStep({ tag: "quiz" })}
+          readOnly={readOnly}
+        />
       </div>
     );
   }
@@ -154,12 +81,14 @@ export function QuizModule({
   // ─── Quiz Screen ───
   if (step.tag === "quiz") {
     return (
-      <div className={cn(className)} style={style}>
+      <div ref={contentRef} tabIndex={-1} className={cn("outline-none", className)} style={style}>
         <QuizSession
           questions={questions}
           onSubmit={handleSubmit}
           timeElapsedSeconds={timeElapsed}
           timeLimitSeconds={timeLimitSeconds}
+          questionMaterials={questionMaterials}
+          readOnly={readOnly}
         />
       </div>
     );
@@ -167,75 +96,26 @@ export function QuizModule({
 
   // ─── 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 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 Quiz"
+        showReview={showReview}
+        readOnly={readOnly}
+      />
     </div>
   );
 }
+
+export const QuizModule = withProGate(QuizModuleBase, "QuizModule");

package/src/modules/QuizModule/types.ts

@@ -1,4 +1,5 @@
-import type { QuestionData, SessionAnswer } from "../../questions/types";
+import type { QuestionData, QuestionMaterial } from "../../questions/types";
+import type { AssessmentResult } from "../_shared/types";
 
 /**
  * QuizModule — a complete multi-step assessment experience.
@@ -34,23 +35,17 @@ export interface QuizModuleProps {
   onComplete?: (result: QuizModuleResult) => void;
   /** Whether to show correct/incorrect answer highlighting in the review. @default true */
   showReview?: boolean;
+  /**
+   * Related materials keyed by question UID. When provided, a "Materials"
+   * button appears in the question header, opening a drawer with content blocks.
+   */
+  questionMaterials?: QuestionMaterial[];
+  /** 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 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;
-}
+export interface QuizModuleResult extends AssessmentResult {}

package/src/modules/StudentDashboardModule/StudentDashboardModule.tsx

@@ -0,0 +1,117 @@
+import { useRef, useEffect } from "react";
+import { BookOpen, Bell, BarChart3 } from "lucide-react";
+import { ProgressDashboard } from "../../sections/ProgressDashboard/ProgressDashboard";
+import { CourseCatalog } from "../../sections/CourseCatalog/CourseCatalog";
+import { AnnouncementFeed } from "../../sections/AnnouncementFeed/AnnouncementFeed";
+import { ProgressRing } from "../../progress/progress-ring";
+import { Tabs, TabsList, TabsTrigger, TabsContent } from "../../ui/tabs";
+import { Separator } from "../../ui/separator";
+import { cn } from "../../lib/utils";
+import { withProGate } from "../../license/withProGate";
+import type { StudentDashboardModuleProps } from "./types";
+
+/**
+ * StudentDashboardModule — a multi-tab student home page.
+ *
+ * Combines ProgressDashboard, CourseCatalog, and AnnouncementFeed in a tabbed layout
+ * to provide a complete student landing page experience.
+ */
+function StudentDashboardModuleBase({
+  studentName,
+  overallProgress,
+  totalTimeSpent,
+  modules,
+  recentActivity,
+  streak,
+  achievements,
+  enrolledCourses,
+  onCourseClick,
+  announcements = [],
+  onAnnouncementSelect,
+  onMarkRead,
+  readOnly = false,
+  className,
+  style,
+}: StudentDashboardModuleProps) {
+  const contentRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    contentRef.current?.focus({ preventScroll: true });
+  }, []);
+
+  const unreadCount = announcements.filter((a) => !a.isRead).length;
+
+  return (
+    <div
+      ref={contentRef}
+      tabIndex={-1}
+      className={cn("outline-none", className)}
+      style={style}
+    >
+      {/* Header */}
+      <div className="flex items-center justify-between mb-6">
+        <h2 className="text-xl font-bold text-foreground">
+          Welcome back, {studentName}
+        </h2>
+        <ProgressRing value={overallProgress} size={48} strokeWidth={4} />
+      </div>
+
+      <Separator className="mb-6" />
+
+      {/* Tabs */}
+      <Tabs defaultValue="overview">
+        <TabsList className="mb-6">
+          <TabsTrigger value="overview">
+            <BarChart3 className="size-4 mr-1.5" />
+            Overview
+          </TabsTrigger>
+          <TabsTrigger value="courses">
+            <BookOpen className="size-4 mr-1.5" />
+            My Courses
+          </TabsTrigger>
+          <TabsTrigger value="announcements">
+            <Bell className="size-4 mr-1.5" />
+            Announcements
+            {unreadCount > 0 && (
+              <span className="ml-1.5 inline-flex items-center justify-center rounded-full bg-primary text-primary-foreground text-xs font-medium min-w-5 h-5 px-1.5">
+                {unreadCount}
+              </span>
+            )}
+          </TabsTrigger>
+        </TabsList>
+
+        <TabsContent value="overview">
+          <ProgressDashboard
+            overallProgress={overallProgress}
+            totalTimeSpent={totalTimeSpent}
+            modules={modules}
+            recentActivity={recentActivity}
+            streak={streak}
+            achievements={achievements}
+          />
+        </TabsContent>
+
+        <TabsContent value="courses">
+          <CourseCatalog
+            courses={enrolledCourses}
+            onCourseClick={(course) => !readOnly && onCourseClick(course.uid)}
+            showSearch
+            viewMode="grid"
+            readOnly={readOnly}
+          />
+        </TabsContent>
+
+        <TabsContent value="announcements">
+          <AnnouncementFeed
+            announcements={announcements}
+            onSelect={onAnnouncementSelect}
+            onMarkRead={onMarkRead}
+            readOnly={readOnly}
+          />
+        </TabsContent>
+      </Tabs>
+    </div>
+  );
+}
+
+export const StudentDashboardModule = withProGate(StudentDashboardModuleBase, "StudentDashboardModule");

package/src/modules/StudentDashboardModule/types.ts

@@ -0,0 +1,56 @@
+import type { CourseInfo } from "../../sections/CourseCatalog/types";
+import type { Announcement } from "../../sections/AnnouncementFeed/types";
+import type {
+  ModuleProgress,
+  ActivityItem,
+  Achievement,
+} from "../../sections/ProgressDashboard/types";
+
+/**
+ * StudentDashboardModule — a multi-tab student home page.
+ *
+ * Combines ProgressDashboard, CourseCatalog, and AnnouncementFeed in a tabbed layout
+ * to provide a complete student landing page experience.
+ *
+ * @example
+ * <StudentDashboardModule
+ *   studentName="Jane"
+ *   overallProgress={72}
+ *   totalTimeSpent={14400}
+ *   modules={[]}
+ *   enrolledCourses={courses}
+ *   onCourseClick={(uid) => navigate(`/courses/${uid}`)}
+ * />
+ */
+export interface StudentDashboardModuleProps {
+  /** Student's display name */
+  studentName: string;
+  /** Overall progress percentage (0-100) */
+  overallProgress: number;
+  /** Total time spent in seconds */
+  totalTimeSpent: number;
+  /** Per-module progress data */
+  modules: ModuleProgress[];
+  /** Recent activity items */
+  recentActivity?: ActivityItem[];
+  /** Streak data */
+  streak?: { currentDays: number; longestDays: number };
+  /** Achievements */
+  achievements?: Achievement[];
+  /** Enrolled courses for the courses tab */
+  enrolledCourses: CourseInfo[];
+  /** Called when a course is clicked */
+  onCourseClick: (courseUid: string) => void;
+  /** Announcements for the announcements tab */
+  announcements?: Announcement[];
+  /** Called when an announcement is selected */
+  onAnnouncementSelect?: (announcement: Announcement) => void;
+  /** Called when an announcement is marked as read */
+  onMarkRead?: (uid: string) => 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;
+}