@hydralms/components 0.2.0 → 0.3.1

package/src/sections/EnrollmentWizard/EnrollmentWizard.tsx

@@ -0,0 +1,343 @@
+import { useState, useMemo } from "react";
+import {
+  CheckCircle2,
+  XCircle,
+  AlertCircle,
+  Clock,
+  BookOpen,
+  Loader2,
+} from "lucide-react";
+import { Stepper } from "../../common/stepper";
+import { Card, CardContent } from "../../ui/card";
+import { Button } from "../../ui/button";
+import { Badge } from "../../ui/badge";
+import { Separator } from "../../ui/separator";
+import { UserAvatar } from "../../social/user-avatar";
+import { Skeleton } from "../../ui/skeleton";
+import { EmptyState } from "../../common/empty-state";
+import { cn } from "../../lib/utils";
+import type { EnrollmentWizardProps } from "./types";
+
+type Step = "details" | "prerequisites" | "confirmation";
+
+export function EnrollmentWizard({
+  course,
+  prerequisites,
+  onEnroll,
+  onCancel,
+  enrollLabel = "Enroll Now",
+  isEnrolling = false,
+  isLoading,
+  error,
+  onRetry,
+  className,
+  style,
+}: EnrollmentWizardProps) {
+  const hasPrerequisites =
+    Array.isArray(prerequisites) && prerequisites.length > 0;
+
+  const [step, setStep] = useState<Step>("details");
+
+  /* ------------------------------------------------------------------ */
+  /*  Stepper setup                                                      */
+  /* ------------------------------------------------------------------ */
+  const allSteps = useMemo<{ key: Step; label: string }[]>(
+    () =>
+      hasPrerequisites
+        ? [
+            { key: "details", label: "Course Details" },
+            { key: "prerequisites", label: "Prerequisites" },
+            { key: "confirmation", label: "Confirmation" },
+          ]
+        : [
+            { key: "details", label: "Course Details" },
+            { key: "confirmation", label: "Confirmation" },
+          ],
+    [hasPrerequisites],
+  );
+
+  /* ------------------------------------------------------------------ */
+  /*  Loading early return                                               */
+  /* ------------------------------------------------------------------ */
+  if (isLoading) {
+    return (
+      <div className={cn("space-y-4", className)} style={style}>
+        <Skeleton className="h-8 w-48" />
+        <Skeleton className="h-48 w-full" />
+        <Skeleton className="h-10 w-32" />
+      </div>
+    );
+  }
+
+  /* ------------------------------------------------------------------ */
+  /*  Error early return                                                 */
+  /* ------------------------------------------------------------------ */
+  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>
+    );
+  }
+
+  const currentStepIndex = allSteps.findIndex((s) => s.key === step);
+
+  const allPrerequisitesMet =
+    !hasPrerequisites || prerequisites!.every((p) => p.isMet);
+
+  /* ------------------------------------------------------------------ */
+  /*  Navigation helpers                                                 */
+  /* ------------------------------------------------------------------ */
+  function goNext() {
+    const nextIndex = currentStepIndex + 1;
+    if (nextIndex < allSteps.length) {
+      setStep(allSteps[nextIndex].key);
+    }
+  }
+
+  function goBack() {
+    const prevIndex = currentStepIndex - 1;
+    if (prevIndex >= 0) {
+      setStep(allSteps[prevIndex].key);
+    }
+  }
+
+  /* ------------------------------------------------------------------ */
+  /*  Details step                                                       */
+  /* ------------------------------------------------------------------ */
+  function renderDetails() {
+    return (
+      <Card>
+        <CardContent className="pt-6">
+          {/* Thumbnail or initial placeholder */}
+          {course.thumbnailUrl ? (
+            <img
+              src={course.thumbnailUrl}
+              alt={course.title}
+              className="w-full h-48 object-cover rounded-lg mb-4"
+            />
+          ) : (
+            <div className="w-full h-48 rounded-lg mb-4 bg-muted flex items-center justify-center">
+              <BookOpen className="size-12 text-muted-foreground" />
+            </div>
+          )}
+
+          {/* Title */}
+          <h2 className="text-xl font-bold text-foreground mb-1">
+            {course.title}
+          </h2>
+
+          {/* Description */}
+          {course.description && (
+            <p className="text-sm text-muted-foreground mb-3">
+              {course.description}
+            </p>
+          )}
+
+          {/* Instructor + duration row */}
+          <div className="flex items-center gap-3 mb-3">
+            {course.instructor && (
+              <div className="flex items-center gap-2">
+                <UserAvatar
+                  displayName={course.instructor.displayName}
+                  avatarUrl={course.instructor.avatarUrl}
+                  size="small"
+                />
+                <span className="text-sm text-foreground">
+                  {course.instructor.displayName}
+                </span>
+              </div>
+            )}
+            {course.duration && (
+              <Badge variant="muted">
+                <Clock className="size-3 mr-1" />
+                {course.duration}
+              </Badge>
+            )}
+          </div>
+
+          {/* Syllabus */}
+          {course.syllabus && course.syllabus.length > 0 && (
+            <>
+              <Separator className="my-3" />
+              <div className="mb-1 text-sm font-semibold text-foreground">
+                Syllabus
+              </div>
+              <ul className="list-disc list-inside space-y-1">
+                {course.syllabus.map((item, i) => (
+                  <li key={i} className="text-sm text-muted-foreground">
+                    {item}
+                  </li>
+                ))}
+              </ul>
+            </>
+          )}
+
+          {/* Actions */}
+          <Separator className="my-4" />
+          <div className="flex justify-end gap-2">
+            {onCancel && (
+              <Button variant="outline" onClick={onCancel}>
+                Cancel
+              </Button>
+            )}
+            <Button onClick={goNext}>Continue</Button>
+          </div>
+        </CardContent>
+      </Card>
+    );
+  }
+
+  /* ------------------------------------------------------------------ */
+  /*  Prerequisites step                                                 */
+  /* ------------------------------------------------------------------ */
+  function renderPrerequisites() {
+    return (
+      <Card>
+        <CardContent className="pt-6">
+          <h3 className="text-lg font-semibold text-foreground mb-3">
+            Prerequisites
+          </h3>
+
+          <ul className="space-y-3">
+            {prerequisites!.map((prereq) => (
+              <li key={prereq.uid} className="flex items-start gap-2">
+                {prereq.isMet ? (
+                  <CheckCircle2 className="size-4 text-success shrink-0 mt-0.5" />
+                ) : (
+                  <XCircle className="size-4 text-destructive shrink-0 mt-0.5" />
+                )}
+                <div>
+                  <span className="text-sm font-medium text-foreground">
+                    {prereq.label}
+                  </span>
+                  {prereq.description && (
+                    <p className="text-xs text-muted-foreground mt-0.5">
+                      {prereq.description}
+                    </p>
+                  )}
+                </div>
+              </li>
+            ))}
+          </ul>
+
+          <Separator className="my-4" />
+          <div className="flex justify-end gap-2">
+            <Button variant="outline" onClick={goBack}>
+              Back
+            </Button>
+            <Button onClick={goNext} disabled={!allPrerequisitesMet}>
+              Continue
+            </Button>
+          </div>
+        </CardContent>
+      </Card>
+    );
+  }
+
+  /* ------------------------------------------------------------------ */
+  /*  Confirmation step                                                  */
+  /* ------------------------------------------------------------------ */
+  function renderConfirmation() {
+    return (
+      <Card>
+        <CardContent className="pt-6">
+          <h3 className="text-lg font-semibold text-foreground mb-3">
+            Confirm Enrollment
+          </h3>
+
+          {/* Summary */}
+          <div className="space-y-2 mb-3">
+            <div className="flex items-center gap-2">
+              <BookOpen className="size-4 text-muted-foreground" />
+              <span className="text-sm font-medium text-foreground">
+                {course.title}
+              </span>
+            </div>
+            {course.instructor && (
+              <div className="flex items-center gap-2">
+                <UserAvatar
+                  displayName={course.instructor.displayName}
+                  avatarUrl={course.instructor.avatarUrl}
+                  size="small"
+                />
+                <span className="text-sm text-muted-foreground">
+                  {course.instructor.displayName}
+                </span>
+              </div>
+            )}
+            {course.duration && (
+              <div className="flex items-center gap-2">
+                <Clock className="size-4 text-muted-foreground" />
+                <span className="text-sm text-muted-foreground">
+                  {course.duration}
+                </span>
+              </div>
+            )}
+          </div>
+
+          {/* Prerequisites badge */}
+          {hasPrerequisites && (
+            <div className="mb-3">
+              {allPrerequisitesMet ? (
+                <Badge variant="success">
+                  <CheckCircle2 className="size-3 mr-1" />
+                  All prerequisites met
+                </Badge>
+              ) : (
+                <Badge variant="warning">
+                  <XCircle className="size-3 mr-1" />
+                  Some prerequisites not met
+                </Badge>
+              )}
+            </div>
+          )}
+
+          <Separator className="my-4" />
+          <div className="flex justify-end gap-2">
+            <Button variant="outline" onClick={goBack}>
+              Back
+            </Button>
+            <Button
+              onClick={() => onEnroll(course.uid)}
+              disabled={isEnrolling}
+            >
+              {isEnrolling && (
+                <Loader2 className="size-4 mr-1 animate-spin" />
+              )}
+              {enrollLabel}
+            </Button>
+          </div>
+        </CardContent>
+      </Card>
+    );
+  }
+
+  /* ------------------------------------------------------------------ */
+  /*  Render                                                             */
+  /* ------------------------------------------------------------------ */
+  return (
+    <div className={className} style={style}>
+      <Stepper
+        steps={allSteps.map((s) => ({ label: s.label }))}
+        currentStep={currentStepIndex}
+        className="mb-6"
+      />
+
+      {step === "details" && renderDetails()}
+      {step === "prerequisites" && renderPrerequisites()}
+      {step === "confirmation" && renderConfirmation()}
+    </div>
+  );
+}

