@hydralms/components 0.1.3 → 0.3.0

package/src/modules/_shared/assessment-results.tsx

@@ -0,0 +1,133 @@
+import type { ReactNode } from "react";
+import { CheckCircle2, XCircle, Trophy, Clock, RotateCcw } from "lucide-react";
+import { ProgressRing } from "../../progress/progress-ring";
+import { StatCard } from "../../progress/stat-card";
+import { Button } from "../../ui/button";
+import { Badge } from "../../ui/badge";
+import { Card, CardContent } from "../../ui/card";
+import { Separator } from "../../ui/separator";
+import { formatDuration } from "../../utils/format-duration";
+import { AssessmentReview } from "../../sections/AssessmentReview/AssessmentReview";
+import type { QuestionData, SessionAnswer } from "../../questions/types";
+
+export interface AssessmentResultsProps {
+  title: string;
+  percentage: number;
+  passed: boolean;
+  correct: number;
+  total: number;
+  timeElapsedSeconds: number;
+  answers: SessionAnswer[];
+  questions: QuestionData[];
+  /** Allow retaking the assessment. */
+  allowRetake?: boolean;
+  onRetake?: () => void;
+  retakeLabel?: string;
+  /** Show per-question review below the summary. */
+  showReview?: boolean;
+  /** Extra badges shown next to the pass/fail badge (e.g., "Auto-submitted"). */
+  extraBadges?: ReactNode;
+  /** When true, disables interactions for preview/demo mode. @default false */
+  readOnly?: boolean;
+}
+
+export function AssessmentResults({
+  title,
+  percentage,
+  passed,
+  correct,
+  total,
+  timeElapsedSeconds,
+  answers,
+  questions,
+  allowRetake,
+  onRetake,
+  retakeLabel = "Retake",
+  showReview = true,
+  extraBadges,
+  readOnly = false,
+}: AssessmentResultsProps) {
+  return (
+    <>
+      <Card>
+        <CardContent className="pt-8 pb-8">
+          {/* Score summary */}
+          <div className="text-center mb-8">
+            <ProgressRing
+              value={percentage}
+              size={140}
+              strokeWidth={10}
+              color={passed ? "var(--success)" : "var(--destructive)"}
+              className="mx-auto mb-4 text-foreground"
+            />
+            <Badge
+              variant={passed ? "success" : "destructive"}
+              className="text-sm px-3 py-1 mb-2"
+            >
+              {passed ? "Passed" : "Failed"}
+            </Badge>
+            {extraBadges}
+            <h2 className="text-xl font-bold text-foreground">{title}</h2>
+          </div>
+
+          {/* Stats grid */}
+          <div className="grid grid-cols-2 sm:grid-cols-4 gap-3 mb-8">
+            <StatCard
+              icon={<CheckCircle2 />}
+              label="Correct"
+              description="Questions answered right"
+              value={`${correct}/${total}`}
+              accent="var(--success)"
+            />
+            <StatCard
+              icon={<XCircle />}
+              label="Incorrect"
+              description="Questions to review"
+              value={`${total - correct}/${total}`}
+              accent="var(--destructive)"
+            />
+            <StatCard
+              icon={<Trophy />}
+              label="Score"
+              description="Overall percentage"
+              value={`${percentage}%`}
+              accent="var(--palette-3)"
+            />
+            <StatCard
+              icon={<Clock />}
+              label="Time"
+              description="Total elapsed"
+              value={formatDuration(timeElapsedSeconds)}
+              accent="var(--palette-1)"
+            />
+          </div>
+
+          {/* Actions */}
+          {allowRetake && onRetake && !readOnly && (
+            <div className="flex justify-center mb-8">
+              <Button variant="outline" onClick={onRetake}>
+                <RotateCcw className="size-4 mr-2" />
+                {retakeLabel}
+              </Button>
+            </div>
+          )}
+        </CardContent>
+      </Card>
+
+      {/* Per-question review */}
+      {showReview && (
+        <>
+          <Separator className="my-6" />
+          <h3 className="text-lg font-semibold text-foreground mb-4">
+            Question Review
+          </h3>
+          <AssessmentReview
+            questions={questions}
+            sessionAnswers={answers}
+            showCorrectAnswers
+          />
+        </>
+      )}
+    </>
+  );
+}

package/src/modules/_shared/types.ts

@@ -0,0 +1,11 @@
+import type { SessionAnswer } from "../../questions/types";
+
+/** Shared result shape for scored assessment modules. */
+export interface AssessmentResult {
+  answers: SessionAnswer[];
+  correct: number;
+  total: number;
+  percentage: number;
+  passed: boolean;
+  timeElapsedSeconds: number;
+}

package/src/modules/_shared/use-timer.ts

