@hydralms/components 0.1.1 → 0.1.3

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;
+}

package/src/sections/LecturePlayer/LecturePlayer.tsx

@@ -0,0 +1,60 @@
+import { VideoPlayer } from "../../video";
+import { Card, CardHeader, CardTitle, CardContent } from "../../ui/card";
+import type { LecturePlayerProps } from "./types";
+import { cn } from "../../lib/utils";
+
+export function LecturePlayer({
+  video,
+  notes,
+  layout = "horizontal",
+  notesPanelWidth = "340px",
+  notesPanelHeight = "240px",
+  className,
+  style,
+}: LecturePlayerProps) {
+  const isHorizontal = layout === "horizontal";
+
+  if (!notes) {
+    return (
+      <div className={className} style={style}>
+        <VideoPlayer {...video} />
+      </div>
+    );
+  }
+
+  return (
+    <div
+      className={cn(
+        "flex overflow-hidden",
+        isHorizontal ? "flex-row" : "flex-col",
+        className,
+      )}
+      style={style}
+    >
+      <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
+          )}
+        </CardContent>
+      </Card>
+    </div>
+  );
+}

package/src/sections/LecturePlayer/types.ts

@@ -0,0 +1,48 @@
+import type { ReactNode } from "react";
+import type { VideoPlayerProps } from "../../video/types";
+
+/**
+ * LecturePlayer section — video player paired with an optional notes/transcript panel.
+ *
+ * Supports horizontal (side-by-side) and vertical (stacked) layouts with
+ * configurable panel dimensions. When notes are omitted, the video fills
+ * the full container.
+ *
+ * @example
+ * <LecturePlayer
+ *   video={{ src: "https://example.com/lecture.mp4", title: "React Hooks" }}
+ *   notes={<TranscriptPanel />}
+ *   layout="horizontal"
+ * />
+ */
+export interface LecturePlayerProps {
+  /** Props passed directly to the underlying VideoPlayer */
+  video: VideoPlayerProps;
+  /**
+   * Content rendered in the companion panel.
+   * Can be any ReactNode — transcript, MDX, note editor, etc.
+   * If omitted, the player fills the full container with no panel.
+   */
+  notes?: ReactNode;
+  /**
+   * Layout direction of the two-pane split.
+   * - "horizontal": video left, notes right
+   * - "vertical": video top, notes bottom
+   * @default "horizontal"
+   */
+  layout?: "horizontal" | "vertical";
+  /**
+   * Width of the notes panel when layout is "horizontal".
+   * @default "340px"
+   */
+  notesPanelWidth?: string | number;
+  /**
+   * Height of the notes panel when layout is "vertical".
+   * @default "240px"
+   */
+  notesPanelHeight?: string | number;
+  /** CSS class name for the root element */
+  className?: string;
+  /** Inline styles for the root element */
+  style?: React.CSSProperties;
+}

package/src/sections/LessonPage/LessonPage.tsx

@@ -0,0 +1,91 @@
+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 { Separator } from "../../ui/separator";
+import { formatDuration } from "../../utils/format-duration";
+import type { LessonPageProps } from "./types";
+import { cn } from "../../lib/utils";
+
+export function LessonPage({
+  title,
+  blocks,
+  isCompleted = false,
+  onMarkComplete,
+  onNextLesson,
+  nextLessonTitle,
+  estimatedDuration,
+  showDuration = true,
+  readOnly = false,
+  className,
+  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);
+    onMarkComplete?.();
+  }
+
+  return (
+    <div className={cn(className)} style={style}>
+      {/* Header */}
+      <div className="mb-3">
+        <p className="text-2xl font-bold mb-0.5 text-foreground">{title}</p>
+        {showDuration && estimatedDuration != null && (
+          <div className="flex items-center gap-0.5 text-muted-foreground">
+            <Clock size={16} />
+            <span className="text-sm">{formatDuration(estimatedDuration)}</span>
+          </div>
+        )}
+      </div>
+
+      <Separator className="mb-3" />
+
+      {/* Content blocks */}
+      <div className="flex flex-col gap-3">
+        {blocks.map((block, i) => (
+          <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">
+        <div className="flex justify-between items-center">
+          {completed ? (
+            <div className="flex items-center gap-1 text-success">
+              <Check size={20} />
+              <span className="text-sm font-semibold">Lesson Complete</span>
+            </div>
+          ) : (
+            <Button
+              onClick={handleMarkComplete}
+              disabled={readOnly}
+            >
+              <Check size={18} /> Mark Complete
+            </Button>
+          )}
+          {onNextLesson && (
+            <Button
+              variant={completed ? "default" : "outline"}
+              onClick={onNextLesson}
+            >
+              {nextLessonTitle ? `Next: ${nextLessonTitle}` : "Next Lesson"} <ChevronRight size={18} />
+            </Button>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/sections/LessonPage/types.ts

@@ -0,0 +1,41 @@
+import type { LessonBlock } from "../../content/types";
+
+/**
+ * LessonPage section — a multi-content lesson experience.
+ *
+ * Sequences video, rich text, images, embedded quizzes, flashcards,
+ * and callouts into a single scrollable page with a sticky completion
+ * bar at the bottom.
+ *
+ * @example
+ * <LessonPage
+ *   title="React Hooks Deep Dive"
+ *   blocks={lessonBlocks}
+ *   onMarkComplete={() => completeLesson()}
+ *   onNextLesson={() => navigate(nextLesson)}
+ * />
+ */
+export interface LessonPageProps {
+  /** Lesson title */
+  title: string;
+  /** Ordered content blocks */
+  blocks: LessonBlock[];
+  /** Whether the lesson is already marked complete */
+  isCompleted?: boolean;
+  /** Called when the user marks the lesson complete */
+  onMarkComplete?: () => void;
+  /** Called when the user clicks "Next Lesson" */
+  onNextLesson?: () => void;
+  /** Next lesson title shown on the completion bar */
+  nextLessonTitle?: string;
+  /** Estimated duration in seconds */
+  estimatedDuration?: number;
+  /** Whether to show estimated duration */
+  showDuration?: boolean;
+  /** When true, disables interactive elements */
+  readOnly?: boolean;
+  /** CSS class name for the root element */
+  className?: string;
+  /** Inline styles for the root element */
+  style?: React.CSSProperties;
+}