@locusai/web 0.1.7 → 0.2.2

package/src/components/ui/Avatar.tsx

@@ -0,0 +1,123 @@
+"use client";
+
+import Image from "next/image";
+import { cn } from "@/lib/utils";
+
+/**
+ * Avatar component props
+ *
+ * @property name - User name for initials fallback and alt text
+ * @property src - Optional image URL (if not provided, shows initials)
+ * @property size - Avatar size (default: "md")
+ */
+interface AvatarProps {
+  /** Image URL for avatar photo */
+  src?: string | null;
+  /** User name (used for initials and alt text) */
+  name: string;
+  /** Avatar size */
+  size?: "sm" | "md" | "lg";
+  /** Additional CSS classes */
+  className?: string;
+}
+
+const sizeClasses = {
+  sm: "h-6 w-6 text-[10px]",
+  md: "h-8 w-8 text-xs",
+  lg: "h-10 w-10 text-sm",
+};
+
+const imageSizes = {
+  sm: 24,
+  md: 32,
+  lg: 40,
+};
+
+/**
+ * Extract initials from user name
+ * @example getInitials("John Doe") // "JD"
+ */
+function getInitials(name: string): string {
+  return name
+    .split(" ")
+    .map((n) => n[0])
+    .join("")
+    .toUpperCase()
+    .slice(0, 2);
+}
+
+/**
+ * Get consistent color from user name using hash
+ * Ensures same name always gets same color
+ */
+function getColorFromName(name: string): string {
+  const colors = [
+    "bg-rose-500",
+    "bg-pink-500",
+    "bg-fuchsia-500",
+    "bg-purple-500",
+    "bg-violet-500",
+    "bg-indigo-500",
+    "bg-blue-500",
+    "bg-sky-500",
+    "bg-cyan-500",
+    "bg-teal-500",
+    "bg-emerald-500",
+    "bg-green-500",
+    "bg-lime-500",
+    "bg-yellow-500",
+    "bg-amber-500",
+    "bg-orange-500",
+  ];
+
+  let hash = 0;
+  for (let i = 0; i < name.length; i++) {
+    hash = name.charCodeAt(i) + ((hash << 5) - hash);
+  }
+
+  return colors[Math.abs(hash) % colors.length];
+}
+
+/**
+ * Avatar component
+ *
+ * Displays user avatar with image or initials fallback.
+ * Automatically assigns consistent colors based on name hash.
+ *
+ * @example
+ * // With image
+ * <Avatar src="/avatar.jpg" name="John Doe" />
+ *
+ * @example
+ * // Without image (shows initials)
+ * <Avatar name="Jane Smith" size="lg" />
+ */
+export function Avatar({ src, name, size = "md", className }: AvatarProps) {
+  if (src) {
+    return (
+      <Image
+        src={src}
+        alt={name}
+        width={imageSizes[size]}
+        height={imageSizes[size]}
+        className={cn(
+          "rounded-full object-cover ring-2 ring-border/50",
+          className
+        )}
+      />
+    );
+  }
+
+  return (
+    <div
+      className={cn(
+        "rounded-full flex items-center justify-center font-bold text-white ring-2 ring-border/50",
+        sizeClasses[size],
+        getColorFromName(name),
+        className
+      )}
+    >
+      {getInitials(name)}
+    </div>
+  );
+}

package/src/components/ui/Badge.tsx

@@ -1,16 +1,54 @@
+/**
+ * Badge component props
+ *
+ * @property variant - Badge color variant
+ * @property size - Badge size (default: "sm")
+ */
 interface BadgeProps {
+  /** Badge content */
   children: React.ReactNode;
-  variant?: "default" | "success" | "warning" | "error" | "info" | "purple";
+  /** Badge color variant */
+  variant?:
+    | "default"
+    | "success"
+    | "warning"
+    | "error"
+    | "info"
+    | "purple"
+    | "primary"
+    | "secondary"
+    | "outline";
+  /** Badge size */
   size?: "sm" | "md";
+  /** Additional CSS classes */
+  className?: string;
 }
 