@@ -0,0 +1,49 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+
+/**
+ * Manages an interval-based timer that runs while `active` is true.
+ * Returns elapsed seconds and a reset function.
+ */
+export function useTimer(active: boolean) {
+  const [timeElapsed, setTimeElapsed] = useState(0);
+  const startTimeRef = useRef<number | null>(null);
+  const intervalRef = useRef<ReturnType<typeof setInterval> | null>(null);
+  const timeElapsedRef = useRef(0);
+
+  useEffect(() => {
+    if (active) {
+      startTimeRef.current = Date.now();
+      intervalRef.current = setInterval(() => {
+        if (startTimeRef.current) {
+          const next = Math.floor((Date.now() - startTimeRef.current) / 1000);
+          if (next !== timeElapsedRef.current) {
+            timeElapsedRef.current = next;
+            setTimeElapsed(next);
+          }
+        }
+      }, 1000);
+    } else {
+      if (intervalRef.current) {
+        clearInterval(intervalRef.current);
+        intervalRef.current = null;
+      }
+    }
+    return () => {
+      if (intervalRef.current) clearInterval(intervalRef.current);
+    };
+  }, [active]);
+
+  const getFinalElapsed = useCallback(() => {
+    return startTimeRef.current
+      ? Math.floor((Date.now() - startTimeRef.current) / 1000)
+      : timeElapsedRef.current;
+  }, []);
+
+  const reset = useCallback(() => {
+    timeElapsedRef.current = 0;
+    setTimeElapsed(0);
+    startTimeRef.current = null;
+  }, []);
+
+  return { timeElapsed, getFinalElapsed, reset };
+}

package/src/modules/index.ts

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

package/src/progress/achievement-badge.tsx

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

package/src/progress/activity-timeline.tsx

@@ -0,0 +1,84 @@
+import { BookOpen, CheckCircle, Send, Award, Circle } from "lucide-react";
+import { Button } from "../ui/button";
+import { formatTimestamp } from "../utils/format-timestamp";
+import { cn } from "../lib/utils";
+import type { ActivityTimelineProps } from "./types";
+
+const DEFAULT_ICONS: Record<string, React.ElementType> = {
+  lesson_completed: BookOpen,
+  quiz_passed: CheckCircle,
+  assignment_submitted: Send,
+  badge_earned: Award,
+};
+
+/**
+ * ActivityTimeline renders a vertical timeline of activity events
+ * with icons, timestamps, and an optional "load more" action.
+ */
+export function ActivityTimeline({
+  events,
+  limit,
+  showLoadMore = false,
+  onLoadMore,
+  emptyMessage = "No recent activity",
+  className,
+  style,
+}: ActivityTimelineProps) {
+  const displayedEvents = limit ? events.slice(0, limit) : events;
+
+  if (events.length === 0) {
+    return (
+      <p className={cn("text-sm text-muted-foreground", className)} style={style}>
+        {emptyMessage}
+      </p>
+    );
+  }
+
+  return (
+    <div className={cn("relative", className)} style={style}>
+      {/* Vertical line */}
+      <div className="absolute left-3.5 top-0 bottom-0 w-px bg-border" />
+
+      {displayedEvents.map((event) => {
+        const Icon = DEFAULT_ICONS[event.type] ?? Circle;
+
+        return (
+          <div
+            key={event.uid}
+            className="relative flex gap-3 pb-4 last:pb-0"
+          >
+            {/* Dot / Icon */}
+            <div className="relative z-10 shrink-0 w-7 h-7 rounded-full bg-background border border-border flex items-center justify-center">
+              {event.icon ?? (
+                <Icon size={14} className="text-muted-foreground" />
+              )}
+            </div>
+
+            {/* Content */}
+            <div className="flex-1 min-w-0 pt-0.5">
+              <p className="text-sm font-medium text-foreground">
+                {event.title}
+              </p>
+              {event.description && (
+                <p className="text-xs text-muted-foreground mt-0.5">
+                  {event.description}
+                </p>
+              )}
+              <span className="text-xs text-muted-foreground">
+                {formatTimestamp(event.timestamp)}
+              </span>
+            </div>
+          </div>
+        );
+      })}
+
+      {showLoadMore && onLoadMore && (
+        <div className="pl-10 pt-1">
+          <Button variant="ghost" size="sm" onClick={onLoadMore}>
+            Load more
+          </Button>
+        </div>
+      )}
+    </div>
+  );
+}

package/src/progress/grade-indicator.tsx

