@hydralms/components 0.1.3 → 0.3.0

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

@@ -0,0 +1,185 @@
+import { useState, useRef, useEffect } from "react";
+import {
+  ClipboardList,
+  CheckCircle2,
+  HelpCircle,
+  RotateCcw,
+  Play,
+  Clock,
+} from "lucide-react";
+import { SurveyForm } from "../../sections/SurveyForm/SurveyForm";
+import { StatCard } from "../../progress/stat-card";
+import { Button } from "../../ui/button";
+import { Badge } from "../../ui/badge";
+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 =
+  | { tag: "intro" }
+  | { tag: "survey" }
+  | { tag: "thankYou"; result: SurveyModuleResult };
+
+/**
+ * SurveyModule — a complete survey experience with intro, form, and thank-you steps.
+ *
+ * Steps: Intro → SurveyForm → Thank You with response stats.
+ */
+function SurveyModuleBase({
+  title,
+  description,
+  questions = [],
+  requireAll = false,
+  showProgress = true,
+  thankYouTitle = "Thank You!",
+  thankYouMessage,
+  onComplete,
+  allowRestart = false,
+  readOnly = false,
+  className,
+  style,
+}: SurveyModuleProps) {
+  const [step, setStep] = useState<InternalStep>({ tag: "intro" });
+  const startTimeRef = useRef<number | null>(null);
+  const contentRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    contentRef.current?.focus({ preventScroll: true });
+  }, [step.tag]);
+
+  function handleSubmit(answers: SurveyAnswer[]) {
+    const elapsed = startTimeRef.current
+      ? Math.floor((Date.now() - startTimeRef.current) / 1000)
+      : 0;
+    const result: SurveyModuleResult = {
+      answers,
+      totalQuestions: questions.length,
+      answeredCount: answers.length,
+      timeElapsedSeconds: elapsed,
+    };
+    setStep({ tag: "thankYou", result });
+    onComplete?.(result);
+  }
+
+  function handleRestart() {
+    startTimeRef.current = null;
+    setStep({ tag: "intro" });
+  }
+
+  function handleStart() {
+    startTimeRef.current = Date.now();
+    setStep({ tag: "survey" });
+  }
+
+  // ─── 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">
+              <ClipboardList 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>
+            )}
+            <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>
+            </div>
+            <Button size="lg" onClick={handleStart} disabled={readOnly}>
+              <Play className="size-4 mr-2" />
+              Begin Survey
+            </Button>
+          </CardContent>
+        </Card>
+      </div>
+    );
+  }
+
+  // ─── Survey Screen ───
+  if (step.tag === "survey") {
+    return (
+      <div
+        ref={contentRef}
+        tabIndex={-1}
+        className={cn("outline-none", className)}
+        style={style}
+      >
+        <SurveyForm
+          title={title}
+          questions={questions}
+          requireAll={requireAll}
+          showProgress={showProgress}
+          onSubmit={handleSubmit}
+          readOnly={readOnly}
+        />
+      </div>
+    );
+  }
+
+  // ─── Thank You Screen ───
+  const { result } = step;
+
+  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-success/10 flex items-center justify-center">
+            <CheckCircle2 className="size-7 text-success" />
+          </div>
+          <h2 className="text-2xl font-bold text-foreground mb-2">
+            {thankYouTitle}
+          </h2>
+          <p className="text-muted-foreground mb-6 max-w-md mx-auto">
+            {thankYouMessage ?? "Your responses have been recorded. Thank you for your feedback!"}
+          </p>
+
+          {/* Stats */}
+          <div className="grid grid-cols-2 gap-3 max-w-sm mx-auto mb-6">
+            <StatCard
+              icon={<HelpCircle />}
+              label="Answered"
+              description="Questions completed"
+              value={`${result.answeredCount}/${result.totalQuestions}`}
+            />
+            <StatCard
+              icon={<Clock />}
+              label="Time"
+              description="Total elapsed"
+              value={formatDuration(result.timeElapsedSeconds)}
+            />
+          </div>
+
+          {/* Actions */}
+          {allowRestart && (
+            <Button variant="outline" onClick={handleRestart} disabled={readOnly}>
+              <RotateCcw className="size-4 mr-2" />
+              Take Again
+            </Button>
+          )}
+        </CardContent>
+      </Card>
+    </div>
+  );
+}
+
+export const SurveyModule = withProGate(SurveyModuleBase, "SurveyModule");

package/src/modules/SurveyModule/types.ts

@@ -0,0 +1,53 @@
+import type { SurveyQuestion, SurveyAnswer } from "../../sections/SurveyForm/types";
+
+/**
+ * SurveyModule — a complete survey experience with intro, form, and thank-you steps.
+ *
+ * Wraps SurveyForm with a welcoming intro screen and a thank-you completion
+ * screen showing response stats.
+ *
+ * @example
+ * <SurveyModule
+ *   title="Course Evaluation"
+ *   description="Help us improve this course."
+ *   questions={surveyQuestions}
+ *   onComplete={(result) => submitSurvey(result)}
+ * />
+ */
+export interface SurveyModuleProps {
+  /** Survey title displayed on the intro and form screens */
+  title: string;
+  /** Survey description displayed on the intro screen */
+  description?: string;
+  /** Survey questions */
+  questions: SurveyQuestion[];
+  /** Whether all questions must be answered before submit. @default false */
+  requireAll?: boolean;
+  /** Whether to show a progress indicator in the survey form. @default true */
+  showProgress?: boolean;
+  /** Custom title for the thank-you screen. @default "Thank You!" */
+  thankYouTitle?: string;
+  /** Custom message for the thank-you screen */
+  thankYouMessage?: string;
+  /** Called when the survey is completed */
+  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 */
+  style?: React.CSSProperties;
+}
+
+export interface SurveyModuleResult {
+  /** The user's submitted answers */
+  answers: SurveyAnswer[];
+  /** Total number of questions */
+  totalQuestions: number;
+  /** Number of questions answered */
+  answeredCount: number;
+  /** Total time taken in seconds */
+  timeElapsedSeconds: number;
+}

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