@hydralms/components 0.1.1 → 0.1.3

package/src/utils/debounce.ts

@@ -0,0 +1,10 @@
+export function debounce<T extends (...args: Parameters<T>) => void>(
+  fn: T,
+  delay: number,
+): (...args: Parameters<T>) => void {
+  let timer: ReturnType<typeof setTimeout>;
+  return (...args: Parameters<T>) => {
+    clearTimeout(timer);
+    timer = setTimeout(() => fn(...args), delay);
+  };
+}

package/src/utils/format-duration.test.ts

@@ -0,0 +1,55 @@
+import { formatDuration, formatTimer } from "./format-duration";
+
+describe("formatDuration", () => {
+  it("returns dash for values less than 1", () => {
+    expect(formatDuration(0)).toBe("-");
+    expect(formatDuration(-5)).toBe("-");
+    expect(formatDuration(0.5)).toBe("-");
+  });
+
+  it("formats seconds only", () => {
+    expect(formatDuration(45)).toBe("45s");
+  });
+
+  it("formats minutes and seconds", () => {
+    expect(formatDuration(125)).toBe("2m 5s");
+  });
+
+  it("formats hours, minutes, and seconds", () => {
+    expect(formatDuration(3661)).toBe("1h 1m 1s");
+  });
+
+  it("formats exact hours", () => {
+    expect(formatDuration(7200)).toBe("2h");
+  });
+
+  it("formats hours and minutes without seconds", () => {
+    expect(formatDuration(3660)).toBe("1h 1m");
+  });
+
+  it("formats hours and seconds without minutes", () => {
+    expect(formatDuration(3601)).toBe("1h 1s");
+  });
+});
+
+describe("formatTimer", () => {
+  it("formats zero as 00:00", () => {
+    expect(formatTimer(0)).toBe("00:00");
+  });
+
+  it("formats seconds with padding", () => {
+    expect(formatTimer(5)).toBe("00:05");
+  });
+
+  it("formats minutes and seconds", () => {
+    expect(formatTimer(125)).toBe("02:05");
+  });
+
+  it("includes hours when applicable", () => {
+    expect(formatTimer(3661)).toBe("01:01:01");
+  });
+
+  it("pads all segments", () => {
+    expect(formatTimer(3600)).toBe("01:00:00");
+  });
+});

package/src/utils/format-duration.ts

@@ -0,0 +1,30 @@
+export const formatDuration = (duration: number): string => {
+  if (duration < 1) {
+    return "-";
+  }
+
+  const hours = Math.floor(duration / 3600);
+  const minutes = Math.floor((duration % 3600) / 60);
+  const seconds = duration % 60;
+  const parts: string[] = [];
+
+  if (hours > 0) parts.push(`${hours}h`);
+  if (minutes > 0) parts.push(`${minutes}m`);
+  if (seconds > 0) parts.push(`${seconds}s`);
+
+  return parts.join(" ");
+};
+
+export const formatTimer = (totalSeconds: number): string => {
+  const hours = Math.floor(totalSeconds / 3600);
+  const minutes = Math.floor((totalSeconds % 3600) / 60);
+  const seconds = totalSeconds % 60;
+
+  const pad = (n: number) => n.toString().padStart(2, "0");
+
+  if (hours > 0) {
+    return `${pad(hours)}:${pad(minutes)}:${pad(seconds)}`;
+  }
+
+  return `${pad(minutes)}:${pad(seconds)}`;
+};

package/src/video/index.ts

@@ -0,0 +1,17 @@
+export { VideoPlayer } from "./video-player";
+export { VideoTranscript } from "./video-transcript";
+export { VideoChapterList } from "./video-chapter-list";
+export { VideoThumbnailCard } from "./video-thumbnail-card";
+export { VideoBookmark } from "./video-bookmark";
+export { VideoPlaylistItem } from "./video-playlist-item";
+export type {
+  VideoPlayerProps,
+  VideoTranscriptProps,
+  VideoChapterListProps,
+  VideoThumbnailCardProps,
+  VideoBookmarkProps,
+  VideoPlaylistItemProps,
+  TranscriptEntry,
+  VideoChapter,
+  VideoBookmarkData,
+} from "./types";

package/src/video/types.ts

