@hydralms/components 0.1.3 → 0.3.0

package/src/modules/CertificateModule/types.ts

@@ -0,0 +1,49 @@
+import type { Requirement } from "../../sections/RequirementsChecklist/types";
+import type { CertificateVariant } from "../../sections/CertificateViewer/types";
+
+/**
+ * CertificateModule — a certificate-earning flow with requirements tracking
+ * and certificate display.
+ *
+ * Steps: Requirements (checklist + progress) → Certificate (CertificateViewer).
+ * The certificate step is only accessible when all requirements are met.
+ *
+ * @example
+ * <CertificateModule
+ *   courseTitle="React Fundamentals"
+ *   recipientName="Jane Smith"
+ *   organizationName="HydraLMS Academy"
+ *   requirements={requirements}
+ *   overallProgress={100}
+ * />
+ */
+export interface CertificateModuleProps {
+  /** Course or program title */
+  courseTitle: string;
+  /** Recipient's full name */
+  recipientName: string;
+  /** Issuing organization name */
+  organizationName: string;
+  /** Organization logo URL */
+  organizationLogo?: string;
+  /** Signatory information */
+  signatory?: { name: string; title: string };
+  /** Completion date (used on the certificate) */
+  completionDate?: string;
+  /** Certificate visual variant. @default "modern" */
+  certificateVariant?: CertificateVariant;
+  /** Completion requirements */
+  requirements: Requirement[];
+  /** Overall course progress (0-100). When omitted, derived from requirements completion. */
+  overallProgress?: number;
+  /** Called when a requirement item is clicked */
+  onRequirementClick?: (uid: string) => void;
+  /** Called when the certificate is first displayed. @default undefined */
+  onComplete?: () => 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;
+}

package/src/modules/CourseCatalogModule/CourseCatalogModule.tsx

@@ -0,0 +1,126 @@
+import { useState, useRef, useEffect } from "react";
+import { ArrowLeft } from "lucide-react";
+import { CourseCatalog } from "../../sections/CourseCatalog/CourseCatalog";
+import { EnrollmentWizard } from "../../sections/EnrollmentWizard/EnrollmentWizard";
+import { Button } from "../../ui/button";
+import { Card, CardContent } from "../../ui/card";
+import { cn } from "../../lib/utils";
+import { withProGate } from "../../license/withProGate";
+import type { CourseCatalogModuleProps } from "./types";
+
+type InternalStep =
+  | { tag: "browse" }
+  | { tag: "enroll"; courseUid: string };
+
+/**
+ * CourseCatalogModule — a browse-and-enroll course catalog module.
+ *
+ * Master-detail layout: CourseCatalog (browse) ↔ EnrollmentWizard (enroll).
+ * Clicking a course drills into the enrollment flow; a back button returns to browsing.
+ */
+function CourseCatalogModuleBase({
+  title,
+  courses = [],
+  categories = [],
+  enrollmentData,
+  onEnroll,
+  onCourseOpen,
+  readOnly = false,
+  className,
+  style,
+}: CourseCatalogModuleProps) {
+  const [step, setStep] = useState<InternalStep>({ tag: "browse" });
+  const contentRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    contentRef.current?.focus({ preventScroll: true });
+  }, [step.tag]);
+
+  function handleCourseClick(courseUid: string) {
+    if (enrollmentData?.[courseUid]) {
+      setStep({ tag: "enroll", courseUid });
+    } else {
+      onCourseOpen?.(courseUid);
+    }
+  }
+
+  function handleBack() {
+    setStep({ tag: "browse" });
+  }
+
+  function handleEnrollConfirm(courseUid: string) {
+    onEnroll(courseUid);
+    setStep({ tag: "browse" });
+  }
+
+  return (
+    <div
+      ref={contentRef}
+      tabIndex={-1}
+      className={cn("outline-none", className)}
+      style={style}
+    >
+      {title && step.tag === "browse" && (
+        <h2 className="text-xl font-bold text-foreground mb-4">{title}</h2>
+      )}
+
+      {step.tag === "enroll" ? (
+        /* --- Enrollment View --- */
+        <div>
+          <Button
+            variant="ghost"
+            size="sm"
+            onClick={handleBack}
+            className="mb-4"
+          >
+            <ArrowLeft className="size-4 mr-1.5" />
+            Back to Catalog
+          </Button>
+          {enrollmentData?.[step.courseUid] ? (
+            <EnrollmentWizard
+              course={enrollmentData[step.courseUid].course}
+              prerequisites={enrollmentData[step.courseUid].prerequisites}
+              onEnroll={handleEnrollConfirm}
+              onCancel={handleBack}
+            />
+          ) : (
+            /* Fallback when enrollment data is not yet available */
+            <Card>
+              <CardContent className="pt-6">
+                <h3 className="text-lg font-semibold text-foreground mb-2">
+                  {courses.find((c) => c.uid === step.courseUid)?.title ??
+                    "Course"}
+                </h3>
+                <p className="text-sm text-muted-foreground mb-4">
+                  Enrollment details are loading. You can enroll directly below.
+                </p>
+                <div className="flex gap-2">
+                  <Button variant="outline" onClick={handleBack}>
+                    Cancel
+                  </Button>
+                  <Button
+                    onClick={() => handleEnrollConfirm(step.courseUid)}
+                    disabled={readOnly}
+                  >
+                    Enroll Now
+                  </Button>
+                </div>
+              </CardContent>
+            </Card>
+          )}
+        </div>
+      ) : (
+        /* --- Browse View --- */
+        <CourseCatalog
+          courses={courses}
+          categories={categories}
+          onCourseClick={(course) => handleCourseClick(course.uid)}
+          onEnroll={(course) => handleCourseClick(course.uid)}
+          readOnly={readOnly}
+        />
+      )}
+    </div>
+  );
+}
+
+export const CourseCatalogModule = withProGate(CourseCatalogModuleBase, "CourseCatalogModule");

