@hydralms/components 0.1.2 → 0.2.0

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/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/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,9 +11,10 @@ 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,
@@ -21,22 +24,31 @@ export function StatCard({
   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 bg-primary/10 flex items-center justify-center text-primary [&>svg]:size-5">
+            {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,6 +60,8 @@ 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 */
@@ -71,3 +73,102 @@ export interface StatCardProps {
   /** 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 */
+  style?: React.CSSProperties;
+}

package/src/questions/choice.tsx

@@ -1,4 +1,4 @@
-import { useState, useEffect } from "react";
+import { useState, useMemo } from "react";
 import type { QuestionProps } from "./types";
 import { Alert, AlertDescription } from "../ui/alert";
 import { cn } from "../lib/utils";
@@ -20,10 +20,13 @@ export const Choice = ({
   showCorrectAnswers = false,
   disabled = false,
 }: QuestionProps) => {
-  const [selectedAnswer, setSelectedAnswer] = useState<string>("");
+  const [selectedAnswer, setSelectedAnswer] = useState<string>(
+    () => sessionAnswers?.[0]?.answerUid || "",
+  );
 
-  const sortedAnswers = [...(question.answers || [])].sort(
-    (a, b) => a.sequence - b.sequence,
+  const sortedAnswers = useMemo(
+    () => [...(question.answers || [])].sort((a, b) => a.sequence - b.sequence),
+    [question.answers],
   );
 
   const handleChange = (uid: string) => {
@@ -33,11 +36,6 @@ export const Choice = ({
     onAnswer?.([{ uid }]);
   };
 
-  useEffect(() => {
-    const current = sessionAnswers?.[0]?.answerUid || "";
-    setSelectedAnswer(current);
-  }, [sessionAnswers]);
-
   const getAnswerClasses = (answerUid: string) => {
     if (!showCorrectAnswers) return "px-2";
 

package/src/questions/essay.tsx

@@ -1,10 +1,10 @@
-import { useState, useEffect, useCallback } from "react";
+import { useState, useMemo, useRef } from "react";
 import { debounce } from "../utils/debounce";
-import { Textarea } from "../ui/textarea";
+import { RichTextEditor } from "../ui/rich-text-editor";
 import type { QuestionProps } from "./types";
 
 /**
- * Essay renders a long-form text input question with a multiline textarea.
+ * Essay renders a long-form rich text input question.
  *
  * @example
  * <Essay
@@ -19,40 +19,38 @@ export const Essay = ({
   readOnly = false,
   disabled = false,
 }: QuestionProps) => {
-  const [value, setValue] = useState("");
+  const [value, setValue] = useState(() => sessionAnswers?.[0]?.content || "");
 
-  const debouncedAnswer = useCallback(
-    debounce((content: string) => {
-      onAnswer?.([
-        {
-          uid: question.answers?.[0]?.uid || question.uid,
-          content,
-        },
-      ]);
-    }, 500),
-    [onAnswer, question.answers, question.uid],
+  const onAnswerRef = useRef(onAnswer);
+  onAnswerRef.current = onAnswer;
+  const answerUidRef = useRef(question.answers?.[0]?.uid || question.uid);
+  answerUidRef.current = question.answers?.[0]?.uid || question.uid;
+
+  const debouncedAnswer = useMemo(
+    () =>
+      debounce((content: string) => {
+        onAnswerRef.current?.([{ uid: answerUidRef.current, content }]);
+      }, 500),
+    [],
   );
 
-  const handleChange = (e: React.ChangeEvent<HTMLTextAreaElement>) => {
-    const newValue = e.target.value;
-    setValue(newValue);
-    debouncedAnswer(newValue);
+  const handleChange = (html: string) => {
+    setValue(html);
+    debouncedAnswer(html);
   };
 
-  useEffect(() => {
-    setValue(sessionAnswers?.[0]?.content || "");
-  }, [sessionAnswers]);
-
   return (
     <div className="flex flex-col gap-2">
       <div dangerouslySetInnerHTML={{ __html: question.content }} />
 
-      <Textarea
-        className="min-h-30 resize-y"
+      <RichTextEditor
+        className="min-h-30"
         value={value}
         onChange={handleChange}
         placeholder="Write your response here..."
-        disabled={readOnly || disabled}
+        readOnly={readOnly}
+        disabled={disabled}
+        variant="default"
       />
     </div>
   );

package/src/questions/fill-in-the-blank.tsx

@@ -1,4 +1,4 @@
-import { useState, useEffect, useCallback } from "react";
+import { useState, useMemo, useRef } from "react";
 import { debounce } from "../utils/debounce";
 import { Input } from "../ui/input";
 import { Alert, AlertDescription } from "../ui/alert";
@@ -21,18 +21,19 @@ export const FillInTheBlank = ({
   showCorrectAnswers = false,
   disabled = false,
 }: QuestionProps) => {
-  const [value, setValue] = useState("");
+  const [value, setValue] = useState(() => sessionAnswers?.[0]?.content || "");
 
-  const debouncedAnswer = useCallback(
-    debounce((content: string) => {
-      onAnswer?.([
-        {
-          uid: question.answers?.[0]?.uid || "",
-          content,
-        },
-      ]);
-    }, 300),
-    [onAnswer, question.answers],
+  const onAnswerRef = useRef(onAnswer);
+  onAnswerRef.current = onAnswer;
+  const answerUidRef = useRef(question.answers?.[0]?.uid || "");
+  answerUidRef.current = question.answers?.[0]?.uid || "";
+
+  const debouncedAnswer = useMemo(
+    () =>
+      debounce((content: string) => {
+        onAnswerRef.current?.([{ uid: answerUidRef.current, content }]);
+      }, 300),
+    [],
   );
 
   const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
@@ -41,10 +42,6 @@ export const FillInTheBlank = ({
     debouncedAnswer(newValue);
   };
 
-  useEffect(() => {
-    setValue(sessionAnswers?.[0]?.content || "");
-  }, [sessionAnswers]);
-
   return (
     <div className="flex flex-col gap-2">
       <div dangerouslySetInnerHTML={{ __html: question.content }} />

package/src/questions/hotspot.tsx

@@ -0,0 +1,154 @@
+import { useState, useMemo } from "react";
+import { Alert, AlertDescription } from "../ui/alert";
+import { cn } from "../lib/utils";
+import type { QuestionProps, HotspotRegion } from "./types";
+
+function getRegionStyle(region: HotspotRegion): React.CSSProperties {
+  if (region.shape === "rect") {
+    const [x, y, w, h] = region.coords;
+    return {
+      left: `${x}%`,
+      top: `${y}%`,
+      width: `${w}%`,
+      height: `${h}%`,
+    };
+  }
+  // circle: [cx, cy, r]
+  const [cx, cy, r] = region.coords;
+  return {
+    left: `${cx - r}%`,
+    top: `${cy - r}%`,
+    width: `${r * 2}%`,
+    height: `${r * 2}%`,
+    borderRadius: "50%",
+  };
+}
+
+/**
+ * Hotspot renders an image with clickable regions for selection.
+ *
+ * Regions are positioned using percentage-based coordinates so they scale with the image.
+ *
+ * @example
+ * <Hotspot
+ *   question={{
+ *     uid: "q1",
+ *     type: "hotspot",
+ *     content: "Click on the heart.",
+ *     hotspotImageUrl: "/anatomy.png",
+ *     hotspotRegions: [
+ *       { uid: "r1", shape: "circle", coords: [50, 40, 8], isCorrect: true, label: "Heart" },
+ *     ],
+ *   }}
+ *   onAnswer={(answers) => handleAnswer(answers)}
+ * />
+ */
+export const Hotspot = ({
+  question,
+  sessionAnswers,
+  onAnswer,
+  readOnly = false,
+  showCorrectAnswers = false,
+  disabled = false,
+}: QuestionProps) => {
+  const multiSelect = question.hotspotMultiSelect ?? false;
+
+  const [selected, setSelected] = useState<Set<string>>(() => {
+    const set = new Set<string>();
+    for (const sa of sessionAnswers ?? []) {
+      set.add(sa.answerUid);
+    }
+    return set;
+  });
+
+  const regions = useMemo(
+    () => question.hotspotRegions ?? [],
+    [question.hotspotRegions],
+  );
+
+  const handleClick = (regionUid: string) => {
+    if (readOnly || disabled) return;
+
+    let next: Set<string>;
+    if (multiSelect) {
+      next = new Set(selected);
+      if (next.has(regionUid)) {
+        next.delete(regionUid);
+      } else {
+        next.add(regionUid);
+      }
+    } else {
+      next = selected.has(regionUid) ? new Set() : new Set([regionUid]);
+    }
+
+    setSelected(next);
+    onAnswer?.([...next].map((uid) => ({ uid })));
+  };
+
+  const getRegionClasses = (region: HotspotRegion) => {
+    const isSelected = selected.has(region.uid);
+
+    if (showCorrectAnswers) {
+      if (region.isCorrect && isSelected) {
+        return "ring-3 ring-success bg-success/20 border-2 border-success";
+      }
+      if (region.isCorrect && !isSelected) {
+        return "ring-2 ring-success/50 border-2 border-dashed border-success/50";
+      }
+      if (!region.isCorrect && isSelected) {
+        return "ring-3 ring-destructive bg-destructive/20 border-2 border-destructive";
+      }
+      return "";
+    }
+
+    if (isSelected) {
+      return "ring-3 ring-primary bg-primary/20 border-2 border-primary";
+    }
+
+    return "hover:bg-primary/10";
+  };
+
+  return (
+    <div className="flex flex-col gap-4">
+      <div dangerouslySetInnerHTML={{ __html: question.content }} />
+
+      <div className="relative inline-block max-w-full">
+        {question.hotspotImageUrl && (
+          <img
+            src={question.hotspotImageUrl}
+            alt="Hotspot question image"
+            className="w-full h-auto rounded-md"
+            draggable={false}
+          />
+        )}
+
+        {regions.map((region, i) => (
+          <button
+            key={region.uid}
+            type="button"
+            onClick={() => handleClick(region.uid)}
+            disabled={readOnly || disabled}
+            aria-label={region.label || `Region ${i + 1}`}
+            aria-pressed={selected.has(region.uid)}
+            className={cn(
+              "absolute transition-all cursor-pointer",
+              "disabled:cursor-default",
+              "focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary",
+              getRegionClasses(region),
+            )}
+            style={getRegionStyle(region)}
+          />
+        ))}
+      </div>
+
+      {showCorrectAnswers && question.explanation && (
+        <Alert className="mt-2">
+          <AlertDescription>
+            <strong>Explanation:</strong>{" "}
+            <span dangerouslySetInnerHTML={{ __html: question.explanation }} />
+          </AlertDescription>
+        </Alert>
+      )}
+    </div>
+  );
+};

package/src/questions/index.ts

@@ -4,11 +4,27 @@ export { Choice } from "./choice";
 export { TrueFalse } from "./true-false";
 export { FillInTheBlank } from "./fill-in-the-blank";
 export { Essay } from "./essay";
+export { Numeric } from "./numeric";
+export { Ordering } from "./ordering";
+export { Matching } from "./matching";
+export { Hotspot } from "./hotspot";
+export { InlineChoice } from "./inline-choice";
+export { Scenario } from "./scenario";
+export { Spreadsheet } from "./spreadsheet";
+export { scoreQuestion, scoreScenarioSubQuestions } from "./scoring";
 
 export type {
   QuestionProps,
   QuestionData,
   QuestionTypeEnum,
+  QuestionMaterial,
   AnswerOption,
   SessionAnswer,
+  MatchingPair,
+  HotspotRegion,
+  InlineBlank,
+  ScenarioScoringMode,
+  SpreadsheetColumn,
+  SpreadsheetCell,
+  SpreadsheetRow,
 } from "./types";