@hydralms/components 0.2.0 → 0.3.0

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

@@ -1,3 +1,4 @@
+import { memo } from "react";
 import { Clock } from "lucide-react";
 import { cn } from "../lib/utils";
 import { formatTimer } from "../utils/format-duration";
@@ -22,11 +23,11 @@ function getTimerClasses(isDanger: boolean, isWarning: boolean) {
   };
 }
 
-export const TimerDisplay = ({
+export const TimerDisplay = memo(function TimerDisplay({
   timeElapsedSeconds,
   timeLimitSeconds,
   variant = "compact",
-}: TimerDisplayProps) => {
+}: TimerDisplayProps) {
   const hasTimeLimit = timeLimitSeconds != null && timeLimitSeconds > 0;
   const remainingSeconds = hasTimeLimit
     ? Math.max(0, timeLimitSeconds - timeElapsedSeconds)
@@ -70,4 +71,4 @@ export const TimerDisplay = ({
       </span>
     </div>
   );
-};
+});

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

@@ -134,7 +134,7 @@ export function useCountdown({
       startInterval();
     }
     return clearTimer;
-  }, []); // eslint-disable-line react-hooks/exhaustive-deps
+  }, [autoStart, startInterval, clearTimer]);
 
   const state = stateRef.current;
 

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

@@ -4,6 +4,7 @@ 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,
@@ -12,4 +13,5 @@ export type {
   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, useMemo, useRef } 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";
