@hydralms/components 0.2.0 → 0.3.1

package/src/sections/AdaptiveLearningPath/types.ts

@@ -0,0 +1,159 @@
+import type { ReactNode } from "react";
+
+/**
+ * Status of a single node in the learning path.
+ * - `locked` — prerequisites not met, node is inaccessible
+ * - `available` — prerequisites met, learner can start
+ * - `in_progress` — learner is currently working on this node
+ * - `completed` — learner finished but below mastery threshold
+ * - `mastered` — learner finished and reached the mastery threshold
+ * - `skipped` — node was bypassed by the adaptive engine
+ */
+export type PathNodeStatus =
+  | "locked"
+  | "available"
+  | "in_progress"
+  | "completed"
+  | "mastered"
+  | "skipped";
+
+/**
+ * The type of learning activity a path node represents.
+ * Aligns with LearningObjectIcon type strings.
+ */
+export type PathNodeType =
+  | "lesson"
+  | "quiz"
+  | "assignment"
+  | "video"
+  | "discussion"
+  | "document"
+  | "assessment"
+  | "audio"
+  | "link";
+
+/** A skill or competency area that the learning path develops. */
+export interface PathSkill {
+  uid: string;
+  name: string;
+  /** Current proficiency level 0–100 */
+  proficiency: number;
+  /** Target proficiency level 0–100 */
+  targetProficiency?: number;
+}
+
+/** A milestone marker along the learning path. */
+export interface PathMilestone {
+  uid: string;
+  title: string;
+  description?: string;
+  /** Whether the milestone has been reached */
+  reached: boolean;
+  /** Index of the node after which this milestone appears (zero-based) */
+  afterNodeIndex: number;
+  variant?: "default" | "gold" | "silver" | "bronze";
+}
+
+/** A single node in the adaptive learning path. */
+export interface PathNode {
+  uid: string;
+  title: string;
+  description?: string;
+  /** Learning activity type — used for icon selection via LearningObjectIcon */
+  type: PathNodeType;
+  status: PathNodeStatus;
+  /** Estimated duration in seconds */
+  estimatedDuration?: number;
+  /** Performance score if completed (0–100) */
+  score?: number;
+  /** Whether this node is recommended as the next step */
+  recommended?: boolean;
+  /** Skill UIDs that this node develops */
+  skillUids?: string[];
+  /** UIDs of prerequisite nodes */
+  prerequisites?: string[];
+  /** Optional custom icon (overrides type-based icon) */
+  icon?: ReactNode;
+}
+
+/** A branch point where the adaptive engine may redirect the learner. */
+export interface PathBranch {
+  uid: string;
+  /** UID of the node where the branch originates */
+  fromNodeUid: string;
+  /** Label for this branch (e.g., "Review Fundamentals") */
+  label: string;
+  /** UIDs of nodes in this branch path */
+  nodeUids: string[];
+  /** Whether this branch is the active/chosen branch */
+  active?: boolean;
+  /** Condition description (e.g., "Score below 70%") */
+  condition?: string;
+}
+
+/** Overall progress summary for the path. */
+export interface PathProgress {
+  /** Percentage of path completed (0–100) */
+  completionPercentage: number;
+  completedNodes: number;
+  totalNodes: number;
+  /** Total time spent in seconds */
+  totalTimeSpent: number;
+  /** Average score across completed nodes (0–100) */
+  averageScore?: number;
+  /** Current streak in days */
+  currentStreak?: number;
+}
+
+/**
+ * AdaptiveLearningPath section — a premium visualization of a personalized
+ * learning sequence that adapts based on learner performance.
+ *
+ * Shows a visual path map with nodes, connectors, milestones, skill bars,
+ * and summary stats. 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)}
+ * />
+ */
+export interface AdaptiveLearningPathProps {
+  /** Path title */
+  title: string;
+  /** Optional path description */
+  description?: string;
+  /** Difficulty level displayed in the header */
+  difficulty?: "beginner" | "intermediate" | "advanced";
+  /** Ordered list of learning path nodes */
+  nodes: PathNode[];
+  /** Overall path progress data */
+  progress: PathProgress;
+  /** Skill/competency areas covered by this path */
+  skills?: PathSkill[];
+  /** Milestones along the path */
+  milestones?: PathMilestone[];
+  /** Branch points for adaptive routing */
+  branches?: PathBranch[];
+  /** Called when the user clicks a node */
+  onNodeClick?: (nodeUid: string) => void;
+  /** Called when the user starts a recommended or available activity */
+  onNodeStart?: (nodeUid: string) => void;
+  /** Called when the user clicks a skill */
+  onSkillClick?: (skillUid: string) => void;
+  /** When true, disables all interactive elements. @default false */
+  readOnly?: boolean;
+  /** Render skeleton placeholders instead of content */
+  isLoading?: boolean;
+  /** Error message — renders an error state with optional retry */
+  error?: string | null;
+  /** Called when the user clicks retry in the error state */
+  onRetry?: () => void;
+  className?: string;
+  style?: React.CSSProperties;
+}

