@hydralms/components 0.2.0 → 0.3.1

package/src/sections/FlashcardStudySession/FlashcardStudySession.tsx

@@ -1,8 +1,10 @@
 import { useState } from "react";
 import { CheckCircle } from "lucide-react";
 import { FlashcardDeck } from "../../flashcards";
+import { Skeleton } from "../../ui/skeleton";
 import { Button } from "../../ui/button";
 import { Card, CardContent } from "../../ui/card";
+import { SectionShell } from "../_shared/section-shell";
 import type {
   FlashcardStudySessionProps,
   FlashcardSessionStats,
@@ -16,6 +18,9 @@ export function FlashcardStudySession({
   shuffled = false,
   onComplete,
   readOnly = false,
+  isLoading,
+  error,
+  onRetry,
   className,
   style,
 }: FlashcardStudySessionProps) {
@@ -35,42 +40,54 @@ export function FlashcardStudySession({
     setIsComplete(false);
   }
 
-  if (isComplete) {
-    return (
-      <div className={cn("flex flex-col items-center", className)} style={style}>
-        <Card>
-          <CardContent className="pt-6 text-center flex flex-col items-center gap-2">
-            <CheckCircle size={48} className="text-success" />
-            <span className="text-xl font-bold text-foreground">Deck complete!</span>
-            {title && (
-              <span className="text-muted-foreground">
-                You finished <strong>{title}</strong>
-              </span>
-            )}
-            <span className="text-sm text-muted-foreground">
-              {stats.totalCards} card{stats.totalCards !== 1 ? "s" : ""} studied
-              {stats.wasShuffled ? " (shuffled)" : ""}
-            </span>
-            <Button className="mt-2" onClick={handleStudyAgain}>
-              Study Again
-            </Button>
-          </CardContent>
-        </Card>
-      </div>
-    );
-  }
-
   return (
-    <div className={cn("flex flex-col items-center", className)} style={style}>
-      <FlashcardDeck
-        cards={cards}
-        deckName={title}
-        deckDescription={description}
-        shuffled={shuffled}
-        showProgress
-        onComplete={handleComplete}
-        readOnly={readOnly}
-      />
-    </div>
+    <SectionShell
+      isLoading={isLoading}
+      error={error}
+      onRetry={onRetry}
+      className={className}
+      style={style}
+      skeleton={
+        <>
+          <Skeleton className="h-6 w-48" />
+          <Skeleton className="h-64 w-full rounded-lg" />
+        </>
+      }
+    >
+      {isComplete ? (
+        <div className={cn("flex flex-col items-center", className)} style={style}>
+          <Card>
+            <CardContent className="pt-6 text-center flex flex-col items-center gap-2">
+              <CheckCircle size={48} className="text-success" />
+              <span className="text-xl font-bold text-foreground">Deck complete!</span>
+              {title && (
+                <span className="text-muted-foreground">
+                  You finished <strong>{title}</strong>
+                </span>
+              )}
+              <span className="text-sm text-muted-foreground">
+                {stats.totalCards} card{stats.totalCards !== 1 ? "s" : ""} studied
+                {stats.wasShuffled ? " (shuffled)" : ""}
+              </span>
+              <Button className="mt-2" onClick={handleStudyAgain}>
+                Study Again
+              </Button>
+            </CardContent>
+          </Card>
+        </div>
+      ) : (
+        <div className={cn("flex flex-col items-center", className)} style={style}>
+          <FlashcardDeck
+            cards={cards}
+            deckName={title}
+            deckDescription={description}
+            shuffled={shuffled}
+            showProgress
+            onComplete={handleComplete}
+            readOnly={readOnly}
+          />
+        </div>
+      )}
+    </SectionShell>
   );
 }

package/src/sections/FlashcardStudySession/types.ts

@@ -28,6 +28,12 @@ export interface FlashcardStudySessionProps {
   onComplete?: (stats: FlashcardSessionStats) => void;
   /** When true, disables card flipping */
   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 */

package/src/sections/ForumBoard/ForumBoard.tsx

@@ -1,5 +1,6 @@
-import { useState, useMemo } from "react";
+import { useState, useMemo, memo, useCallback } from "react";
 import {
+  AlertCircle,
   Plus,
   MessageSquare,
   Heart,
@@ -7,6 +8,7 @@ import {
   CheckCircle2,
   ArrowUpDown,
 } from "lucide-react";
+import { Skeleton } from "../../ui/skeleton";
 import { SearchInput } from "../../common/search-input";
 import { UserAvatar } from "../../social/user-avatar";
 import { EmptyState } from "../../common/empty-state";
@@ -19,6 +21,7 @@ import { RichTextEditor } from "../../ui/rich-text-editor";
 import { isEmptyHtml } from "../../utils/is-empty-html";
 import { cn } from "../../lib/utils";
 import { formatTimestamp } from "../../utils/format-timestamp";
+import { Pagination } from "../../common/pagination";
 import type { ForumBoardProps, ForumTopic, ForumSortOrder } from "./types";
 
 const SORT_LABELS: Record<ForumSortOrder, string> = {
@@ -44,6 +47,13 @@ export function ForumBoard({
   searchQuery = "",
   onSearchChange,
   readOnly,
+  isLoading,
+  error,
+  onRetry,
+  pageSize,
+  currentPage = 1,
+  totalItems,
+  onPageChange,
   className,
   style,
 }: ForumBoardProps) {
@@ -117,6 +127,42 @@ export function ForumBoard({
     });
   }, [topics, activeSearch, activeSort]);
 
+  if (isLoading) {
+    return (
+      <div className={cn("space-y-4", className)} style={style}>
+        <Skeleton className="h-9 w-full" />
+        {Array.from({ length: 4 }).map((_, i) => (
+          <div key={i} className="flex items-center gap-3">
+            <Skeleton className="h-8 w-8 rounded-full" />
+            <div className="flex-1 space-y-2">
+              <Skeleton className="h-5 w-64" />
+              <Skeleton className="h-4 w-32" />
+            </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>
+    );
+  }
+
   return (
     <div className={cn("flex flex-col gap-4", className)} style={style}>
       {/* Header */}
@@ -204,31 +250,45 @@ export function ForumBoard({
         />
       ) : (
         <div className="flex flex-col gap-2">
-          {sorted.map((topic) => (
+          {(onPageChange && pageSize
+            ? sorted.slice((currentPage - 1) * pageSize, currentPage * pageSize)
+            : sorted
+          ).map((topic) => (
             <TopicRow
               key={topic.uid}
               topic={topic}
-              onClick={() => onTopicClick(topic.uid)}
+              onClick={onTopicClick}
             />
           ))}
         </div>
       )}
+
+      {onPageChange && pageSize && sorted.length > 0 && (
+        <Pagination
+          currentPage={currentPage}
+          totalPages={Math.ceil((totalItems ?? sorted.length) / pageSize)}
+          onPageChange={onPageChange}
+          className="mt-4"
+        />
+      )}
     </div>
   );
 }
 
-function TopicRow({
+const TopicRow = memo(function TopicRow({
   topic,
   onClick,
 }: {
   topic: ForumTopic;
-  onClick: () => void;
+  onClick: (uid: string) => void;
 }) {
+  const handleClick = useCallback(() => onClick(topic.uid), [onClick, topic.uid]);
+
   return (
     <button
       type="button"
       className="w-full text-left"
-      onClick={onClick}
+      onClick={handleClick}
     >
       <Card
         className={cn(
@@ -281,4 +341,4 @@ function TopicRow({
       </Card>
     </button>
   );
-}
+});

package/src/sections/ForumBoard/types.ts

@@ -37,6 +37,20 @@ export interface ForumBoardProps {
   onSearchChange?: (query: string) => void;
   /** When true, disables create and 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 */

package/src/sections/GradebookTable/GradebookTable.tsx

@@ -1,9 +1,13 @@
 import { Fragment, useMemo, useState } from "react";
-import { ArrowUp, ArrowDown } from "lucide-react";
+import { ArrowUp, ArrowDown, AlertCircle } from "lucide-react";
 import { GradeIndicator } from "../../progress";
 import { StatusBadge, DueDateDisplay } from "../../common";
 import { Card, CardContent } from "../../ui/card";
 import { Table, TableHeader, TableBody, TableRow, TableHead, TableCell } from "../../ui/table";
+import { Skeleton } from "../../ui/skeleton";
+import { Button } from "../../ui/button";
+import { EmptyState } from "../../common/empty-state";
+import { Pagination } from "../../common/pagination";
 import type { GradebookTableProps, GradeCategory } from "./types";
 import { cn } from "../../lib/utils";
 
@@ -53,6 +57,13 @@ export function GradebookTable({
   showCategoryTotals = true,
   onItemClick,
   readOnly = false,
+  isLoading,
+  error,
+  onRetry,
+  pageSize,
+  currentPage = 1,
+  totalItems,
+  onPageChange,
   className,
   style,
 }: GradebookTableProps) {
@@ -104,6 +115,39 @@ export function GradebookTable({
 
   const colCount = showWeights ? 5 : 4;
 
+  if (isLoading) {
+    return (
+      <div className={cn("space-y-4", className)} style={style}>
+        <Skeleton className="h-20 w-full" />
+        <Skeleton className="h-10 w-full" />
+        <Skeleton className="h-12 w-full" />
+        <Skeleton className="h-12 w-full" />
+        <Skeleton className="h-12 w-full" />
+        <Skeleton className="h-12 w-full" />
+        <Skeleton className="h-12 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={className} style={style}>
       {/* Overall grade */}
@@ -224,6 +268,15 @@ export function GradebookTable({
           </TableBody>
         </Table>
       </Card>
+
+      {onPageChange && pageSize && (
+        <Pagination
+          currentPage={currentPage}
+          totalPages={Math.ceil((totalItems ?? items.length) / pageSize)}
+          onPageChange={onPageChange}
+          className="mt-4"
+        />
+      )}
     </div>
   );
 }

package/src/sections/GradebookTable/types.ts

@@ -27,6 +27,20 @@ export interface GradebookTableProps {
   onItemClick?: (item: GradeItem) => void;
   /** 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 */

package/src/sections/LecturePlayer/LecturePlayer.tsx

@@ -1,5 +1,8 @@
+import { useCallback } from "react";
 import { VideoPlayer } from "../../video";
 import { Card, CardHeader, CardTitle, CardContent } from "../../ui/card";
+import { Skeleton } from "../../ui/skeleton";
+import { SectionShell } from "../_shared/section-shell";
 import type { LecturePlayerProps } from "./types";
 import { cn } from "../../lib/utils";
 
@@ -9,52 +12,75 @@ export function LecturePlayer({
   layout = "horizontal",
   notesPanelWidth = "340px",
   notesPanelHeight = "240px",
+  isLoading,
+  error,
+  onRetry,
+  onComplete,
   className,
   style,
 }: LecturePlayerProps) {
   const isHorizontal = layout === "horizontal";
 
-  if (!notes) {
-    return (
-      <div className={className} style={style}>
-        <VideoPlayer {...video} />
-      </div>
-    );
-  }
+  const handleEnded = useCallback(() => {
+    video.onEnded?.();
+    onComplete?.();
+  }, [video, onComplete]);
 
   return (
-    <div
-      className={cn(
-        "flex overflow-hidden gap-4",
-        isHorizontal ? "flex-row" : "flex-col",
-        className,
-      )}
+    <SectionShell
+      isLoading={isLoading}
+      error={error}
+      onRetry={onRetry}
+      className={className}
       style={style}
+      skeleton={
+        <>
+          <Skeleton className="aspect-video w-full rounded-lg" />
+          {notes !== undefined && (
+            <Skeleton className="h-32 w-full rounded-lg" />
+          )}
+        </>
+      }
     >
-      <div className="flex-1 min-w-0 min-h-0">
-        <VideoPlayer {...video} />
-      </div>
-      <Card
-        className={cn(
-          "overflow-auto shrink-0 rounded-none border-0",
-          isHorizontal ? "border-l border-border" : "border-t border-border w-full",
-        )}
-        style={{
-          width: isHorizontal ? notesPanelWidth : undefined,
-          height: isHorizontal ? undefined : notesPanelHeight,
-        }}
-      >
-        <CardHeader>
-          <CardTitle>Notes</CardTitle>
-        </CardHeader>
-        <CardContent>
-          {typeof notes === "string" ? (
-            <span className="text-sm text-foreground">{notes}</span>
-          ) : (
-            notes
+      {!notes ? (
+        <div className={className} style={style}>
+          <VideoPlayer {...video} onEnded={handleEnded} />
+        </div>
+      ) : (
+        <div
+          className={cn(
+            "flex overflow-hidden gap-4",
+            isHorizontal ? "flex-row" : "flex-col",
+            className,
           )}
-        </CardContent>
-      </Card>
-    </div>
+          style={style}
+        >
+          <div className="flex-1 min-w-0 min-h-0">
+            <VideoPlayer {...video} onEnded={handleEnded} />
+          </div>
+          <Card
+            className={cn(
+              "overflow-auto shrink-0 rounded-none border-0",
+              isHorizontal ? "border-l border-border" : "border-t border-border w-full",
+            )}
+            style={{
+              width: isHorizontal ? notesPanelWidth : undefined,
+              height: isHorizontal ? undefined : notesPanelHeight,
+            }}
+          >
+            <CardHeader>
+              <CardTitle>Notes</CardTitle>
+            </CardHeader>
+            <CardContent>
+              {typeof notes === "string" ? (
+                <span className="text-sm text-foreground">{notes}</span>
+              ) : (
+                notes
+              )}
+            </CardContent>
+          </Card>
+        </div>
+      )}
+    </SectionShell>
   );
 }

package/src/sections/LecturePlayer/types.ts

@@ -41,6 +41,14 @@ export interface LecturePlayerProps {
    * @default "240px"
    */
   notesPanelHeight?: string | number;
+  /** 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;
+  /** Called when the video playback ends. */
+  onComplete?: () => void;
   /** CSS class name for the root element */
   className?: string;
   /** Inline styles for the root element */

package/src/sections/LessonPage/LessonPage.tsx

@@ -1,12 +1,15 @@
 import { useState } from "react";
 import { Check, ChevronRight, Clock } from "lucide-react";
 import { ContentBlock } from "../../content";
+import { Skeleton } from "../../ui/skeleton";
+import { EmptyState } from "../../common/empty-state";
 import { Button } from "../../ui/button";
 import { Card, CardContent } from "../../ui/card";
 import { Separator } from "../../ui/separator";
+import { SectionShell } from "../_shared/section-shell";
 import { formatDuration } from "../../utils/format-duration";
 import type { LessonPageProps } from "./types";
-import { cn } from "../../lib/utils";
+
 
 export function LessonPage({
   title,
@@ -18,18 +21,37 @@ export function LessonPage({
   estimatedDuration,
   showDuration = true,
   readOnly = false,
+  isLoading,
+  error,
+  onRetry,
   className,
   style,
 }: LessonPageProps) {
-  const [completed, setCompleted] = useState(isCompleted);
+  const [localCompleted, setLocalCompleted] = useState(false);
+  const completed = isCompleted || localCompleted;
 
   function handleMarkComplete() {
-    setCompleted(true);
+    setLocalCompleted(true);
     onMarkComplete?.();
   }
 
   return (
-    <div className={cn(className)} style={style}>
+    <SectionShell
+      isLoading={isLoading}
+      error={error}
+      onRetry={onRetry}
+      className={className}
+      style={style}
+      skeleton={
+        <>
+          <Skeleton className="h-8 w-64" />
+          <Skeleton className="h-24 w-full" />
+          <Skeleton className="h-16 w-full" />
+          <Skeleton className="h-32 w-full" />
+        </>
+      }
+    >
+    <div>
       {/* Header */}
       <div className="mb-3">
         <p className="text-2xl font-bold mb-0.5 text-foreground">{title}</p>
@@ -45,13 +67,18 @@ export function LessonPage({
 
       {/* Content blocks */}
       <div className="flex flex-col gap-3">
-        {blocks.map((block, i) => (
+        {blocks?.length ? blocks.map((block, i) => (
           <ContentBlock
             key={i}
             block={block}
             readOnly={readOnly}
           />
-        ))}
+        )) : (
+          <EmptyState
+            title="No content yet"
+            description="This lesson doesn't have any content blocks."
+          />
+        )}
       </div>
 
       {/* Completion bar */}
@@ -83,5 +110,6 @@ export function LessonPage({
         </CardContent>
       </Card>
     </div>
+    </SectionShell>
   );
 }

package/src/sections/LessonPage/types.ts

@@ -34,6 +34,12 @@ export interface LessonPageProps {
   showDuration?: boolean;
   /** When true, disables interactive elements */
   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 */