@@ -36,7 +36,15 @@ export function GradeIndicator({
   if (variant === "linear") {
     return (
       <div className={cn("flex flex-row items-center gap-1", className)} style={style}>
-        <div className="flex-1 bg-muted rounded-full overflow-hidden" style={{ height: TRACK_HEIGHTS[size] }}>
+        <div
+          className="flex-1 bg-muted rounded-full overflow-hidden"
+          style={{ height: TRACK_HEIGHTS[size] }}
+          role="progressbar"
+          aria-valuenow={Math.round(percentage)}
+          aria-valuemin={0}
+          aria-valuemax={100}
+          aria-label={`Grade: ${letterGrade ?? `${Math.round(percentage)}%`}`}
+        >
           <div
             className="h-full rounded-full transition-[width] duration-300 ease-in-out"
             style={{ width: `${percentage}%`, background: color }}

package/src/progress/index.ts

@@ -1,8 +1,15 @@
 export { ProgressRing } from "./progress-ring";
 export { GradeIndicator } from "./grade-indicator";
 export { StatCard } from "./stat-card";
+export { AchievementBadge } from "./achievement-badge";
+export { StreakBadge } from "./streak-badge";
+export { ActivityTimeline } from "./activity-timeline";
 export type {
   ProgressRingProps,
   GradeIndicatorProps,
   StatCardProps,
+  AchievementBadgeProps,
+  StreakBadgeProps,
+  ActivityTimelineProps,
+  TimelineEvent,
 } from "./types";

package/src/progress/progress-ring.tsx

@@ -21,7 +21,7 @@ export function ProgressRing({
       className={cn("relative inline-flex", className)}
       style={{ width: `${size}px`, height: `${size}px`, ...style }}
     >
-      <svg width={size} height={size}>
+      <svg width={size} height={size} role="img" aria-label={label ?? `${Math.round(value)}% progress`}>
         <circle
           cx={center}
           cy={center}
@@ -48,6 +48,7 @@ export function ProgressRing({
       <span
         className="absolute inset-0 flex items-center justify-center font-bold text-foreground"
         style={{ fontSize: `${size * 0.2}px` }}
+        aria-hidden="true"
       >
         {label ?? `${Math.round(value)}%`}
       </span>

package/src/progress/stat-card.tsx

@@ -1,4 +1,6 @@
+import { memo } from "react";
 import { TrendingUp, TrendingDown, Minus } from "lucide-react";
+import { Card, CardContent } from "../ui/card";
 import type { StatCardProps } from "./types";
 import { cn } from "../lib/utils";
 
@@ -9,34 +11,51 @@ const TREND_COLORS = {
 };
 const TREND_ICONS = { up: TrendingUp, down: TrendingDown, flat: Minus };
 
-export function StatCard({
+export const StatCard = memo(function StatCard({
   icon,
   label,
+  description,
   value,
   subtitle,
   trend,
+  accent,
   className,
   style,
 }: StatCardProps) {
   const TrendIcon = trend ? TREND_ICONS[trend.direction] : null;
 
   return (
-    <div className={cn("rounded-md border border-border p-4", className)} style={style}>
-      {icon && <div className="mb-1 text-primary [&>svg]:size-6">{icon}</div>}
-      <span className="text-xs text-muted-foreground">{label}</span>
-      <div className="flex flex-row items-baseline gap-1">
-        <span className="text-2xl font-bold">{value}</span>
-        {trend && TrendIcon && (
-          <span className="flex flex-row items-center gap-px" style={{ color: TREND_COLORS[trend.direction] }}>
-            <TrendIcon size={14} />
-            <span className="text-xs font-semibold">
-              {trend.value > 0 ? "+" : ""}
-              {trend.value}%
-            </span>
-          </span>
+    <Card className={cn(className)} style={style}>
+      <CardContent className="p-4">
+        {icon && (
+          <div
+            className="mb-2 w-9 h-9 rounded-lg flex items-center justify-center [&>svg]:size-5"
+            style={{
+              backgroundColor: `color-mix(in oklch, ${accent ?? "var(--primary)"} 10%, transparent)`,
+              color: accent ?? "var(--primary)",
+            }}
+          >
+            {icon}
+          </div>
+        )}
+        <span className="text-sm font-medium text-foreground">{label}</span>
+        {description && (
+          <p className="text-xs text-muted-foreground mt-0.5 leading-snug">{description}</p>
         )}
-      </div>
-      {subtitle && <span className="text-xs text-muted-foreground">{subtitle}</span>}
-    </div>
+        <div className="flex flex-row items-baseline gap-1.5 mt-1">
+          <span className="text-3xl font-bold tracking-tight">{value}</span>
+          {trend && TrendIcon && (
+            <span className="flex flex-row items-center gap-px" style={{ color: TREND_COLORS[trend.direction] }}>
+              <TrendIcon size={14} />
+              <span className="text-xs font-semibold">
+                {trend.value > 0 ? "+" : ""}
+                {trend.value}%
+              </span>
+            </span>
+          )}
+        </div>
+        {subtitle && <span className="text-xs text-muted-foreground">{subtitle}</span>}
+      </CardContent>
+    </Card>
   );
-}
+});

package/src/progress/streak-badge.tsx

@@ -0,0 +1,35 @@
+import { Flame } from "lucide-react";
+import { cn } from "../lib/utils";
+import type { StreakBadgeProps } from "./types";
+
+/**
+ * StreakBadge displays a compact learning streak indicator with
+ * a fire icon and day count.
+ */
+export function StreakBadge({
+  currentStreak,
+  longestStreak,
+  unit = "days",
+  showLongest = false,
+  className,
+  style,
+}: StreakBadgeProps) {
+  return (
+    <div
+      className={cn("flex items-center gap-2", className)}
+      style={style}
+    >
+      <Flame size={20} className="text-warning shrink-0" />
+      <div>
+        <span className="text-sm font-bold text-foreground">
+          {currentStreak} {unit}
+        </span>
+        {showLongest && longestStreak != null && (
+          <span className="block text-xs text-muted-foreground">
+            Longest: {longestStreak} {unit}
+          </span>
+        )}
+      </div>
+    </div>
+  );
+}

package/src/progress/types.ts

@@ -60,12 +60,115 @@ export interface StatCardProps {
   icon?: ReactNode;
   /** Stat label */
   label: string;
+  /** Short description displayed below the label */
+  description?: string;
   /** Stat value */
   value: string | number;
   /** Secondary text below the value */
   subtitle?: string;
   /** Optional trend data */
   trend?: { value: number; direction: "up" | "down" | "flat" };
+  /** Accent color CSS value for the icon background. Defaults to primary. */
+  accent?: string;
+  /** CSS class name for the root element */
+  className?: string;
+  /** Inline styles for the root element */
+  style?: React.CSSProperties;
+}
+
+/**
+ * AchievementBadge displays a single achievement or badge earned by a learner,
+ * with support for locked/earned states and metal-tier variants.
+ *
+ * @example
+ * <AchievementBadge
+ *   title="Quiz Master"
+ *   description="Pass 10 quizzes with 90%+ score"
+ *   variant="gold"
+ *   earnedDate="2025-12-01T00:00:00Z"
+ * />
+ */
+export interface AchievementBadgeProps {
+  /** Achievement title */
+  title: string;
+  /** Optional description of how to earn the achievement */
+  description?: string;
+  /** Custom icon to display. Falls back to Trophy icon */
+  icon?: ReactNode;
+  /** ISO date string of when the achievement was earned */
+  earnedDate?: string;
+  /** Whether the achievement is locked (not yet earned). @default false */
+  locked?: boolean;
+  /** Visual tier variant. @default 'default' */
+  variant?: "default" | "gold" | "silver" | "bronze";
+  /** CSS class name for the root element */
+  className?: string;
+  /** Inline styles for the root element */
+  style?: React.CSSProperties;
+}
+
+/**
+ * StreakBadge displays a compact learning streak indicator with
+ * a fire icon and day count.
+ *
+ * @example
+ * <StreakBadge currentStreak={7} longestStreak={14} showLongest />
+ */
+export interface StreakBadgeProps {
+  /** Current active streak count */
+  currentStreak: number;
+  /** All-time longest streak count */
+  longestStreak?: number;
+  /** Unit label for the streak count. @default "days" */
+  unit?: string;
+  /** Whether to show the longest streak subtitle. @default false */
+  showLongest?: boolean;
+  /** CSS class name for the root element */
+  className?: string;
+  /** Inline styles for the root element */
+  style?: React.CSSProperties;
+}
+
+/**
+ * A single event in an ActivityTimeline.
+ */
+export interface TimelineEvent {
+  /** Unique identifier */
+  uid: string;
+  /** Event type — used for default icon selection */
+  type: string;
+  /** Event title */
+  title: string;
+  /** Optional longer description */
+  description?: string;
+  /** ISO 8601 timestamp */
+  timestamp: string;
+  /** Optional custom icon (overrides type-based default) */
+  icon?: ReactNode;
+}
+
+/**
+ * ActivityTimeline renders a vertical timeline of activity events
+ * with icons, timestamps, and an optional "load more" action.
+ *
+ * @example
+ * <ActivityTimeline
+ *   events={[
+ *     { uid: "1", type: "lesson_completed", title: "Completed Lesson 3", timestamp: "2025-03-01T12:00:00Z" },
+ *   ]}
+ * />
+ */
+export interface ActivityTimelineProps {
+  /** List of activity events to display */
+  events: TimelineEvent[];
+  /** Maximum number of events to display. When set, truncates the list. */
+  limit?: number;
+  /** Whether to show a "Load more" button at the bottom. @default false */
+  showLoadMore?: boolean;
+  /** Called when the user clicks "Load more" */
+  onLoadMore?: () => void;
+  /** Message displayed when the events list is empty. @default "No recent activity" */
+  emptyMessage?: string;
   /** CSS class name for the root element */
   className?: string;
   /** Inline styles for the root element */