@hydralms/components 0.1.1 → 0.1.2

package/src/sections/PracticeQuiz/PracticeQuiz.tsx

@@ -0,0 +1,199 @@
+import { useMemo, useState } from "react";
+import { CheckCircle } from "lucide-react";
+import { QuestionRenderer } from "../../questions";
+import { FeedbackBanner } from "../../feedback";
+import { Button } from "../../ui/button";
+import { Card, CardContent } from "../../ui/card";
+import { Progress } from "../../ui/progress";
+import type { PracticeQuizProps, PracticeQuizStats } from "./types";
+
+function shuffleArray<T>(arr: T[]): T[] {
+  const copy = [...arr];
+  for (let i = copy.length - 1; i > 0; i--) {
+    const j = Math.floor(Math.random() * (i + 1));
+    [copy[i], copy[j]] = [copy[j], copy[i]];
+  }
+  return copy;
+}
+
+export function PracticeQuiz({
+  questions: questionsProp,
+  instantFeedback = true,
+  allowRetry = true,
+  onComplete,
+  shuffled = false,
+  readOnly = false,
+  className,
+  style,
+}: PracticeQuizProps) {
+  const questions = useMemo(
+    () => (shuffled ? shuffleArray(questionsProp) : questionsProp),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [questionsProp, shuffled],
+  );
+
+  const [currentIndex, setCurrentIndex] = useState(0);
+  const [revealedUids, setRevealedUids] = useState<Set<string>>(new Set());
+  const [attemptCounts, setAttemptCounts] = useState<Map<string, number>>(new Map());
+  const [firstAttemptCorrect, setFirstAttemptCorrect] = useState<Set<string>>(new Set());
+  const [currentAnswer, setCurrentAnswer] = useState<{ uid: string; content?: string }[] | null>(null);
+  const [isComplete, setIsComplete] = useState(false);
+
+  const currentQuestion = questions[currentIndex];
+  const isRevealed = currentQuestion ? revealedUids.has(currentQuestion.uid) : false;
+
+  function checkAnswer() {
+    if (!currentQuestion || !currentAnswer) return;
+
+    const attempts = (attemptCounts.get(currentQuestion.uid) ?? 0) + 1;
+    setAttemptCounts((prev) => new Map(prev).set(currentQuestion.uid, attempts));
+    setRevealedUids((prev) => new Set(prev).add(currentQuestion.uid));
+
+    const correctUids = new Set(
+      currentQuestion.answers?.filter((a) => a.isCorrect).map((a) => a.uid) ?? [],
+    );
+    const selectedUids = new Set(currentAnswer.map((a) => a.uid));
+    const isCorrect =
+      correctUids.size === selectedUids.size &&
+      [...correctUids].every((uid) => selectedUids.has(uid));
+
+    if (isCorrect && attempts === 1) {
+      setFirstAttemptCorrect((prev) => new Set(prev).add(currentQuestion.uid));
+    }
+  }
+
+  function handleRetry() {
+    if (!currentQuestion) return;
+    setRevealedUids((prev) => {
+      const next = new Set(prev);
+      next.delete(currentQuestion.uid);
+      return next;
+    });
+    setCurrentAnswer(null);
+  }
+
+  function handleNext() {
+    if (currentIndex < questions.length - 1) {
+      setCurrentIndex((i) => i + 1);
+      setCurrentAnswer(null);
+    } else {
+      const stats: PracticeQuizStats = {
+        totalQuestions: questions.length,
+        correctOnFirstAttempt: firstAttemptCorrect.size,
+        totalAttempts: Array.from(attemptCounts.values()).reduce((a, b) => a + b, 0),
+      };
+      setIsComplete(true);
+      onComplete?.(stats);
+    }
+  }
+
+  const isCurrentCorrect = useMemo(() => {
+    if (!currentQuestion || !currentAnswer) return false;
+    const correctUids = new Set(
+      currentQuestion.answers?.filter((a) => a.isCorrect).map((a) => a.uid) ?? [],
+    );
+    const selectedUids = new Set(currentAnswer.map((a) => a.uid));
+    return (
+      correctUids.size === selectedUids.size &&
+      [...correctUids].every((uid) => selectedUids.has(uid))
+    );
+  }, [currentQuestion, currentAnswer]);
+
+  if (isComplete) {
+    const percentage = questions.length > 0
+      ? Math.round((firstAttemptCorrect.size / questions.length) * 100)
+      : 0;
+    return (
+      <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}%)
+          </p>
+          <div className="flex justify-center">
+            <Button
+              variant="outline"
+              onClick={() => {
+                setCurrentIndex(0);
+                setRevealedUids(new Set());
+                setAttemptCounts(new Map());
+                setFirstAttemptCorrect(new Set());
+                setCurrentAnswer(null);
+                setIsComplete(false);
+              }}
+            >
+              Practice Again
+            </Button>
+          </div>
+        </CardContent>
+      </Card>
+    );
+  }
+
+  return (
+    <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"
+      />
+
+      {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}
+              />
+            )}
+
+            <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>
+  );
+}

