@hydralms/components 0.1.3 → 0.3.0

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

@@ -0,0 +1,119 @@
+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;
+  /** Accessible label for screen readers (defaults to "Rich text editor") */
+  ariaLabel?: string;
+  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",
+  ariaLabel = "Rich text editor",
+  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,
+    editorProps: {
+      attributes: {
+        "aria-label": ariaLabel,
+        role: "textbox",
+        "aria-multiline": "true",
+      },
+    },
+    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,157 @@
+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}
+      aria-label={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" role="toolbar" aria-label="Text formatting">
+      <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/ui/toast.tsx

@@ -0,0 +1,170 @@
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useRef,
+  useState,
+  type ReactNode,
+} from "react";
+import { createPortal } from "react-dom";
+import { cva } from "class-variance-authority";
+import { X, CheckCircle2, AlertCircle, AlertTriangle, Info } from "lucide-react";
+import { cn } from "../lib/utils";
+
+const toastVariants = cva(
+  "pointer-events-auto relative flex w-full items-start gap-3 rounded-lg border p-4 pr-8 shadow-lg text-sm transition-all",
+  {
+    variants: {
+      variant: {
+        success:
+          "border-success/50 bg-success/5 text-success [&>svg]:text-success",
+        error:
+          "border-destructive/50 bg-destructive/5 text-destructive [&>svg]:text-destructive",
+        warning:
+          "border-warning/50 bg-warning/5 text-warning [&>svg]:text-warning",
+        info: "border-info/50 bg-info/5 text-info [&>svg]:text-info",
+      },
+    },
+    defaultVariants: {
+      variant: "info",
+    },
+  },
+);
+
+type ToastVariant = "success" | "error" | "warning" | "info";
+
+/** Options for creating a toast notification. */
+interface ToastOptions {
+  /** Toast message */
+  message: string;
+  /** Optional title */
+  title?: string;
+  /** Visual variant */
+  variant?: ToastVariant;
+  /** Auto-dismiss duration in ms (default 5000, 0 = no auto-dismiss) */
+  duration?: number;
+}
+
+interface ToastItem extends ToastOptions {
+  id: string;
+}
+
+interface ToastContextValue {
+  toast: (options: ToastOptions) => void;
+}
+
+const ToastContext = createContext<ToastContextValue | null>(null);
+
+const VARIANT_ICONS: Record<ToastVariant, React.ElementType> = {
+  success: CheckCircle2,
+  error: AlertCircle,
+  warning: AlertTriangle,
+  info: Info,
+};
+
+function ToastCard({
+  item,
+  onDismiss,
+}: {
+  item: ToastItem;
+  onDismiss: (id: string) => void;
+}) {
+  const timerRef = useRef<ReturnType<typeof setTimeout>>(undefined);
+  const duration = item.duration ?? 5000;
+  const Icon = VARIANT_ICONS[item.variant ?? "info"];
+
+  useEffect(() => {
+    if (duration > 0) {
+      timerRef.current = setTimeout(() => onDismiss(item.id), duration);
+    }
+    return () => clearTimeout(timerRef.current);
+  }, [duration, item.id, onDismiss]);
+
+  return (
+    <div
+      data-slot="toast"
+      role="status"
+      aria-live="polite"
+      className={cn(toastVariants({ variant: item.variant ?? "info" }))}
+    >
+      <Icon className="size-4 shrink-0 translate-y-0.5" />
+      <div className="flex-1 space-y-1">
+        {item.title && (
+          <p className="font-medium leading-none">{item.title}</p>
+        )}
+        <p className="text-sm opacity-90">{item.message}</p>
+      </div>
+      <button
+        type="button"
+        onClick={() => onDismiss(item.id)}
+        aria-label="Dismiss notification"
+        className="absolute right-2 top-2 rounded-md p-1 opacity-70 hover:opacity-100 transition-opacity"
+      >
+        <X className="size-3.5" />
+      </button>
+    </div>
+  );
+}
+
+const MAX_VISIBLE = 3;
+let idCounter = 0;
+
+/**
+ * ToastProvider wraps your app to enable toast notifications.
+ * Renders a fixed-position toast container via portal.
+ *
+ * @example
+ * <ToastProvider>
+ *   <App />
+ * </ToastProvider>
+ */
+function ToastProvider({ children }: { children: ReactNode }) {
+  const [toasts, setToasts] = useState<ToastItem[]>([]);
+
+  const toast = useCallback((options: ToastOptions) => {
+    const id = `toast-${++idCounter}`;
+    setToasts((prev) => [...prev.slice(-(MAX_VISIBLE - 1)), { ...options, id }]);
+  }, []);
+
+  const dismiss = useCallback((id: string) => {
+    setToasts((prev) => prev.filter((t) => t.id !== id));
+  }, []);
+
+  return (
+    <ToastContext.Provider value={{ toast }}>
+      {children}
+      {typeof document !== "undefined" &&
+        createPortal(
+          <div
+            data-slot="toaster"
+            className="fixed top-4 right-4 z-50 flex flex-col gap-2 w-80 pointer-events-none"
+          >
+            {toasts.map((item) => (
+              <ToastCard key={item.id} item={item} onDismiss={dismiss} />
+            ))}
+          </div>,
+          document.body,
+        )}
+    </ToastContext.Provider>
+  );
+}
+
+/**
+ * Hook to trigger toast notifications. Must be used within a ToastProvider.
+ *
+ * @example
+ * const { toast } = useToast();
+ * toast({ message: "Saved!", variant: "success" });
+ */
+function useToast(): ToastContextValue {
+  const ctx = useContext(ToastContext);
+  if (!ctx) throw new Error("useToast must be used within a ToastProvider");
+  return ctx;
+}
+
+/** Convenience alias for ToastProvider. */
+const Toaster = ToastProvider;
+
+export { ToastProvider, Toaster, useToast, toastVariants };
+export type { ToastOptions, ToastVariant };

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/debounce.ts

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

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/pick-palette-color.ts

