@hydralms/components 0.2.0 → 0.3.1

package/src/sections/StudentProfile/types.ts

@@ -0,0 +1,99 @@
+
+/**
+ * StudentProfile section — a student profile overview.
+ *
+ * Displays student info header, stat cards, enrolled courses list,
+ * achievements grid, and certificates list.
+ *
+ * @example
+ * <StudentProfile
+ *   student={{ uid: "s1", displayName: "Jane Doe", email: "jane@example.com" }}
+ *   enrolledCourses={courses}
+ *   achievements={badges}
+ *   onCourseClick={(uid) => navigate(`/courses/${uid}`)}
+ * />
+ */
+export interface StudentProfileProps {
+  /** Student information */
+  student: StudentInfo;
+  /** Enrolled courses */
+  enrolledCourses?: EnrolledCourse[];
+  /** Earned achievements */
+  achievements?: ProfileAchievement[];
+  /** Earned certificates */
+  certificates?: ProfileCertificate[];
+  /** Custom stat cards to display */
+  stats?: { label: string; value: string; icon?: React.ReactNode }[];
+  /** When false, hides the Enrolled Courses section. @default true */
+  showCourses?: boolean;
+  /** When false, hides the Achievements section. @default true */
+  showAchievements?: boolean;
+  /** Called when a course is clicked */
+  onCourseClick?: (courseUid: string) => void;
+  /** Called when a certificate is clicked */
+  onCertificateClick?: (certificateUid: string) => void;
+  /** When true, disables interactions */
+  readOnly?: boolean;
+  /** Render skeleton placeholders instead of content */
+  isLoading?: boolean;
+  /** Error message — renders an error state with optional retry */
+  error?: string | null;
+  /** Called when the user clicks retry in the error state */
+  onRetry?: () => void;
+  /** CSS class name for the root element */
+  className?: string;
+  /** Inline styles for the root element */
+  style?: React.CSSProperties;
+}
+
+export interface StudentInfo {
+  /** Unique identifier */
+  uid: string;
+  /** Display name */
+  displayName: string;
+  /** Avatar URL */
+  avatarUrl?: string;
+  /** Email address */
+  email?: string;
+  /** Short bio */
+  bio?: string;
+  /** Join date as ISO string */
+  joinedAt?: string;
+  /** Role label */
+  role?: string;
+}
+
+export interface EnrolledCourse {
+  /** Course UID */
+  uid: string;
+  /** Course title */
+  title: string;
+  /** Progress percentage (0-100) */
+  progress: number;
+  /** Last accessed as ISO string */
+  lastAccessedAt?: string;
+}
+
+export interface ProfileAchievement {
+  /** Unique identifier */
+  uid: string;
+  /** Achievement name */
+  name: string;
+  /** Achievement description */
+  description: string;
+  /** Icon URL */
+  iconUrl?: string;
+  /** Date earned as ISO string */
+  earnedAt: string;
+}
+
+export interface ProfileCertificate {
+  /** Unique identifier */
+  uid: string;
+  /** Course name */
+  courseName: string;
+  /** Date issued as ISO string */
+  issuedAt: string;
+  /** Certificate URL */
+  certificateUrl?: string;
+}

package/src/sections/SurveyForm/SurveyForm.tsx

@@ -1,16 +1,19 @@
 import { useState, useMemo } from "react";
 import { LikertScale, StarRating } from "../../feedback";
+
 import { Button } from "../../ui/button";
 import { Card, CardContent } from "../../ui/card";
 import { Progress } from "../../ui/progress";
 import { Separator } from "../../ui/separator";
+import { Skeleton } from "../../ui/skeleton";
 import { RichTextEditor } from "../../ui/rich-text-editor";
