@hydralms/components 0.2.0 → 0.3.1

package/src/questions/scenario.tsx

@@ -1,4 +1,4 @@
-import { useMemo, useRef } from "react";
+import { useMemo, useRef, memo } from "react";
 import { Alert, AlertDescription } from "../ui/alert";
 import { Separator } from "../ui/separator";
 import { cn } from "../lib/utils";
@@ -26,14 +26,14 @@ import type { QuestionProps, SessionAnswer } from "./types";
  *   onAnswer={(answers) => handleAnswer(answers)}
  * />
  */
-export const Scenario = ({
+export const Scenario = memo(function Scenario({
   question,
   sessionAnswers,
   onAnswer,
   readOnly = false,
   showCorrectAnswers = false,
   disabled = false,
-}: QuestionProps) => {
+}: QuestionProps) {
   const subQuestions = question.scenarioQuestions ?? [];
 
   // Track the latest answers from each sub-question in a ref so
@@ -137,4 +137,4 @@ export const Scenario = ({
       )}
     </div>
   );
-};
+});

package/src/questions/spreadsheet.tsx

@@ -1,4 +1,4 @@
-import { useState, useMemo, useRef } from "react";
+import { useState, useMemo, useRef, useEffect, memo } from "react";
 import { debounce } from "../utils/debounce";
 import { Input } from "../ui/input";
 import {
@@ -66,14 +66,14 @@ function getCellStatus(
  *   onAnswer={(answers) => handleAnswer(answers)}
  * />
  */
-export const Spreadsheet = ({
+export const Spreadsheet = memo(function Spreadsheet({
   question,
   sessionAnswers,
   onAnswer,
   readOnly = false,
   showCorrectAnswers = false,
   disabled = false,
-}: QuestionProps) => {
+}: QuestionProps) {
   const columns = question.spreadsheetColumns ?? [];
   const rows = question.spreadsheetRows ?? [];
 
@@ -104,6 +104,7 @@ export const Spreadsheet = ({
       }, 300),
     [],
   );
+  useEffect(() => () => debouncedEmit.cancel(), [debouncedEmit]);
 
   const [values, setValues] = useState<Map<string, string>>(() => {
     const map = new Map<string, string>();
@@ -256,4 +257,4 @@ export const Spreadsheet = ({
       )}
     </div>
   );
-};
+});

package/src/questions/true-false.tsx

@@ -1,4 +1,4 @@
-import { useState, useMemo } from "react";
+import { useState, useMemo, memo } from "react";
 import type { QuestionProps } from "./types";
 import { Alert, AlertDescription } from "../ui/alert";
 import { cn } from "../lib/utils";
@@ -12,14 +12,14 @@ import { cn } from "../lib/utils";
  *   onAnswer={(answers) => handleAnswer(answers)}
  * />
  */
-export const TrueFalse = ({
+export const TrueFalse = memo(function TrueFalse({
   question,
   sessionAnswers,
   onAnswer,
   readOnly = false,
   showCorrectAnswers = false,
   disabled = false,
-}: QuestionProps) => {
+}: QuestionProps) {
   const [selectedAnswer, setSelectedAnswer] = useState<string>(
     () => sessionAnswers?.[0]?.answerUid || "",
   );
@@ -53,7 +53,8 @@ export const TrueFalse = ({
     <div className="flex flex-col gap-4">
       <div dangerouslySetInnerHTML={{ __html: question.content }} />
 
-      <div className="flex flex-col gap-2">
+      <fieldset className="flex flex-col gap-2 border-0 p-0 m-0">
+        <legend className="sr-only">True or False</legend>
         {sortedAnswers.map((answer) => (
           <div
             key={answer.uid}
@@ -70,10 +71,16 @@ export const TrueFalse = ({
                 className="accent-primary m-0 shrink-0"
               />
               <span dangerouslySetInnerHTML={{ __html: answer.content }} />
+              {showCorrectAnswers && answer.isCorrect && (
+                <span className="sr-only">(Correct answer)</span>
+              )}
+              {showCorrectAnswers && selectedAnswer === answer.uid && !answer.isCorrect && (
+                <span className="sr-only">(Your answer — incorrect)</span>
+              )}
             </label>
           </div>
         ))}
-      </div>
+      </fieldset>
 
       {showCorrectAnswers && question.explanation && (
         <Alert className="mt-2">
@@ -85,4 +92,4 @@ export const TrueFalse = ({
       )}
     </div>
   );
-};
+});

package/src/sections/AdaptiveLearningPath/AdaptiveLearningPath.tsx

@@ -0,0 +1,251 @@
+import { useMemo } from "react";
+import {
+  Target,
+  BookOpen,
+  Clock,
+  TrendingUp,
+  Flame,
+} from "lucide-react";
+import { StatCard } from "../../progress/stat-card";
+import { ProgressRing } from "../../progress/progress-ring";
+import { Badge } from "../../ui/badge";
+import { Separator } from "../../ui/separator";
+import { Skeleton } from "../../ui/skeleton";
+import { SectionShell } from "../_shared/section-shell";
+import { withProGate } from "../../license/withProGate";
+import { formatDuration } from "../../utils/format-duration";
+import type { AdaptiveLearningPathProps, PathMilestone } from "./types";
+import { PathNodeCard } from "./path-node-card";
+import { PathConnector } from "./path-connector";
+import { PathMilestoneMarker } from "./path-milestone-marker";
+import { PathSkillBar } from "./path-skill-bar";
+
+const DIFFICULTY_CONFIG = {
+  beginner: { label: "Beginner", variant: "success" as const },
+  intermediate: { label: "Intermediate", variant: "warning" as const },
+  advanced: { label: "Advanced", variant: "destructive" as const },
+};
+
+/**
+ * AdaptiveLearningPath section — a premium visualization of a personalized
+ * learning sequence that adapts based on learner performance.
+ *
+ * Renders a vertical path map with nodes, connectors, milestones, skill bars,
+ * and summary statistics. Each node represents a learning activity with status,
+ * score, and recommended-next indicators.
+ *
+ * @example
+ * <AdaptiveLearningPath
+ *   title="React Mastery Path"
+ *   description="A personalized journey for mastering React"
+ *   nodes={pathNodes}
+ *   progress={pathProgress}
+ *   onNodeClick={(uid) => navigate(`/activity/${uid}`)}
+ *   onNodeStart={(uid) => startActivity(uid)}
+ * />
+ */
+function AdaptiveLearningPathBase({
+  title,
+  description,
+  difficulty,
+  nodes = [],
+  progress,
+  skills,
+  milestones,
+  onNodeClick,
+  onNodeStart,
+  onSkillClick,
+  readOnly = false,
+  isLoading,
+  error,
+  onRetry,
+  className,
+  style,
+}: AdaptiveLearningPathProps) {
+  const milestoneMap = useMemo(() => {
+    const map = new Map<number, PathMilestone>();
+    if (milestones) {
+      for (const m of milestones) {
+        map.set(m.afterNodeIndex, m);
+      }
+    }
+    return map;
+  }, [milestones]);
+
+  const safeNodes = Array.isArray(nodes) ? nodes : [];
+  const safeSkills = Array.isArray(skills) ? skills : [];
+
+  return (
+    <SectionShell
+      isLoading={isLoading}
+      error={error}
+      onRetry={onRetry}
+      className={className}
+      style={style}
+      skeleton={
+        <>
+          <Skeleton className="h-8 w-64" />
+          <Skeleton className="h-4 w-96 mt-2" />
+          <div className="grid grid-cols-2 sm:grid-cols-4 gap-3 mt-6">
+            {Array.from({ length: 4 }, (_, i) => (
+              <Skeleton key={i} className="h-28" />
+            ))}
+          </div>
+          <div className="mt-8 space-y-3">
+            {Array.from({ length: 5 }, (_, i) => (
+              <Skeleton key={i} className="h-20" />
+            ))}
+          </div>
+        </>
+      }
+    >
+      <div className={className} style={style}>
+        {/* Header */}
+        <div className="flex items-start justify-between gap-4 flex-wrap">
+          <div className="flex items-center gap-4">
+            <ProgressRing
+              value={progress.completionPercentage}
+              size={64}
+              strokeWidth={5}
+              className="shrink-0 text-primary"
+            />
+            <div>
+              <h2 className="text-xl font-bold text-foreground">{title}</h2>
+              {description && (
+                <p className="text-sm text-muted-foreground mt-0.5">
+                  {description}
+                </p>
+              )}
+            </div>
+          </div>
+          {difficulty && (
+            <Badge variant={DIFFICULTY_CONFIG[difficulty].variant}>
+              {DIFFICULTY_CONFIG[difficulty].label}
+            </Badge>
+          )}
+        </div>
+
+        {/* Stats row */}
+        <div className="grid grid-cols-2 sm:grid-cols-4 gap-3 mt-6">
+          <StatCard
+            icon={<Target />}
+            label="Progress"
+            value={`${Math.round(progress.completionPercentage)}%`}
+            subtitle="of path completed"
+            accent="var(--primary)"
+          />
+          <StatCard
+            icon={<BookOpen />}
+            label="Completed"
+            value={`${progress.completedNodes}/${progress.totalNodes}`}
+            subtitle="activities"
+            accent="var(--success)"
+          />
+          <StatCard
+            icon={<Clock />}
+            label="Time Spent"
+            value={formatDuration(progress.totalTimeSpent)}
+            subtitle="total"
+            accent="var(--info)"
+          />
+          {progress.averageScore != null ? (
+            <StatCard
+              icon={<TrendingUp />}
+              label="Avg Score"
+              value={`${Math.round(progress.averageScore)}%`}
+              subtitle="across activities"
+              accent="var(--warning)"
+            />
+          ) : progress.currentStreak != null ? (
+            <StatCard
+              icon={<Flame />}
+              label="Streak"
+              value={`${progress.currentStreak}`}
+              subtitle="days"
+              accent="var(--warning)"
+            />
+          ) : (
+            <StatCard
+              icon={<TrendingUp />}
+              label="Remaining"
+              value={`${progress.totalNodes - progress.completedNodes}`}
+              subtitle="activities left"
+              accent="var(--warning)"
+            />
+          )}
+        </div>
+
+        {/* Skills */}
+        {safeSkills.length > 0 && (
+          <>
+            <Separator className="my-5" />
+            <div>
+              <h3 className="text-sm font-semibold text-foreground mb-3">
+                Skills
+              </h3>
+              <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-x-6 gap-y-2">
+                {safeSkills.map((skill) => (
+                  <PathSkillBar
+                    key={skill.uid}
+                    skill={skill}
+                    onClick={onSkillClick}
+                  />
+                ))}
+              </div>
+            </div>
+          </>
+        )}
+
+        {/* Path visualization */}
+        <Separator className="my-5" />
+        <div
+          className="relative"
+          role="list"
+          aria-label={`Learning path: ${progress.completedNodes} of ${progress.totalNodes} completed`}
+        >
+          {safeNodes.map((node, index) => (
+            <div key={node.uid} role="listitem">
+              {/* Connector (between nodes) */}
+              {index > 0 && (
+                <PathConnector fromStatus={safeNodes[index - 1].status} />
+              )}
+
+              {/* Milestone marker (appears before node, after previous connector) */}
+              {milestoneMap.has(index - 1) && (
+                <PathMilestoneMarker
+                  milestone={milestoneMap.get(index - 1)!}
+                  className="my-1"
+                />
+              )}
+
+              {/* Node card */}
+              <PathNodeCard
+                node={node}
+                onClick={onNodeClick}
+                onStart={onNodeStart}
+                readOnly={readOnly}
+              />
+            </div>
+          ))}
+
+          {/* Final milestone (after last node) */}
+          {safeNodes.length > 0 &&
+            milestoneMap.has(safeNodes.length - 1) && (
+              <>
+                <PathConnector fromStatus={safeNodes[safeNodes.length - 1].status} />
+                <PathMilestoneMarker
+                  milestone={milestoneMap.get(safeNodes.length - 1)!}
+                  className="my-1"
+                />
+              </>
+            )}
+        </div>
+      </div>
+    </SectionShell>
+  );
+}
+
+export const AdaptiveLearningPath = withProGate(
+  AdaptiveLearningPathBase,
+  "AdaptiveLearningPath",
+);

package/src/sections/AdaptiveLearningPath/path-connector.tsx

@@ -0,0 +1,27 @@
+import { cn } from "../../lib/utils";
+import type { PathNodeStatus } from "./types";
+
+interface PathConnectorProps {
+  /** Status of the node above this connector */
+  fromStatus: PathNodeStatus;
+  className?: string;
+}
+
+export function PathConnector({ fromStatus, className }: PathConnectorProps) {
+  const isDone = fromStatus === "mastered" || fromStatus === "completed";
+  const isActive = fromStatus === "in_progress";
+
+  return (
+    <div className={cn("flex justify-center", className)}>
+      <div
+        className={cn(
+          "w-0.5 h-8",
+          isDone && "bg-success",
+          isActive && "bg-primary",
+          !isDone && !isActive && "bg-border",
+          fromStatus === "skipped" && "border-l border-dashed border-muted-foreground bg-transparent",
+        )}
+      />
+    </div>
+  );
+}

package/src/sections/AdaptiveLearningPath/path-milestone-marker.tsx

@@ -0,0 +1,50 @@
+import { Trophy, Lock } from "lucide-react";
+import { cn } from "../../lib/utils";
+import type { PathMilestone } from "./types";
+
+const VARIANT_COLORS = {
+  default: "text-primary",
+  gold: "text-palette-3",
+  silver: "text-muted-foreground",
+  bronze: "text-palette-3/70",
+} as const;
+
+interface PathMilestoneMarkerProps {
+  milestone: PathMilestone;
+  className?: string;
+}
+
+export function PathMilestoneMarker({
+  milestone,
+  className,
+}: PathMilestoneMarkerProps) {
+  const variant = milestone.variant ?? "default";
+
+  return (
+    <div
+      className={cn(
+        "flex items-center gap-3 py-2 px-4",
+        !milestone.reached && "opacity-50",
+        className,
+      )}
+    >
+      <div className="flex-1 h-px bg-border" />
+      <div className="flex items-center gap-2">
+        {milestone.reached ? (
+          <Trophy size={16} className={VARIANT_COLORS[variant]} />
+        ) : (
+          <Lock size={14} className="text-muted-foreground" />
+        )}
+        <span
+          className={cn(
+            "text-xs font-semibold whitespace-nowrap",
+            milestone.reached ? "text-foreground" : "text-muted-foreground",
+          )}
+        >
+          {milestone.title}
+        </span>
+      </div>
+      <div className="flex-1 h-px bg-border" />
+    </div>
+  );
+}

package/src/sections/AdaptiveLearningPath/path-node-card.tsx

@@ -0,0 +1,166 @@
+import { memo, useCallback } from "react";
+import {
+  Clock,
+  Lock,
+  CheckCircle2,
+  ShieldCheck,
+  SkipForward,
+  Sparkles,
+  Play,
+} from "lucide-react";
+import { Card, CardContent } from "../../ui/card";
+import { Badge } from "../../ui/badge";
+import { Button } from "../../ui/button";
+import { LearningObjectIcon } from "../../curriculum/learning-object-icon";
+import { formatDuration } from "../../utils/format-duration";
+import { cn } from "../../lib/utils";
+import type { PathNode, PathNodeStatus } from "./types";
+
+interface PathNodeCardProps {
+  node: PathNode;
+  onClick?: (uid: string) => void;
+  onStart?: (uid: string) => void;
+  readOnly?: boolean;
+  className?: string;
+}
+
+const STATUS_CONFIG: Record<
+  PathNodeStatus,
+  { label: string; variant: "success" | "destructive" | "warning" | "muted" | "info" | "default" | "secondary"; icon?: React.ElementType }
+> = {
+  mastered: { label: "Mastered", variant: "success", icon: ShieldCheck },
+  completed: { label: "Completed", variant: "success", icon: CheckCircle2 },
+  in_progress: { label: "In Progress", variant: "info", icon: Play },
+  available: { label: "Available", variant: "secondary" },
+  locked: { label: "Locked", variant: "muted", icon: Lock },
+  skipped: { label: "Skipped", variant: "muted", icon: SkipForward },
+};
+
+export const PathNodeCard = memo(function PathNodeCard({
+  node,
+  onClick,
+  onStart,
+  readOnly = false,
+  className,
+}: PathNodeCardProps) {
+  const config = STATUS_CONFIG[node.status];
+  const StatusIcon = config.icon;
+  const isInteractive = node.status !== "locked" && !readOnly;
+  const showStart =
+    !readOnly &&
+    (node.status === "available" || node.recommended) &&
+    node.status !== "locked" &&
+    node.status !== "completed" &&
+    node.status !== "mastered" &&
+    onStart;
+
+  const handleClick = useCallback(() => {
+    if (isInteractive && onClick) onClick(node.uid);
+  }, [isInteractive, onClick, node.uid]);
+
+  const handleKeyDown = useCallback(
+    (e: React.KeyboardEvent) => {
+      if (e.key === "Enter" || e.key === " ") {
+        e.preventDefault();
+        onClick?.(node.uid);
+      }
+    },
+    [onClick, node.uid],
+  );
+
+  const handleStart = useCallback(
+    (e: React.MouseEvent) => {
+      e.stopPropagation();
+      onStart?.(node.uid);
+    },
+    [onStart, node.uid],
+  );
+
+  return (
+    <Card
+      className={cn(
+        "transition-all",
+        isInteractive && onClick && "cursor-pointer hover:border-primary/50 hover:shadow-md",
+        node.status === "in_progress" && "border-primary ring-1 ring-primary/20",
+        node.status === "locked" && "opacity-60",
+        node.status === "skipped" && "opacity-50",
+        node.recommended && node.status !== "locked" && "border-primary/40",
+        className,
+      )}
+      onClick={isInteractive && onClick ? handleClick : undefined}
+      role={isInteractive && onClick ? "button" : undefined}
+      tabIndex={isInteractive && onClick ? 0 : undefined}
+      onKeyDown={isInteractive && onClick ? handleKeyDown : undefined}
+    >
+      <CardContent className="p-4">
+        <div className="flex items-start gap-3">
+          {/* Icon */}
+          <div
+            className={cn(
+              "shrink-0 w-9 h-9 rounded-lg flex items-center justify-center",
+              node.status === "locked"
+                ? "bg-muted text-muted-foreground"
+                : "bg-primary/10 text-primary",
+            )}
+          >
+            {node.icon ?? <LearningObjectIcon type={node.type} size={18} />}
+          </div>
+
+          {/* Content */}
+          <div className="flex-1 min-w-0">
+            <div className="flex items-center gap-2 flex-wrap">
+              <h4 className="text-sm font-semibold text-foreground truncate">
+                {node.title}
+              </h4>
+              {node.recommended && node.status !== "locked" && (
+                <Badge variant="default" className="text-[10px] px-1.5 h-5 gap-0.5">
+                  <Sparkles size={10} />
+                  Recommended
+                </Badge>
+              )}
+            </div>
+
+            {node.description && (
+              <p className="text-xs text-muted-foreground mt-0.5 line-clamp-1">
+                {node.description}
+              </p>
+            )}
+
+            {/* Meta row */}
+            <div className="flex items-center gap-3 mt-2 flex-wrap">
+              <Badge variant={config.variant} className="text-[10px] px-1.5 h-5 gap-0.5">
+                {StatusIcon && <StatusIcon size={10} />}
+                {config.label}
+              </Badge>
+
+              {node.estimatedDuration != null && node.estimatedDuration > 0 && (
+                <span className="flex items-center gap-1 text-xs text-muted-foreground">
+                  <Clock size={12} />
+                  {formatDuration(node.estimatedDuration)}
+                </span>
+              )}
+
+              {node.score != null && (
+                <span className="text-xs font-medium tabular-nums text-foreground">
+                  {node.score}%
+                </span>
+              )}
+            </div>
+          </div>
+
+          {/* Action */}
+          {showStart && (
+            <Button
+              size="sm"
+              variant={node.recommended ? "default" : "outline"}
+              className="shrink-0"
+              onClick={handleStart}
+            >
+              {node.status === "in_progress" ? "Continue" : "Start"}
+            </Button>
+          )}
+        </div>
+      </CardContent>
+    </Card>
+  );
+});

package/src/sections/AdaptiveLearningPath/path-skill-bar.tsx

@@ -0,0 +1,49 @@
+import { memo } from "react";
+import { Progress } from "../../ui/progress";
+import { Tooltip, TooltipTrigger, TooltipContent } from "../../ui/tooltip";
+import { cn } from "../../lib/utils";
+import type { PathSkill } from "./types";
+
+interface PathSkillBarProps {
+  skill: PathSkill;
+  onClick?: (uid: string) => void;
+  className?: string;
+}
+
+export const PathSkillBar = memo(function PathSkillBar({ skill, onClick, className }: PathSkillBarProps) {
+  const target = skill.targetProficiency ?? 100;
+
+  return (
+    <Tooltip>
+      <TooltipTrigger>
+        <button
+          type="button"
+          onClick={onClick ? () => onClick(skill.uid) : undefined}
+          disabled={!onClick}
+          className={cn(
+            "flex items-center gap-2 min-w-0 text-left",
+            onClick && "cursor-pointer hover:opacity-80",
+            !onClick && "cursor-default",
+            className,
+          )}
+        >
+          <span className="text-xs font-medium text-foreground whitespace-nowrap truncate min-w-16">
+            {skill.name}
+          </span>
+          <Progress
+            value={skill.proficiency}
+            max={target}
+            size="sm"
+            className="flex-1 min-w-20"
+          />
+          <span className="text-xs tabular-nums text-muted-foreground whitespace-nowrap">
+            {skill.proficiency}%
+          </span>
+        </button>
+      </TooltipTrigger>
+      <TooltipContent>
+        {skill.name}: {skill.proficiency}%{target < 100 ? ` / ${target}% target` : ""}
+      </TooltipContent>
+    </Tooltip>
+  );
+});