package/src/modules/CourseCatalogModule/types.ts

@@ -0,0 +1,47 @@
+import type { CourseInfo } from "../../sections/CourseCatalog/types";
+import type {
+  EnrollmentCourse,
+  Prerequisite,
+} from "../../sections/EnrollmentWizard/types";
+
+/**
+ * CourseCatalogModule — a browse-and-enroll course catalog module.
+ *
+ * Master-detail layout: CourseCatalog (browse) ↔ EnrollmentWizard (enroll).
+ * Clicking a course drills into the enrollment flow; a back button returns to browsing.
+ *
+ * @example
+ * <CourseCatalogModule
+ *   title="Course Catalog"
+ *   courses={courses}
+ *   categories={categories}
+ *   enrollmentData={enrollmentData}
+ *   onEnroll={(courseUid) => handleEnroll(courseUid)}
+ * />
+ */
+export interface CourseCatalogModuleProps {
+  /** Catalog title */
+  title?: string;
+  /** Courses to display */
+  courses: CourseInfo[];
+  /** Optional categories for filtering */
+  categories?: { uid: string; label: string }[];
+  /** Enrollment data keyed by course UID — provides course details and prerequisites for the enrollment wizard */
+  enrollmentData?: Record<
+    string,
+    {
+      course: EnrollmentCourse;
+      prerequisites?: Prerequisite[];
+    }
+  >;
+  /** Called when a user confirms enrollment */
+  onEnroll: (courseUid: string) => void;
+  /** Called when a course is opened (for lazy-loading enrollment data) */
+  onCourseOpen?: (courseUid: string) => 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;
+}

package/src/modules/CoursePlayer/CoursePlayer.tsx

@@ -1,11 +1,18 @@
-import { useState, useMemo } from "react";
+import { useCallback, useState, useMemo, useRef, useEffect } from "react";
 import {
   ChevronLeft,
   ChevronRight,
   Check,
-  PanelLeftClose,
   PanelLeft,
 } from "lucide-react";
+import {
+  Drawer,
+  DrawerContent,
+  DrawerHeader,
+  DrawerBody,
+  DrawerTitle,
+  DrawerClose,
+} from "../../ui/drawer";
 import { CourseOutline } from "../../sections/CourseOutline/CourseOutline";
 import { LessonPage } from "../../sections/LessonPage/LessonPage";
 import { LecturePlayer } from "../../sections/LecturePlayer/LecturePlayer";
@@ -13,23 +20,13 @@ import { PracticeQuiz } from "../../sections/PracticeQuiz/PracticeQuiz";
 import { EmptyState } from "../../common";
 import { Progress } from "../../ui/progress";
 import { Button } from "../../ui/button";
+import { flattenLeaves } from "../../utils/flatten-leaves";
 import { cn } from "../../lib/utils";
 import type { CurriculumItem } from "../../curriculum/types";
