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

package/README.md

@@ -1,33 +1,31 @@
 # @connect-soft/form-generator
 
-> Type-safe form generator with Radix UI, Tailwind CSS, and react-hook-form
+> Headless, type-safe form generator with react-hook-form and Zod validation
 
 [![Version](https://img.shields.io/npm/v/@connect-soft/form-generator)](https://www.npmjs.com/package/@connect-soft/form-generator)
 [![License](https://img.shields.io/npm/l/@connect-soft/form-generator)](./LICENSE)
-[![Bundle Size](https://img.shields.io/bundlephobia/minzip/@connect-soft/form-generator)](https://bundlephobia.com/package/@connect-soft/form-generator)
-
-**v2.0.0** - Complete rewrite with Radix UI + Tailwind CSS
-**50-60% smaller bundle** | **No runtime CSS overhead** | **Modern, accessible UI**
 
 ---
 
 ## Features
 
-✨ **Modern UI Stack**: Radix UI primitives + Tailwind CSS (shadcn/ui approach)
-📦 **Lightweight**: <80 KB gzipped (50-60% reduction from v1)
-🎯 **Type-Safe**: Full TypeScript inference for form values
-🔧 **Flexible**: 10+ field types with extensible API
-♿ **Accessible**: Built on Radix UI's accessible primitives
-🎨 **Customizable**: Easy styling with Tailwind classes
-🚀 **Performance**: No runtime CSS-in-JS, field-level subscriptions
-🔄 **Backward Compatible**: v1→v2 adapter included
+- **Headless**: Bring your own UI components (Radix, MUI, Chakra, or plain HTML)
+- **Type-Safe**: Full TypeScript inference for form values and field types
+- **Field Type Checking**: Compile-time validation of `field.type` with autocomplete
+- **Extensible Types**: Add custom field types via module augmentation
+- **Imperative API**: Control form via ref (`setValues`, `reset`, `submit`, etc.)
+- **Flexible**: Register custom field components with a simple API
+- **Validation**: Built-in Zod validation support
+- **Layouts**: Support for sections and multi-column layouts
+- **Lightweight**: No UI dependencies, minimal footprint
+- **HTML Fallbacks**: Works out of the box with native HTML inputs
 
 ---
 
 ## Installation
 
 ```bash
-npm install @connect-soft/form-generator react-hook-form zod
+npm install @connect-soft/form-generator
 ```
 
 ### Peer Dependencies
@@ -36,74 +34,23 @@ npm install @connect-soft/form-generator react-hook-form zod
 - `react-dom` ^19.0.0
 - `zod` ^4.0.0
 
-### Tailwind CSS Setup
-
-This library requires Tailwind CSS. If you don't have it set up:
-
-```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}',
-  ],
-  theme: {
-    extend: {
-      // Your custom theme
-    },
-  },
-  plugins: [],
-};
-```
-
-**Import the styles in your main file:**
-```typescript
-import '@connect-soft/form-generator/dist/styles.css';
-```
-
 ---
 
 ## Quick Start
 
+The library works immediately with HTML fallback components:
+
 ```typescript
-import { FormGenerator, Field } from '@connect-soft/form-generator';
+import { FormGenerator } from '@connect-soft/form-generator';
 
-const fields: Field[] = [
-  {
-    type: 'text',
-    name: 'email',
-    label: 'Email',
-    fieldType: 'email',
-    required: true,
-    placeholder: 'Enter your email',
-  },
-  {
-    type: 'number',
-    name: 'age',
-    label: 'Age',
-    min: 18,
-    max: 120,
-  },
-  {
-    type: 'select',
-    name: 'country',
-    label: 'Country',
-    options: [
-      { label: 'United States', value: 'us' },
-      { label: 'United Kingdom', value: 'uk' },
-      { label: 'Germany', value: 'de' },
-    ],
-  },
-  {
-    type: 'checkbox',
-    name: 'subscribe',
-    label: 'Subscribe to newsletter',
-  },
+const fields = [
+  { type: 'text', name: 'email', label: 'Email', required: true },
+  { type: 'number', name: 'age', label: 'Age', min: 18, max: 120 },
+  { type: 'select', name: 'country', label: 'Country', options: [
+    { label: 'United States', value: 'us' },
+    { label: 'Germany', value: 'de' },
+  ]},
+  { type: 'checkbox', name: 'subscribe', label: 'Subscribe to newsletter' },
 ] as const;
 
 function MyForm() {
@@ -111,13 +58,8 @@ function MyForm() {
     <FormGenerator
       fields={fields}
       onSubmit={(values) => {
-        // ✅ values is fully typed!
-        console.log(values.email);    // string
-        console.log(values.age);      // number
-        console.log(values.country);  // string
-        console.log(values.subscribe);// boolean
+        console.log(values); // Fully typed!
       }}
-      submitText="Create Account"
     />
   );
 }
@@ -125,77 +67,137 @@ function MyForm() {
 
 ---
 
+## Registering Custom Components
+
+Register your own UI components to replace the HTML fallbacks:
+
+```typescript
+import { registerFields, registerFormComponents } from '@connect-soft/form-generator';
+import { Input } from './ui/input';
+import { Label } from './ui/label';
+import { Checkbox } from './ui/checkbox';
+import { Button } from './ui/button';
+
+// Register field components
+registerFields({
+  text: ({ field, formField }) => (
+    <Input
+      {...formField}
+      type={field.fieldType || 'text'}
+      placeholder={field.placeholder}
+      disabled={field.disabled}
+    />
+  ),
+  number: ({ field, formField }) => (
+    <Input
+      {...formField}
+      type="number"
+      min={field.min}
+      max={field.max}
+    />
+  ),
+  checkbox: {
+    component: ({ field, formField }) => (
+      <Checkbox
+        checked={formField.value}
+        onCheckedChange={formField.onChange}
+        disabled={field.disabled}
+      />
+    ),
+    options: {
+      className: 'flex items-center gap-2',
+    }
+  },
+});
+
+// Register form wrapper components
+registerFormComponents({
+  FormItem: ({ children, className }) => <div className={className}>{children}</div>,
+  FormLabel: Label,
+  FormMessage: ({ children }) => <span className="text-red-500 text-sm">{children}</span>,
+  SubmitButton: Button,
+});
+```
+
+---
+
 ## Field Types
 
+Built-in HTML fallback types:
+
 | Type | Description | Value Type |
 |------|-------------|------------|
-| `text` | Text input (email, password, url, tel) | `string` |
-| `textarea` | Multi-line text input | `string` |
-| `number` | Number input with min/max/step | `number` |
-| `checkbox` | Checkbox input | `boolean` |
-| `switch` | Toggle switch | `boolean` |
+| `text` | Text input | `string` |
+| `email` | Email input | `string` |
+| `password` | Password input | `string` |
+| `number` | Number input with min/max | `number` |
+| `textarea` | Multi-line text | `string` |
+| `checkbox` | Checkbox | `boolean` |
 | `select` | Dropdown select | `string` |
 | `radio` | Radio button group | `string` |
-| `date` | Date picker (react-day-picker) | `Date` |
-| `dateRange` | Date range picker | `{from: Date, to?: Date}` |
-| `time` | Time picker (HH:mm) | `string` |
+| `date` | Date input | `Date` |
+| `time` | Time input | `string` |
+| `file` | File input | `File` |
+| `hidden` | Hidden input | `string` |
 
----
+### Adding Custom Field Types (TypeScript)
 
-## Advanced Components
-
-### MultiSelect
+Extend the `FieldTypeRegistry` interface to add type checking for custom fields:
 
 ```typescript
-import { MultiSelect } from '@connect-soft/form-generator/advanced';
-
-<MultiSelect
-  options={[
-    { label: 'React', value: 'react' },
-    { label: 'Vue', value: 'vue' },
-    { label: 'Angular', value: 'angular' },
-  ]}
-  value={selected}
-  onChange={setSelected}
-  placeholder="Select frameworks..."
-/>
+// types/form-generator.d.ts
+import { CreateFieldType } from '@connect-soft/form-generator';
+
+declare module '@connect-soft/form-generator' {
+  interface FieldTypeRegistry {
+    // Add your custom field types
+    'color-picker': CreateFieldType<'color-picker', string, {
+      swatches?: string[];
+      showAlpha?: boolean;
+    }>;
+    'rich-text': CreateFieldType<'rich-text', string, {
+      toolbar?: ('bold' | 'italic' | 'link')[];
+      maxLength?: number;
+    }>;
+  }
+}
 ```
 
-### ColorPicker
+Now TypeScript will recognize your custom field types:
 
 ```typescript
-import { ColorPicker } from '@connect-soft/form-generator/advanced';
-
-<ColorPicker
-  value={color}
-  onChange={setColor}
-/>
+const fields = [
+  { type: 'color-picker', name: 'theme', swatches: ['#fff', '#000'] }, // ✅ Valid
+  { type: 'unknown-type', name: 'test' }, // ❌ Type error
+] as const;
 ```
 
-### TransferList
+Don't forget to register the component for your custom field:
 
 ```typescript
-import { TransferList } from '@connect-soft/form-generator/advanced';
-
-<TransferList
-  options={allOptions}
-  value={selectedValues}
-  onChange={setSelectedValues}
-  leftTitle="Available"
-  rightTitle="Selected"
-  searchable={true}
-/>
+import { registerField } from '@connect-soft/form-generator';
+import { ColorPicker } from './components/ColorPicker';
+
+registerField('color-picker', ({ field, formField }) => (
+  <ColorPicker
+    value={formField.value}
+    onChange={formField.onChange}
+    swatches={field.swatches}
+    showAlpha={field.showAlpha}
+  />
+));
 ```
 
 ---
 
 ## Custom Validation
 
-Use Zod for schema validation:
+Use Zod for field-level or form-level validation:
 
 ```typescript
 import { z } from 'zod';
 
+// Field-level validation
 const fields = [
   {
     type: 'text',
@@ -207,106 +209,159 @@ const fields = [
     type: 'text',
     name: 'email',
     label: 'Email',
-    fieldType: 'email',
-    validation: z.string().email().endsWith('@company.com'),
-  },
-  {
-    type: 'number',
-    name: 'age',
-    label: 'Age',
-    validation: z.number().min(18).max(120),
+    validation: z.string().email(),
   },
 ] as const;
-```
 
----
+// Or use a full schema for type inference
+const schema = z.object({
+  username: z.string().min(3),
+  email: z.string().email(),
+});
 
-## Styling
-
-### Using Tailwind Classes
-
-```typescript
-{
-  type: 'text',
-  name: 'email',
-  className: 'bg-blue-50 border-blue-300 focus:ring-blue-500',
-}
-```
-
-### Form-Level Styling
-
-```typescript
 <FormGenerator
   fields={fields}
-  onSubmit={handleSubmit}
-  className="max-w-md mx-auto p-6 bg-white rounded-lg shadow"
+  schema={schema}
+  onSubmit={(values) => {
+    // values is inferred from schema
+  }}
 />
 ```
 
-### Custom Theme
+---
 
-Override CSS variables in your global CSS:
+## Layouts
 
-```css
-:root {
-  --primary: 220 90% 56%;
-  --primary-foreground: 0 0% 100%;
-  --radius: 0.5rem;
-}
+Organize fields with sections and columns:
+
+```typescript
+const fields = [
+  {
+    type: 'section',
+    title: 'Personal Information',
+    children: [
+      { type: 'text', name: 'firstName', label: 'First Name' },
+      { type: 'text', name: 'lastName', label: 'Last Name' },
+    ],
+  },
+  {
+    type: 'columns',
+    columns: [
+      {
+        width: '1',
+        children: [
+          { type: 'text', name: 'city', label: 'City' },
+        ],
+      },
+      {
+        width: '1',
+        children: [
+          { type: 'text', name: 'zip', label: 'ZIP Code' },
+        ],
+      },
+    ],
+  },
+];
 ```
 
 ---
 
 ## TypeScript Type Inference
 
-The library provides full type inference for form values:
+Get full type inference from field definitions:
 
 ```typescript
 const fields = [
-  { type: 'text', name: 'email', fieldType: 'email' },
-  { type: 'number', name: 'age' },
+  { type: 'text', name: 'email', required: true },
+  { type: 'number', name: 'age', required: true },
   { type: 'checkbox', name: 'terms' },
-  { type: 'date', name: 'birthdate' },
 ] as const;
 
 <FormGenerator
   fields={fields}
   onSubmit={(values) => {
-    // ✅ Fully typed!
-    values.email;     // string
-    values.age;       // number
-    values.terms;     // boolean
-    values.birthdate; // Date
+    values.email;  // string
+    values.age;    // number
+    values.terms;  // boolean | undefined
   }}
 />
 ```
 
----
+Or provide an explicit Zod schema:
+
+```typescript
+const schema = z.object({
+  email: z.string().email(),
+  age: z.number().min(18),
+  terms: z.boolean(),
+});
 
-## Migration from v1.x
+<FormGenerator
+  fields={fields}
+  schema={schema}
+  onSubmit={(values) => {
+    // values: { email: string; age: number; terms: boolean }
+  }}
+/>
+```
 
-Migrating from `@connect-soft/mui-hook-form` v1.x? See the [MIGRATION.md](./MIGRATION.md) guide.
+---
 
-### Quick Migration with Adapter
+## Imperative API (Ref)
+
+Access form methods programmatically using a ref:
 
 ```typescript
-import { FormGenerator } from '@connect-soft/form-generator';
-import { adaptV1FieldsToV2 } from '@connect-soft/form-generator/adapters';
+import { useRef } from 'react';
+import { FormGenerator, FormGeneratorRef } from '@connect-soft/form-generator';
 
-// Your existing v1 fields
-const v1Fields = [
-  {
-    type: 'textField',
-    props: { name: 'email', label: 'Email', required: true },
-  },
-];
+function MyForm() {
+  const formRef = useRef<FormGeneratorRef>(null);
 
-// Auto-convert to v2
-const v2Fields = adaptV1FieldsToV2(v1Fields);
+  const handleExternalSubmit = async () => {
+    await formRef.current?.submit();
+  };
 
-<FormGenerator fields={v2Fields} onSubmit={handleSubmit} />
+  const handleReset = () => {
+    formRef.current?.reset();
+  };
+
+  const handleSetValues = () => {
+    formRef.current?.setValues({
+      email: 'test@example.com',
+      age: 25,
+    });
+  };
+
+  return (
+    <>
+      <FormGenerator
+        ref={formRef}
+        fields={fields}
+        onSubmit={(values) => console.log(values)}
+      />
+      <button type="button" onClick={handleExternalSubmit}>Submit Externally</button>
+      <button type="button" onClick={handleReset}>Reset Form</button>
+      <button type="button" onClick={handleSetValues}>Set Values</button>
+    </>
+  );
+}
 ```
 
+### Available Ref Methods
+
+| Method | Description |
+|--------|-------------|
+| `setValues(values)` | Set form values (partial update) |
+| `getValues()` | Get current form values |
+| `reset(values?)` | Reset to default or provided values |
+| `submit()` | Programmatically submit the form |
+| `clearErrors()` | Clear all validation errors |
+| `setError(name, error)` | Set error for a specific field |
+| `isValid()` | Check if form passes validation |
+| `isDirty()` | Check if form has unsaved changes |
+| `form` | Access underlying react-hook-form instance |
+
 ---
 
 ## API Reference
@@ -315,12 +370,12 @@ const v2Fields = adaptV1FieldsToV2(v1Fields);
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `fields` | `Field[]` | **required** | Array of field definitions |
+| `fields` | `FormItem[]` | **required** | Array of field definitions |
 | `onSubmit` | `(values) => void \| Promise<void>` | **required** | Form submission handler |
-| `defaultValues` | `Partial<InferFormValues<TFields>>` | `{}` | Initial form values |
-| `className` | `string` | - | Tailwind classes for form container |
+| `schema` | `ZodType` | - | Optional Zod schema for validation |
+| `defaultValues` | `object` | `{}` | Initial form values |
+| `className` | `string` | - | CSS class for form element |
 | `submitText` | `string` | `'Submit'` | Submit button text |
-| `submitButtonVariant` | `'default' \| 'destructive' \| 'outline' \| 'secondary' \| 'ghost' \| 'link'` | `'default'` | Submit button style |
 | `disabled` | `boolean` | `false` | Disable entire form |
 | `mode` | `'onChange' \| 'onBlur' \| 'onSubmit' \| 'onTouched' \| 'all'` | `'onChange'` | Validation trigger mode |
 
@@ -337,13 +392,12 @@ const v2Fields = adaptV1FieldsToV2(v1Fields);
 | `hidden` | `boolean` | Hide field |
 | `defaultValue` | `any` | Default field value |
 | `validation` | `ZodType` | Zod validation schema |
-| `className` | `string` | Tailwind classes for field |
+| `className` | `string` | CSS class for field wrapper |
 
 ---
 
 ## Links
 
-- [Migration Guide](./MIGRATION.md)
 - [GitLab Repository](https://gitlab.com/connect-soft/components/form-generator)
 - [Issues](https://gitlab.com/connect-soft/components/form-generator/issues)
 
@@ -352,17 +406,3 @@ const v2Fields = adaptV1FieldsToV2(v1Fields);
 ## License
 
 ISC © Connect Soft
-
----
-
-## Acknowledgments
-
-Built with:
-- [Radix UI](https://www.radix-ui.com/) - Accessible UI primitives
-- [Tailwind CSS](https://tailwindcss.com/) - Utility-first CSS framework
-- [react-hook-form](https://react-hook-form.com/) - Performant form library
-- [Zod](https://zod.dev/) - TypeScript-first schema validation
-- [react-day-picker](https://react-day-picker.js.org/) - Flexible date picker
-- [lucide-react](https://lucide.dev/) - Beautiful icons
-
-Inspired by [shadcn/ui](https://ui.shadcn.com/) component architecture.