@hydralms/components 0.1.2 → 0.2.0

package/src/ui/rich-text-editor.tsx

@@ -0,0 +1,109 @@
+import { useEffect } from "react";
+import { useEditor, EditorContent } from "@tiptap/react";
+import StarterKit from "@tiptap/starter-kit";
+import Placeholder from "@tiptap/extension-placeholder";
+import UnderlineExtension from "@tiptap/extension-underline";
+import LinkExtension from "@tiptap/extension-link";
+import { cn } from "../lib/utils";
+import { RichTextToolbar } from "./rich-text-toolbar";
+
+export type RichTextEditorVariant = "default" | "minimal";
+
+export interface RichTextEditorProps {
+  /** HTML string value */
+  value?: string;
+  /** Called with the HTML string on every content change */
+  onChange?: (html: string) => void;
+  /** Placeholder text shown when the editor is empty */
+  placeholder?: string;
+  /** Makes the editor non-editable (shows content without toolbar) */
+  readOnly?: boolean;
+  /** Visually disables the editor */
+  disabled?: boolean;
+  /** `"default"` shows full toolbar; `"minimal"` shows only basic formatting */
+  variant?: RichTextEditorVariant;
+  className?: string;
+  style?: React.CSSProperties;
+}
+
+/**
+ * RichTextEditor wraps Tiptap to provide a rich text editing experience
+ * styled to match the HydraLMS design system.
+ *
+ * @example
+ * <RichTextEditor
+ *   value={html}
+ *   onChange={setHtml}
+ *   placeholder="Write your response..."
+ *   variant="default"
+ * />
+ */
+export function RichTextEditor({
+  value = "",
+  onChange,
+  placeholder,
+  readOnly = false,
+  disabled = false,
+  variant = "default",
+  className,
+  style,
+}: RichTextEditorProps) {
+  const editor = useEditor({
+    extensions: [
+      StarterKit,
+      UnderlineExtension,
+      LinkExtension.configure({
+        openOnClick: false,
+        HTMLAttributes: { class: "text-primary underline" },
+      }),
+      Placeholder.configure({ placeholder }),
+    ],
+    content: value,
+    editable: !readOnly && !disabled,
+    onUpdate: ({ editor: e }) => {
+      onChange?.(e.getHTML());
+    },
+  });
+
+  // Sync external value changes into the editor
+  useEffect(() => {
+    if (!editor) return;
+    if (editor.getHTML() !== value) {
+      editor.commands.setContent(value, { emitUpdate: false });
+    }
+  }, [editor, value]);
+
+  // Sync editable state
+  useEffect(() => {
+    if (!editor) return;
+    editor.setEditable(!readOnly && !disabled);
+  }, [editor, readOnly, disabled]);
+
+  if (!editor) return null;
+
+  return (
+    <div
+      className={cn(
+        "rounded-md border border-input bg-transparent text-sm shadow-xs transition-[color,box-shadow]",
+        "focus-within:border-ring focus-within:ring-ring/50 focus-within:ring-[3px]",
+        disabled && "pointer-events-none opacity-50",
+        className,
+      )}
+      style={style}
+    >
+      {!readOnly && !disabled && (
+        <RichTextToolbar editor={editor} variant={variant} />
+      )}
+      <EditorContent
+        editor={editor}
+        className={cn(
+          "px-3 py-2 [&_.tiptap]:min-h-16 [&_.tiptap]:outline-none",
+          "[&_.tiptap_p]:mb-1 [&_.tiptap_h2]:text-lg [&_.tiptap_h2]:font-semibold [&_.tiptap_h2]:mb-1",
+          "[&_.tiptap_ul]:list-disc [&_.tiptap_ul]:pl-5 [&_.tiptap_ol]:list-decimal [&_.tiptap_ol]:pl-5",
+          "[&_.tiptap_blockquote]:border-l-2 [&_.tiptap_blockquote]:border-muted-foreground/30 [&_.tiptap_blockquote]:pl-3 [&_.tiptap_blockquote]:italic",
+          "[&_.tiptap_pre]:rounded-md [&_.tiptap_pre]:bg-muted [&_.tiptap_pre]:p-3 [&_.tiptap_pre]:font-mono [&_.tiptap_pre]:text-sm",
+        )}
+      />
+    </div>
+  );
+}

