@hydralms/components 0.1.0 → 0.1.2

package/src/sections/ExamSession/ExamSession.tsx

@@ -0,0 +1,182 @@
+import { useEffect, useMemo, useRef, useState } from "react";
+import { AssessmentToolbar } 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 { cn } from "../../lib/utils";
+import type { ExamSessionProps, ExamSubmitMetadata } from "./types";
+
+export function ExamSession({
+  questions,
+  initialAnswers = [],
+  onSubmit,
+  onAnswerChange,
+  timeLimitSeconds,
+  timeElapsedSeconds,
+  autoSubmitOnTimeout = true,
+  timeWarningThreshold = 300,
+  allowBackNavigation = true,
+  confirmBeforeSubmit = true,
+  examTitle,
+  instructions,
+  isSubmitting = false,
+  readOnly = false,
+  className,
+  style,
+}: ExamSessionProps) {
+  const [currentIndex, setCurrentIndex] = useState(0);
+  const [sessionAnswers, setSessionAnswers] = useState<SessionAnswer[]>(initialAnswers);
+  const [flaggedUids, setFlaggedUids] = useState<Set<string>>(new Set());
+  const [showConfirm, setShowConfirm] = useState(false);
+  const [showTimeWarning, setShowTimeWarning] = useState(false);
+  const hasAutoSubmitted = useRef(false);
+
+  const currentQuestion = questions[currentIndex];
+  const remainingSeconds = timeLimitSeconds - timeElapsedSeconds;
+
+  useEffect(() => {
+    if (remainingSeconds <= timeWarningThreshold && remainingSeconds > 0) {
+      setShowTimeWarning(true);
+    }
+  }, [remainingSeconds, timeWarningThreshold]);
+
+  useEffect(() => {
+    if (autoSubmitOnTimeout && remainingSeconds <= 0 && !hasAutoSubmitted.current) {
+      hasAutoSubmitted.current = true;
+      doSubmit(true);
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [remainingSeconds, autoSubmitOnTimeout]);
+
+  const navigatorItems = useMemo<QuestionNavigatorItem[]>(
+    () =>
+      questions.map((q, idx) => ({
+        uid: q.uid,
+        sequence: idx + 1,
+        isFlagged: flaggedUids.has(q.uid),
+        isAnswered: sessionAnswers.some((a) => a.uid === q.uid),
+        isSkipped: false,
+      })),
+    [questions, sessionAnswers, flaggedUids],
+  );
+
+  function handleAnswer(rawAnswers: { uid: string; content?: string }[]) {
+    if (!currentQuestion) return;
+    const questionUid = currentQuestion.uid;
+    const newAnswers: SessionAnswer[] = rawAnswers.map((a) => ({
+      uid: questionUid,
+      answerUid: a.uid,
+      content: a.content,
+    }));
+    setSessionAnswers((prev) => {
+      const filtered = prev.filter((a) => a.uid !== questionUid);
+      const merged = [...filtered, ...newAnswers];
+      onAnswerChange?.(merged);
+      return merged;
+    });
+  }
+
+  function handleNavigate(uid: string) {
+    const idx = questions.findIndex((q) => q.uid === uid);
+    if (idx !== -1) setCurrentIndex(idx);
+  }
+
+  function handleToggleFlag(uid: string) {
+    setFlaggedUids((prev) => {
+      const next = new Set(prev);
+      if (next.has(uid)) next.delete(uid);
+      else next.add(uid);
+      return next;
+    });
+  }
+
+  function handleSubmitClick() {
+    if (confirmBeforeSubmit) {
+      setShowConfirm(true);
+    } else {
+      doSubmit(false);
+    }
+  }
+
+  function doSubmit(wasAutoSubmitted: boolean) {
+    const answeredUids = new Set(sessionAnswers.map((a) => a.uid));
+    const metadata: ExamSubmitMetadata = {
+      timeElapsedSeconds,
+      wasAutoSubmitted,
+      answeredCount: questions.filter((q) => answeredUids.has(q.uid)).length,
+      totalQuestions: questions.length,
+    };
+    onSubmit(sessionAnswers, metadata);
+  }
+
+  return (
+    <div className={cn(className)} style={style}>
+      {examTitle && (
+        <p className="text-xl font-bold mb-2 text-foreground">{examTitle}</p>
+      )}
+
+      {showTimeWarning && remainingSeconds > 0 && remainingSeconds <= timeWarningThreshold && (
+        <Alert variant="warning" className="mb-2">
+          <AlertDescription>
+            {Math.ceil(remainingSeconds / 60)} minute{Math.ceil(remainingSeconds / 60) !== 1 ? "s" : ""} remaining
+          </AlertDescription>
+        </Alert>
+      )}
+
+      <AssessmentToolbar
+        currentQuestionIndex={currentIndex}
+        totalQuestions={questions.length}
+        hasNext={currentIndex < questions.length - 1}
+        hasPrevious={allowBackNavigation && currentIndex > 0}
+        onNext={() => setCurrentIndex((i) => Math.min(i + 1, questions.length - 1))}
+        onPrevious={() => allowBackNavigation && setCurrentIndex((i) => Math.max(i - 1, 0))}
+        onSubmit={handleSubmitClick}
+        timeElapsedSeconds={timeElapsedSeconds}
+        timeLimitSeconds={timeLimitSeconds}
+        questions={navigatorItems}
+        onNavigateToQuestion={handleNavigate}
+        onToggleFlag={handleToggleFlag}
+        currentQuestionUid={currentQuestion?.uid}
+        isSubmitting={isSubmitting}
+        readOnly={readOnly}
+      />
+
+      {instructions && currentIndex === 0 && (
+        <Card className="mt-3">
+          <CardContent className="pt-6">{instructions}</CardContent>
+        </Card>
+      )}
+
+      {currentQuestion && (
+        <Card className="mt-3">
+          <CardContent className="pt-6">
+            <QuestionRenderer
+              question={currentQuestion}
+              sessionAnswers={sessionAnswers.filter((a) => a.uid === currentQuestion.uid)}
+              onAnswer={handleAnswer}
+              readOnly={readOnly}
+            />
+          </CardContent>
+        </Card>
+      )}
+
+      <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.`}
+        confirmLabel="Submit Exam"
+        cancelLabel="Continue Exam"
+        confirmColor="primary"
+        onConfirm={() => {
+          setShowConfirm(false);
+          doSubmit(false);
+        }}
+        onCancel={() => setShowConfirm(false)}
+        isLoading={isSubmitting}
+      />
+    </div>
+  );
+}

package/src/sections/ExamSession/types.ts

@@ -0,0 +1,64 @@
+import type { ReactNode } from "react";
+import type { QuestionData, SessionAnswer } from "../../questions/types";
+
+/**
+ * ExamSession section — a formal timed exam experience.
+ *
+ * Provides enforced time limits with auto-submit on timeout, time warnings,
+ * optional back-navigation restriction, and a confirmation dialog before
+ * final submission.
+ *
+ * @example
+ * <ExamSession
+ *   questions={questions}
+ *   timeLimitSeconds={3600}
+ *   timeElapsedSeconds={elapsed}
+ *   onSubmit={(answers, meta) => submitExam(answers, meta)}
+ *   examTitle="Final Exam"
+ * />
+ */
+export interface ExamSessionProps {
+  /** Ordered list of questions */
+  questions: QuestionData[];
+  /** Pre-populated answers for resuming */
+  initialAnswers?: SessionAnswer[];
+  /** Called on submission with answers and metadata */
+  onSubmit: (answers: SessionAnswer[], metadata: ExamSubmitMetadata) => void;
+  /** Called whenever the user changes an answer */
+  onAnswerChange?: (answers: SessionAnswer[]) => void;
+  /** Time limit in seconds (required for exam mode) */
+  timeLimitSeconds: number;
+  /** Current elapsed time in seconds (controlled externally) */
+  timeElapsedSeconds: number;
+  /** Auto-submit when time runs out */
+  autoSubmitOnTimeout?: boolean;
+  /** Seconds remaining at which to show a time warning */
+  timeWarningThreshold?: number;
+  /** Whether the user can go back to previous questions */
+  allowBackNavigation?: boolean;
+  /** Show a confirmation dialog before final submission */
+  confirmBeforeSubmit?: boolean;
+  /** Title shown in the exam header */
+  examTitle?: string;
+  /** Instructions displayed above the first question */
+  instructions?: ReactNode;
+  /** Whether the submit action is in flight */
+  isSubmitting?: boolean;
+  /** When true, all inputs are disabled */
+  readOnly?: boolean;
+  /** CSS class name for the root element */
+  className?: string;
+  /** Inline styles for the root element */
+  style?: React.CSSProperties;
+}
+
+export interface ExamSubmitMetadata {
+  /** Total time the user spent in seconds */
+  timeElapsedSeconds: number;
+  /** Whether the submission was triggered by timeout */
+  wasAutoSubmitted: boolean;
+  /** Number of questions the user answered */
+  answeredCount: number;
+  /** Total questions in the exam */
+  totalQuestions: number;
+}

package/src/sections/FlashcardStudySession/FlashcardStudySession.tsx

@@ -0,0 +1,76 @@
+import { useState } from "react";
+import { CheckCircle } from "lucide-react";
+import { FlashcardDeck } from "../../flashcards";
+import { Button } from "../../ui/button";
+import { Card, CardContent } from "../../ui/card";
+import type {
+  FlashcardStudySessionProps,
+  FlashcardSessionStats,
+} from "./types";
+import { cn } from "../../lib/utils";
+
+export function FlashcardStudySession({
+  cards,
+  title,
+  description,
+  shuffled = false,
+  onComplete,
+  readOnly = false,
+  className,
+  style,
+}: FlashcardStudySessionProps) {
+  const [isComplete, setIsComplete] = useState(false);
+
+  const stats: FlashcardSessionStats = {
+    totalCards: cards.length,
+    wasShuffled: shuffled,
+  };
+
+  function handleComplete() {
+    setIsComplete(true);
+    onComplete?.(stats);
+  }
+
+  function handleStudyAgain() {
+    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>
+  );
+}

package/src/sections/FlashcardStudySession/types.ts

@@ -0,0 +1,42 @@
+import type { FlashcardData } from "../../flashcards/types";
+
+/**
+ * FlashcardStudySession section — a complete flashcard study experience.
+ *
+ * Wraps FlashcardDeck with a session header and a completion screen
+ * (checkmark, stats, "Study Again" button). Drop in your cards and an
+ * optional onComplete callback to get a ready-to-use study session.
+ *
+ * @example
+ * <FlashcardStudySession
+ *   cards={cards}
+ *   title="React Fundamentals"
+ *   shuffled
+ *   onComplete={(stats) => trackStudySession(stats)}
+ * />
+ */
+export interface FlashcardStudySessionProps {
+  /** The cards to study */
+  cards: FlashcardData[];
+  /** Session title displayed in the header */
+  title?: string;
+  /** Optional subtitle / description */
+  description?: string;
+  /** Whether to shuffle cards at session start — passed through to FlashcardDeck */
+  shuffled?: boolean;
+  /** Called when the user completes the deck */
+  onComplete?: (stats: FlashcardSessionStats) => void;
+  /** When true, disables card flipping */
+  readOnly?: boolean;
+  /** CSS class name for the root element */
+  className?: string;
+  /** Inline styles for the root element */
+  style?: React.CSSProperties;
+}
+
+export interface FlashcardSessionStats {
+  /** Total number of cards in the deck */
+  totalCards: number;
+  /** Whether the deck was shuffled */
+  wasShuffled: boolean;
+}

package/src/sections/GradebookTable/GradebookTable.tsx

@@ -0,0 +1,229 @@
+import { Fragment, useMemo, useState } from "react";
+import { ArrowUp, ArrowDown } 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 type { GradebookTableProps, GradeCategory } from "./types";
+import { cn } from "../../lib/utils";
+
+type SortField = "name" | "score" | "dueDate" | "status";
+
+function SortableHeader({
+  label,
+  field,
+  sortField,
+  sortDir,
+  onSort,
+  textAlign,
+}: {
+  label: string;
+  field: SortField;
+  sortField: SortField;
+  sortDir: "asc" | "desc";
+  onSort: (field: SortField) => void;
+  textAlign?: "left" | "right";
+}) {
+  const isActive = sortField === field;
+  return (
+    <TableHead
+      className={cn(
+        "cursor-pointer select-none hover:bg-muted",
+        textAlign === "right" && "text-right",
+      )}
+      onClick={() => onSort(field)}
+    >
+      <div className={cn("flex items-center gap-1", textAlign === "right" && "justify-end")}>
+        <span className={cn(isActive ? "text-foreground" : "text-muted-foreground")}>
+          {label}
+        </span>
+        {isActive && (
+          sortDir === "asc" ? <ArrowUp size={14} /> : <ArrowDown size={14} />
+        )}
+      </div>
+    </TableHead>
+  );
+}
+
+export function GradebookTable({
+  items,
+  categories,
+  overallGrade,
+  showWeights = true,
+  showCategoryTotals = true,
+  onItemClick,
+  readOnly = false,
+  className,
+  style,
+}: GradebookTableProps) {
+  const [sortField, setSortField] = useState<SortField>("dueDate");
+  const [sortDir, setSortDir] = useState<"asc" | "desc">("asc");
+
+  function handleSort(field: SortField) {
+    if (sortField === field) {
+      setSortDir((d) => (d === "asc" ? "desc" : "asc"));
+    } else {
+      setSortField(field);
+      setSortDir("asc");
+    }
+  }
+
+  const sortedItems = useMemo(() => {
+    const copy = [...items];
+    copy.sort((a, b) => {
+      let cmp = 0;
+      switch (sortField) {
+        case "name":
+          cmp = a.name.localeCompare(b.name);
+          break;
+        case "score":
+          cmp = (a.score ?? -1) - (b.score ?? -1);
+          break;
+        case "dueDate":
+          cmp = (a.dueDate ?? "").localeCompare(b.dueDate ?? "");
+          break;
+        case "status":
+          cmp = a.status.localeCompare(b.status);
+          break;
+      }
+      return sortDir === "asc" ? cmp : -cmp;
+    });
+    return copy;
+  }, [items, sortField, sortDir]);
+
+  const grouped = useMemo<{ category: GradeCategory | null; items: typeof sortedItems }[]>(() => {
+    if (!categories || categories.length === 0) return [{ category: null, items: sortedItems }];
+    const groups: { category: GradeCategory | null; items: typeof sortedItems }[] = categories.map((cat) => ({
+      category: cat,
+      items: sortedItems.filter((item) => item.categoryUid === cat.uid),
+    }));
+    const ungrouped = sortedItems.filter((item) => !item.categoryUid);
+    if (ungrouped.length > 0) groups.push({ category: null, items: ungrouped });
+    return groups;
+  }, [sortedItems, categories]);
+
+  const colCount = showWeights ? 5 : 4;
+
+  return (
+    <div className={className} style={style}>
+      {/* Overall grade */}
+      {overallGrade && (
+        <Card className="mb-3">
+          <CardContent className="pt-6">
+            <div className="flex items-center gap-3">
+              <GradeIndicator
+                percentage={overallGrade.percentage}
+                letterGrade={overallGrade.letterGrade}
+                size="large"
+                passingThreshold={60}
+              />
+              <div>
+                <div className="text-lg font-semibold text-foreground">Overall Grade</div>
+                <span className="text-sm text-muted-foreground">
+                  {overallGrade.pointsEarned} / {overallGrade.pointsPossible} points
+                </span>
+              </div>
+            </div>
+          </CardContent>
+        </Card>
+      )}
+
+      {/* Table */}
+      <Card>
+        <Table>
+          <TableHeader>
+            <TableRow>
+              <SortableHeader
+                label="Assignment"
+                field="name"
+                sortField={sortField}
+                sortDir={sortDir}
+                onSort={handleSort}
+              />
+              <SortableHeader
+                label="Status"
+                field="status"
+                sortField={sortField}
+                sortDir={sortDir}
+                onSort={handleSort}
+              />
+              <SortableHeader
+                label="Due Date"
+                field="dueDate"
+                sortField={sortField}
+                sortDir={sortDir}
+                onSort={handleSort}
+              />
+              <SortableHeader
+                label="Score"
+                field="score"
+                sortField={sortField}
+                sortDir={sortDir}
+                onSort={handleSort}
+                textAlign="right"
+              />
+              {showWeights && (
+                <TableHead className="text-right text-muted-foreground">Weight</TableHead>
+              )}
+            </TableRow>
+          </TableHeader>
+          <TableBody>
+            {grouped.map((group, gi) => (
+              <Fragment key={gi}>
+                {group.category && showCategoryTotals && (
+                  <TableRow className="bg-muted hover:bg-muted">
+                    <TableCell colSpan={colCount}>
+                      <span className="font-semibold text-sm text-foreground">
+                        {group.category.name}
+                        {group.category.weight != null && ` (${group.category.weight}%)`}
+                      </span>
+                    </TableCell>
+                  </TableRow>
+                )}
+                {group.items.map((item) => (
+                  <TableRow
+                    key={item.uid}
+                    className={cn(onItemClick && !readOnly && "cursor-pointer")}
+                    onClick={() => onItemClick && !readOnly ? onItemClick(item) : undefined}
+                  >
+                    <TableCell>{item.name}</TableCell>
+                    <TableCell>
+                      <StatusBadge status={item.status} size="small" />
+                    </TableCell>
+                    <TableCell>
+                      {item.dueDate ? (
+                        <DueDateDisplay
+                          dueDate={item.dueDate}
+                          submittedDate={item.submittedDate}
+                          size="small"
+                        />
+                      ) : (
+                        "\u2014"
+                      )}
+                    </TableCell>
+                    <TableCell className="text-right">
+                      {item.score != null ? (
+                        <span className="text-sm font-semibold text-foreground">
+                          {item.score} / {item.maxScore}
+                        </span>
+                      ) : item.status === "excused" ? (
+                        <span className="text-sm text-muted-foreground">Excused</span>
+                      ) : (
+                        <span className="text-sm text-muted-foreground">{"\u2014"}</span>
+                      )}
+                    </TableCell>
+                    {showWeights && (
+                      <TableCell className="text-right">
+                        {item.weight != null ? `${item.weight}%` : "\u2014"}
+                      </TableCell>
+                    )}
+                  </TableRow>
+                ))}
+              </Fragment>
+            ))}
+          </TableBody>
+        </Table>
+      </Card>
+    </div>
+  );
+}

package/src/sections/GradebookTable/types.ts

@@ -0,0 +1,75 @@
+
+/**
+ * GradebookTable section — a tabular student gradebook.
+ *
+ * Displays assignment scores, weights, and an overall computed grade
+ * with sortable columns and optional category grouping.
+ *
+ * @example
+ * <GradebookTable
+ *   items={gradeItems}
+ *   categories={gradeCategories}
+ *   overallGrade={{ percentage: 87, letterGrade: "B+", pointsEarned: 435, pointsPossible: 500 }}
+ * />
+ */
+export interface GradebookTableProps {
+  /** Grade items (assignments, quizzes, etc.) */
+  items: GradeItem[];
+  /** Optional category grouping */
+  categories?: GradeCategory[];
+  /** Overall course grade summary */
+  overallGrade?: OverallGrade;
+  /** Whether to show the weight column */
+  showWeights?: boolean;
+  /** Whether to show category subtotals */
+  showCategoryTotals?: boolean;
+  /** Called when the user clicks a grade item row */
+  onItemClick?: (item: GradeItem) => void;
+  /** When true, disables interactions */
+  readOnly?: boolean;
+  /** CSS class name for the root element */
+  className?: string;
+  /** Inline styles for the root element */
+  style?: React.CSSProperties;
+}
+
+export interface GradeItem {
+  /** Unique identifier */
+  uid: string;
+  /** Assignment name */
+  name: string;
+  /** Category UID for grouping */
+  categoryUid?: string;
+  /** Score earned — null if not yet graded */
+  score: number | null;
+  /** Maximum possible score */
+  maxScore: number;
+  /** Weight as a percentage */
+  weight?: number;
+  /** Due date as ISO string */
+  dueDate?: string;
+  /** Submission date */
+  submittedDate?: string;
+  /** Item status */
+  status: "graded" | "submitted" | "pending" | "missing" | "excused";
+}
+
+export interface GradeCategory {
+  /** Unique identifier */
+  uid: string;
+  /** Category name (e.g. "Assignments", "Quizzes") */
+  name: string;
+  /** Category weight percentage */
+  weight?: number;
+}
+
+export interface OverallGrade {
+  /** Overall percentage */
+  percentage: number;
+  /** Letter grade */
+  letterGrade?: string;
+  /** Points earned */
+  pointsEarned: number;
+  /** Points possible */
+  pointsPossible: number;
+}