@hydralms/components 0.1.2 → 0.2.0

package/src/assessment-toolbar/question-header-bar.tsx

@@ -0,0 +1,61 @@
+import { BookOpen, Flag } from "lucide-react";
+import { Button } from "../ui/button";
+import { cn } from "../lib/utils";
+import type { QuestionHeaderBarProps } from "./types";
+
+export const QuestionHeaderBar = ({
+  questionNumber,
+  totalQuestions,
+  isFlagged,
+  onToggleFlag,
+  hasMaterials = false,
+  onOpenMaterials,
+  readOnly = false,
+}: QuestionHeaderBarProps) => {
+  return (
+    <div className="flex items-center justify-between pb-3 border-b border-border">
+      <span className="text-sm font-semibold text-foreground">
+        Question {questionNumber}{" "}
+        <span className="font-normal text-muted-foreground">
+          of {totalQuestions}
+        </span>
+      </span>
+
+      {!readOnly && (
+        <div className="flex items-center gap-1">
+          {hasMaterials && onOpenMaterials && (
+            <Button
+              variant="ghost"
+              size="sm"
+              className="gap-1.5 text-muted-foreground hover:text-foreground"
+              onClick={onOpenMaterials}
+            >
+              <BookOpen size={14} />
+              Related Material
+            </Button>
+          )}
+
+          {onToggleFlag && (
+            <Button
+              variant="ghost"
+              size="icon"
+              className={cn(
+                "size-8",
+                isFlagged
+                  ? "text-warning hover:text-warning/80"
+                  : "text-muted-foreground hover:text-warning",
+              )}
+              onClick={onToggleFlag}
+              aria-label={isFlagged ? "Unflag question" : "Flag question"}
+            >
+              <Flag
+                size={14}
+                fill={isFlagged ? "currentColor" : "none"}
+              />
+            </Button>
+          )}
+        </div>
+      )}
+    </div>
+  );
+};

package/src/assessment-toolbar/question-materials-drawer.tsx

@@ -0,0 +1,55 @@
+import {
+  Drawer,
+  DrawerContent,
+  DrawerHeader,
+  DrawerTitle,
+  DrawerBody,
+  DrawerClose,
+} from "../ui/drawer";
+import { ContentBlock } from "../content";
+import type { QuestionMaterialsDrawerProps } from "./types";
+
+export const QuestionMaterialsDrawer = ({
+  open,
+  onOpenChange,
+  materials,
+  questionNumber,
+}: QuestionMaterialsDrawerProps) => {
+  if (!materials.length) return null;
+
+  const drawerTitle = questionNumber
+    ? `Question ${questionNumber} — Related Material`
+    : "Related Material";
+
+  return (
+    <Drawer open={open} onOpenChange={onOpenChange} side="right">
+      <DrawerContent size="lg" scrollLock={false}>
+        <DrawerHeader className="flex-row items-center justify-between">
+          <DrawerTitle>{drawerTitle}</DrawerTitle>
+          <DrawerClose />
+        </DrawerHeader>
+        <DrawerBody>
+          <div className="space-y-6">
+            {materials.map((material, mi) => (
+              <section key={mi}>
+                {material.label && (
+                  <h3 className="text-sm font-semibold text-foreground mb-3">
+                    {material.label}
+                  </h3>
+                )}
+                <div className="space-y-4">
+                  {material.blocks.map((block, bi) => (
+                    <ContentBlock key={bi} block={block} readOnly />
+                  ))}
+                </div>
+                {mi < materials.length - 1 && (
+                  <div className="border-b border-border mt-6" />
+                )}
+              </section>
+            ))}
+          </div>
+        </DrawerBody>
+      </DrawerContent>
+    </Drawer>
+  );
+};

package/src/assessment-toolbar/question-navigator.tsx

@@ -1,6 +1,4 @@
-import { Flag } from "lucide-react";
 import type { QuestionNavigatorProps } from "./types";
