@hydralms/components 0.2.0 → 0.3.0

package/src/sections/PracticeQuiz/PracticeQuiz.tsx

@@ -1,10 +1,12 @@
-import { useMemo, useState } from "react";
+import { useEffect, useMemo, useRef, useState } from "react";
 import { CheckCircle } from "lucide-react";
 import { QuestionRenderer, scoreQuestion } from "../../questions";
 import { FeedbackBanner } from "../../feedback";
 import { Button } from "../../ui/button";
 import { Card, CardContent } from "../../ui/card";
 import { Progress } from "../../ui/progress";
+import { Skeleton } from "../../ui/skeleton";
+import { SectionShell } from "../_shared/section-shell";
 import type { PracticeQuizProps, PracticeQuizStats } from "./types";
 import { shuffle } from "../../utils/shuffle";
 
@@ -15,11 +17,17 @@ export function PracticeQuiz({
   onComplete,
   shuffled = false,
   readOnly = false,
+  isLoading,
+  error,
+  onRetry,
   className,
   style,
 }: PracticeQuizProps) {
   const questions = useMemo(
-    () => (shuffled ? shuffle(questionsProp) : questionsProp),
+    () => {
+      const qs = questionsProp ?? [];
+      return shuffled ? shuffle(qs) : qs;
+    },
     // eslint-disable-next-line react-hooks/exhaustive-deps
     [questionsProp, shuffled],
   );
@@ -30,6 +38,16 @@ export function PracticeQuiz({
   const [firstAttemptCorrect, setFirstAttemptCorrect] = useState<Set<string>>(new Set());
   const [currentAnswer, setCurrentAnswer] = useState<{ uid: string; content?: string }[] | null>(null);
   const [isComplete, setIsComplete] = useState(false);
+  const questionAreaRef = useRef<HTMLDivElement>(null);
+  const isFirstRender = useRef(true);
+
+  useEffect(() => {
+    if (isFirstRender.current) {
+      isFirstRender.current = false;
+      return;
+    }
+    questionAreaRef.current?.focus();
+  }, [currentIndex]);
 
   const currentQuestion = questions[currentIndex];
   const isRevealed = currentQuestion ? revealedUids.has(currentQuestion.uid) : false;
@@ -78,27 +96,45 @@ export function PracticeQuiz({
     }
   }
 
-  const isCurrentCorrect = useMemo(() => {
-    if (!currentQuestion || !currentAnswer) return false;
-    const sessionAnswers = currentAnswer.map((a) => ({
+  const currentSessionAnswers = useMemo(() => {
+    if (!currentQuestion || !currentAnswer) return [];
+    return currentAnswer.map((a) => ({
       uid: currentQuestion.uid,
       answerUid: a.uid,
       content: a.content,
     }));
-    return scoreQuestion(currentQuestion, sessionAnswers) === true;
   }, [currentQuestion, currentAnswer]);
 
-  if (isComplete) {
-    const percentage = questions.length > 0
-      ? Math.round((firstAttemptCorrect.size / questions.length) * 100)
-      : 0;
-    return (
+  const isCurrentCorrect = useMemo(
+    () => currentQuestion ? scoreQuestion(currentQuestion, currentSessionAnswers) === true : false,
+    [currentQuestion, currentSessionAnswers],
+  );
+
+  const completionPercentage = questions.length > 0
+    ? Math.round((firstAttemptCorrect.size / questions.length) * 100)
+    : 0;
+
+  return (
+    <SectionShell
+      isLoading={isLoading}
+      error={error}
+      onRetry={onRetry}
+      className={className}
+      style={style}
+      skeleton={
+        <>
+          <Skeleton className="h-2 w-full" />
+          <Skeleton className="h-48 w-full" />
+        </>
+      }
+    >
+    {isComplete ? (
       <Card className={className} style={style}>
         <CardContent className="pt-6 text-center">
           <CheckCircle size={48} className="text-success mx-auto mb-4" />
           <p className="text-xl font-bold mb-1 text-foreground">Practice Complete!</p>
           <p className="text-muted-foreground mb-2">
-            {firstAttemptCorrect.size} of {questions.length} correct on first attempt ({percentage}%)
+            {firstAttemptCorrect.size} of {questions.length} correct on first attempt ({completionPercentage}%)
           </p>
           <div className="flex justify-center">
             <Button
@@ -117,72 +153,68 @@ export function PracticeQuiz({
           </div>
         </CardContent>
       </Card>
-    );
-  }
+    ) : (
+      <div className={className} style={style}>
+        <div className="flex justify-between items-center mb-2">
+          <span className="font-semibold text-sm text-foreground">
+            Question {currentIndex + 1} of {questions.length}
+          </span>
+          <span className="text-xs text-muted-foreground">
+            {firstAttemptCorrect.size} correct on first try
+          </span>
+        </div>
+        <Progress
+          value={currentIndex + (isRevealed ? 1 : 0)}
+          max={questions.length}
+          size="sm"
+          className="mb-3"
+        />
 
-  return (
-    <div className={className} style={style}>
-      <div className="flex justify-between items-center mb-2">
-        <span className="font-semibold text-sm text-foreground">
+        <span className="sr-only" aria-live="polite">
           Question {currentIndex + 1} of {questions.length}
         </span>
-        <span className="text-xs text-muted-foreground">
-          {firstAttemptCorrect.size} correct on first try
-        </span>
-      </div>
-      <Progress
-        value={currentIndex + (isRevealed ? 1 : 0)}
-        max={questions.length}
-        size="sm"
-        className="mb-3"
-      />
-
-      {currentQuestion && (
-        <Card>
-          <CardContent className="pt-6">
-            <QuestionRenderer
-              question={currentQuestion}
-              sessionAnswers={
-                currentAnswer?.map((a) => ({
-                  uid: currentQuestion.uid,
-                  answerUid: a.uid,
-                  content: a.content,
-                })) ?? []
-              }
-              onAnswer={(answers) => setCurrentAnswer(answers)}
-              readOnly={readOnly || isRevealed}
-              showCorrectAnswers={isRevealed}
-            />
-
-            {instantFeedback && isRevealed && (
-              <FeedbackBanner
-                isCorrect={isCurrentCorrect}
-                explanation={currentQuestion.explanation}
-                onRetry={allowRetry && !isCurrentCorrect ? handleRetry : undefined}
+        {currentQuestion && (
+          <Card ref={questionAreaRef} tabIndex={-1}>
+            <CardContent className="pt-6">
+              <QuestionRenderer
+                question={currentQuestion}
+                sessionAnswers={currentSessionAnswers}
+                onAnswer={setCurrentAnswer}
+                readOnly={readOnly || isRevealed}
+                showCorrectAnswers={isRevealed}
               />
-            )}
-
-            <div className="flex justify-end gap-2 mt-2">
-              {!isRevealed && instantFeedback && (
-                <Button
-                  onClick={checkAnswer}
-                  disabled={!currentAnswer || currentAnswer.length === 0 || readOnly}
-                >
-                  Check Answer
-                </Button>
-              )}
-              {(!instantFeedback || isRevealed) && (
-                <Button
-                  onClick={handleNext}
-                  disabled={readOnly}
-                >
-                  {currentIndex < questions.length - 1 ? "Next Question" : "Finish"}
-                </Button>
+
+              {instantFeedback && isRevealed && (
+                <FeedbackBanner
+                  isCorrect={isCurrentCorrect}
+                  explanation={currentQuestion.explanation}
+                  onRetry={allowRetry && !isCurrentCorrect ? handleRetry : undefined}
+                />
               )}
-            </div>
-          </CardContent>
-        </Card>
-      )}
-    </div>
+
+              <div className="flex justify-end gap-2 mt-2">
+                {!isRevealed && instantFeedback && (
+                  <Button
+                    onClick={checkAnswer}
+                    disabled={!currentAnswer || currentAnswer.length === 0 || readOnly}
+                  >
+                    Check Answer
+                  </Button>
+                )}
+                {(!instantFeedback || isRevealed) && (
+                  <Button
+                    onClick={handleNext}
+                    disabled={readOnly}
+                  >
+                    {currentIndex < questions.length - 1 ? "Next Question" : "Finish"}
+                  </Button>
+                )}
+              </div>
+            </CardContent>
+          </Card>
+        )}
+      </div>
+    )}
+    </SectionShell>
   );
 }

package/src/sections/PracticeQuiz/types.ts

@@ -28,6 +28,12 @@ export interface PracticeQuizProps {
   shuffled?: boolean;
   /** When true, all inputs are disabled */
   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/ProgressDashboard/ProgressDashboard.tsx

@@ -1,4 +1,5 @@
-import { BookOpen, Clock } from "lucide-react";
+import { useMemo } from "react";
+import { BookOpen, Clock, AlertCircle } from "lucide-react";
 import {
   ProgressRing,
   StatCard,
@@ -10,7 +11,11 @@ import type { TimelineEvent } from "../../progress";
 import { Progress } from "../../ui/progress";
 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";
 
@@ -23,9 +28,63 @@ 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 */}
@@ -56,7 +115,7 @@ export function ProgressDashboard({
           icon={<BookOpen size={24} />}
           label="Modules"
           description="Course progress"
-          value={`${modules.filter((m) => m.completedItems === m.totalItems).length} / ${modules.length}`}
+          value={`${completedModuleCount} / ${modules.length}`}
           subtitle="completed"
         />
       </div>
@@ -65,7 +124,7 @@ export function ProgressDashboard({
       <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-4">
-        {modules.map((mod) => {
+        {modules.map((mod, index) => {
           const pct = mod.totalItems > 0 ? (mod.completedItems / mod.totalItems) * 100 : 0;
           return (
             <Card
@@ -83,7 +142,7 @@ export function ProgressDashboard({
                     {mod.completedItems} / {mod.totalItems}
                   </span>
                 </div>
-                <Progress value={pct} size="sm" />
+                <Progress value={pct} size="sm" variant={pct >= 100 ? "success" : pickPaletteVariant(index)} />
               </CardContent>
             </Card>
           );
@@ -97,12 +156,7 @@ export function ProgressDashboard({
           <p className="text-lg font-semibold mb-2 text-foreground">Recent Activity</p>
           <div className="mb-4">
             <ActivityTimeline
-              events={recentActivity.map<TimelineEvent>((activity) => ({
-                uid: activity.uid,
-                type: activity.type,
-                title: activity.description,
-                timestamp: activity.timestamp,
-              }))}
+              events={timelineEvents}
               limit={recentActivityLimit}
             />
           </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,13 +1,14 @@
-import { useMemo, useState } from "react";
+import { useCallback, useRef } from "react";
 import { ChevronLeft, ChevronRight, Send } from "lucide-react";
 import { AssessmentToolbar, QuestionHeaderBar, QuestionMaterialsDrawer } from "../../assessment-toolbar";
-import type { QuestionNavigatorItem } from "../../assessment-toolbar/types";
 import { QuestionRenderer } from "../../questions";
-import type { SessionAnswer } from "../../questions/types";
 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,
@@ -19,88 +20,74 @@ export function QuizSession({
   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 [materialsOpen, setMaterialsOpen] = useState(false);
+  const {
+    currentIndex,
+    currentQuestion,
+    sessionAnswers,
+    flaggedUids,
+    materialsOpen,
+    setMaterialsOpen,
+    questionAreaRef,
+    currentQuestionAnswers,
+    currentMaterials,
+    navigatorItems,
+    handleAnswer,
+    handleNavigate,
+    handleToggleFlag,
+    goNext,
+    goPrevious,
+    hasNext,
+    hasPrevious,
+  } = useAssessmentSession({ questions, initialAnswers, onAnswerChange, questionMaterials });
 
-  const currentQuestion = questions[currentIndex];
+  const sessionAnswersRef = useRef(sessionAnswers);
+  sessionAnswersRef.current = sessionAnswers;
+  const onSubmitRef = useRef(onSubmit);
+  onSubmitRef.current = onSubmit;
 
-  const currentQuestionAnswers = useMemo(
-    () =>
-      currentQuestion
-        ? sessionAnswers.filter((a) => a.uid === currentQuestion.uid)
-        : [],
-    [sessionAnswers, currentQuestion],
-  );
+  const handleSubmit = useCallback(() => {
+    onSubmitRef.current(sessionAnswersRef.current);
+  }, []);
 
-  const currentMaterials = useMemo(
-    () => questionMaterials?.filter((m) => m.questionUid === currentQuestion?.uid) ?? [],
-    [questionMaterials, currentQuestion],
-  );
-
-  const navigatorItems = useMemo<QuestionNavigatorItem[]>(
-    () =>
-      questions.map((q, idx) => ({
-        uid: q.uid,
-        sequence: idx,
-        isFlagged: flaggedUids.has(q.uid),
-        isAnswered: sessionAnswers.some((a) => a.uid === q.uid),
-        isSkipped: false,
-      })),
-    [questions, sessionAnswers, flaggedUids],
-  );
+  const currentQuestionUidRef = useRef(currentQuestion?.uid);
+  currentQuestionUidRef.current = currentQuestion?.uid;
 
-  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 toggleCurrentFlag = useCallback(() => {
+    const uid = currentQuestionUidRef.current;
+    if (uid) handleToggleFlag(uid);
+  }, [handleToggleFlag]);
 
-  function handleNavigate(uid: string) {
-    const idx = questions.findIndex((q) => q.uid === uid);
-    if (idx !== -1) setCurrentIndex(idx);
-  }
-
-  function handleToggleFlag(uid: string) {
-    setFlaggedUids((prev) => {
-      const next = new Set(prev);
-      if (next.has(uid)) {
-        next.delete(uid);
-      } else {
-        next.add(uid);
-      }
-      return next;
-    });
-  }
-
-  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}
@@ -110,16 +97,19 @@ export function QuizSession({
         isSubmitting={isSubmitting}
         readOnly={readOnly}
       />
+      <span className="sr-only" aria-live="polite">
+        Question {currentIndex + 1} of {questions.length}
+      </span>
       {currentQuestion && (
-        <Card className="mt-3">
+        <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={() => handleToggleFlag(currentQuestion.uid)}
+              onToggleFlag={toggleCurrentFlag}
               hasMaterials={currentMaterials.length > 0}
-              onOpenMaterials={() => setMaterialsOpen(true)}
+              onOpenMaterials={openMaterials}
               readOnly={readOnly}
             />
           </CardHeader>
@@ -139,16 +129,14 @@ export function QuizSession({
         <div className="flex items-center justify-between gap-3 mt-3">
           <Button
             variant="outline"
-            disabled={currentIndex <= 0}
-            onClick={() => setCurrentIndex((i) => Math.max(i - 1, 0))}
+            disabled={!hasPrevious}
+            onClick={goPrevious}
           >
             <ChevronLeft className="size-4 mr-1" />
             Previous
           </Button>
-          {currentIndex < questions.length - 1 ? (
-            <Button
-              onClick={() => setCurrentIndex((i) => Math.min(i + 1, questions.length - 1))}
-            >
+          {hasNext ? (
+            <Button onClick={goNext}>
               Next
               <ChevronRight className="size-4 ml-1" />
             </Button>
@@ -168,5 +156,6 @@ export function QuizSession({
         questionNumber={currentIndex + 1}
       />
     </div>
+    </SectionShell>
   );
 }

package/src/sections/QuizSession/types.ts

@@ -45,6 +45,12 @@ export interface QuizSessionProps {
   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

@@ -1,5 +1,8 @@
 import { useMemo } from "react";
-import { CheckCircle2, Circle, ChevronRight } from "lucide-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";
@@ -14,6 +17,9 @@ export function RequirementsChecklist({
   title,
   requirements,
   onRequirementClick,
+  isLoading,
+  error,
+  onRetry,
   className,
   style,
 }: RequirementsChecklistProps) {
@@ -26,6 +32,40 @@ export function RequirementsChecklist({
       ? 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 */}