+/**
+ * Badge component
+ *
+ * A small component used to display status, labels, or tags.
+ * Supports multiple variants and sizes.
+ *
+ * @example
+ * // Basic badge
+ * <Badge>New</Badge>
+ *
+ * @example
+ * // Success badge
+ * <Badge variant="success">Active</Badge>
+ */
 export function Badge({
   children,
   variant = "default",
   size = "sm",
+  className = "",
 }: BadgeProps) {
   const variants = {
     default: "bg-primary text-primary-foreground shadow hover:bg-primary/80",
+    primary: "bg-primary/15 text-primary border-primary/20",
+    secondary: "bg-secondary text-secondary-foreground hover:bg-secondary/80",
+    outline: "text-foreground border-border",
     success: "bg-status-done/15 text-status-done border-status-done/20",
     warning:
       "bg-status-progress/15 text-status-progress border-status-progress/20",
@@ -26,14 +64,20 @@ export function Badge({
 
   return (
     <span
-      className={`inline-flex items-center rounded-md border transition-colors focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 ${variants[variant]} ${sizes[size]}`}
+      className={`inline-flex items-center rounded-md border transition-colors focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 ${variants[variant]} ${sizes[size]} ${className}`}
     >
       {children}
     </span>
   );
 }
 
+/**
+ * Priority badge component props
+ *
+ * @property priority - Task priority level
+ */
 interface PriorityBadgeProps {
+  /** Task priority level */
   priority: "LOW" | "MEDIUM" | "HIGH" | "CRITICAL";
 }
 
@@ -44,12 +88,26 @@ const PRIORITY_CONFIG = {
   CRITICAL: { label: "Critical", variant: "error" as const },
 };
 
+/**
+ * Priority badge component
+ *
+ * Displays task priority with appropriate color coding.
+ *
+ * @example
+ * <PriorityBadge priority="HIGH" />
+ */
 export function PriorityBadge({ priority }: PriorityBadgeProps) {
   const config = PRIORITY_CONFIG[priority];
   return <Badge variant={config.variant}>{config.label}</Badge>;
 }
 
+/**
+ * Status badge component props
+ *
+ * @property status - Task status
+ */
 interface StatusBadgeProps {
+  /** Task status value */
   status: string;
 }
 
@@ -68,6 +126,15 @@ const STATUS_CONFIG: Record<
   BLOCKED: { label: "Blocked", variant: "error" },
 };
 
+/**
+ * Status badge component
+ *
+ * Displays task status with appropriate color coding.
+ * Automatically maps status values to display labels and colors.
+ *
+ * @example
+ * <StatusBadge status="IN_PROGRESS" />
+ */
 export function StatusBadge({ status }: StatusBadgeProps) {
   const config = STATUS_CONFIG[status] || {
     label: status,

package/src/components/ui/Button.tsx

@@ -1,47 +1,88 @@
 import { type ButtonHTMLAttributes, forwardRef } from "react";
+import { cn } from "@/lib/utils";
+import { BUTTON_SIZES, BUTTON_VARIANTS } from "./constants";
+import { Spinner } from "./Spinner";
 
-interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
-  variant?:
-    | "primary"
-    | "secondary"
-    | "outline"
-    | "ghost"
-    | "danger"
-    | "success";
-  size?: "sm" | "md" | "lg" | "icon";
+/**
+ * Button component props
+ *
+ * @property variant - Button visual style (default: "primary")
+ * @property size - Button size (default: "md")
+ * @property isLoading - Show loading state with spinner
+ * @property loadingText - Text to show while loading (if not provided, shows original children)
+ */
+export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+  /** Button visual style */
+  variant?: keyof typeof BUTTON_VARIANTS;
+  /** Button size */
+  size?: keyof typeof BUTTON_SIZES;
+  /** Show loading state */
+  isLoading?: boolean;
+  /** Text to display when loading */
+  loadingText?: string;
 }
 
 const Button = forwardRef<HTMLButtonElement, ButtonProps>(
-  ({ className, variant = "primary", size = "md", ...props }, ref) => {
-    const variants = {
-      primary: "bg-primary text-primary-foreground shadow hover:bg-primary/90",
-      secondary:
-        "bg-secondary text-secondary-foreground shadow-sm hover:bg-secondary/80",
-      outline:
-        "border border-input bg-background shadow-sm hover:bg-accent hover:text-accent-foreground",
-      ghost: "hover:bg-accent hover:text-accent-foreground",
-      danger:
-        "bg-destructive text-destructive-foreground shadow-sm hover:bg-destructive/90",
-      success: "bg-emerald-600 text-white shadow-sm hover:bg-emerald-700",
-    };
-
-    const sizes = {
-      sm: "h-8 px-3 text-xs",
-      md: "h-9 px-4 py-2 text-sm",
-      lg: "h-10 px-8 text-base",
-      icon: "h-9 w-9",
-    };
+  (
+    {
+      className,
+      variant = "primary",
+      size = "md",
+      isLoading = false,
+      loadingText,
+      disabled,
+      children,
+      ...props
+    },
+    ref
+  ) => {
+    const isDisabled = isLoading || disabled;
 
     return (
       <button
         ref={ref}
-        className={`inline-flex items-center justify-center gap-2 font-semibold rounded-lg transition-all duration-200 active:scale-95 disabled:opacity-50 disabled:pointer-events-none ${variants[variant]} ${sizes[size]} ${className || ""}`}
+        disabled={isDisabled}
+        className={cn(
+          "inline-flex items-center justify-center gap-2 font-semibold rounded-lg transition-all duration-200 active:scale-95 disabled:opacity-50 disabled:pointer-events-none",
+          BUTTON_VARIANTS[variant],
+          BUTTON_SIZES[size],
+          className
+        )}
+        aria-busy={isLoading}
         {...props}
-      />
+      >
+        {isLoading ? (
+          <>
+            <Spinner size="sm" className="mr-2" aria-hidden="true" />
+            {loadingText || children}
+          </>
+        ) : (
+          children
+        )}
+      </button>
     );
   }
 );
 
+/**
+ * Button component
+ *
+ * A reusable button component with multiple variants and sizes.
+ * Supports loading state with spinner and automatic disabling.
+ *
+ * @example
+ * // Primary button
+ * <Button onClick={handleClick}>Click me</Button>
+ *
+ * @example
+ * // Loading state
+ * <Button isLoading loadingText="Saving...">Save</Button>
+ *
+ * @example
+ * // Different variants
+ * <Button variant="danger">Delete</Button>
+ * <Button variant="ghost">Cancel</Button>
+ */
 Button.displayName = "Button";
 
 export { Button };

package/src/components/ui/Checkbox.tsx

@@ -1,14 +1,46 @@
 import { Check } from "lucide-react";
 import { cn } from "@/lib/utils";
 
+/**
+ * Checkbox component props
+ *
+ * @property checked - Whether checkbox is checked
+ * @property onChange - Callback when checkbox state changes
+ * @property label - Optional label text displayed next to checkbox
+ * @property disabled - Disable the checkbox (default: false)
+ */
 interface CheckboxProps {
+  /** Whether checkbox is currently checked */
   checked: boolean;
+  /** Callback when checkbox state changes */
   onChange: (checked: boolean) => void;
+  /** Optional label text */
   label?: string;
+  /** Disable checkbox interaction */
   disabled?: boolean;
+  /** Additional CSS classes */
   className?: string;
 }
 
+/**
+ * Checkbox component
+ *
+ * A custom checkbox with optional label and full accessibility support.
+ * Automatically applies line-through style to label when checked.
+ *
+ * @example
+ * // Basic checkbox
+ * const [checked, setChecked] = useState(false);
+ * <Checkbox checked={checked} onChange={setChecked} />
+ *
+ * @example
+ * // With label
+ * <Checkbox
+ *   checked={isSubscribed}
+ *   onChange={setIsSubscribed}
+ *   label="Subscribe to newsletter"
+ * />
+ */
 export function Checkbox({
   checked,
   onChange,
@@ -30,11 +62,13 @@ export function Checkbox({
         onChange={(e) => onChange(e.target.checked)}
         disabled={disabled}
         className="hidden"
+        aria-label={label}
       />
       <span
         className={`h-4 w-4 shrink-0 rounded-sm border border-primary shadow focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50 transition-all duration-150 flex items-center justify-center ${
           checked ? "bg-primary text-primary-foreground" : "bg-transparent"
         }`}
+        aria-hidden="true"
       >
         {checked && <Check size={12} strokeWidth={3} />}
       </span>

package/src/components/ui/Dropdown.tsx

@@ -3,22 +3,79 @@
 import { ChevronDown } from "lucide-react";
 import { type ReactNode, useEffect, useRef, useState } from "react";
 
+/**
+ * Dropdown option configuration
+ *
+ * @property value - Unique value identifier
+ * @property label - Display label for option
+ * @property color - Optional color indicator
+ */
 interface DropdownOption<T extends string> {
+  /** Unique value identifier */
   value: T;
+  /** Display label */
   label: string;
+  /** Optional color for indicator dot */
   color?: string;
 }
 
+/**
+ * Dropdown component props
+ *
+ * @property value - Currently selected value
+ * @property onChange - Callback when selection changes
+ * @property options - Available options to select from
+ * @property placeholder - Placeholder text when no selection
+ * @property label - Optional label above dropdown
+ * @property disabled - Disable dropdown interaction
+ * @property renderOption - Custom option rendering
+ */
 interface DropdownProps<T extends string> {
+  /** Currently selected value */
   value: T | undefined;
+  /** Callback when selection changes */
   onChange: (value: T) => void;
+  /** Available options */
   options: DropdownOption<T>[];
+  /** Placeholder text */
   placeholder?: string;
+  /** Optional label */
   label?: string;
+  /** Disable dropdown */
   disabled?: boolean;
+  /** Custom option renderer */
   renderOption?: (option: DropdownOption<T>) => ReactNode;
 }
 
+/**
+ * Dropdown component
+ *
+ * A generic, type-safe dropdown select component with support for
+ * custom option rendering and color indicators.
+ *
+ * @example
+ * // Basic dropdown
+ * const [status, setStatus] = useState<"pending" | "done">();
+ * <Dropdown
+ *   value={status}
+ *   onChange={setStatus}
+ *   options={[
+ *     { value: "pending", label: "Pending" },
+ *     { value: "done", label: "Done" },
+ *   ]}
+ * />
+ *
+ * @example
+ * // With color indicators
+ * <Dropdown
+ *   value={priority}
+ *   onChange={setPriority}
+ *   options={[
+ *     { value: "low", label: "Low", color: "#22c55e" },
+ *     { value: "high", label: "High", color: "#ef4444" },
+ *   ]}
+ * />
+ */
 export function Dropdown<T extends string>({
   value,
   onChange,
@@ -59,6 +116,8 @@ export function Dropdown<T extends string>({
         className="w-full flex items-center justify-between gap-2 px-3.5 py-2.5 bg-background border border-input rounded-md text-foreground text-sm cursor-pointer transition-all hover:bg-accent hover:text-accent-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:opacity-50 disabled:cursor-not-allowed shadow-sm"
         onClick={() => !disabled && setIsOpen(!isOpen)}
         disabled={disabled}
+        aria-haspopup="listbox"
+        aria-expanded={isOpen}
       >
         <span className={selectedOption ? "" : "text-muted-foreground"}>
           {selectedOption ? selectedOption.label : placeholder}
@@ -66,11 +125,15 @@ export function Dropdown<T extends string>({
         <ChevronDown
           size={16}
           className={`transition-transform duration-200 text-muted-foreground ${isOpen ? "rotate-180" : "rotate-0"}`}
+          aria-hidden="true"
         />
       </button>
 
       {isOpen && (
-        <div className="absolute top-full left-0 right-0 mt-2 bg-popover border border-border rounded-md p-1 z-50 max-h-[240px] overflow-y-auto animate-in fade-in slide-in-from-top-2 duration-200 shadow-md">
+        <div
+          className="absolute top-full left-0 right-0 mt-2 bg-popover border border-border rounded-md p-1 z-50 max-h-[240px] overflow-y-auto animate-in fade-in slide-in-from-top-2 duration-200 shadow-md"
+          role="listbox"
+        >
           {options.map((option) => (
             <button
               key={option.value}
@@ -84,6 +147,8 @@ export function Dropdown<T extends string>({
                 onChange(option.value);
                 setIsOpen(false);
               }}
+              role="option"
+              aria-selected={option.value === value}
             >
               {renderOption ? (
                 renderOption(option)
@@ -93,6 +158,7 @@ export function Dropdown<T extends string>({
                     <span
                       className="w-2 h-2 rounded-full shrink-0"
                       style={{ background: option.color }}
+                      aria-hidden="true"
                     />
                   )}
                   {option.label}

package/src/components/ui/EmptyState.tsx

@@ -0,0 +1,129 @@
+"use client";
+
+import { type LucideIcon, Sparkles } from "lucide-react";
+import type { ReactNode } from "react";
+import { cn } from "@/lib/utils";
+
+/**
+ * Empty state component props
+ *
+ * @property icon - Icon component to display
+ * @property title - Main empty state title
+ * @property description - Optional description text
+ * @property action - Optional action button/element
+ * @property variant - Display variant: default, compact, or minimal
+ */
+interface EmptyStateProps {
+  /** Icon component (default: Sparkles) */
+  icon?: LucideIcon;
+  /** Empty state title */
+  title: string;
+  /** Optional description text */
+  description?: string;
+  /** Optional action element (e.g., Button) */
+  action?: ReactNode;
+  /** Additional CSS classes */
+  className?: string;
+  /** Display variant */
+  variant?: "default" | "compact" | "minimal";
+}
+
+/**
+ * Empty state component
+ *
+ * Displays a friendly empty state UI for when no data is available.
+ * Supports three variants for different contexts.
+ *
+ * @example
+ * // Default variant (large, centered)
+ * <EmptyState
+ *   title="No tasks yet"
+ *   description="Create your first task to get started"
+ *   action={<Button>Create Task</Button>}
+ * />
+ *
+ * @example
+ * // Compact variant (smaller)
+ * <EmptyState
+ *   variant="compact"
+ *   title="No results"
+ *   icon={Search}
+ * />
+ *
+ * @example
+ * // Minimal variant (inline)
+ * <EmptyState
+ *   variant="minimal"
+ *   title="No items"
+ *   icon={ListX}
+ * />
+ */
+export function EmptyState({
+  icon: Icon = Sparkles,
+  title,
+  description,
+  action,
+  className,
+  variant = "default",
+}: EmptyStateProps) {
+  if (variant === "minimal") {
+    return (
+      <div
+        className={cn(
+          "flex flex-col items-center justify-center py-8 text-center",
+          className
+        )}
+      >
+        <Icon
+          size={24}
+          className="text-muted-foreground/40 mb-2"
+          aria-hidden="true"
+        />
+        <p className="text-sm text-muted-foreground/60 font-medium">{title}</p>
+      </div>
+    );
+  }
+
+  if (variant === "compact") {
+    return (
+      <div
+        className={cn(
+          "flex flex-col items-center justify-center p-6 text-center bg-secondary/10 rounded-xl border border-dashed border-border/50",
+          className
+        )}
+      >
+        <Icon size={20} className="text-primary/40 mb-2" aria-hidden="true" />
+        <h3 className="text-sm font-semibold text-foreground">{title}</h3>
+        {description && (
+          <p className="text-xs text-muted-foreground mt-1">{description}</p>
+        )}
+        {action && <div className="mt-3">{action}</div>}
+      </div>
+    );
+  }
+
+  return (
+    <div
+      className={cn(
+        "flex flex-col items-center justify-center p-12 text-center",
+        className
+      )}
+    >
+      <div className="relative mb-6">
+        <div className="absolute inset-0 rounded-full" />
+        <div className="relative flex items-center justify-center w-20 h-20 rounded-2xl bg-linear-to-br from-secondary to-secondary/30 border border-border/50">
+          <Icon size={32} className="text-primary/60" aria-hidden="true" />
+        </div>
+      </div>
+
+      <h3 className="text-xl font-bold text-foreground mb-2">{title}</h3>
+      {description && (
+        <p className="max-w-[300px] text-sm text-muted-foreground mb-8 leading-relaxed">
+          {description}
+        </p>
+      )}
+
+      {action && <div>{action}</div>}
+    </div>
+  );
+}