@connect-soft/form-generator 1.0.0 → 1.1.0-alpha2

package/MIGRATION.md

@@ -0,0 +1,503 @@
+# Migration Guide: v1.x (MUI) → v2.0 (Radix UI + Tailwind CSS)
+
+This guide will help you migrate from `@connect-soft/mui-hook-form` v1.x to `@connect-soft/form-generator` v2.0.
+
+## Overview
+
+v2.0 is a **complete rewrite** with breaking changes:
+
+- ❌ **Removed:** All Material-UI dependencies (@mui/material, @emotion/react, @emotion/styled)
+- ✅ **Added:** Radix UI primitives + Tailwind CSS
+- 🎨 **New:** Simplified, modern API
+- 📦 **Result:** 50-60% smaller bundle size (<80 KB vs ~120-377 KB)
+
+---
+
+## Breaking Changes
+
+### 1. Package Name Changed
+
+**v1.x:**
+```bash
+npm install @connect-soft/mui-hook-form
+```
+
+**v2.0:**
+```bash
+npm install @connect-soft/form-generator
+```
+
+### 2. Peer Dependencies Changed
+
+**v1.x required:**
+- `@mui/material` v7.x
+- `@mui/icons-material` v7.x
+- `@mui/x-date-pickers` v8.x
+- `@emotion/react` v11.x
+- `@emotion/styled` v11.x
+- `dayjs` v1.x
+
+**v2.0 requires:**
+- `react` v19.x
+- `react-dom` v19.x
+- `zod` v4.x
+- **No MUI or Emotion dependencies!**
+
+### 3. Tailwind CSS Required
+
+v2.0 uses Tailwind CSS for styling. You must set up Tailwind in your project:
+
+```bash
+npm install -D tailwindcss postcss autoprefixer
+npx tailwindcss init -p
+```
+
+**tailwind.config.js:**
+```javascript
+module.exports = {
+  content: [
+    './src/**/*.{js,ts,jsx,tsx}',
+    './node_modules/@connect-soft/form-generator/dist/**/*.{js,mjs}',
+  ],
+  // ... rest of config
+};
+```
+
+**Import global CSS:**
+```typescript
+// In your main file (e.g., App.tsx, index.tsx)
+import '@connect-soft/form-generator/dist/styles.css';
+```
+
+### 4. Field Type Definitions Changed
+
+The field definition structure has been simplified.
+
+#### v1.x Field Structure:
+```typescript
+const v1Field = {
+  type: 'textField',
+  props: {
+    name: 'email',
+    label: 'Email Address',
+    required: true,
+    placeholder: 'Enter your email',
+    type: 'email',
+  },
+  display: (values) => values.showEmail,
+};
+```
+
+#### v2.0 Field Structure:
+```typescript
+const v2Field = {
+  type: 'text',
+  name: 'email',
+  label: 'Email Address',
+  required: true,
+  placeholder: 'Enter your email',
+  fieldType: 'email',
+  // No nested 'props'!
+};
+```
+
+---
+
+## Field Type Mapping
+
+| v1.x Type | v2.0 Type | Notes |
+|-----------|-----------|-------|
+| `textField` | `text` | Use `fieldType` for email, password, etc. |
+| `textArea` | `textarea` | - |
+| `numberField` | `number` | - |
+| `checkBox` | `checkbox` | - |
+| `switch` | `switch` | - |
+| `select` | `select` | Options format unchanged |
+| `radioGroup` | `radio` | Options format unchanged |
+| `datePicker` | `date` | Now uses react-day-picker |
+| `dateRangePicker` | `dateRange` | Now uses react-day-picker |
+| `timePicker` | `time` | - |
+
+---
+
+## Migration Strategies
+
+### Strategy 1: Gradual Migration with Adapter (Recommended)
+
+Use the built-in v1→v2 adapter to convert old field configs automatically:
+
+```typescript
+import { FormGenerator } from '@connect-soft/form-generator';
+import { adaptV1FieldsToV2 } from '@connect-soft/form-generator/adapters';
+
+// Your existing v1 fields
+const v1Fields = [
+  {
+    type: 'textField',
+    props: { name: 'email', label: 'Email', required: true },
+  },
+  // ... more v1 fields
+];
+
+// Auto-convert to v2
+const v2Fields = adaptV1FieldsToV2(v1Fields);
+
+function MyForm() {
+  return (
+    <FormGenerator
+      fields={v2Fields}
+      onSubmit={(values) => console.log(values)}
+    />
+  );
+}
+```
+
+### Strategy 2: Complete Rewrite
+
+Rewrite your field definitions using the new v2 API:
+
+```typescript
+import { FormGenerator, Field } from '@connect-soft/form-generator';
+
+const fields: Field[] = [
+  {
+    type: 'text',
+    name: 'email',
+    label: 'Email',
+    fieldType: 'email',
+    required: true,
+  },
+  {
+    type: 'select',
+    name: 'country',
+    label: 'Country',
+    options: [
+      { label: 'USA', value: 'us' },
+      { label: 'UK', value: 'uk' },
+    ],
+  },
+] as const;
+
+function MyForm() {
+  return (
+    <FormGenerator
+      fields={fields}
+      onSubmit={(values) => {
+        // values is fully typed!
+        console.log(values.email, values.country);
+      }}
+    />
+  );
+}
+```
+
+---
+
+## API Changes
+
+### FormGenerator Props
+
+#### Removed Props:
+- ❌ `sx` (MUI styling)
+- ❌ `theme` (MUI theme)
+- ❌ `muiProps` (MUI-specific props)
+
+#### New Props:
+- ✅ `className` (Tailwind classes)
+- ✅ `submitButtonVariant` (Button style variants)
+
+#### Unchanged Props:
+- ✅ `fields`
+- ✅ `onSubmit`
+- ✅ `defaultValues`
+- ✅ `mode`
+- ✅ `disabled`
+
+### Type Inference (Maintained!)
+
+v2.0 maintains the same powerful TypeScript inference from v1.x:
+
+```typescript
+const fields = [
+  { type: 'text', name: 'email', fieldType: 'email' },
+  { type: 'number', name: 'age' },
+  { type: 'checkbox', name: 'subscribe' },
+] as const;
+
+<FormGenerator
+  fields={fields}
+  onSubmit={(values) => {
+    // ✅ values.email: string
+    // ✅ values.age: number
+    // ✅ values.subscribe: boolean
+  }}
+/>
+```
+
+---
+
+## Styling Changes
+
+### v1.x (MUI)
+```typescript
+<FormGenerator
+  fields={fields}
+  sx={{ padding: 2, backgroundColor: 'primary.main' }}
+/>
+```
+
+### v2.0 (Tailwind CSS)
+```typescript
+<FormGenerator
+  fields={fields}
+  className="p-4 bg-primary"
+/>
+```
+
+To customize component styles, you can:
+
+1. **Use Tailwind classes** on individual fields:
+```typescript
+{
+  type: 'text',
+  name: 'email',
+  className: 'bg-blue-50 border-blue-300',
+}
+```
+
+2. **Override Tailwind theme** in `tailwind.config.js`:
+```javascript
+module.exports = {
+  theme: {
+    extend: {
+      colors: {
+        primary: '#your-color',
+      },
+    },
+  },
+};
+```
+
+3. **Use CSS variables** (defined in globals.css):
+```css
+:root {
+  --primary: 222.2 47.4% 11.2%;
+}
+```
+
+---
+
+## Complex Components
+
+### ColorPicker
+
+**v1.x:**
+```typescript
+import { ColorPicker } from '@connect-soft/mui-hook-form';
+```
+
+**v2.0:**
+```typescript
+import { ColorPicker } from '@connect-soft/form-generator/advanced';
+```
+
+### MultiSelect
+
+**v1.x:**
+```typescript
+// Used MUI Autocomplete
+```
+
+**v2.0:**
+```typescript
+import { MultiSelect } from '@connect-soft/form-generator/advanced';
+
+<MultiSelect
+  options={[
+    { label: 'Option 1', value: '1' },
+    { label: 'Option 2', value: '2' },
+  ]}
+  value={selected}
+  onChange={setSelected}
+/>
+```
+
+### TransferList
+
+**v1.x:**
+```typescript
+// Used MUI List/ListItem
+```
+
+**v2.0:**
+```typescript
+import { TransferList } from '@connect-soft/form-generator/advanced';
+
+<TransferList
+  options={allOptions}
+  value={selectedValues}
+  onChange={setSelectedValues}
+  searchable={true}
+/>
+```
+
+---
+
+## Date Pickers
+
+### Major Change: MUI X Date Pickers → react-day-picker
+
+**v1.x:**
+- Used `@mui/x-date-pickers`
+- Required `dayjs` as peer dependency
+- Used MUI's LocalizationProvider
+
+**v2.0:**
+- Uses `react-day-picker` v9
+- Uses `date-fns` for formatting
+- No provider needed!
+
+### Migration Example:
+
+**v1.x:**
+```typescript
+import { LocalizationProvider } from '@mui/x-date-pickers';
+import { AdapterDayjs } from '@mui/x-date-pickers/AdapterDayjs';
+
+<LocalizationProvider dateAdapter={AdapterDayjs}>
+  <FormGenerator fields={fields} />
+</LocalizationProvider>
+```
+
+**v2.0:**
+```typescript
+// No provider needed!
+<FormGenerator fields={fields} />
+```
+
+---
+
+## Testing Considerations
+
+### Update Test Setup
+
+If you were mocking MUI components in tests, you'll need to update:
+
+**v1.x:**
+```typescript
+jest.mock('@mui/material/TextField', () => ({
+  __esModule: true,
+  default: jest.fn(),
+}));
+```
+
+**v2.0:**
+```typescript
+// Mock Radix UI components if needed
+jest.mock('@radix-ui/react-select', () => ({
+  Root: jest.fn(),
+  Trigger: jest.fn(),
+  // ...
+}));
+```
+
+### Snapshot Tests
+
+All snapshots will change due to:
+- Different DOM structure (Radix vs MUI)
+- Different class names (Tailwind vs MUI)
+- **Action Required:** Regenerate all snapshots
+
+---
+
+## Bundle Size Impact
+
+### Before (v1.x with MUI):
+- Full bundle: ~377 KB
+- With tree-shaking: ~120 KB
+- Runtime: CSS-in-JS overhead
+
+### After (v2.0 with Radix + Tailwind):
+- Target: <80 KB gzipped
+- **50-60% reduction**
+- No runtime CSS overhead (Tailwind is build-time)
+
+---
+
+## Step-by-Step Migration Checklist
+
+- [ ] 1. Install v2.0: `npm install @connect-soft/form-generator`
+- [ ] 2. Set up Tailwind CSS in your project
+- [ ] 3. Import global CSS: `import '@connect-soft/form-generator/dist/styles.css'`
+- [ ] 4. Update imports: `@connect-soft/mui-hook-form` → `@connect-soft/form-generator`
+- [ ] 5. Use adapter for existing v1 fields OR rewrite field definitions
+- [ ] 6. Remove MUI peer dependencies
+- [ ] 7. Update styling (sx → className)
+- [ ] 8. Remove LocalizationProvider if used
+- [ ] 9. Update tests and regenerate snapshots
+- [ ] 10. Test thoroughly in development
+- [ ] 11. Uninstall v1.x: `npm uninstall @connect-soft/mui-hook-form`
+
+---
+
+## Troubleshooting
+
+### Issue: "Module not found: Can't resolve '@radix-ui/react-*'"
+
+**Solution:** Make sure you installed the package correctly:
+```bash
+npm install @connect-soft/form-generator
+```
+
+### Issue: "Styles not appearing"
+
+**Solution:**
+1. Ensure Tailwind CSS is configured in your project
+2. Import the global CSS file
+3. Add the package path to Tailwind's content array
+
+### Issue: "Type inference not working"
+
+**Solution:** Use `as const` assertion on your fields array:
+```typescript
+const fields = [...] as const;
+```
+
+### Issue: "Adapter not converting fields correctly"
+
+**Solution:** Check if your v1 fields follow the correct structure:
+```typescript
+// Correct v1 structure
+{ type: 'textField', props: { name: 'field1' } }
+
+// Incorrect
+{ fieldType: 'text', name: 'field1' }  // Wrong!
+```
+
+---
+
+## Support
+
+If you encounter issues during migration:
+
+1. Check this guide thoroughly
+2. Review the [CHANGELOG.md](./CHANGELOG.md)
+3. Open an issue: https://gitlab.com/connect-soft/components/form-generator/issues
+
+---
+
+## Summary
+
+**v2.0 Benefits:**
+- ✅ 50-60% smaller bundle
+- ✅ No runtime CSS-in-JS overhead
+- ✅ Simpler, cleaner API
+- ✅ Modern UI with Radix + Tailwind
+- ✅ Maintained TypeScript type safety
+
+**Migration Effort:**
+- **Small projects (< 10 forms):** 1-2 hours
+- **Medium projects (10-50 forms):** 1-2 days
+- **Large projects (50+ forms):** 1 week
+
+The migration is worth the effort for improved performance and developer experience!