package/src/ui/rich-text-toolbar.tsx

@@ -0,0 +1,156 @@
+import type { Editor } from "@tiptap/react";
+import {
+  Bold,
+  Italic,
+  Underline,
+  Heading2,
+  List,
+  ListOrdered,
+  Quote,
+  Link,
+  Code,
+} from "lucide-react";
+import { cn } from "../lib/utils";
+import { Separator } from "./separator";
+
+type RichTextToolbarVariant = "default" | "minimal";
+
+interface RichTextToolbarProps {
+  editor: Editor;
+  variant?: RichTextToolbarVariant;
+}
+
+function ToolbarButton({
+  active,
+  disabled,
+  onClick,
+  title,
+  children,
+}: {
+  active?: boolean;
+  disabled?: boolean;
+  onClick: () => void;
+  title: string;
+  children: React.ReactNode;
+}) {
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      disabled={disabled}
+      title={title}
+      className={cn(
+        "inline-flex items-center justify-center rounded-sm p-1.5 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground disabled:pointer-events-none disabled:opacity-50",
+        active && "bg-muted text-foreground",
+      )}
+    >
+      {children}
+    </button>
+  );
+}
+
+export function RichTextToolbar({
+  editor,
+  variant = "default",
+}: RichTextToolbarProps) {
+  const iconSize = 16;
+
+  function handleLink() {
+    const previousUrl = editor.getAttributes("link").href as string;
+    const url = window.prompt("Enter URL", previousUrl || "https://");
+    if (url === null) return;
+    if (url === "") {
+      editor.chain().focus().extendMarkRange("link").unsetLink().run();
+    } else {
+      editor
+        .chain()
+        .focus()
+        .extendMarkRange("link")
+        .setLink({ href: url })
+        .run();
+    }
+  }
+
+  return (
+    <div className="flex items-center gap-0.5 border-b border-border px-2 py-1.5">
+      <ToolbarButton
+        active={editor.isActive("bold")}
+        onClick={() => editor.chain().focus().toggleBold().run()}
+        title="Bold"
+      >
+        <Bold size={iconSize} />
+      </ToolbarButton>
+      <ToolbarButton
+        active={editor.isActive("italic")}
+        onClick={() => editor.chain().focus().toggleItalic().run()}
+        title="Italic"
+      >
+        <Italic size={iconSize} />
+      </ToolbarButton>
+      <ToolbarButton
+        active={editor.isActive("underline")}
+        onClick={() => editor.chain().focus().toggleUnderline().run()}
+        title="Underline"
+      >
+        <Underline size={iconSize} />
+      </ToolbarButton>
+
+      <Separator orientation="vertical" className="mx-1 h-5" />
+
+      <ToolbarButton
+        active={editor.isActive("bulletList")}
+        onClick={() => editor.chain().focus().toggleBulletList().run()}
+        title="Bullet list"
+      >
+        <List size={iconSize} />
+      </ToolbarButton>
+      <ToolbarButton
+        active={editor.isActive("orderedList")}
+        onClick={() => editor.chain().focus().toggleOrderedList().run()}
+        title="Ordered list"
+      >
+        <ListOrdered size={iconSize} />
+      </ToolbarButton>
+
+      <Separator orientation="vertical" className="mx-1 h-5" />
+
+      <ToolbarButton
+        active={editor.isActive("link")}
+        onClick={handleLink}
+        title="Link"
+      >
+        <Link size={iconSize} />
+      </ToolbarButton>
+
+      {variant === "default" && (
+        <>
+          <Separator orientation="vertical" className="mx-1 h-5" />
+
+          <ToolbarButton
+            active={editor.isActive("heading", { level: 2 })}
+            onClick={() =>
+              editor.chain().focus().toggleHeading({ level: 2 }).run()
+            }
+            title="Heading"
+          >
+            <Heading2 size={iconSize} />
+          </ToolbarButton>
+          <ToolbarButton
+            active={editor.isActive("blockquote")}
+            onClick={() => editor.chain().focus().toggleBlockquote().run()}
+            title="Blockquote"
+          >
+            <Quote size={iconSize} />
+          </ToolbarButton>
+          <ToolbarButton
+            active={editor.isActive("codeBlock")}
+            onClick={() => editor.chain().focus().toggleCodeBlock().run()}
+            title="Code block"
+          >
+            <Code size={iconSize} />
+          </ToolbarButton>
+        </>
+      )}
+    </div>
+  );
+}

