@locusai/web 0.1.7 → 0.2.2

package/src/components/ui/Input.tsx

@@ -1,28 +1,57 @@
 import { forwardRef, type InputHTMLAttributes, type ReactNode } from "react";
+import { cn } from "@/lib/utils";
 
+/**
+ * Input component props
+ *
+ * @property icon - Optional left icon element
+ * @property rightElement - Optional right element (e.g., clear button)
+ * @property error - Show error state
+ */
 interface InputProps extends InputHTMLAttributes<HTMLInputElement> {
+  /** Icon displayed on the left side of input */
   icon?: ReactNode;
+  /** Element displayed on the right side of input */
   rightElement?: ReactNode;
+  /** Show error state */
+  error?: boolean;
 }
 
 const Input = forwardRef<HTMLInputElement, InputProps>(
-  ({ className, icon, rightElement, ...props }, ref) => {
+  ({ className, icon, rightElement, error, ...props }, ref) => {
     return (
       <div className="relative w-full group">
         {icon && (
-          <div className="absolute left-3 top-1/2 -translate-y-1/2 text-text-muted group-focus-within:text-accent transition-colors">
+          <div
+            className="absolute left-3 top-1/2 -translate-y-1/2 text-muted-foreground group-focus-within:text-primary transition-colors"
+            aria-hidden="true"
+          >
             {icon}
           </div>
         )}
         <input
           ref={ref}
-          className={`flex h-9 w-full rounded-md border border-input bg-transparent px-3 py-1 text-sm shadow-sm transition-colors file:border-0 file:bg-transparent file:text-sm file:font-medium placeholder:text-zinc-500 focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50 ${
-            icon ? "pl-10" : "pl-3"
-          } ${rightElement ? "pr-10" : "pr-3"} ${className || ""}`}
+          className={cn(
+            "flex h-9 w-full rounded-lg border bg-secondary/30 px-3 py-1 text-sm transition-all",
+            "placeholder:text-muted-foreground/50",
+            "hover:border-border hover:bg-secondary/50",
+            "focus:outline-none focus:border-primary/50 focus:bg-background focus:ring-2 focus:ring-primary/10",
+            "disabled:cursor-not-allowed disabled:opacity-50",
+            "file:border-0 file:bg-transparent file:text-sm file:font-medium",
+            error
+              ? "border-red-500/50 ring-2 ring-red-500/10"
+              : "border-border/60",
+            icon && "pl-10",
+            rightElement && "pr-10",
+            className
+          )}
           {...props}
         />
         {rightElement && (
-          <div className="absolute right-3 top-1/2 -translate-y-1/2 text-muted-foreground">
+          <div
+            className="absolute right-3 top-1/2 -translate-y-1/2 text-muted-foreground"
+            aria-hidden="true"
+          >
             {rightElement}
           </div>
         )}
@@ -31,6 +60,24 @@ const Input = forwardRef<HTMLInputElement, InputProps>(
   }
 );
 
+/**
+ * Input component
+ *
+ * A flexible input component with support for left/right icons and error states.
+ * Automatically adjusts padding when icons are present.
+ *
+ * @example
+ * // Basic input
+ * <Input placeholder="Enter text..." />
+ *
+ * @example
+ * // With left icon
+ * <Input icon={<Search size={16} />} placeholder="Search..." />
+ *
+ * @example
+ * // With error state
+ * <Input error value={value} onChange={handleChange} />
+ */
 Input.displayName = "Input";
 
 export { Input };

package/src/components/ui/Modal.tsx

@@ -3,13 +3,27 @@
 import { X } from "lucide-react";
 import { type ReactNode, useEffect, useRef } from "react";
 import { createPortal } from "react-dom";
+import { MODAL_SIZES, Z_INDEXES } from "./constants";
 
+/**
+ * Modal component props
+ *
+ * @property isOpen - Control modal visibility
+ * @property onClose - Callback when modal should close
+ * @property title - Optional modal header title
+ * @property size - Modal width size (default: "md")
+ */
 interface ModalProps {
+  /** Whether modal is visible */
   isOpen: boolean;
+  /** Called when user attempts to close modal */
   onClose: () => void;
+  /** Modal content */
   children: ReactNode;
+  /** Optional modal header title */
   title?: string;
-  size?: "sm" | "md" | "lg";
+  /** Modal size */
+  size?: keyof typeof MODAL_SIZES;
 }
 
 export function Modal({
@@ -39,35 +53,37 @@ export function Modal({
 
   if (!isOpen) return null;
 
-  const widths = {
-    sm: "w-[400px]",
-    md: "w-[520px]",
-    lg: "w-[680px]",
-  };
-
   return createPortal(
     <div
       ref={overlayRef}
-      className="fixed inset-0 bg-black/40 backdrop-blur-md flex items-center justify-center z-1000 animate-in fade-in duration-300"
+      className={`fixed inset-0 bg-black/40 backdrop-blur-md flex items-center justify-center ${Z_INDEXES.modalOverlay} animate-in fade-in duration-300`}
       onClick={(e) => {
         if (e.target === overlayRef.current) onClose();
       }}
+      role="presentation"
     >
       <div
         className={`bg-background border border-border rounded-xl shadow-lg animate-in zoom-in-95 duration-200 max-h-[90vh] overflow-hidden flex flex-col ${
-          widths[size]
-        } max-w-[90vw]`}
+          MODAL_SIZES[size]
+        } max-w-[90vw] ${Z_INDEXES.modal}`}
+        role="dialog"
+        aria-modal="true"
+        aria-labelledby={title ? "modal-title" : undefined}
       >
         {title && (
           <div className="flex justify-between items-center p-5 border-b border-border">
-            <h3 className="text-lg font-semibold m-0 text-foreground">
+            <h3
+              id="modal-title"
+              className="text-lg font-semibold m-0 text-foreground"
+            >
               {title}
             </h3>
             <button
               className="bg-transparent border-none text-muted-foreground hover:text-foreground cursor-pointer p-0 transition-colors duration-200"
               onClick={onClose}
+              aria-label="Close modal"
             >
-              <X size={20} />
+              <X size={20} aria-hidden="true" />
             </button>
           </div>
         )}
@@ -77,3 +93,20 @@ export function Modal({
     document.body
   );
 }
+
+/**
+ * Modal component
+ *
+ * A accessible, dismissable modal dialog component.
+ * - Closes on Escape key
+ * - Closes on backdrop click
+ * - Prevents body scroll when open
+ * - Includes proper ARIA attributes
+ *
+ * @example
+ * // Basic modal
+ * <Modal isOpen={isOpen} onClose={handleClose} title="Confirm Action">
+ *   <p>Are you sure?</p>
+ *   <Button onClick={handleConfirm}>Confirm</Button>
+ * </Modal>
+ */

package/src/components/ui/OtpInput.tsx

@@ -0,0 +1,148 @@
+"use client";
+
+import { useEffect, useRef, useState } from "react";
+import { cn } from "@/lib/utils";
+
+/**
+ * OTP input component props
+ *
+ * @property length - Number of input fields (default: 6)
+ * @property value - Current OTP value (e.g., "123456")
+ * @property onChange - Callback when OTP value changes
+ * @property disabled - Disable the inputs
+ */
+interface OtpInputProps {
+  /** Number of OTP digits (default: 6) */
+  length?: number;
+  /** Current OTP value as string */
+  value: string;
+  /** Callback when OTP changes */
+  onChange: (value: string) => void;
+  /** Disable OTP inputs */
+  disabled?: boolean;
+}
+
+/**
+ * OTP input component
+ *
+ * A specialized input component for one-time passwords.
+ * - Auto-focuses next field on digit entry
+ * - Supports backspace and arrow navigation
+ * - Supports paste functionality
+ * - Numeric input only
+ *
+ * @example
+ * const [otp, setOtp] = useState("");
+ * <OtpInput
+ *   length={6}
+ *   value={otp}
+ *   onChange={setOtp}
+ * />
+ */
+export function OtpInput({
+  length = 6,
+  value,
+  onChange,
+  disabled = false,
+}: OtpInputProps) {
+  const [focusedIndex, setFocusedIndex] = useState<number | null>(null);
+  const inputRefs = useRef<(HTMLInputElement | null)[]>([]);
+
+  // Initialize refs array
+  useEffect(() => {
+    inputRefs.current = inputRefs.current.slice(0, length);
+  }, [length]);
+
+  const handleChange = (
+    e: React.ChangeEvent<HTMLInputElement>,
+    index: number
+  ) => {
+    const char = e.target.value.slice(-1); // Only take last character
+
+    // Only allow numbers
+    if (char && !/^\d$/.test(char)) return;
+
+    const newValue = value.split("");
+    newValue[index] = char;
+    const finalValue = newValue.join("");
+    onChange(finalValue);
+
+    // Focus next input
+    if (char && index < length - 1) {
+      inputRefs.current[index + 1]?.focus();
+    }
+  };
+
+  const handleKeyDown = (
+    e: React.KeyboardEvent<HTMLInputElement>,
+    index: number
+  ) => {
+    if (e.key === "Backspace") {
+      if (!value[index] && index > 0) {
+        // If current is empty, move back and clear previous
+        const newValue = value.split("");
+        newValue[index - 1] = "";
+        onChange(newValue.join(""));
+        inputRefs.current[index - 1]?.focus();
+      } else {
+        // Just clear current
+        const newValue = value.split("");
+        newValue[index] = "";
+        onChange(newValue.join(""));
+      }
+    } else if (e.key === "ArrowLeft" && index > 0) {
+      inputRefs.current[index - 1]?.focus();
+    } else if (e.key === "ArrowRight" && index < length - 1) {
+      inputRefs.current[index + 1]?.focus();
+    }
+  };
+
+  const handlePaste = (e: React.ClipboardEvent) => {
+    e.preventDefault();
+    const pastedData = e.clipboardData
+      .getData("text")
+      .slice(0, length)
+      .replace(/\D/g, "");
+    if (pastedData) {
+      onChange(pastedData);
+      // Focus the next available slot or the last one
+      const nextIndex = Math.min(pastedData.length, length - 1);
+      inputRefs.current[nextIndex]?.focus();
+    }
+  };
+
+  return (
+    <fieldset
+      className="flex justify-between gap-2 sm:gap-3"
+      onPaste={handlePaste}
+    >
+      <legend className="sr-only">One-time password input</legend>
+      {Array.from({ length }).map((_, i) => (
+        <input
+          key={i}
+          ref={(el) => {
+            inputRefs.current[i] = el;
+          }}
+          type="text"
+          inputMode="numeric"
+          autoComplete="one-time-code"
+          value={value[i] || ""}
+          onChange={(e) => handleChange(e, i)}
+          onKeyDown={(e) => handleKeyDown(e, i)}
+          onFocus={() => setFocusedIndex(i)}
+          onBlur={() => setFocusedIndex(null)}
+          disabled={disabled}
+          className={cn(
+            "w-full h-12 sm:h-14 text-center text-xl font-bold rounded-xl border transition-all duration-200 outline-none",
+            "bg-secondary/20 border-border/40 text-foreground",
+            focusedIndex === i
+              ? "border-primary bg-background ring-4 ring-primary/10"
+              : "hover:border-border/80",
+            disabled && "opacity-50 cursor-not-allowed"
+          )}
+          aria-label={`Digit ${i + 1}`}
+        />
+      ))}
+    </fieldset>
+  );
+}

package/src/components/ui/Skeleton.tsx

@@ -0,0 +1,36 @@
+"use client";
+
+import { cn } from "@/lib/utils";
+
+/**
+ * Skeleton component props
+ *
+ * @property className - Additional CSS classes
+ */
+interface SkeletonProps {
+  /** Additional CSS classes */
+  className?: string;
+}
+
+/**
+ * Skeleton component
+ *
+ * A placeholder element with pulsing animation for loading states.
+ * Use to create skeleton screens that match your content layout.
+ *
+ * @example
+ * // Skeleton for avatar
+ * <Skeleton className="h-10 w-10 rounded-full" />
+ *
+ * @example
+ * // Skeleton for text
+ * <Skeleton className="h-4 w-full rounded" />
+ */
+export function Skeleton({ className }: SkeletonProps) {
+  return (
+    <div
+      className={cn("animate-pulse rounded-md bg-muted/50", className)}
+      aria-busy="true"
+    />
+  );
+}

package/src/components/ui/Spinner.tsx

@@ -0,0 +1,112 @@
+"use client";
+
+import { cn } from "@/lib/utils";
+import { SPINNER_SIZES } from "./constants";
+
+/**
+ * Spinner component props
+ *
+ * @property size - Spinner size (default: "md")
+ * @property className - Additional CSS classes
+ */
+interface SpinnerProps {
+  /** Additional CSS classes */
+  className?: string;
+  /** Spinner size */
+  size?: keyof typeof SPINNER_SIZES;
+}
+
+/**
+ * Spinner component
+ *
+ * A circular loading indicator with smooth animation.
+ * Used to indicate data fetching or processing.
+ *
+ * @example
+ * // Default spinner
+ * <Spinner />
+ *
+ * @example
+ * // Large spinner
+ * <Spinner size="lg" />
+ */
+export function Spinner({ className, size = "md" }: SpinnerProps) {
+  const sizeClasses = {
+    sm: "h-4 w-4 border-2",
+    md: "h-8 w-8 border-3",
+    lg: "h-12 w-12 border-4",
+    xl: "h-16 w-16 border-4",
+  };
+
+  return (
+    <div
+      className={cn(
+        "animate-spin rounded-full border-primary border-t-transparent",
+        sizeClasses[size],
+        className
+      )}
+    />
+  );
+}
+
+/**
+ * Full-page loading state component
+ *
+ * Displays a centered spinner for full-page loading scenarios.
+ * Use for page transitions and initial data loading.
+ *
+ * @example
+ * <LoadingPage />
+ */
+export function LoadingPage() {
+  return (
+    <div className="flex items-center justify-center w-full h-full min-h-screen">
+      <Spinner size="lg" />
+    </div>
+  );
+}
+
+/**
+ * Full-screen loading skeleton component
+ *
+ * Displays a full-screen loading state with sidebar placeholder
+ * to prevent layout shift during initial hydration.
+ * Use during app initialization in dashboard layout.
+ *
+ * @example
+ * <LoadingSkeleton />
+ */
+export function LoadingSkeleton() {
+  return (
+    <div className="flex h-screen overflow-hidden bg-background">
+      {/* Sidebar Skeleton */}
+      <aside className="w-56 border-r border-border bg-background flex flex-col">
+        <div className="flex-1" />
+      </aside>
+
+      {/* Main Content Skeleton */}
+      <main className="flex-1 overflow-auto bg-background p-6">
+        <div className="flex items-center justify-center h-full">
+          <Spinner size="lg" />
+        </div>
+      </main>
+    </div>
+  );
+}
+
+/**
+ * Overlay loading state component
+ *
+ * Displays a semi-transparent overlay with centered spinner.
+ * Use for asynchronous operations on pages that should remain interactive.
+ *
+ * @example
+ * {isLoading && <LoadingOverlay />}
+ */
+export function LoadingOverlay() {
+  return (
+    <div className="absolute inset-0 bg-background/50 backdrop-blur-sm z-50 flex items-center justify-center">
+      <Spinner size="lg" />
+    </div>
+  );
+}

package/src/components/ui/Textarea.tsx

@@ -1,15 +1,40 @@
 import { forwardRef, type TextareaHTMLAttributes } from "react";
+import { cn } from "@/lib/utils";
 
+/**
+ * Textarea component props
+ *
+ * Extends standard HTML textarea attributes
+ */
 interface TextareaProps extends TextareaHTMLAttributes<HTMLTextAreaElement> {}
 
+/**
+ * Textarea component
+ *
+ * A multi-line text input field with consistent styling.
+ * Automatically prevents resizing via CSS (use JavaScript if needed).
+ *
+ * @example
+ * // Basic textarea
+ * <Textarea placeholder="Enter description..." />
+ *
+ * @example
+ * // With value binding
+ * <Textarea
+ *   value={description}
+ *   onChange={(e) => setDescription(e.target.value)}
+ *   disabled={isLoading}
+ * />
+ */
 const Textarea = forwardRef<HTMLTextAreaElement, TextareaProps>(
   ({ className, ...props }, ref) => {
     return (
       <textarea
         ref={ref}
-        className={`flex min-h-[60px] w-full rounded-md border border-input bg-transparent px-3 py-2 text-sm shadow-sm placeholder:text-zinc-500 focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50 resize-none ${
-          className || ""
-        }`}
+        className={cn(
+          "flex min-h-[60px] w-full rounded-md border border-input bg-transparent px-3 py-2 text-sm shadow-sm placeholder:text-zinc-500 focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50 resize-none",
+          className
+        )}
         {...props}
       />
     );

package/src/components/ui/Toast.tsx

@@ -0,0 +1,99 @@
+"use client";
+
+import { Toaster as SonnerToaster, toast } from "sonner";
+
+// Re-export toast for convenience
+export { toast };
+
+/**
+ * Toaster component
+ *
+ * Renders the toast notification container.
+ * Place at root level in your app (typically in layout).
+ * Handles all notification positioning and styling.
+ *
+ * @example
+ * // In layout.tsx
+ * export default function Layout() {
+ *   return (
+ *     <>
+ *       {children}
+ *       <Toaster />
+ *     </>
+ *   );
+ * }
+ */
+export function Toaster() {
+  return (
+    <SonnerToaster
+      position="top-center"
+      expand={false}
+      richColors
+      theme="dark"
+      toastOptions={{
+        style: {
+          background: "rgba(23, 23, 23, 0.95)",
+          border: "1px solid rgba(255, 255, 255, 0.1)",
+          backdropFilter: "blur(12px)",
+        },
+        classNames: {
+          toast: "rounded-xl shadow-xl",
+          title: "font-semibold text-sm",
+          description: "text-muted-foreground text-xs",
+          success: "!bg-emerald-950/90 !border-emerald-500/30",
+          error: "!bg-rose-950/90 !border-rose-500/30",
+          warning: "!bg-amber-950/90 !border-amber-500/30",
+          info: "!bg-sky-950/90 !border-sky-500/30",
+        },
+      }}
+    />
+  );
+}
+
+/**
+ * Toast notification convenience wrapper
+ *
+ * Provides typed toast methods with consistent options.
+ *
+ * @example
+ * showToast.success("Saved!", "Your changes have been saved");
+ * showToast.error("Error", "Something went wrong");
+ * showToast.promise(apiCall(), {
+ *   loading: "Saving...",
+ *   success: "Saved!",
+ *   error: "Error saving",
+ * });
+ */
+export const showToast = {
+  /** Success notification */
+  success: (title: string, description?: string) => {
+    toast.success(title, { description, dismissible: true });
+  },
+  /** Error notification */
+  error: (title: string, description?: string) => {
+    toast.error(title, { description, dismissible: true });
+  },
+  /** Warning notification */
+  warning: (title: string, description?: string) => {
+    toast.warning(title, { description, dismissible: true });
+  },
+  /** Info notification */
+  info: (title: string, description?: string) => {
+    toast.info(title, { description, dismissible: true });
+  },
+  /** Loading notification (returns ID for updating) */
+  loading: (title: string, description?: string) => {
+    return toast.loading(title, { description, dismissible: true });
+  },
+  /** Promise-based notification for async operations */
+  promise: <T,>(
+    promise: Promise<T>,
+    messages: {
+      loading: string;
+      success: string;
+      error: string;
+    }
+  ) => {
+    return toast.promise(promise, messages);
+  },
+};

package/src/components/ui/Toggle.tsx

@@ -0,0 +1,63 @@
+"use client";
+
+import { motion } from "framer-motion";
+
+/**
+ * Toggle component props
+ *
+ * @property checked - Whether toggle is on
+ * @property onChange - Callback when toggle state changes
+ * @property disabled - Disable toggle interaction
+ */
+interface ToggleProps {
+  /** Whether toggle is currently on/checked */
+  checked: boolean;
+  /** Callback when toggle state changes */
+  onChange: (checked: boolean) => void;
+  /** Disable toggle */
+  disabled?: boolean;
+}
+
+/**
+ * Toggle component
+ *
+ * An accessible, animated toggle switch component.
+ * Uses Framer Motion for smooth animations.
+ *
+ * @example
+ * const [isEnabled, setIsEnabled] = useState(false);
+ * <Toggle
+ *   checked={isEnabled}
+ *   onChange={setIsEnabled}
+ * />
+ *
+ * @example
+ * // Disabled toggle
+ * <Toggle
+ *   checked={true}
+ *   onChange={handleChange}
+ *   disabled={isLoading}
+ * />
+ */
+export function Toggle({ checked, onChange, disabled }: ToggleProps) {
+  return (
+    <button
+      type="button"
+      role="switch"
+      aria-checked={checked}
+      aria-label={checked ? "Enabled" : "Disabled"}
+      disabled={disabled}
+      onClick={() => onChange(!checked)}
+      className={`relative inline-flex h-6 w-11 shrink-0 cursor-pointer rounded-full border-2 border-transparent transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary focus-visible:ring-offset-2 ${
+        checked ? "bg-primary" : "bg-secondary"
+      } ${disabled ? "opacity-50 cursor-not-allowed" : ""}`}
+    >
+      <motion.span
+        animate={{ x: checked ? 20 : 0 }}
+        transition={{ type: "spring", stiffness: 500, damping: 30 }}
+        className="pointer-events-none inline-block h-5 w-5 transform rounded-full bg-white shadow-lg ring-0"
+        aria-hidden="true"
+      />
+    </button>
+  );
+}