@hydralms/components 0.1.0 → 0.1.2

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

package/src/sections/PracticeQuiz/PracticeQuiz.tsx

@@ -0,0 +1,199 @@
+import { useMemo, useState } from "react";
+import { CheckCircle } from "lucide-react";
+import { QuestionRenderer } 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;
+}
+
+export function PracticeQuiz({
+  questions: questionsProp,
+  instantFeedback = true,
+  allowRetry = true,
+  onComplete,
+  shuffled = false,
+  readOnly = false,
+  className,
+  style,
+}: PracticeQuizProps) {
+  const questions = useMemo(
+    () => (shuffled ? shuffleArray(questionsProp) : questionsProp),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [questionsProp, shuffled],
+  );
+
+  const [currentIndex, setCurrentIndex] = useState(0);
+  const [revealedUids, setRevealedUids] = useState<Set<string>>(new Set());
+  const [attemptCounts, setAttemptCounts] = useState<Map<string, number>>(new Map());
+  const [firstAttemptCorrect, setFirstAttemptCorrect] = useState<Set<string>>(new Set());
+  const [currentAnswer, setCurrentAnswer] = useState<{ uid: string; content?: string }[] | null>(null);
+  const [isComplete, setIsComplete] = useState(false);
+
+  const currentQuestion = questions[currentIndex];
+  const isRevealed = currentQuestion ? revealedUids.has(currentQuestion.uid) : false;
+
+  function checkAnswer() {
+    if (!currentQuestion || !currentAnswer) return;
+
+    const attempts = (attemptCounts.get(currentQuestion.uid) ?? 0) + 1;
+    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));
+
+    if (isCorrect && attempts === 1) {
+      setFirstAttemptCorrect((prev) => new Set(prev).add(currentQuestion.uid));
+    }
+  }
+
+  function handleRetry() {
+    if (!currentQuestion) return;
+    setRevealedUids((prev) => {
+      const next = new Set(prev);
+      next.delete(currentQuestion.uid);
+      return next;
+    });
+    setCurrentAnswer(null);
+  }
+
+  function handleNext() {
+    if (currentIndex < questions.length - 1) {
+      setCurrentIndex((i) => i + 1);
+      setCurrentAnswer(null);
+    } else {
+      const stats: PracticeQuizStats = {
+        totalQuestions: questions.length,
+        correctOnFirstAttempt: firstAttemptCorrect.size,
+        totalAttempts: Array.from(attemptCounts.values()).reduce((a, b) => a + b, 0),
+      };
+      setIsComplete(true);
+      onComplete?.(stats);
+    }
+  }
+
+  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))
+    );
+  }, [currentQuestion, currentAnswer]);
+
+  if (isComplete) {
+    const percentage = questions.length > 0
+      ? Math.round((firstAttemptCorrect.size / questions.length) * 100)
+      : 0;
+    return (
+      <Card className={className} style={style}>
+        <CardContent className="pt-6 text-center">
+          <CheckCircle size={48} className="text-success mx-auto mb-4" />
+          <p className="text-xl font-bold mb-1 text-foreground">Practice Complete!</p>
+          <p className="text-muted-foreground mb-2">
+            {firstAttemptCorrect.size} of {questions.length} correct on first attempt ({percentage}%)
+          </p>
+          <div className="flex justify-center">
+            <Button
+              variant="outline"
+              onClick={() => {
+                setCurrentIndex(0);
+                setRevealedUids(new Set());
+                setAttemptCounts(new Map());
+                setFirstAttemptCorrect(new Set());
+                setCurrentAnswer(null);
+                setIsComplete(false);
+              }}
+            >
+              Practice Again
+            </Button>
+          </div>
+        </CardContent>
+      </Card>
+    );
+  }
+
+  return (
+    <div className={className} style={style}>
+      <div className="flex justify-between items-center mb-2">
+        <span className="font-semibold text-sm text-foreground">
+          Question {currentIndex + 1} of {questions.length}
+        </span>
+        <span className="text-xs text-muted-foreground">
+          {firstAttemptCorrect.size} correct on first try
+        </span>
+      </div>
+      <Progress
+        value={currentIndex + (isRevealed ? 1 : 0)}
+        max={questions.length}
+        size="sm"
+        className="mb-3"
+      />
+
+      {currentQuestion && (
+        <Card>
+          <CardContent className="pt-6">
+            <QuestionRenderer
+              question={currentQuestion}
+              sessionAnswers={
+                currentAnswer?.map((a) => ({
+                  uid: currentQuestion.uid,
+                  answerUid: a.uid,
+                  content: a.content,
+                })) ?? []
+              }
+              onAnswer={(answers) => setCurrentAnswer(answers)}
+              readOnly={readOnly || isRevealed}
+              showCorrectAnswers={isRevealed}
+            />
+
+            {instantFeedback && isRevealed && (
+              <FeedbackBanner
+                isCorrect={isCurrentCorrect}
+                explanation={currentQuestion.explanation}
+                onRetry={allowRetry && !isCurrentCorrect ? handleRetry : undefined}
+              />
+            )}
+
+            <div className="flex justify-end gap-2 mt-2">
+              {!isRevealed && instantFeedback && (
+                <Button
+                  onClick={checkAnswer}
+                  disabled={!currentAnswer || currentAnswer.length === 0 || readOnly}
+                >
+                  Check Answer
+                </Button>
+              )}
+              {(!instantFeedback || isRevealed) && (
+                <Button
+                  onClick={handleNext}
+                  disabled={readOnly}
+                >
+                  {currentIndex < questions.length - 1 ? "Next Question" : "Finish"}
+                </Button>
+              )}
+            </div>
+          </CardContent>
+        </Card>
+      )}
+    </div>
+  );
+}

