@hydralms/components 0.1.1 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hydralms/components",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "React component library for LMS platforms",
   "license": "MIT",
   "author": "HydraLMS",
@@ -30,6 +30,7 @@
   "module": "./src/index.ts",
   "types": "./src/index.ts",
   "files": [
+    "src",
     "dist",
     "LICENSE",
     "README.md"
@@ -134,6 +135,7 @@
       "types": "./src/provider/index.ts",
       "default": "./src/provider/index.ts"
     },
+    "./*": "./src/*",
     "./styles.css": "./src/styles/globals.css",
     "./package.json": "./package.json"
   },

package/src/__tests__/setup.ts

@@ -0,0 +1 @@
+import "@testing-library/jest-dom/vitest";

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

@@ -0,0 +1,96 @@
+import { ChevronLeft, ChevronRight, Send } from "lucide-react";
+import { TimerDisplay } from "./timer-display";
+import { QuestionNavigator } from "./question-navigator";
+import { Button } from "../ui/button";
+import type { AssessmentToolbarProps } from "./types";
+
+export const AssessmentToolbar = ({
+  currentQuestionIndex,
+  totalQuestions,
+  hasNext,
+  hasPrevious,
+  onNext,
+  onPrevious,
+  onSubmit,
+  timeElapsedSeconds,
+  timeLimitSeconds,
+  questions,
+  onNavigateToQuestion,
+  onToggleFlag,
+  currentQuestionUid,
+  isCompleted = false,
+  isSubmitting = false,
+  readOnly = false,
+}: AssessmentToolbarProps) => {
+  const showTimer =
+    timeElapsedSeconds != null && timeElapsedSeconds >= 0;
+  const showNavigator = questions && questions.length > 0;
+
+  return (
+    <div className="rounded-lg border border-border overflow-hidden shadow-sm">
+      {/* Header */}
+      <div className="flex items-center justify-between px-4 py-2.5 bg-muted border-b border-border">
+        <span className="text-sm font-medium text-foreground">
+          Question{" "}
+          <span className="font-bold">{currentQuestionIndex + 1}</span>
+          {" "}of {totalQuestions}
+        </span>
+
+        {showTimer && (
+          <TimerDisplay
+            timeElapsedSeconds={timeElapsedSeconds}
+            timeLimitSeconds={timeLimitSeconds}
+          />
+        )}
+      </div>
+
+      {/* Navigator */}
+      {showNavigator && (
+        <div className="px-4 py-3 border-b border-border">
+          <QuestionNavigator
+            questions={questions}
+            currentQuestionUid={currentQuestionUid}
+            onNavigate={onNavigateToQuestion}
+            onToggleFlag={onToggleFlag}
+            readOnly={readOnly}
+          />
+        </div>
+      )}
+
+      {/* Navigation buttons */}
+      <div className="flex items-center justify-between gap-2 px-4 py-3">
+        <Button
+          variant="outline"
+          size="sm"
+          className="rounded-lg"
+          disabled={!hasPrevious || readOnly}
+          onClick={onPrevious}
+        >
+          <ChevronLeft size={16} /> Previous
+        </Button>
+
+        {!hasNext || isCompleted ? (
+          <Button
+            variant={isCompleted ? "secondary" : "default"}
+            size="sm"
+            className="rounded-lg"
+            onClick={onSubmit}
+            disabled={readOnly || isSubmitting}
+          >
+            {isSubmitting ? "Submitting..." : isCompleted ? "Review" : "Submit"}
+            {!isSubmitting && <Send size={14} />}
+          </Button>
+        ) : (
+          <Button
+            size="sm"
+            className="rounded-lg"
+            disabled={!hasNext || readOnly}
+            onClick={onNext}
+          >
+            Next <ChevronRight size={16} />
+          </Button>
+        )}
+      </div>
+    </div>
+  );
+};

package/src/assessment-toolbar/index.ts

@@ -0,0 +1,10 @@
+export { AssessmentToolbar } from "./assessment-toolbar";
+export { TimerDisplay } from "./timer-display";
+export { QuestionNavigator } from "./question-navigator";
+
+export type {
+  AssessmentToolbarProps,
+  TimerDisplayProps,
+  QuestionNavigatorProps,
+  QuestionNavigatorItem,
+} from "./types";

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