+import { SectionShell } from "../_shared/section-shell";
 import type { SurveyFormProps, SurveyAnswer } from "./types";
 
 export function SurveyForm({
   title,
   description,
-  questions,
+  questions = [],
   initialAnswers = [],
   onSubmit,
   onAnswerChange,
@@ -19,6 +22,9 @@ export function SurveyForm({
   submitLabel = "Submit Survey",
   isSubmitting = false,
   readOnly = false,
+  isLoading,
+  error,
+  onRetry,
   className,
   style,
 }: SurveyFormProps) {
@@ -40,11 +46,31 @@ export function SurveyForm({
     });
   }
 
-  function getAnswer(questionUid: string): SurveyAnswer | undefined {
-    return answers.find((a) => a.questionUid === questionUid);
-  }
+  const answerMap = useMemo(() => {
+    const map = new Map<string, SurveyAnswer>();
+    for (const a of answers) {
+      map.set(a.questionUid, a);
+    }
+    return map;
+  }, [answers]);
 
   return (
+    <SectionShell
+      isLoading={isLoading}
+      error={error}
+      onRetry={onRetry}
+      className={className}
+      style={style}
+      skeleton={
+        <>
+          <Skeleton className="h-6 w-48" />
+          <Skeleton className="h-2 w-full" />
+          <Skeleton className="h-16 w-full" />
+          <Skeleton className="h-16 w-full" />
+          <Skeleton className="h-16 w-full" />
+        </>
+      }
+    >
     <div className={className} style={style}>
       <p className="text-xl font-bold text-foreground mb-2">{title}</p>
       {description && (
@@ -66,7 +92,7 @@ export function SurveyForm({
       )}
 
       {questions.map((q, index) => {
-        const answer = getAnswer(q.uid);
+        const answer = answerMap.get(q.uid);
         return (
           <Card key={q.uid} className="mb-2"><CardContent className="pt-6">
             <p className="font-medium text-foreground mb-2">
@@ -179,5 +205,6 @@ export function SurveyForm({
         </Button>
       </div>
     </div>
+    </SectionShell>
   );
 }

package/src/sections/SurveyForm/types.ts

@@ -38,6 +38,12 @@ export interface SurveyFormProps {
   isSubmitting?: boolean;
   /** When true, all inputs are disabled */
   readOnly?: boolean;
+  /** Render skeleton placeholders instead of content */
+  isLoading?: boolean;
+  /** Error message — renders an error state with optional retry */
+  error?: string | null;
+  /** Called when the user clicks retry in the error state */
+  onRetry?: () => void;
   /** CSS class name for the root element */
   className?: string;
   /** Inline styles for the root element */

package/src/sections/_shared/merge-answers.ts

@@ -0,0 +1,22 @@
+import type { SessionAnswer } from "../../questions/types";
+
+/**
+ * Replaces all existing answers for `questionUid` with `rawAnswers`,
+ * then invokes an optional change callback with the merged array.
+ */
+export function mergeSessionAnswers(
+  prev: SessionAnswer[],
+  questionUid: string,
+  rawAnswers: { uid: string; content?: string }[],
+  onChange?: (merged: SessionAnswer[]) => void,
+): SessionAnswer[] {
+  const newAnswers: SessionAnswer[] = rawAnswers.map((a) => ({
+    uid: questionUid,
+    answerUid: a.uid,
+    content: a.content,
+  }));
+  const filtered = prev.filter((a) => a.uid !== questionUid);
+  const merged = [...filtered, ...newAnswers];
+  onChange?.(merged);
+  return merged;
+}

package/src/sections/_shared/section-shell.tsx

@@ -0,0 +1,64 @@
+import type { ReactNode } from "react";
+import { AlertCircle } from "lucide-react";
+import { EmptyState } from "../../common";
+import { Button } from "../../ui/button";
+import { cn } from "../../lib/utils";
+
+export interface SectionShellProps {
+  isLoading?: boolean;
+  error?: string | null;
+  onRetry?: () => void;
+  /** Skeleton placeholder rendered when `isLoading` is true. */
+  skeleton?: ReactNode;
+  /** Extra class merged into the loading wrapper (default `"space-y-4"`). */
+  loadingClassName?: string;
+  className?: string;
+  style?: React.CSSProperties;
+  children: ReactNode;
+}
+
+/**
+ * Shared wrapper that handles loading skeleton and error states
+ * so individual sections don't repeat the same early-return blocks.
+ *
+ * When neither loading nor error, renders children directly (no extra wrapper).
+ */
+export function SectionShell({
+  isLoading,
+  error,
+  onRetry,
+  skeleton,
+  loadingClassName = "space-y-4",
+  className,
+  style,
+  children,
+}: SectionShellProps) {
+  if (isLoading) {
+    return (
+      <div className={cn(loadingClassName, className)} style={style}>
+        {skeleton}
+      </div>
+    );
+  }
+
+  if (error) {
+    return (
+      <div className={cn("py-12", className)} style={style}>
+        <EmptyState
+          icon={<AlertCircle className="size-10 text-destructive" />}
+          title="Something went wrong"
+          description={error}
+          action={
+            onRetry ? (
+              <Button variant="outline" onClick={onRetry}>
+                Retry
+              </Button>
+            ) : undefined
+          }
+        />
+      </div>
+    );
+  }
+
+  return <>{children}</>;
+}

package/src/sections/_shared/use-assessment-session.ts

@@ -0,0 +1,125 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import type { QuestionNavigatorItem } from "../../assessment-toolbar/types";
+import type { QuestionData, QuestionMaterial, SessionAnswer } from "../../questions/types";
+import { mergeSessionAnswers } from "./merge-answers";
+
+export interface UseAssessmentSessionOptions {
+  questions: QuestionData[];
+  initialAnswers?: SessionAnswer[];
+  onAnswerChange?: (answers: SessionAnswer[]) => void;
+  questionMaterials?: QuestionMaterial[];
+}
+
+export function useAssessmentSession({
+  questions,
+  initialAnswers = [],
+  onAnswerChange,
+  questionMaterials,
+}: UseAssessmentSessionOptions) {
+  const [currentIndex, setCurrentIndex] = useState(0);
+  const [sessionAnswers, setSessionAnswers] = useState<SessionAnswer[]>(initialAnswers);
+  const [flaggedUids, setFlaggedUids] = useState<Set<string>>(new Set());
+  const [materialsOpen, setMaterialsOpen] = useState(false);
+  const questionAreaRef = useRef<HTMLDivElement>(null);
+  const isFirstRender = useRef(true);
+
+  // Refs for stable callbacks
+  const questionsRef = useRef(questions);
+  questionsRef.current = questions;
+  const currentIndexRef = useRef(currentIndex);
+  currentIndexRef.current = currentIndex;
+  const onAnswerChangeRef = useRef(onAnswerChange);
+  onAnswerChangeRef.current = onAnswerChange;
+
+  const currentQuestion = questions[currentIndex];
+
+  // Focus question area on navigation (skip first render)
+  useEffect(() => {
+    if (isFirstRender.current) {
+      isFirstRender.current = false;
+      return;
+    }
+    questionAreaRef.current?.focus();
+  }, [currentIndex]);
+
+  const currentQuestionAnswers = useMemo(
+    () =>
+      currentQuestion
+        ? sessionAnswers.filter((a) => a.uid === currentQuestion.uid)
+        : [],
+    [sessionAnswers, currentQuestion],
+  );
+
+  const currentMaterials = useMemo(
+    () => questionMaterials?.filter((m) => m.questionUid === currentQuestion?.uid) ?? [],
+    [questionMaterials, currentQuestion],
+  );
+
+  const navigatorItems = useMemo<QuestionNavigatorItem[]>(
+    () =>
+      questions.map((q, idx) => ({
+        uid: q.uid,
+        sequence: idx,
+        isFlagged: flaggedUids.has(q.uid),
+        isAnswered: sessionAnswers.some((a) => a.uid === q.uid),
+        isSkipped: false,
+      })),
+    [questions, sessionAnswers, flaggedUids],
+  );
+
+  const handleAnswer = useCallback(
+    (rawAnswers: { uid: string; content?: string }[]) => {
+      const q = questionsRef.current[currentIndexRef.current];
+      if (!q) return;
+      setSessionAnswers((prev) =>
+        mergeSessionAnswers(prev, q.uid, rawAnswers, onAnswerChangeRef.current),
+      );
+    },
+    [],
+  );
+
+  const handleNavigate = useCallback(
+    (uid: string) => {
+      const idx = questions.findIndex((q) => q.uid === uid);
+      if (idx !== -1) setCurrentIndex(idx);
+    },
+    [questions],
+  );
+
+  const handleToggleFlag = useCallback((uid: string) => {
+    setFlaggedUids((prev) => {
+      const next = new Set(prev);
+      if (next.has(uid)) next.delete(uid);
+      else next.add(uid);
+      return next;
+    });
+  }, []);
+
+  const goNext = useCallback(() => {
+    setCurrentIndex((i) => Math.min(i + 1, questionsRef.current.length - 1));
+  }, []);
+
+  const goPrevious = useCallback(() => {
+    setCurrentIndex((i) => Math.max(i - 1, 0));
+  }, []);
+
+  return {
+    currentIndex,
+    currentQuestion,
+    sessionAnswers,
+    flaggedUids,
+    materialsOpen,
+    setMaterialsOpen,
+    questionAreaRef,
+    currentQuestionAnswers,
+    currentMaterials,
+    navigatorItems,
+    handleAnswer,
+    handleNavigate,
+    handleToggleFlag,
+    goNext,
+    goPrevious,
+    hasNext: currentIndex < questions.length - 1,
+    hasPrevious: currentIndex > 0,
+  };
+}

package/src/sections/index.ts

@@ -107,3 +107,43 @@ export type {
 
 export { ForumBoard } from "./ForumBoard/ForumBoard";
 export type { ForumBoardProps, ForumTopic, ForumSortOrder } from "./ForumBoard/types";
+
+export { EnrollmentWizard } from "./EnrollmentWizard/EnrollmentWizard";
+export type {
+  EnrollmentWizardProps,
+  EnrollmentCourse,
+  Prerequisite,
+} from "./EnrollmentWizard/types";
+
+export { CourseCatalog } from "./CourseCatalog/CourseCatalog";
+export type {
+  CourseCatalogProps,
+  CourseInfo,
+} from "./CourseCatalog/types";
+
+export { StudentProfile } from "./StudentProfile/StudentProfile";
+export type {
+  StudentProfileProps,
+  StudentInfo,
+  EnrolledCourse,
+  ProfileAchievement,
+  ProfileCertificate,
+} from "./StudentProfile/types";
+
+export { ContentAuthoringStudio } from "./ContentAuthoringStudio/ContentAuthoringStudio";
+export type {
+  ContentAuthoringStudioProps,
+  AuthoringBlock,
+} from "./ContentAuthoringStudio/types";
+
+export { AdaptiveLearningPath } from "./AdaptiveLearningPath/AdaptiveLearningPath";
+export type {
+  AdaptiveLearningPathProps,
+  PathNode,
+  PathNodeStatus,
+  PathNodeType,
+  PathSkill,
+  PathMilestone,
+  PathBranch,
+  PathProgress,
+} from "./AdaptiveLearningPath/types";

package/src/social/user-avatar.tsx

@@ -13,7 +13,7 @@ const ROLE_LABELS: Record<string, string> = {
 
 const ROLE_COLORS: Record<string, string> = {
   instructor: "var(--primary)",
-  ta: "var(--purple)",
+  ta: "var(--palette-0)",
   admin: "var(--destructive)",
   student: "var(--muted-foreground)",
 };
@@ -67,10 +67,14 @@ export function UserAvatar({
         )}
       </div>
       {showBadge && (
-        <span
-          className="absolute -bottom-0.5 -right-0.5 size-2.5 rounded-full border-2 border-background"
-          style={{ background: ROLE_COLORS[role] ?? "var(--muted-foreground)" }}
-        />
+        <>
+          <span
+            className="absolute -bottom-0.5 -right-0.5 size-2.5 rounded-full border-2 border-background"
+            style={{ background: ROLE_COLORS[role] ?? "var(--muted-foreground)" }}
+            aria-hidden="true"
+          />
+          <span className="sr-only">{ROLE_LABELS[role] ?? role}</span>
+        </>
       )}
     </div>
   );

package/src/styles/globals.css

@@ -1,40 +1,10 @@
-@import "tailwindcss";
-
-@custom-variant dark (&:is(.dark *));
-
-@theme inline {
-  --color-background: var(--background);
-  --color-foreground: var(--foreground);
-  --color-card: var(--card);
-  --color-card-foreground: var(--card-foreground);
-  --color-popover: var(--popover);
-  --color-popover-foreground: var(--popover-foreground);
-  --color-primary: var(--primary);
-  --color-primary-foreground: var(--primary-foreground);
-  --color-secondary: var(--secondary);
-  --color-secondary-foreground: var(--secondary-foreground);
-  --color-muted: var(--muted);
-  --color-muted-foreground: var(--muted-foreground);
-  --color-accent: var(--accent);
-  --color-accent-foreground: var(--accent-foreground);
-  --color-destructive: var(--destructive);
-  --color-destructive-foreground: var(--destructive-foreground);
-  --color-border: var(--border);
-  --color-input: var(--input);
-  --color-ring: var(--ring);
-  --color-success: var(--success);
-  --color-success-foreground: var(--success-foreground);
-  --color-warning: var(--warning);
-  --color-warning-foreground: var(--warning-foreground);
-  --color-info: var(--info);
-  --color-info-foreground: var(--info-foreground);
-  --color-purple: var(--purple);
-  --color-teal: var(--teal);
-  --radius-sm: calc(var(--radius) - 4px);
-  --radius-md: calc(var(--radius) - 2px);
-  --radius-lg: var(--radius);
-  --radius-xl: calc(var(--radius) + 4px);
-}
+/*
+ * HydraLMS design tokens & base styles.
+ * NOTE: This file must NOT contain @import "tailwindcss" or Tailwind
+ * directives (@theme, @custom-variant). Those belong in the consumer's
+ * CSS entry point, which should also include an @source directive
+ * pointing to this library's source files. See the getting-started guide.
+ */
 
 .hydra-root {
   --radius: 0.625rem;
@@ -65,8 +35,16 @@
   --warning-foreground: oklch(0.98 0.016 73);
   --info: oklch(0.623 0.214 259);
   --info-foreground: oklch(0.97 0.014 254);
-  --purple: oklch(0.627 0.265 303);
-  --teal: oklch(0.697 0.146 182);
+
+  /* Palette colors for visual variety */
+  --palette-0: oklch(0.627 0.265 303);
+  --palette-0-foreground: oklch(0.985 0 0);
+  --palette-1: oklch(0.680 0.162 195);
+  --palette-1-foreground: oklch(0.985 0 0);
+  --palette-2: oklch(0.720 0.185 130);
+  --palette-2-foreground: oklch(0.985 0 0);
+  --palette-3: oklch(0.700 0.180 70);
+  --palette-3-foreground: oklch(0.15 0 0);
 
   color: var(--foreground);
   background: var(--background);
@@ -101,8 +79,16 @@
   --warning-foreground: oklch(0.15 0.05 60);
   --info: oklch(0.623 0.214 259);
   --info-foreground: oklch(0.15 0.05 255);
-  --purple: oklch(0.627 0.265 303);
-  --teal: oklch(0.697 0.146 182);
+
+  /* Palette colors for visual variety */
+  --palette-0: oklch(0.700 0.200 303);
+  --palette-0-foreground: oklch(0.15 0 0);
+  --palette-1: oklch(0.730 0.150 195);
+  --palette-1-foreground: oklch(0.15 0 0);
+  --palette-2: oklch(0.760 0.170 130);
+  --palette-2-foreground: oklch(0.15 0 0);
+  --palette-3: oklch(0.740 0.165 70);
+  --palette-3-foreground: oklch(0.15 0 0);
 }
 
 /* Rich text support for flashcard back content */
@@ -136,3 +122,15 @@
   height: 0;
   pointer-events: none;
 }
+
+/* Respect user preference for reduced motion (WCAG 2.3.3) */
+@media (prefers-reduced-motion: reduce) {
+  .hydra-root *,
+  .hydra-root *::before,
+  .hydra-root *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+}

package/src/ui/badge.tsx

@@ -24,6 +24,14 @@ const badgeVariants = cva(
           "border-transparent bg-info/15 text-info",
         muted:
           "border-transparent bg-muted text-muted-foreground",
+        palette0:
+          "border-transparent bg-palette-0/15 text-palette-0",
+        palette1:
+          "border-transparent bg-palette-1/15 text-palette-1",
+        palette2:
+          "border-transparent bg-palette-2/15 text-palette-2",
+        palette3:
+          "border-transparent bg-palette-3/15 text-palette-3",
       },
     },
     defaultVariants: {

package/src/ui/index.ts

@@ -61,3 +61,5 @@ export { Skeleton } from "./skeleton";
 export { Tooltip, TooltipTrigger, TooltipContent } from "./tooltip";
 export { RichTextEditor } from "./rich-text-editor";
 export type { RichTextEditorProps, RichTextEditorVariant } from "./rich-text-editor";
+export { ToastProvider, Toaster, useToast, toastVariants } from "./toast";
+export type { ToastOptions, ToastVariant } from "./toast";

package/src/ui/progress.tsx

@@ -10,6 +10,10 @@ const progressVariants = cva("h-full rounded-full transition-all duration-300",
       success: "bg-success",
       warning: "bg-warning",
       info: "bg-info",
+      palette0: "bg-palette-0",
+      palette1: "bg-palette-1",
+      palette2: "bg-palette-2",
+      palette3: "bg-palette-3",
     },
     size: {
       sm: "",

package/src/ui/rich-text-editor.tsx

@@ -22,6 +22,8 @@ export interface RichTextEditorProps {
   disabled?: boolean;
   /** `"default"` shows full toolbar; `"minimal"` shows only basic formatting */
   variant?: RichTextEditorVariant;
+  /** Accessible label for screen readers (defaults to "Rich text editor") */
+  ariaLabel?: string;
   className?: string;
   style?: React.CSSProperties;
 }
@@ -45,6 +47,7 @@ export function RichTextEditor({
   readOnly = false,
   disabled = false,
   variant = "default",
+  ariaLabel = "Rich text editor",
   className,
   style,
 }: RichTextEditorProps) {
@@ -60,6 +63,13 @@ export function RichTextEditor({
     ],
     content: value,
     editable: !readOnly && !disabled,
+    editorProps: {
+      attributes: {
+        "aria-label": ariaLabel,
+        role: "textbox",
+        "aria-multiline": "true",
+      },
+    },
     onUpdate: ({ editor: e }) => {
       onChange?.(e.getHTML());
     },

package/src/ui/rich-text-toolbar.tsx

@@ -39,6 +39,7 @@ function ToolbarButton({
       onClick={onClick}
       disabled={disabled}
       title={title}
+      aria-label={title}
       className={cn(
         "inline-flex items-center justify-center rounded-sm p-1.5 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground disabled:pointer-events-none disabled:opacity-50",
         active && "bg-muted text-foreground",
@@ -72,7 +73,7 @@ export function RichTextToolbar({
   }
 
   return (
-    <div className="flex items-center gap-0.5 border-b border-border px-2 py-1.5">
+    <div className="flex items-center gap-0.5 border-b border-border px-2 py-1.5" role="toolbar" aria-label="Text formatting">
       <ToolbarButton
         active={editor.isActive("bold")}
         onClick={() => editor.chain().focus().toggleBold().run()}