@@ -0,0 +1,216 @@
+/**
+ * VideoPlayer component for rendering video content with interactive playback controls.
+ *
+ * @example
+ * <VideoPlayer
+ *   src="https://example.com/lesson.mp4"
+ *   poster="https://example.com/thumbnail.jpg"
+ *   title="Introduction to React"
+ *   onEnded={() => markLessonComplete()}
+ * />
+ */
+export interface VideoPlayerProps {
+  /** URL of the video source */
+  src?: string;
+  /** URL of the poster/thumbnail image */
+  poster?: string;
+  /** Title displayed above the video */
+  title?: string;
+  /** Whether the video should autoplay */
+  autoPlay?: boolean;
+  /** Called when the video starts playing */
+  onPlay?: () => void;
+  /** Called when the video is paused */
+  onPause?: () => void;
+  /** Called when the video ends */
+  onEnded?: () => void;
+  /** Called on each time update tick with currentTime and duration */
+  onTimeUpdate?: (currentTime: number, duration: number) => void;
+  /** When true, shows a poster image instead of interactive controls */
+  readOnly?: boolean;
+  /** Aspect ratio of the video container */
+  aspectRatio?: "16/9" | "4/3" | "1/1";
+  /** CSS class name for the root element */
+  className?: string;
+  /** Inline styles for the root element */
+  style?: React.CSSProperties;
+}
+
+// ─── Data Types ───
+
+export interface TranscriptEntry {
+  /** Timestamp in seconds */
+  time: number;
+  /** Optional speaker name */
+  speaker?: string;
+  /** Transcript text content */
+  text: string;
+}
+
+export interface VideoChapter {
+  /** Chapter start time in seconds */
+  time: number;
+  /** Chapter title */
+  title: string;
+  /** Optional chapter thumbnail URL */
+  thumbnail?: string;
+  /** Chapter duration in seconds */
+  duration?: number;
+}
+
+export interface VideoBookmarkData {
+  /** Unique bookmark identifier */
+  id: string;
+  /** Bookmark timestamp in seconds */
+  time: number;
+  /** Optional note attached to the bookmark */
+  note?: string;
+  /** ISO 8601 creation timestamp */
+  createdAt?: string;
+}
+
+// ─── Component Props ───
+
+/**
+ * VideoTranscript renders a scrollable timestamped transcript with active-line
+ * highlighting based on the current playback time.
+ *
+ * @example
+ * <VideoTranscript
+ *   entries={transcript}
+ *   currentTime={42}
+ *   onSeek={(time) => player.seekTo(time)}
+ * />
+ */
+export interface VideoTranscriptProps {
+  /** Array of transcript entries with timestamps */
+  entries: TranscriptEntry[];
+  /** Current playback time in seconds — used to highlight the active entry */
+  currentTime?: number;
+  /** Called when the user clicks a transcript entry to seek */
+  onSeek?: (time: number) => void;
+  /** When true, disables click-to-seek interaction */
+  readOnly?: boolean;
+  /** Maximum height of the scrollable container (CSS value) */
+  maxHeight?: string;
+  /** CSS class name for the root element */
+  className?: string;
+  /** Inline styles for the root element */
+  style?: React.CSSProperties;
+}
+
+/**
+ * VideoChapterList renders an ordered list of video chapters with timestamps,
+ * active chapter highlighting, and optional thumbnails.
+ *
+ * @example
+ * <VideoChapterList
+ *   chapters={chapters}
+ *   currentTime={120}
+ *   onSeek={(time) => player.seekTo(time)}
+ * />
+ */
+export interface VideoChapterListProps {
+  /** Array of chapter markers */
+  chapters: VideoChapter[];
+  /** Current playback time in seconds — used to determine the active chapter */
+  currentTime?: number;
+  /** Called when the user clicks a chapter to seek */
+  onSeek?: (time: number) => void;
+  /** CSS class name for the root element */
+  className?: string;
+  /** Inline styles for the root element */
+  style?: React.CSSProperties;
+}
+
+/**
+ * VideoThumbnailCard renders a clickable card-style video preview with a poster
+ * image, play icon overlay, duration badge, title, and optional progress bar.
+ *
+ * @example
+ * <VideoThumbnailCard
+ *   poster="https://example.com/thumb.jpg"
+ *   title="Introduction to React"
+ *   duration={420}
+ *   progress={65}
+ *   onClick={() => navigate('/lesson/1')}
+ * />
+ */
+export interface VideoThumbnailCardProps {
+  /** URL of the poster/thumbnail image */
+  poster?: string;
+  /** Video title displayed below the poster */
+  title: string;
+  /** Video duration in seconds */
+  duration?: number;
+  /** Watch progress percentage (0–100) */
+  progress?: number;
+  /** Called when the card is clicked */
+  onClick?: () => void;
+  /** CSS class name for the root element */
+  className?: string;
+  /** Inline styles for the root element */
+  style?: React.CSSProperties;
+}
+
+/**
+ * VideoBookmark renders a single timestamped bookmark row with an optional note,
+ * clickable timestamp for seeking, and edit/delete action buttons.
+ *
+ * @example
+ * <VideoBookmark
+ *   bookmark={{ id: "b1", time: 125, note: "Key concept explained here" }}
+ *   onSeek={(time) => player.seekTo(time)}
+ *   onDelete={(id) => removeBookmark(id)}
+ * />
+ */
+export interface VideoBookmarkProps {
+  /** Bookmark data object */
+  bookmark: VideoBookmarkData;
+  /** Called when the user clicks the timestamp to seek */
+  onSeek?: (time: number) => void;
+  /** Called when the user clicks the delete button */
+  onDelete?: (id: string) => void;
+  /** Called when the user clicks the edit button */
+  onEdit?: (id: string) => void;
+  /** CSS class name for the root element */
+  className?: string;
+  /** Inline styles for the root element */
+  style?: React.CSSProperties;
+}
+
+/**
+ * VideoPlaylistItem renders a horizontal row for a sequential video playlist,
+ * showing a thumbnail, title, duration, completion status, and active state.
+ *
+ * @example
+ * <VideoPlaylistItem
+ *   thumbnail="https://example.com/thumb.jpg"
+ *   title="Lesson 1: Getting Started"
+ *   duration={420}
+ *   status="completed"
+ *   isActive={false}
+ *   index={1}
+ *   onClick={() => navigate('/lesson/1')}
+ * />
+ */
+export interface VideoPlaylistItemProps {
+  /** URL of the video thumbnail */
+  thumbnail?: string;
+  /** Video title */
+  title: string;
+  /** Video duration in seconds */
+  duration?: number;
+  /** Watch status of this video */
+  status?: "unwatched" | "in-progress" | "completed";
+  /** Whether this is the currently playing item */
+  isActive?: boolean;
+  /** 1-based display index in the playlist */
+  index?: number;
+  /** Called when the item is clicked */
+  onClick?: () => void;
+  /** CSS class name for the root element */
+  className?: string;
+  /** Inline styles for the root element */
+  style?: React.CSSProperties;
+}

