@hydralms/components 0.1.3 → 0.2.0

package/src/modules/CertificateModule/CertificateModule.tsx

@@ -0,0 +1,161 @@
+import { useState, useRef, useEffect, useMemo } from "react";
+import { Award, ArrowLeft, PartyPopper } from "lucide-react";
+import { RequirementsChecklist } from "../../sections/RequirementsChecklist/RequirementsChecklist";
+import { CertificateViewer } from "../../sections/CertificateViewer/CertificateViewer";
+import { ProgressRing } from "../../progress/progress-ring";
+import { Button } from "../../ui/button";
+import { Card, CardContent } from "../../ui/card";
+import { cn } from "../../lib/utils";
+import type { CertificateModuleProps } from "./types";
+
+type InternalStep = { tag: "requirements" } | { tag: "certificate" };
+
+/**
+ * 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 completed.
+ */
+export function CertificateModule({
+  courseTitle,
+  recipientName,
+  organizationName,
+  organizationLogo,
+  signatory,
+  completionDate,
+  certificateVariant = "modern",
+  requirements,
+  overallProgress,
+  onRequirementClick,
+  onCertificateEarned,
+  className,
+  style,
+}: CertificateModuleProps) {
+  const { allComplete, completedCount } = useMemo(() => {
+    const count = requirements.filter((r) => r.completed).length;
+    return { allComplete: count === requirements.length, completedCount: count };
+  }, [requirements]);
+
+  const [step, setStep] = useState<InternalStep>({ tag: "requirements" });
+  const contentRef = useRef<HTMLDivElement>(null);
+  const earnedFiredRef = useRef(false);
+
+  useEffect(() => {
+    contentRef.current?.focus({ preventScroll: true });
+  }, [step.tag]);
+
+  // Fire onCertificateEarned once when certificate step is first shown
+  useEffect(() => {
+    if (step.tag === "certificate" && !earnedFiredRef.current) {
+      earnedFiredRef.current = true;
+      onCertificateEarned?.();
+    }
+  }, [step.tag, onCertificateEarned]);
+
+  // ─── Requirements Screen ───
+  if (step.tag === "requirements") {
+    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">
+            {/* Header with progress */}
+            <div className="text-center mb-6">
+              <ProgressRing
+                value={overallProgress}
+                size={100}
+                strokeWidth={8}
+                color={
+                  allComplete ? "var(--success)" : "var(--primary)"
+                }
+                className="mx-auto mb-4 text-foreground"
+              />
+              <h2 className="text-xl font-bold text-foreground mb-2">
+                {courseTitle}
+              </h2>
+              <p className="text-sm text-muted-foreground">
+                {allComplete
+                  ? "All requirements met — your certificate is ready!"
+                  : `${completedCount} of ${requirements.length} requirements complete`}
+              </p>
+            </div>
+
+            {/* Requirements checklist */}
+            <RequirementsChecklist
+              requirements={requirements}
+              onRequirementClick={onRequirementClick}
+              className="mb-6"
+            />
+
+            {/* View Certificate button */}
+            {allComplete && (
+              <div className="text-center mt-6">
+                <Button
+                  size="lg"
+                  onClick={() => setStep({ tag: "certificate" })}
+                >
+                  <Award className="size-4 mr-2" />
+                  View Certificate
+                </Button>
+              </div>
+            )}
+          </CardContent>
+        </Card>
+      </div>
+    );
+  }
+
+  // ─── Certificate Screen ───
+  return (
+    <div
+      ref={contentRef}
+      tabIndex={-1}
+      className={cn("outline-none", className)}
+      style={style}
+    >
+      {/* Back link */}
+      <Button
+        variant="ghost"
+        size="sm"
+        onClick={() => setStep({ tag: "requirements" })}
+        className="mb-4"
+      >
+        <ArrowLeft className="size-4 mr-1.5" />
+        Back to Requirements
+      </Button>
+
+      {/* Congratulations header */}
+      <div className="text-center mb-8">
+        <div className="mx-auto mb-4 w-14 h-14 rounded-full bg-success/10 flex items-center justify-center">
+          <PartyPopper className="size-7 text-success" />
+        </div>
+        <h2 className="text-2xl font-bold text-foreground mb-2">
+          Congratulations!
+        </h2>
+        <p className="text-muted-foreground">
+          You&apos;ve completed all requirements for{" "}
+          <span className="font-medium text-foreground">{courseTitle}</span>
+        </p>
+      </div>
+
+      {/* Certificate */}
+      <CertificateViewer
+        recipientName={recipientName}
+        courseTitle={courseTitle}
+        completionDate={
+          completionDate ?? new Date().toISOString().split("T")[0]
+        }
+        organizationName={organizationName}
+        organizationLogo={organizationLogo}
+        signatory={signatory}
+        variant={certificateVariant}
+        showActions
+      />
+    </div>
+  );
+}

package/src/modules/CertificateModule/types.ts

@@ -0,0 +1,47 @@
+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) */
+  overallProgress: number;
+  /** Called when a requirement item is clicked */
+  onRequirementClick?: (uid: string) => void;
+  /** Called when the certificate screen is first displayed */
+  onCertificateEarned?: () => void;
+  /** 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 { 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,22 +20,11 @@ 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 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,
@@ -42,6 +38,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,6 +71,10 @@ export function CoursePlayer({
 
   const activeItem = itemMap.get(activeUid);
 
+  useEffect(() => {
+    contentRef.current?.focus({ preventScroll: true });
+  }, [activeUid]);
+
   function navigateTo(uid: string) {
     setActiveUid(uid);
     onItemChange?.(uid);
@@ -121,45 +122,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,7 +167,7 @@ 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)
           ) : (

package/src/modules/DiscussionModule/DiscussionModule.tsx

@@ -0,0 +1,110 @@
+import { useState, useRef, useEffect } from "react";
+import { ArrowLeft } from "lucide-react";
+import { ForumBoard } from "../../sections/ForumBoard/ForumBoard";
+import { DiscussionThread } from "../../sections/DiscussionThread/DiscussionThread";
+import { Button } from "../../ui/button";
+import { cn } from "../../lib/utils";
+import type { ForumSortOrder } from "../../sections/ForumBoard/types";
+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.
+ */
+export function DiscussionModule({
+  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]);
+
+  function handleTopicClick(topicUid: string) {
+    setActiveTopicUid(topicUid);
+    onTopicOpen?.(topicUid);
+  }
+
+  function handleBack() {
+    setActiveTopicUid(null);
+  }
+
+  const activeThread = activeTopicUid ? threads[activeTopicUid] : null;
+  const activeTopic = activeTopicUid
+    ? topics.find((t) => t.uid === activeTopicUid)
+    : null;
+
+  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={(parentUid, content) =>
+              onReply?.(activeTopicUid, parentUid, content)
+            }
+            onToggleLike={
+              onToggleLike
+                ? (postUid) => onToggleLike(activeTopicUid, postUid)
+                : undefined
+            }
+            onMarkAnswer={
+              onMarkAnswer
+                ? (postUid) => onMarkAnswer(activeTopicUid, postUid)
+                : undefined
+            }
+            readOnly={readOnly}
+          />
+        </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>
+  );
+}

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