package/src/sections/PracticeQuiz/types.ts

@@ -0,0 +1,44 @@
+import type { QuestionData } from "../../questions/types";
+
+/**
+ * PracticeQuiz section — a low-stakes practice quiz with instant feedback.
+ *
+ * After each answer the correct answer is revealed with an explanation.
+ * Users can retry incorrect questions. A completion screen shows stats
+ * when all questions have been attempted.
+ *
+ * @example
+ * <PracticeQuiz
+ *   questions={questions}
+ *   onComplete={(stats) => trackPractice(stats)}
+ *   instantFeedback
+ *   allowRetry
+ * />
+ */
+export interface PracticeQuizProps {
+  /** Ordered list of questions to practice */
+  questions: QuestionData[];
+  /** Whether to reveal the correct answer immediately after answering */
+  instantFeedback?: boolean;
+  /** Whether to allow retrying incorrect answers */
+  allowRetry?: boolean;
+  /** Called when the user completes all questions */
+  onComplete?: (stats: PracticeQuizStats) => void;
+  /** Whether to shuffle the question order */
+  shuffled?: boolean;
+  /** When true, all inputs are disabled */
+  readOnly?: boolean;
+  /** CSS class name for the root element */
+  className?: string;
+  /** Inline styles for the root element */
+  style?: React.CSSProperties;
+}
+
+export interface PracticeQuizStats {
+  /** Total number of questions */
+  totalQuestions: number;
+  /** Questions answered correctly on the first attempt */
+  correctOnFirstAttempt: number;
+  /** Total answer attempts across all questions */
+  totalAttempts: number;
+}

package/src/sections/ProgressDashboard/ProgressDashboard.tsx

@@ -0,0 +1,140 @@
+import {
+  Award,
+  BookOpen,
+  CheckCircle,
+  Clock,
+  Flame,
+  Send,
+  Trophy,
+} from "lucide-react";
+import { ProgressRing, StatCard } from "../../progress";
+import { Progress } from "../../ui/progress";
+import { Card } from "../../ui/card";
+import { formatDuration } from "../../utils/format-duration";
+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,
+  modules,
+  recentActivity,
+  streak,
+  achievements,
+  recentActivityLimit = 5,
+  onModuleClick,
+  className,
+  style,
+}: ProgressDashboardProps) {
+  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} />
+        </Card>
+        <StatCard
+          icon={<Clock size={24} />}
+          label="Time Spent"
+          value={formatDuration(totalTimeSpent)}
+        />
+        {streak && (
+          <StatCard
+            icon={<Flame size={24} />}
+            label="Current Streak"
+            value={`${streak.currentDays} days`}
+            subtitle={`Longest: ${streak.longestDays} days`}
+          />
+        )}
+        <StatCard
+          icon={<BookOpen size={24} />}
+          label="Modules"
+          value={`${modules.filter((m) => m.completedItems === m.totalItems).length} / ${modules.length}`}
+          subtitle="completed"
+        />
+      </div>
+
+      {/* Module progress */}
+      <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) => {
+          const pct = mod.totalItems > 0 ? (mod.completedItems / mod.totalItems) * 100 : 0;
+          return (
+            <Card
+              key={mod.uid}
+              className={cn(
+                "p-2 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" />
+            </Card>
+          );
+        })}
+      </div>
+
+      {/* Recent activity */}
+      {recentActivity && recentActivity.length > 0 && (
+        <>
+          <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>
+        </>
+      )}
+
+      {/* Achievements */}
+      {achievements && achievements.length > 0 && (
+        <>
+          <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>
+            ))}
+          </div>
+        </>
+      )}
+    </div>
+  );
+}

package/src/sections/ProgressDashboard/types.ts

