@hydralms/components 0.1.3 → 0.3.0

package/src/sections/RequirementsChecklist/types.ts

@@ -0,0 +1,44 @@
+/**
+ * RequirementsChecklist section — shows completion requirements with progress tracking.
+ *
+ * Displays a list of requirements with checked/unchecked status and an overall
+ * progress bar. Incomplete items can be clicked to navigate to the relevant content.
+ *
+ * @example
+ * <RequirementsChecklist
+ *   title="Certificate Requirements"
+ *   requirements={requirements}
+ *   onRequirementClick={(uid) => navigateTo(uid)}
+ * />
+ */
+export interface RequirementsChecklistProps {
+  /** Section title */
+  title?: string;
+  /** List of requirements to display */
+  requirements: Requirement[];
+  /** Called when the user clicks an incomplete requirement */
+  onRequirementClick?: (uid: string) => void;
+  /** 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 Requirement {
+  /** Unique identifier */
+  uid: string;
+  /** Requirement label */
+  label: string;
+  /** Optional description */
+  description?: string;
+  /** Whether this requirement has been completed */
+  completed: boolean;
+  /** Optional action label for clickable items */
+  actionLabel?: string;
+}

package/src/sections/ResourceLibrary/ResourceLibrary.tsx

@@ -1,19 +1,16 @@
 import { useMemo, useState } from "react";
-import { Download, Grid, List as ListIcon } from "lucide-react";
+import { AlertCircle, Download, Grid, List as ListIcon } from "lucide-react";
 import { LearningObjectIcon } from "../../curriculum";
 import { SearchInput, EmptyState } from "../../common";
+import { Skeleton } from "../../ui/skeleton";
 import { Button } from "../../ui/button";
 import { Card, CardContent } from "../../ui/card";
 import { Tabs, TabsList, TabsTrigger } from "../../ui/tabs";
 import { Tooltip, TooltipTrigger, TooltipContent } from "../../ui/tooltip";
+import { Pagination } from "../../common/pagination";
 import type { ResourceLibraryProps, Resource } from "./types";
 import { cn } from "../../lib/utils";
