@hydralms/components 0.1.3 → 0.3.0

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

@@ -1,9 +1,23 @@
+import { memo } from "react";
 import { Info, AlertTriangle, Lightbulb } from "lucide-react";
 import { VideoPlayer } from "../video";
 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";
 
@@ -13,7 +27,7 @@ const CALLOUT_CONFIG = {
   tip: { variant: "success" as const, Icon: Lightbulb },
 };
 
-export function ContentBlock({
+export const ContentBlock = memo(function ContentBlock({
   block,
   onQuestionAnswer,
   readOnly = false,
@@ -57,6 +71,7 @@ export function ContentBlock({
           <img
             src={block.src}
             alt={block.alt ?? ""}
+            loading="lazy"
             className="max-w-full rounded-sm"
           />
           {block.caption && (
@@ -104,6 +119,57 @@ export 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 />);
 
@@ -113,4 +179,4 @@ export function ContentBlock({
     default:
       return null;
   }
-}
+});

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>
+  );
+});

package/src/content/file-upload-zone.tsx

@@ -3,12 +3,7 @@ import { Upload, File, X } from "lucide-react";
 import { Button } from "../ui/button";
 import type { FileUploadZoneProps } from "./types";
 import { cn } from "../lib/utils";
-
-function formatFileSize(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";
 
 export function FileUploadZone({
   files,
@@ -44,7 +39,17 @@ export function FileUploadZone({
           isDragging && "border-primary bg-muted",
           disabled && "cursor-default opacity-50",
           atLimit && "cursor-default",
+          "focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ring",
         )}
+        role="button"
+        tabIndex={disabled || atLimit ? -1 : 0}
+        aria-label={atLimit ? `Maximum ${maxFiles} files reached` : label}
+        onKeyDown={(e) => {
+          if ((e.key === "Enter" || e.key === " ") && !disabled && !atLimit) {
+            e.preventDefault();
+            inputRef.current?.click();
+          }
+        }}
         onDragOver={(e) => {
           e.preventDefault();
           if (!disabled && !atLimit) setIsDragging(true);

package/src/content/index.ts

@@ -1,7 +1,16 @@
 export { ContentBlock } from "./content-block";
 export { FileUploadZone } from "./file-upload-zone";
+export { AttachmentList } from "./attachment-list";
 export type {
   LessonBlock,
   ContentBlockProps,
   FileUploadZoneProps,
+  AttachmentListProps,
+  AttachmentFile,
 } from "./types";
+export { AudioPlayer } from "./audio-player";
+export type { AudioPlayerProps } from "./audio-player";
+export { CodeBlock } from "./code-block";
+export type { CodeBlockProps } from "./code-block";
+export { EmbedBlock } from "./embed-block";
+export type { EmbedBlockProps, EmbedAspectRatio } from "./embed-block";

package/src/content/types.ts

@@ -14,6 +14,11 @@ export type LessonBlock =
   | { type: "callout"; content: string; variant?: "info" | "warning" | "tip" }
   | { type: "question"; question: QuestionData }
   | { type: "flashcards"; cards: FlashcardData[]; deckName?: string }
+  | { type: "audio"; src: string; title?: string }
+  | { type: "code"; code: string; language?: string; filename?: string; showLineNumbers?: boolean }
+  | { type: "embed"; src: string; title?: string; aspectRatio?: "16/9" | "4/3" | "1/1"; allowFullscreen?: boolean }
+  | { type: "table"; headers: string[]; rows: string[][]; caption?: string }
+  | { type: "file"; files: AttachmentFile[] }
   | { type: "divider" }
   | { type: "custom"; render: ReactNode };
 
@@ -74,3 +79,44 @@ export interface FileUploadZoneProps {
   /** Inline styles for the root element */
   style?: React.CSSProperties;
 }
+
+/**
+ * A single file attachment for display in AttachmentList.
+ */
+export interface AttachmentFile {
+  /** File name with extension */
+  name: string;
+  /** File size in bytes */
+  size: number;
+  /** MIME type (e.g. "application/pdf", "image/png") */
+  type: string;
+  /** Optional download URL */
+  url?: string;
+}
+
+/**
+ * AttachmentList displays a read-only list of file attachments
+ * with type icons, formatted sizes, and optional download/remove actions.
+ *
+ * @example
+ * <AttachmentList
+ *   files={[
+ *     { name: "syllabus.pdf", size: 245000, type: "application/pdf", url: "/files/syllabus.pdf" },
+ *   ]}
+ *   onDownload={(file) => window.open(file.url)}
+ * />
+ */
+export interface AttachmentListProps {
+  /** List of file attachments to display */
+  files: AttachmentFile[];
+  /** Called when the user clicks a file's download action */
+  onDownload?: (file: AttachmentFile) => void;
+  /** Called when the user clicks a file's remove button (only shown when not readOnly) */
+  onRemove?: (file: AttachmentFile) => void;
+  /** When true, hides the remove button. @default true */
+  readOnly?: boolean;
+  /** CSS class name for the root element */
+  className?: string;
+  /** Inline styles for the root element */
+  style?: React.CSSProperties;
+}