@delightui/components 0.1.160 → 0.1.162-alpha.0

package/docs/components/molecules/FormField.md

@@ -1,36 +1,58 @@
 # FormField
 
+> **⚠️ BREAKING CHANGES:** The FormField component has been updated to work with the new React Hook Form-based Form component. See the [Migration Guide](../../../FORM_MIGRATION_GUIDE.md) for details.
+
 ## Description
 
-A form field wrapper component that provides consistent labeling, validation messaging, and styling for form inputs. Integrates seamlessly with the Form component to provide a complete form field experience with error handling, required field indicators, and accessibility features.
+A form field wrapper component that provides consistent labeling, validation messaging, and styling for form inputs. Works seamlessly with the Form component (React Hook Form) or standalone with controlled value/onChange props. Features error handling, required field indicators, async validation, and full TypeScript support.
 
 ## Aliases
 
 - FormField
-- FieldWrapper
-- InputWrapper
-- FormGroup
 - Field
 
-## Props Breakdown
-
-**Extends:** `HTMLAttributes<HTMLDivElement>`
+## Props Breakdown (Inside Form)
 
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
-| `name` | `string` | - | Yes | Name of the form field |
+| `name` | `string` (type-safe) | - | Yes | Name of the form field (type-checked against form values) |
 | `label` | `string` | - | No | Label for the form field |
 | `children` | `ReactNode` | - | Yes | Form input component to wrap |
-| `message` | `string` | - | No | Message for the form field |
-| `hasMessage` | `boolean` | `false` | No | Whether there is a message/error for the field |
-| `infoIcon` | `ReactNode` | - | No | Info icon for the form field |
 | `required` | `boolean` | `false` | No | Whether the form field is required |
-| `validate` | `FieldValidationFunction` | - | No | Validation function for the form field |
+| `validate` | `(value) => string \| undefined` | - | No | Sync validation function (returns error message or undefined) |
+| `asyncValidate` | `(value) => Promise<string \| undefined>` | - | No | Async validation function |
+| `defaultValue` | `TValue` | - | No | Default value for this field |
+| `message` | `string` | - | No | Info/helper message to display |
 | `disabled` | `boolean` | `false` | No | Whether the form field is disabled |
-| `invalid` | `boolean` | `false` | No | Whether the form field is invalid |
+| `invalid` | `boolean` | `false` | No | External invalid state |
+| `infoIcon` | `ReactNode` | - | No | Info icon element |
+| `displayName` | `string` | - | No | Custom name for validation error messages |
 | `id` | `string` | - | No | ID for the form field |
 
-Plus all standard HTML div attributes (className, style, onClick, etc.).
+## Props Breakdown (Standalone Mode)
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `name` | `string` | - | Yes | Name of the form field |
+| `value` | `TValue` | - | No | Controlled value |
+| `onChange` | `(value: TValue) => void` | - | No | Change handler |
+| `error` | `string` | - | No | External error message |
+| All other props same as above | | | | |
+
+### Removed Props (Breaking Changes)
+
+| OLD Prop | Migration Path |
+|----------|----------------|
+| `hasMessage` | No longer needed - remove it |
+| `validate: (setError, value) => boolean` | Change to `(value) => string \| undefined` |
+
+### Key Differences from Old API
+
+- ✅ **`validate`** now returns error message string instead of calling `setError`
+- ✅ **`asyncValidate`** added for async validation
+- ✅ **Standalone mode** - works without Form using `value`/`onChange`
+- ✅ **Type-safe** - field names are type-checked against form values
+- ✅ **`displayName`** for custom error message field names
 
 ## Examples
 
@@ -164,28 +186,26 @@ function InputTypesExample() {
 }
 ```
 
-### Custom Validation
+### Custom Validation (NEW API)
 ```tsx
 function CustomValidationExample() {
-  const validateAge = (setError, value) => {
+  const validateAge = (value: string) => {
     if (!value) {
-      setError('Age is required');
-      return false;
+      return 'Age is required';
     }
-    
+
     const age = parseInt(value);
     if (isNaN(age) || age < 18 || age > 120) {
-      setError('Age must be between 18 and 120');
-      return false;
+      return 'Age must be between 18 and 120';
     }
-    
-    return true;
+
+    return undefined; // Valid
   };
 
   return (
-    <FormField 
-      name="age" 
-      label="Age" 
+    <FormField
+      name="age"
+      label="Age"
       required
       validate={validateAge}
     >
@@ -195,41 +215,116 @@ function CustomValidationExample() {
 }
 ```
 
-### Form Integration
+### Async Validation (NEW)
+```tsx
+function AsyncValidationExample() {
+  const validateEmail = async (value: string) => {
+    if (!value) return 'Email is required';
+
+    // Check if email is already registered
+    const response = await fetch(`/api/check-email?email=${value}`);
+    const { exists } = await response.json();
+
+    if (exists) {
+      return 'Email is already registered';
+    }
+    return undefined;
+  };
+
+  return (
+    <FormField
+      name="email"
+      label="Email"
+      required
+      asyncValidate={validateEmail}
+    >
+      <Input inputType="Email" placeholder="Enter your email" />
+    </FormField>
+  );
+}
+```
+
+### Standalone Mode (NEW - No Form Required)
+```tsx
+import { useState } from 'react';
+
+function StandaloneFieldExample() {
+  const [email, setEmail] = useState('');
+
+  const validateEmail = (value: string) => {
+    if (!value.includes('@')) {
+      return 'Please enter a valid email';
+    }
+    return undefined;
+  };
+
+  return (
+    <FormField
+      name="email"
+      label="Email Address"
+      value={email}
+      onChange={setEmail}
+      required
+      validate={validateEmail}
+    >
+      <Input inputType="Email" placeholder="Enter email" />
+    </FormField>
+  );
+}
+```
+
+### Form Integration (NEW API)
 ```tsx
 function FormIntegrationExample() {
-  const handleSubmit = (values, setError) => {
+  const handleSubmit = (values: {
+    firstName: string;
+    lastName: string;
+    email: string;
+    phone: string;
+    message: string;
+  }) => {
     console.log('Form values:', values);
   };
 
   return (
-    <Form onSubmit={handleSubmit}>
+    <Form
+      defaultValues={{ firstName: '', lastName: '', email: '', phone: '', message: '' }}
+      onSubmit={handleSubmit}
+    >
       <FormField name="firstName" label="First Name" required>
         <Input />
       </FormField>
-      
+
       <FormField name="lastName" label="Last Name" required>
         <Input />
       </FormField>
-      
+
       <FormField name="email" label="Email" required>
         <Input inputType="Email" />
       </FormField>
-      
+
       <FormField name="phone" label="Phone Number">
         <Input inputType="Tel" />
       </FormField>
-      
+
       <FormField name="message" label="Message">
         <TextArea rows={4} />
       </FormField>
-      
+
       <Button actionType="submit">Submit</Button>
     </Form>
   );
 }
 ```
 
+---
+
+## Additional Resources
+
+- [Form Documentation](../../organisms/Form.md)
+- [Migration Guide](../../../FORM_MIGRATION_GUIDE.md)
+- [React Hook Form Documentation](https://react-hook-form.com/)
+
 ### Conditional Fields
 ```tsx
 function ConditionalFieldsExample() {