package/src/sections/EnrollmentWizard/types.ts

@@ -0,0 +1,65 @@
+/**
+ * EnrollmentWizard section — a multi-step course enrollment flow.
+ *
+ * Guides users through course details, prerequisite checks, and enrollment
+ * confirmation with visual step progress.
+ *
+ * @example
+ * <EnrollmentWizard
+ *   course={{ uid: "c1", title: "React 101", description: "Learn React" }}
+ *   prerequisites={[{ uid: "p1", label: "JavaScript Basics", isMet: true }]}
+ *   onEnroll={(courseUid) => enroll(courseUid)}
+ * />
+ */
+export interface EnrollmentWizardProps {
+  /** Course information to display */
+  course: EnrollmentCourse;
+  /** Prerequisites for enrollment */
+  prerequisites?: Prerequisite[];
+  /** Called when the user confirms enrollment */
+  onEnroll: (courseUid: string) => void;
+  /** Called when the user cancels the wizard */
+  onCancel?: () => void;
+  /** Label for the enroll button */
+  enrollLabel?: string;
+  /** Whether enrollment is in progress (shows spinner) */
+  isEnrolling?: 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 */
+  style?: React.CSSProperties;
+}
+
+export interface EnrollmentCourse {
+  /** Course UID */
+  uid: string;
+  /** Course title */
+  title: string;
+  /** Course description */
+  description?: string;
+  /** Thumbnail image URL */
+  thumbnailUrl?: string;
+  /** Instructor info */
+  instructor?: { displayName: string; avatarUrl?: string };
+  /** Estimated duration */
+  duration?: string;
+  /** Syllabus bullet points */
+  syllabus?: string[];
+}
+
+export interface Prerequisite {
+  /** Unique identifier */
+  uid: string;
+  /** Prerequisite label */
+  label: string;
+  /** Whether this prerequisite has been met */
+  isMet: boolean;
+  /** Optional description */
+  description?: string;
+}

