# LambdaCurry Forms - Complete Implementation Guide for LLMs

This comprehensive guide covers everything needed to implement forms using the `@lambdacurry/forms` remix-hook-form components, including the new FormError component for form-level error handling. This documentation is specifically designed for LLMs to understand all features, patterns, and best practices.

## Core Architecture Overview

The library provides **form-aware wrapper components** in the `remix-hook-form` directory that automatically integrate with React Router forms and Remix Hook Form context. These components eliminate boilerplate while maintaining full customization capabilities.

### Key Principle: Zero Boilerplate Form Integration
- Components automatically access form context via `useRemixFormContext()`
- No need to manually pass `control` props
- Automatic error handling and validation display
- Built-in accessibility features

## Form-Level Error Handling with FormError

The `FormError` component provides standardized form-level error handling, complementing the existing field-level error system.

### FormError Component Usage

```typescript
// Import form-aware FormError component
import { FormError } from '@lambdacurry/forms';

// Basic usage - looks for errors._form by default
<FormError />

// Custom error key
<FormError name="general" />

// With custom styling and placement
<FormError className="mb-4 p-3 bg-red-50 border border-red-200 rounded" />

// With custom component override
<FormError 
  components={{
    FormMessage: CustomErrorMessage,
  }}
/>
```

### Server Action Pattern for Form-Level Errors

```typescript
export const action = async ({ request }: ActionFunctionArgs) => {
  const { data, errors } = await getValidatedFormData<FormData>(
    request, 
    zodResolver(formSchema)
  );

  // Return field-level validation errors
  if (errors) {
    return { errors };
  }

  // Business logic validation
  try {
    await processForm(data);
    return { message: 'Success!' };
  } catch (error) {
    // Return form-level error using _form key
    return {
      errors: {
        _form: { message: 'Unable to process form. Please try again.' }
      }
    };
  }
};
```

### Error Hierarchy Guidelines

**Field-Level Errors (use FormMessage automatically in form components):**
- Validation errors: "Email is required", "Password too short"
- Format errors: "Invalid email format"
- Field-specific business rules: "Username already taken"

**Form-Level Errors (use FormError component):**
- Server errors: "Server temporarily unavailable"
- Authentication failures: "Invalid credentials"
- Network issues: "Connection timeout"
- General business logic: "Account suspended"
- Rate limiting: "Too many attempts, try again later"

## Basic Form Setup Pattern

## Import Structure

The `@lambdacurry/forms` library follows a clear import structure:

### Form-Aware Components (from `@lambdacurry/forms`)
These components automatically integrate with React Router forms and Remix Hook Form context:
- `TextField` - Form-aware text input with automatic validation
- `Textarea` - Form-aware textarea with automatic validation  
- `Checkbox` - Form-aware checkbox with automatic validation
- `Switch` - Form-aware switch/toggle with automatic validation
- `RadioGroup` - Form-aware radio group with automatic validation
- `RadioGroupItem` - Individual radio items for RadioGroup
- `DatePicker` - Form-aware date picker with automatic validation
- `DropdownMenuSelect` - Form-aware dropdown select with automatic validation
- `OtpInput` - Form-aware OTP/PIN input with automatic validation
- `FormError` - Component for displaying form-level errors
- `FormLabel`, `FormControl`, `FormDescription`, `FormMessage` - Form field components
- `useFormField` - Hook for accessing form field context
- Data table components: `DataTableRouterForm`, `DataTableRouterToolbar`, etc.

### UI Components (from `@lambdacurry/forms/ui`)
These are the underlying UI components without form integration:
- `Button` - Button component with variants
- `Calendar` - Calendar component for date selection
- `Badge` - Badge/chip component for labels
- `Dialog` - Modal dialog component
- `Popover` - Popover/tooltip component
- `Select` - Basic select dropdown
- `Separator` - Visual separator/divider
- `Slider` - Range slider component
- `Table` - Table components for data display
- `Tabs` - Tab navigation component
- `Command` - Command palette/search component
- Field variants: `CheckboxField`, `TextareaField`, `TextField`, `SwitchField`, etc.
- And many more UI primitives

## Component Reference

