@hydralms/components 0.2.0 → 0.3.1

package/src/modules/StudentProfileModule/StudentProfileModule.tsx

@@ -0,0 +1,289 @@
+import { useState, useRef, useEffect } from "react";
+import { ArrowLeft, User, BookOpen, Trophy, Award } from "lucide-react";
+import { StudentProfile } from "../../sections/StudentProfile/StudentProfile";
+import { CertificateViewer } from "../../sections/CertificateViewer/CertificateViewer";
+import { AchievementBadge } from "../../progress/achievement-badge";
+import { ProgressRing } from "../../progress/progress-ring";
+import { UserAvatar } from "../../social/user-avatar";
+import { Button } from "../../ui/button";
+import { Card, CardContent } from "../../ui/card";
+import { Badge } from "../../ui/badge";
+import { Tabs, TabsList, TabsTrigger, TabsContent } from "../../ui/tabs";
+import { Separator } from "../../ui/separator";
+import { cn } from "../../lib/utils";
+import { formatTimestamp } from "../../utils/format-timestamp";
+import { withProGate } from "../../license/withProGate";
+import type { StudentProfileModuleProps } from "./types";
+
+/**
+ * StudentProfileModule — a tabbed student profile page with certificate drill-down.
+ *
+ * Uses a tabbed layout with Profile, Courses, Achievements, and Certificates tabs.
+ * Clicking a certificate (when certificateData is provided) drills down into a
+ * full CertificateViewer with a back button to return to the tabbed view.
+ */
+function StudentProfileModuleBase({
+  student,
+  enrolledCourses = [],
+  achievements = [],
+  certificates = [],
+  stats,
+  onCourseClick,
+  certificateData,
+  readOnly = false,
+  className,
+  style,
+}: StudentProfileModuleProps) {
+  const [drillDownCertUid, setDrillDownCertUid] = useState<string | null>(null);
+  const contentRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    contentRef.current?.focus({ preventScroll: true });
+  }, [drillDownCertUid]);
+
+  function handleCertificateClick(certUid: string) {
+    if (readOnly) return;
+    if (certificateData?.[certUid]) {
+      setDrillDownCertUid(certUid);
+    }
+  }
+
+  function handleBack() {
+    setDrillDownCertUid(null);
+  }
+
+  const drillDownData = drillDownCertUid
+    ? certificateData?.[drillDownCertUid]
+    : null;
+  const drillDownCert = drillDownCertUid
+    ? certificates.find((c) => c.uid === drillDownCertUid)
+    : null;
+
+  return (
+    <div
+      ref={contentRef}
+      tabIndex={-1}
+      className={cn("outline-none", className)}
+      style={style}
+    >
+      {/* Header */}
+      <div className="flex items-center gap-4 mb-6">
+        <UserAvatar
+          displayName={student.displayName}
+          avatarUrl={student.avatarUrl}
+          size="medium"
+        />
+        <div className="flex-1 min-w-0">
+          <div className="flex items-center gap-2 flex-wrap">
+            <h2 className="text-xl font-bold text-foreground">
+              {student.displayName}
+            </h2>
+            {student.role && (
+              <Badge variant="secondary">{student.role}</Badge>
+            )}
+          </div>
+          {student.email && (
+            <p className="text-sm text-muted-foreground">{student.email}</p>
+          )}
+        </div>
+      </div>
+
+      <Separator className="mb-6" />
+
+      {/* Drill-down view */}
+      {drillDownCert && drillDownData ? (
+        <div>
+          <Button
+            variant="ghost"
+            size="sm"
+            onClick={handleBack}
+            className="mb-4"
+          >
+            <ArrowLeft className="size-4 mr-1.5" />
+            Back to Profile
+          </Button>
+          <CertificateViewer {...drillDownData} showActions />
+        </div>
+      ) : (
+        <Tabs defaultValue="profile">
+          <TabsList className="mb-6">
+            <TabsTrigger value="profile">
+              <User className="size-4 mr-1.5" />
+              Profile
+            </TabsTrigger>
+            <TabsTrigger value="courses">
+              <BookOpen className="size-4 mr-1.5" />
+              Courses
+            </TabsTrigger>
+            <TabsTrigger value="achievements">
+              <Trophy className="size-4 mr-1.5" />
+              Achievements
+            </TabsTrigger>
+            <TabsTrigger value="certificates">
+              <Award className="size-4 mr-1.5" />
+              Certificates
+            </TabsTrigger>
+          </TabsList>
+
+          {/* Profile tab */}
+          <TabsContent value="profile">
+            <StudentProfile
+              student={student}
+              enrolledCourses={enrolledCourses}
+              achievements={achievements}
+              stats={stats}
+              onCourseClick={onCourseClick}
+              showCourses={false}
+              showAchievements={false}
+              readOnly
+            />
+          </TabsContent>
+
+          {/* Courses tab */}
+          <TabsContent value="courses">
+            {enrolledCourses.length > 0 ? (
+              <Card>
+                <CardContent className="p-0 divide-y divide-border">
+                  {enrolledCourses.map((course) => (
+                    <div
+                      key={course.uid}
+                      className={cn(
+                        "flex items-center gap-3 px-4 py-3 transition-colors",
+                        onCourseClick && !readOnly && "cursor-pointer hover:bg-muted/50",
+                      )}
+                      onClick={
+                        onCourseClick && !readOnly
+                          ? () => onCourseClick(course.uid)
+                          : undefined
+                      }
+                    >
+                      <ProgressRing
+                        value={course.progress}
+                        size={32}
+                        strokeWidth={3}
+                      />
+                      <div className="flex-1 min-w-0">
+                        <p className="text-sm font-medium text-foreground truncate">
+                          {course.title}
+                        </p>
+                        {course.lastAccessedAt && (
+                          <p className="text-xs text-muted-foreground">
+                            {formatTimestamp(course.lastAccessedAt)}
+                          </p>
+                        )}
+                      </div>
+                      <span className="text-xs text-muted-foreground whitespace-nowrap">
+                        {Math.round(course.progress)}%
+                      </span>
+                    </div>
+                  ))}
+                </CardContent>
+              </Card>
+            ) : (
+              <div className="py-12 text-center">
+                <BookOpen className="size-10 text-muted-foreground mx-auto mb-3" />
+                <p className="text-sm font-medium text-foreground">
+                  No courses yet
+                </p>
+                <p className="text-xs text-muted-foreground mt-1">
+                  Enrolled courses will appear here.
+                </p>
+              </div>
+            )}
+          </TabsContent>
+
+          {/* Achievements tab */}
+          <TabsContent value="achievements">
+            {achievements.length > 0 ? (
+              <div className="grid grid-cols-2 sm:grid-cols-3 lg:grid-cols-4 gap-2">
+                {achievements.map((achievement) => (
+                  <AchievementBadge
+                    key={achievement.uid}
+                    title={achievement.name}
+                    description={achievement.description}
+                    icon={
+                      achievement.iconUrl ? (
+                        <img
+                          src={achievement.iconUrl}
+                          alt={achievement.name}
+                          className="w-12 h-12"
+                        />
+                      ) : undefined
+                    }
+                    earnedDate={achievement.earnedAt}
+                  />
+                ))}
+              </div>
+            ) : (
+              <div className="py-12 text-center">
+                <Trophy className="size-10 text-muted-foreground mx-auto mb-3" />
+                <p className="text-sm font-medium text-foreground">
+                  No achievements yet
+                </p>
+                <p className="text-xs text-muted-foreground mt-1">
+                  Achievements will appear here as they are earned.
+                </p>
+              </div>
+            )}
+          </TabsContent>
+
+          {/* Certificates tab */}
+          <TabsContent value="certificates">
+            {certificates.length > 0 ? (
+              <Card>
+                <CardContent className="p-0 divide-y divide-border">
+                  {certificates.map((cert) => (
+                    <div
+                      key={cert.uid}
+                      className={cn(
+                        "flex items-center gap-3 px-4 py-3 transition-colors",
+                        certificateData?.[cert.uid] &&
+                          !readOnly &&
+                          "cursor-pointer hover:bg-muted/50",
+                      )}
+                      onClick={
+                        certificateData?.[cert.uid] && !readOnly
+                          ? () => handleCertificateClick(cert.uid)
+                          : undefined
+                      }
+                    >
+                      <div className="w-9 h-9 rounded-lg bg-primary/10 flex items-center justify-center text-primary">
+                        <Award size={20} />
+                      </div>
+                      <div className="flex-1 min-w-0">
+                        <p className="text-sm font-medium text-foreground truncate">
+                          {cert.courseName}
+                        </p>
+                        <p className="text-xs text-muted-foreground">
+                          Issued{" "}
+                          {new Date(cert.issuedAt).toLocaleDateString()}
+                        </p>
+                      </div>
+                      {certificateData?.[cert.uid] && (
+                        <Badge variant="secondary" className="text-xs">
+                          View
+                        </Badge>
+                      )}
+                    </div>
+                  ))}
+                </CardContent>
+              </Card>
+            ) : (
+              <div className="py-12 text-center">
+                <Award className="size-10 text-muted-foreground mx-auto mb-3" />
+                <p className="text-sm font-medium text-foreground">
+                  No certificates yet
+                </p>
+                <p className="text-xs text-muted-foreground mt-1">
+                  Certificates will appear here once courses are completed.
+                </p>
+              </div>
+            )}
+          </TabsContent>
+        </Tabs>
+      )}
+    </div>
+  );
+}
+
+export const StudentProfileModule = withProGate(StudentProfileModuleBase, "StudentProfileModule");