package/src/sections/ExamSession/ExamSession.tsx

@@ -1,16 +1,17 @@
-import { useEffect, useMemo, useRef, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "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 { ConfirmDialog } from "../../common";
+import { QuestionRenderer } from "../../questions";
 import { Alert, AlertDescription } from "../../ui/alert";
 import { Card, CardHeader, CardContent } from "../../ui/card";
-import { cn } from "../../lib/utils";
+import { Skeleton } from "../../ui/skeleton";
+
+import { useAssessmentSession } from "../_shared/use-assessment-session";
+import { SectionShell } from "../_shared/section-shell";
 import type { ExamSessionProps, ExamSubmitMetadata } from "./types";
 
 export function ExamSession({
-  questions,
+  questions = [],
   initialAnswers = [],
   onSubmit,
   onAnswerChange,
@@ -25,32 +26,63 @@ export function ExamSession({
   questionMaterials,
   isSubmitting = false,
   readOnly = false,
+  isLoading,
+  error,
+  onRetry,
   className,
   style,
 }: ExamSessionProps) {
-  const [currentIndex, setCurrentIndex] = useState(0);
-  const [sessionAnswers, setSessionAnswers] = useState<SessionAnswer[]>(initialAnswers);
-  const [flaggedUids, setFlaggedUids] = useState<Set<string>>(new Set());
+  const {
+    currentIndex,
+    currentQuestion,
+    sessionAnswers,
+    flaggedUids,
+    materialsOpen,
+    setMaterialsOpen,
+    questionAreaRef,
+    currentQuestionAnswers,
+    currentMaterials,
+    navigatorItems,
+    handleAnswer,
+    handleNavigate,
+    handleToggleFlag,
+    goNext,
+    goPrevious,
+    hasNext,
+  } = useAssessmentSession({ questions, initialAnswers, onAnswerChange, questionMaterials });
+
   const [showConfirm, setShowConfirm] = useState(false);
   const [showTimeWarning, setShowTimeWarning] = useState(false);
-  const [materialsOpen, setMaterialsOpen] = useState(false);
   const hasAutoSubmitted = useRef(false);
 
-  const currentQuestion = questions[currentIndex];
+  // Refs for stable callbacks
+  const sessionAnswersRef = useRef(sessionAnswers);
+  sessionAnswersRef.current = sessionAnswers;
+  const onSubmitRef = useRef(onSubmit);
+  onSubmitRef.current = onSubmit;
+  const timeElapsedSecondsRef = useRef(timeElapsedSeconds);
+  timeElapsedSecondsRef.current = timeElapsedSeconds;
+  const currentQuestionUidRef = useRef(currentQuestion?.uid);
+  currentQuestionUidRef.current = currentQuestion?.uid;
+
   const remainingSeconds = timeLimitSeconds - timeElapsedSeconds;
 
-  const currentQuestionAnswers = useMemo(
-    () =>
-      currentQuestion
-        ? sessionAnswers.filter((a) => a.uid === currentQuestion.uid)
-        : [],
-    [sessionAnswers, currentQuestion],
+  const answeredCount = useMemo(
+    () => navigatorItems.filter((q) => q.isAnswered).length,
+    [navigatorItems],
   );
 
-  const currentMaterials = useMemo(
-    () => questionMaterials?.filter((m) => m.questionUid === currentQuestion?.uid) ?? [],
-    [questionMaterials, currentQuestion],
-  );
+  const doSubmit = useCallback((wasAutoSubmitted: boolean) => {
+    const answers = sessionAnswersRef.current;
+    const answeredUids = new Set(answers.map((a) => a.uid));
+    const metadata: ExamSubmitMetadata = {
+      timeElapsedSeconds: timeElapsedSecondsRef.current,
+      wasAutoSubmitted,
+      answeredCount: questions.filter((q) => answeredUids.has(q.uid)).length,
+      totalQuestions: questions.length,
+    };
+    onSubmitRef.current(answers, metadata);
+  }, [questions]);
 
   useEffect(() => {
     if (remainingSeconds <= timeWarningThreshold && remainingSeconds > 0) {
@@ -63,77 +95,50 @@ export function ExamSession({
       hasAutoSubmitted.current = true;
       doSubmit(true);
     }
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [remainingSeconds, autoSubmitOnTimeout]);
-
-  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],
-  );
+  }, [remainingSeconds, autoSubmitOnTimeout, doSubmit]);
 
-  const answeredCount = useMemo(
-    () => navigatorItems.filter((q) => q.isAnswered).length,
-    [navigatorItems],
-  );
-
-  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;
-    });
-  }
-
-  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 handleSubmitClick() {
+  const handleSubmitClick = useCallback(() => {
     if (confirmBeforeSubmit) {
       setShowConfirm(true);
     } else {
       doSubmit(false);
     }
-  }
+  }, [confirmBeforeSubmit, doSubmit]);
 
-  function doSubmit(wasAutoSubmitted: boolean) {
-    const answeredUids = new Set(sessionAnswers.map((a) => a.uid));
-    const metadata: ExamSubmitMetadata = {
-      timeElapsedSeconds,
-      wasAutoSubmitted,
-      answeredCount: questions.filter((q) => answeredUids.has(q.uid)).length,
-      totalQuestions: questions.length,
-    };
-    onSubmit(sessionAnswers, metadata);
-  }
+  const handlePrevious = useCallback(() => {
+    if (allowBackNavigation) goPrevious();
+  }, [allowBackNavigation, goPrevious]);
+
+  const toggleCurrentFlag = useCallback(() => {
+    const uid = currentQuestionUidRef.current;
+    if (uid) handleToggleFlag(uid);
+  }, [handleToggleFlag]);
+
+  const openMaterials = useCallback(() => setMaterialsOpen(true), [setMaterialsOpen]);
+
+  const confirmSubmit = useCallback(() => {
+    setShowConfirm(false);
+    doSubmit(false);
+  }, [doSubmit]);
+
+  const cancelConfirm = useCallback(() => setShowConfirm(false), []);
 
   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>
       {examTitle && (
         <p className="text-xl font-bold mb-2 text-foreground">{examTitle}</p>
       )}
@@ -149,10 +154,10 @@ export function ExamSession({
       <AssessmentToolbar
         currentQuestionIndex={currentIndex}
         totalQuestions={questions.length}
-        hasNext={currentIndex < questions.length - 1}
+        hasNext={hasNext}
         hasPrevious={allowBackNavigation && currentIndex > 0}
-        onNext={() => setCurrentIndex((i) => Math.min(i + 1, questions.length - 1))}
-        onPrevious={() => allowBackNavigation && setCurrentIndex((i) => Math.max(i - 1, 0))}
+        onNext={goNext}
+        onPrevious={handlePrevious}
         onSubmit={handleSubmitClick}
         timeElapsedSeconds={timeElapsedSeconds}
         timeLimitSeconds={timeLimitSeconds}
@@ -169,16 +174,19 @@ export function ExamSession({
         </Card>
       )}
 
+      <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>
@@ -207,13 +215,11 @@ export function ExamSession({
         confirmLabel="Submit Exam"
         cancelLabel="Continue Exam"
         confirmColor="primary"
-        onConfirm={() => {
-          setShowConfirm(false);
-          doSubmit(false);
-        }}
-        onCancel={() => setShowConfirm(false)}
+        onConfirm={confirmSubmit}
+        onCancel={cancelConfirm}
         isLoading={isSubmitting}
       />
     </div>
+    </SectionShell>
   );
 }

package/src/sections/ExamSession/types.ts

@@ -51,6 +51,12 @@ export interface ExamSessionProps {
   questionMaterials?: QuestionMaterial[];
   /** 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 */