@hydralms/components 0.1.0 → 0.1.2

package/src/ui/tooltip.tsx

@@ -0,0 +1,177 @@
+import * as React from "react";
+import {
+  createContext,
+  useContext,
+  useState,
+  useRef,
+  useCallback,
+  useLayoutEffect,
+  useId,
+  cloneElement,
+  isValidElement,
+} from "react";
+import { createPortal } from "react-dom";
+
+import { cn } from "../lib/utils";
+
+/* --------------------------------- Context -------------------------------- */
+
+interface TooltipContextValue {
+  open: boolean;
+  show: () => void;
+  hide: () => void;
+  triggerRef: React.RefObject<HTMLElement | null>;
+  tooltipId: string;
+}
+
+const TooltipContext = createContext<TooltipContextValue | null>(null);
+
+function useTooltipContext() {
+  const ctx = useContext(TooltipContext);
+  if (!ctx) throw new Error("Tooltip compound components must be used within <Tooltip>");
+  return ctx;
+}
+
+/* --------------------------------- Tooltip -------------------------------- */
+
+interface TooltipProps {
+  children: React.ReactNode;
+  delayDuration?: number;
+}
+
+function Tooltip({ children, delayDuration = 300 }: TooltipProps) {
+  const [open, setOpen] = useState(false);
+  const triggerRef = useRef<HTMLElement | null>(null);
+  const delayRef = useRef<ReturnType<typeof setTimeout>>(undefined);
+  const tooltipId = useId();
+
+  const show = useCallback(() => {
+    clearTimeout(delayRef.current);
+    delayRef.current = setTimeout(() => setOpen(true), delayDuration);
+  }, [delayDuration]);
+
+  const hide = useCallback(() => {
+    clearTimeout(delayRef.current);
+    setOpen(false);
+  }, []);
+
+  return (
+    <TooltipContext.Provider value={{ open, show, hide, triggerRef, tooltipId }}>
+      {children}
+    </TooltipContext.Provider>
+  );
+}
+
+/* ------------------------------ TooltipTrigger ----------------------------- */
+
+interface TooltipTriggerProps {
+  children: React.ReactElement<Record<string, unknown>>;
+}
+
+function TooltipTrigger({ children }: TooltipTriggerProps) {
+  const { show, hide, triggerRef, tooltipId, open } = useTooltipContext();
+
+  if (!isValidElement(children)) return children;
+
+  return cloneElement(children, {
+    ref: (node: HTMLElement | null) => {
+      triggerRef.current = node;
+      // Forward ref if child has one
+      const childRef = (children as React.ReactElement & { ref?: React.Ref<HTMLElement> }).ref;
+      if (typeof childRef === "function") childRef(node);
+      else if (childRef && typeof childRef === "object") {
+        (childRef as React.MutableRefObject<HTMLElement | null>).current = node;
+      }
+    },
+    onMouseEnter: (e: React.MouseEvent) => {
+      show();
+      const handler = (children.props as Record<string, Function | undefined>).onMouseEnter;
+      handler?.(e);
+    },
+    onMouseLeave: (e: React.MouseEvent) => {
+      hide();
+      const handler = (children.props as Record<string, Function | undefined>).onMouseLeave;
+      handler?.(e);
+    },
+    onFocus: (e: React.FocusEvent) => {
+      show();
+      const handler = (children.props as Record<string, Function | undefined>).onFocus;
+      handler?.(e);
+    },
+    onBlur: (e: React.FocusEvent) => {
+      hide();
+      const handler = (children.props as Record<string, Function | undefined>).onBlur;
+      handler?.(e);
+    },
+    "aria-describedby": open ? tooltipId : undefined,
+  } as Record<string, unknown>);
+}
+
+/* ------------------------------ TooltipContent ----------------------------- */
+
+interface TooltipContentProps extends React.ComponentProps<"div"> {
+  sideOffset?: number;
+}
+
+function TooltipContent({
+  className,
+  sideOffset = 8,
+  children,
+  style,
+  ...props
+}: TooltipContentProps) {
+  const { open, triggerRef, tooltipId } = useTooltipContext();
+  const popupRef = useRef<HTMLDivElement>(null);
+  const [position, setPosition] = useState<React.CSSProperties>({
+    position: "fixed",
+    top: 0,
+    left: 0,
+    visibility: "hidden",
+  });
+
+  useLayoutEffect(() => {
+    if (!open || !triggerRef.current || !popupRef.current) return;
+
+    const trigger = triggerRef.current.getBoundingClientRect();
+    const popup = popupRef.current.getBoundingClientRect();
+
+    // Default: above trigger, centered horizontally
+    let top = trigger.top - popup.height - sideOffset;
+    let left = trigger.left + trigger.width / 2 - popup.width / 2;
+
+    // Flip below if overflows top
+    if (top < 4) {
+      top = trigger.bottom + sideOffset;
+    }
+
+    // Clamp horizontally
+    if (left < 4) left = 4;
+    if (left + popup.width > window.innerWidth - 4) {
+      left = window.innerWidth - popup.width - 4;
+    }
+
+    setPosition({ position: "fixed", top, left, visibility: "visible" });
+  }, [open, sideOffset, triggerRef]);
+
+  if (!open) return null;
+
+  return createPortal(
+    <div
+      ref={popupRef}
+      id={tooltipId}
+      role="tooltip"
+      data-slot="tooltip-content"
+      className={cn(
+        "bg-primary text-primary-foreground z-50 max-w-60 rounded-md px-2.5 py-1.5 text-xs leading-snug shadow-md animate-in fade-in-0 zoom-in-95",
+        className,
+      )}
+      style={{ ...position, ...style }}
+      {...props}
+    >
+      {children}
+    </div>,
+    document.body,
+  );
+}
+
+export { Tooltip, TooltipTrigger, TooltipContent };

package/src/utils/debounce.test.ts

@@ -0,0 +1,59 @@
+import { debounce } from "./debounce";
+
+describe("debounce", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("delays function execution", () => {
+    const fn = vi.fn();
+    const debounced = debounce(fn, 100);
+
+    debounced();
+    expect(fn).not.toHaveBeenCalled();
+
+    vi.advanceTimersByTime(100);
+    expect(fn).toHaveBeenCalledOnce();
+  });
+
+  it("resets the timer on subsequent calls", () => {
+    const fn = vi.fn();
+    const debounced = debounce(fn, 100);
+
+    debounced();
+    vi.advanceTimersByTime(50);
+    debounced();
+    vi.advanceTimersByTime(50);
+
+    expect(fn).not.toHaveBeenCalled();
+
+    vi.advanceTimersByTime(50);
+    expect(fn).toHaveBeenCalledOnce();
+  });
+
+  it("passes arguments to the debounced function", () => {
+    const fn = vi.fn();
+    const debounced = debounce(fn, 100);
+
+    debounced("hello", "world");
+    vi.advanceTimersByTime(100);
+
+    expect(fn).toHaveBeenCalledWith("hello", "world");
+  });
+
+  it("uses arguments from the last call", () => {
+    const fn = vi.fn();
+    const debounced = debounce(fn, 100);
+
+    debounced("first");
+    debounced("second");
+    vi.advanceTimersByTime(100);
+
+    expect(fn).toHaveBeenCalledOnce();
+    expect(fn).toHaveBeenCalledWith("second");
+  });
+});

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