@delightui/components 0.1.161 → 0.1.162-alpha.0

package/docs/components/organisms/Form.md

@@ -1,68 +1,84 @@
 # Form
 
+> **⚠️ BREAKING CHANGES:** The Form component has been rewritten using React Hook Form. See the [Migration Guide](../../../FORM_MIGRATION_GUIDE.md) for detailed migration instructions.
+
 ## Description
 
-A comprehensive form management component that provides state management, validation, error handling, and submission workflows. Built with TypeScript for type safety and supports both controlled and uncontrolled form patterns with extensive validation capabilities.
+A comprehensive form management component built on **React Hook Form** that provides state management, validation, error handling, and submission workflows. Features TypeScript support, autosave functionality, async validation, and seamless integration with the FormField component.
 
 ## Aliases
 
 - Form
-- FormProvider
-- FormContainer
-- FormWrapper
 
 ## Props Breakdown
 
-**Extends:** `FormHTMLAttributes<HTMLFormElement>` (excluding `onSubmit`)
-
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
-| `formRef` | `Ref<HTMLFormElement>` | - | No | Reference to the form element |
-| `children` | `ReactNode` | - | No | Form fields and content |
-| `formState` | `FormState` | - | No | Initial form state values |
-| `onFormStateChange` | `FormStateChangeHandler` | - | No | Callback when form state changes |
-| `formValidator` | `FormValidator` | - | No | Function to validate entire form |
-| `onSubmit` | `FormSubmitHandler` | - | No | Form submission handler |
-| `validateOnChange` | `boolean` | - | No | Whether to validate on field changes |
+| `children` | `ReactNode` | - | Yes | Form fields and content |
+| `defaultValues` | `object` | - | No | Initial form values (uncontrolled mode) |
+| `onSubmit` | `(values: TFormValues) => void \| Promise<void>` | - | No | Form submission handler (no setError callback) |
 | `autosave` | `boolean` | `false` | No | Enable automatic form submission on value changes |
-| `autosaveDelayMs` | `number` | - | No | Delay in milliseconds before autosave triggers |
+| `autosaveDelayMs` | `number` | `1000` | No | Debounce delay in milliseconds before autosave triggers |
+| `mode` | `'onSubmit' \| 'onChange' \| 'onBlur' \| 'onTouched' \| 'all'` | `'onSubmit'` | No | React Hook Form validation mode |
+| `formOptions` | `UseFormProps` | - | No | Additional React Hook Form options |
+| `formRef` | `Ref<HTMLFormElement>` | - | No | Reference to the form element |
+| `className` | `string` | - | No | CSS class for the form element |
+| `style` | `CSSProperties` | - | No | Inline styles for the form element |
+
+### Removed Props (Breaking Changes)
+
+| OLD Prop | Migration Path |
+|----------|----------------|
+| `formState` | Use `defaultValues` instead |
+| `onFormStateChange` | Use RHF's `watch()` or `useWatch()` hooks |
+| `formValidator` | Use field-level validation or RHF resolver |
+| `validateOnChange` | Use `mode="onChange"` instead |
+
+### Key Differences from Old API
 
-Plus all standard HTML form attributes (method, action, encType, target, etc.) except `onSubmit`.
+- ✅ **`onSubmit`** now receives only `values` (no `setError` callback)
+- ✅ **`defaultValues`** replaces `formState` for initial values
+- ✅ **`mode`** prop provides flexible validation timing
+- ✅ Full React Hook Form ecosystem access via hooks
+- ✅ Better TypeScript type safety
+- ✅ Improved performance and smaller bundle size
 
 ## Examples
 
 ### Basic Form
 ```tsx
-import { Form, FormField, Input, Button } from '@delightui/components';
+import { Form, FormField, Input, Button, TextArea } from '@delightui/components';
 
 function BasicFormExample() {
-  const handleSubmit = (values, setError) => {
+  const handleSubmit = (values: { name: string; email: string; message: string }) => {
     console.log('Form submitted:', values);
-    
-    // Example validation
-    if (!values.email || !values.email.includes('@')) {
-      setError('email', 'Please enter a valid email address');
-      return;
-    }
-    
-    // Process form submission
     alert('Form submitted successfully!');
   };
 
+  const validateEmail = (value: string) => {
+    if (!value.includes('@')) {
+      return 'Please enter a valid email address';
+    }
+    return undefined;
+  };
+
   return (
-    <Form onSubmit={handleSubmit}>
+    <Form
+      defaultValues={{ name: '', email: '', message: '' }}
+      onSubmit={handleSubmit}
+    >
       <FormField name="name" label="Full Name" required>
         <Input placeholder="Enter your name" />
       </FormField>
-      
-      <FormField name="email" label="Email Address" required>
+
+      <FormField name="email" label="Email Address" required validate={validateEmail}>
         <Input inputType="Email" placeholder="Enter your email" />
       </FormField>
-      
+
       <FormField name="message" label="Message">
         <TextArea placeholder="Your message..." rows={4} />
       </FormField>
-      
+
       <Button actionType="submit">Submit Form</Button>
     </Form>
   );
@@ -71,115 +87,127 @@ function BasicFormExample() {
 
 ### Form with Validation
 ```tsx