package/src/video/video-bookmark.tsx

@@ -0,0 +1,76 @@
+import { Bookmark, Pencil, Trash2 } from "lucide-react";
+import type { VideoBookmarkProps } from "./types";
+import { cn } from "../lib/utils";
+import { formatTimer } from "../utils/format-duration";
+
+export const VideoBookmark = ({
+  bookmark,
+  onSeek,
+  onDelete,
+  onEdit,
+  className,
+  style,
+}: VideoBookmarkProps) => {
+  return (
+    <div
+      className={cn(
+        "flex items-start gap-3 rounded-md border border-border p-3",
+        className,
+      )}
+      style={style}
+    >
+      <div className="flex shrink-0 items-center justify-center size-8 rounded-full bg-primary/10 text-primary">
+        <Bookmark size={16} />
+      </div>
+
+      <div className="min-w-0 flex-1">
+        <button
+          type="button"
+          className={cn(
+            "font-mono text-xs font-medium tabular-nums",
+            onSeek
+              ? "cursor-pointer text-primary hover:underline"
+              : "text-muted-foreground",
+          )}
+          onClick={() => onSeek?.(bookmark.time)}
+          disabled={!onSeek}
+        >
+          {formatTimer(Math.floor(bookmark.time))}
+        </button>
+        {bookmark.note && (
+          <p className="mt-0.5 text-sm text-foreground">{bookmark.note}</p>
+        )}
+        {bookmark.createdAt && (
+          <span className="text-xs text-muted-foreground">
+            {new Date(bookmark.createdAt).toLocaleDateString()}
+          </span>
+        )}
+      </div>
+
+      {(onEdit || onDelete) && (
+        <div className="flex shrink-0 items-center gap-1">
+          {onEdit && (
+            <button
+              type="button"
+              className="inline-flex items-center justify-center rounded-md p-1.5 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
+              aria-label="Edit bookmark"
+              onClick={() => onEdit(bookmark.id)}
+            >
+              <Pencil size={14} />
+            </button>
+          )}
+          {onDelete && (
+            <button
+              type="button"
+              className="inline-flex items-center justify-center rounded-md p-1.5 text-muted-foreground transition-colors hover:bg-destructive/10 hover:text-destructive"
+              aria-label="Delete bookmark"
+              onClick={() => onDelete(bookmark.id)}
+            >
+              <Trash2 size={14} />
+            </button>
+          )}
+        </div>
+      )}
+    </div>
+  );
+};

