@hydralms/components 0.1.0 → 0.1.2

package/src/index.ts

@@ -0,0 +1,38 @@
+// Questions
+export * from "./questions";
+
+// Assessment Toolbar
+export * from "./assessment-toolbar";
+
+// Flashcards
+export * from "./flashcards";
+
+// Curriculum
+export * from "./curriculum";
+
+// Video
+export * from "./video";
+
+// Common
+export * from "./common";
+
+// Feedback
+export * from "./feedback";
+
+// Progress
+export * from "./progress";
+
+// Social
+export * from "./social";
+
+// Content
+export * from "./content";
+
+// Provider
+export * from "./provider";
+
+// UI primitives (shadcn/ui + Base UI)
+export * from "./ui";
+
+// Utilities
+export { cn } from "./lib/utils";

package/src/lib/utils.ts

@@ -0,0 +1,6 @@
+import { clsx, type ClassValue } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}

package/src/modules/CoursePlayer/CoursePlayer.tsx

@@ -0,0 +1,281 @@
+import { useState, useMemo } from "react";
+import {
+  ChevronLeft,
+  ChevronRight,
+  Check,
+  PanelLeftClose,
+  PanelLeft,
+} from "lucide-react";
+import { CourseOutline } from "../../sections/CourseOutline/CourseOutline";
+import { LessonPage } from "../../sections/LessonPage/LessonPage";
+import { LecturePlayer } from "../../sections/LecturePlayer/LecturePlayer";
+import { PracticeQuiz } from "../../sections/PracticeQuiz/PracticeQuiz";
+import { EmptyState } from "../../common";
+import { Progress } from "../../ui/progress";
+import { Button } from "../../ui/button";
+import { cn } from "../../lib/utils";
+import type { CurriculumItem } from "../../curriculum/types";
+import type { CoursePlayerProps, CoursePlayerItem } from "./types";
+
+function flattenLeaves(items: CurriculumItem[]): string[] {
+  const leaves: string[] = [];
+  for (const item of items) {
+    if (!item.children || item.children.length === 0) {
+      leaves.push(item.uid);
+    } else {
+      leaves.push(...flattenLeaves(item.children));
+    }
+  }
+  return leaves;
+}
+
+export function CoursePlayer({
+  courseTitle,
+  curriculum,
+  progress,
+  items,
+  initialItemUid,
+  onItemComplete,
+  onItemChange,
+  sidebarCollapsed = false,
+  readOnly = false,
+  className,
+  style,
+}: CoursePlayerProps) {
+  const leafUids = useMemo(() => flattenLeaves(curriculum), [curriculum]);
+  const itemMap = useMemo(
+    () => new Map(items.map((item) => [item.uid, item])),
+    [items],
+  );
+
+  const [activeUid, setActiveUid] = useState(
+    initialItemUid ?? leafUids[0] ?? "",
+  );
+  const [sidebarOpen, setSidebarOpen] = useState(!sidebarCollapsed);
+  const [completedUids, setCompletedUids] = useState<Set<string>>(() => {
+    if (!progress) return new Set();
+    return new Set(
+      progress.filter((p) => p.isCompleted).map((p) => p.resourceUid),
+    );
+  });
+
+  const currentIndex = leafUids.indexOf(activeUid);
+  const hasPrevious = currentIndex > 0;
+  const hasNext = currentIndex < leafUids.length - 1;
+  const isCurrentCompleted = completedUids.has(activeUid);
+  const overallPercentage =
+    leafUids.length > 0
+      ? Math.round(
+          (leafUids.filter((uid) => completedUids.has(uid)).length /
+            leafUids.length) *
+            100,
+        )
+      : 0;
+
+  const activeItem = itemMap.get(activeUid);
+
+  function navigateTo(uid: string) {
+    setActiveUid(uid);
+    onItemChange?.(uid);
+  }
+
+  function handleItemClick(item: CurriculumItem) {
+    if (!item.children || item.children.length === 0) {
+      navigateTo(item.uid);
+    }
+  }
+
+  function handleMarkComplete() {
+    setCompletedUids((prev) => new Set(prev).add(activeUid));
+    onItemComplete?.(activeUid);
+  }
+
+  function handleNext() {
+    if (hasNext) navigateTo(leafUids[currentIndex + 1]);
+  }
+
+  function handlePrevious() {
+    if (hasPrevious) navigateTo(leafUids[currentIndex - 1]);
+  }
+
+  // Build combined progress for CourseOutline
+  const combinedProgress = useMemo(() => {
+    const progressMap = new Map(
+      (progress ?? []).map((p) => [p.resourceUid, p]),
+    );
+    for (const uid of completedUids) {
+      if (!progressMap.has(uid)) {
+        progressMap.set(uid, { resourceUid: uid, isCompleted: true });
+      } else {
+        progressMap.set(uid, { ...progressMap.get(uid)!, isCompleted: true });
+      }
+    }
+    return Array.from(progressMap.values());
+  }, [progress, completedUids]);
+
+  // Find next item title for the nav buttons
+  const nextItem = hasNext ? itemMap.get(leafUids[currentIndex + 1]) : null;
+
+  return (
+    <div
+      className={cn("flex h-full overflow-hidden", className)}
+      style={style}
+    >
+      {/* Sidebar */}
+      {sidebarOpen && (
+        <aside className="w-80 shrink-0 border-r border-border overflow-y-auto bg-background">
+          <div className="flex items-center justify-between px-3 pt-3 pb-1">
+            <span className="text-xs font-semibold text-muted-foreground uppercase tracking-wide">
+              Course
+            </span>
+            <button
+              type="button"
+              className="p-1 rounded hover:bg-muted text-muted-foreground"
+              onClick={() => setSidebarOpen(false)}
+            >
+              <PanelLeftClose className="size-4" />
+            </button>
+          </div>
+          <CourseOutline
+            items={curriculum}
+            progress={combinedProgress}
+            courseTitle={courseTitle}
+            activeItemUid={activeUid}
+            onItemClick={handleItemClick}
+            readOnly={readOnly}
+          />
+        </aside>
+      )}
+
+      {/* Main content area */}
+      <div className="flex-1 flex flex-col min-w-0 overflow-hidden">
+        {/* Toolbar */}
+        <div className="flex items-center gap-2 px-4 py-2 border-b border-border bg-background shrink-0">
+          {!sidebarOpen && (
+            <button
+              type="button"
+              className="p-1 rounded hover:bg-muted text-muted-foreground mr-1"
+              onClick={() => setSidebarOpen(true)}
+            >
+              <PanelLeft className="size-4" />
+            </button>
+          )}
+          <div className="flex-1 min-w-0">
+            <span className="text-sm font-semibold text-foreground truncate block">
+              {activeItem?.title ?? "Select an item"}
+            </span>
+          </div>
+          <span className="text-xs text-muted-foreground shrink-0">
+            {currentIndex + 1} / {leafUids.length}
+          </span>
+        </div>
+
+        {/* Content */}
+        <div className="flex-1 overflow-y-auto p-6">
+          {activeItem ? (
+            renderContent(activeItem, readOnly, handleMarkComplete, isCurrentCompleted, handleNext, hasNext, nextItem)
+          ) : (
+            <EmptyState
+              title="No content selected"
+              description="Select an item from the course outline to get started."
+            />
+          )}
+        </div>
+
+        {/* Bottom bar */}
+        <div className="shrink-0 border-t border-border bg-background px-4 py-3">
+          <div className="flex items-center gap-4">
+            <div className="flex-1 min-w-0">
+              <div className="flex items-center gap-2 mb-1">
+                <span className="text-xs text-muted-foreground">
+                  {overallPercentage}% complete
+                </span>
+              </div>
+              <Progress value={overallPercentage} size="sm" />
+            </div>
+            <div className="flex items-center gap-2 shrink-0">
+              {!isCurrentCompleted && activeItem && (
+                <Button
+                  size="sm"
+                  variant="outline"
+                  onClick={handleMarkComplete}
+                  disabled={readOnly}
+                >
+                  <Check className="size-3.5 mr-1" />
+                  Complete
+                </Button>
+              )}
+              <Button
+                size="sm"
+                variant="ghost"
+                onClick={handlePrevious}
+                disabled={!hasPrevious}
+              >
+                <ChevronLeft className="size-4" />
+              </Button>
+              <Button
+                size="sm"
+                variant="ghost"
+                onClick={handleNext}
+                disabled={!hasNext}
+              >
+                <ChevronRight className="size-4" />
+              </Button>
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+function renderContent(
+  item: CoursePlayerItem,
+  readOnly: boolean,
+  onMarkComplete: () => void,
+  isCompleted: boolean,
+  onNext: () => void,
+  hasNext: boolean,
+  nextItem: CoursePlayerItem | null | undefined,
+) {
+  switch (item.type) {
+    case "lesson":
+      return (
+        <LessonPage
+          title={item.title}
+          blocks={item.blocks}
+          isCompleted={isCompleted}
+          onMarkComplete={onMarkComplete}
+          onNextLesson={hasNext ? onNext : undefined}
+          nextLessonTitle={nextItem?.title}
+          readOnly={readOnly}
+        />
+      );
+    case "video":
+      return (
+        <LecturePlayer
+          video={{
+            src: item.src,
+            poster: item.poster,
+            title: item.title,
+          }}
+        />
+      );
+    case "quiz":
+      return (
+        <PracticeQuiz
+          questions={item.questions}
+          instantFeedback
+          allowRetry
+          readOnly={readOnly}
+        />
+      );
+    default:
+      return (
+        <EmptyState
+          title="Unknown content type"
+          description="This content type is not supported."
+        />
+      );
+  }
+}

package/src/modules/CoursePlayer/types.ts

@@ -0,0 +1,48 @@
+import type { CurriculumItem, CurriculumItemProgress } from "../../curriculum/types";
+import type { LessonBlock } from "../../content/types";
+import type { QuestionData } from "../../questions/types";
+
+/**
+ * CoursePlayer — a complete course consumption shell with sidebar and content panel.
+ *
+ * Renders a collapsible CourseOutline sidebar alongside a content panel that
+ * switches between LessonPage, LecturePlayer, or PracticeQuiz based on the
+ * active item type. Includes a bottom bar with progress and navigation.
+ *
+ * @example
+ * <CoursePlayer
+ *   courseTitle="Introduction to React"
+ *   curriculum={curriculum}
+ *   items={courseItems}
+ *   onItemComplete={(uid) => markComplete(uid)}
+ * />
+ */
+export interface CoursePlayerProps {
+  /** Course title displayed in the sidebar header */
+  courseTitle: string;
+  /** Hierarchical curriculum structure for the sidebar */
+  curriculum: CurriculumItem[];
+  /** User's progress data for completion indicators */
+  progress?: CurriculumItemProgress[];
+  /** Content data for each leaf curriculum item */
+  items: CoursePlayerItem[];
+  /** UID of the initially active item */
+  initialItemUid?: string;
+  /** Called when the user marks a content item as complete */
+  onItemComplete?: (itemUid: string) => void;
+  /** Called when the active item changes (user navigates) */
+  onItemChange?: (itemUid: string) => void;
+  /** Whether the sidebar starts collapsed. @default false */
+  sidebarCollapsed?: boolean;
+  /** When true, disables all interactive elements */
+  readOnly?: boolean;
+  /** CSS class name for the root element */
+  className?: string;
+  /** Inline styles for the root element */
+  style?: React.CSSProperties;
+}
+
+export type CoursePlayerItem =
+  | { uid: string; type: "lesson"; title: string; blocks: LessonBlock[] }
+  | { uid: string; type: "video"; title: string; src: string; poster?: string }
+  | { uid: string; type: "quiz"; title: string; questions: QuestionData[] };

package/src/modules/FlashcardLab/FlashcardLab.tsx

@@ -0,0 +1,275 @@
+import { useState, useRef } from "react";
+import {
+  BookOpen,
+  Shuffle,
+  RotateCcw,
+  CheckCircle2,
+  Layers,
+  Clock,
+  ArrowLeft,
+} from "lucide-react";
+import { FlashcardStudySession } from "../../sections/FlashcardStudySession/FlashcardStudySession";
+import { ProgressRing } from "../../progress/progress-ring";
+import { StatCard } from "../../progress/stat-card";
+import { Button } from "../../ui/button";
+import { Badge } from "../../ui/badge";
+import { Card, CardContent } from "../../ui/card";
+import { formatDuration } from "../../utils/format-duration";
+import { cn } from "../../lib/utils";
+import type { FlashcardData } from "../../flashcards/types";
+import type {
+  FlashcardLabProps,
+  FlashcardLabResult,
+} from "./types";
+
+type InternalStep =
+  | { tag: "setup" }
+  | { tag: "study"; cards: FlashcardData[]; deckUids: string[]; shuffled: boolean }
+  | { tag: "completion"; result: FlashcardLabResult };
+
+export function FlashcardLab({
+  decks,
+  showShuffleToggle = true,
+  defaultShuffled = false,
+  allowMultiSelect = true,
+  onComplete,
+  className,
+  style,
+}: FlashcardLabProps) {
+  const [step, setStep] = useState<InternalStep>({ tag: "setup" });
+  const [selectedUids, setSelectedUids] = useState<Set<string>>(new Set());
+  const [shuffled, setShuffled] = useState(defaultShuffled);
+  const startTimeRef = useRef<number | null>(null);
+
+  function toggleDeck(uid: string) {
+    setSelectedUids((prev) => {
+      const next = new Set(prev);
+      if (next.has(uid)) {
+        next.delete(uid);
+      } else {
+        if (!allowMultiSelect) next.clear();
+        next.add(uid);
+      }
+      return next;
+    });
+  }
+
+  function startStudying() {
+    const selected = decks.filter((d) => selectedUids.has(d.uid));
+    const cards = selected.flatMap((d) => d.cards);
+    startTimeRef.current = Date.now();
+    setStep({
+      tag: "study",
+      cards,
+      deckUids: selected.map((d) => d.uid),
+      shuffled,
+    });
+  }
+
+  function handleStudyComplete() {
+    if (step.tag !== "study") return;
+    const elapsed = startTimeRef.current
+      ? Math.floor((Date.now() - startTimeRef.current) / 1000)
+      : 0;
+
+    const result: FlashcardLabResult = {
+      totalCards: step.cards.length,
+      decksStudied: step.deckUids.length,
+      deckUids: step.deckUids,
+      wasShuffled: step.shuffled,
+      timeElapsedSeconds: elapsed,
+    };
+    setStep({ tag: "completion", result });
+    onComplete?.(result);
+  }
+
+  function handleStudyAgain() {
+    if (step.tag !== "completion") return;
+    const selected = decks.filter((d) => step.result.deckUids.includes(d.uid));
+    const cards = selected.flatMap((d) => d.cards);
+    startTimeRef.current = Date.now();
+    setStep({
+      tag: "study",
+      cards,
+      deckUids: step.result.deckUids,
+      shuffled: step.result.wasShuffled,
+    });
+  }
+
+  function handlePickNewDeck() {
+    setSelectedUids(new Set());
+    setShuffled(defaultShuffled);
+    setStep({ tag: "setup" });
+  }
+
+  // ─── Setup Screen ───
+  if (step.tag === "setup") {
+    return (
+      <div className={cn(className)} style={style}>
+        <div className="text-center mb-6">
+          <div className="mx-auto mb-3 w-14 h-14 rounded-full bg-primary/10 flex items-center justify-center">
+            <BookOpen className="size-7 text-primary" />
+          </div>
+          <h2 className="text-2xl font-bold text-foreground mb-1">
+            Choose Your Decks
+          </h2>
+          <p className="text-muted-foreground text-sm">
+            {allowMultiSelect
+              ? "Select one or more decks to study"
+              : "Select a deck to study"}
+          </p>
+        </div>
+
+        {/* Deck grid */}
+        <div className="grid sm:grid-cols-2 lg:grid-cols-3 gap-3 mb-6">
+          {decks.map((deck) => {
+            const isSelected = selectedUids.has(deck.uid);
+            return (
+              <Card
+                key={deck.uid}
+                className={cn(
+                  "cursor-pointer transition-all py-0",
+                  isSelected
+                    ? "border-primary ring-1 ring-primary"
+                    : "hover:border-muted-foreground/30",
+                )}
+                onClick={() => toggleDeck(deck.uid)}
+              >
+                <CardContent className="py-4">
+                  <div className="flex items-start justify-between mb-2">
+                    <h3 className="font-semibold text-foreground text-sm">
+                      {deck.title}
+                    </h3>
+                    <Badge variant="secondary" className="text-xs shrink-0">
+                      {deck.cards.length} cards
+                    </Badge>
+                  </div>
+                  {deck.description && (
+                    <p className="text-xs text-muted-foreground line-clamp-2">
+                      {deck.description}
+                    </p>
+                  )}
+                </CardContent>
+              </Card>
+            );
+          })}
+        </div>
+
+        {/* Options + start */}
+        <div className="flex items-center justify-between">
+          <div className="flex items-center gap-3">
+            {showShuffleToggle && (
+              <button
+                type="button"
+                className={cn(
+                  "flex items-center gap-1.5 text-sm px-3 py-1.5 rounded-md border transition-colors",
+                  shuffled
+                    ? "border-primary bg-primary/10 text-primary"
+                    : "border-border text-muted-foreground hover:text-foreground",
+                )}
+                onClick={() => setShuffled((s) => !s)}
+              >
+                <Shuffle className="size-3.5" />
+                Shuffle
+              </button>
+            )}
+            {selectedUids.size > 0 && (
+              <span className="text-xs text-muted-foreground">
+                {decks
+                  .filter((d) => selectedUids.has(d.uid))
+                  .reduce((sum, d) => sum + d.cards.length, 0)}{" "}
+                cards selected
+              </span>
+            )}
+          </div>
+          <Button
+            onClick={startStudying}
+            disabled={selectedUids.size === 0}
+          >
+            Start Studying
+          </Button>
+        </div>
+      </div>
+    );
+  }
+
+  // ─── Study Screen ───
+  if (step.tag === "study") {
+    const deckNames = decks
+      .filter((d) => step.deckUids.includes(d.uid))
+      .map((d) => d.title)
+      .join(", ");
+
+    return (
+      <div className={cn(className)} style={style}>
+        <FlashcardStudySession
+          cards={step.cards}
+          title={deckNames}
+          shuffled={step.shuffled}
+          onComplete={handleStudyComplete}
+        />
+      </div>
+    );
+  }
+
+  // ─── Completion Screen ───
+  const { result } = step;
+
+  return (
+    <div className={cn(className)} style={style}>
+      <div className="text-center mb-8">
+        <div className="relative mx-auto mb-4">
+          <ProgressRing
+            value={100}
+            size={120}
+            strokeWidth={10}
+            color="var(--success)"
+            className="text-foreground"
+            label=""
+          />
+          <CheckCircle2 className="size-8 text-success absolute inset-0 m-auto" />
+        </div>
+        <h2 className="text-xl font-bold text-foreground mb-1">
+          Study Session Complete
+        </h2>
+        <p className="text-muted-foreground text-sm">
+          Great work! Here's your session summary.
+        </p>
+      </div>
+
+      <div className="grid grid-cols-2 sm:grid-cols-4 gap-3 mb-8">
+        <StatCard
+          icon={<Layers />}
+          label="Cards Studied"
+          value={String(result.totalCards)}
+        />
+        <StatCard
+          icon={<BookOpen />}
+          label="Decks"
+          value={String(result.decksStudied)}
+        />
+        <StatCard
+          icon={<Clock />}
+          label="Time Spent"
+          value={formatDuration(result.timeElapsedSeconds)}
+        />
+        <StatCard
+          icon={<Shuffle />}
+          label="Shuffled"
+          value={result.wasShuffled ? "Yes" : "No"}
+        />
+      </div>
+
+      <div className="flex justify-center gap-3">
+        <Button variant="outline" onClick={handlePickNewDeck}>
+          <ArrowLeft className="size-4 mr-2" />
+          Pick New Deck
+        </Button>
+        <Button onClick={handleStudyAgain}>
+          <RotateCcw className="size-4 mr-2" />
+          Study Again
+        </Button>
+      </div>
+    </div>
+  );
+}