package/src/sections/AnnouncementFeed/AnnouncementFeed.tsx

@@ -1,13 +1,15 @@
 import { useMemo, useState } from "react";
-import { Pin } from "lucide-react";
+import { AlertCircle, Pin } from "lucide-react";
 import { UserAvatar } from "../../social";
 import { EmptyState } from "../../common";
+import { Skeleton } from "../../ui/skeleton";
 import { Badge } from "../../ui/badge";
 import { Button } from "../../ui/button";
 import { Card, CardContent } from "../../ui/card";
 import type { AnnouncementFeedProps } from "./types";
 import { cn } from "../../lib/utils";
 import { formatTimestamp } from "../../utils/format-timestamp";
+import { Pagination } from "../../common/pagination";
 
 export function AnnouncementFeed({
   announcements,
@@ -17,6 +19,13 @@ export function AnnouncementFeed({
   previewLines = 3,
   emptyMessage = "No announcements yet",
   readOnly = false,
+  isLoading,
+  error,
+  onRetry,
+  pageSize,
+  currentPage = 1,
+  totalItems,
+  onPageChange,
   className,
   style,
 }: AnnouncementFeedProps) {
@@ -41,6 +50,42 @@ export function AnnouncementFeed({
     }
   }
 
+  if (isLoading) {
+    return (
+      <div className={cn("space-y-4", className)} style={style}>
+        {Array.from({ length: 3 }).map((_, i) => (
+          <div key={i} className="flex gap-3 items-start">
+            <Skeleton className="h-10 w-10 rounded-full shrink-0" />
+            <div className="flex-1 space-y-2">
+              <Skeleton className="h-5 w-48" />
+              <Skeleton className="h-4 w-full" />
+              <Skeleton className="h-4 w-full" />
+            </div>
+          </div>
+        ))}
+      </div>
+    );
+  }
+
+  if (error) {
+    return (
+      <div className={cn("py-12", className)} style={style}>
+        <EmptyState
+          icon={<AlertCircle className="size-10 text-destructive" />}
+          title="Something went wrong"
+          description={error}
+          action={
+            onRetry ? (
+              <Button variant="outline" onClick={onRetry}>
+                Retry
+              </Button>
+            ) : undefined
+          }
+        />
+      </div>
+    );
+  }
+
   if (sorted.length === 0) {
     return (
       <div className={className} style={style}>
@@ -51,7 +96,10 @@ export function AnnouncementFeed({
 
   return (
     <div className={cn("flex flex-col gap-2", className)} style={style}>
-      {sorted.map((a) => {
+      {(onPageChange && pageSize
+        ? sorted.slice((currentPage - 1) * pageSize, currentPage * pageSize)
+        : sorted
+      ).map((a) => {
         const isExpanded = expandedUids.has(a.uid);
 
         return (
@@ -91,9 +139,9 @@ export function AnnouncementFeed({
                   <span className="block text-xs text-muted-foreground mb-1">
                     {a.author.displayName} · {formatTimestamp(a.createdAt)}
                   </span>
-                  <span
+                  <div
                     className={cn(
-                      "text-sm text-foreground",
+                      "text-sm text-foreground [&_p]:mb-2 [&_ul]:list-disc [&_ul]:pl-5 [&_ol]:list-decimal [&_ol]:pl-5",
                       !isExpanded && "line-clamp-(--preview-lines) overflow-hidden",
                     )}
                     style={
@@ -101,10 +149,9 @@ export function AnnouncementFeed({
                         ? { "--preview-lines": previewLines } as React.CSSProperties
                         : undefined
                     }
-                  >
-                    {a.content}
-                  </span>
-                  {!isExpanded && a.content.length > 200 && (
+                    dangerouslySetInnerHTML={{ __html: a.content }}
+                  />
+                  {!isExpanded && a.content.replace(/<[^>]*>/g, "").length > 200 && (
                     <Button
                       variant="link"
                       size="xs"
@@ -123,6 +170,15 @@ export function AnnouncementFeed({
           </Card>
         );
       })}
+
+      {onPageChange && pageSize && sorted.length > 0 && (
+        <Pagination
+          currentPage={currentPage}
+          totalPages={Math.ceil((totalItems ?? sorted.length) / pageSize)}
+          onPageChange={onPageChange}
+          className="mt-4"
+        />
+      )}
     </div>
   );
 }

package/src/sections/AnnouncementFeed/types.ts

@@ -26,6 +26,20 @@ export interface AnnouncementFeedProps {
   emptyMessage?: string;
   /** When true, disables interactions */
   readOnly?: boolean;
+  /** Render skeleton placeholders instead of content */
+  isLoading?: boolean;
+  /** Error message — renders an error state with optional retry */
+  error?: string | null;
+  /** Called when the user clicks retry in the error state */
+  onRetry?: () => void;
+  /** Number of items per page (enables pagination when set with onPageChange) */
+  pageSize?: number;
+  /** Current page (1-indexed) */
+  currentPage?: number;
+  /** Total number of items (for server-side pagination) */
+  totalItems?: number;
+  /** Called when the user navigates to a different page */
+  onPageChange?: (page: number) => void;
   /** CSS class name for the root element */
   className?: string;
   /** Inline styles for the root element */
@@ -37,7 +51,7 @@ export interface Announcement {
   uid: string;
   /** Announcement title */
   title: string;
-  /** Announcement body content */
+  /** Announcement body content. May contain HTML from a rich-text editor. */
   content: string;
   /** Author information */
   author: { displayName: string; avatarUrl?: string; role?: string };

package/src/sections/AssessmentReview/AssessmentReview.tsx

@@ -1,9 +1,13 @@
 import { useMemo } from "react";
+import { AlertCircle } from "lucide-react";
 import { QuestionRenderer } from "../../questions";
 import type { QuestionData, SessionAnswer } from "../../questions/types";
 import { Badge } from "../../ui/badge";
 import { Card, CardContent } from "../../ui/card";
 import { Separator } from "../../ui/separator";
+import { Skeleton } from "../../ui/skeleton";
+import { Button } from "../../ui/button";
+import { EmptyState } from "../../common/empty-state";
 import { cn } from "../../lib/utils";
 import type {
   AssessmentReviewProps,
@@ -140,9 +144,42 @@ export function AssessmentReview({
   score,
   questionGroups,
   showCorrectAnswers = true,
+  isLoading,
+  error,
+  onRetry,
   className,
   style,
 }: AssessmentReviewProps) {
+  if (isLoading) {
+    return (
+      <div className={cn("space-y-4", className)} style={style}>
+        <Skeleton className="h-16 w-full" />
+        <Skeleton className="h-24 w-full" />
+        <Skeleton className="h-24 w-full" />
+        <Skeleton className="h-24 w-full" />
+      </div>
+    );
+  }
+
+  if (error) {
+    return (
+      <div className={cn("py-12", className)} style={style}>
+        <EmptyState
+          icon={<AlertCircle className="size-10 text-destructive" />}
+          title="Something went wrong"
+          description={error}
+          action={
+            onRetry ? (
+              <Button variant="outline" onClick={onRetry}>
+                Retry
+              </Button>
+            ) : undefined
+          }
+        />
+      </div>
+    );
+  }
+
   return (
     <div className={cn(className)} style={style}>
       {score && <ScoreHeader score={score} />}

package/src/sections/AssessmentReview/types.ts

@@ -34,6 +34,12 @@ export interface AssessmentReviewProps {
    * @default true
    */
   showCorrectAnswers?: boolean;
+  /** Render skeleton placeholders instead of content */
+  isLoading?: boolean;
+  /** Error message — renders an error state with optional retry */
+  error?: string | null;
+  /** Called when the user clicks retry in the error state */
+  onRetry?: () => void;
   /** CSS class name for the root element */
   className?: string;
   /** Inline styles for the root element */

package/src/sections/AssignmentSubmission/AssignmentSubmission.tsx

@@ -1,5 +1,5 @@
 import { useState } from "react";
-import { Send, Save } from "lucide-react";
+import { Send, Save, AlertCircle } from "lucide-react";
 import { StatusBadge, DueDateDisplay } from "../../common";
 import { FileUploadZone } from "../../content";
 import { Button } from "../../ui/button";
@@ -9,6 +9,9 @@ import { Separator } from "../../ui/separator";
 import { Card, CardContent } from "../../ui/card";
 import { Alert, AlertDescription } from "../../ui/alert";
 import { Tabs, TabsList, TabsTrigger, TabsContent } from "../../ui/tabs";
+import { Skeleton } from "../../ui/skeleton";
+import { EmptyState } from "../../common/empty-state";
+import { cn } from "../../lib/utils";
 import type { AssignmentSubmissionProps, SubmissionData } from "./types";
 
 export function AssignmentSubmission({
@@ -25,6 +28,9 @@ export function AssignmentSubmission({
   grade,
   isSubmitting = false,
   readOnly = false,
+  isLoading,
+  error,
+  onRetry,
   className,
   style,
 }: AssignmentSubmissionProps) {
@@ -33,6 +39,36 @@ export function AssignmentSubmission({
   const [url, setUrl] = useState(existingSubmission?.url ?? "");
   const [activeTab, setActiveTab] = useState<"text" | "file" | "url">(submissionTypes[0]);
 
+  if (isLoading) {
+    return (
+      <div className={cn("space-y-4", className)} style={style}>
+        <Skeleton className="h-8 w-64" />
+        <Skeleton className="h-6 w-20" />
+        <Skeleton className="h-32 w-full" />
+        <Skeleton className="h-10 w-32" />
+      </div>
+    );
+  }
+
+  if (error) {
+    return (
+      <div className={cn("py-12", className)} style={style}>
+        <EmptyState
+          icon={<AlertCircle className="size-10 text-destructive" />}
+          title="Something went wrong"
+          description={error}
+          action={
+            onRetry ? (
+              <Button variant="outline" onClick={onRetry}>
+                Retry
+              </Button>
+            ) : undefined
+          }
+        />
+      </div>
+    );
+  }
+
   const isEditable = !readOnly && !["submitted", "graded"].includes(status);
 
   function getSubmissionData(): SubmissionData {

package/src/sections/AssignmentSubmission/types.ts

@@ -44,6 +44,12 @@ export interface AssignmentSubmissionProps {
   isSubmitting?: boolean;
   /** When true, disables all interactions */
   readOnly?: boolean;
+  /** Render skeleton placeholders instead of content */
+  isLoading?: boolean;
+  /** Error message — renders an error state with optional retry */
+  error?: string | null;
+  /** Called when the user clicks retry in the error state */
+  onRetry?: () => void;
   /** CSS class name for the root element */
   className?: string;
   /** Inline styles for the root element */