### Complete List of Form-Aware Components (`@lambdacurry/forms`)
```typescript
// Form input components (automatically integrate with form context)
import { 
  TextField,           // Text input with validation
  Textarea,           // Multi-line text input with validation
  Checkbox,           // Checkbox with validation
  Switch,             // Toggle switch with validation
  RadioGroup,         // Radio button group with validation
  RadioGroupItem,     // Individual radio button
  DatePicker,         // Date selection with validation
  DropdownMenuSelect, // Dropdown select with validation
  OtpInput,           // OTP/PIN input with validation
  
  // Form structure components
  FormError,          // Form-level error display
  FormLabel,          // Form field labels
  FormControl,        // Form field wrapper
  FormDescription,    // Form field descriptions
  FormMessage,        // Form field error messages
  useFormField,       // Hook for form field context
  
  // Data table components
  DataTableRouterForm,
  DataTableRouterToolbar,
  useDataTableUrlState,
} from '@lambdacurry/forms';
```

### Complete List of UI Components (`@lambdacurry/forms/ui`)
```typescript
// Basic UI components (no form integration)
import {
  // Buttons and actions
  Button,             // Button with variants
  
  // Form inputs (non-form-aware versions)
  CheckboxField,      // Checkbox without form integration
  TextareaField,      // Textarea without form integration
  TextField,          // Text input without form integration
  SwitchField,        // Switch without form integration
  RadioGroupField,    // Radio group without form integration
  DatePickerField,    // Date picker without form integration
  DropdownMenuSelectField, // Dropdown without form integration
  OtpInputField,      // OTP input without form integration
  FormErrorField,     // Error display without form integration
  
  // Layout and navigation
  Dialog,             // Modal dialogs
  Popover,            // Popover/tooltips
  Tabs,               // Tab navigation
  Separator,          // Visual dividers
  
  // Data display
  Table,              // Table components
  Badge,              // Labels and badges
  Calendar,           // Calendar component
  
  // Form primitives
  Label,              // Basic labels
  Select,             // Basic select dropdown
  Slider,             // Range slider
  Command,            // Command palette
  
  // Data table system
  DataTable,          // Data table components
  DataTableFilter,    // Table filtering
  
  // Utilities
  DebouncedInput,     // Debounced input
} from '@lambdacurry/forms/ui';
```

### 1. Required Imports
```typescript
import { zodResolver } from '@hookform/resolvers/zod';
import { RemixFormProvider, useRemixForm, getValidatedFormData } from 'remix-hook-form';
import { z } from 'zod';
import { useFetcher, type ActionFunctionArgs } from 'react-router';

// Import form-aware components from main package
import { TextField, Checkbox, FormError } from '@lambdacurry/forms';
// Import UI components from /ui subpath
import { Button } from '@lambdacurry/forms/ui';
```

### 2. Zod Schema Definition
```typescript
const formSchema = z.object({
  username: z.string().min(3, 'Username must be at least 3 characters'),
  email: z.string().email('Invalid email address'),
  terms: z.boolean().refine(val => val === true, 'You must accept the terms'),
  age: z.coerce.number().min(18, 'Must be at least 18 years old'),
});

type FormData = z.infer<typeof formSchema>;
```

### 3. Complete Login Form Example with FormError

```typescript
const LoginForm = () => {
  const fetcher = useFetcher<{ 
    message?: string; 
    errors?: Record<string, { message: string }> 
  }>();
  
  const methods = useRemixForm<FormData>({
    resolver: zodResolver(formSchema),
    defaultValues: {
      email: '',
      password: '',
    },
    fetcher,
    submitConfig: {
      action: '/login',
      method: 'post',
    },
  });

  const isSubmitting = fetcher.state === 'submitting';

  return (
    <RemixFormProvider {...methods}>
      <fetcher.Form onSubmit={methods.handleSubmit} className="max-w-md mx-auto p-6 space-y-4">
        <h2 className="text-xl font-semibold text-gray-900">Sign In</h2>
        
        <TextField
          name="email"
          type="email"
          label="Email Address"
          placeholder="Enter your email"
          disabled={isSubmitting}
        />
        
        <TextField
          name="password"
          type="password"
          label="Password"
          placeholder="Enter your password"
          disabled={isSubmitting}
        />
        
        <FormError className="mb-4" />
        
        <Button type="submit" disabled={isSubmitting} className="w-full">
          {isSubmitting ? 'Signing In...' : 'Sign In'}
        </Button>
        
        {fetcher.data?.message && (
          <div className="mt-4 p-4 bg-green-50 border border-green-200 rounded-md">
            <p className="text-green-700 font-medium">{fetcher.data.message}</p>
          </div>
        )}
      </fetcher.Form>
    </RemixFormProvider>
  );
};
```