@@ -23,6 +23,7 @@ export function SearchInput({
     () => 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/types.ts

@@ -166,3 +166,5 @@ export interface StepperProps {
   /** Inline styles for the root element */
   style?: React.CSSProperties;
 }
+
+export type { PaginationProps } from "./pagination";

package/src/content/attachment-list.tsx

@@ -68,6 +68,7 @@ export function AttachmentList({
                 size="sm"
                 className="shrink-0 h-7 w-7 p-0"
                 onClick={() => onDownload(file)}
+                aria-label={`Download ${file.name}`}
               >
                 <Download size={14} />
               </Button>
@@ -78,6 +79,7 @@ export function AttachmentList({
                 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>

package/src/content/audio-player.tsx

@@ -0,0 +1,196 @@
+import { memo, useCallback, useRef, useState } from "react";
+import { Play, Pause, Volume2, VolumeX } from "lucide-react";
+import { cn } from "../lib/utils";
+import { Button } from "../ui/button";
+import { formatTimer } from "../utils/format-duration";
+
+/**
+ * AudioPlayer provides an HTML5 audio player with custom controls
+ * including play/pause, seek, speed adjustment, and mute toggle.
+ *
+ * @example
+ * <AudioPlayer src="/audio/lecture-1.mp3" title="Lecture 1: Introduction" />
+ */
+export interface AudioPlayerProps {
+  /** Audio source URL */
+  src: string;
+  /** Optional title displayed above the player */
+  title?: string;
+  /** Called when playback ends */
+  onEnded?: () => void;
+  /** Called on time update with current time and duration */
+  onTimeUpdate?: (currentTime: number, duration: number) => void;
+  /** CSS class name for the root element */
+  className?: string;
+  /** Inline styles for the root element */
+  style?: React.CSSProperties;
+}
+
+const SPEEDS = [0.5, 0.75, 1, 1.25, 1.5, 2];
+
+export const AudioPlayer = memo(function AudioPlayer({
+  src,
+  title,
+  onEnded,
+  onTimeUpdate,
+  className,
+  style,
+}: AudioPlayerProps) {
+  const audioRef = useRef<HTMLAudioElement>(null);
+  const [isPlaying, setIsPlaying] = useState(false);
+  const [isMuted, setIsMuted] = useState(false);
+  const [currentTime, setCurrentTime] = useState(0);
+  const [duration, setDuration] = useState(0);
+  const [speed, setSpeed] = useState(1);
+  const lastReportedTime = useRef(-1);
+  const onTimeUpdateRef = useRef(onTimeUpdate);
+  onTimeUpdateRef.current = onTimeUpdate;
+
+  const togglePlay = useCallback(() => {
+    const audio = audioRef.current;
+    if (!audio) return;
+    if (audio.paused) {
+      audio.play();
+    } else {
+      audio.pause();
+    }
+  }, []);
+
+  const toggleMute = useCallback(() => {
+    const audio = audioRef.current;
+    if (!audio) return;
+    audio.muted = !audio.muted;
+    setIsMuted((prev) => !prev);
+  }, []);
+
+  const cycleSpeed = useCallback(() => {
+    const audio = audioRef.current;
+    if (!audio) return;
+    setSpeed((prev) => {
+      const idx = SPEEDS.indexOf(prev);
+      const next = SPEEDS[(idx + 1) % SPEEDS.length];
+      audio.playbackRate = next;
+      return next;
+    });
+  }, []);
+
+  const handleSeek = useCallback(
+    (e: React.ChangeEvent<HTMLInputElement>) => {
+      const audio = audioRef.current;
+      if (!audio) return;
+      const time = Number(e.target.value);
+      audio.currentTime = time;
+      lastReportedTime.current = Math.floor(time * 4) / 4;
+      setCurrentTime(time);
+    },
+    [],
+  );
+
+  const handleTimeUpdate = useCallback(() => {
+    const audio = audioRef.current;
+    if (!audio) return;
+    const rounded = Math.floor(audio.currentTime * 4) / 4;
+    if (rounded !== lastReportedTime.current) {
+      lastReportedTime.current = rounded;
+      setCurrentTime(audio.currentTime);
+      onTimeUpdateRef.current?.(audio.currentTime, audio.duration);
+    }
+  }, []);
+
+  const handleLoadedMetadata = useCallback(() => {
+    const audio = audioRef.current;
+    if (audio && !isNaN(audio.duration)) setDuration(audio.duration);
+  }, []);
+
+  const progress = duration > 0 ? (currentTime / duration) * 100 : 0;
+
+  return (
+    <div
+      data-slot="audio-player"
+      className={cn("rounded-lg border bg-card p-4 space-y-3", className)}
+      style={style}
+    >
+      {title && (
+        <p className="text-sm font-medium text-foreground">{title}</p>
+      )}
+      <audio
+        ref={audioRef}
+        src={src}
+        onPlay={() => setIsPlaying(true)}
+        onPause={() => setIsPlaying(false)}
+        onEnded={() => {
+          setIsPlaying(false);
+          onEnded?.();
+        }}
+        onTimeUpdate={handleTimeUpdate}
+        onLoadedMetadata={handleLoadedMetadata}
+        preload="metadata"
+      />
+      <div className="flex items-center gap-3">
+        <Button
+          variant="ghost"
+          size="icon-sm"
+          onClick={togglePlay}
+          aria-label={isPlaying ? "Pause" : "Play"}
+        >
+          {isPlaying ? (
+            <Pause className="size-4" />
+          ) : (
+            <Play className="size-4" />
+          )}
+        </Button>
+
+        <span className="text-xs tabular-nums text-muted-foreground w-12 shrink-0">
+          {formatTimer(Math.floor(currentTime))}
+        </span>
+
+        <div className="relative flex-1 h-5 flex items-center">
+          <div className="absolute inset-y-0 left-0 flex items-center w-full">
+            <div className="w-full h-1 rounded-full bg-muted overflow-hidden">
+              <div
+                className="h-full bg-primary rounded-full transition-[width] duration-100"
+                style={{ width: `${progress}%` }}
+              />
+            </div>
+          </div>
+          <input
+            type="range"
+            min={0}
+            max={duration || 0}
+            step={0.1}
+            value={currentTime}
+            onChange={handleSeek}
+            className="absolute inset-0 w-full opacity-0 cursor-pointer"
+            aria-label="Seek"
+          />
+        </div>
+
+        <span className="text-xs tabular-nums text-muted-foreground w-12 shrink-0 text-right">
+          {formatTimer(Math.floor(duration))}
+        </span>
+
+        <Button
+          variant="ghost"
+          size="icon-xs"
+          onClick={toggleMute}
+          aria-label={isMuted ? "Unmute" : "Mute"}
+        >
+          {isMuted ? (
+            <VolumeX className="size-3.5" />
+          ) : (
+            <Volume2 className="size-3.5" />
+          )}
+        </Button>
+
+        <button
+          type="button"
+          onClick={cycleSpeed}
+          className="text-xs font-medium text-muted-foreground hover:text-foreground transition-colors tabular-nums w-8 text-center"
+          aria-label={`Playback speed ${speed}x`}
+        >
+          {speed}x
+        </button>
+      </div>
+    </div>
+  );
+});

package/src/content/code-block.tsx

@@ -0,0 +1,113 @@
+import { memo, useCallback, useEffect, useRef, useState } from "react";
+import { Copy, Check, FileCode } from "lucide-react";
+import { cn } from "../lib/utils";
+import { Button } from "../ui/button";
+
+/**
+ * CodeBlock renders source code with optional line numbers, a filename header,
+ * and a copy-to-clipboard button. Does not bundle a syntax highlighter —
+ * consumers can apply their own (Prism, Shiki, etc.) via the `language-*` class on the `<code>` element.
+ *
+ * @example
+ * <CodeBlock
+ *   code="console.log('hello');"
+ *   language="javascript"
+ *   filename="example.js"
+ *   showLineNumbers
+ * />
+ */
+export interface CodeBlockProps {
+  /** The code content to display */
+  code: string;
+  /** Programming language identifier (applied as `language-*` class on `<code>`) */
+  language?: string;
+  /** Optional filename shown in the header bar */
+  filename?: string;
+  /** Whether to display line numbers */
+  showLineNumbers?: boolean;
+  /** Called after code is copied to clipboard */
+  onCopy?: () => void;
+  /** CSS class name for the root element */
+  className?: string;
+  /** Inline styles for the root element */
+  style?: React.CSSProperties;
+}
+
+export const CodeBlock = memo(function CodeBlock({
+  code,
+  language,
+  filename,
+  showLineNumbers = false,
+  onCopy,
+  className,
+  style,
+}: CodeBlockProps) {
+  const [copied, setCopied] = useState(false);
+  const hasHeader = !!(filename || language);
+  const copyTimerRef = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+  useEffect(() => () => clearTimeout(copyTimerRef.current), []);
+
+  const handleCopy = useCallback(async () => {
+    try {
+      await navigator.clipboard.writeText(code);
+      setCopied(true);
+      onCopy?.();
+      clearTimeout(copyTimerRef.current);
+      copyTimerRef.current = setTimeout(() => setCopied(false), 2000);
+    } catch {
+      // Clipboard API not available
+    }
+  }, [code, onCopy]);
+
+  const lines = code.split("\n");
+
+  const copyButton = (
+    <Button
+      variant="ghost"
+      size="icon-xs"
+      onClick={handleCopy}
+      aria-label={copied ? "Copied" : "Copy code"}
+    >
+      {copied ? <Check className="size-3" /> : <Copy className="size-3" />}
+    </Button>
+  );
+
+  return (
+    <div
+      data-slot="code-block"
+      className={cn(
+        "relative rounded-lg border bg-card overflow-hidden text-sm",
+        className,
+      )}
+      style={style}
+    >
+      {hasHeader ? (
+        <div className="flex items-center justify-between px-4 py-2 border-b bg-muted/50">
+          <div className="flex items-center gap-2 text-xs text-muted-foreground">
+            <FileCode className="size-3.5" />
+            <span>{filename ?? language}</span>
+          </div>
+          {copyButton}
+        </div>
+      ) : (
+        <div className="absolute top-2 right-2 z-10">{copyButton}</div>
+      )}
+      <div className="overflow-x-auto">
+        <pre className="p-4 m-0">
+          <code className={language ? `language-${language}` : undefined}>
+            {showLineNumbers
+              ? lines.map((line, i) => (
+                  <div key={i} className="flex">
+                    <span className="select-none text-muted-foreground/50 w-8 shrink-0 text-right pr-4 tabular-nums">
+                      {i + 1}
+                    </span>
+                    <span>{line}</span>
+                  </div>
+                ))
+              : code}
+          </code>
+        </pre>
+      </div>
+    </div>
+  );
+});

package/src/content/content-block.tsx

@@ -5,6 +5,19 @@ import { QuestionRenderer } from "../questions";
 import { FlashcardDeck } from "../flashcards";
 import { Alert, AlertDescription } from "../ui/alert";
 import { Separator } from "../ui/separator";
+import {
+  Table,
+  TableHeader,
+  TableBody,
+  TableRow,
+  TableHead,
+  TableCell,
+  TableCaption,
+} from "../ui/table";
+import { AudioPlayer } from "./audio-player";
+import { CodeBlock } from "./code-block";
+import { EmbedBlock } from "./embed-block";
+import { AttachmentList } from "./attachment-list";
 import type { ContentBlockProps } from "./types";
 import { cn } from "../lib/utils";
 
@@ -106,6 +119,57 @@ export const ContentBlock = memo(function ContentBlock({
         />
       );
 
+    case "audio":
+      return wrapper(
+        <AudioPlayer src={block.src} title={block.title} />
+      );
+
+    case "code":
+      return wrapper(
+        <CodeBlock
+          code={block.code}
+          language={block.language}
+          filename={block.filename}
+          showLineNumbers={block.showLineNumbers}
+        />
+      );
+
+    case "embed":
+      return wrapper(
+        <EmbedBlock
+          src={block.src}
+          title={block.title}
+          aspectRatio={block.aspectRatio}
+          allowFullscreen={block.allowFullscreen}
+        />
+      );
+
+    case "table":
+      return wrapper(
+        <Table>
+          {block.caption && <TableCaption>{block.caption}</TableCaption>}
+          <TableHeader>
+            <TableRow>
+              {block.headers.map((header, i) => (
+                <TableHead key={i}>{header}</TableHead>
+              ))}
+            </TableRow>
+          </TableHeader>
+          <TableBody>
+            {block.rows.map((row, i) => (
+              <TableRow key={i}>
+                {row.map((cell, j) => (
+                  <TableCell key={j}>{cell}</TableCell>
+                ))}
+              </TableRow>
+            ))}
+          </TableBody>
+        </Table>
+      );
+
+    case "file":
+      return wrapper(<AttachmentList files={block.files} readOnly />);
+
     case "divider":
       return wrapper(<Separator />);
 

package/src/content/embed-block.tsx

@@ -0,0 +1,78 @@
+import { memo, useState } from "react";
+import { ExternalLink } from "lucide-react";
+import { cn } from "../lib/utils";
+import { Skeleton } from "../ui/skeleton";
+
+export type EmbedAspectRatio = "16/9" | "4/3" | "1/1";
+
+/**
+ * EmbedBlock renders a responsive iframe wrapper with an optional title bar
+ * and loading skeleton. Ideal for embedding YouTube videos, SCORM objects,
+ * Google Slides, and other external content.
+ *
+ * @example
+ * <EmbedBlock
+ *   src="https://www.youtube.com/embed/dQw4w9WgXcQ"
+ *   title="Introduction Video"
+ *   aspectRatio="16/9"
+ * />
+ */
+export interface EmbedBlockProps {
+  /** iframe source URL */
+  src: string;
+  /** Optional title for the embed */
+  title?: string;
+  /** Aspect ratio of the embed container */
+  aspectRatio?: EmbedAspectRatio;
+  /** Whether to allow fullscreen */
+  allowFullscreen?: boolean;
+  /** CSS class name for the root element */
+  className?: string;
+  /** Inline styles for the root element */
+  style?: React.CSSProperties;
+}
+
+const ASPECT_CLASSES: Record<EmbedAspectRatio, string> = {
+  "16/9": "aspect-video",
+  "4/3": "aspect-[4/3]",
+  "1/1": "aspect-square",
+};
+
+export const EmbedBlock = memo(function EmbedBlock({
+  src,
+  title,
+  aspectRatio = "16/9",
+  allowFullscreen = true,
+  className,
+  style,
+}: EmbedBlockProps) {
+  const [isLoaded, setIsLoaded] = useState(false);
+
+  return (
+    <div
+      data-slot="embed-block"
+      className={cn("rounded-lg border bg-card overflow-hidden", className)}
+      style={style}
+    >
+      {title && (
+        <div className="flex items-center justify-between px-4 py-2 border-b bg-muted/50">
+          <div className="flex items-center gap-2 text-xs text-muted-foreground">
+            <ExternalLink className="size-3.5" />
+            <span>{title}</span>
+          </div>
+        </div>
+      )}
+      <div className={cn("relative w-full", ASPECT_CLASSES[aspectRatio])}>
+        {!isLoaded && <Skeleton className="absolute inset-0 rounded-none" />}
+        <iframe
+          src={src}
+          title={title ?? "Embedded content"}
+          allowFullScreen={allowFullscreen}
+          onLoad={() => setIsLoaded(true)}
+          className="absolute inset-0 w-full h-full border-0"
+          sandbox="allow-scripts allow-same-origin allow-popups allow-presentation"
+        />
+      </div>
+    </div>
+  );
+});