@delightui/components 0.1.162-alpha.4 → 0.1.162

package/docs/FORM_MIGRATION_GUIDE.md

@@ -1,631 +0,0 @@
-# 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