@hydralms/components 0.1.3 → 0.2.0

package/src/sections/ExamSession/ExamSession.tsx

@@ -1,11 +1,11 @@
 import { useEffect, useMemo, useRef, useState } from "react";
-import { AssessmentToolbar } from "../../assessment-toolbar";
+import { AssessmentToolbar, QuestionHeaderBar, QuestionMaterialsDrawer } from "../../assessment-toolbar";
 import type { QuestionNavigatorItem } from "../../assessment-toolbar/types";
 import { QuestionRenderer } from "../../questions";
 import type { SessionAnswer } from "../../questions/types";
 import { ConfirmDialog } from "../../common";
 import { Alert, AlertDescription } from "../../ui/alert";
-import { Card, CardContent } from "../../ui/card";
+import { Card, CardHeader, CardContent } from "../../ui/card";
 import { cn } from "../../lib/utils";
 import type { ExamSessionProps, ExamSubmitMetadata } from "./types";
 
@@ -22,6 +22,7 @@ export function ExamSession({
   confirmBeforeSubmit = true,
   examTitle,
   instructions,
+  questionMaterials,
   isSubmitting = false,
   readOnly = false,
   className,
@@ -32,11 +33,25 @@ export function ExamSession({
   const [flaggedUids, setFlaggedUids] = useState<Set<string>>(new Set());
   const [showConfirm, setShowConfirm] = useState(false);
   const [showTimeWarning, setShowTimeWarning] = useState(false);
+  const [materialsOpen, setMaterialsOpen] = useState(false);
   const hasAutoSubmitted = useRef(false);
 
   const currentQuestion = questions[currentIndex];
   const remainingSeconds = timeLimitSeconds - timeElapsedSeconds;
 
+  const currentQuestionAnswers = useMemo(
+    () =>
+      currentQuestion
+        ? sessionAnswers.filter((a) => a.uid === currentQuestion.uid)
+        : [],
+    [sessionAnswers, currentQuestion],
+  );
+
+  const currentMaterials = useMemo(
+    () => questionMaterials?.filter((m) => m.questionUid === currentQuestion?.uid) ?? [],
+    [questionMaterials, currentQuestion],
+  );
+
   useEffect(() => {
     if (remainingSeconds <= timeWarningThreshold && remainingSeconds > 0) {
       setShowTimeWarning(true);
@@ -55,7 +70,7 @@ export function ExamSession({
     () =>
       questions.map((q, idx) => ({
         uid: q.uid,
-        sequence: idx + 1,
+        sequence: idx,
         isFlagged: flaggedUids.has(q.uid),
         isAnswered: sessionAnswers.some((a) => a.uid === q.uid),
         isSkipped: false,
@@ -63,6 +78,11 @@ export function ExamSession({
     [questions, sessionAnswers, flaggedUids],
   );
 
+  const answeredCount = useMemo(
+    () => navigatorItems.filter((q) => q.isAnswered).length,
+    [navigatorItems],
+  );
+
   function handleAnswer(rawAnswers: { uid: string; content?: string }[]) {
     if (!currentQuestion) return;
     const questionUid = currentQuestion.uid;
@@ -138,7 +158,6 @@ export function ExamSession({
         timeLimitSeconds={timeLimitSeconds}
         questions={navigatorItems}
         onNavigateToQuestion={handleNavigate}
-        onToggleFlag={handleToggleFlag}
         currentQuestionUid={currentQuestion?.uid}
         isSubmitting={isSubmitting}
         readOnly={readOnly}
@@ -152,10 +171,21 @@ export function ExamSession({
 
       {currentQuestion && (
         <Card className="mt-3">
-          <CardContent className="pt-6">
+          <CardHeader className="pb-0">
+            <QuestionHeaderBar
+              questionNumber={currentIndex + 1}
+              totalQuestions={questions.length}
+              isFlagged={flaggedUids.has(currentQuestion.uid)}
+              onToggleFlag={() => handleToggleFlag(currentQuestion.uid)}
+              hasMaterials={currentMaterials.length > 0}
+              onOpenMaterials={() => setMaterialsOpen(true)}
+              readOnly={readOnly}
+            />
+          </CardHeader>
+          <CardContent>
             <QuestionRenderer
               question={currentQuestion}
-              sessionAnswers={sessionAnswers.filter((a) => a.uid === currentQuestion.uid)}
+              sessionAnswers={currentQuestionAnswers}
               onAnswer={handleAnswer}
               readOnly={readOnly}
             />
@@ -163,10 +193,17 @@ export function ExamSession({
         </Card>
       )}
 
+      <QuestionMaterialsDrawer
+        open={materialsOpen}
+        onOpenChange={setMaterialsOpen}
+        materials={currentMaterials}
+        questionNumber={currentIndex + 1}
+      />
+
       <ConfirmDialog
         open={showConfirm}
         title="Submit Exam?"
-        message={`You have answered ${navigatorItems.filter((q) => q.isAnswered).length} of ${questions.length} questions. Once submitted, you cannot change your answers.`}
+        message={`You have answered ${answeredCount} of ${questions.length} questions. Once submitted, you cannot change your answers.`}
         confirmLabel="Submit Exam"
         cancelLabel="Continue Exam"
         confirmColor="primary"

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,6 +44,11 @@ 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;
   /** CSS class name for the root element */

package/src/sections/ForumBoard/ForumBoard.tsx

@@ -0,0 +1,284 @@
+import { useState, useMemo } from "react";
+import {
+  Plus,
+  MessageSquare,
+  Heart,
+  Pin,
+  CheckCircle2,
+  ArrowUpDown,
+} from "lucide-react";
+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 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,
+  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]);
+
+  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">
+          {sorted.map((topic) => (
+            <TopicRow
+              key={topic.uid}
+              topic={topic}
+              onClick={() => onTopicClick(topic.uid)}
+            />
+          ))}
+        </div>
+      )}
+    </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,67 @@
+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;
+  /** 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

@@ -169,7 +169,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}>

package/src/sections/LecturePlayer/LecturePlayer.tsx

@@ -25,7 +25,7 @@ export function LecturePlayer({
   return (
     <div
       className={cn(
-        "flex overflow-hidden",
+        "flex overflow-hidden gap-4",
         isHorizontal ? "flex-row" : "flex-col",
         className,
       )}

package/src/sections/LessonPage/LessonPage.tsx

@@ -1,8 +1,8 @@
 import { useState } from "react";
 import { Check, ChevronRight, Clock } from "lucide-react";
 import { ContentBlock } from "../../content";
-import type { SessionAnswer } from "../../questions/types";
 import { Button } from "../../ui/button";
+import { Card, CardContent } from "../../ui/card";
 import { Separator } from "../../ui/separator";
 import { formatDuration } from "../../utils/format-duration";
 import type { LessonPageProps } from "./types";
@@ -22,11 +22,6 @@ export function LessonPage({
   style,
 }: LessonPageProps) {
   const [completed, setCompleted] = useState(isCompleted);
-  const [, setQuestionAnswers] = useState<Map<string, SessionAnswer[]>>(new Map());
-
-  function handleQuestionAnswer(questionUid: string, answers: SessionAnswer[]) {
-    setQuestionAnswers((prev) => new Map(prev).set(questionUid, answers));
-  }
 
   function handleMarkComplete() {
     setCompleted(true);
@@ -54,14 +49,14 @@ export function LessonPage({
           <ContentBlock
             key={i}
             block={block}
-            onQuestionAnswer={handleQuestionAnswer}
             readOnly={readOnly}
           />
         ))}
       </div>
 
       {/* Completion bar */}
-      <div className="border border-border rounded-md px-4 py-3 mt-4 sticky bottom-0 bg-background z-10">
+      <Card className="mt-4 sticky bottom-0 z-10">
+        <CardContent className="px-4 py-3">
         <div className="flex justify-between items-center">
           {completed ? (
             <div className="flex items-center gap-1 text-success">
@@ -85,7 +80,8 @@ export function LessonPage({
             </Button>
           )}
         </div>
-      </div>
+        </CardContent>
+      </Card>
     </div>
   );
 }

package/src/sections/PracticeQuiz/PracticeQuiz.tsx

@@ -1,20 +1,12 @@
 import { useMemo, useState } from "react";
 import { CheckCircle } from "lucide-react";
-import { QuestionRenderer } from "../../questions";
+import { QuestionRenderer, scoreQuestion } from "../../questions";
 import { FeedbackBanner } from "../../feedback";
 import { Button } from "../../ui/button";
 import { Card, CardContent } from "../../ui/card";
 import { Progress } from "../../ui/progress";
 import type { PracticeQuizProps, PracticeQuizStats } from "./types";
-
-function shuffleArray<T>(arr: T[]): T[] {
-  const copy = [...arr];
-  for (let i = copy.length - 1; i > 0; i--) {
-    const j = Math.floor(Math.random() * (i + 1));
-    [copy[i], copy[j]] = [copy[j], copy[i]];
-  }
-  return copy;
-}
+import { shuffle } from "../../utils/shuffle";
 
 export function PracticeQuiz({
   questions: questionsProp,
@@ -27,7 +19,7 @@ export function PracticeQuiz({
   style,
 }: PracticeQuizProps) {
   const questions = useMemo(
-    () => (shuffled ? shuffleArray(questionsProp) : questionsProp),
+    () => (shuffled ? shuffle(questionsProp) : questionsProp),
     // eslint-disable-next-line react-hooks/exhaustive-deps
     [questionsProp, shuffled],
   );
@@ -49,13 +41,12 @@ export function PracticeQuiz({
     setAttemptCounts((prev) => new Map(prev).set(currentQuestion.uid, attempts));
     setRevealedUids((prev) => new Set(prev).add(currentQuestion.uid));
 
-    const correctUids = new Set(
-      currentQuestion.answers?.filter((a) => a.isCorrect).map((a) => a.uid) ?? [],
-    );
-    const selectedUids = new Set(currentAnswer.map((a) => a.uid));
-    const isCorrect =
-      correctUids.size === selectedUids.size &&
-      [...correctUids].every((uid) => selectedUids.has(uid));
+    const sessionAnswers = currentAnswer.map((a) => ({
+      uid: currentQuestion.uid,
+      answerUid: a.uid,
+      content: a.content,
+    }));
+    const isCorrect = scoreQuestion(currentQuestion, sessionAnswers) === true;
 
     if (isCorrect && attempts === 1) {
       setFirstAttemptCorrect((prev) => new Set(prev).add(currentQuestion.uid));
@@ -89,14 +80,12 @@ export function PracticeQuiz({
 
   const isCurrentCorrect = useMemo(() => {
     if (!currentQuestion || !currentAnswer) return false;
-    const correctUids = new Set(
-      currentQuestion.answers?.filter((a) => a.isCorrect).map((a) => a.uid) ?? [],
-    );
-    const selectedUids = new Set(currentAnswer.map((a) => a.uid));
-    return (
-      correctUids.size === selectedUids.size &&
-      [...correctUids].every((uid) => selectedUids.has(uid))
-    );
+    const sessionAnswers = currentAnswer.map((a) => ({
+      uid: currentQuestion.uid,
+      answerUid: a.uid,
+      content: a.content,
+    }));
+    return scoreQuestion(currentQuestion, sessionAnswers) === true;
   }, [currentQuestion, currentAnswer]);
 
   if (isComplete) {