@hydralms/components 0.1.1 → 0.1.3

package/src/flashcards/flashcard.tsx

@@ -0,0 +1,108 @@
+import { useState } from "react";
+import { RotateCcw } from "lucide-react";
+import type { FlashcardProps } from "./types";
+import { cn } from "../lib/utils";
+
+const COLOR_MAP: Record<string, { bg: string; border: string; accent: string }> = {
+  color1: { bg: "bg-blue-50 dark:bg-blue-950/40", border: "border-blue-200 dark:border-blue-800", accent: "bg-blue-200 dark:bg-blue-800" },
+  color2: { bg: "bg-violet-50 dark:bg-violet-950/40", border: "border-violet-200 dark:border-violet-800", accent: "bg-violet-200 dark:bg-violet-800" },
+  color3: { bg: "bg-emerald-50 dark:bg-emerald-950/40", border: "border-emerald-200 dark:border-emerald-800", accent: "bg-emerald-200 dark:bg-emerald-800" },
+  color4: { bg: "bg-amber-50 dark:bg-amber-950/40", border: "border-amber-200 dark:border-amber-800", accent: "bg-amber-200 dark:bg-amber-800" },
+  color5: { bg: "bg-rose-50 dark:bg-rose-950/40", border: "border-rose-200 dark:border-rose-800", accent: "bg-rose-200 dark:bg-rose-800" },
+  color6: { bg: "bg-green-50 dark:bg-green-950/40", border: "border-green-200 dark:border-green-800", accent: "bg-green-200 dark:bg-green-800" },
+};
+
+const SIZE_MAP: Record<string, { width: number; height: number; fontSize: string }> = {
+  small: { width: 280, height: 180, fontSize: "0.875rem" },
+  medium: { width: 400, height: 260, fontSize: "1rem" },
+  large: { width: 520, height: 340, fontSize: "1.125rem" },
+};
+
+export const Flashcard = ({
+  card,
+  isFlipped: controlledFlipped,
+  onFlip,
+  readOnly = false,
+  size = "medium",
+}: FlashcardProps) => {
+  const [internalFlipped, setInternalFlipped] = useState(false);
+
+  const isControlled = controlledFlipped !== undefined;
+  const isFlipped = isControlled ? controlledFlipped : internalFlipped;
+
+  const handleClick = () => {
+    if (readOnly) return;
+    if (isControlled) {
+      onFlip?.();
+    } else {
+      setInternalFlipped((prev) => !prev);
+      onFlip?.();
+    }
+  };
+
+  const { width, height, fontSize } = SIZE_MAP[size];
+  const colors = COLOR_MAP[card.color] || COLOR_MAP.color1;
+
+  return (
+    <div
+      className="perspective-[1000px]"
+      style={{ width: `${width}px`, height: `${height}px` }}
+    >
+      <div
+        className={cn(
+          "relative size-full transition-transform duration-500 transform-3d",
+          isFlipped && "transform-[rotateY(180deg)]",
+        )}
+      >
+        {/* Front */}
+        <div
+          className={cn(
+            "absolute inset-0 flex flex-col rounded-lg border backface-hidden",
+            colors.bg,
+            colors.border,
+            !readOnly && "cursor-pointer",
+          )}
+          onClick={handleClick}
+        >
+          <div className="flex flex-1 items-center justify-center p-5 overflow-auto">
+            <div
+              className="text-center"
+              style={{ fontSize }}
+              dangerouslySetInnerHTML={{ __html: card.front }}
+            />
+          </div>
+          {!readOnly && (
+            <div className="flex items-center justify-center gap-1 pb-3 text-muted-foreground">
+              <RotateCcw size={12} />
+              <span className="text-xs">Tap to flip</span>
+            </div>
+          )}
+        </div>
+
+        {/* Back */}
+        <div
+          className={cn(
+            "absolute inset-0 flex flex-col rounded-lg border border-border bg-background backface-hidden transform-[rotateY(180deg)]",
+            !readOnly && "cursor-pointer",
+          )}
+          onClick={handleClick}
+        >
+          <div className={cn("h-1.5 rounded-t-lg", colors.accent)} />
+          <div className="flex flex-1 items-start justify-center p-5 overflow-auto">
+            <div
+              className="text-left w-full flashcard-back-content"
+              style={{ fontSize }}
+              dangerouslySetInnerHTML={{ __html: card.back }}
+            />
+          </div>
+          {!readOnly && (
+            <div className="flex items-center justify-center gap-1 pb-3 text-muted-foreground">
+              <RotateCcw size={12} />
+              <span className="text-xs">Tap to flip back</span>
+            </div>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+};

package/src/flashcards/index.ts

@@ -0,0 +1,3 @@
+export { Flashcard } from "./flashcard";
+export { FlashcardDeck } from "./flashcard-deck";
+export type { FlashcardData, FlashcardProps, FlashcardDeckProps } from "./types";

package/src/flashcards/types.ts

@@ -0,0 +1,60 @@
+/**
+ * Flashcard component with 3D flip animation. Supports controlled and uncontrolled flip state.
+ *
+ * @example
+ * <Flashcard
+ *   card={{ uid: "1", front: "What is React?", back: "A JavaScript library for building UIs", color: "color1" }}
+ *   size="medium"
+ * />
+ */
+export interface FlashcardProps {
+  /** The flashcard data to display */
+  card: FlashcardData;
+  /** Controlled flip state — if provided, flip state is managed externally */
+  isFlipped?: boolean;
+  /** Called when the card is flipped */
+  onFlip?: () => void;
+  /** When true, disables the flip interaction */
+  readOnly?: boolean;
+  /** Card size variant */
+  size?: "small" | "medium" | "large";
+}
+
+/**
+ * FlashcardDeck component for navigating through a collection of flashcards.
+ *
+ * @example
+ * <FlashcardDeck
+ *   cards={cards}
+ *   deckName="React Fundamentals"
+ *   showProgress
+ *   onComplete={() => alert('Deck complete!')}
+ * />
+ */
+export interface FlashcardDeckProps {
+  /** Array of flashcard data to display */
+  cards: FlashcardData[];
+  /** Title shown above the deck */
+  deckName?: string;
+  /** Description shown below the deck name */
+  deckDescription?: string;
+  /** Controlled current card index */
+  currentIndex?: number;
+  /** Called when the user navigates to a different card */
+  onNavigate?: (index: number) => void;
+  /** Called when the user finishes the last card */
+  onComplete?: () => void;
+  /** When true, disables card flipping */
+  readOnly?: boolean;
+  /** Whether to show the progress bar and counter */
+  showProgress?: boolean;
+  /** Whether to shuffle the cards randomly */
+  shuffled?: boolean;
+}
+
+export interface FlashcardData {
+  uid: string;
+  front: string;
+  back: string;
+  color: string;
+}

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[] };