-
-function formatBytes(bytes: number): string {
-  if (bytes < 1024) return `${bytes} B`;
-  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
-  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
-}
+import { formatFileSize } from "../../utils/format-file-size";
 
 const TYPE_TO_ICON: Record<string, string> = {
   pdf: "document",
@@ -35,6 +32,13 @@ export function ResourceLibrary({
   showSearch = true,
   emptyMessage = "No resources found",
   readOnly = false,
+  isLoading,
+  error,
+  onRetry,
+  pageSize,
+  currentPage = 1,
+  totalItems,
+  onPageChange,
   className,
   style,
 }: ResourceLibraryProps) {
@@ -58,6 +62,38 @@ export function ResourceLibrary({
     return result;
   }, [resources, activeCategoryUid, searchQuery]);
 
+  if (isLoading) {
+    return (
+      <div className={cn("space-y-4", className)} style={style}>
+        <Skeleton className="h-9 w-full" />
+        <div className="grid grid-cols-3 gap-4">
+          {Array.from({ length: 6 }).map((_, i) => (
+            <Skeleton key={i} className="h-32 w-full rounded-lg" />
+          ))}
+        </div>
+      </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>
+    );
+  }
+
   function renderResource(resource: Resource) {
     const iconType = TYPE_TO_ICON[resource.type] ?? "document";
 
@@ -66,10 +102,10 @@ export function ResourceLibrary({
         key={resource.uid}
         className={cn(
           "flex items-center gap-3 px-3 py-2",
-          !readOnly && "cursor-pointer hover:bg-muted",
-          readOnly && "opacity-70",
+          !readOnly && onResourceClick && "cursor-pointer hover:bg-muted",
+          (readOnly || !onResourceClick) && "opacity-70",
         )}
-        onClick={() => !readOnly && onResourceClick(resource)}
+        onClick={() => !readOnly && onResourceClick?.(resource)}
       >
         <div className="min-w-10">
           <LearningObjectIcon type={iconType} size={20} />
@@ -77,10 +113,10 @@ export function ResourceLibrary({
         <div className="flex-1 min-w-0">
           <span className="text-sm text-foreground">{resource.name}</span>
           {(resource.description || resource.fileSize != null) && (
-            <span className="text-sm text-muted-foreground">
+            <span className="block text-xs text-muted-foreground">
               {[
                 resource.description,
-                resource.fileSize != null && formatBytes(resource.fileSize),
+                resource.fileSize != null && formatFileSize(resource.fileSize),
               ]
                 .filter(Boolean)
                 .join(" \u00b7 ")}
@@ -178,18 +214,24 @@ export function ResourceLibrary({
         <EmptyState title={emptyMessage} description="Try adjusting your search or filter." />
       ) : viewMode === "list" ? (
         <Card>
-          {filtered.map(renderResource)}
+          {(onPageChange && pageSize
+            ? filtered.slice((currentPage - 1) * pageSize, currentPage * pageSize)
+            : filtered
+          ).map(renderResource)}
         </Card>
       ) : (
         <div className="grid grid-cols-[repeat(auto-fill,minmax(240px,1fr))] gap-2">
-          {filtered.map((resource) => (
+          {(onPageChange && pageSize
+            ? filtered.slice((currentPage - 1) * pageSize, currentPage * pageSize)
+            : filtered
+          ).map((resource) => (
             <Card
               key={resource.uid}
               className={cn(
                 "transition-colors",
-                !readOnly && "cursor-pointer hover:border-primary",
+                !readOnly && onResourceClick && "cursor-pointer hover:border-primary",
               )}
-              onClick={() => !readOnly && onResourceClick(resource)}
+              onClick={() => !readOnly && onResourceClick?.(resource)}
             >
               <CardContent className="pt-4 pb-4">
                 <div className="flex gap-1 items-center mb-1">
@@ -205,7 +247,7 @@ export function ResourceLibrary({
                 )}
                 {resource.fileSize != null && (
                   <span className="text-xs text-muted-foreground">
-                    {formatBytes(resource.fileSize)}
+                    {formatFileSize(resource.fileSize)}
                   </span>
                 )}
               </CardContent>
@@ -213,6 +255,15 @@ export function ResourceLibrary({
           ))}
         </div>
       )}
+
+      {onPageChange && pageSize && filtered.length > 0 && (
+        <Pagination
+          currentPage={currentPage}
+          totalPages={Math.ceil((totalItems ?? filtered.length) / pageSize)}
+          onPageChange={onPageChange}
+          className="mt-4"
+        />
+      )}
     </div>
   );
 }

package/src/sections/ResourceLibrary/types.ts

@@ -18,7 +18,7 @@ export interface ResourceLibraryProps {
   /** Optional categories for tab filtering */
   categories?: { uid: string; label: string }[];
   /** Called when the user clicks a resource */
-  onResourceClick: (resource: Resource) => void;
+  onResourceClick?: (resource: Resource) => void;
   /** Called when the user downloads a resource */
   onDownload?: (resource: Resource) => void;
   /** Layout view mode */
@@ -31,6 +31,20 @@ export interface ResourceLibraryProps {
   emptyMessage?: string;
   /** 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;
+  /** Number of items per page (enables pagination when set with onPageChange) */
+  pageSize?: number;
+  /** Current page (1-indexed) */
+  currentPage?: number;
+  /** Total number of items (for server-side pagination) */
+  totalItems?: number;
+  /** Called when the user navigates to a different page */
+  onPageChange?: (page: number) => void;
   /** CSS class name for the root element */
   className?: string;
   /** Inline styles for the root element */

package/src/sections/RubricView/RubricView.tsx

@@ -0,0 +1,174 @@
+import { AlertCircle, CheckCircle2 } from "lucide-react";
+import { Skeleton } from "../../ui/skeleton";
+import { EmptyState } from "../../common/empty-state";
+import { Button } from "../../ui/button";
+import { Card, CardContent } from "../../ui/card";
+import {
+  Table,
+  TableHeader,
+  TableBody,
+  TableRow,
+  TableHead,
+  TableCell,
+} from "../../ui/table";
+import { Badge } from "../../ui/badge";
+import { Separator } from "../../ui/separator";
+import { cn } from "../../lib/utils";
+import type { RubricViewProps } from "./types";
+
+/**
+ * RubricView — displays a grading rubric with criteria rows and proficiency level columns.
+ *
+ * When `selectedLevels` is provided, highlights the scored level per criterion and
+ * shows an overall score. Useful inside AssignmentModule for showing grading criteria
+ * and results.
+ */
+export function RubricView({
+  criteria,
+  selectedLevels,
+  totalScore,
+  maxScore,
+  feedback,
+  isLoading,
+  error,
+  onRetry,
+  className,
+  style,
+}: RubricViewProps) {
+  const isScored = selectedLevels && Object.keys(selectedLevels).length > 0;
+
+  if (isLoading) {
+    return (
+      <div className={cn("space-y-4", className)} style={style}>
+        <Skeleton className="h-10 w-full" />
+        {Array.from({ length: 3 }).map((_, i) => (
+          <Skeleton key={i} className="h-16 w-full" />
+        ))}
+      </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 (
+    <div className={cn("flex flex-col gap-4", className)} style={style}>
+      {/* Score header */}
+      {isScored && totalScore !== undefined && maxScore !== undefined && (
+        <div className="flex items-center justify-between">
+          <h3 className="text-lg font-semibold text-foreground">Rubric</h3>
+          <Badge variant={totalScore >= maxScore * 0.7 ? "success" : "destructive"}>
+            {totalScore} / {maxScore} pts
+          </Badge>
+        </div>
+      )}
+
+      {!isScored && (
+        <h3 className="text-lg font-semibold text-foreground">Grading Rubric</h3>
+      )}
+
+      {/* Criteria table */}
+      <Card>
+        <CardContent className="p-0">
+          <div className="overflow-x-auto">
+            <Table className="text-sm">
+              <TableHeader>
+                <TableRow className="bg-muted/50">
+                  <TableHead className="text-left font-medium text-muted-foreground w-1/5">
+                    Criterion
+                  </TableHead>
+                  {criteria[0]?.levels.map((level) => (
+                    <TableHead
+                      key={level.uid}
+                      className="text-center font-medium text-muted-foreground"
+                    >
+                      <div>{level.label}</div>
+                      <div className="text-xs font-normal mt-0.5">
+                        {level.points} pts
+                      </div>
+                    </TableHead>
+                  ))}
+                </TableRow>
+              </TableHeader>
+              <TableBody>
+                {criteria.map((criterion, i) => {
+                  const selectedLevelUid = selectedLevels?.[criterion.uid];
+                  return (
+                    <TableRow
+                      key={criterion.uid}
+                      className={cn(i % 2 === 1 && "bg-muted/20")}
+                    >
+                      <TableCell className="align-top">
+                        <div className="font-medium text-foreground">
+                          {criterion.name}
+                        </div>
+                        {criterion.description && (
+                          <div className="text-xs text-muted-foreground mt-0.5">
+                            {criterion.description}
+                          </div>
+                        )}
+                      </TableCell>
+                      {criterion.levels.map((level) => {
+                        const isSelected = selectedLevelUid === level.uid;
+                        return (
+                          <TableCell
+                            key={level.uid}
+                            className={cn(
+                              "align-top text-center",
+                              isSelected &&
+                                "bg-primary/10 ring-2 ring-primary/30 ring-inset rounded-sm"
+                            )}
+                          >
+                            <div className="text-xs text-muted-foreground">
+                              {level.description}
+                            </div>
+                            {isSelected && (
+                              <div className="mt-1.5 flex justify-center">
+                                <CheckCircle2 className="size-4 text-primary" />
+                              </div>
+                            )}
+                          </TableCell>
+                        );
+                      })}
+                    </TableRow>
+                  );
+                })}
+              </TableBody>
+            </Table>
+          </div>
+        </CardContent>
+      </Card>
+
+      {/* Feedback */}
+      {feedback && (
+        <>
+          <Separator />
+          <div>
+            <h4 className="text-sm font-medium text-foreground mb-1">
+              Instructor Feedback
+            </h4>
+            <p className="text-sm text-muted-foreground whitespace-pre-wrap">
+              {feedback}
+            </p>
+          </div>
+        </>
+      )}
+    </div>
+  );
+}

package/src/sections/RubricView/types.ts

@@ -0,0 +1,58 @@
+/**
+ * RubricView section — displays a grading rubric with criteria and proficiency levels.
+ *
+ * Shows criteria as rows with level columns. When `selectedLevels` is provided,
+ * highlights the scored level per criterion and shows total score.
+ *
+ * @example
+ * <RubricView
+ *   criteria={rubricCriteria}
+ *   selectedLevels={{ "c1": "l2", "c2": "l3" }}
+ *   totalScore={85}
+ *   maxScore={100}
+ * />
+ */
+export interface RubricViewProps {
+  /** Rubric criteria (rows) */
+  criteria: RubricCriterion[];
+  /** Selected level UID per criterion UID — highlights scored cells */
+  selectedLevels?: Record<string, string>;
+  /** Overall rubric score (sum of selected levels) */
+  totalScore?: number;
+  /** Maximum possible score */
+  maxScore?: number;
+  /** Instructor feedback text */
+  feedback?: string;
+  /** 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 RubricCriterion {
+  /** Unique identifier */
+  uid: string;
+  /** Criterion name (e.g. "Organization", "Evidence") */
+  name: string;
+  /** Optional description of what this criterion evaluates */
+  description?: string;
+  /** Proficiency levels from lowest to highest */
+  levels: RubricLevel[];
+}
+
+export interface RubricLevel {
+  /** Unique identifier */
+  uid: string;
+  /** Level label (e.g. "Excellent", "Good", "Needs Work") */
+  label: string;
+  /** Description of what this level looks like */
+  description: string;
+  /** Point value for this level */
+  points: number;
+}

package/src/sections/ScrollableQuiz/ScrollableQuiz.tsx

@@ -1,9 +1,15 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { QuestionRenderer } from "../../questions";
 import type { SessionAnswer } from "../../questions/types";
+
+const EMPTY_ANSWERS: SessionAnswer[] = [];
 import { Button } from "../../ui/button";
 import { Card, CardContent } from "../../ui/card";
+import { Separator } from "../../ui/separator";
+import { Skeleton } from "../../ui/skeleton";
 import { cn } from "../../lib/utils";
+import { mergeSessionAnswers } from "../_shared/merge-answers";
+import { SectionShell } from "../_shared/section-shell";
 import type { ScrollableQuizProps } from "./types";
 
 export function ScrollableQuiz({
@@ -16,6 +22,9 @@ export function ScrollableQuiz({
   questionGroups,
   isSubmitting = false,
   readOnly = false,
+  isLoading,
+  error,
+  onRetry,
   className,
   style,
 }: ScrollableQuizProps) {
@@ -23,10 +32,20 @@ export function ScrollableQuiz({
   const [activeUid, setActiveUid] = useState<string | null>(questions[0]?.uid ?? null);
   const questionRefs = useRef<Map<string, HTMLElement>>(new Map());
 
-  const answeredCount = useMemo(() => {
-    const answered = new Set(sessionAnswers.map((a) => a.uid));
-    return questions.filter((q) => answered.has(q.uid)).length;
-  }, [questions, sessionAnswers]);
+  const answersByQuestion = useMemo(() => {
+    const map = new Map<string, SessionAnswer[]>();
+    for (const a of sessionAnswers) {
+      const list = map.get(a.uid);
+      if (list) list.push(a);
+      else map.set(a.uid, [a]);
+    }
+    return map;
+  }, [sessionAnswers]);
+
+  const answeredCount = useMemo(
+    () => questions.filter((q) => answersByQuestion.has(q.uid)).length,
+    [questions, answersByQuestion],
+  );
 
   useEffect(() => {
     const observer = new IntersectionObserver(
@@ -49,19 +68,17 @@ export function ScrollableQuiz({
     else questionRefs.current.delete(uid);
   }, []);
 
-  function handleAnswer(questionUid: string, rawAnswers: { uid: string; content?: string }[]) {
-    const newAnswers: SessionAnswer[] = rawAnswers.map((a) => ({
-      uid: questionUid,
-      answerUid: a.uid,
-      content: a.content,
-    }));
-    setSessionAnswers((prev) => {
-      const filtered = prev.filter((a) => a.uid !== questionUid);
-      const merged = [...filtered, ...newAnswers];
-      onAnswerChange?.(merged);
-      return merged;
-    });
-  }
+  const onAnswerChangeRef = useRef(onAnswerChange);
+  onAnswerChangeRef.current = onAnswerChange;
+
+  const handleAnswer = useCallback(
+    (questionUid: string, rawAnswers: { uid: string; content?: string }[]) => {
+      setSessionAnswers((prev) =>
+        mergeSessionAnswers(prev, questionUid, rawAnswers, onAnswerChangeRef.current),
+      );
+    },
+    [],
+  );
 
   function scrollToQuestion(uid: string) {
     questionRefs.current.get(uid)?.scrollIntoView({ behavior: "smooth", block: "center" });
@@ -86,11 +103,25 @@ export function ScrollableQuiz({
   let globalIndex = 0;
 
   return (
-    <div className={cn("flex gap-3", className)} style={style}>
+    <SectionShell
+      isLoading={isLoading}
+      error={error}
+      onRetry={onRetry}
+      className={className}
+      style={style}
+      skeleton={
+        <>
+          <Skeleton className="h-32 w-full" />
+          <Skeleton className="h-32 w-full" />
+          <Skeleton className="h-32 w-full" />
+        </>
+      }
+    >
+    <div className="flex gap-3">
       {/* Main content */}
       <div className="flex-1 min-w-0">
         {orderedQuestions.map((group, gi) => (
-          <div key={gi}>
+          <div key={group.label ?? `ungrouped-${gi}`}>
             {group.label && (
               <p className={cn("text-lg font-semibold mb-2 text-foreground", gi > 0 && "mt-4")}>
                 {group.label}
@@ -113,7 +144,7 @@ export function ScrollableQuiz({
                     )}
                     <QuestionRenderer
                       question={q}
-                      sessionAnswers={sessionAnswers.filter((a) => a.uid === q.uid)}
+                      sessionAnswers={answersByQuestion.get(q.uid) ?? EMPTY_ANSWERS}
                       onAnswer={(answers) => handleAnswer(q.uid, answers)}
                       readOnly={readOnly}
                     />
@@ -123,7 +154,8 @@ export function ScrollableQuiz({
             })}
           </div>
         ))}
-        <div className="mt-3 flex justify-between items-center">
+        <Separator className="my-3" />
+        <div className="flex justify-between items-center">
           <span className="text-sm text-muted-foreground">
             {answeredCount} of {questions.length} answered
           </span>
@@ -138,11 +170,12 @@ export function ScrollableQuiz({
 
       {/* Sidebar navigator */}
       {showNavigator && (
-        <Card className="hidden md:block w-50 shrink-0 sticky top-4 self-start p-3">
+        <Card className="hidden md:block w-50 shrink-0 sticky top-4 self-start">
+          <CardContent className="p-3">
           <p className="font-semibold text-sm mb-1 text-foreground">Questions</p>
           <div className="flex flex-wrap gap-1">
             {questions.map((q, i) => {
-              const isAnswered = sessionAnswers.some((a) => a.uid === q.uid);
+              const isAnswered = answersByQuestion.has(q.uid);
               const isActive = activeUid === q.uid;
               return (
                 <button
@@ -163,8 +196,10 @@ export function ScrollableQuiz({
               );
             })}
           </div>
+          </CardContent>
         </Card>
       )}
     </div>
+    </SectionShell>
   );
 }

package/src/sections/ScrollableQuiz/types.ts

@@ -33,6 +33,12 @@ export interface ScrollableQuizProps {
   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 */