### 4. General Form Component Setup
```typescript
const MyFormComponent = () => {
  const fetcher = useFetcher<{ message: string; errors?: Record<string, { message: string }> }>();
  
  const methods = useRemixForm<FormData>({
    resolver: zodResolver(formSchema),
    defaultValues: {
      username: '',
      email: '',
      terms: false,
      age: undefined,
    },
    fetcher,
    submitConfig: {
      action: '/',
      method: 'post',
    },
  });

  return (
    <RemixFormProvider {...methods}>
      <fetcher.Form onSubmit={methods.handleSubmit}>
        <TextField name="username" label="Username" />
        <TextField name="email" label="Email Address" />
        <TextField name="age" type="number" label="Age" />
        <Checkbox name="terms" label="Accept Terms and Conditions" />
        
        <Button type="submit">Submit</Button>
        {fetcher.data?.message && <p>{fetcher.data.message}</p>}
      </fetcher.Form>
    </RemixFormProvider>
  );
};
```

### 5. Server Action Handler with FormError Support
```typescript
export const action = async ({ request }: ActionFunctionArgs) => {
  const { data, errors } = await getValidatedFormData<FormData>(
    request, 
    zodResolver(formSchema)
  );

  if (errors) {
    return { errors };
  }

  // Business logic validation
  try {
    const user = await authenticateUser(data.email, data.password);
    return { message: 'Login successful!', redirectTo: '/dashboard' };
  } catch (error) {
    // Return form-level error using _form key
    return {
      errors: {
        _form: { message: 'Invalid credentials. Please try again.' }
      }
    };
  }
};
```

## Available Form Components

### TextField Component
```typescript
<TextField 
  name="fieldName"           // Required: field name for form registration
  label="Field Label"        // Optional: display label
  description="Help text"    // Optional: description text
  placeholder="Enter text"   // Optional: placeholder text
  type="text"               // Optional: input type (text, email, password, number, etc.)
  prefix="$"                // Optional: prefix content (e.g., currency symbol)
  suffix="USD"              // Optional: suffix content (e.g., units)
  className="custom-class"   // Optional: additional CSS classes
  components={{              // Optional: custom component overrides
    Input: CustomInput,
    FormLabel: CustomLabel,
    FormMessage: CustomMessage,
  }}
/>
```

### Textarea Component
```typescript
<Textarea 
  name="message"
  label="Your Message"
  description="Enter your detailed message"
  placeholder="Type your message here..."
  rows={5}                  // Optional: number of visible rows
  className="custom-class"
  components={{
    TextArea: CustomTextarea,
    FormLabel: CustomLabel,
  }}
/>
```

### Checkbox Component
```typescript
<Checkbox 
  name="terms"
  label="Accept Terms and Conditions"
  description="You must accept our terms to continue"
  className="custom-class"
  components={{
    FormLabel: CustomLabel,
    FormMessage: CustomMessage,
  }}
/>
```

### Switch Component
```typescript
<Switch 
  name="notifications"
  label="Enable Notifications"
  description="Receive email notifications"
  className="custom-class"
/>
```

### RadioGroup Component
Two usage patterns available:

#### Pattern 1: Using options prop
```typescript
const sizeOptions = [
  { value: 'xs', label: 'Extra Small' },
  { value: 'sm', label: 'Small' },
  { value: 'md', label: 'Medium' },
  { value: 'lg', label: 'Large' },
];

<RadioGroup
  name="size"
  label="Select Size"
  description="Choose your preferred size"
  options={sizeOptions}
  labelClassName="font-semibold"    // Optional: custom label styling
  itemClassName="p-2 rounded"       // Optional: custom item styling
/>
```

#### Pattern 2: Using RadioGroupItem children
```typescript
<RadioGroup
  name="design"
  label="Design Style"
  description="Choose your design preference"
>
  <div className="grid grid-cols-3 gap-4">
    <RadioGroupItem
      value="modern"
      label="Modern"
      wrapperClassName="bg-blue-50 p-3 rounded-lg"
      labelClassName="text-blue-800 font-bold"
    />
    <RadioGroupItem
      value="classic"
      label="Classic"
      wrapperClassName="bg-amber-50 p-3 rounded-lg"
      labelClassName="text-amber-800 font-bold"
    />
  </div>
</RadioGroup>
```

### DatePicker Component
```typescript
<DatePicker 
  name="birthDate"
  label="Birth Date"
  description="Select your date of birth"
  className="custom-class"
  disabled={isSubmitting}   // Optional: disable during form submission
/>
```

**Zod Schema for Date Fields:**
```typescript
const formSchema = z.object({
  birthDate: z.coerce.date({
    required_error: 'Please select a date',
  }),
});
```

