@delightui/components 0.1.161 → 0.1.162-alpha.1

package/docs/FORM_MIGRATION_GUIDE.md

@@ -0,0 +1,631 @@
+# Form & FormField Migration Guide
+
+## Overview
+
+The Form and FormField components have been rewritten on top of **React Hook Form** (RHF) to provide better performance, TypeScript support, and a more modern API. This guide will help you migrate from the old custom form implementation to the new RHF-based implementation.
+
+---
+
+## Quick Reference: Props Comparison
+
+### Form Component
+
+| OLD Prop | NEW Prop | Status | Migration Notes |
+|----------|----------|--------|-----------------|
+| `formState?: T` | `defaultValues?: object` | 🔴 **BREAKING** | Renamed. Use for initial uncontrolled form values |
+| `onFormStateChange?: (state, setError) => void` | ❌ Removed | 🔴 **BREAKING** | Use RHF's `watch()` or `useWatch()` hooks instead |
+| `formValidator?: (state, setError) => boolean` | ❌ Removed | 🔴 **BREAKING** | Use field-level validation or RHF's `resolver` |
+| `onSubmit?: (values, setError) => void` | `onSubmit?: (values) => void \| Promise<void>` | 🔴 **BREAKING** | No `setError` callback - use RHF hooks instead |
+| `validateOnChange?: boolean` | `mode?: 'onSubmit' \| 'onChange' \| 'onBlur' \| ...` | 🔴 **BREAKING** | More flexible validation modes |
+| `formRef?: Ref<HTMLFormElement>` | `formRef?: Ref<HTMLFormElement>` | ✅ **SAME** | Unchanged |
+| `children?: ReactNode` | `children: ReactNode` | ✅ **SAME** | Now required |
+| ❌ N/A | `autosave?: boolean` | 🟢 **NEW** | Enable autosave functionality |
+| ❌ N/A | `autosaveDelayMs?: number` | 🟢 **NEW** | Autosave debounce delay |
+| ❌ N/A | `formOptions?: UseFormProps` | 🟢 **NEW** | Pass additional RHF options |
+| ❌ N/A | `className?: string` | 🟢 **NEW** | Form CSS class |
+| ❌ N/A | `style?: CSSProperties` | 🟢 **NEW** | Form inline styles |
+
+### FormField Component
+
+| OLD Prop | NEW Prop | Status | Migration Notes |
+|----------|----------|--------|-----------------|
+| `name: string` | `name: TName` (type-safe) | 🟡 **ENHANCED** | Now type-checked against form values |
+| `label?: string` | `label?: string` | ✅ **SAME** | Unchanged |
+| `children: ReactNode` | `children: ReactNode` | ✅ **SAME** | Unchanged |
+| `message?: string` | `message?: string` | ✅ **SAME** | Info message |
+| `hasMessage?: boolean` | ❌ Removed | 🔴 **BREAKING** | No longer needed |
+| `infoIcon?: ReactNode` | `infoIcon?: ReactNode` | ✅ **SAME** | Unchanged |
+| `required?: boolean` | `required?: boolean` | ✅ **SAME** | Unchanged |
+| `validate?: (setError, value?) => boolean` | `validate?: (value) => string \| undefined` | 🔴 **BREAKING** | Return error message instead of calling setError |
+| ❌ N/A | `asyncValidate?: (value) => Promise<string \| undefined>` | 🟢 **NEW** | Async validation support |
+| `disabled?: boolean` | `disabled?: boolean` | ✅ **SAME** | Unchanged |
+| `invalid?: boolean` | `invalid?: boolean` | ✅ **SAME** | External invalid state |
+| `id?: string` | `id?: string` | ✅ **SAME** | Unchanged |
+| ❌ N/A | `displayName?: string` | 🟢 **NEW** | Custom name for error messages |
+| ❌ N/A | `defaultValue?: TValue` | 🟢 **NEW** | Field-level default value |
+| ❌ N/A | `value?: TValue` | 🟢 **NEW** | Standalone mode: controlled value |
+| ❌ N/A | `onChange?: (value) => void` | 🟢 **NEW** | Standalone mode: onChange handler |
+| ❌ N/A | `error?: string` | 🟢 **NEW** | Standalone mode: external error |
+
+---
+
+## Breaking Changes
+
+### 1. FormProvider Component Removed
+
+**OLD:**
+```tsx
+<FormProvider formState={formState} onFormStateChange={handleChange} onSubmit={handleSubmit}>
+  <Form>
+    <FormField name="email" required>
+      <Input />
+    </FormField>
+  </Form>
+</FormProvider>
+```
+
+**NEW:**
+```tsx
+<Form defaultValues={formState} onSubmit={handleSubmit}>
+  <FormField name="email" required>
+    <Input />
+  </FormField>
+</Form>
+```
+
+### 2. Props Renamed: `formState` → `defaultValues`
+
+**OLD:**
+```tsx
+<FormProvider formState={{ email: '', name: '' }}>
+  <Form>{/* ... */}</Form>
+</FormProvider>
+```
+
+**NEW:**
+```tsx
+<Form defaultValues={{ email: '', name: '' }}>
+  {/* ... */}
+</Form>
+```
+
+### 3. `onSubmit` Signature Changed
+
+**OLD:**
+```tsx
+const handleSubmit = (values, setError) => {
+  if (!validateEmail(values.email)) {
+    setError('email', 'Invalid email');
+    return;
+  }
+  // Submit logic
+};
+```
+
+**NEW:**
+```tsx
+import { useFormContext } from 'react-hook-form';
+
+const handleSubmit = async (values) => {
+  // For setting errors, use RHF hooks in a component
+  // or handle validation in field-level validators
+  try {
+    await submitToAPI(values);
+  } catch (error) {
+    // Use setError from useFormContext if needed
+  }
+};
+```
+
+**Setting Errors in NEW Version:**
+```tsx
+// Create a component that can access form context
+function MyFormContent() {
+  const { setError } = useFormContext();
+
+  const handleAPIError = (fieldName, message) => {
+    setError(fieldName, { message });
+  };
+
+  return (
+    <FormField name="email" required>
+      <Input />
+    </FormField>
+  );
+}
+
+function MyForm() {
+  const handleSubmit = async (values) => {
+    // Handle submission
+  };
+
+  return (
+    <Form defaultValues={{ email: '' }} onSubmit={handleSubmit}>
+      <MyFormContent />
+    </Form>
+  );
+}
+```
+
+### 4. Validation Function Signature Changed
+
+**OLD:**
+```tsx
+const validatePassword = (setError, value) => {
+  if (!value) {
+    setError('Password is required');
+    return false;
+  }
+  if (value.length < 8) {
+    setError('Password must be at least 8 characters');
+    return false;
+  }
+  return true;
+};
+
+<FormField name="password" validate={validatePassword}>
+  <Input inputType="Password" />
+</FormField>
+```
+
+**NEW:**
+```tsx
+const validatePassword = (value: string) => {
+  if (!value) {
+    return 'Password is required';
+  }
+  if (value.length < 8) {
+    return 'Password must be at least 8 characters';
+  }
+  return undefined; // Valid
+};
+
+<FormField name="password" validate={validatePassword}>
+  <Input inputType="Password" />
+</FormField>
+```
+
+### 5. `onFormStateChange` Removed
+
+**OLD:**
+```tsx
+const handleStateChange = (state, setError) => {
+  console.log('Form changed:', state);
+  // Validate on change
+  if (state.email && !validateEmail(state.email)) {
+    setError('email', 'Invalid email');
+  }
+};
+
+<FormProvider
+  formState={formState}
+  onFormStateChange={handleStateChange}
+>
+  <Form>{/* ... */}</Form>
+</FormProvider>
+```
+
+**NEW:**
+```tsx
+import { useWatch } from 'react-hook-form';
+
+function FormContent() {
+  const formValues = useWatch(); // Watch all fields
+  // Or watch specific field: const email = useWatch({ name: 'email' });
+
+  useEffect(() => {
+    console.log('Form changed:', formValues);
+  }, [formValues]);
+
+  return (
+    <>
+      <FormField name="email" required>
+        <Input />
+      </FormField>
+      {/* ... */}
+    </>
+  );
+}
+
+function MyForm() {
+  return (
+    <Form defaultValues={{ email: '' }}>
+      <FormContent />
+    </Form>
+  );
+}
+```
+
+### 6. `validateOnChange` → `mode`
+
+**OLD:**
+```tsx
+<FormProvider validateOnChange={true}>
+  <Form>{/* ... */}</Form>
+</FormProvider>
+```
+
+**NEW:**
+```tsx
+<Form mode="onChange">
+  {/* ... */}
+</Form>
+```
+
+**Available modes:**
+- `"onSubmit"` (default) - Validate on submit
+- `"onChange"` - Validate on every change
+- `"onBlur"` - Validate on blur
+- `"onTouched"` - Validate after first blur, then on change
+- `"all"` - Validate on change, blur, and submit
+
+### 7. `formValidator` Removed
+
+**OLD:**
+```tsx
+const formValidator = (state, setError) => {
+  let isValid = true;
+  if (state.password !== state.confirmPassword) {
+    setError('confirmPassword', 'Passwords do not match');
+    isValid = false;
+  }
+  return isValid;
+};
+
+<FormProvider formValidator={formValidator}>
+  <Form>{/* ... */}</Form>
+</FormProvider>
+```
+
+**NEW (Option 1 - Field-level validation):**
+```tsx
+<FormField
+  name="confirmPassword"
+  validate={(value) => {
+    const password = /* get password value using useWatch */;
+    if (value !== password) {
+      return 'Passwords do not match';
+    }
+    return undefined;
+  }}
+>
+  <Input inputType="Password" />
+</FormField>
+```
+
+**NEW (Option 2 - RHF Resolver):**
+```tsx
+import { zodResolver } from '@hookform/resolvers/zod';
+import * as z from 'zod';
+
+const schema = z.object({
+  password: z.string().min(8),
+  confirmPassword: z.string()
+}).refine(data => data.password === data.confirmPassword, {
+  message: "Passwords do not match",
+  path: ["confirmPassword"]
+});
+
+<Form
+  formOptions={{ resolver: zodResolver(schema) }}
+  defaultValues={{ password: '', confirmPassword: '' }}
+>
+  {/* ... */}
+</Form>
+```
+
+### 8. `hasMessage` Prop Removed
+
+**OLD:**
+```tsx
+<FormField name="email" hasMessage={true} message="Invalid email">
+  <Input />
+</FormField>
+```
+
+**NEW:**
+```tsx
+<FormField name="email" message="Invalid email">
+  <Input />
+</FormField>
+```
+
+---
+
+## New Features
+
+### 1. Autosave Support
+
+```tsx
+<Form
+  defaultValues={{ title: '', content: '' }}
+  onSubmit={handleAutosave}
+  autosave={true}
+  autosaveDelayMs={2000} // Wait 2s after user stops typing
+>
+  <FormField name="title" label="Title">
+    <Input />
+  </FormField>
+  <FormField name="content" label="Content">
+    <TextArea rows={10} />
+  </FormField>
+</Form>
+```
+
+### 2. Async Validation
+
+```tsx
+const validateUsername = async (value: string) => {
+  const response = await fetch(`/api/check-username?username=${value}`);
+  const { available } = await response.json();
+  if (!available) {
+    return 'Username is already taken';
+  }
+  return undefined;
+};
+
+<FormField
+  name="username"
+  label="Username"
+  asyncValidate={validateUsername}
+>
+  <Input />
+</FormField>
+```
+
+### 3. Standalone FormField (No Form Required)
+
+```tsx
+function StandaloneExample() {
+  const [email, setEmail] = useState('');
+  const [error, setError] = useState('');
+
+  const validateEmail = (value: string) => {
+    if (!value.includes('@')) {
+      return 'Invalid email';
+    }
+    return undefined;
+  };
+
+  return (
+    <FormField
+      name="email"
+      label="Email"
+      value={email}
+      onChange={setEmail}
+      error={error}
+      validate={(value) => {
+        const error = validateEmail(value);
+        setError(error || '');
+        return error;
+      }}
+    >
+      <Input />
+    </FormField>
+  );
+}
+```
+
+### 4. Full TypeScript Type Safety
+
+```tsx
+interface MyFormValues {
+  email: string;
+  age: number;
+  newsletter: boolean;
+}
+
+function TypeSafeForm() {
+  const handleSubmit = (values: MyFormValues) => {
+    // values is fully typed!
+    console.log(values.email); // ✅ TypeScript knows this is a string
+  };
+
+  return (
+    <Form<MyFormValues>
+      defaultValues={{ email: '', age: 0, newsletter: false }}
+      onSubmit={handleSubmit}
+    >
+      {/* TypeScript will validate field names */}
+      <FormField<MyFormValues> name="email" label="Email">
+        <Input />
+      </FormField>
+
+      {/* This would cause a TypeScript error: */}
+      {/* <FormField name="invalidField"> */}
+    </Form>
+  );
+}
+```
+
+### 5. Access to React Hook Form Methods
+
+```tsx
+import { useFormContext } from 'react-hook-form';
+
+function FormActions() {
+  const { reset, setValue, getValues, formState } = useFormContext();
+
+  return (
+    <div>
+      <Button onClick={() => reset()}>Reset Form</Button>
+      <Button onClick={() => setValue('email', 'test@example.com')}>
+        Prefill Email
+      </Button>
+      <Text>Form is {formState.isDirty ? 'modified' : 'pristine'}</Text>
+    </div>
+  );
+}
+
+function MyForm() {
+  return (
+    <Form defaultValues={{ email: '' }}>
+      <FormField name="email" label="Email">
+        <Input />
+      </FormField>
+      <FormActions />
+    </Form>
+  );
+}
+```
+
+---
+
+## Migration Checklist
+
+- [ ] Replace `FormProvider` wrapper with direct `<Form>` usage
+- [ ] Rename `formState` prop to `defaultValues`
+- [ ] Update `onSubmit` handlers to remove `setError` parameter
+- [ ] Convert validation functions to return error strings instead of calling `setError`
+- [ ] Replace `onFormStateChange` with `useWatch()` or `useFormContext()`
+- [ ] Change `validateOnChange` to `mode="onChange"`
+- [ ] Remove `formValidator` and use field-level validation or RHF resolver
+- [ ] Remove `hasMessage` prop from FormField components
+- [ ] Update TypeScript types to use new form value types
+- [ ] Test all form validation flows
+- [ ] Test form submission and error handling
+- [ ] Consider using new features: autosave, async validation, standalone mode
+
+---
+
+## Common Migration Patterns
+
+### Pattern 1: Simple Contact Form
+
+**OLD:**
+```tsx
+function ContactForm() {
+  const [formState, setFormState] = useState({ name: '', email: '', message: '' });
+
+  const handleSubmit = (values, setError) => {
+    if (!values.email.includes('@')) {
+      setError('email', 'Invalid email');
+      return;
+    }
+    console.log('Submitted:', values);
+  };
+
+  return (
+    <FormProvider formState={formState} onSubmit={handleSubmit}>
+      <Form>
+        <FormField name="name" label="Name" required><Input /></FormField>
+        <FormField name="email" label="Email" required><Input /></FormField>
+        <FormField name="message" label="Message"><TextArea /></FormField>
+        <Button actionType="submit">Send</Button>
+      </Form>
+    </FormProvider>
+  );
+}
+```
+
+**NEW:**
+```tsx
+function ContactForm() {
+  const handleSubmit = (values: { name: string; email: string; message: string }) => {
+    console.log('Submitted:', values);
+  };
+
+  const validateEmail = (value: string) => {
+    if (!value.includes('@')) return 'Invalid email';
+    return undefined;
+  };
+
+  return (
+    <Form
+      defaultValues={{ name: '', email: '', message: '' }}
+      onSubmit={handleSubmit}
+    >
+      <FormField name="name" label="Name" required><Input /></FormField>
+      <FormField name="email" label="Email" required validate={validateEmail}>
+        <Input />
+      </FormField>
+      <FormField name="message" label="Message"><TextArea /></FormField>
+      <Button actionType="submit">Send</Button>
+    </Form>
+  );
+}
+```
+
+### Pattern 2: Form with Dynamic Validation
+
+**OLD:**
+```tsx
+function SignupForm() {
+  const formValidator = (state, setError) => {
+    if (state.password !== state.confirmPassword) {
+      setError('confirmPassword', 'Passwords must match');
+      return false;
+    }
+    return true;
+  };
+
+  return (
+    <FormProvider formValidator={formValidator}>
+      <Form>
+        <FormField name="password" label="Password" required>
+          <Input inputType="Password" />
+        </FormField>
+        <FormField name="confirmPassword" label="Confirm" required>
+          <Input inputType="Password" />
+        </FormField>
+        <Button actionType="submit">Sign Up</Button>
+      </Form>
+    </FormProvider>
+  );
+}
+```
+
+**NEW:**
+```tsx
+import { useWatch, useFormContext } from 'react-hook-form';
+
+function ConfirmPasswordField() {
+  const password = useWatch({ name: 'password' });
+
+  const validateConfirm = (value: string) => {
+    if (value !== password) return 'Passwords must match';
+    return undefined;
+  };
+
+  return (
+    <FormField
+      name="confirmPassword"
+      label="Confirm"
+      required
+      validate={validateConfirm}
+    >
+      <Input inputType="Password" />
+    </FormField>
+  );
+}
+
+function SignupForm() {
+  return (
+    <Form defaultValues={{ password: '', confirmPassword: '' }}>
+      <FormField name="password" label="Password" required>
+        <Input inputType="Password" />
+      </FormField>
+      <ConfirmPasswordField />
+      <Button actionType="submit">Sign Up</Button>
+    </Form>
+  );
+}
+```
+
+---
+
+## Resources
+
+- [React Hook Form Documentation](https://react-hook-form.com/)
+- [React Hook Form API Reference](https://react-hook-form.com/api)
+- [Migration Examples in Codebase](./components/organisms/Form/examples/)
+
+---
+
+## Need Help?
+
+If you encounter issues during migration:
+
+1. Check the [Form examples](../src/components/organisms/Form/examples/) in the codebase
+2. Review the [React Hook Form docs](https://react-hook-form.com/)
+3. Reach out to the team for assistance