@hydralms/components 0.2.0 → 0.3.0

package/src/modules/QuizModule/QuizModule.tsx

@@ -1,25 +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 { Separator } from "../../ui/separator";
-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 =
@@ -27,7 +15,7 @@ type InternalStep =
   | { tag: "quiz" }
   | { tag: "results"; result: QuizModuleResult };
 
-export function QuizModule({
+function QuizModuleBase({
   title,
   description,
   questions,
@@ -37,106 +25,55 @@ export function QuizModule({
   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");
 
-  useEffect(() => {
-    contentRef.current?.focus({ preventScroll: true });
-  }, [step.tag]);
+  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 {
+  const handleSubmit = useCallback((answers: SessionAnswer[]) => {
     const { correct, total, percentage } = scoreAssessment(questions, answers);
-    const elapsed = startTimeRef.current
-      ? Math.floor((Date.now() - startTimeRef.current) / 1000)
-      : timeElapsed;
-
-    return {
+    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 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">
-              <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-2 mb-8">
-              <Badge variant="outline" className="gap-1.5">
-                <HelpCircle className="size-3.5" />
-                {questions.length} questions
-              </Badge>
-              {timeLimitSeconds && (
-                <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: "quiz" })}>
-              <Play className="size-4 mr-2" />
-              Start Quiz
-            </Button>
-          </CardContent>
-        </Card>
+        <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>
     );
   }
@@ -151,6 +88,7 @@ export function QuizModule({
           timeElapsedSeconds={timeElapsed}
           timeLimitSeconds={timeLimitSeconds}
           questionMaterials={questionMaterials}
+          readOnly={readOnly}
         />
       </div>
     );
@@ -158,84 +96,26 @@ export function QuizModule({
 
   // ─── 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>
-            <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 Quiz
-              </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
-          />
-        </>
-      )}
+      <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, QuestionMaterial, SessionAnswer } from "../../questions/types";
+import type { QuestionData, QuestionMaterial } from "../../questions/types";
+import type { AssessmentResult } from "../_shared/types";
 
 /**
  * QuizModule — a complete multi-step assessment experience.
@@ -39,23 +40,12 @@ export interface QuizModuleProps {
    * 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;
+}