@hydralms/components 0.2.0 → 0.3.0

package/src/modules/DiscussionModule/DiscussionModule.tsx

@@ -1,10 +1,12 @@
-import { useState, useRef, useEffect } from "react";
+import { useCallback, useState, useRef, useEffect } from "react";
 import { ArrowLeft } from "lucide-react";
 import { ForumBoard } from "../../sections/ForumBoard/ForumBoard";
 import { DiscussionThread } from "../../sections/DiscussionThread/DiscussionThread";
+import { EmptyState } from "../../common";
 import { Button } from "../../ui/button";
 import { cn } from "../../lib/utils";
 import type { ForumSortOrder } from "../../sections/ForumBoard/types";
+import { withProGate } from "../../license/withProGate";
 import type { DiscussionModuleProps } from "./types";
 
 /**
@@ -13,11 +15,11 @@ import type { DiscussionModuleProps } from "./types";
  * Panel-based layout: ForumBoard (topic listing) ↔ DiscussionThread (thread detail).
  * Clicking a topic drills into the thread; a back button returns to the board.
  */
-export function DiscussionModule({
+function DiscussionModuleBase({
   forumTitle,
-  topics,
+  topics = [],
   currentUser,
-  threads,
+  threads = {},
   onCreateTopic,
   onReply,
   onToggleLike,
@@ -36,20 +38,44 @@ export function DiscussionModule({
     contentRef.current?.focus({ preventScroll: true });
   }, [activeTopicUid]);
 
-  function handleTopicClick(topicUid: string) {
+  const onTopicOpenRef = useRef(onTopicOpen);
+  onTopicOpenRef.current = onTopicOpen;
+
+  const handleTopicClick = useCallback((topicUid: string) => {
     setActiveTopicUid(topicUid);
-    onTopicOpen?.(topicUid);
-  }
+    onTopicOpenRef.current?.(topicUid);
+  }, []);
 
-  function handleBack() {
+  const handleBack = useCallback(() => {
     setActiveTopicUid(null);
-  }
+  }, []);
 
   const activeThread = activeTopicUid ? threads[activeTopicUid] : null;
   const activeTopic = activeTopicUid
     ? topics.find((t) => t.uid === activeTopicUid)
     : null;
 
+  const handleReply = useCallback(
+    (parentUid: string, content: string) => {
+      if (activeTopicUid) onReply?.(activeTopicUid, parentUid, content);
+    },
+    [activeTopicUid, onReply],
+  );
+
+  const handleToggleLike = useCallback(
+    (postUid: string) => {
+      if (activeTopicUid) onToggleLike?.(activeTopicUid, postUid);
+    },
+    [activeTopicUid, onToggleLike],
+  );
+
+  const handleMarkAnswer = useCallback(
+    (postUid: string) => {
+      if (activeTopicUid) onMarkAnswer?.(activeTopicUid, postUid);
+    },
+    [activeTopicUid, onMarkAnswer],
+  );
+
   return (
     <div
       ref={contentRef}
@@ -74,22 +100,29 @@ export function DiscussionModule({
             rootPost={activeThread.rootPost}
             replies={activeThread.replies}
             currentUser={currentUser}
-            onReply={(parentUid, content) =>
-              onReply?.(activeTopicUid, parentUid, content)
-            }
-            onToggleLike={
-              onToggleLike
-                ? (postUid) => onToggleLike(activeTopicUid, postUid)
-                : undefined
-            }
-            onMarkAnswer={
-              onMarkAnswer
-                ? (postUid) => onMarkAnswer(activeTopicUid, postUid)
-                : undefined
-            }
+            onReply={handleReply}
+            onToggleLike={onToggleLike ? handleToggleLike : undefined}
+            onMarkAnswer={onMarkAnswer ? handleMarkAnswer : undefined}
             readOnly={readOnly}
           />
         </div>
+      ) : activeTopicUid && !activeThread ? (
+        /* ─── Empty Thread State ─── */
+        <div>
+          <Button
+            variant="ghost"
+            size="sm"
+            onClick={handleBack}
+            className="mb-4"
+          >
+            <ArrowLeft className="size-4 mr-1.5" />
+            Back to Topics
+          </Button>
+          <EmptyState
+            title="No discussion yet"
+            description="Be the first to start this conversation."
+          />
+        </div>
       ) : (
         /* ─── Forum Board View ─── */
         <ForumBoard
@@ -108,3 +141,5 @@ export function DiscussionModule({
     </div>
   );
 }
+
+export const DiscussionModule = withProGate(DiscussionModuleBase, "DiscussionModule");

package/src/modules/ExamModule/ExamModule.tsx

@@ -1,28 +1,16 @@
-import { useState, useRef, useEffect } from "react";
-import {
-  ShieldCheck,
-  RotateCcw,
-  Clock,
-  HelpCircle,
-  CheckCircle2,
-  XCircle,
-  Trophy,
-  Play,
-} from "lucide-react";
+import { useState, useRef, useEffect, useCallback } from "react";
+import { ShieldCheck } from "lucide-react";
 import { ExamSession } from "../../sections/ExamSession/ExamSession";
-import { AssessmentReview } from "../../sections/AssessmentReview/AssessmentReview";
-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 { Alert, AlertDescription } from "../../ui/alert";
-import { Separator } from "../../ui/separator";
-import { formatDuration } from "../../utils/format-duration";
 import { cn } from "../../lib/utils";
 import type { SessionAnswer } from "../../questions/types";
 import type { ExamSubmitMetadata } from "../../sections/ExamSession/types";
 import { scoreAssessment } from "../../questions/scoring";
+import { useTimer } from "../_shared/use-timer";
+import { AssessmentIntro } from "../_shared/assessment-intro";
+import { AssessmentResults } from "../_shared/assessment-results";
+import { withProGate } from "../../license/withProGate";
 import type { ExamModuleProps, ExamModuleResult } from "./types";
 
 type InternalStep =
@@ -36,11 +24,11 @@ type InternalStep =
  * Steps: Intro (rules/instructions) → Exam (timed ExamSession) → Results (score + review).
  * Manages an external timer that feeds elapsed time to ExamSession.
  */
-export function ExamModule({
+function ExamModuleBase({
   title,
   description,
   instructions,
-  questions,
+  questions = [],
   timeLimitSeconds,
   passingScore,
   allowBackNavigation = true,
@@ -49,45 +37,24 @@ export function ExamModule({
   allowRetake = false,
   showReview = true,
   onComplete,
+  readOnly = false,
   className,
   style,
 }: ExamModuleProps) {
   const [step, setStep] = useState<InternalStep>({ tag: "intro" });
-  const [timeElapsed, setTimeElapsed] = useState(0);
-  const startTimeRef = useRef<number | null>(null);
-  const intervalRef = useRef<ReturnType<typeof setInterval> | null>(null);
   const contentRef = useRef<HTMLDivElement>(null);
+  const { timeElapsed, reset: resetTimer } = useTimer(step.tag === "exam");
 
-  useEffect(() => {
-    contentRef.current?.focus({ preventScroll: true });
-  }, [step.tag]);
+  const onCompleteRef = useRef(onComplete);
+  onCompleteRef.current = onComplete;
 
-  // Timer for exam step
   useEffect(() => {
-    if (step.tag === "exam") {
-      startTimeRef.current = Date.now();
-      intervalRef.current = setInterval(() => {
-        if (startTimeRef.current) {
-          setTimeElapsed(Math.floor((Date.now() - startTimeRef.current) / 1000));
-        }
-      }, 1000);
-    } else {
-      if (intervalRef.current) {
-        clearInterval(intervalRef.current);
-        intervalRef.current = null;
-      }
-    }
-    return () => {
-      if (intervalRef.current) clearInterval(intervalRef.current);
-    };
+    contentRef.current?.focus({ preventScroll: true });
   }, [step.tag]);
 
-  function scoreAnswers(
-    answers: SessionAnswer[],
-    metadata: ExamSubmitMetadata
-  ): ExamModuleResult {
+  const handleSubmit = useCallback((answers: SessionAnswer[], metadata: ExamSubmitMetadata) => {
     const { correct, total, percentage } = scoreAssessment(questions, answers);
-    return {
+    const result: ExamModuleResult = {
       answers,
       correct,
       total,
@@ -96,72 +63,36 @@ export function ExamModule({
       timeElapsedSeconds: metadata.timeElapsedSeconds,
       wasAutoSubmitted: metadata.wasAutoSubmitted,
     };
-  }
-
-  function handleSubmit(answers: SessionAnswer[], metadata: ExamSubmitMetadata) {
-    const result = scoreAnswers(answers, metadata);
     setStep({ tag: "results", result });
-    onComplete?.(result);
-  }
+    onCompleteRef.current?.(result);
+  }, [questions, passingScore]);
 
-  function handleRetake() {
-    setTimeElapsed(0);
-    startTimeRef.current = null;
+  const handleRetake = useCallback(() => {
+    resetTimer();
     setStep({ tag: "intro" });
-  }
+  }, [resetTimer]);
 
   // ─── Intro Screen ───
   if (step.tag === "intro") {
     return (
-      <div
-        ref={contentRef}
-        tabIndex={-1}
-        className={cn("max-w-2xl mx-auto outline-none", className)}
-        style={style}
-      >
-        <Card>
-          <CardContent className="pt-8 pb-8 text-center">
-            <div className="mx-auto mb-4 w-14 h-14 rounded-full bg-primary/10 flex items-center justify-center">
-              <ShieldCheck className="size-7 text-primary" />
-            </div>
-            <h2 className="text-2xl font-bold text-foreground mb-2">{title}</h2>
-            {description && (
-              <p className="text-muted-foreground mb-6 max-w-md mx-auto">
-                {description}
-              </p>
-            )}
-
-            {/* Instructions */}
-            {instructions && (
-              <Alert className="text-left mb-6">
-                <AlertDescription>{instructions}</AlertDescription>
-              </Alert>
-            )}
-
-            {/* Metadata chips */}
-            <div className="flex flex-wrap justify-center gap-2 mb-8">
-              <Badge variant="outline" className="gap-1.5">
-                <HelpCircle className="size-3.5" />
-                {questions.length} questions
-              </Badge>
-              <Badge variant="outline" className="gap-1.5">
-                <Clock className="size-3.5" />
-                {formatDuration(timeLimitSeconds)} time limit
-              </Badge>
-              {passingScore !== undefined && (
-                <Badge variant="outline" className="gap-1.5">
-                  <CheckCircle2 className="size-3.5" />
-                  {passingScore}% to pass
-                </Badge>
-              )}
-            </div>
-
-            <Button size="lg" onClick={() => setStep({ tag: "exam" })}>
-              <Play className="size-4 mr-2" />
-              Begin Exam
-            </Button>
-          </CardContent>
-        </Card>
+      <div ref={contentRef} tabIndex={-1} className={cn("max-w-2xl mx-auto outline-none", className)} style={style}>
+        <AssessmentIntro
+          icon={<ShieldCheck className="size-7 text-primary" />}
+          title={title}
+          description={description}
+          questionCount={questions.length}
+          timeLimitSeconds={timeLimitSeconds}
+          passingScore={passingScore}
+          startLabel="Begin Exam"
+          onStart={() => setStep({ tag: "exam" })}
+          readOnly={readOnly}
+        >
+          {instructions && (
+            <Alert className="text-left mb-6">
+              <AlertDescription>{instructions}</AlertDescription>
+            </Alert>
+          )}
+        </AssessmentIntro>
       </div>
     );
   }
@@ -169,12 +100,7 @@ export function ExamModule({
   // ─── Exam Screen ───
   if (step.tag === "exam") {
     return (
-      <div
-        ref={contentRef}
-        tabIndex={-1}
-        className={cn("outline-none", className)}
-        style={style}
-      >
+      <div ref={contentRef} tabIndex={-1} className={cn("outline-none", className)} style={style}>
         <ExamSession
           questions={questions}
           timeLimitSeconds={timeLimitSeconds}
@@ -185,6 +111,7 @@ export function ExamModule({
           confirmBeforeSubmit
           examTitle={title}
           onSubmit={handleSubmit}
+          readOnly={readOnly}
         />
       </div>
     );
@@ -192,94 +119,33 @@ export function ExamModule({
 
   // ─── Results Screen ───
   const { result } = step;
-  const passed = result.passed;
 
   return (
-    <div
-      ref={contentRef}
-      tabIndex={-1}
-      className={cn("max-w-2xl mx-auto outline-none", className)}
-      style={style}
-    >
-      <Card>
-        <CardContent className="pt-8 pb-8">
-          {/* Score summary */}
-          <div className="text-center mb-8">
-            <ProgressRing
-              value={result.percentage}
-              size={140}
-              strokeWidth={10}
-              color={passed ? "var(--success)" : "var(--destructive)"}
-              className="mx-auto mb-4 text-foreground"
-            />
-            <Badge
-              variant={passed ? "success" : "destructive"}
-              className="text-sm px-3 py-1 mb-2"
-            >
-              {passed ? "Passed" : "Failed"}
+    <div ref={contentRef} tabIndex={-1} className={cn("max-w-2xl mx-auto outline-none", className)} style={style}>
+      <AssessmentResults
+        title={title}
+        percentage={result.percentage}
+        passed={result.passed}
+        correct={result.correct}
+        total={result.total}
+        timeElapsedSeconds={result.timeElapsedSeconds}
+        answers={result.answers}
+        questions={questions}
+        allowRetake={allowRetake}
+        onRetake={handleRetake}
+        retakeLabel="Retake Exam"
+        showReview={showReview}
+        readOnly={readOnly}
+        extraBadges={
+          result.wasAutoSubmitted ? (
+            <Badge variant="outline" className="text-sm px-3 py-1 mb-2 ml-2">
+              Auto-submitted
             </Badge>
-            {result.wasAutoSubmitted && (
-              <Badge variant="outline" className="text-sm px-3 py-1 mb-2 ml-2">
-                Auto-submitted
-              </Badge>
-            )}
-            <h2 className="text-xl font-bold text-foreground">{title}</h2>
-          </div>
-
-          {/* Stats grid */}
-          <div className="grid grid-cols-2 sm:grid-cols-4 gap-3 mb-8">
-            <StatCard
-              icon={<CheckCircle2 />}
-              label="Correct"
-              description="Questions answered right"
-              value={`${result.correct}/${result.total}`}
-            />
-            <StatCard
-              icon={<XCircle />}
-              label="Incorrect"
-              description="Questions to review"
-              value={`${result.total - result.correct}/${result.total}`}
-            />
-            <StatCard
-              icon={<Trophy />}
-              label="Score"
-              description="Overall percentage"
-              value={`${result.percentage}%`}
-            />
-            <StatCard
-              icon={<Clock />}
-              label="Time"
-              description="Total elapsed"
-              value={formatDuration(result.timeElapsedSeconds)}
-            />
-          </div>
-
-          {/* Actions */}
-          {allowRetake && (
-            <div className="flex justify-center mb-8">
-              <Button variant="outline" onClick={handleRetake}>
-                <RotateCcw className="size-4 mr-2" />
-                Retake Exam
-              </Button>
-            </div>
-          )}
-        </CardContent>
-      </Card>
-
-      {/* Per-question review */}
-      {showReview && (
-        <>
-          <Separator className="my-6" />
-          <h3 className="text-lg font-semibold text-foreground mb-4">
-            Question Review
-          </h3>
-          <AssessmentReview
-            questions={questions}
-            sessionAnswers={result.answers}
-            showCorrectAnswers
-          />
-        </>
-      )}
+          ) : null
+        }
+      />
     </div>
   );
 }
+
+export const ExamModule = withProGate(ExamModuleBase, "ExamModule");

package/src/modules/ExamModule/types.ts

@@ -1,5 +1,6 @@
 import type { ReactNode } from "react";
-import type { QuestionData, SessionAnswer } from "../../questions/types";
+import type { QuestionData } from "../../questions/types";
+import type { AssessmentResult } from "../_shared/types";
 
 /**
  * ExamModule — a formal timed exam experience with intro, exam, and results steps.
@@ -42,25 +43,15 @@ export interface ExamModuleProps {
   showReview?: boolean;
   /** Called when the exam is completed (submitted) */
   onComplete?: (result: ExamModuleResult) => void;
+  /** When true, disables interactions for preview/demo mode. @default false */
+  readOnly?: boolean;
   /** CSS class name for the root element */
   className?: string;
   /** Inline styles for the root element */
   style?: React.CSSProperties;
 }
 
-export interface ExamModuleResult {
-  /** The user's submitted answers */
-  answers: SessionAnswer[];
-  /** Number of correct answers */
-  correct: number;
-  /** Total number of gradable questions */
-  total: number;
-  /** Score as a percentage (0-100) */
-  percentage: number;
-  /** Whether the user passed (only meaningful when passingScore is set) */
-  passed: boolean;
-  /** Total time taken in seconds */
-  timeElapsedSeconds: number;
+export interface ExamModuleResult extends AssessmentResult {
   /** Whether the submission was triggered by timeout */
   wasAutoSubmitted: boolean;
 }

package/src/modules/FlashcardLab/FlashcardLab.tsx

@@ -17,6 +17,7 @@ import { Card, CardContent } from "../../ui/card";
 import { formatDuration } from "../../utils/format-duration";
 import { cn } from "../../lib/utils";
 import type { FlashcardData } from "../../flashcards/types";
+import { withProGate } from "../../license/withProGate";
 import type {
   FlashcardLabProps,
   FlashcardLabResult,
@@ -27,12 +28,13 @@ type InternalStep =
   | { tag: "study"; cards: FlashcardData[]; deckUids: string[]; shuffled: boolean }
   | { tag: "completion"; result: FlashcardLabResult };
 
-export function FlashcardLab({
-  decks,
+function FlashcardLabBase({
+  decks = [],
   showShuffleToggle = true,
   defaultShuffled = false,
   allowMultiSelect = true,
   onComplete,
+  readOnly = false,
   className,
   style,
 }: FlashcardLabProps) {
@@ -187,7 +189,7 @@ export function FlashcardLab({
           </div>
           <Button
             onClick={startStudying}
-            disabled={selectedUids.size === 0}
+            disabled={selectedUids.size === 0 || readOnly}
           >
             Start Studying
           </Button>
@@ -212,6 +214,7 @@ export function FlashcardLab({
           title={deckNames}
           shuffled={step.shuffled}
           onComplete={handleStudyComplete}
+          readOnly={readOnly}
         />
       </div>
     );
@@ -272,11 +275,11 @@ export function FlashcardLab({
       </div>
 
       <div className="flex justify-center gap-3">
-        <Button variant="outline" onClick={handlePickNewDeck}>
+        <Button variant="outline" onClick={handlePickNewDeck} disabled={readOnly}>
           <ArrowLeft className="size-4 mr-2" />
           Pick New Deck
         </Button>
-        <Button onClick={handleStudyAgain}>
+        <Button onClick={handleStudyAgain} disabled={readOnly}>
           <RotateCcw className="size-4 mr-2" />
           Study Again
         </Button>
@@ -286,3 +289,5 @@ export function FlashcardLab({
     </div>
   );
 }
+
+export const FlashcardLab = withProGate(FlashcardLabBase, "FlashcardLab");

package/src/modules/FlashcardLab/types.ts

@@ -27,6 +27,8 @@ export interface FlashcardLabProps {
   allowMultiSelect?: boolean;
   /** Called when the user completes a study session */
   onComplete?: (result: FlashcardLabResult) => void;
+  /** When true, disables interactions for preview/demo mode. @default false */
+  readOnly?: boolean;
   /** CSS class name for the root element */
   className?: string;
   /** Inline styles for the root element */

package/src/modules/GradeCenterModule/GradeCenterModule.tsx

@@ -10,6 +10,7 @@ import { Tabs, TabsList, TabsTrigger, TabsContent } from "../../ui/tabs";
 import { Separator } from "../../ui/separator";
 import { cn } from "../../lib/utils";
 import type { GradeItem } from "../../sections/GradebookTable/types";
+import { withProGate } from "../../license/withProGate";
 import type { GradeCenterModuleProps } from "./types";
 
 /**
@@ -19,14 +20,15 @@ import type { GradeCenterModuleProps } from "./types";
  * Uses a panel-based layout (like CoursePlayer) with tabs for Grades and Progress,
  * and a slide-in detail panel for reviewing individual assessments.
  */
-export function GradeCenterModule({
+function GradeCenterModuleBase({
   courseTitle,
-  gradeItems,
+  gradeItems = [],
   categories,
   overallGrade,
   showWeights,
   progressData,
   reviewData,
+  readOnly = false,
   className,
   style,
 }: GradeCenterModuleProps) {
@@ -147,6 +149,7 @@ export function GradeCenterModule({
               overallGrade={overallGrade}
               showWeights={showWeights}
               onItemClick={handleItemClick}
+              readOnly={readOnly}
             />
           </TabsContent>
 
@@ -167,3 +170,5 @@ export function GradeCenterModule({
     </div>
   );
 }
+
+export const GradeCenterModule = withProGate(GradeCenterModuleBase, "GradeCenterModule");

package/src/modules/GradeCenterModule/types.ts

@@ -56,6 +56,8 @@ export interface GradeCenterModuleProps {
       score?: AssessmentScore;
     }
   >;
+  /** When true, disables interactions for preview/demo mode. @default false */
+  readOnly?: boolean;
   /** CSS class name for the root element */
   className?: string;
   /** Inline styles for the root element */