### DropdownMenuSelect Component
```typescript
<DropdownMenuSelect 
  name="fruit"
  label="Select Fruit"
  description="Choose your favorite fruit"
  disabled={isSubmitting}   // Optional: disable during form submission
>
  <DropdownMenuSelectItem value="apple">Apple</DropdownMenuSelectItem>
  <DropdownMenuSelectItem value="banana">Banana</DropdownMenuSelectItem>
  <DropdownMenuSelectItem value="orange">Orange</DropdownMenuSelectItem>
</DropdownMenuSelect>
```

**Zod Schema for Select Fields:**
```typescript
const formSchema = z.object({
  fruit: z.string({
    required_error: 'Please select a fruit',
  }),
});
```

### OTPInput Component
```typescript
<OTPInput 
  name="otp"
  label="Enter Verification Code"
  description="Enter the 6-digit code sent to your phone"
  maxLength={6}             // Required: number of digits
  className="custom-class"
  disabled={isSubmitting}   // Optional: disable during form submission
/>
```

**Zod Schema for OTP Fields:**
```typescript
const formSchema = z.object({
  otp: z.string().min(6, 'OTP must be 6 digits'),
});
```

## Component Customization System

### Custom Input Components
```typescript
// Create custom input component
const PurpleInput = (props: React.InputHTMLAttributes<HTMLInputElement>) => (
  <input
    {...props}
    className="w-full rounded-lg border-2 border-purple-300 bg-purple-50 px-4 py-2 text-purple-900 focus:border-purple-500"
  />
);

// Use in TextField
<TextField
  name="email"
  label="Email"
  components={{
    Input: PurpleInput,
  }}
/>
```

### Custom Form Components
```typescript
// Custom label
const CustomLabel = (props: React.ComponentPropsWithoutRef<typeof FormLabel>) => (
  <FormLabel className="text-lg font-bold text-blue-700" {...props} />
);

// Custom error message
const CustomMessage = (props: React.ComponentPropsWithoutRef<typeof FormMessage>) => (
  <FormMessage className="text-red-500 bg-red-50 p-2 rounded-md" {...props} />
);

// Apply to any component
<TextField
  name="username"
  label="Username"
  components={{
    FormLabel: CustomLabel,
    FormMessage: CustomMessage,
  }}
/>
```

## Advanced Form Patterns

### Custom Submit Handlers

Use `submitHandlers.onValid` to transform data before submission. This is useful for:
- Adding computed fields (timestamps, IDs)
- Transforming data formats
- Combining multiple fields
- Adding metadata

```typescript
const methods = useRemixForm<FormData>({
  resolver: zodResolver(formSchema),
  fetcher,
  submitConfig: {
    action: '/',
    method: 'post',
  },
  submitHandlers: {
    onValid: (data) => {
      // Transform data before submission
      const transformedData = {
        ...data,
        timestamp: new Date().toISOString(),
        processed: true,
        fullName: `${data.firstName} ${data.lastName}`, // Combine fields
      };

      fetcher.submit(
        createFormData(transformedData),
        {
          method: 'post',
          action: '/',
        }
      );
    },
  },
});
```

### Checkbox Groups with Custom Submission

When working with multiple checkboxes, you often want to transform the boolean object into an array of selected values:

**Schema for Checkbox Group:**
```typescript
const formSchema = z.object({
  colors: z.object({
    red: z.boolean().default(false),
    blue: z.boolean().default(false),
    green: z.boolean().default(false),
  }),
});
```

**Form Implementation:**
```typescript
<div className="space-y-2">
  <Checkbox name="colors.red" label="Red" />
  <Checkbox name="colors.blue" label="Blue" />
  <Checkbox name="colors.green" label="Green" />
</div>
```

**Custom Submission Handler:**
```typescript
submitHandlers: {
  onValid: (data) => {
    // Extract selected colors into array
    const selectedColors = Object.entries(data.colors)
      .filter(([_, selected]) => selected)
      .map(([color]) => color);

    // Submit transformed data
    fetcher.submit(
      createFormData({ selectedColors }),
      { method: 'post', action: '/' }
    );
  },
}
```

### Conditional Field Display
```typescript
const MyForm = () => {
  const methods = useRemixForm<FormData>({...});
  const watchAccountType = methods.watch('accountType');

  return (
    <RemixFormProvider {...methods}>
      <fetcher.Form onSubmit={methods.handleSubmit}>
        <RadioGroup
          name="accountType"
          label="Account Type"
          options={[
            { value: 'personal', label: 'Personal' },
            { value: 'business', label: 'Business' },
          ]}
        />

        {/* Conditional field based on selection */}
        {watchAccountType === 'business' && (
          <TextField
            name="companyName"
            label="Company Name"
            description="Enter your company name"
          />
        )}

        <Button type="submit">Submit</Button>
      </fetcher.Form>
    </RemixFormProvider>
  );
};
```