@@ -0,0 +1,74 @@
+
+/**
+ * ProgressDashboard section — a visual course progress overview.
+ *
+ * Shows overall completion, time spent, streak data, per-module progress,
+ * recent activity log, and earned achievements.
+ *
+ * @example
+ * <ProgressDashboard
+ *   overallProgress={72}
+ *   totalTimeSpent={14400}
+ *   modules={modules}
+ *   streak={{ currentDays: 5, longestDays: 12 }}
+ * />
+ */
+export interface ProgressDashboardProps {
+  /** Overall course progress percentage (0-100) */
+  overallProgress: number;
+  /** Total time spent in seconds */
+  totalTimeSpent: number;
+  /** Per-module progress */
+  modules: ModuleProgress[];
+  /** Recent activity items */
+  recentActivity?: ActivityItem[];
+  /** Streak data */
+  streak?: { currentDays: number; longestDays: number };
+  /** Earned achievements/badges */
+  achievements?: Achievement[];
+  /** Number of recent activity items to show */
+  recentActivityLimit?: number;
+  /** Called when the user clicks a module */
+  onModuleClick?: (moduleUid: string) => void;
+  /** CSS class name for the root element */
+  className?: string;
+  /** Inline styles for the root element */
+  style?: React.CSSProperties;
+}
+
+export interface ModuleProgress {
+  /** Unique identifier */
+  uid: string;
+  /** Module name */
+  name: string;
+  /** Completed items count */
+  completedItems: number;
+  /** Total items in the module */
+  totalItems: number;
+  /** Time spent in seconds */
+  timeSpent: number;
+}
+
+export interface ActivityItem {
+  /** Unique identifier */
+  uid: string;
+  /** Activity description */
+  description: string;
+  /** Activity timestamp */
+  timestamp: string;
+  /** Activity type */
+  type: "lesson_completed" | "quiz_passed" | "assignment_submitted" | "badge_earned";
+}
+
+export interface Achievement {
+  /** Unique identifier */
+  uid: string;
+  /** Achievement name */
+  name: string;
+  /** Achievement description */
+  description: string;
+  /** Icon URL */
+  iconUrl?: string;
+  /** Date earned */
+  earnedAt: string;
+}

package/src/sections/QuizSession/QuizSession.tsx

@@ -0,0 +1,113 @@
+import { useMemo, useState } from "react";
+import { AssessmentToolbar } from "../../assessment-toolbar";
+import type { QuestionNavigatorItem } from "../../assessment-toolbar/types";
+import { QuestionRenderer } from "../../questions";
+import type { SessionAnswer } from "../../questions/types";
+import { Card, CardContent } from "../../ui/card";
+import type { QuizSessionProps } from "./types";
+import { cn } from "../../lib/utils";
+
+export function QuizSession({
+  questions,
+  initialAnswers = [],
+  onSubmit,
+  onAnswerChange,
+  timeElapsedSeconds,
+  timeLimitSeconds,
+  isSubmitting = false,
+  readOnly = false,
+  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 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],
+  );
+
+  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 handleSubmit() {
+    onSubmit(sessionAnswers);
+  }
+
+  return (
+    <div className={cn(className)} style={style}>
+      <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))}
+        onSubmit={handleSubmit}
+        timeElapsedSeconds={timeElapsedSeconds}
+        timeLimitSeconds={timeLimitSeconds}
+        questions={navigatorItems}
+        onNavigateToQuestion={handleNavigate}
+        onToggleFlag={handleToggleFlag}
+        currentQuestionUid={currentQuestion?.uid}
+        isSubmitting={isSubmitting}
+        readOnly={readOnly}
+      />
+      {currentQuestion && (
+        <Card className="mt-3">
+          <CardContent className="pt-6">
+            <QuestionRenderer
+              question={currentQuestion}
+              sessionAnswers={sessionAnswers.filter(
+                (a) => a.uid === currentQuestion.uid,
+              )}
+              onAnswer={handleAnswer}
+              readOnly={readOnly}
+            />
+          </CardContent>
+        </Card>
+      )}
+    </div>
+  );
+}

package/src/sections/QuizSession/types.ts

@@ -0,0 +1,47 @@
+import type { QuestionData, SessionAnswer } from "../../questions/types";
+
+/**
+ * QuizSession section — a complete assessment session experience.
+ *
+ * Manages question navigation, per-question answer accumulation, and
+ * flag toggling. Combines AssessmentToolbar with QuestionRenderer.
+ * Pass your questions array and an onSubmit callback — everything
+ * else is handled internally.
+ *
+ * @example
+ * <QuizSession
+ *   questions={questions}
+ *   onSubmit={(answers) => submitAssessment(answers)}
+ *   timeLimitSeconds={1800}
+ * />
+ */
+export interface QuizSessionProps {
+  /** Ordered list of questions to present */
+  questions: QuestionData[];
+  /**
+   * Pre-populated answers — use to resume a session already in progress.
+   */
+  initialAnswers?: SessionAnswer[];
+  /**
+   * Called when the user clicks Submit.
+   * Receives the final accumulated answers array.
+   */
+  onSubmit: (answers: SessionAnswer[]) => void;
+  /**
+   * Called whenever the user changes an answer (useful for auto-save).
+   * Fires with the full answers array after each mutation.
+   */
+  onAnswerChange?: (answers: SessionAnswer[]) => void;
+  /** Elapsed time in seconds — renders the timer in the toolbar when provided */
+  timeElapsedSeconds?: number;
+  /** Time limit in seconds — enables countdown mode in the timer */
+  timeLimitSeconds?: number;
+  /** Whether the submit action is currently in flight */
+  isSubmitting?: boolean;
+  /** When true, all inputs are disabled (e.g. after submission) */
+  readOnly?: boolean;
+  /** CSS class name for the root element */
+  className?: string;
+  /** Inline styles for the root element */
+  style?: React.CSSProperties;
+}