+import { withProGate } from "../../license/withProGate";
 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({
+function CoursePlayerBase({
   courseTitle,
   curriculum,
   progress,
@@ -42,6 +39,7 @@ export function CoursePlayer({
   className,
   style,
 }: CoursePlayerProps) {
+  const contentRef = useRef<HTMLDivElement>(null);
   const leafUids = useMemo(() => flattenLeaves(curriculum), [curriculum]);
   const itemMap = useMemo(
     () => new Map(items.map((item) => [item.uid, item])),
@@ -74,29 +72,47 @@ export function CoursePlayer({
 
   const activeItem = itemMap.get(activeUid);
 
-  function navigateTo(uid: string) {
+  const videoConfig = useMemo(
+    () => activeItem?.type === "video"
+      ? { src: activeItem.src, poster: activeItem.poster, title: activeItem.title }
+      : null,
+    [activeItem],
+  );
+
+  useEffect(() => {
+    contentRef.current?.focus({ preventScroll: true });
+  }, [activeUid]);
+
+  const onItemChangeRef = useRef(onItemChange);
+  onItemChangeRef.current = onItemChange;
+  const onItemCompleteRef = useRef(onItemComplete);
+  onItemCompleteRef.current = onItemComplete;
+
+  const navigateTo = useCallback((uid: string) => {
     setActiveUid(uid);
-    onItemChange?.(uid);
-  }
+    onItemChangeRef.current?.(uid);
+  }, []);
 
-  function handleItemClick(item: CurriculumItem) {
+  const handleItemClick = useCallback((item: CurriculumItem) => {
     if (!item.children || item.children.length === 0) {
       navigateTo(item.uid);
     }
-  }
+  }, [navigateTo]);
 
-  function handleMarkComplete() {
+  const handleMarkComplete = useCallback(() => {
     setCompletedUids((prev) => new Set(prev).add(activeUid));
-    onItemComplete?.(activeUid);
-  }
+    onItemCompleteRef.current?.(activeUid);
+  }, [activeUid]);
 
-  function handleNext() {
-    if (hasNext) navigateTo(leafUids[currentIndex + 1]);
-  }
+  const handleNext = useCallback(() => {
+    const idx = leafUids.indexOf(activeUid);
+    if (idx < leafUids.length - 1) navigateTo(leafUids[idx + 1]);
+  }, [leafUids, activeUid, navigateTo]);
 
-  function handlePrevious() {
-    if (hasPrevious) navigateTo(leafUids[currentIndex - 1]);
-  }
+  const handlePrevious = useCallback(() => {
+    const idx = leafUids.indexOf(activeUid);
+    if (idx > 0) navigateTo(leafUids[idx - 1]);
+  }, [leafUids, activeUid, navigateTo]);
 
   // Build combined progress for CourseOutline
   const combinedProgress = useMemo(() => {
@@ -121,45 +137,40 @@ export function CoursePlayer({
       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">
+      {/* Sidebar Drawer */}
+      <Drawer open={sidebarOpen} onOpenChange={setSidebarOpen} side="left">
+        <DrawerContent size="sm" scrollLock={false}>
+          <DrawerHeader className="flex-row items-center justify-between">
+            <DrawerTitle 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>
-      )}
+            </DrawerTitle>
+            <DrawerClose />
+          </DrawerHeader>
+          <DrawerBody className="px-2 pb-2">
+            <CourseOutline
+              items={curriculum}
+              progress={combinedProgress}
+              courseTitle={courseTitle}
+              activeItemUid={activeUid}
+              onItemClick={handleItemClick}
+              readOnly={readOnly}
+            />
+          </DrawerBody>
+        </DrawerContent>
+      </Drawer>
 
       {/* 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>
-          )}
+          <Button
+            variant="ghost"
+            size="sm"
+            className="size-7 p-0 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"}
@@ -171,9 +182,9 @@ export function CoursePlayer({
         </div>
 
         {/* Content */}
-        <div className="flex-1 overflow-y-auto p-6">
+        <div ref={contentRef} tabIndex={-1} className="flex-1 overflow-y-auto p-6 outline-none">
           {activeItem ? (
-            renderContent(activeItem, readOnly, handleMarkComplete, isCurrentCompleted, handleNext, hasNext, nextItem)
+            renderContent(activeItem, readOnly, handleMarkComplete, isCurrentCompleted, handleNext, hasNext, nextItem, videoConfig)
           ) : (
             <EmptyState
               title="No content selected"
@@ -237,6 +248,7 @@ function renderContent(
   onNext: () => void,
   hasNext: boolean,
   nextItem: CoursePlayerItem | null | undefined,
+  videoConfig: { src: string; poster?: string; title: string } | null,
 ) {
   switch (item.type) {
     case "lesson":
@@ -254,11 +266,8 @@ function renderContent(
     case "video":
       return (
         <LecturePlayer
-          video={{
-            src: item.src,
-            poster: item.poster,
-            title: item.title,
-          }}
+          video={videoConfig ?? { src: "", title: item.title }}
+          onComplete={isCompleted ? undefined : onMarkComplete}
         />
       );
     case "quiz":
@@ -279,3 +288,5 @@ function renderContent(
       );
   }
 }
+
+export const CoursePlayer = withProGate(CoursePlayerBase, "CoursePlayer");

package/src/modules/DiscussionModule/DiscussionModule.tsx

@@ -0,0 +1,145 @@
+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";
+
+/**
+ * DiscussionModule — a master-detail discussion forum with topic list and thread view.
+ *
+ * Panel-based layout: ForumBoard (topic listing) ↔ DiscussionThread (thread detail).
+ * Clicking a topic drills into the thread; a back button returns to the board.
+ */
+function DiscussionModuleBase({
+  forumTitle,
+  topics = [],
+  currentUser,
+  threads = {},
+  onCreateTopic,
+  onReply,
+  onToggleLike,
+  onMarkAnswer,
+  onTopicOpen,
+  readOnly,
+  className,
+  style,
+}: DiscussionModuleProps) {
+  const [activeTopicUid, setActiveTopicUid] = useState<string | null>(null);
+  const [searchQuery, setSearchQuery] = useState("");
+  const [sortOrder, setSortOrder] = useState<ForumSortOrder>("newest");
+  const contentRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    contentRef.current?.focus({ preventScroll: true });
+  }, [activeTopicUid]);
+
+  const onTopicOpenRef = useRef(onTopicOpen);
+  onTopicOpenRef.current = onTopicOpen;
+
+  const handleTopicClick = useCallback((topicUid: string) => {
+    setActiveTopicUid(topicUid);
+    onTopicOpenRef.current?.(topicUid);
+  }, []);
+
+  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}
+      tabIndex={-1}
+      className={cn("outline-none", className)}
+      style={style}
+    >
+      {activeTopicUid && activeThread ? (
+        /* ─── Thread View ─── */
+        <div>
+          <Button
+            variant="ghost"
+            size="sm"
+            onClick={handleBack}
+            className="mb-4"
+          >
+            <ArrowLeft className="size-4 mr-1.5" />
+            Back to Topics
+          </Button>
+          <DiscussionThread
+            title={activeTopic?.title ?? ""}
+            rootPost={activeThread.rootPost}
+            replies={activeThread.replies}
+            currentUser={currentUser}
+            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
+          title={forumTitle}
+          topics={topics}
+          currentUser={currentUser}
+          onTopicClick={handleTopicClick}
+          onCreateTopic={onCreateTopic}
+          sortOrder={sortOrder}
+          onSortChange={setSortOrder}
+          searchQuery={searchQuery}
+          onSearchChange={setSearchQuery}
+          readOnly={readOnly}
+        />
+      )}
+    </div>
+  );
+}
+
+export const DiscussionModule = withProGate(DiscussionModuleBase, "DiscussionModule");

package/src/modules/DiscussionModule/types.ts

@@ -0,0 +1,54 @@
+import type {
+  DiscussionUser,
+  DiscussionPost,
+} from "../../sections/DiscussionThread/types";
+import type { ForumTopic } from "../../sections/ForumBoard/types";
+
+/**
+ * DiscussionModule — a master-detail discussion forum with topic list and thread view.
+ *
+ * Panel-based layout: ForumBoard (topic list) ↔ DiscussionThread (thread detail).
+ * Clicking a topic drills into the thread; a back button returns to the board.
+ *
+ * @example
+ * <DiscussionModule
+ *   forumTitle="Class Discussion"
+ *   topics={topics}
+ *   threads={threadData}
+ *   currentUser={user}
+ *   onCreateTopic={(title, content) => createTopic(title, content)}
+ *   onReply={(topicUid, parentUid, content) => postReply(topicUid, parentUid, content)}
+ * />
+ */
+export interface DiscussionModuleProps {
+  /** Forum title */
+  forumTitle?: string;
+  /** List of discussion topics */
+  topics: ForumTopic[];
+  /** The currently authenticated user */
+  currentUser: DiscussionUser;
+  /** Thread data keyed by topic UID */
+  threads: Record<
+    string,
+    {
+      rootPost: DiscussionPost;
+      replies: DiscussionPost[];
+    }
+  >;
+  /** Called when a new topic is created */
+  onCreateTopic?: (title: string, content: string) => void;
+  /** Called when a reply is posted */
+  onReply?: (topicUid: string, parentUid: string, content: string) => void;
+  /** Called when a like is toggled */
+  onToggleLike?: (topicUid: string, postUid: string) => void;
+  /** Called when a post is marked as the answer */
+  onMarkAnswer?: (topicUid: string, postUid: string) => void;
+  /** Called when a topic is opened (for lazy loading thread data) */
+  onTopicOpen?: (topicUid: string) => void;
+  /** When true, disables all interactions */
+  readOnly?: boolean;
+  /** CSS class name for the root element */
+  className?: string;
+  /** Inline styles for the root element */
+  style?: React.CSSProperties;
+}