package/src/video/video-chapter-list.tsx

@@ -0,0 +1,93 @@
+import { Play } from "lucide-react";
+import type { VideoChapterListProps } from "./types";
+import { cn } from "../lib/utils";
+import { formatTimer, formatDuration } from "../utils/format-duration";
+
+export const VideoChapterList = ({
+  chapters,
+  currentTime = 0,
+  onSeek,
+  className,
+  style,
+}: VideoChapterListProps) => {
+  // Active chapter: last chapter whose time <= currentTime
+  const activeIndex = chapters.reduce<number>(
+    (acc, ch, i) => (ch.time <= currentTime ? i : acc),
+    -1,
+  );
+
+  return (
+    <div
+      className={cn(
+        "divide-y divide-border rounded-md border border-border",
+        className,
+      )}
+      style={style}
+    >
+      {chapters.map((chapter, i) => {
+        const isActive = i === activeIndex;
+        return (
+          <div
+            key={i}
+            className={cn(
+              "flex items-center gap-3 p-3 transition-colors",
+              isActive && "bg-primary/10",
+              onSeek && "cursor-pointer hover:bg-muted",
+            )}
+            onClick={() => onSeek?.(chapter.time)}
+          >
+            {chapter.thumbnail ? (
+              <div
+                className="relative shrink-0 w-16 overflow-hidden rounded"
+                style={{ aspectRatio: "16/9" }}
+              >
+                <img
+                  src={chapter.thumbnail}
+                  alt={chapter.title}
+                  className="size-full object-cover"
+                />
+                {isActive && (
+                  <div className="absolute inset-0 flex items-center justify-center bg-black/40">
+                    <Play size={14} className="ml-px text-white" />
+                  </div>
+                )}
+              </div>
+            ) : (
+              <div
+                className={cn(
+                  "flex shrink-0 items-center justify-center size-8 rounded-full",
+                  isActive
+                    ? "bg-primary text-primary-foreground"
+                    : "bg-muted text-muted-foreground",
+                )}
+              >
+                <span className="text-xs font-semibold">{i + 1}</span>
+              </div>
+            )}
+
+            <div className="min-w-0 flex-1">
+              <div
+                className={cn(
+                  "truncate text-sm font-medium",
+                  isActive ? "text-primary" : "text-foreground",
+                )}
+              >
+                {chapter.title}
+              </div>
+              <div className="mt-0.5 flex items-center gap-2">
+                <span className="font-mono text-xs tabular-nums text-muted-foreground">
+                  {formatTimer(Math.floor(chapter.time))}
+                </span>
+                {chapter.duration != null && chapter.duration > 0 && (
+                  <span className="text-xs text-muted-foreground">
+                    {formatDuration(chapter.duration)}
+                  </span>
+                )}
+              </div>
+            </div>
+          </div>
+        );
+      })}
+    </div>
+  );
+};

package/src/video/video-player.tsx