-import { Tooltip, TooltipTrigger, TooltipContent } from "../ui/tooltip";
 import { cn } from "../lib/utils";
 
 const CHIP_CLASSES = {
@@ -24,7 +22,6 @@ export const QuestionNavigator = ({
   questions,
   currentQuestionUid,
   onNavigate,
-  onToggleFlag,
   readOnly = false,
 }: QuestionNavigatorProps) => {
   const getTooltipContent = (q: (typeof questions)[0]): string => {
@@ -36,7 +33,7 @@ export const QuestionNavigator = ({
   };
 
   return (
-    <div className="flex flex-wrap gap-1.5">
+    <div className="flex gap-1">
       {questions.map((q) => {
         const variant = getChipVariant(q, currentQuestionUid);
         return (
@@ -44,40 +41,15 @@ export const QuestionNavigator = ({
             key={q.uid}
             title={getTooltipContent(q)}
             className={cn(
-              "inline-flex items-center gap-1 px-2 py-1 rounded-md border transition-all duration-150",
+              "inline-flex items-center justify-center px-1.5 py-0.5 rounded border text-[11px] leading-tight transition-all duration-150 min-w-5.5",
               CHIP_CLASSES[variant],
               readOnly ? "cursor-default" : "cursor-pointer hover:shadow-sm hover:-translate-y-px",
             )}
             onClick={readOnly ? undefined : () => onNavigate?.(q.uid)}
           >
-            <span className="text-xs font-semibold min-w-4 text-center">
+            <span className="font-semibold min-w-3.5 text-center">
               {q.sequence + 1}
             </span>
-            {!readOnly && onToggleFlag && (
-              <Tooltip>
-                <TooltipTrigger>
-                  <span
-                    role="button"
-                    aria-label={q.isFlagged ? "Unflag question" : "Flag question"}
-                    className={cn(
-                      "inline-flex cursor-pointer transition-colors duration-150",
-                      q.isFlagged
-                        ? "text-warning"
-                        : variant === "current"
-                          ? "text-primary-foreground/60 hover:text-primary-foreground"
-                          : "text-muted-foreground hover:text-warning",
-                    )}
-                    onClick={(e: React.MouseEvent) => {
-                      e.stopPropagation();
-                      onToggleFlag(q.uid);
-                    }}
-                  >
-                    <Flag size={11} fill={q.isFlagged ? "currentColor" : "none"} />
-                  </span>
-                </TooltipTrigger>
-                <TooltipContent>{q.isFlagged ? "Unflag question" : "Flag question"}</TooltipContent>
-              </Tooltip>
-            )}
           </div>
         );
       })}

package/src/assessment-toolbar/timer-display.tsx

@@ -52,7 +52,7 @@ export const TimerDisplay = ({
         <span className="inline-flex leading-none">
           <Clock size={13} />
         </span>
-        <span className="text-xs font-semibold font-mono tracking-wide">
+        <span className="text-xs font-semibold font-mono tracking-wide" aria-live="polite" aria-atomic="true">
           {displayTime}
         </span>
       </div>
@@ -66,7 +66,7 @@ export const TimerDisplay = ({
       </span>
       <span className={cn("text-sm", classes.bold && "font-semibold")}>
         {hasTimeLimit ? "Time remaining: " : "Time elapsed: "}
-        <span className="font-mono font-semibold">{displayTime}</span>
+        <span className="font-mono font-semibold" aria-live="polite" aria-atomic="true">{displayTime}</span>
       </span>
     </div>
   );

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;
+  }, []); // eslint-disable-line react-hooks/exhaustive-deps
+
+  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/index.ts

@@ -3,10 +3,13 @@ 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 type {
   EmptyStateProps,
   ConfirmDialogProps,
   SearchInputProps,
   StatusBadgeProps,
   DueDateDisplayProps,
+  StepperProps,
+  StepDefinition,
 } from "./types";

package/src/common/search-input.tsx

@@ -1,4 +1,4 @@
-import { useState, useEffect, useCallback } from "react";
+import { useState, useMemo, useRef } from "react";
 import { Search, X } from "lucide-react";
 import { debounce } from "../utils/debounce";
 import type { SearchInputProps } from "./types";
@@ -16,12 +16,13 @@ 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],
+  );
 
   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,42 @@ 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;
+}