@hydralms/components 0.1.3 → 0.3.0

package/src/sections/ExamSession/types.ts

@@ -1,5 +1,5 @@
 import type { ReactNode } from "react";
-import type { QuestionData, SessionAnswer } from "../../questions/types";
+import type { QuestionData, QuestionMaterial, SessionAnswer } from "../../questions/types";
 
 /**
  * ExamSession section — a formal timed exam experience.
@@ -44,8 +44,19 @@ export interface ExamSessionProps {
   instructions?: ReactNode;
   /** Whether the submit action is in flight */
   isSubmitting?: boolean;
+  /**
+   * Related materials keyed by question UID. When provided, a "Materials"
+   * button appears in the question header, opening a drawer with content blocks.
+   */
+  questionMaterials?: QuestionMaterial[];
   /** When true, all inputs are disabled */
   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/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

@@ -0,0 +1,342 @@
+import { useState, useMemo } from "react";
+import {
+  AlertCircle,
+  Plus,
+  MessageSquare,
+  Heart,
+  Pin,
+  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";
+import { Button } from "../../ui/button";
+import { Card, CardContent } from "../../ui/card";
+import { Badge } from "../../ui/badge";
+import { Separator } from "../../ui/separator";
+import { Input } from "../../ui/input";
+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> = {
+  newest: "Newest",
+  oldest: "Oldest",
+  most_replies: "Most Replies",
+  most_liked: "Most Liked",
+};
+
+/**
+ * ForumBoard — a topic listing view for a discussion forum.
+ *
+ * Displays a searchable, sortable list of discussion topics with author info,
+ * reply/like counts, timestamps, and new topic creation.
+ */
+export function ForumBoard({
+  title,
+  topics,
+  onTopicClick,
+  onCreateTopic,
+  sortOrder = "newest",
+  onSortChange,
+  searchQuery = "",
+  onSearchChange,
+  readOnly,
+  isLoading,
+  error,
+  onRetry,
+  pageSize,
+  currentPage = 1,
+  totalItems,
+  onPageChange,
+  className,
+  style,
+}: ForumBoardProps) {
+  const [showCreateForm, setShowCreateForm] = useState(false);
+  const [newTitle, setNewTitle] = useState("");
+  const [newContent, setNewContent] = useState("");
+  const [localSearch, setLocalSearch] = useState(searchQuery);
+  const [localSort, setLocalSort] = useState(sortOrder);
+
+  const activeSearch = onSearchChange !== undefined ? searchQuery : localSearch;
+  const activeSort = onSortChange !== undefined ? sortOrder : localSort;
+
+  function handleSearchChange(query: string) {
+    if (onSearchChange) {
+      onSearchChange(query);
+    } else {
+      setLocalSearch(query);
+    }
+  }
+
+  function handleSortChange() {
+    const order: Array<"newest" | "oldest" | "most_replies" | "most_liked"> = [
+      "newest",
+      "oldest",
+      "most_replies",
+      "most_liked",
+    ];
+    const idx = order.indexOf(activeSort);
+    const next = order[(idx + 1) % order.length];
+    if (onSortChange) {
+      onSortChange(next);
+    } else {
+      setLocalSort(next);
+    }
+  }
+
+  function handleCreateTopic() {
+    if (!newTitle.trim() || isEmptyHtml(newContent)) return;
+    onCreateTopic?.(newTitle.trim(), newContent);
+    setNewTitle("");
+    setNewContent("");
+    setShowCreateForm(false);
+  }
+
+  // Filter and sort
+  const sorted = useMemo(() => {
+    const filtered = topics.filter((t) => {
+      if (!activeSearch) return true;
+      const q = activeSearch.toLowerCase();
+      return (
+        t.title.toLowerCase().includes(q) ||
+        t.preview?.toLowerCase().includes(q) ||
+        t.author.displayName.toLowerCase().includes(q)
+      );
+    });
+
+    return [...filtered].sort((a, b) => {
+      if (a.isPinned && !b.isPinned) return -1;
+      if (!a.isPinned && b.isPinned) return 1;
+      switch (activeSort) {
+        case "oldest":
+          return new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime();
+        case "most_replies":
+          return b.replyCount - a.replyCount;
+        case "most_liked":
+          return b.likeCount - a.likeCount;
+        case "newest":
+        default:
+          return new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime();
+      }
+    });
+  }, [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 */}
+      <div className="flex items-center justify-between gap-4">
+        {title && (
+          <h2 className="text-xl font-bold text-foreground">{title}</h2>
+        )}
+        {!readOnly && onCreateTopic && (
+          <Button
+            size="sm"
+            onClick={() => setShowCreateForm(!showCreateForm)}
+          >
+            <Plus className="size-4 mr-1.5" />
+            New Topic
+          </Button>
+        )}
+      </div>
+
+      <Separator />
+
+      {/* Create topic form */}
+      {showCreateForm && (
+        <Card>
+          <CardContent className="pt-4 space-y-3">
+            <Input
+              placeholder="Topic title"
+              value={newTitle}
+              onChange={(e) => setNewTitle(e.target.value)}
+            />
+            <RichTextEditor
+              placeholder="What would you like to discuss?"
+              value={newContent}
+              onChange={(html) => setNewContent(html)}
+              variant="minimal"
+            />
+            <div className="flex justify-end gap-2">
+              <Button
+                variant="outline"
+                size="sm"
+                onClick={() => {
+                  setShowCreateForm(false);
+                  setNewTitle("");
+                  setNewContent("");
+                }}
+              >
+                Cancel
+              </Button>
+              <Button
+                size="sm"
+                onClick={handleCreateTopic}
+                disabled={!newTitle.trim() || isEmptyHtml(newContent)}
+              >
+                Post Topic
+              </Button>
+            </div>
+          </CardContent>
+        </Card>
+      )}
+
+      {/* Search & sort bar */}
+      <div className="flex items-center gap-2">
+        <div className="flex-1">
+          <SearchInput
+            value={activeSearch}
+            onChange={handleSearchChange}
+            placeholder="Search topics..."
+          />
+        </div>
+        <Button variant="outline" size="sm" onClick={handleSortChange}>
+          <ArrowUpDown className="size-3.5 mr-1.5" />
+          {SORT_LABELS[activeSort]}
+        </Button>
+      </div>
+
+      {/* Topic list */}
+      {sorted.length === 0 ? (
+        <EmptyState
+          icon={<MessageSquare className="size-10 text-muted-foreground" />}
+          title="No topics found"
+          description={
+            activeSearch
+              ? "Try a different search term."
+              : "Be the first to start a discussion!"
+          }
+        />
+      ) : (
+        <div className="flex flex-col gap-2">
+          {(onPageChange && pageSize
+            ? sorted.slice((currentPage - 1) * pageSize, currentPage * pageSize)
+            : sorted
+          ).map((topic) => (
+            <TopicRow
+              key={topic.uid}
+              topic={topic}
+              onClick={() => onTopicClick(topic.uid)}
+            />
+          ))}
+        </div>
+      )}
+
+      {onPageChange && pageSize && sorted.length > 0 && (
+        <Pagination
+          currentPage={currentPage}
+          totalPages={Math.ceil((totalItems ?? sorted.length) / pageSize)}
+          onPageChange={onPageChange}
+          className="mt-4"
+        />
+      )}
+    </div>
+  );
+}
+
+function TopicRow({
+  topic,
+  onClick,
+}: {
+  topic: ForumTopic;
+  onClick: () => void;
+}) {
+  return (
+    <button
+      type="button"
+      className="w-full text-left"
+      onClick={onClick}
+    >
+      <Card
+        className={cn(
+          "transition-colors hover:bg-muted/30",
+          topic.isPinned && "border-l-2 border-l-warning"
+        )}
+      >
+        <CardContent className="py-3 px-4">
+          <div className="flex items-start gap-3">
+            <UserAvatar
+              displayName={topic.author.displayName}
+              avatarUrl={topic.author.avatarUrl}
+              size="small"
+            />
+            <div className="flex-1 min-w-0">
+              <div className="flex items-center gap-2 mb-0.5">
+                <span className="font-medium text-foreground text-sm truncate">
+                  {topic.title}
+                </span>
+                {topic.isPinned && (
+                  <Pin className="size-3 text-warning shrink-0" />
+                )}
+                {topic.isAnswered && (
+                  <Badge variant="success" className="text-xs shrink-0">
+                    <CheckCircle2 className="size-3 mr-0.5" />
+                    Answered
+                  </Badge>
+                )}
+              </div>
+              {topic.preview && (
+                <p className="text-xs text-muted-foreground line-clamp-1">
+                  {topic.preview}
+                </p>
+              )}
+              <div className="flex items-center gap-3 mt-1.5 text-xs text-muted-foreground">
+                <span>{topic.author.displayName}</span>
+                <span>{formatTimestamp(topic.createdAt)}</span>
+                <Badge variant="muted" className="gap-0.5 text-xs px-1.5 py-0">
+                  <MessageSquare className="size-3" />
+                  {topic.replyCount}
+                </Badge>
+                <Badge variant="muted" className="gap-0.5 text-xs px-1.5 py-0">
+                  <Heart className="size-3" />
+                  {topic.likeCount}
+                </Badge>
+              </div>
+            </div>
+          </div>
+        </CardContent>
+      </Card>
+    </button>
+  );
+}

package/src/sections/ForumBoard/types.ts

@@ -0,0 +1,81 @@
+import type { DiscussionUser } from "../DiscussionThread/types";
+
+export type ForumSortOrder = "newest" | "oldest" | "most_replies" | "most_liked";
+
+/**
+ * ForumBoard section — a topic listing view for a discussion forum.
+ *
+ * Displays a searchable, sortable list of discussion topics with author info,
+ * reply/like counts, and timestamps. Supports creating new topics inline.
+ *
+ * @example
+ * <ForumBoard
+ *   title="Class Discussion"
+ *   topics={topics}
+ *   onTopicClick={(uid) => openThread(uid)}
+ *   onCreateTopic={(title, content) => createTopic(title, content)}
+ * />
+ */
+export interface ForumBoardProps {
+  /** Forum title */
+  title?: string;
+  /** List of discussion topics */
+  topics: ForumTopic[];
+  /** The currently authenticated user (reserved for future use) */
+  currentUser?: DiscussionUser;
+  /** Called when a topic is clicked */
+  onTopicClick: (topicUid: string) => void;
+  /** Called when a new topic is created */
+  onCreateTopic?: (title: string, content: string) => void;
+  /** Current sort order */
+  sortOrder?: ForumSortOrder;
+  /** Called when sort order changes */
+  onSortChange?: (sort: ForumSortOrder) => void;
+  /** Current search query (controlled) */
+  searchQuery?: string;
+  /** Called when search query changes */
+  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 */
+  style?: React.CSSProperties;
+}
+
+export interface ForumTopic {
+  /** Unique identifier */
+  uid: string;
+  /** Topic title */
+  title: string;
+  /** Topic author */
+  author: DiscussionUser;
+  /** Creation timestamp */
+  createdAt: string;
+  /** Number of replies */
+  replyCount: number;
+  /** Number of likes */
+  likeCount: number;
+  /** Timestamp of the most recent reply */
+  lastReplyAt?: string;
+  /** Whether this topic is pinned to the top */
+  isPinned?: boolean;
+  /** Whether this topic has a marked answer */
+  isAnswered?: boolean;
+  /** Preview text (first ~100 chars of content) */
+  preview?: string;
+}

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 */}
@@ -169,7 +213,7 @@ export function GradebookTable({
           </TableHeader>
           <TableBody>
             {grouped.map((group, gi) => (
-              <Fragment key={gi}>
+              <Fragment key={group.category?.uid ?? `ungrouped-${gi}`}>
                 {group.category && showCategoryTotals && (
                   <TableRow className="bg-muted hover:bg-muted">
                     <TableCell colSpan={colCount}>
@@ -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 */