package/src/modules/StudentProfileModule/types.ts

@@ -0,0 +1,45 @@
+import type {
+  StudentInfo,
+  EnrolledCourse,
+  ProfileAchievement,
+  ProfileCertificate,
+} from "../../sections/StudentProfile/types";
+import type { CertificateViewerProps } from "../../sections/CertificateViewer/types";
+
+/**
+ * StudentProfileModule — a tabbed student profile page with certificate drill-down.
+ *
+ * Combines StudentProfile, course list, achievements, and CertificateViewer
+ * in a tabbed layout with drill-down into individual certificates.
+ *
+ * @example
+ * <StudentProfileModule
+ *   student={{ uid: "s1", displayName: "Jane Doe" }}
+ *   enrolledCourses={courses}
+ *   achievements={badges}
+ *   certificates={certs}
+ *   certificateData={{ cert1: { recipientName: "Jane", courseTitle: "React 101", completionDate: "2025-01-01", organizationName: "Hydra Academy" } }}
+ * />
+ */
+export interface StudentProfileModuleProps {
+  /** Student information */
+  student: StudentInfo;
+  /** Enrolled courses */
+  enrolledCourses?: EnrolledCourse[];
+  /** Earned achievements */
+  achievements?: ProfileAchievement[];
+  /** Earned certificates */
+  certificates?: ProfileCertificate[];
+  /** Custom stat cards */
+  stats?: { label: string; value: string; icon?: React.ReactNode }[];
+  /** Called when a course is clicked */
+  onCourseClick?: (courseUid: string) => void;
+  /** Certificate data keyed by certificate UID — enables drill-down on click */
+  certificateData?: Record<string, CertificateViewerProps>;
+  /** 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/SurveyModule/SurveyModule.tsx

@@ -15,6 +15,7 @@ import { Card, CardContent } from "../../ui/card";
 import { formatDuration } from "../../utils/format-duration";
 import { cn } from "../../lib/utils";
 import type { SurveyAnswer } from "../../sections/SurveyForm/types";
+import { withProGate } from "../../license/withProGate";
 import type { SurveyModuleProps, SurveyModuleResult } from "./types";
 
 type InternalStep =
@@ -27,16 +28,17 @@ type InternalStep =
  *
  * Steps: Intro → SurveyForm → Thank You with response stats.
  */
-export function SurveyModule({
+function SurveyModuleBase({
   title,
   description,
-  questions,
+  questions = [],
   requireAll = false,
   showProgress = true,
   thankYouTitle = "Thank You!",
   thankYouMessage,
   onComplete,
   allowRestart = false,
+  readOnly = false,
   className,
   style,
 }: SurveyModuleProps) {
@@ -98,7 +100,7 @@ export function SurveyModule({
                 {questions.length} questions
               </Badge>
             </div>
-            <Button size="lg" onClick={handleStart}>
+            <Button size="lg" onClick={handleStart} disabled={readOnly}>
               <Play className="size-4 mr-2" />
               Begin Survey
             </Button>
@@ -123,6 +125,7 @@ export function SurveyModule({
           requireAll={requireAll}
           showProgress={showProgress}
           onSubmit={handleSubmit}
+          readOnly={readOnly}
         />
       </div>
     );
@@ -168,7 +171,7 @@ export function SurveyModule({
 
           {/* Actions */}
           {allowRestart && (
-            <Button variant="outline" onClick={handleRestart}>
+            <Button variant="outline" onClick={handleRestart} disabled={readOnly}>
               <RotateCcw className="size-4 mr-2" />
               Take Again
             </Button>
@@ -178,3 +181,5 @@ export function SurveyModule({
     </div>
   );
 }
+
+export const SurveyModule = withProGate(SurveyModuleBase, "SurveyModule");

package/src/modules/SurveyModule/types.ts

@@ -33,6 +33,8 @@ export interface SurveyModuleProps {
   onComplete?: (result: SurveyModuleResult) => void;
   /** Allow restarting the survey from the thank-you screen. @default false */
   allowRestart?: boolean;
+  /** 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/_shared/assessment-intro.tsx

@@ -0,0 +1,75 @@
+import type { ReactNode } from "react";
+import { HelpCircle, Clock, CheckCircle2, Play } from "lucide-react";
+import { Button } from "../../ui/button";
+import { Badge } from "../../ui/badge";
+import { Card, CardContent } from "../../ui/card";
+import { formatDuration } from "../../utils/format-duration";
+
+export interface AssessmentIntroProps {
+  icon: ReactNode;
+  title: string;
+  description?: string;
+  questionCount: number;
+  timeLimitSeconds?: number;
+  passingScore?: number;
+  startLabel: string;
+  onStart: () => void;
+  /** Extra content rendered between the description and metadata badges. */
+  children?: ReactNode;
+  /** When true, disables interactions for preview/demo mode. @default false */
+  readOnly?: boolean;
+}
+
+export function AssessmentIntro({
+  icon,
+  title,
+  description,
+  questionCount,
+  timeLimitSeconds,
+  passingScore,
+  startLabel,
+  onStart,
+  children,
+  readOnly = false,
+}: AssessmentIntroProps) {
+  return (
+    <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">
+          {icon}
+        </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>
+        )}
+
+        {children}
+
+        <div className="flex flex-wrap justify-center gap-2 mb-8">
+          <Badge variant="outline" className="gap-1.5">
+            <HelpCircle className="size-3.5" />
+            {questionCount} questions
+          </Badge>
+          {timeLimitSeconds != null && (
+            <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={onStart} disabled={readOnly}>
+          <Play className="size-4 mr-2" />
+          {startLabel}
+        </Button>
+      </CardContent>
+    </Card>
+  );
+}

package/src/modules/_shared/assessment-results.tsx

@@ -0,0 +1,133 @@
+import type { ReactNode } from "react";
+import { CheckCircle2, XCircle, Trophy, Clock, RotateCcw } from "lucide-react";
+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 { Separator } from "../../ui/separator";
+import { formatDuration } from "../../utils/format-duration";
+import { AssessmentReview } from "../../sections/AssessmentReview/AssessmentReview";
+import type { QuestionData, SessionAnswer } from "../../questions/types";
+
+export interface AssessmentResultsProps {
+  title: string;
+  percentage: number;
+  passed: boolean;
+  correct: number;
+  total: number;
+  timeElapsedSeconds: number;
+  answers: SessionAnswer[];
+  questions: QuestionData[];
+  /** Allow retaking the assessment. */
+  allowRetake?: boolean;
+  onRetake?: () => void;
+  retakeLabel?: string;
+  /** Show per-question review below the summary. */
+  showReview?: boolean;
+  /** Extra badges shown next to the pass/fail badge (e.g., "Auto-submitted"). */
+  extraBadges?: ReactNode;
+  /** When true, disables interactions for preview/demo mode. @default false */
+  readOnly?: boolean;
+}
+
+export function AssessmentResults({
+  title,
+  percentage,
+  passed,
+  correct,
+  total,
+  timeElapsedSeconds,
+  answers,
+  questions,
+  allowRetake,
+  onRetake,
+  retakeLabel = "Retake",
+  showReview = true,
+  extraBadges,
+  readOnly = false,
+}: AssessmentResultsProps) {
+  return (
+    <>
+      <Card>
+        <CardContent className="pt-8 pb-8">
+          {/* Score summary */}
+          <div className="text-center mb-8">
+            <ProgressRing
+              value={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"}
+            </Badge>
+            {extraBadges}
+            <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={`${correct}/${total}`}
+              accent="var(--success)"
+            />
+            <StatCard
+              icon={<XCircle />}
+              label="Incorrect"
+              description="Questions to review"
+              value={`${total - correct}/${total}`}
+              accent="var(--destructive)"
+            />
+            <StatCard
+              icon={<Trophy />}
+              label="Score"
+              description="Overall percentage"
+              value={`${percentage}%`}
+              accent="var(--palette-3)"
+            />
+            <StatCard
+              icon={<Clock />}
+              label="Time"
+              description="Total elapsed"
+              value={formatDuration(timeElapsedSeconds)}
+              accent="var(--palette-1)"
+            />
+          </div>
+
+          {/* Actions */}
+          {allowRetake && onRetake && !readOnly && (
+            <div className="flex justify-center mb-8">
+              <Button variant="outline" onClick={onRetake}>
+                <RotateCcw className="size-4 mr-2" />
+                {retakeLabel}
+              </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={answers}
+            showCorrectAnswers
+          />
+        </>
+      )}
+    </>
+  );
+}

package/src/modules/_shared/types.ts

@@ -0,0 +1,11 @@
+import type { SessionAnswer } from "../../questions/types";
+
+/** Shared result shape for scored assessment modules. */
+export interface AssessmentResult {
+  answers: SessionAnswer[];
+  correct: number;
+  total: number;
+  percentage: number;
+  passed: boolean;
+  timeElapsedSeconds: number;
+}

package/src/modules/_shared/use-timer.ts

@@ -0,0 +1,49 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+
+/**
+ * Manages an interval-based timer that runs while `active` is true.
+ * Returns elapsed seconds and a reset function.
+ */
+export function useTimer(active: boolean) {
+  const [timeElapsed, setTimeElapsed] = useState(0);
+  const startTimeRef = useRef<number | null>(null);
+  const intervalRef = useRef<ReturnType<typeof setInterval> | null>(null);
+  const timeElapsedRef = useRef(0);
+
+  useEffect(() => {
+    if (active) {
+      startTimeRef.current = Date.now();
+      intervalRef.current = setInterval(() => {
+        if (startTimeRef.current) {
+          const next = Math.floor((Date.now() - startTimeRef.current) / 1000);
+          if (next !== timeElapsedRef.current) {
+            timeElapsedRef.current = next;
+            setTimeElapsed(next);
+          }
+        }
+      }, 1000);
+    } else {
+      if (intervalRef.current) {
+        clearInterval(intervalRef.current);
+        intervalRef.current = null;
+      }
+    }
+    return () => {
+      if (intervalRef.current) clearInterval(intervalRef.current);
+    };
+  }, [active]);
+
+  const getFinalElapsed = useCallback(() => {
+    return startTimeRef.current
+      ? Math.floor((Date.now() - startTimeRef.current) / 1000)
+      : timeElapsedRef.current;
+  }, []);
+
+  const reset = useCallback(() => {
+    timeElapsedRef.current = 0;
+    setTimeElapsed(0);
+    startTimeRef.current = null;
+  }, []);
+
+  return { timeElapsed, getFinalElapsed, reset };
+}

package/src/modules/index.ts

@@ -34,3 +34,12 @@ export type { CertificateModuleProps } from "./CertificateModule/types";
 
 export { DiscussionModule } from "./DiscussionModule/DiscussionModule";
 export type { DiscussionModuleProps } from "./DiscussionModule/types";
+
+export { StudentDashboardModule } from "./StudentDashboardModule/StudentDashboardModule";
+export type { StudentDashboardModuleProps } from "./StudentDashboardModule/types";
+
+export { CourseCatalogModule } from "./CourseCatalogModule/CourseCatalogModule";
+export type { CourseCatalogModuleProps } from "./CourseCatalogModule/types";
+
+export { StudentProfileModule } from "./StudentProfileModule/StudentProfileModule";
+export type { StudentProfileModuleProps } from "./StudentProfileModule/types";