package/src/utils/array-utils.ts

@@ -0,0 +1,17 @@
+/**
+ * Group an array of items by a key derived from each item.
+ */
+export function groupBy<T>(
+  arr: T[],
+  keyFn: (item: T) => string,
+): Record<string, T[]> {
+  const result: Record<string, T[]> = {};
+  for (const item of arr) {
+    const key = keyFn(item);
+    if (!result[key]) {
+      result[key] = [];
+    }
+    result[key].push(item);
+  }
+  return result;
+}

package/src/utils/flatten-leaves.ts

@@ -0,0 +1,17 @@
+import type { CurriculumItem } from "../curriculum/types";
+
+/**
+ * Recursively collects the UIDs of all leaf nodes (items with no children)
+ * in a curriculum tree.
+ */
+export function flattenLeaves(items: CurriculumItem[]): string[] {
+  const leaves: string[] = [];
+  for (const item of items) {
+    if (!item.children || item.children.length === 0) {
+      leaves.push(item.uid);
+    } else {
+      leaves.push(...flattenLeaves(item.children));
+    }
+  }
+  return leaves;
+}

package/src/utils/format-file-size.ts

@@ -0,0 +1,5 @@
+export 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`;
+}

package/src/utils/format-timestamp.ts

@@ -0,0 +1,13 @@
+export function formatTimestamp(iso: string): string {
+  const date = new Date(iso);
+  const now = new Date();
+  const diffMs = now.getTime() - date.getTime();
+  const diffMins = Math.floor(diffMs / 60000);
+  if (diffMins < 1) return "Just now";
+  if (diffMins < 60) return `${diffMins}m ago`;
+  const diffHours = Math.floor(diffMins / 60);
+  if (diffHours < 24) return `${diffHours}h ago`;
+  const diffDays = Math.floor(diffHours / 24);
+  if (diffDays < 7) return `${diffDays}d ago`;
+  return date.toLocaleDateString();
+}

package/src/utils/is-empty-html.ts

@@ -0,0 +1,7 @@
+/**
+ * Returns true if an HTML string contains no meaningful text content.
+ * Tiptap returns `"<p></p>"` for an empty editor, not an empty string.
+ */
+export function isEmptyHtml(html: string): boolean {
+  return html.replace(/<[^>]*>/g, "").trim().length === 0;
+}

package/src/utils/shuffle.ts

@@ -0,0 +1,8 @@
+export function shuffle<T>(array: T[]): T[] {
+  const shuffled = [...array];
+  for (let i = shuffled.length - 1; i > 0; i--) {
+    const j = Math.floor(Math.random() * (i + 1));
+    [shuffled[i], shuffled[j]] = [shuffled[j], shuffled[i]];
+  }
+  return shuffled;
+}

package/src/utils/string-utils.ts

@@ -0,0 +1,30 @@
+/**
+ * Truncate text to a maximum length, appending a suffix if truncated.
+ */
+export function truncateText(
+  text: string,
+  maxLength: number,
+  suffix = "...",
+): string {
+  if (text.length <= maxLength) return text;
+  return text.slice(0, maxLength - suffix.length) + suffix;
+}
+
+/**
+ * Format a decimal value as a percentage string.
+ */
+export function formatPercentage(value: number, decimals = 0): string {
+  return `${value.toFixed(decimals)}%`;
+}
+
+/**
+ * Return the singular or plural form of a word based on count.
+ */
+export function pluralize(
+  count: number,
+  singular: string,
+  plural?: string,
+): string {
+  if (count === 1) return singular;
+  return plural ?? `${singular}s`;
+}

package/src/video/video-bookmark.tsx

@@ -1,16 +1,17 @@
+import { memo } from "react";
 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 = ({
+export const VideoBookmark = memo(function VideoBookmark({
   bookmark,
   onSeek,
   onDelete,
   onEdit,
   className,
   style,
-}: VideoBookmarkProps) => {
+}: VideoBookmarkProps) {
   return (
     <div
       className={cn(
@@ -73,4 +74,4 @@ export const VideoBookmark = ({
       )}
     </div>
   );
-};
+});

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

@@ -1,3 +1,4 @@
+import { useMemo } from "react";
 import { Play } from "lucide-react";
 import type { VideoChapterListProps } from "./types";
 import { cn } from "../lib/utils";
@@ -11,9 +12,9 @@ export const VideoChapterList = ({
   style,
 }: VideoChapterListProps) => {
   // Active chapter: last chapter whose time <= currentTime
-  const activeIndex = chapters.reduce<number>(
-    (acc, ch, i) => (ch.time <= currentTime ? i : acc),
-    -1,
+  const activeIndex = useMemo(
+    () => chapters.reduce<number>((acc, ch, i) => (ch.time <= currentTime ? i : acc), -1),
+    [chapters, currentTime],
   );
 
   return (
@@ -28,13 +29,16 @@ export const VideoChapterList = ({
         const isActive = i === activeIndex;
         return (
           <div
-            key={i}
+            key={chapter.time}
             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)}
+            role={onSeek ? "button" : undefined}
+            tabIndex={onSeek ? 0 : undefined}
+            onKeyDown={onSeek ? (e) => { if (e.key === "Enter" || e.key === " ") { e.preventDefault(); onSeek(chapter.time); } } : undefined}
           >
             {chapter.thumbnail ? (
               <div
@@ -44,6 +48,7 @@ export const VideoChapterList = ({
                 <img
                   src={chapter.thumbnail}
                   alt={chapter.title}
+                  loading="lazy"
                   className="size-full object-cover"
                 />
                 {isActive && (

package/src/video/video-player.tsx

@@ -1,4 +1,4 @@
-import { useRef } from "react";
+import { useRef, useCallback } from "react";
 import { Video, Play } from "lucide-react";
 import type { VideoPlayerProps } from "./types";
 import { cn } from "../lib/utils";
@@ -18,13 +18,18 @@ export const VideoPlayer = ({
   style,
 }: VideoPlayerProps) => {
   const videoRef = useRef<HTMLVideoElement>(null);
+  const lastReportedTime = useRef(-1);
 
-  const handleTimeUpdate = () => {
+  const handleTimeUpdate = useCallback(() => {
     const video = videoRef.current;
     if (video && onTimeUpdate) {
-      onTimeUpdate(video.currentTime, video.duration);
+      const rounded = Math.floor(video.currentTime * 4) / 4; // 250ms granularity
+      if (rounded !== lastReportedTime.current) {
+        lastReportedTime.current = rounded;
+        onTimeUpdate(video.currentTime, video.duration);
+      }
     }
-  };
+  }, [onTimeUpdate]);
 
   if (!src) {
     return (
@@ -54,6 +59,7 @@ export const VideoPlayer = ({
           <img
             src={poster}
             alt={title || "Video poster"}
+            loading="lazy"
             style={{ width: "100%", height: "100%", objectFit: "cover" }}
           />
         ) : (
@@ -90,6 +96,7 @@ export const VideoPlayer = ({
           src={src}
           poster={poster}
           controls
+          preload="metadata"
           autoPlay={autoPlay}
           onPlay={onPlay}
           onPause={onPause}

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

@@ -1,9 +1,10 @@
+import { memo } from "react";
 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 = ({
+export const VideoPlaylistItem = memo(function VideoPlaylistItem({
   thumbnail,
   title,
   duration,
@@ -13,7 +14,7 @@ export const VideoPlaylistItem = ({
   onClick,
   className,
   style,
-}: VideoPlaylistItemProps) => {
+}: VideoPlaylistItemProps) {
   return (
     <div
       className={cn(
@@ -24,6 +25,9 @@ export const VideoPlaylistItem = ({
       )}
       style={style}
       onClick={onClick}
+      role={onClick ? "button" : undefined}
+      tabIndex={onClick ? 0 : undefined}
+      onKeyDown={onClick ? (e) => { if (e.key === "Enter" || e.key === " ") { e.preventDefault(); onClick(); } } : undefined}
     >
       {/* Index / Status icon */}
       <div className="flex shrink-0 items-center justify-center size-6">
@@ -55,6 +59,7 @@ export const VideoPlaylistItem = ({
           <img
             src={thumbnail}
             alt={title}
+            loading="lazy"
             className={cn(
               "size-full object-cover",
               status === "completed" && "opacity-60",
@@ -87,4 +92,4 @@ export const VideoPlaylistItem = ({
       </div>
     </div>
   );
-};
+});

package/src/video/video-thumbnail-card.tsx

@@ -22,6 +22,9 @@ export const VideoThumbnailCard = ({
       )}
       style={style}
       onClick={onClick}
+      role={onClick ? "button" : undefined}
+      tabIndex={onClick ? 0 : undefined}
+      onKeyDown={onClick ? (e) => { if (e.key === "Enter" || e.key === " ") { e.preventDefault(); onClick(); } } : undefined}
     >
       {/* Poster area */}
       <div className="relative overflow-hidden" style={{ aspectRatio: "16/9" }}>
@@ -29,6 +32,7 @@ export const VideoThumbnailCard = ({
           <img
             src={poster}
             alt={title}
+            loading="lazy"
             className="size-full object-cover transition-transform duration-300 group-hover:scale-105"
           />
         ) : (

package/src/video/video-transcript.tsx

@@ -1,4 +1,4 @@
-import { useRef, useEffect } from "react";
+import { useRef, useEffect, useMemo } from "react";
 import { Clock } from "lucide-react";
 import type { VideoTranscriptProps } from "./types";
 import { cn } from "../lib/utils";
@@ -17,9 +17,9 @@ export const VideoTranscript = ({
   const activeRef = useRef<HTMLDivElement>(null);
 
   // Last entry whose time <= currentTime
-  const activeIndex = entries.reduce<number>(
-    (acc, entry, i) => (entry.time <= currentTime ? i : acc),
-    -1,
+  const activeIndex = useMemo(
+    () => entries.reduce<number>((acc, entry, i) => (entry.time <= currentTime ? i : acc), -1),
+    [entries, currentTime],
   );
 
   useEffect(() => {
@@ -61,7 +61,7 @@ export const VideoTranscript = ({
         const isActive = i === activeIndex;
         return (
           <div
-            key={i}
+            key={`${entry.time}-${entry.text.slice(0, 20)}`}
             ref={isActive ? activeRef : undefined}
             className={cn(
               "flex gap-3 px-3 py-2 text-sm transition-colors",
@@ -69,6 +69,9 @@ export const VideoTranscript = ({
               !readOnly && onSeek && "cursor-pointer hover:bg-muted",
             )}
             onClick={() => !readOnly && onSeek?.(entry.time)}
+            role={!readOnly && onSeek ? "button" : undefined}
+            tabIndex={!readOnly && onSeek ? 0 : undefined}
+            onKeyDown={!readOnly && onSeek ? (e) => { if (e.key === "Enter" || e.key === " ") { e.preventDefault(); onSeek(entry.time); } } : undefined}
           >
             <span
               className={cn(