@hydralms/components 0.3.0 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hydralms/components",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "React component library for LMS platforms",
   "license": "MIT",
   "author": "HydraLMS",
@@ -113,14 +113,31 @@
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0",
-    "tailwindcss": "^4.0.0"
+    "tailwindcss": "^4.0.0",
+    "@tiptap/react": "^3.0.0",
+    "@tiptap/starter-kit": "^3.0.0",
+    "@tiptap/extension-link": "^3.0.0",
+    "@tiptap/extension-placeholder": "^3.0.0",
+    "@tiptap/extension-underline": "^3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@tiptap/react": {
+      "optional": true
+    },
+    "@tiptap/starter-kit": {
+      "optional": true
+    },
+    "@tiptap/extension-link": {
+      "optional": true
+    },
+    "@tiptap/extension-placeholder": {
+      "optional": true
+    },
+    "@tiptap/extension-underline": {
+      "optional": true
+    }
   },
   "dependencies": {
-    "@tiptap/extension-link": "^3.20.1",
-    "@tiptap/extension-placeholder": "^3.20.1",
-    "@tiptap/extension-underline": "^3.20.1",
-    "@tiptap/react": "^3.20.1",
-    "@tiptap/starter-kit": "^3.20.1",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "lucide-react": "^0.475.0",

package/src/license/index.ts

@@ -1,7 +1,7 @@
 export { HydraLicenseProvider, HydraLicenseContext } from './HydraContext';
 export type { HydraPlan, HydraLicenseContextValue, HydraLicenseProviderProps } from './HydraContext';
 export { useHydraLicense } from './useHydraLicense';
-export { isProModule, PRO_MODULES } from './tiers';
-export type { ProModuleName } from './tiers';
+export { isProModule, PRO_MODULES, isProSection, PRO_SECTIONS } from './tiers';
+export type { ProModuleName, ProSectionName } from './tiers';
 export { ProBadge } from './ProBadge';
 export { withProGate } from './withProGate';

package/src/license/tiers.ts

@@ -1,6 +1,6 @@
 // ─── HydraLMS Pro Tier Definitions ──────────────────────────────
-// All 12 modules are Pro tier. UI primitives, base components, and
-// sections are free and always will be.
+// All 12 modules and premium sections are Pro tier.
+// UI primitives, base components, and standard sections are free.
 
 export const PRO_MODULES = new Set([
   'QuizModule',
@@ -22,3 +22,13 @@ export type ProModuleName = typeof PRO_MODULES extends Set<infer T> ? T : never;
 export function isProModule(name: string): boolean {
   return PRO_MODULES.has(name as any);
 }
+
+export const PRO_SECTIONS = new Set([
+  'ContentAuthoringStudio',
+] as const);
+
+export type ProSectionName = typeof PRO_SECTIONS extends Set<infer T> ? T : never;
+
+export function isProSection(name: string): boolean {
+  return PRO_SECTIONS.has(name as any);
+}

package/src/modules/CoursePlayer/CoursePlayer.tsx

@@ -76,7 +76,9 @@ function CoursePlayerBase({
     () => activeItem?.type === "video"
       ? { src: activeItem.src, poster: activeItem.poster, title: activeItem.title }
       : null,
-    [activeItem],
+    // activeItem is looked up from a stable Map — uid change means new item
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [activeItem?.uid],
   );
 
   useEffect(() => {

package/src/progress/stat-card.tsx

@@ -1,4 +1,4 @@
-import { memo } from "react";
+import { memo, useMemo } from "react";
 import { TrendingUp, TrendingDown, Minus } from "lucide-react";
 import { Card, CardContent } from "../ui/card";
 import type { StatCardProps } from "./types";
@@ -24,16 +24,21 @@ export const StatCard = memo(function StatCard({
 }: StatCardProps) {
   const TrendIcon = trend ? TREND_ICONS[trend.direction] : null;
 
+  const iconStyle = useMemo(
+    () => ({
+      backgroundColor: `color-mix(in oklch, ${accent ?? "var(--primary)"} 10%, transparent)`,
+      color: accent ?? "var(--primary)",
+    }),
+    [accent],
+  );
+
   return (
     <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)",
-            }}
+            style={iconStyle}
           >
             {icon}
           </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>
+  );
+});