@hydralms/components 0.1.3 → 0.2.0

package/src/modules/GradeCenterModule/types.ts

@@ -0,0 +1,63 @@
+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;
+    }
+  >;
+  /** CSS class name for the root element */
+  className?: string;
+  /** Inline styles for the root element */
+  style?: React.CSSProperties;
+}

package/src/modules/QuizModule/QuizModule.tsx

@@ -15,9 +15,11 @@ 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 type { QuizModuleProps, QuizModuleResult } from "./types";
 
 type InternalStep =
@@ -34,6 +36,7 @@ export function QuizModule({
   allowRetake = true,
   onComplete,
   showReview = true,
+  questionMaterials,
   className,
   style,
 }: QuizModuleProps) {
@@ -41,6 +44,11 @@ export function QuizModule({
   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 quiz step
   useEffect(() => {
@@ -63,25 +71,7 @@ export function QuizModule({
   }, [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 { correct, total, percentage } = scoreAssessment(questions, answers);
     const elapsed = startTimeRef.current
       ? Math.floor((Date.now() - startTimeRef.current) / 1000)
       : timeElapsed;
@@ -111,7 +101,7 @@ export function QuizModule({
   // ─── Intro Screen ───
   if (step.tag === "intro") {
     return (
-      <div className={cn("max-w-2xl mx-auto", 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 text-center">
             <div className="mx-auto mb-4 w-14 h-14 rounded-full bg-primary/10 flex items-center justify-center">
@@ -123,22 +113,22 @@ export function QuizModule({
                 {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>
+            <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 && (
-                <div className="flex items-center gap-2 text-sm text-muted-foreground">
-                  <Clock className="size-4" />
-                  <span>{formatDuration(timeLimitSeconds)} time limit</span>
-                </div>
+                <Badge variant="outline" className="gap-1.5">
+                  <Clock className="size-3.5" />
+                  {formatDuration(timeLimitSeconds)} time limit
+                </Badge>
               )}
               {passingScore !== undefined && (
-                <div className="flex items-center gap-2 text-sm text-muted-foreground">
-                  <CheckCircle2 className="size-4" />
-                  <span>{passingScore}% to pass</span>
-                </div>
+                <Badge variant="outline" className="gap-1.5">
+                  <CheckCircle2 className="size-3.5" />
+                  {passingScore}% to pass
+                </Badge>
               )}
             </div>
             <Button size="lg" onClick={() => setStep({ tag: "quiz" })}>
@@ -154,12 +144,13 @@ 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}
         />
       </div>
     );
@@ -170,62 +161,71 @@ export function QuizModule({
   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>
-      )}
+    <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 && (
-        <div>
+        <>
+          <Separator className="my-6" />
           <h3 className="text-lg font-semibold text-foreground mb-4">
             Question Review
           </h3>
@@ -234,7 +234,7 @@ export function QuizModule({
             sessionAnswers={result.answers}
             showCorrectAnswers
           />
-        </div>
+        </>
       )}
     </div>
   );

package/src/modules/QuizModule/types.ts

@@ -1,4 +1,4 @@
-import type { QuestionData, SessionAnswer } from "../../questions/types";
+import type { QuestionData, QuestionMaterial, SessionAnswer } from "../../questions/types";
 
 /**
  * QuizModule — a complete multi-step assessment experience.
@@ -34,6 +34,11 @@ 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[];
   /** CSS class name for the root element */
   className?: string;
   /** Inline styles for the root element */

package/src/modules/SurveyModule/SurveyModule.tsx

@@ -0,0 +1,180 @@
+import { useState, useRef, useEffect } from "react";
+import {
+  ClipboardList,
+  CheckCircle2,
+  HelpCircle,
+  RotateCcw,
+  Play,
+  Clock,
+} from "lucide-react";
+import { SurveyForm } from "../../sections/SurveyForm/SurveyForm";
+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 { SurveyAnswer } from "../../sections/SurveyForm/types";
+import type { SurveyModuleProps, SurveyModuleResult } from "./types";
+
+type InternalStep =
+  | { tag: "intro" }
+  | { tag: "survey" }
+  | { tag: "thankYou"; result: SurveyModuleResult };
+
+/**
+ * SurveyModule — a complete survey experience with intro, form, and thank-you steps.
+ *
+ * Steps: Intro → SurveyForm → Thank You with response stats.
+ */
+export function SurveyModule({
+  title,
+  description,
+  questions,
+  requireAll = false,
+  showProgress = true,
+  thankYouTitle = "Thank You!",
+  thankYouMessage,
+  onComplete,
+  allowRestart = false,
+  className,
+  style,
+}: SurveyModuleProps) {
+  const [step, setStep] = useState<InternalStep>({ tag: "intro" });
+  const startTimeRef = useRef<number | null>(null);
+  const contentRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    contentRef.current?.focus({ preventScroll: true });
+  }, [step.tag]);
+
+  function handleSubmit(answers: SurveyAnswer[]) {
+    const elapsed = startTimeRef.current
+      ? Math.floor((Date.now() - startTimeRef.current) / 1000)
+      : 0;
+    const result: SurveyModuleResult = {
+      answers,
+      totalQuestions: questions.length,
+      answeredCount: answers.length,
+      timeElapsedSeconds: elapsed,
+    };
+    setStep({ tag: "thankYou", result });
+    onComplete?.(result);
+  }
+
+  function handleRestart() {
+    startTimeRef.current = null;
+    setStep({ tag: "intro" });
+  }
+
+  function handleStart() {
+    startTimeRef.current = Date.now();
+    setStep({ tag: "survey" });
+  }
+
+  // ─── 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">
+              <ClipboardList 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>
+            </div>
+            <Button size="lg" onClick={handleStart}>
+              <Play className="size-4 mr-2" />
+              Begin Survey
+            </Button>
+          </CardContent>
+        </Card>
+      </div>
+    );
+  }
+
+  // ─── Survey Screen ───
+  if (step.tag === "survey") {
+    return (
+      <div
+        ref={contentRef}
+        tabIndex={-1}
+        className={cn("outline-none", className)}
+        style={style}
+      >
+        <SurveyForm
+          title={title}
+          questions={questions}
+          requireAll={requireAll}
+          showProgress={showProgress}
+          onSubmit={handleSubmit}
+        />
+      </div>
+    );
+  }
+
+  // ─── Thank You Screen ───
+  const { result } = step;
+
+  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-success/10 flex items-center justify-center">
+            <CheckCircle2 className="size-7 text-success" />
+          </div>
+          <h2 className="text-2xl font-bold text-foreground mb-2">
+            {thankYouTitle}
+          </h2>
+          <p className="text-muted-foreground mb-6 max-w-md mx-auto">
+            {thankYouMessage ?? "Your responses have been recorded. Thank you for your feedback!"}
+          </p>
+
+          {/* Stats */}
+          <div className="grid grid-cols-2 gap-3 max-w-sm mx-auto mb-6">
+            <StatCard
+              icon={<HelpCircle />}
+              label="Answered"
+              description="Questions completed"
+              value={`${result.answeredCount}/${result.totalQuestions}`}
+            />
+            <StatCard
+              icon={<Clock />}
+              label="Time"
+              description="Total elapsed"
+              value={formatDuration(result.timeElapsedSeconds)}
+            />
+          </div>
+
+          {/* Actions */}
+          {allowRestart && (
+            <Button variant="outline" onClick={handleRestart}>
+              <RotateCcw className="size-4 mr-2" />
+              Take Again
+            </Button>
+          )}
+        </CardContent>
+      </Card>
+    </div>
+  );
+}

package/src/modules/SurveyModule/types.ts

@@ -0,0 +1,51 @@
+import type { SurveyQuestion, SurveyAnswer } from "../../sections/SurveyForm/types";
+
+/**
+ * SurveyModule — a complete survey experience with intro, form, and thank-you steps.
+ *
+ * Wraps SurveyForm with a welcoming intro screen and a thank-you completion
+ * screen showing response stats.
+ *
+ * @example
+ * <SurveyModule
+ *   title="Course Evaluation"
+ *   description="Help us improve this course."
+ *   questions={surveyQuestions}
+ *   onComplete={(result) => submitSurvey(result)}
+ * />
+ */
+export interface SurveyModuleProps {
+  /** Survey title displayed on the intro and form screens */
+  title: string;
+  /** Survey description displayed on the intro screen */
+  description?: string;
+  /** Survey questions */
+  questions: SurveyQuestion[];
+  /** Whether all questions must be answered before submit. @default false */
+  requireAll?: boolean;
+  /** Whether to show a progress indicator in the survey form. @default true */
+  showProgress?: boolean;
+  /** Custom title for the thank-you screen. @default "Thank You!" */
+  thankYouTitle?: string;
+  /** Custom message for the thank-you screen */
+  thankYouMessage?: string;
+  /** Called when the survey is completed */
+  onComplete?: (result: SurveyModuleResult) => void;
+  /** Allow restarting the survey from the thank-you screen. @default false */
+  allowRestart?: boolean;
+  /** CSS class name for the root element */
+  className?: string;
+  /** Inline styles for the root element */
+  style?: React.CSSProperties;
+}
+
+export interface SurveyModuleResult {
+  /** The user's submitted answers */
+  answers: SurveyAnswer[];
+  /** Total number of questions */
+  totalQuestions: number;
+  /** Number of questions answered */
+  answeredCount: number;
+  /** Total time taken in seconds */
+  timeElapsedSeconds: number;
+}

package/src/modules/index.ts

@@ -10,3 +10,27 @@ export type {
 
 export { CoursePlayer } from "./CoursePlayer/CoursePlayer";
 export type { CoursePlayerProps, CoursePlayerItem } from "./CoursePlayer/types";
+
+export { ExamModule } from "./ExamModule/ExamModule";
+export type { ExamModuleProps, ExamModuleResult } from "./ExamModule/types";
+
+export { SurveyModule } from "./SurveyModule/SurveyModule";
+export type {
+  SurveyModuleProps,
+  SurveyModuleResult,
+} from "./SurveyModule/types";
+
+export { GradeCenterModule } from "./GradeCenterModule/GradeCenterModule";
+export type { GradeCenterModuleProps } from "./GradeCenterModule/types";
+
+export { AssignmentModule } from "./AssignmentModule/AssignmentModule";
+export type {
+  AssignmentModuleProps,
+  AssignmentModuleResult,
+} from "./AssignmentModule/types";
+
+export { CertificateModule } from "./CertificateModule/CertificateModule";
+export type { CertificateModuleProps } from "./CertificateModule/types";
+
+export { DiscussionModule } from "./DiscussionModule/DiscussionModule";
+export type { DiscussionModuleProps } from "./DiscussionModule/types";

package/src/progress/achievement-badge.tsx

@@ -0,0 +1,52 @@
+import { Trophy, Lock } from "lucide-react";
+import { Card } from "../ui/card";
+import { cn } from "../lib/utils";
+import type { AchievementBadgeProps } from "./types";
+
+const VARIANT_STYLES = {
+  default: "text-primary",
+  gold: "text-yellow-500",
+  silver: "text-gray-400",
+  bronze: "text-amber-700",
+} as const;
+
+/**
+ * AchievementBadge displays a single achievement or badge earned by a learner,
+ * with support for locked/earned states and metal-tier variants.
+ */
+export function AchievementBadge({
+  title,
+  description,
+  icon,
+  earnedDate,
+  locked = false,
+  variant = "default",
+  className,
+  style,
+}: AchievementBadgeProps) {
+  return (
+    <Card
+      className={cn("p-2 text-center", locked && "opacity-60", className)}
+      style={style}
+    >
+      <div className="mx-auto mb-1 w-12 h-12 flex items-center justify-center">
+        {locked ? (
+          <Lock size={32} className="text-muted-foreground" />
+        ) : (
+          icon ?? (
+            <Trophy size={32} className={VARIANT_STYLES[variant]} />
+          )
+        )}
+      </div>
+      <p className="font-semibold text-sm text-foreground">{title}</p>
+      {description && (
+        <p className="text-xs text-muted-foreground">{description}</p>
+      )}
+      {earnedDate && !locked && (
+        <p className="text-xs text-muted-foreground mt-0.5">
+          {new Date(earnedDate).toLocaleDateString()}
+        </p>
+      )}
+    </Card>
+  );
+}