@hydralms/components 0.2.0 → 0.3.0

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/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/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/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-player.tsx

@@ -14,6 +14,7 @@ export const VideoPlayer = ({
   onTimeUpdate,
   readOnly = false,
   aspectRatio = "16/9",
+  tracks,
   className,
   style,
 }: VideoPlayerProps) => {
@@ -103,7 +104,18 @@ export const VideoPlayer = ({
           onEnded={onEnded}
           onTimeUpdate={handleTimeUpdate}
           style={{ width: "100%", aspectRatio, display: "block" }}
-        />
+        >
+          {tracks?.map((track) => (
+            <track
+              key={`${track.kind}-${track.srcLang}`}
+              src={track.src}
+              kind={track.kind}
+              label={track.label}
+              srcLang={track.srcLang}
+              default={track.default}
+            />
+          ))}
+        </video>
       </div>
     </div>
   );