@hydralms/components 0.1.3 → 0.3.0

package/src/sections/ProgressDashboard/ProgressDashboard.tsx

@@ -1,26 +1,24 @@
+import { useMemo } from "react";
+import { BookOpen, Clock, AlertCircle } from "lucide-react";
 import {
-  Award,
-  BookOpen,
-  CheckCircle,
-  Clock,
-  Flame,
-  Send,
-  Trophy,
-} from "lucide-react";
-import { ProgressRing, StatCard } from "../../progress";
+  ProgressRing,
+  StatCard,
+  AchievementBadge,
+  StreakBadge,
+  ActivityTimeline,
+} from "../../progress";
+import type { TimelineEvent } from "../../progress";
 import { Progress } from "../../ui/progress";
-import { Card } from "../../ui/card";
+import { Card, CardContent } from "../../ui/card";
+import { Separator } from "../../ui/separator";
+import { Skeleton } from "../../ui/skeleton";
+import { Button } from "../../ui/button";
+import { EmptyState } from "../../common/empty-state";
 import { formatDuration } from "../../utils/format-duration";
+import { pickPaletteVariant } from "../../utils/pick-palette-color";
 import type { ProgressDashboardProps } from "./types";
 import { cn } from "../../lib/utils";
 
-const ACTIVITY_ICONS = {
-  lesson_completed: BookOpen,
-  quiz_passed: CheckCircle,
-  assignment_submitted: Send,
-  badge_earned: Award,
-};
-
 export function ProgressDashboard({
   overallProgress,
   totalTimeSpent,
@@ -30,58 +28,122 @@ export function ProgressDashboard({
   achievements,
   recentActivityLimit = 5,
   onModuleClick,
+  isLoading,
+  error,
+  onRetry,
   className,
   style,
 }: ProgressDashboardProps) {
+  const completedModuleCount = useMemo(
+    () => modules.filter((m) => m.completedItems === m.totalItems).length,
+    [modules],
+  );
+
+  const timelineEvents = useMemo<TimelineEvent[]>(
+    () =>
+      recentActivity?.map((activity) => ({
+        uid: activity.uid,
+        type: activity.type,
+        title: activity.description,
+        timestamp: activity.timestamp,
+      })) ?? [],
+    [recentActivity],
+  );
+
+  if (isLoading) {
+    return (
+      <div className={cn("space-y-4", className)} style={style}>
+        <div className="grid grid-cols-3 gap-3">
+          <Skeleton className="h-24" />
+          <Skeleton className="h-24" />
+          <Skeleton className="h-24" />
+        </div>
+        <Skeleton className="h-32 w-32 rounded-full mx-auto" />
+        <Skeleton className="h-8 w-full" />
+        <Skeleton className="h-8 w-full" />
+        <Skeleton className="h-8 w-full" />
+      </div>
+    );
+  }
+
+  if (error) {
+    return (
+      <div className={cn("py-12", className)} style={style}>
+        <EmptyState
+          icon={<AlertCircle className="size-10 text-destructive" />}
+          title="Something went wrong"
+          description={error}
+          action={
+            onRetry ? (
+              <Button variant="outline" onClick={onRetry}>
+                Retry
+              </Button>
+            ) : undefined
+          }
+        />
+      </div>
+    );
+  }
+
   return (
     <div className={className} style={style}>
       {/* Stats row */}
-      <div className="grid grid-cols-[repeat(auto-fit,minmax(160px,1fr))] gap-2 mb-3">
-        <Card className="p-2 flex justify-center">
-          <ProgressRing value={overallProgress} size={100} />
+      <div className="grid grid-cols-[repeat(auto-fit,minmax(160px,1fr))] gap-3 mb-4">
+        <Card>
+          <CardContent className="p-3 flex justify-center">
+            <ProgressRing value={overallProgress} size={100} />
+          </CardContent>
         </Card>
         <StatCard
           icon={<Clock size={24} />}
           label="Time Spent"
+          description="Total learning time"
           value={formatDuration(totalTimeSpent)}
         />
         {streak && (
-          <StatCard
-            icon={<Flame size={24} />}
-            label="Current Streak"
-            value={`${streak.currentDays} days`}
-            subtitle={`Longest: ${streak.longestDays} days`}
-          />
+          <Card>
+            <CardContent className="p-4 flex items-center">
+              <StreakBadge
+                currentStreak={streak.currentDays}
+                longestStreak={streak.longestDays}
+                showLongest
+              />
+            </CardContent>
+          </Card>
         )}
         <StatCard
           icon={<BookOpen size={24} />}
           label="Modules"
-          value={`${modules.filter((m) => m.completedItems === m.totalItems).length} / ${modules.length}`}
+          description="Course progress"
+          value={`${completedModuleCount} / ${modules.length}`}
           subtitle="completed"
         />
       </div>
 
       {/* Module progress */}
+      <Separator className="mb-3" />
       <p className="text-lg font-semibold mb-2 text-foreground">Module Progress</p>
-      <div className="flex flex-col gap-2 mb-3">
-        {modules.map((mod) => {
+      <div className="flex flex-col gap-2 mb-4">
+        {modules.map((mod, index) => {
           const pct = mod.totalItems > 0 ? (mod.completedItems / mod.totalItems) * 100 : 0;
           return (
             <Card
               key={mod.uid}
               className={cn(
-                "p-2 transition-colors",
+                "transition-colors",
                 onModuleClick && "cursor-pointer hover:border-primary",
               )}
               onClick={() => onModuleClick?.(mod.uid)}
             >
-              <div className="flex justify-between items-center mb-0.5">
-                <span className="font-semibold text-sm text-foreground">{mod.name}</span>
-                <span className="text-xs text-muted-foreground">
-                  {mod.completedItems} / {mod.totalItems}
-                </span>
-              </div>
-              <Progress value={pct} size="sm" />
+              <CardContent className="p-3">
+                <div className="flex justify-between items-center mb-0.5">
+                  <span className="font-semibold text-sm text-foreground">{mod.name}</span>
+                  <span className="text-xs text-muted-foreground">
+                    {mod.completedItems} / {mod.totalItems}
+                  </span>
+                </div>
+                <Progress value={pct} size="sm" variant={pct >= 100 ? "success" : pickPaletteVariant(index)} />
+              </CardContent>
             </Card>
           );
         })}
@@ -90,22 +152,13 @@ export function ProgressDashboard({
       {/* Recent activity */}
       {recentActivity && recentActivity.length > 0 && (
         <>
+          <Separator className="mb-3" />
           <p className="text-lg font-semibold mb-2 text-foreground">Recent Activity</p>
-          <div className="flex flex-col gap-1.5 mb-3">
-            {recentActivity.slice(0, recentActivityLimit).map((activity) => {
-              const Icon = ACTIVITY_ICONS[activity.type] ?? CheckCircle;
-              return (
-                <div key={activity.uid} className="flex gap-1.5 items-center">
-                  <Icon size={16} />
-                  <span className="flex-1 text-sm text-foreground">
-                    {activity.description}
-                  </span>
-                  <span className="text-xs text-muted-foreground">
-                    {new Date(activity.timestamp).toLocaleDateString()}
-                  </span>
-                </div>
-              );
-            })}
+          <div className="mb-4">
+            <ActivityTimeline
+              events={timelineEvents}
+              limit={recentActivityLimit}
+            />
           </div>
         </>
       )}
@@ -113,24 +166,25 @@ export function ProgressDashboard({
       {/* Achievements */}
       {achievements && achievements.length > 0 && (
         <>
+          <Separator className="mb-3" />
           <p className="text-lg font-semibold mb-2 text-foreground">Achievements</p>
           <div className="grid grid-cols-[repeat(auto-fill,minmax(140px,1fr))] gap-2">
             {achievements.map((badge) => (
-              <Card key={badge.uid} className="p-2 text-center">
-                {badge.iconUrl ? (
-                  <img
-                    src={badge.iconUrl}
-                    alt={badge.name}
-                    className="w-12 h-12 mb-1 mx-auto"
-                  />
-                ) : (
-                  <Trophy size={32} className="mx-auto mb-2 text-warning" />
-                )}
-                <p className="font-semibold text-sm text-foreground">{badge.name}</p>
-                <p className="text-xs text-muted-foreground">
-                  {badge.description}
-                </p>
-              </Card>
+              <AchievementBadge
+                key={badge.uid}
+                title={badge.name}
+                description={badge.description}
+                icon={
+                  badge.iconUrl ? (
+                    <img
+                      src={badge.iconUrl}
+                      alt={badge.name}
+                      className="w-12 h-12"
+                    />
+                  ) : undefined
+                }
+                earnedDate={badge.earnedAt}
+              />
             ))}
           </div>
         </>

package/src/sections/ProgressDashboard/types.ts

@@ -30,6 +30,12 @@ export interface ProgressDashboardProps {
   recentActivityLimit?: number;
   /** Called when the user clicks a module */
   onModuleClick?: (moduleUid: string) => void;
+  /** Render skeleton placeholders instead of content */
+  isLoading?: boolean;
+  /** Error message — renders an error state with optional retry */
+  error?: string | null;
+  /** Called when the user clicks retry in the error state */
+  onRetry?: () => void;
   /** CSS class name for the root element */
   className?: string;
   /** Inline styles for the root element */

package/src/sections/QuizSession/QuizSession.tsx

@@ -1,11 +1,14 @@
-import { useMemo, useState } from "react";
-import { AssessmentToolbar } from "../../assessment-toolbar";
-import type { QuestionNavigatorItem } from "../../assessment-toolbar/types";
+import { useCallback, useRef } from "react";
+import { ChevronLeft, ChevronRight, Send } from "lucide-react";
+import { AssessmentToolbar, QuestionHeaderBar, QuestionMaterialsDrawer } from "../../assessment-toolbar";
 import { QuestionRenderer } from "../../questions";
-import type { SessionAnswer } from "../../questions/types";
-import { Card, CardContent } from "../../ui/card";
+import { Button } from "../../ui/button";
+import { Card, CardHeader, CardContent } from "../../ui/card";
+import { Skeleton } from "../../ui/skeleton";
+
+import { useAssessmentSession } from "../_shared/use-assessment-session";
+import { SectionShell } from "../_shared/section-shell";
 import type { QuizSessionProps } from "./types";
-import { cn } from "../../lib/utils";
 
 export function QuizSession({
   questions,
@@ -14,100 +17,145 @@ export function QuizSession({
   onAnswerChange,
   timeElapsedSeconds,
   timeLimitSeconds,
+  questionMaterials,
   isSubmitting = false,
   readOnly = false,
+  isLoading,
+  error,
+  onRetry,
   className,
   style,
 }: QuizSessionProps) {
-  const [currentIndex, setCurrentIndex] = useState(0);
-  const [sessionAnswers, setSessionAnswers] =
-    useState<SessionAnswer[]>(initialAnswers);
-  const [flaggedUids, setFlaggedUids] = useState<Set<string>>(new Set());
-
-  const currentQuestion = questions[currentIndex];
+  const {
+    currentIndex,
+    currentQuestion,
+    sessionAnswers,
+    flaggedUids,
+    materialsOpen,
+    setMaterialsOpen,
+    questionAreaRef,
+    currentQuestionAnswers,
+    currentMaterials,
+    navigatorItems,
+    handleAnswer,
+    handleNavigate,
+    handleToggleFlag,
+    goNext,
+    goPrevious,
+    hasNext,
+    hasPrevious,
+  } = useAssessmentSession({ questions, initialAnswers, onAnswerChange, questionMaterials });
 
-  const navigatorItems = useMemo<QuestionNavigatorItem[]>(
-    () =>
-      questions.map((q, idx) => ({
-        uid: q.uid,
-        sequence: idx + 1,
-        isFlagged: flaggedUids.has(q.uid),
-        isAnswered: sessionAnswers.some((a) => a.uid === q.uid),
-        isSkipped: false,
-      })),
-    [questions, sessionAnswers, flaggedUids],
-  );
+  const sessionAnswersRef = useRef(sessionAnswers);
+  sessionAnswersRef.current = sessionAnswers;
+  const onSubmitRef = useRef(onSubmit);
+  onSubmitRef.current = onSubmit;
 
-  function handleAnswer(rawAnswers: { uid: string; content?: string }[]) {
-    if (!currentQuestion) return;
-    const questionUid = currentQuestion.uid;
-    const newAnswers: SessionAnswer[] = rawAnswers.map((a) => ({
-      uid: questionUid,
-      answerUid: a.uid,
-      content: a.content,
-    }));
-    setSessionAnswers((prev) => {
-      const filtered = prev.filter((a) => a.uid !== questionUid);
-      const merged = [...filtered, ...newAnswers];
-      onAnswerChange?.(merged);
-      return merged;
-    });
-  }
+  const handleSubmit = useCallback(() => {
+    onSubmitRef.current(sessionAnswersRef.current);
+  }, []);
 
-  function handleNavigate(uid: string) {
-    const idx = questions.findIndex((q) => q.uid === uid);
-    if (idx !== -1) setCurrentIndex(idx);
-  }
+  const currentQuestionUidRef = useRef(currentQuestion?.uid);
+  currentQuestionUidRef.current = currentQuestion?.uid;
 
-  function handleToggleFlag(uid: string) {
-    setFlaggedUids((prev) => {
-      const next = new Set(prev);
-      if (next.has(uid)) {
-        next.delete(uid);
-      } else {
-        next.add(uid);
-      }
-      return next;
-    });
-  }
+  const toggleCurrentFlag = useCallback(() => {
+    const uid = currentQuestionUidRef.current;
+    if (uid) handleToggleFlag(uid);
+  }, [handleToggleFlag]);
 
-  function handleSubmit() {
-    onSubmit(sessionAnswers);
-  }
+  const openMaterials = useCallback(() => setMaterialsOpen(true), [setMaterialsOpen]);
 
   return (
-    <div className={cn(className)} style={style}>
+    <SectionShell
+      isLoading={isLoading}
+      error={error}
+      onRetry={onRetry}
+      className={className}
+      style={style}
+      skeleton={
+        <>
+          <Skeleton className="h-10 w-full" />
+          <Skeleton className="h-48 w-full" />
+          <Skeleton className="h-12 w-full" />
+        </>
+      }
+    >
+    <div>
       <AssessmentToolbar
         currentQuestionIndex={currentIndex}
         totalQuestions={questions.length}
-        hasNext={currentIndex < questions.length - 1}
-        hasPrevious={currentIndex > 0}
-        onNext={() => setCurrentIndex((i) => Math.min(i + 1, questions.length - 1))}
-        onPrevious={() => setCurrentIndex((i) => Math.max(i - 1, 0))}
+        hasNext={hasNext}
+        hasPrevious={hasPrevious}
+        onNext={goNext}
+        onPrevious={goPrevious}
         onSubmit={handleSubmit}
         timeElapsedSeconds={timeElapsedSeconds}
         timeLimitSeconds={timeLimitSeconds}
         questions={navigatorItems}
         onNavigateToQuestion={handleNavigate}
-        onToggleFlag={handleToggleFlag}
         currentQuestionUid={currentQuestion?.uid}
         isSubmitting={isSubmitting}
         readOnly={readOnly}
       />
+      <span className="sr-only" aria-live="polite">
+        Question {currentIndex + 1} of {questions.length}
+      </span>
       {currentQuestion && (
-        <Card className="mt-3">
-          <CardContent className="pt-6">
+        <Card className="mt-3" ref={questionAreaRef} tabIndex={-1}>
+          <CardHeader className="pb-0">
+            <QuestionHeaderBar
+              questionNumber={currentIndex + 1}
+              totalQuestions={questions.length}
+              isFlagged={flaggedUids.has(currentQuestion.uid)}
+              onToggleFlag={toggleCurrentFlag}
+              hasMaterials={currentMaterials.length > 0}
+              onOpenMaterials={openMaterials}
+              readOnly={readOnly}
+            />
+          </CardHeader>
+          <CardContent>
             <QuestionRenderer
               question={currentQuestion}
-              sessionAnswers={sessionAnswers.filter(
-                (a) => a.uid === currentQuestion.uid,
-              )}
+              sessionAnswers={currentQuestionAnswers}
               onAnswer={handleAnswer}
               readOnly={readOnly}
             />
           </CardContent>
         </Card>
       )}
+
+      {/* Bottom navigation */}
+      {!readOnly && (
+        <div className="flex items-center justify-between gap-3 mt-3">
+          <Button
+            variant="outline"
+            disabled={!hasPrevious}
+            onClick={goPrevious}
+          >
+            <ChevronLeft className="size-4 mr-1" />
+            Previous
+          </Button>
+          {hasNext ? (
+            <Button onClick={goNext}>
+              Next
+              <ChevronRight className="size-4 ml-1" />
+            </Button>
+          ) : (
+            <Button onClick={handleSubmit} disabled={isSubmitting}>
+              {isSubmitting ? "Submitting..." : "Submit Quiz"}
+              {!isSubmitting && <Send className="size-4 ml-1" />}
+            </Button>
+          )}
+        </div>
+      )}
+
+      <QuestionMaterialsDrawer
+        open={materialsOpen}
+        onOpenChange={setMaterialsOpen}
+        materials={currentMaterials}
+        questionNumber={currentIndex + 1}
+      />
     </div>
+    </SectionShell>
   );
 }

package/src/sections/QuizSession/types.ts

@@ -1,4 +1,4 @@
-import type { QuestionData, SessionAnswer } from "../../questions/types";
+import type { QuestionData, QuestionMaterial, SessionAnswer } from "../../questions/types";
 
 /**
  * QuizSession section — a complete assessment session experience.
@@ -38,8 +38,19 @@ export interface QuizSessionProps {
   timeLimitSeconds?: number;
   /** Whether the submit action is currently in flight */
   isSubmitting?: 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, all inputs are disabled (e.g. after submission) */
   readOnly?: boolean;
+  /** Render skeleton placeholders instead of content */
+  isLoading?: boolean;
+  /** Error message — renders an error state with optional retry */
+  error?: string | null;
+  /** Called when the user clicks retry in the error state */
+  onRetry?: () => void;
   /** CSS class name for the root element */
   className?: string;
   /** Inline styles for the root element */

package/src/sections/RequirementsChecklist/RequirementsChecklist.tsx

@@ -0,0 +1,147 @@
+import { useMemo } from "react";
+import { AlertCircle, CheckCircle2, Circle, ChevronRight } from "lucide-react";
+import { Skeleton } from "../../ui/skeleton";
+import { EmptyState } from "../../common/empty-state";
+import { Button } from "../../ui/button";
+import { Progress } from "../../ui/progress";
+import { cn } from "../../lib/utils";
+import type { RequirementsChecklistProps } from "./types";
+
+/**
+ * RequirementsChecklist — shows completion requirements with checked/unchecked status.
+ *
+ * Displays a vertical list of requirements with an overall progress bar.
+ * Incomplete items can be clicked to navigate to the relevant content.
+ */
+export function RequirementsChecklist({
+  title,
+  requirements,
+  onRequirementClick,
+  isLoading,
+  error,
+  onRetry,
+  className,
+  style,
+}: RequirementsChecklistProps) {
+  const completedCount = useMemo(
+    () => requirements.filter((r) => r.completed).length,
+    [requirements]
+  );
+  const progressPercent =
+    requirements.length > 0
+      ? Math.round((completedCount / requirements.length) * 100)
+      : 0;
+
+  if (isLoading) {
+    return (
+      <div className={cn("space-y-4", className)} style={style}>
+        <Skeleton className="h-6 w-48" />
+        <Skeleton className="h-2 w-full" />
+        {Array.from({ length: 4 }).map((_, i) => (
+          <div key={i} className="flex items-center gap-3">
+            <Skeleton className="h-5 w-5 rounded-full" />
+            <Skeleton className="h-4 w-3/4" />
+          </div>
+        ))}
+      </div>
+    );
+  }
+
+  if (error) {
+    return (
+      <div className={cn("py-12", className)} style={style}>
+        <EmptyState
+          icon={<AlertCircle className="size-10 text-destructive" />}
+          title="Something went wrong"
+          description={error}
+          action={
+            onRetry ? (
+              <Button variant="outline" onClick={onRetry}>
+                Retry
+              </Button>
+            ) : undefined
+          }
+        />
+      </div>
+    );
+  }
+
+  return (
+    <div className={cn("flex flex-col gap-4", className)} style={style}>
+      {/* Header */}
+      {title && (
+        <h3 className="text-lg font-semibold text-foreground">{title}</h3>
+      )}
+
+      {/* Progress bar */}
+      <div className="flex flex-col gap-1.5">
+        <div className="flex items-center justify-between text-sm">
+          <span className="text-muted-foreground">
+            {completedCount} of {requirements.length} complete
+          </span>
+          <span className="font-medium text-foreground">{progressPercent}%</span>
+        </div>
+        <Progress value={progressPercent} />
+      </div>
+
+      {/* Requirement list */}
+      <ul className="flex flex-col gap-1">
+        {requirements.map((req) => (
+          <li key={req.uid}>
+            <button
+              type="button"
+              className={cn(
+                "w-full flex items-start gap-3 p-3 rounded-lg text-left transition-colors",
+                req.completed
+                  ? "bg-success/5"
+                  : onRequirementClick
+                    ? "hover:bg-muted/50 cursor-pointer"
+                    : "cursor-default"
+              )}
+              onClick={() => {
+                if (!req.completed && onRequirementClick) {
+                  onRequirementClick(req.uid);
+                }
+              }}
+              disabled={req.completed}
+            >
+              {/* Icon */}
+              {req.completed ? (
+                <CheckCircle2 className="size-5 text-success shrink-0 mt-0.5" />
+              ) : (
+                <Circle className="size-5 text-muted-foreground shrink-0 mt-0.5" />
+              )}
+
+              {/* Content */}
+              <div className="flex-1 min-w-0">
+                <div
+                  className={cn(
+                    "text-sm font-medium",
+                    req.completed
+                      ? "text-muted-foreground line-through"
+                      : "text-foreground"
+                  )}
+                >
+                  {req.label}
+                </div>
+                {req.description && (
+                  <div className="text-xs text-muted-foreground mt-0.5">
+                    {req.description}
+                  </div>
+                )}
+              </div>
+
+              {/* Action indicator */}
+              {!req.completed && onRequirementClick && (
+                <div className="shrink-0 flex items-center gap-1 text-xs text-primary mt-0.5">
+                  {req.actionLabel && <span>{req.actionLabel}</span>}
+                  <ChevronRight className="size-4" />
+                </div>
+              )}
+            </button>
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}