### Form with Loading States
```typescript
const MyForm = () => {
  const fetcher = useFetcher<{ message: string }>();
  const isSubmitting = fetcher.state === 'submitting';

  return (
    <RemixFormProvider {...methods}>
      <fetcher.Form onSubmit={methods.handleSubmit}>
        <TextField name="email" label="Email" disabled={isSubmitting} />
        
        <Button type="submit" disabled={isSubmitting}>
          {isSubmitting ? 'Submitting...' : 'Submit'}
        </Button>
        
        {fetcher.data?.message && (
          <div className="mt-4 p-4 bg-green-50 rounded-md">
            <p className="text-green-700">{fetcher.data.message}</p>
          </div>
        )}
      </fetcher.Form>
    </RemixFormProvider>
  );
};
```

## Zod Schema Patterns & Validation

### Common Validation Patterns
```typescript
const formSchema = z.object({
  // Required string with minimum length
  username: z.string().min(3, 'Username must be at least 3 characters'),
  
  // Email validation
  email: z.string().email('Please enter a valid email address'),
  
  // Password with complexity requirements
  password: z.string()
    .min(8, 'Password must be at least 8 characters')
    .regex(/^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)/, 'Password must contain uppercase, lowercase, and number'),
  
  // Number with range validation
  age: z.coerce.number()
    .min(18, 'Must be at least 18 years old')
    .max(120, 'Age must be realistic'),
  
  // Boolean with custom validation
  terms: z.boolean().refine(val => val === true, 'You must accept the terms'),
  
  // Optional fields
  middleName: z.string().optional(),
  
  // Date validation
  birthDate: z.coerce.date({
    required_error: 'Please select your birth date',
  }),
  
  // Enum validation for select/radio
  size: z.enum(['xs', 'sm', 'md', 'lg', 'xl'], {
    required_error: 'Please select a size',
  }),
  
  // Array validation
  hobbies: z.array(z.string()).min(1, 'Select at least one hobby'),
  
  // Object validation for nested data
  address: z.object({
    street: z.string().min(1, 'Street is required'),
    city: z.string().min(1, 'City is required'),
    zipCode: z.string().regex(/^\d{5}$/, 'ZIP code must be 5 digits'),
  }),
});
```

### Server-Side Validation & Error Handling
```typescript
export const action = async ({ request }: ActionFunctionArgs) => {
  const { data, errors } = await getValidatedFormData<FormData>(
    request, 
    zodResolver(formSchema)
  );

  // Return validation errors
  if (errors) {
    return { errors };
  }

  // Additional server-side validation
  const existingUser = await getUserByEmail(data.email);
  if (existingUser) {
    return {
      errors: {
        email: { message: 'Email address is already registered' }
      }
    };
  }

  // Process successful submission
  try {
    await createUser(data);
    return { 
      message: 'Account created successfully!',
      redirectTo: '/dashboard' 
    };
  } catch (error) {
    return { 
      errors: { 
        _form: { message: 'Failed to create account. Please try again.' }
      }
    };
  }
};
```

## Success Handling & Redirects

### Success Messages

Display success messages from server responses:

```typescript
// In your component
{fetcher.data?.message && (
  <div className="mt-4 p-4 bg-green-50 border border-green-200 rounded-md">
    <p className="text-green-700 font-medium">{fetcher.data.message}</p>
  </div>
)}

// Error messages
{fetcher.data?.errors?._form && (
  <div className="mt-4 p-4 bg-red-50 border border-red-200 rounded-md">
    <p className="text-red-700 font-medium">{fetcher.data.errors._form.message}</p>
  </div>
)}
```

### Programmatic Redirects

**Client-side redirect handling:**
```typescript
import { useNavigate } from 'react-router';

const MyForm = () => {
  const navigate = useNavigate();
  const fetcher = useFetcher();

  // Handle redirect from server response
  useEffect(() => {
    if (fetcher.data?.redirectTo) {
      navigate(fetcher.data.redirectTo);
    }
  }, [fetcher.data?.redirectTo, navigate]);

  // ... rest of component
};
```

**Server-side redirect:**
```typescript
import { redirect } from 'react-router';

export const action = async ({ request }: ActionFunctionArgs) => {
  // ... validation and processing
  
  // Redirect after successful submission
  return redirect('/success');
};
```

### Optimistic UI Updates

Show immediate feedback while form is submitting:

```typescript
import { useState, useEffect } from 'react';

const MyForm = () => {
  const fetcher = useFetcher();
  const [optimisticMessage, setOptimisticMessage] = useState('');

  const handleSubmit = (data: FormData) => {
    // Show optimistic message immediately
    setOptimisticMessage('Saving...');
    
    // Submit form
    methods.handleSubmit();
  };

  useEffect(() => {
    if (fetcher.state === 'idle' && fetcher.data) {
      setOptimisticMessage('');
    }
  }, [fetcher.state, fetcher.data]);

  return (
    <RemixFormProvider {...methods}>
      <fetcher.Form onSubmit={handleSubmit}>
        {/* Form fields */}
        
        {optimisticMessage && <p className="text-blue-600">{optimisticMessage}</p>}
        {fetcher.data?.message && <p className="text-green-600">{fetcher.data.message}</p>}
      </fetcher.Form>
    </RemixFormProvider>
  );
};
```

## Complete Form Example

Here's a comprehensive example demonstrating all major features:

```typescript
import { zodResolver } from '@hookform/resolvers/zod';
import { 
  TextField, 
  Textarea, 
  Checkbox, 
  RadioGroup, 
  DatePicker,
  DropdownMenuSelect 
} from '@lambdacurry/forms';
import { Button } from '@lambdacurry/forms/ui';
import { DropdownMenuSelectItem } from '@lambdacurry/forms/ui';
import { RemixFormProvider, useRemixForm, getValidatedFormData, createFormData } from 'remix-hook-form';
import { useFetcher, type ActionFunctionArgs } from 'react-router';
import { z } from 'zod';

// Comprehensive form schema
const formSchema = z.object({
  // Personal Information
  firstName: z.string().min(2, 'First name must be at least 2 characters'),
  lastName: z.string().min(2, 'Last name must be at least 2 characters'),
  email: z.string().email('Please enter a valid email address'),
  birthDate: z.coerce.date({
    required_error: 'Please select your birth date',
  }),
  
  // Preferences
  accountType: z.enum(['personal', 'business'], {
    required_error: 'Please select an account type',
  }),
  notifications: z.boolean().default(false),
  newsletter: z.boolean().default(false),
  
  // Additional Info
  bio: z.string().min(10, 'Bio must be at least 10 characters').optional(),
  country: z.string({
    required_error: 'Please select your country',
  }),
  
  // Terms
  terms: z.boolean().refine(val => val === true, 'You must accept the terms'),
});

type FormData = z.infer<typeof formSchema>;

const ComprehensiveForm = () => {
  const fetcher = useFetcher<{ 
    message: string; 
    errors?: Record<string, { message: string }>;
    redirectTo?: string;
  }>();
  
  const methods = useRemixForm<FormData>({
    resolver: zodResolver(formSchema),
    defaultValues: {
      firstName: '',
      lastName: '',
      email: '',
      birthDate: undefined,
      accountType: undefined,
      notifications: false,
      newsletter: false,
      bio: '',
      country: '',
      terms: false,
    },
    fetcher,
    submitConfig: {
      action: '/register',
      method: 'post',
    },
    submitHandlers: {
      onValid: (data) => {
        // Transform data before submission
        const transformedData = {
          ...data,
          fullName: `${data.firstName} ${data.lastName}`,
          registrationDate: new Date().toISOString(),
        };

        fetcher.submit(
          createFormData(transformedData),
          {
            method: 'post',
            action: '/register',
          }
        );
      },
    },
  });

  const watchAccountType = methods.watch('accountType');
  const isSubmitting = fetcher.state === 'submitting';

  return (
    <RemixFormProvider {...methods}>
      <fetcher.Form onSubmit={methods.handleSubmit} className="max-w-2xl mx-auto p-6 space-y-6">
        <h1 className="text-2xl font-bold text-gray-900">Create Account</h1>
        
        {/* Personal Information Section */}
        <div className="space-y-4">
          <h2 className="text-lg font-semibold text-gray-800">Personal Information</h2>
          
          <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
            <TextField
              name="firstName"
              label="First Name"
              placeholder="Enter your first name"
              disabled={isSubmitting}
            />
            <TextField
              name="lastName"
              label="Last Name"
              placeholder="Enter your last name"
              disabled={isSubmitting}
            />
          </div>
          
          <TextField
            name="email"
            type="email"
            label="Email Address"
            placeholder="Enter your email"
            description="We'll use this to send you important updates"
            disabled={isSubmitting}
          />
          
          <DatePicker
            name="birthDate"
            label="Date of Birth"
            description="You must be 18 or older to register"
            disabled={isSubmitting}
          />
        </div>

        {/* Account Preferences */}
        <div className="space-y-4">
          <h2 className="text-lg font-semibold text-gray-800">Account Preferences</h2>
          
          <RadioGroup
            name="accountType"
            label="Account Type"
            description="Choose the type of account you want to create"
            options={[
              { value: 'personal', label: 'Personal Account' },
              { value: 'business', label: 'Business Account' },
            ]}
            disabled={isSubmitting}
          />
          
          {/* Conditional field based on account type */}
          {watchAccountType === 'business' && (
            <TextField
              name="companyName"
              label="Company Name"
              placeholder="Enter your company name"
              description="This will appear on your business profile"
              disabled={isSubmitting}
            />
          )}
          
          <DropdownMenuSelect
            name="country"
            label="Country"
            description="Select your country of residence"
            disabled={isSubmitting}
          >
            <DropdownMenuSelectItem value="us">United States</DropdownMenuSelectItem>
            <DropdownMenuSelectItem value="ca">Canada</DropdownMenuSelectItem>
            <DropdownMenuSelectItem value="uk">United Kingdom</DropdownMenuSelectItem>
            <DropdownMenuSelectItem value="au">Australia</DropdownMenuSelectItem>
          </DropdownMenuSelect>
        </div>

        {/* Additional Information */}
        <div className="space-y-4">
          <h2 className="text-lg font-semibold text-gray-800">Additional Information</h2>
          
          <Textarea
            name="bio"
            label="Bio (Optional)"
            placeholder="Tell us a bit about yourself..."
            description="This will appear on your public profile"
            rows={4}
            disabled={isSubmitting}
          />
        </div>

        {/* Notifications & Terms */}
        <div className="space-y-4">
          <h2 className="text-lg font-semibold text-gray-800">Preferences & Terms</h2>
          
          <div className="space-y-3">
            <Checkbox
              name="notifications"
              label="Enable email notifications"
              description="Receive updates about your account and new features"
              disabled={isSubmitting}
            />
            
            <Checkbox
              name="newsletter"
              label="Subscribe to newsletter"
              description="Get weekly tips and product updates"
              disabled={isSubmitting}
            />
            
            <Checkbox
              name="terms"
              label="I accept the Terms of Service and Privacy Policy"
              description="Required to create an account"
              disabled={isSubmitting}
            />
          </div>
        </div>

        {/* Submit Button & Status */}
        <div className="pt-6">
          {/* Form-level errors appear below inputs, above submit button */}
          <FormError className="mb-4" />
          
          <Button 
            type="submit" 
            disabled={isSubmitting}
            className="w-full"
          >
            {isSubmitting ? 'Creating Account...' : 'Create Account'}
          </Button>
          
          {/* Success Message */}
          {fetcher.data?.message && (
            <div className="mt-4 p-4 bg-green-50 border border-green-200 rounded-md">
              <p className="text-green-700 font-medium">{fetcher.data.message}</p>
            </div>
          )}
        </div>
      </fetcher.Form>
    </RemixFormProvider>
  );
};

// Server action handler
export const action = async ({ request }: ActionFunctionArgs) => {
  const { data, errors } = await getValidatedFormData<FormData>(
    request, 
    zodResolver(formSchema)
  );

  if (errors) {
    return { errors };
  }

  // Additional server-side validation
  const existingUser = await getUserByEmail(data.email);
  if (existingUser) {
    return {
      errors: {
        email: { message: 'This email address is already registered' }
      }
    };
  }

  try {
    // Create user account
    const user = await createUser({
      firstName: data.firstName,
      lastName: data.lastName,
      email: data.email,
      birthDate: data.birthDate,
      accountType: data.accountType,
      country: data.country,
      bio: data.bio,
      preferences: {
        notifications: data.notifications,
        newsletter: data.newsletter,
      },
    });

    return { 
      message: 'Account created successfully! Welcome aboard!',
      redirectTo: '/dashboard'
    };
  } catch (error) {
    console.error('Account creation failed:', error);
    return { 
      errors: { 
        _form: { message: 'Failed to create account. Please try again.' }
      }
    };
  }
};

export default ComprehensiveForm;
```