@@ -0,0 +1,33 @@
+/**
+ * Palette CSS variable names matching --palette-0 through --palette-3
+ * defined in globals.css.
+ */
+export const PALETTE_VARS = [
+  "var(--palette-0)",
+  "var(--palette-1)",
+  "var(--palette-2)",
+  "var(--palette-3)",
+] as const;
+
+/** Number of palette colors available. */
+export const PALETTE_COUNT = PALETTE_VARS.length;
+
+/**
+ * Pick a palette CSS variable by cycling through the 4 palette colors.
+ * Useful for assigning varied colors to list items by index.
+ */
+export function pickPaletteColor(index: number): string {
+  return PALETTE_VARS[((index % PALETTE_COUNT) + PALETTE_COUNT) % PALETTE_COUNT];
+}
+
+/** Palette variant name for CVA-based components (badge, progress). */
+export type PaletteVariant = "palette0" | "palette1" | "palette2" | "palette3";
+
+/**
+ * Pick a palette variant name by cycling through the 4 palette variants.
+ * Useful for assigning varied CVA variants to list items by index.
+ */
+export function pickPaletteVariant(index: number): PaletteVariant {
+  const i = ((index % PALETTE_COUNT) + PALETTE_COUNT) % PALETTE_COUNT;
+  return `palette${i}` as PaletteVariant;
+}

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/types.ts

@@ -9,6 +9,20 @@
  *   onEnded={() => markLessonComplete()}
  * />
  */
+/** A text track (captions, subtitles) for the video element. */
+export interface VideoTrack {
+  /** URL of the track file (e.g., .vtt) */
+  src: string;
+  /** Track kind */
+  kind: "captions" | "subtitles" | "descriptions" | "chapters" | "metadata";
+  /** Human-readable track label (e.g., "English") */
+  label: string;
+  /** BCP 47 language code (e.g., "en") */
+  srcLang: string;
+  /** Whether this track should be active by default */
+  default?: boolean;
+}
+
 export interface VideoPlayerProps {
   /** URL of the video source */
   src?: string;
@@ -30,6 +44,8 @@ export interface VideoPlayerProps {
   readOnly?: boolean;
   /** Aspect ratio of the video container */
   aspectRatio?: "16/9" | "4/3" | "1/1";
+  /** Array of text tracks (captions, subtitles) for the video */
+  tracks?: VideoTrack[];
   /** CSS class name for the root element */
   className?: string;
   /** Inline styles for the root element */

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