@@ -0,0 +1,103 @@
+import { useRef } from "react";
+import { Video, Play } from "lucide-react";
+import type { VideoPlayerProps } from "./types";
+import { cn } from "../lib/utils";
+
+export const VideoPlayer = ({
+  src,
+  poster,
+  title,
+  autoPlay = false,
+  onPlay,
+  onPause,
+  onEnded,
+  onTimeUpdate,
+  readOnly = false,
+  aspectRatio = "16/9",
+  className,
+  style,
+}: VideoPlayerProps) => {
+  const videoRef = useRef<HTMLVideoElement>(null);
+
+  const handleTimeUpdate = () => {
+    const video = videoRef.current;
+    if (video && onTimeUpdate) {
+      onTimeUpdate(video.currentTime, video.duration);
+    }
+  };
+
+  if (!src) {
+    return (
+      <div
+        className={cn("relative overflow-hidden rounded-lg border border-border bg-muted", className)}
+        style={{ aspectRatio, ...style }}
+      >
+        <div className="absolute inset-0 flex flex-col items-center justify-center gap-2">
+          <div className="flex items-center justify-center size-12 rounded-full bg-muted-foreground/10">
+            <Video size={24} />
+          </div>
+          <span className="text-sm text-muted-foreground">
+            No video source provided
+          </span>
+        </div>
+      </div>
+    );
+  }
+
+  if (readOnly) {
+    return (
+      <div
+        className={cn("relative overflow-hidden rounded-lg", className)}
+        style={{ aspectRatio, ...style }}
+      >
+        {poster ? (
+          <img
+            src={poster}
+            alt={title || "Video poster"}
+            style={{ width: "100%", height: "100%", objectFit: "cover" }}
+          />
+        ) : (
+          <div className="absolute inset-0 flex items-center justify-center bg-muted">
+            <div className="flex items-center justify-center size-14 rounded-full bg-black/60">
+              <Play size={28} className="text-white ml-0.5" />
+            </div>
+          </div>
+        )}
+
+        {poster && (
+          <div className="absolute inset-0 flex items-center justify-center bg-black/30 transition-opacity">
+            <div className="flex items-center justify-center size-14 rounded-full bg-black/60">
+              <Play size={28} className="text-white ml-0.5" />
+            </div>
+          </div>
+        )}
+
+        {title && (
+          <div className="absolute bottom-0 left-0 right-0 bg-linear-to-t from-black/60 to-transparent p-2">
+            <span className="text-sm text-white font-medium">{title}</span>
+          </div>
+        )}
+      </div>
+    );
+  }
+
+  return (
+    <div className={className} style={style}>
+      {title && <p className="mb-2 text-sm font-medium">{title}</p>}
+      <div className="rounded-lg overflow-hidden">
+        <video
+          ref={videoRef}
+          src={src}
+          poster={poster}
+          controls
+          autoPlay={autoPlay}
+          onPlay={onPlay}
+          onPause={onPause}
+          onEnded={onEnded}
+          onTimeUpdate={handleTimeUpdate}
+          style={{ width: "100%", aspectRatio, display: "block" }}
+        />
+      </div>
+    </div>
+  );
+};

package/src/video/video-playlist-item.tsx

@@ -0,0 +1,90 @@
+import { Play, CheckCircle2, Circle } from "lucide-react";
+import type { VideoPlaylistItemProps } from "./types";
+import { cn } from "../lib/utils";
+import { formatDuration } from "../utils/format-duration";
+
+export const VideoPlaylistItem = ({
+  thumbnail,
+  title,
+  duration,
+  status = "unwatched",
+  isActive = false,
+  index,
+  onClick,
+  className,
+  style,
+}: VideoPlaylistItemProps) => {
+  return (
+    <div
+      className={cn(
+        "flex items-center gap-3 rounded-md px-3 py-2 transition-colors",
+        isActive && "bg-primary/10",
+        onClick && "cursor-pointer hover:bg-muted",
+        className,
+      )}
+      style={style}
+      onClick={onClick}
+    >
+      {/* Index / Status icon */}
+      <div className="flex shrink-0 items-center justify-center size-6">
+        {status === "completed" ? (
+          <span className="text-success">
+            <CheckCircle2 size={18} />
+          </span>
+        ) : isActive ? (
+          <span className="text-primary">
+            <Play size={16} className="ml-px" />
+          </span>
+        ) : index != null ? (
+          <span className="text-xs font-medium tabular-nums text-muted-foreground">
+            {index}
+          </span>
+        ) : (
+          <span className="text-muted-foreground">
+            <Circle size={16} />
+          </span>
+        )}
+      </div>
+
+      {/* Thumbnail */}
+      {thumbnail && (
+        <div
+          className="relative shrink-0 w-16 overflow-hidden rounded"
+          style={{ aspectRatio: "16/9" }}
+        >
+          <img
+            src={thumbnail}
+            alt={title}
+            className={cn(
+              "size-full object-cover",
+              status === "completed" && "opacity-60",
+            )}
+          />
+          {isActive && (
+            <div className="absolute inset-0 flex items-center justify-center bg-black/40">
+              <Play size={12} className="ml-px text-white" />
+            </div>
+          )}
+        </div>
+      )}
+
+      {/* Title + duration */}
+      <div className="min-w-0 flex-1">
+        <div
+          className={cn(
+            "truncate text-sm",
+            isActive ? "font-medium text-primary" : "text-foreground",
+            status === "completed" && !isActive && "text-muted-foreground",
+          )}
+        >
+          {title}
+        </div>
+        {duration != null && duration > 0 && (
+          <span className="text-xs text-muted-foreground">
+            {formatDuration(duration)}
+          </span>
+        )}
+      </div>
+    </div>
+  );
+};