**This example demonstrates:**
- ✅ All major form components (TextField, Textarea, Checkbox, RadioGroup, DatePicker, DropdownMenuSelect)
- ✅ Complex validation with Zod schemas
- ✅ Conditional field display based on form values
- ✅ Custom submit handlers with data transformation
- ✅ Loading states and disabled inputs during submission
- ✅ Error handling for both client and server-side validation
- ✅ Success messages and redirect handling
- ✅ Responsive layout with proper spacing and styling
- ✅ Accessibility features built-in to all components

This comprehensive example serves as a complete reference for implementing any form using the LambdaCurry Forms library!

---

## Key Implementation Notes for LLMs

### Essential Patterns to Follow:

1. **Form Provider Setup**
   ```typescript
   <RemixFormProvider {...methods}>
     <fetcher.Form onSubmit={methods.handleSubmit}>
       {/* Form components */}
     </fetcher.Form>
   </RemixFormProvider>
   ```

2. **Error Handling**
   - Errors display automatically via `FormMessage` component
   - Server errors: `return { errors }` from action
   - Field-specific: `errors.fieldName.message`
   - Form-level: `errors._form.message`

3. **Loading States**
   ```typescript
   const isSubmitting = fetcher.state === 'submitting';
   <TextField disabled={isSubmitting} />
   <Button disabled={isSubmitting}>
     {isSubmitting ? 'Submitting...' : 'Submit'}
   </Button>
   ```