-function ValidationFormExample() {
-  const handleSubmit = (values, setError) => {
-    // Custom validation logic
-    let hasErrors = false;
-    
-    if (!values.password || values.password.length < 8) {
-      setError('password', 'Password must be at least 8 characters');
-      hasErrors = true;
-    }
-    
-    if (values.password !== values.confirmPassword) {
-      setError('confirmPassword', 'Passwords do not match');
-      hasErrors = true;
+import { useWatch } from 'react-hook-form';
+
+function ConfirmPasswordField() {
+  const password = useWatch({ name: 'password' });
+
+  const validateConfirm = (value: string) => {
+    if (value !== password) {
+      return 'Passwords do not match';
     }
-    
-    if (!hasErrors) {
-      console.log('Creating account:', values);
+    return undefined;
+  };
+
+  return (
+    <FormField
+      name="confirmPassword"
+      label="Confirm Password"
+      required
+      validate={validateConfirm}
+    >
+      <Input inputType="Password" placeholder="Confirm password" />
+    </FormField>
+  );
+}
+
+function ValidationFormExample() {
+  const handleSubmit = (values: { username: string; email: string; password: string; confirmPassword: string }) => {
+    console.log('Creating account:', values);
+  };
+
+  const validateUsername = (value: string) => {
+    if (value.length < 3) {
+      return 'Username must be at least 3 characters';
     }
+    return undefined;
   };
 
-  const formValidator = (values, setError) => {
-    let isValid = true;
-    
-    // Username validation
-    if (!values.username || values.username.length < 3) {
-      setError('username', 'Username must be at least 3 characters');
-      isValid = false;
+  const validateEmail = (value: string) => {
+    if (!/\S+@\S+\.\S+/.test(value)) {
+      return 'Please enter a valid email';
     }
-    
-    // Email validation
-    if (!values.email || !/\S+@\S+\.\S+/.test(values.email)) {
-      setError('email', 'Please enter a valid email');
-      isValid = false;
+    return undefined;
+  };
+
+  const validatePassword = (value: string) => {
+    if (value.length < 8) {
+      return 'Password must be at least 8 characters';
     }
-    
-    return isValid;
+    return undefined;
   };
 
   return (
-    <Form 
+    <Form
+      defaultValues={{ username: '', email: '', password: '', confirmPassword: '' }}
       onSubmit={handleSubmit}
-      formValidator={formValidator}
-      validateOnChange={true}
+      mode="onChange" // Validate on every change
     >
-      <FormField name="username" label="Username" required>
+      <FormField name="username" label="Username" required validate={validateUsername}>
         <Input placeholder="Choose a username" />
       </FormField>
-      
-      <FormField name="email" label="Email" required>
+
+      <FormField name="email" label="Email" required validate={validateEmail}>
         <Input inputType="Email" placeholder="your@email.com" />
       </FormField>
-      
-      <FormField name="password" label="Password" required>
+
+      <FormField name="password" label="Password" required validate={validatePassword}>
         <Input inputType="Password" placeholder="Create password" />
       </FormField>
-      
-      <FormField name="confirmPassword" label="Confirm Password" required>
-        <Input inputType="Password" placeholder="Confirm password" />
-      </FormField>
-      
+
+      <ConfirmPasswordField />
+
       <div className="form-actions">
         <Button actionType="submit">Create Account</Button>
-        <Button type="Outlined" actionType="reset">Clear Form</Button>
       </div>
     </Form>
   );
 }
 ```
 
-### Form with Initial State
+### Form with Initial Values
 ```tsx
 function InitialStateFormExample() {
-  const initialFormState = {
-    firstName: 'John',
-    lastName: 'Doe',
-    email: 'john.doe@example.com',
-    role: 'developer',
-    notifications: true
-  };
-
-  const handleSubmit = (values, setError) => {
+  const handleSubmit = (values: {
+    firstName: string;
+    lastName: string;
+    email: string;
+    role: string;
+    notifications: boolean;
+  }) => {
     console.log('Updated profile:', values);
   };
 
-  const handleStateChange = (state, setError) => {
-    // Validate on state change
-    if (state.email && !state.email.includes('@')) {
-      setError('email', 'Invalid email format');
+  const validateEmail = (value: string) => {
+    if (!value.includes('@')) {
+      return 'Invalid email format';
     }
+    return undefined;
   };
 
   return (
-    <Form 
-      formState={initialFormState}
+    <Form
+      defaultValues={{
+        firstName: 'John',
+        lastName: 'Doe',
+        email: 'john.doe@example.com',
+        role: 'developer',
+        notifications: true
+      }}
       onSubmit={handleSubmit}
-      onFormStateChange={handleStateChange}
     >
       <FormField name="firstName" label="First Name" required>
         <Input />
       </FormField>
-      
+
       <FormField name="lastName" label="Last Name" required>
         <Input />
       </FormField>
-      
-      <FormField name="email" label="Email" required>
+
+      <FormField name="email" label="Email" required validate={validateEmail}>
         <Input inputType="Email" />
       </FormField>
-      
+
       <FormField name="role" label="Role">
         <Select>
           <Option value="developer">Developer</Option>
@@ -187,11 +215,11 @@ function InitialStateFormExample() {
           <Option value="manager">Manager</Option>
         </Select>
       </FormField>
-      
+
       <FormField name="notifications" label="Email Notifications">
         <Checkbox>Send me email notifications</Checkbox>
       </FormField>
-      
+
       <Button actionType="submit">Update Profile</Button>
     </Form>
   );
@@ -536,24 +564,24 @@ function AsyncFormExample() {
 
 ### Autosave Form
 ```tsx
+import { useState } from 'react';
+
 function AutosaveFormExample() {
   const [saveCount, setSaveCount] = useState(0);
-  const [lastSaved, setLastSaved] = useState(null);
+  const [lastSaved, setLastSaved] = useState<string | null>(null);
 
-  const handleSubmit = async (values, setError) => {
+  const handleAutosave = async (values: { title: string; content: string }) => {
     try {
       // Simulate API call to save draft
-      const response = await fetch('/api/drafts', {
+      await fetch('/api/drafts', {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify(values)
       });
-      
-      if (response.ok) {
-        setSaveCount(prev => prev + 1);
-        setLastSaved(new Date().toLocaleTimeString());
-        console.log('Draft auto-saved:', values);
-      }
+
+      setSaveCount(prev => prev + 1);
+      setLastSaved(new Date().toLocaleTimeString());
+      console.log('Draft auto-saved:', values);
     } catch (error) {
       console.error('Failed to save draft:', error);
     }
@@ -561,29 +589,23 @@ function AutosaveFormExample() {
 
   return (
     <div>
-      <Form 
-        onSubmit={handleSubmit}
+      <Form
+        defaultValues={{ title: '', content: '' }}
+        onSubmit={handleAutosave}
         autosave={true}
         autosaveDelayMs={2000} // Wait 2 seconds after user stops typing
       >
         <FormField name="title" label="Title">
           <Input placeholder="Enter title" />
         </FormField>
-        
+
         <FormField name="content" label="Content">
-          <TextArea 
-            placeholder="Start writing..." 
-            rows={10} 
-          />
-        </FormField>
-        
-        <FormField name="tags" label="Tags">
-          <ChipInput 
-            placeholder="Add tags" 
-            options={['react', 'typescript', 'design', 'tutorial']}
+          <TextArea
+            placeholder="Start writing..."
+            rows={10}
           />
         </FormField>
-        
+
         {lastSaved && (
           <Text type="BodySmall">
             Auto-saved {saveCount} times. Last saved at {lastSaved}
@@ -595,66 +617,740 @@ function AutosaveFormExample() {
 }
 ```
 
-### Autosave with Manual Submit
+### Async Validation
 ```tsx
-function AutosaveWithManualSubmitExample() {
-  const [isDraft, setIsDraft] = useState(true);
+function AsyncValidationExample() {
+  const validateUsername = async (value: string) => {
+    if (!value) return 'Username is required';
 
-  const handleAutosave = (values, setError) => {
-    if (isDraft) {
-      console.log('Draft auto-saved:', values);
-      // Save to local storage or draft API
-      localStorage.setItem('formDraft', JSON.stringify(values));
+    // Simulate API call
+    const response = await fetch(`/api/check-username?username=${value}`);
+    const { available } = await response.json();
+
+    if (!available) {
+      return 'Username is already taken';
     }
+    return undefined;
   };
 
-  const handlePublish = () => {
-    setIsDraft(false);
-    // Form will now submit normally
+  const handleSubmit = (values: { username: string; email: string }) => {
+    console.log('Account created:', values);
   };
 
   return (
-    <Form 
-      onSubmit={handleAutosave}
-      autosave={isDraft}
-      autosaveDelayMs={1000}
-      formState={{
-        title: localStorage.getItem('formDraft')?.title || '',
-        content: localStorage.getItem('formDraft')?.content || ''
+    <Form
+      defaultValues={{ username: '', email: '' }}
+      onSubmit={handleSubmit}
+    >
+      <FormField
+        name="username"
+        label="Username"
+        required
+        asyncValidate={validateUsername}
+      >
+        <Input placeholder="Choose a username" />
+      </FormField>
+
+      <FormField name="email" label="Email" required>
+        <Input inputType="Email" placeholder="your@email.com" />
+      </FormField>
+
+      <Button actionType="submit">Create Account</Button>
+    </Form>
+  );
+}
+```
+
+### Using React Hook Form Hooks
+```tsx
+import { useFormContext, useWatch } from 'react-hook-form';
+
+function FormDebugger() {
+  const { formState } = useFormContext();
+  const watchedValues = useWatch();
+
+  return (
+    <div style={{ padding: '10px', background: '#f0f0f0', marginTop: '10px' }}>
+      <Text type="BodySmall">
+        Form is {formState.isDirty ? 'modified' : 'pristine'}
+      </Text>
+      <Text type="BodySmall">
+        Form is {formState.isValid ? 'valid' : 'invalid'}
+      </Text>
+      <pre>{JSON.stringify(watchedValues, null, 2)}</pre>
+    </div>
+  );
+}
+
+function FormWithHooksExample() {
+  const handleSubmit = (values: { email: string; password: string }) => {
+    console.log('Submitted:', values);
+  };
+
+  return (
+    <Form
+      defaultValues={{ email: '', password: '' }}
+      onSubmit={handleSubmit}
+      mode="onChange"
+    >
+      <FormField name="email" label="Email" required>
+        <Input inputType="Email" />
+      </FormField>
+
+      <FormField name="password" label="Password" required>
+        <Input inputType="Password" />
+      </FormField>
+
+      <Button actionType="submit">Sign In</Button>
+
+      <FormDebugger />
+    </Form>
+  );
+}
+```
+
+### Tracking Dirty Fields
+```tsx
+import { useFormContext } from 'react-hook-form';
+
+function DirtyFieldsExample() {
+  const handleSubmit = (values: { name: string; email: string; phone: string }) => {
+    console.log('Submitted:', values);
+  };
+
+  return (
+    <Form
+      defaultValues={{ name: 'John Doe', email: 'john@example.com', phone: '' }}
+      onSubmit={handleSubmit}
+    >
+      <FormField name="name" label="Name" required>
+        <Input />
+      </FormField>
+
+      <FormField name="email" label="Email" required>
+        <Input inputType="Email" />
+      </FormField>
+
+      <FormField name="phone" label="Phone">
+        <Input inputType="Tel" />
+      </FormField>
+
+      <DirtyFieldsIndicator />
+
+      <Button actionType="submit">Save Changes</Button>
+    </Form>
+  );
+}
+
+function DirtyFieldsIndicator() {
+  const { formState } = useFormContext();
+  const { dirtyFields, isDirty } = formState;
+
+  if (!isDirty) {
+    return (
+      <div style={{ padding: '10px', background: '#e8f5e9', marginTop: '10px' }}>
+        <Text type="BodySmall">No changes made</Text>
+      </div>
+    );
+  }
+
+  const changedFields = Object.keys(dirtyFields).filter(key => dirtyFields[key]);
+
+  return (
+    <div style={{ padding: '10px', background: '#fff3e0', marginTop: '10px' }}>
+      <Text type="BodySmall" weight="SemiBold">
+        Modified fields: {changedFields.join(', ')}
+      </Text>
+      <Text type="BodySmall">
+        You have unsaved changes in {changedFields.length} field(s)
+      </Text>
+    </div>
+  );
+}
+```
+
+### Server-Side Error Handling
+```tsx
+import { useFormContext } from 'react-hook-form';
+
+function ServerValidationExample() {
+  const [isSubmitting, setIsSubmitting] = useState(false);
+
+  const handleSubmit = async (values: { email: string; username: string }) => {
+    setIsSubmitting(true);
+
+    try {
+      const response = await fetch('/api/register', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(values)
+      });
+
+      const data = await response.json();
+
+      if (!response.ok) {
+        // Server returned validation errors
+        throw data;
+      }
+
+      alert('Registration successful!');
+    } catch (error: any) {
+      // Handle server-side validation errors
+      // Error format: { field: 'email', message: 'Email already exists' }
+      console.error('Server validation error:', error);
+    } finally {
+      setIsSubmitting(false);
+    }
+  };
+
+  return (
+    <Form
+      defaultValues={{ email: '', username: '' }}
+      onSubmit={handleSubmit}
+    >
+      <FormField name="email" label="Email" required>
+        <Input inputType="Email" />
+      </FormField>
+
+      <FormField name="username" label="Username" required>
+        <Input />
+      </FormField>
+
+      <ServerErrorHandler />
+
+      <Button actionType="submit" loading={isSubmitting}>
+        Register
+      </Button>
+    </Form>
+  );
+}
+
+function ServerErrorHandler() {
+  const { setError, clearErrors } = useFormContext();
+
+  // Example: You could expose a method to set errors from parent
+  // or handle them via a context/state management solution
+
+  const handleServerError = (field: string, message: string) => {
+    setError(field, {
+      type: 'server',
+      message: message
+    });
+  };
+
+  const handleClearErrors = () => {
+    clearErrors(); // Clear all errors
+    // or clearErrors('email'); // Clear specific field
+  };
+
+  return null; // This is a utility component
+}
+```
+
+### Dynamic Form Arrays (useFieldArray)
+```tsx
+import { useFieldArray, useFormContext } from 'react-hook-form';
+
+interface FormValues {
+  name: string;
+  emails: { value: string }[];
+}
+
+function DynamicFieldArrayExample() {
+  const handleSubmit = (values: FormValues) => {
+    console.log('Submitted:', values);
+    alert(`Name: ${values.name}\nEmails: ${values.emails.map(e => e.value).join(', ')}`);
+  };
+
+  return (
+    <Form<FormValues>
+      defaultValues={{
+        name: '',
+        emails: [{ value: '' }] // Start with one email field
       }}
+      onSubmit={handleSubmit}
     >
-      <FormField name="title" label="Article Title" required>
-        <Input placeholder="Enter title" />
+      <FormField name="name" label="Name" required>
+        <Input placeholder="Enter your name" />
       </FormField>
-      
-      <FormField name="content" label="Article Content" required>
-        <TextArea placeholder="Write your article..." rows={15} />
+
+      <EmailFieldArray />
+
+      <Button actionType="submit">Submit</Button>
+    </Form>
+  );
+}
+
+function EmailFieldArray() {
+  const { control } = useFormContext();
+  const { fields, append, remove } = useFieldArray({
+    control,
+    name: 'emails'
+  });
+
+  return (
+    <div>
+      <Text type="BodyMedium" weight="SemiBold">Email Addresses</Text>
+
+      {fields.map((field, index) => (
+        <div key={field.id} style={{ display: 'flex', gap: '8px', marginTop: '8px' }}>
+          <FormField
+            name={`emails.${index}.value` as any}
+            label={`Email ${index + 1}`}
+            required
+          >
+            <Input inputType="Email" placeholder="email@example.com" />
+          </FormField>
+
+          {fields.length > 1 && (
+            <Button
+              type="Ghost"
+              style="Destructive"
+              size="Small"
+              onClick={() => remove(index)}
+            >
+              Remove
+            </Button>
+          )}
+        </div>
+      ))}
+
+      <Button
+        type="Ghost"
+        size="Small"
+        onClick={() => append({ value: '' })}
+        style={{ marginTop: '8px' }}
+      >
+        Add Email
+      </Button>
+    </div>
+  );
+}
+```
+
+### Conditional Validation
+```tsx
+import { useWatch } from 'react-hook-form';
+
+function ConditionalValidationExample() {
+  const handleSubmit = (values: { contactMethod: string; email?: string; phone?: string }) => {
+    console.log('Submitted:', values);
+  };
+
+  return (
+    <Form
+      defaultValues={{ contactMethod: 'email', email: '', phone: '' }}
+      onSubmit={handleSubmit}
+    >
+      <FormField name="contactMethod" label="Preferred Contact Method">
+        <Select>
+          <Option value="email">Email</Option>
+          <Option value="phone">Phone</Option>
+          <Option value="both">Both</Option>
+        </Select>
       </FormField>
-      
-      <FormField name="category" label="Category">
+
+      <ConditionalFields />
+
+      <Button actionType="submit">Submit</Button>
+    </Form>
+  );
+}
+
+function ConditionalFields() {
+  const contactMethod = useWatch({ name: 'contactMethod' });
+
+  const validateEmail = (value: string) => {
+    if ((contactMethod === 'email' || contactMethod === 'both') && !value) {
+      return 'Email is required for your selected contact method';
+    }
+    if (value && !value.includes('@')) {
+      return 'Invalid email format';
+    }
+    return undefined;
+  };
+
+  const validatePhone = (value: string) => {
+    if ((contactMethod === 'phone' || contactMethod === 'both') && !value) {
+      return 'Phone is required for your selected contact method';
+    }
+    return undefined;
+  };
+
+  return (
+    <>
+      {(contactMethod === 'email' || contactMethod === 'both') && (
+        <FormField
+          name="email"
+          label="Email"
+          required={contactMethod === 'email' || contactMethod === 'both'}
+          validate={validateEmail}
+        >
+          <Input inputType="Email" placeholder="your@email.com" />
+        </FormField>
+      )}
+
+      {(contactMethod === 'phone' || contactMethod === 'both') && (
+        <FormField
+          name="phone"
+          label="Phone"
+          required={contactMethod === 'phone' || contactMethod === 'both'}
+          validate={validatePhone}
+        >
+          <Input inputType="Tel" placeholder="(555) 123-4567" />
+        </FormField>
+      )}
+    </>
+  );
+}
+```
+
+### Reset with Specific Values
+```tsx
+import { useFormContext } from 'react-hook-form';
+
+function ResetWithValuesExample() {
+  const savedData = {
+    name: 'John Doe',
+    email: 'john@example.com',
+    bio: 'Software developer'
+  };
+
+  const handleSubmit = (values: typeof savedData) => {
+    console.log('Saved:', values);
+    alert('Profile updated!');
+  };
+
+  return (
+    <Form
+      defaultValues={savedData}
+      onSubmit={handleSubmit}
+    >
+      <FormField name="name" label="Name" required>
+        <Input />
+      </FormField>
+
+      <FormField name="email" label="Email" required>
+        <Input inputType="Email" />
+      </FormField>
+
+      <FormField name="bio" label="Bio">
+        <TextArea rows={4} />
+      </FormField>
+
+      <ResetButtons savedData={savedData} />
+
+      <Button actionType="submit">Save Changes</Button>
+    </Form>
+  );
+}
+
+function ResetButtons({ savedData }: { savedData: any }) {
+  const { reset, formState } = useFormContext();
+
+  return (
+    <div style={{ display: 'flex', gap: '8px', marginTop: '8px' }}>
+      <Button
+        type="Outlined"
+        onClick={() => reset(savedData)}
+        disabled={!formState.isDirty}
+      >
+        Discard Changes
+      </Button>
+
+      <Button
+        type="Ghost"
+        onClick={() => reset({ name: '', email: '', bio: '' })}
+      >
+        Clear All
+      </Button>
+    </div>
+  );
+}
+```
+
+### Watching Specific Fields
+```tsx
+import { useWatch } from 'react-hook-form';
+
+function WatchSpecificFieldsExample() {
+  const handleSubmit = (values: { country: string; state: string; city: string }) => {
+    console.log('Submitted:', values);
+  };
+
+  return (
+    <Form
+      defaultValues={{ country: '', state: '', city: '' }}
+      onSubmit={handleSubmit}
+    >
+      <FormField name="country" label="Country" required>
         <Select>
-          <Option value="tech">Technology</Option>
-          <Option value="design">Design</Option>
-          <Option value="business">Business</Option>
+          <Option value="">Select a country</Option>
+          <Option value="us">United States</Option>
+          <Option value="canada">Canada</Option>
+          <Option value="uk">United Kingdom</Option>
         </Select>
       </FormField>
-      
-      <div className="form-actions">
-        <Button type="Outlined">Save as Draft</Button>
-        <Button 
-          actionType="submit" 
-          onClick={handlePublish}
+
+      <DependentFields />
+
+      <Button actionType="submit">Submit</Button>
+    </Form>
+  );
+}
+
+function DependentFields() {
+  // Watch only the country field
+  const country = useWatch({ name: 'country' });
+  const { setValue } = useFormContext();
+
+  // Reset dependent fields when country changes
+  useEffect(() => {
+    setValue('state', '');
+    setValue('city', '');
+  }, [country, setValue]);
+
+  if (!country) return null;
+
+  return (
+    <>
+      <FormField name="state" label="State/Province" required>
+        <Select>
+          <Option value="">Select a state</Option>
+          {country === 'us' && (
+            <>
+              <Option value="ca">California</Option>
+              <Option value="ny">New York</Option>
+              <Option value="tx">Texas</Option>
+            </>
+          )}
+          {country === 'canada' && (
+            <>
+              <Option value="on">Ontario</Option>
+              <Option value="qc">Quebec</Option>
+              <Option value="bc">British Columbia</Option>
+            </>
+          )}
+        </Select>
+      </FormField>
+
+      <FormField name="city" label="City" required>
+        <Input placeholder="Enter your city" />
+      </FormField>
+    </>
+  );
+}
+```
+
+### Manual Validation Triggering
+```tsx
+import { useFormContext } from 'react-hook-form';
+
+function ManualValidationExample() {
+  const [isChecking, setIsChecking] = useState(false);
+  const [isAvailable, setIsAvailable] = useState<boolean | null>(null);
+
+  const handleSubmit = (values: { username: string; email: string }) => {
+    console.log('Submitted:', values);
+  };
+
+  return (
+    <Form
+      defaultValues={{ username: '', email: '' }}
+      onSubmit={handleSubmit}
+    >
+      <UsernameFieldWithCheck
+        isChecking={isChecking}
+        setIsChecking={setIsChecking}
+        isAvailable={isAvailable}
+        setIsAvailable={setIsAvailable}
+      />
+
+      <FormField name="email" label="Email" required>
+        <Input inputType="Email" />
+      </FormField>
+
+      <Button actionType="submit">Register</Button>
+    </Form>
+  );
+}
+
+function UsernameFieldWithCheck({
+  isChecking,
+  setIsChecking,
+  isAvailable,
+  setIsAvailable
+}: {
+  isChecking: boolean;
+  setIsChecking: (value: boolean) => void;
+  isAvailable: boolean | null;
+  setIsAvailable: (value: boolean | null) => void;
+}) {
+  const { trigger, getValues, setError, clearErrors } = useFormContext();
+
+  const checkAvailability = async () => {
+    // First, validate the username field
+    const isValid = await trigger('username');
+
+    if (!isValid) {
+      return; // Don't check if validation fails
+    }
+
+    setIsChecking(true);
+    setIsAvailable(null);
+
+    try {
+      const username = getValues('username');
+      const response = await fetch(`/api/check-username?username=${username}`);
+      const { available } = await response.json();
+
+      setIsAvailable(available);
+
+      if (!available) {
+        setError('username', {
+          type: 'manual',
+          message: 'Username is already taken'
+        });
+      } else {
+        clearErrors('username');
+      }
+    } catch (error) {
+      console.error('Failed to check username:', error);
+    } finally {
+      setIsChecking(false);
+    }
+  };
+
+  return (
+    <div>
+      <FormField
+        name="username"
+        label="Username"
+        required
+        validate={(value) => {
+          if (value.length < 3) {
+            return 'Username must be at least 3 characters';
+          }
+          if (!/^[a-zA-Z0-9_]+$/.test(value)) {
+            return 'Username can only contain letters, numbers, and underscores';
+          }
+          return undefined;
+        }}
+      >
+        <Input placeholder="Choose a username" />
+      </FormField>
+
+      <div style={{ marginTop: '4px', display: 'flex', alignItems: 'center', gap: '8px' }}>
+        <Button
+          type="Ghost"
+          size="Small"
+          onClick={checkAvailability}
+          loading={isChecking}
         >
-          Publish Article
+          Check Availability
         </Button>
+
+        {isAvailable === true && (
+          <Text type="BodySmall" style={{ color: 'green' }}>
+            ✓ Username is available
+          </Text>
+        )}
+        {isAvailable === false && (
+          <Text type="BodySmall" style={{ color: 'red' }}>
+            ✗ Username is taken
+          </Text>
+        )}
       </div>
-      
-      {isDraft && (
-        <Text type="BodySmall" style={{ marginTop: '8px' }}>
-          Your changes are automatically saved as you type
-        </Text>
-      )}
+    </div>
+  );
+}
+```
+
+### FormState Properties Reference
+```tsx
+import { useFormContext } from 'react-hook-form';
+
+function FormStateReferenceExample() {
+  const handleSubmit = (values: { name: string; email: string }) => {
+    console.log('Submitted:', values);
+  };
+
+  return (
+    <Form
+      defaultValues={{ name: '', email: '' }}
+      onSubmit={handleSubmit}
+      mode="onChange"
+    >
+      <FormField name="name" label="Name" required>
+        <Input />
+      </FormField>
+
+      <FormField name="email" label="Email" required>
+        <Input inputType="Email" />
+      </FormField>
+
+      <FormStateDisplay />
+
+      <Button actionType="submit">Submit</Button>
     </Form>
   );
 }
-```
+
+function FormStateDisplay() {
+  const { formState } = useFormContext();
+  const {
+    isDirty,           // true if any field has been modified
+    isValid,           // true if no validation errors
+    isSubmitting,      // true during async submission
+    isSubmitted,       // true if form has been submitted
+    isSubmitSuccessful, // true if submission was successful
+    submitCount,       // number of times form has been submitted
+    touchedFields,     // fields that have been focused and blurred
+    dirtyFields,       // fields that have been modified
+    errors             // current validation errors
+  } = formState;
+
+  return (
+    <div style={{
+      padding: '12px',
+      background: '#f5f5f5',
+      borderRadius: '4px',
+      marginTop: '16px',
+      fontSize: '13px'
+    }}>
+      <Text type="BodySmall" weight="SemiBold">Form State Properties:</Text>
+
+      <div style={{ marginTop: '8px', display: 'grid', gap: '4px' }}>
+        <div><strong>isDirty:</strong> {String(isDirty)}</div>
+        <div><strong>isValid:</strong> {String(isValid)}</div>
+        <div><strong>isSubmitting:</strong> {String(isSubmitting)}</div>
+        <div><strong>isSubmitted:</strong> {String(isSubmitted)}</div>
+        <div><strong>isSubmitSuccessful:</strong> {String(isSubmitSuccessful)}</div>
+        <div><strong>submitCount:</strong> {submitCount}</div>
+        <div><strong>touchedFields:</strong> {JSON.stringify(touchedFields)}</div>
+        <div><strong>dirtyFields:</strong> {JSON.stringify(dirtyFields)}</div>
+        <div><strong>errors:</strong> {JSON.stringify(errors)}</div>
+      </div>
+
+      <div style={{ marginTop: '12px', padding: '8px', background: '#e3f2fd' }}>
+        <Text type="BodySmall" weight="SemiBold">Common Patterns:</Text>
+        <ul style={{ margin: '8px 0', paddingLeft: '20px', fontSize: '12px' }}>
+          <li>Disable submit button: <code>disabled={`{!isDirty || !isValid}`}</code></li>
+          <li>Show loading: <code>loading={`{isSubmitting}`}</code></li>
+          <li>Show success message: <code>{`{isSubmitSuccessful && '✓ Saved!'}`}</code></li>
+          <li>Warn on navigation: <code>{`{isDirty && 'Unsaved changes'}`}</code></li>
+        </ul>
+      </div>
+    </div>
+  );
+}
+```
+
+---
+
+## Additional Resources
+
+- [React Hook Form Documentation](https://react-hook-form.com/)
+- [Migration Guide](../../../FORM_MIGRATION_GUIDE.md)
+- [FormField Documentation](../../molecules/FormField.md)
+- [Example Files](../../../src/components/organisms/Form/examples/)