@hydralms/components 0.1.3 → 0.3.0

package/src/assessment-toolbar/types.ts

@@ -37,8 +37,6 @@ export interface AssessmentToolbarProps {
   questions?: QuestionNavigatorItem[];
   /** Called when the user navigates to a specific question via the navigator */
   onNavigateToQuestion?: (questionUid: string) => void;
-  /** Called when the user flags or unflags a question */
-  onToggleFlag?: (questionUid: string) => void;
   /** UID of the currently active question */
   currentQuestionUid?: string;
   /** Whether the assessment has been completed/submitted */
@@ -72,14 +70,12 @@ export interface TimerDisplayProps {
  *   questions={questions}
  *   currentQuestionUid={currentUid}
  *   onNavigate={handleNavigate}
- *   onToggleFlag={handleFlag}
  * />
  */
 export interface QuestionNavigatorProps {
   questions: QuestionNavigatorItem[];
   currentQuestionUid?: string;
   onNavigate?: (questionUid: string) => void;
-  onToggleFlag?: (questionUid: string) => void;
   readOnly?: boolean;
 }
 
@@ -90,3 +86,57 @@ export interface QuestionNavigatorItem {
   isAnswered: boolean;
   isSkipped: boolean;
 }
+
+/**
+ * QuestionHeaderBar displays question number, flag toggle, and optional
+ * materials button inside the question Card above the QuestionRenderer.
+ *
+ * @example
+ * <QuestionHeaderBar
+ *   questionNumber={3}
+ *   totalQuestions={10}
+ *   isFlagged={false}
+ *   onToggleFlag={() => toggleFlag(questionUid)}
+ *   hasMaterials
+ *   onOpenMaterials={() => setDrawerOpen(true)}
+ * />
+ */
+export interface QuestionHeaderBarProps {
+  /** 1-based question number */
+  questionNumber: number;
+  /** Total number of questions */
+  totalQuestions: number;
+  /** Whether this question is currently flagged */
+  isFlagged: boolean;
+  /** Called when the user toggles the flag */
+  onToggleFlag?: () => void;
+  /** Whether the current question has related materials available */
+  hasMaterials?: boolean;
+  /** Called when the user clicks the materials button */
+  onOpenMaterials?: () => void;
+  /** When true, hides interactive elements */
+  readOnly?: boolean;
+}
+
+/**
+ * QuestionMaterialsDrawer renders a slide-in panel with content blocks
+ * linked to the current question for open-book reference.
+ *
+ * @example
+ * <QuestionMaterialsDrawer
+ *   open={open}
+ *   onOpenChange={setOpen}
+ *   materials={currentMaterials}
+ *   questionNumber={3}
+ * />
+ */
+export interface QuestionMaterialsDrawerProps {
+  /** Whether the drawer is open */
+  open: boolean;
+  /** Called when the drawer should open or close */
+  onOpenChange: (open: boolean) => void;
+  /** One or more material groups to display in the drawer */
+  materials: import("../questions/types").QuestionMaterial[];
+  /** Question number for the title display */
+  questionNumber?: number;
+}

package/src/assessment-toolbar/use-countdown.ts

@@ -0,0 +1,153 @@
+import { useState, useRef, useCallback, useEffect } from "react";
+
+export interface UseCountdownOptions {
+  /** Total countdown duration in seconds */
+  durationSeconds: number;
+  /** Seconds remaining at which to trigger warning state. @default 60 */
+  warningThresholdSeconds?: number;
+  /** Called once when the countdown reaches zero */
+  onExpire?: () => void;
+  /** Called once when the countdown enters warning territory */
+  onWarning?: () => void;
+  /** Whether to start the countdown immediately. @default false */
+  autoStart?: boolean;
+}
+
+export interface UseCountdownReturn {
+  /** Seconds remaining in the countdown */
+  timeRemaining: number;
+  /** Whether the countdown is actively running */
+  isRunning: boolean;
+  /** Whether the countdown has been paused */
+  isPaused: boolean;
+  /** Whether the countdown has reached zero */
+  isExpired: boolean;
+  /** Whether the countdown is within the warning threshold */
+  isWarning: boolean;
+  /** Start or restart the countdown */
+  start: () => void;
+  /** Pause the countdown */
+  pause: () => void;
+  /** Resume after pausing */
+  resume: () => void;
+  /** Reset to the original duration, stopped */
+  reset: () => void;
+}
+
+type TimerState = "idle" | "running" | "paused" | "expired";
+
+/**
+ * useCountdown manages a countdown timer lifecycle with warning and expiry callbacks.
+ *
+ * @example
+ * const { timeRemaining, isWarning, start } = useCountdown({
+ *   durationSeconds: 300,
+ *   warningThresholdSeconds: 60,
+ *   onExpire: () => handleAutoSubmit(),
+ * });
+ */
+export function useCountdown({
+  durationSeconds,
+  warningThresholdSeconds = 60,
+  onExpire,
+  onWarning,
+  autoStart = false,
+}: UseCountdownOptions): UseCountdownReturn {
+  const [timeRemaining, setTimeRemaining] = useState(durationSeconds);
+  const stateRef = useRef<TimerState>(autoStart ? "running" : "idle");
+  const intervalRef = useRef<ReturnType<typeof setInterval> | null>(null);
+  const onExpireRef = useRef(onExpire);
+  const onWarningRef = useRef(onWarning);
+  const warningFiredRef = useRef(false);
+
+  // Keep callback refs current without recreating intervals
+  onExpireRef.current = onExpire;
+  onWarningRef.current = onWarning;
+
+  const clearTimer = useCallback(() => {
+    if (intervalRef.current != null) {
+      clearInterval(intervalRef.current);
+      intervalRef.current = null;
+    }
+  }, []);
+
+  const startInterval = useCallback(() => {
+    clearTimer();
+    intervalRef.current = setInterval(() => {
+      setTimeRemaining((prev) => {
+        const next = prev - 1;
+
+        // Warning check
+        if (
+          !warningFiredRef.current &&
+          next <= warningThresholdSeconds &&
+          next > 0
+        ) {
+          warningFiredRef.current = true;
+          onWarningRef.current?.();
+        }
+
+        // Expiry check
+        if (next <= 0) {
+          clearTimer();
+          stateRef.current = "expired";
+          onExpireRef.current?.();
+          return 0;
+        }
+
+        return next;
+      });
+    }, 1000);
+  }, [clearTimer, warningThresholdSeconds]);
+
+  const start = useCallback(() => {
+    setTimeRemaining(durationSeconds);
+    warningFiredRef.current = false;
+    stateRef.current = "running";
+    startInterval();
+  }, [durationSeconds, startInterval]);
+
+  const pause = useCallback(() => {
+    if (stateRef.current !== "running") return;
+    clearTimer();
+    stateRef.current = "paused";
+    // Force re-render so isPaused updates
+    setTimeRemaining((prev) => prev);
+  }, [clearTimer]);
+
+  const resume = useCallback(() => {
+    if (stateRef.current !== "paused") return;
+    stateRef.current = "running";
+    startInterval();
+  }, [startInterval]);
+
+  const reset = useCallback(() => {
+    clearTimer();
+    stateRef.current = "idle";
+    warningFiredRef.current = false;
+    setTimeRemaining(durationSeconds);
+  }, [clearTimer, durationSeconds]);
+
+  // Auto-start on mount if requested
+  useEffect(() => {
+    if (autoStart) {
+      startInterval();
+    }
+    return clearTimer;
+  }, [autoStart, startInterval, clearTimer]);
+
+  const state = stateRef.current;
+
+  return {
+    timeRemaining,
+    isRunning: state === "running",
+    isPaused: state === "paused",
+    isExpired: state === "expired",
+    isWarning:
+      timeRemaining <= warningThresholdSeconds && timeRemaining > 0,
+    start,
+    pause,
+    resume,
+    reset,
+  };
+}

package/src/common/empty-state.tsx

@@ -6,6 +6,7 @@ export function EmptyState({ icon, title, description, action, className, style
     <div
       className={cn("flex flex-col items-center justify-center text-center px-3 py-6", className)}
       style={style}
+      role="status"
     >
       {icon && (
         <div className="mb-2 text-muted-foreground [&>svg]:size-12">

package/src/common/index.ts

@@ -3,10 +3,15 @@ export { ConfirmDialog } from "./confirm-dialog";
 export { SearchInput } from "./search-input";
 export { StatusBadge } from "./status-badge";
 export { DueDateDisplay } from "./due-date-display";
+export { Stepper } from "./stepper";
+export { Pagination } from "./pagination";
 export type {
   EmptyStateProps,
   ConfirmDialogProps,
   SearchInputProps,
   StatusBadgeProps,
   DueDateDisplayProps,
+  StepperProps,
+  StepDefinition,
+  PaginationProps,
 } from "./types";

package/src/common/pagination.tsx

@@ -0,0 +1,135 @@
+import { memo, useMemo } from "react";
+import { ChevronLeft, ChevronRight } from "lucide-react";
+import { cn } from "../lib/utils";
+import { Button } from "../ui/button";
+
+/**
+ * Pagination provides page navigation controls with page numbers,
+ * previous/next buttons, and ellipsis for large page ranges.
+ *
+ * @example
+ * <Pagination
+ *   currentPage={3}
+ *   totalPages={10}
+ *   onPageChange={(page) => setPage(page)}
+ * />
+ */
+export interface PaginationProps {
+  /** Current active page (1-indexed) */
+  currentPage: number;
+  /** Total number of pages */
+  totalPages: number;
+  /** Called when the user navigates to a page */
+  onPageChange: (page: number) => void;
+  /** Number of page buttons shown on each side of the current page (default 1) */
+  siblingCount?: number;
+  /** CSS class name for the root element */
+  className?: string;
+  /** Inline styles for the root element */
+  style?: React.CSSProperties;
+}
+
+function getPageRange(
+  current: number,
+  total: number,
+  siblings: number,
+): (number | "ellipsis")[] {
+  const totalSlots = siblings * 2 + 5;
+  if (total <= totalSlots) {
+    return Array.from({ length: total }, (_, i) => i + 1);
+  }
+
+  const leftSibling = Math.max(current - siblings, 1);
+  const rightSibling = Math.min(current + siblings, total);
+  const showLeftEllipsis = leftSibling > 2;
+  const showRightEllipsis = rightSibling < total - 1;
+
+  if (!showLeftEllipsis && showRightEllipsis) {
+    const leftCount = siblings * 2 + 3;
+    const leftRange = Array.from({ length: leftCount }, (_, i) => i + 1);
+    return [...leftRange, "ellipsis", total];
+  }
+
+  if (showLeftEllipsis && !showRightEllipsis) {
+    const rightCount = siblings * 2 + 3;
+    const rightRange = Array.from(
+      { length: rightCount },
+      (_, i) => total - rightCount + i + 1,
+    );
+    return [1, "ellipsis", ...rightRange];
+  }
+
+  const middleRange = Array.from(
+    { length: rightSibling - leftSibling + 1 },
+    (_, i) => leftSibling + i,
+  );
+  return [1, "ellipsis", ...middleRange, "ellipsis", total];
+}
+
+export const Pagination = memo(function Pagination({
+  currentPage,
+  totalPages,
+  onPageChange,
+  siblingCount = 1,
+  className,
+  style,
+}: PaginationProps) {
+  const pages = useMemo(
+    () => getPageRange(currentPage, totalPages, siblingCount),
+    [currentPage, totalPages, siblingCount],
+  );
+
+  if (totalPages <= 1) return null;
+
+  return (
+    <nav
+      data-slot="pagination"
+      aria-label="Pagination"
+      className={cn("flex items-center justify-center gap-1", className)}
+      style={style}
+    >
+      <Button
+        variant="ghost"
+        size="icon-sm"
+        onClick={() => onPageChange(currentPage - 1)}
+        disabled={currentPage <= 1}
+        aria-label="Previous page"
+      >
+        <ChevronLeft className="size-4" />
+      </Button>
+
+      {pages.map((page, i) =>
+        page === "ellipsis" ? (
+          <span
+            key={`ellipsis-${i}`}
+            className="flex items-center justify-center size-8 text-xs text-muted-foreground"
+          >
+            <span aria-hidden="true">...</span>
+            <span className="sr-only">More pages</span>
+          </span>
+        ) : (
+          <Button
+            key={page}
+            variant={page === currentPage ? "default" : "ghost"}
+            size="icon-sm"
+            onClick={() => onPageChange(page)}
+            aria-label={`Page ${page}`}
+            aria-current={page === currentPage ? "page" : undefined}
+          >
+            <span className="text-xs">{page}</span>
+          </Button>
+        ),
+      )}
+
+      <Button
+        variant="ghost"
+        size="icon-sm"
+        onClick={() => onPageChange(currentPage + 1)}
+        disabled={currentPage >= totalPages}
+        aria-label="Next page"
+      >
+        <ChevronRight className="size-4" />
+      </Button>
+    </nav>
+  );
+});

package/src/common/search-input.tsx

@@ -1,4 +1,4 @@
-import { useState, useEffect, useCallback } from "react";
+import { useState, useMemo, useRef, useEffect } from "react";
 import { Search, X } from "lucide-react";
 import { debounce } from "../utils/debounce";
 import type { SearchInputProps } from "./types";
@@ -16,12 +16,14 @@ export function SearchInput({
 }: SearchInputProps) {
   const [localValue, setLocalValue] = useState(value);
 
-  useEffect(() => {
-    setLocalValue(value);
-  }, [value]);
+  const onChangeRef = useRef(onChange);
+  onChangeRef.current = onChange;
 
-  // eslint-disable-next-line react-hooks/exhaustive-deps
-  const debouncedOnChange = useCallback(debounce(onChange, debounceMs), [onChange, debounceMs]);
+  const debouncedOnChange = useMemo(
+    () => debounce((val: string) => onChangeRef.current(val), debounceMs),
+    [debounceMs],
+  );
+  useEffect(() => () => debouncedOnChange.cancel(), [debouncedOnChange]);
 
   function handleChange(e: React.ChangeEvent<HTMLInputElement>) {
     const next = e.target.value;

package/src/common/stepper.tsx

@@ -0,0 +1,100 @@
+import { Check } from "lucide-react";
+import { cn } from "../lib/utils";
+import type { StepperProps } from "./types";
+
+/**
+ * Stepper renders a visual step indicator for multi-step flows,
+ * showing completed, current, and upcoming steps with labels.
+ */
+export function Stepper({
+  steps,
+  currentStep,
+  orientation = "horizontal",
+  variant = "default",
+  className,
+  style,
+}: StepperProps) {
+  const isHorizontal = orientation === "horizontal";
+  const isCompact = variant === "compact";
+
+  const circleSize = isCompact ? "w-6 h-6 text-xs" : "w-8 h-8 text-sm";
+  const iconSize = isCompact ? 12 : 16;
+
+  return (
+    <div
+      className={cn(
+        "flex",
+        isHorizontal ? "flex-row items-start" : "flex-col",
+        className,
+      )}
+      style={style}
+    >
+      {steps.map((step, index) => {
+        const isCompleted = index < currentStep;
+        const isCurrent = index === currentStep;
+
+        return (
+          <div key={index} className={cn("flex", isHorizontal ? "flex-1 flex-row items-start" : "flex-row items-start")}>
+            {/* Step indicator */}
+            <div className={cn("flex", isHorizontal ? "flex-col items-center" : "flex-row items-start gap-3")}>
+              {/* Circle */}
+              <div
+                className={cn(
+                  "rounded-full flex items-center justify-center shrink-0 font-semibold transition-colors",
+                  circleSize,
+                  isCompleted && "bg-primary text-primary-foreground",
+                  isCurrent && "border-2 border-primary bg-primary/10 text-primary",
+                  !isCompleted && !isCurrent && "border-2 border-border bg-muted text-muted-foreground",
+                )}
+              >
+                {isCompleted ? (
+                  <Check size={iconSize} />
+                ) : (
+                  <span>{index + 1}</span>
+                )}
+              </div>
+
+              {/* Label */}
+              <div className={cn(isHorizontal ? "mt-1.5 text-center" : "pt-0.5")}>
+                <p
+                  className={cn(
+                    "text-sm font-medium leading-tight",
+                    isCurrent ? "text-foreground" : "text-muted-foreground",
+                  )}
+                >
+                  {step.label}
+                </p>
+                {!isCompact && step.description && (
+                  <p className="text-xs text-muted-foreground mt-0.5">
+                    {step.description}
+                  </p>
+                )}
+              </div>
+            </div>
+
+            {/* Connector line */}
+            {index < steps.length - 1 && (
+              isHorizontal ? (
+                <div
+                  className={cn(
+                    "flex-1 h-0.5 self-center mt-0 mx-2",
+                    isCompact ? "mt-3" : "mt-4",
+                    isCompleted ? "bg-primary" : "bg-border",
+                  )}
+                />
+              ) : (
+                <div
+                  className={cn(
+                    "w-0.5 h-6 ml-3.5",
+                    isCompact && "ml-2.5",
+                    isCompleted ? "bg-primary" : "bg-border",
+                  )}
+                />
+              )
+            )}
+          </div>
+        );
+      })}
+    </div>
+  );
+}

package/src/common/types.ts

@@ -127,3 +127,44 @@ export interface DueDateDisplayProps {
   /** Inline styles for the root element */
   style?: React.CSSProperties;
 }
+
+/**
+ * A single step definition used by the Stepper component.
+ */
+export interface StepDefinition {
+  /** Step label text */
+  label: string;
+  /** Optional secondary description */
+  description?: string;
+}
+
+/**
+ * Stepper renders a visual step indicator for multi-step flows,
+ * showing completed, current, and upcoming steps with labels.
+ *
+ * @example
+ * <Stepper
+ *   steps={[
+ *     { label: "Setup" },
+ *     { label: "Questions" },
+ *     { label: "Results" },
+ *   ]}
+ *   currentStep={1}
+ * />
+ */
+export interface StepperProps {
+  /** Ordered list of steps to display */
+  steps: StepDefinition[];
+  /** Zero-based index of the currently active step */
+  currentStep: number;
+  /** Layout orientation. @default 'horizontal' */
+  orientation?: "horizontal" | "vertical";
+  /** Visual density variant. @default 'default' */
+  variant?: "default" | "compact";
+  /** CSS class name for the root element */
+  className?: string;
+  /** Inline styles for the root element */
+  style?: React.CSSProperties;
+}
+
+export type { PaginationProps } from "./pagination";

package/src/content/attachment-list.tsx

@@ -0,0 +1,92 @@
+import {
+  File,
+  FileText,
+  Image,
+  Film,
+  Music,
+  Archive,
+  Download,
+  X,
+} from "lucide-react";
+import { cn } from "../lib/utils";
+import { formatFileSize } from "../utils/format-file-size";
+import { Button } from "../ui/button";
+import type { AttachmentListProps } from "./types";
+
+function getFileIcon(mimeType: string) {
+  if (mimeType.startsWith("image/")) return Image;
+  if (mimeType.startsWith("video/")) return Film;
+  if (mimeType.startsWith("audio/")) return Music;
+  if (mimeType === "application/pdf") return FileText;
+  if (
+    mimeType === "application/zip" ||
+    mimeType === "application/x-rar-compressed" ||
+    mimeType === "application/gzip"
+  )
+    return Archive;
+  return File;
+}
+
+/**
+ * AttachmentList displays a read-only list of file attachments
+ * with type icons, formatted sizes, and optional download/remove actions.
+ */
+export function AttachmentList({
+  files,
+  onDownload,
+  onRemove,
+  readOnly = true,
+  className,
+  style,
+}: AttachmentListProps) {
+  if (files.length === 0) return null;
+
+  return (
+    <div className={cn("flex flex-col gap-1", className)} style={style}>
+      {files.map((file, index) => {
+        const Icon = getFileIcon(file.type);
+
+        return (
+          <div
+            key={`${file.name}-${index}`}
+            className="flex items-center gap-3 rounded-md px-2 py-1.5 hover:bg-muted/50 transition-colors"
+          >
+            <span className="shrink-0 text-muted-foreground">
+              <Icon size={18} />
+            </span>
+            <div className="flex-1 min-w-0">
+              <span className="text-sm text-foreground block truncate">
+                {file.name}
+              </span>
+              <span className="text-xs text-muted-foreground">
+                {formatFileSize(file.size)}
+              </span>
+            </div>
+            {onDownload && file.url && (
+              <Button
+                variant="ghost"
+                size="sm"
+                className="shrink-0 h-7 w-7 p-0"
+                onClick={() => onDownload(file)}
+                aria-label={`Download ${file.name}`}
+              >
+                <Download size={14} />
+              </Button>
+            )}
+            {!readOnly && onRemove && (
+              <Button
+                variant="ghost"
+                size="sm"
+                className="shrink-0 h-7 w-7 p-0 text-muted-foreground hover:text-destructive"
+                onClick={() => onRemove(file)}
+                aria-label={`Remove ${file.name}`}
+              >
+                <X size={14} />
+              </Button>
+            )}
+          </div>
+        );
+      })}
+    </div>
+  );
+}