4. **Conditional Fields**
   ```typescript
   const watchValue = methods.watch('fieldName');
   {watchValue === 'condition' && <TextField name="conditionalField" />}
   ```

5. **Data Transformation**
   ```typescript
   submitHandlers: {
     onValid: (data) => {
       const transformed = { ...data, computed: 'value' };
       fetcher.submit(createFormData(transformed), { method: 'post' });
     }
   }
   ```

6. **Server Validation**
   ```typescript
   export const action = async ({ request }) => {
     const { data, errors } = await getValidatedFormData(request, zodResolver(schema));
     if (errors) return { errors };
     // Process data...
   };
   ```

7. **FormError Placement Options**
   ```typescript
   // Below inputs, above submit button (most common)
   <FormError className="mb-4" />
   
   // Between sections
   <FormError className="my-4 text-center" />
   
   // Top of form (for critical errors that need immediate attention)
   <FormError className="mb-4" />
   
   // Multiple placements with different styling
   <FormError className="mb-4 p-3 bg-red-50 rounded" />
   <FormError className="mt-4 text-sm text-red-600" />
   ```

8. **Custom FormError Styling**
   ```typescript
   const CustomErrorMessage = (props: React.ComponentPropsWithoutRef<typeof FormMessage>) => (
     <div className="alert alert-error">
       <AlertIcon />
       <FormMessage {...props} />
     </div>
   );
   
   <FormError 
     components={{
       FormMessage: CustomErrorMessage,
     }}
   />
   ```

9. **Server Action Error Patterns**
   ```typescript
   // Field-level error
   return {
     errors: {
       email: { message: 'Email already exists' }
     }
   };
   
   // Form-level error
   return {
     errors: {
       _form: { message: 'Server error occurred' }
     }
   };
   
   // Multiple error types
   return {
     errors: {
       email: { message: 'Email already exists' },
       _form: { message: 'Please fix the errors above' }
     }
   };
   ```

## FormError Best Practices

### 1. Error Key Conventions
- Use `_form` for general form-level errors
- Use descriptive keys for specific categories (`payment`, `shipping`, `auth`)
- Be consistent across your application

### 2. Error Message Guidelines
- **Be specific**: "Server temporarily unavailable" vs "Error occurred"
- **Be actionable**: "Please try again in a few minutes" vs "Failed"
- **Be user-friendly**: Avoid technical jargon and error codes

### 3. Placement Strategy
- **Below inputs, above submit button**: Most common placement - users see errors after completing form fields but before submitting
- **Top placement**: For critical errors that need immediate attention before users start filling the form
- **Inline placement**: For contextual errors related to specific sections
- **Multiple placements**: FormError can be placed anywhere in the form and styled differently for various use cases

### 4. Component Integration
- FormError works seamlessly with all existing form components
- Maintains the same component override pattern as other form components
- Automatically integrates with form context and validation state

### Important Reminders:
- 🔥 **Import form-aware components from `@lambdacurry/forms`** - these automatically integrate with form context
- 🔥 **Import UI components from `@lambdacurry/forms/ui`** - these are the underlying UI primitives
- 🔥 **Use `createFormData()` for custom submissions** to ensure proper formatting
- 🔥 **All components are accessible by default** - no additional ARIA setup needed
- 🔥 **Form context is automatic** - no need to pass `control` props manually
- 🔥 **FormError provides form-level error handling** - use it for server errors, auth failures, and general business logic errors

This comprehensive guide provides everything needed to implement forms with both field-level and form-level error handling using the LambdaCurry Forms library!