@@ -0,0 +1,86 @@
+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 = {
+  current: "bg-primary text-primary-foreground border-primary",
+  flagged: "bg-warning/10 text-warning border-warning/30",
+  answered: "bg-success/10 text-success border-success/30",
+  default: "bg-background text-muted-foreground border-border",
+} as const;
+
+const getChipVariant = (
+  q: { uid: string; isFlagged: boolean; isAnswered: boolean },
+  currentUid?: string,
+): keyof typeof CHIP_CLASSES => {
+  if (q.uid === currentUid) return "current";
+  if (q.isFlagged) return "flagged";
+  if (q.isAnswered) return "answered";
+  return "default";
+};
+
+export const QuestionNavigator = ({
+  questions,
+  currentQuestionUid,
+  onNavigate,
+  onToggleFlag,
+  readOnly = false,
+}: QuestionNavigatorProps) => {
+  const getTooltipContent = (q: (typeof questions)[0]): string => {
+    const parts: string[] = [`Question ${q.sequence + 1}`];
+    if (q.isFlagged) parts.push("Flagged");
+    if (q.isAnswered) parts.push("Answered");
+    if (q.isSkipped) parts.push("Skipped");
+    return parts.join(" \u00B7 ");
+  };
+
+  return (
+    <div className="flex flex-wrap gap-1.5">
+      {questions.map((q) => {
+        const variant = getChipVariant(q, currentQuestionUid);
+        return (
+          <div
+            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",
+              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">
+              {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>
+        );
+      })}
+    </div>
+  );
+};

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

@@ -0,0 +1,73 @@
+import { Clock } from "lucide-react";
+import { cn } from "../lib/utils";
+import { formatTimer } from "../utils/format-duration";
+import type { TimerDisplayProps } from "./types";
+
+function getTimerClasses(isDanger: boolean, isWarning: boolean) {
+  if (isDanger) {
+    return {
+      wrapper: "border-destructive/30 bg-destructive/10 text-destructive",
+      bold: true,
+    };
+  }
+  if (isWarning) {
+    return {
+      wrapper: "border-warning/30 bg-warning/10 text-warning",
+      bold: true,
+    };
+  }
+  return {
+    wrapper: "border-border bg-muted text-muted-foreground",
+    bold: false,
+  };
+}
+
+export const TimerDisplay = ({
+  timeElapsedSeconds,
+  timeLimitSeconds,
+  variant = "compact",
+}: TimerDisplayProps) => {
+  const hasTimeLimit = timeLimitSeconds != null && timeLimitSeconds > 0;
+  const remainingSeconds = hasTimeLimit
+    ? Math.max(0, timeLimitSeconds - timeElapsedSeconds)
+    : 0;
+
+  const isWarning = hasTimeLimit && remainingSeconds < timeLimitSeconds * 0.1;
+  const isDanger = hasTimeLimit && remainingSeconds <= 60;
+
+  const displayTime = hasTimeLimit
+    ? formatTimer(remainingSeconds)
+    : formatTimer(timeElapsedSeconds);
+
+  const classes = getTimerClasses(isDanger, isWarning);
+
+  if (variant === "compact") {
+    return (
+      <div
+        className={cn(
+          "flex items-center gap-1.5 px-2.5 py-1 rounded-full border",
+          classes.wrapper,
+        )}
+      >
+        <span className="inline-flex leading-none">
+          <Clock size={13} />
+        </span>
+        <span className="text-xs font-semibold font-mono tracking-wide">
+          {displayTime}
+        </span>
+      </div>
+    );
+  }
+
+  return (
+    <div className={cn("flex items-center gap-1.5", classes.wrapper)}>
+      <span className="inline-flex leading-none">
+        <Clock size={16} />
+      </span>
+      <span className={cn("text-sm", classes.bold && "font-semibold")}>
+        {hasTimeLimit ? "Time remaining: " : "Time elapsed: "}
+        <span className="font-mono font-semibold">{displayTime}</span>
+      </span>
+    </div>
+  );
+};

package/src/assessment-toolbar/types.ts

@@ -0,0 +1,92 @@
+/**
+ * AssessmentToolbar provides navigation controls, timer, and question overview for quiz/assessment sessions.
+ *
+ * @example
+ * <AssessmentToolbar
+ *   currentQuestionIndex={0}
+ *   totalQuestions={10}
+ *   hasNext
+ *   hasPrevious={false}
+ *   onNext={() => setIndex(i => i + 1)}
+ *   onPrevious={() => setIndex(i => i - 1)}
+ *   onSubmit={handleSubmit}
+ *   timeElapsedSeconds={120}
+ *   timeLimitSeconds={1800}
+ * />
+ */
+export interface AssessmentToolbarProps {
+  /** Zero-based index of the current question */
+  currentQuestionIndex: number;
+  /** Total number of questions in the assessment */
+  totalQuestions: number;
+  /** Whether a next question is available */
+  hasNext: boolean;
+  /** Whether a previous question is available */
+  hasPrevious: boolean;
+  /** Called when the user clicks Next */
+  onNext: () => void;
+  /** Called when the user clicks Previous */
+  onPrevious: () => void;
+  /** Called when the user submits the assessment */
+  onSubmit: () => void;
+  /** Elapsed time in seconds for the timer display */
+  timeElapsedSeconds?: number;
+  /** Time limit in seconds — when set, shows countdown instead of elapsed */
+  timeLimitSeconds?: number;
+  /** List of questions for the navigator chips */
+  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 */
+  isCompleted?: boolean;
+  /** Whether the submit action is in progress */
+  isSubmitting?: boolean;
+  /** When true, disables all interactive controls */
+  readOnly?: boolean;
+}
+
+/**
+ * TimerDisplay shows elapsed or remaining time for an assessment.
+ *
+ * @example
+ * <TimerDisplay timeElapsedSeconds={90} timeLimitSeconds={600} variant="compact" />
+ */
+export interface TimerDisplayProps {
+  /** Total seconds elapsed since the assessment started */
+  timeElapsedSeconds: number;
+  /** Optional time limit in seconds — enables countdown mode */
+  timeLimitSeconds?: number;
+  /** Display variant: compact chip or full text */
+  variant?: "compact" | "full";
+}
+
+/**
+ * QuestionNavigator renders chip-based navigation for quickly jumping between questions.
+ *
+ * @example
+ * <QuestionNavigator
+ *   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;
+}
+
+export interface QuestionNavigatorItem {
+  uid: string;
+  sequence: number;
+  isFlagged: boolean;
+  isAnswered: boolean;
+  isSkipped: boolean;
+}

package/src/assets/hydra-icon.svg

@@ -0,0 +1,18 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round">
+  <!-- Center cobra hood -->
+  <path d="M9 12 C9 7 10 3 12 3 C14 3 15 7 15 12" />
+  <!-- Center hood inner curls -->
+  <path d="M10 10 C10.5 7 12 9 12 9 C12 9 13.5 7 14 10" />
+  <!-- Center jaw -->
+  <path d="M10 12.5 C10.5 14 13.5 14 14 12.5" />
+  <!-- Left cobra — large coil -->
+  <path d="M6.5 13 C3.5 12 1 9 1 6 C1 3 3 1.5 5.5 3.5 C7.5 5.5 7.5 9 6.5 13" />
+  <!-- Right cobra — large coil -->
+  <path d="M17.5 13 C20.5 12 23 9 23 6 C23 3 21 1.5 18.5 3.5 C16.5 5.5 16.5 9 17.5 13" />
+  <!-- Left neck -->
+  <path d="M6.5 13 C7.5 16 9 19 10.5 22" />
+  <!-- Center neck -->
+  <path d="M12 14 L12 22" />
+  <!-- Right neck -->
+  <path d="M17.5 13 C16.5 16 15 19 13.5 22" />
+</svg>

package/src/assets/hydra-lms-icon.svg

@@ -0,0 +1,9 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round">
+  <circle cx="12" cy="12" r="3" fill="currentColor" stroke="none"/>
+  <path d="M10.5 9.5C9 5 5 1.5 2 2.5"/>
+  <path d="M12 9C14 4.5 18 3 22 2"/>
+  <path d="M15 10.5C19 8 22 8.5 23 6"/>
+  <path d="M9 14C5 15 2.5 18.5 1.5 22"/>
+  <path d="M12 15C11 19 12 21.5 11 23"/>
+  <path d="M14.5 14.5C18 17 20.5 20.5 22 23"/>
+</svg>

package/src/common/confirm-dialog.tsx

@@ -0,0 +1,60 @@
+import {
+  AlertDialog,
+  AlertDialogContent,
+  AlertDialogHeader,
+  AlertDialogFooter,
+  AlertDialogTitle,
+  AlertDialogDescription,
+  AlertDialogCancel,
+  AlertDialogAction,
+} from "../ui/alert-dialog";
+import { cn } from "../lib/utils";
+import type { ConfirmDialogProps } from "./types";
+
+const CONFIRM_VARIANT: Record<string, string> = {
+  primary: "bg-primary text-primary-foreground hover:bg-primary/90",
+  error: "bg-destructive text-destructive-foreground hover:bg-destructive/90",
+  warning: "bg-warning text-warning-foreground hover:bg-warning/90",
+};
+
+export function ConfirmDialog({
+  open,
+  title,
+  message,
+  confirmLabel = "Confirm",
+  cancelLabel = "Cancel",
+  confirmColor = "primary",
+  onConfirm,
+  onCancel,
+  isLoading = false,
+}: ConfirmDialogProps) {
+  return (
+    <AlertDialog open={open} onOpenChange={(nextOpen) => !nextOpen && onCancel()}>
+      <AlertDialogContent>
+        <AlertDialogHeader>
+          <AlertDialogTitle>{title}</AlertDialogTitle>
+          {typeof message === "string" ? (
+            <AlertDialogDescription>{message}</AlertDialogDescription>
+          ) : (
+            message
+          )}
+        </AlertDialogHeader>
+        <AlertDialogFooter>
+          <AlertDialogCancel onClick={onCancel} disabled={isLoading}>
+            {cancelLabel}
+          </AlertDialogCancel>
+          <AlertDialogAction
+            className={cn(CONFIRM_VARIANT[confirmColor] ?? CONFIRM_VARIANT.primary)}
+            onClick={onConfirm}
+            disabled={isLoading}
+          >
+            {isLoading && (
+              <span className="inline-block size-4 animate-spin rounded-full border-2 border-current border-t-transparent" />
+            )}
+            {confirmLabel}
+          </AlertDialogAction>
+        </AlertDialogFooter>
+      </AlertDialogContent>
+    </AlertDialog>
+  );
+}

package/src/common/due-date-display.tsx

@@ -0,0 +1,64 @@
+import { Clock, CheckCircle } from "lucide-react";
+import type { DueDateDisplayProps } from "./types";
+import { cn } from "../lib/utils";
+
+const URGENCY_CLASS: Record<string, string> = {
+  success: "text-success",
+  destructive: "text-destructive",
+  warning: "text-warning",
+  muted: "text-muted-foreground",
+};
+
+function getRelativeTime(date: Date): string {
+  const now = new Date();
+  const diffMs = date.getTime() - now.getTime();
+  const diffDays = Math.round(diffMs / (1000 * 60 * 60 * 24));
+
+  if (diffDays === 0) return "Due today";
+  if (diffDays === 1) return "Due tomorrow";
+  if (diffDays === -1) return "Due yesterday";
+  if (diffDays > 1) return `Due in ${diffDays} days`;
+  return `${Math.abs(diffDays)} days overdue`;
+}
+
+function getUrgencyKey(date: Date, submitted: boolean): string {
+  if (submitted) return "success";
+  const now = new Date();
+  const diffMs = date.getTime() - now.getTime();
+  const diffDays = diffMs / (1000 * 60 * 60 * 24);
+  if (diffDays < 0) return "destructive";
+  if (diffDays < 2) return "warning";
+  return "muted";
+}
+
+export function DueDateDisplay({
+  dueDate,
+  submittedDate,
+  showRelative = true,
+  size = "medium",
+  className,
+  style,
+}: DueDateDisplayProps) {
+  const date = new Date(dueDate);
+  const isSubmitted = !!submittedDate;
+  const colorClass = URGENCY_CLASS[getUrgencyKey(date, isSubmitted)] ?? "text-muted-foreground";
+  const iconSize = size === "small" ? 14 : 16;
+
+  return (
+    <div
+      className={cn("flex items-center gap-1", colorClass, className)}
+      style={style}
+    >
+      <span className="shrink-0 inline-flex">
+        {isSubmitted ? <CheckCircle size={iconSize} /> : <Clock size={iconSize} />}
+      </span>
+      <span className={size === "small" ? "text-xs" : "text-sm"}>
+        {isSubmitted
+          ? `Submitted ${new Date(submittedDate).toLocaleDateString()}`
+          : showRelative
+            ? getRelativeTime(date)
+            : date.toLocaleDateString()}
+      </span>
+    </div>
+  );
+}

package/src/common/empty-state.tsx

@@ -0,0 +1,24 @@
+import type { EmptyStateProps } from "./types";
+import { cn } from "../lib/utils";
+
+export function EmptyState({ icon, title, description, action, className, style }: EmptyStateProps) {
+  return (
+    <div
+      className={cn("flex flex-col items-center justify-center text-center px-3 py-6", className)}
+      style={style}
+    >
+      {icon && (
+        <div className="mb-2 text-muted-foreground [&>svg]:size-12">
+          {icon}
+        </div>
+      )}
+      <p className="text-lg font-semibold text-foreground mb-1">{title}</p>
+      {description && (
+        <p className={cn("text-sm text-muted-foreground max-w-[360px]", action && "mb-2")}>
+          {description}
+        </p>
+      )}
+      {action}
+    </div>
+  );
+}

package/src/common/index.ts

@@ -0,0 +1,12 @@
+export { EmptyState } from "./empty-state";
+export { ConfirmDialog } from "./confirm-dialog";
+export { SearchInput } from "./search-input";
+export { StatusBadge } from "./status-badge";
+export { DueDateDisplay } from "./due-date-display";
+export type {
+  EmptyStateProps,
+  ConfirmDialogProps,
+  SearchInputProps,
+  StatusBadgeProps,
+  DueDateDisplayProps,
+} from "./types";

package/src/common/search-input.tsx

@@ -0,0 +1,68 @@
+import { useState, useEffect, useCallback } from "react";
+import { Search, X } from "lucide-react";
+import { debounce } from "../utils/debounce";
+import type { SearchInputProps } from "./types";
+import { cn } from "../lib/utils";
+
+export function SearchInput({
+  value,
+  onChange,
+  placeholder = "Search...",
+  debounceMs = 300,
+  fullWidth = false,
+  size = "small",
+  className,
+  style,
+}: SearchInputProps) {
+  const [localValue, setLocalValue] = useState(value);
+
+  useEffect(() => {
+    setLocalValue(value);
+  }, [value]);
+
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  const debouncedOnChange = useCallback(debounce(onChange, debounceMs), [onChange, debounceMs]);
+
+  function handleChange(e: React.ChangeEvent<HTMLInputElement>) {
+    const next = e.target.value;
+    setLocalValue(next);
+    debouncedOnChange(next);
+  }
+
+  function handleClear() {
+    setLocalValue("");
+    onChange("");
+  }
+
+  return (
+    <div
+      className={cn("w-full", className)}
+      style={{ ...style, width: fullWidth ? "100%" : undefined }}
+    >
+      <div className="flex items-center w-full border border-input rounded-md bg-background transition-colors focus-within:border-ring focus-within:ring-ring/50 focus-within:ring-[3px]">
+        <span className="flex items-center justify-center px-2 text-muted-foreground shrink-0">
+          <Search size={18} />
+        </span>
+        <input
+          className={cn(
+            "flex-1 border-none outline-none bg-transparent text-foreground text-sm min-w-0 placeholder:text-muted-foreground",
+            size === "medium" ? "py-2" : "py-1.5",
+          )}
+          value={localValue}
+          onChange={handleChange}
+          placeholder={placeholder}
+        />
+        {localValue && (
+          <button
+            type="button"
+            className="inline-flex items-center justify-center p-0.5 mr-1 rounded-md text-muted-foreground cursor-pointer transition-colors hover:bg-muted hover:text-foreground"
+            aria-label="Clear search"
+            onClick={handleClear}
+          >
+            <X size={16} />
+          </button>
+        )}
+      </div>
+    </div>
+  );
+}