package/src/sections/PracticeQuiz/types.ts

@@ -0,0 +1,44 @@
+import type { QuestionData } from "../../questions/types";
+
+/**
+ * PracticeQuiz section — a low-stakes practice quiz with instant feedback.
+ *
+ * After each answer the correct answer is revealed with an explanation.
+ * Users can retry incorrect questions. A completion screen shows stats
+ * when all questions have been attempted.
+ *
+ * @example
+ * <PracticeQuiz
+ *   questions={questions}
+ *   onComplete={(stats) => trackPractice(stats)}
+ *   instantFeedback
+ *   allowRetry
+ * />
+ */
+export interface PracticeQuizProps {
+  /** Ordered list of questions to practice */
+  questions: QuestionData[];
+  /** Whether to reveal the correct answer immediately after answering */
+  instantFeedback?: boolean;
+  /** Whether to allow retrying incorrect answers */
+  allowRetry?: boolean;
+  /** Called when the user completes all questions */
+  onComplete?: (stats: PracticeQuizStats) => void;
+  /** Whether to shuffle the question order */
+  shuffled?: 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 PracticeQuizStats {
+  /** Total number of questions */
+  totalQuestions: number;
+  /** Questions answered correctly on the first attempt */
+  correctOnFirstAttempt: number;
+  /** Total answer attempts across all questions */
+  totalAttempts: number;
+}

package/src/sections/ProgressDashboard/ProgressDashboard.tsx

@@ -0,0 +1,140 @@
+import {
+  Award,
+  BookOpen,
+  CheckCircle,
+  Clock,
+  Flame,
+  Send,
+  Trophy,
+} from "lucide-react";
+import { ProgressRing, StatCard } from "../../progress";
+import { Progress } from "../../ui/progress";
+import { Card } from "../../ui/card";
+import { formatDuration } from "../../utils/format-duration";
+import type { ProgressDashboardProps } from "./types";
+import { cn } from "../../lib/utils";
+
+const ACTIVITY_ICONS = {
+  lesson_completed: BookOpen,
+  quiz_passed: CheckCircle,
+  assignment_submitted: Send,
+  badge_earned: Award,
+};
+
+export function ProgressDashboard({
+  overallProgress,
+  totalTimeSpent,
+  modules,
+  recentActivity,
+  streak,
+  achievements,
+  recentActivityLimit = 5,
+  onModuleClick,
+  className,
+  style,
+}: ProgressDashboardProps) {
+  return (
+    <div className={className} style={style}>
+      {/* Stats row */}
+      <div className="grid grid-cols-[repeat(auto-fit,minmax(160px,1fr))] gap-2 mb-3">
+        <Card className="p-2 flex justify-center">
+          <ProgressRing value={overallProgress} size={100} />
+        </Card>
+        <StatCard
+          icon={<Clock size={24} />}
+          label="Time Spent"
+          value={formatDuration(totalTimeSpent)}
+        />
+        {streak && (
+          <StatCard
+            icon={<Flame size={24} />}
+            label="Current Streak"
+            value={`${streak.currentDays} days`}
+            subtitle={`Longest: ${streak.longestDays} days`}
+          />
+        )}
+        <StatCard
+          icon={<BookOpen size={24} />}
+          label="Modules"
+          value={`${modules.filter((m) => m.completedItems === m.totalItems).length} / ${modules.length}`}
+          subtitle="completed"
+        />
+      </div>
+
+      {/* Module progress */}
+      <p className="text-lg font-semibold mb-2 text-foreground">Module Progress</p>
+      <div className="flex flex-col gap-2 mb-3">
+        {modules.map((mod) => {
+          const pct = mod.totalItems > 0 ? (mod.completedItems / mod.totalItems) * 100 : 0;
+          return (
+            <Card
+              key={mod.uid}
+              className={cn(
+                "p-2 transition-colors",
+                onModuleClick && "cursor-pointer hover:border-primary",
+              )}
+              onClick={() => onModuleClick?.(mod.uid)}
+            >
+              <div className="flex justify-between items-center mb-0.5">
+                <span className="font-semibold text-sm text-foreground">{mod.name}</span>
+                <span className="text-xs text-muted-foreground">
+                  {mod.completedItems} / {mod.totalItems}
+                </span>
+              </div>
+              <Progress value={pct} size="sm" />
+            </Card>
+          );
+        })}
+      </div>
+
+      {/* Recent activity */}
+      {recentActivity && recentActivity.length > 0 && (
+        <>
+          <p className="text-lg font-semibold mb-2 text-foreground">Recent Activity</p>
+          <div className="flex flex-col gap-1.5 mb-3">
+            {recentActivity.slice(0, recentActivityLimit).map((activity) => {
+              const Icon = ACTIVITY_ICONS[activity.type] ?? CheckCircle;
+              return (
+                <div key={activity.uid} className="flex gap-1.5 items-center">
+                  <Icon size={16} />
+                  <span className="flex-1 text-sm text-foreground">
+                    {activity.description}
+                  </span>
+                  <span className="text-xs text-muted-foreground">
+                    {new Date(activity.timestamp).toLocaleDateString()}
+                  </span>
+                </div>
+              );
+            })}
+          </div>
+        </>
+      )}
+
+      {/* Achievements */}
+      {achievements && achievements.length > 0 && (
+        <>
+          <p className="text-lg font-semibold mb-2 text-foreground">Achievements</p>
+          <div className="grid grid-cols-[repeat(auto-fill,minmax(140px,1fr))] gap-2">
+            {achievements.map((badge) => (
+              <Card key={badge.uid} className="p-2 text-center">
+                {badge.iconUrl ? (
+                  <img
+                    src={badge.iconUrl}
+                    alt={badge.name}
+                    className="w-12 h-12 mb-1 mx-auto"
+                  />
+                ) : (
+                  <Trophy size={32} className="mx-auto mb-2 text-warning" />
+                )}
+                <p className="font-semibold text-sm text-foreground">{badge.name}</p>
+                <p className="text-xs text-muted-foreground">
+                  {badge.description}
+                </p>
+              </Card>
+            ))}
+          </div>
+        </>
+      )}
+    </div>
+  );
+}