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

package/README.md

@@ -1,61 +1,407 @@
 # @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
 
-**v2.0.0** - Complete rewrite with Radix UI + Tailwind CSS
+[![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)
+
+---
 
 ## Features
 
-- ✨ Modern UI with Radix primitives + Tailwind CSS
-- 📦 50-60% smaller bundle (<80 KB gzipped)
-- 🎯 Full TypeScript type inference
-- 🔧 10+ field types with extensible API
-- ♿ Built-in accessibility
-- 🎨 Easy Tailwind customization
-- 🚀 Zero runtime CSS overhead
-- 🔄 v1→v2 migration 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
-pnpm add @connect-soft/form-generator react-hook-form zod
+npm install @connect-soft/form-generator
 ```
 
+### Peer Dependencies
+
+- `react` ^19.0.0
+- `react-dom` ^19.0.0
+- `zod` ^4.0.0
+
+---
+
 ## Quick Start
 
+The library works immediately with HTML fallback components:
+
 ```typescript
 import { FormGenerator } from '@connect-soft/form-generator';
 
 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() {
+  return (
+    <FormGenerator
+      fields={fields}
+      onSubmit={(values) => {
+        console.log(values); // Fully typed!
+      }}
+    />
+  );
+}
+```
+
+---
+
+## 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 | `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 input | `Date` |
+| `time` | Time input | `string` |
+| `file` | File input | `File` |
+| `hidden` | Hidden input | `string` |
+
+### Adding Custom Field Types (TypeScript)
+
+Extend the `FieldTypeRegistry` interface to add type checking for custom fields:
+
+```typescript
+// 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;
+    }>;
+  }
+}
+```
+
+Now TypeScript will recognize your custom field types:
+
+```typescript
+const fields = [
+  { type: 'color-picker', name: 'theme', swatches: ['#fff', '#000'] }, // ✅ Valid
+  { type: 'unknown-type', name: 'test' }, // ❌ Type error
+] as const;
+```
+
+Don't forget to register the component for your custom field:
+
+```typescript
+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 field-level or form-level validation:
+
+```typescript
+import { z } from 'zod';
+
+// Field-level validation
+const fields = [
+  {
+    type: 'text',
+    name: 'username',
+    label: 'Username',
+    validation: z.string().min(3).max(20).regex(/^[a-zA-Z0-9_]+$/),
+  },
   {
     type: 'text',
     name: 'email',
     label: 'Email',
-    fieldType: 'email',
-    required: true,
+    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(),
+});
+
+<FormGenerator
+  fields={fields}
+  schema={schema}
+  onSubmit={(values) => {
+    // values is inferred from schema
+  }}
+/>
+```
+
+---
+
+## Layouts
+
+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: 'number',
-    name: 'age',
-    label: 'Age',
-    min: 18,
+    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
+
+Get full type inference from field definitions:
+
+```typescript
+const fields = [
+  { type: 'text', name: 'email', required: true },
+  { type: 'number', name: 'age', required: true },
+  { type: 'checkbox', name: 'terms' },
 ] as const;
 
-export const MyForm = () => (
-  <FormGenerator
-    fields={fields}
-    onSubmit={(values) => {
-      // values is fully typed!
-      console.log(values);
-    }}
-  />
-);
+<FormGenerator
+  fields={fields}
+  onSubmit={(values) => {
+    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(),
+});
+
+<FormGenerator
+  fields={fields}
+  schema={schema}
+  onSubmit={(values) => {
+    // values: { email: string; age: number; terms: boolean }
+  }}
+/>
+```
+
+---
+
+## Imperative API (Ref)
+
+Access form methods programmatically using a ref:
+
+```typescript
+import { useRef } from 'react';
+import { FormGenerator, FormGeneratorRef } from '@connect-soft/form-generator';
+
+function MyForm() {
+  const formRef = useRef<FormGeneratorRef>(null);
+
+  const handleExternalSubmit = async () => {
+    await formRef.current?.submit();
+  };
+
+  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>
+    </>
+  );
+}
 ```
 
-## Documentation
+### 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
+
+### FormGenerator Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `fields` | `FormItem[]` | **required** | Array of field definitions |
+| `onSubmit` | `(values) => void \| Promise<void>` | **required** | Form submission handler |
+| `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 |
+| `disabled` | `boolean` | `false` | Disable entire form |
+| `mode` | `'onChange' \| 'onBlur' \| 'onSubmit' \| 'onTouched' \| 'all'` | `'onChange'` | Validation trigger mode |
+
+### Field Base Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `type` | `string` | Field type (text, number, select, etc.) |
+| `name` | `string` | Field name (must be unique) |
+| `label` | `string` | Field label |
+| `description` | `string` | Helper text below field |
+| `required` | `boolean` | Mark field as required |
+| `disabled` | `boolean` | Disable field |
+| `hidden` | `boolean` | Hide field |
+| `defaultValue` | `any` | Default field value |
+| `validation` | `ZodType` | Zod validation schema |
+| `className` | `string` | CSS class for field wrapper |
+
+---
+
+## Links
+
+- [GitLab Repository](https://gitlab.com/connect-soft/components/form-generator)
+- [Issues](https://gitlab.com/connect-soft/components/form-generator/issues)
 
-See [main README](../../README.md) for full documentation.
+---
 
 ## License
 

package/dist/index.js

@@ -1,10 +1,10 @@
 'use strict';
 
-var compilerRuntime = require('react/compiler-runtime');
 var jsxRuntime = require('react/jsx-runtime');
 var React = require('react');
 var n$1 = require('zod/v4/core');
 var zod = require('zod');
+var compilerRuntime = require('react/compiler-runtime');
 
 function _interopNamespaceDefault(e) {
     var n = Object.create(null);
@@ -3465,114 +3465,81 @@ function getItemKey(item, index) {
 function hasSchema(props) {
   return props.schema !== undefined;
 }
-function FormGenerator(props) {
-  const $ = compilerRuntime.c(20);
+function FormGeneratorImpl(props) {
   const {
     fields,
     defaultValues,
     className,
-    submitText: t0,
+    submitText = 'Submit',
     disabled,
-    mode: t1
+    mode = 'onChange',
+    ref
   } = props;
-  const submitText = t0 === undefined ? "Submit" : t0;
-  const mode = t1 === undefined ? "onChange" : t1;
   const userSchema = hasSchema(props) ? props.schema : undefined;
   const onSubmit = props.onSubmit;
-  let t2;
-  bb0: {
+  const formRef = React.useRef(null);
+  const schema = React.useMemo(() => {
     if (userSchema) {
-      t2 = userSchema;
-      break bb0;
+      return userSchema;
     }
-    let t3;
-    if ($[0] !== fields) {
-      t3 = buildSchema(fields);
-      $[0] = fields;
-      $[1] = t3;
-    } else {
-      t3 = $[1];
-    }
-    t2 = t3;
-  }
-  const schema = t2;
-  let t3;
-  if ($[2] !== defaultValues || $[3] !== fields) {
+    return buildSchema(fields);
+  }, [fields, userSchema]);
+  const mergedDefaultValues = React.useMemo(() => {
     const builtDefaults = buildDefaultValues(fields);
-    t3 = defaultValues ? deepMerge(builtDefaults, defaultValues) : builtDefaults;
-    $[2] = defaultValues;
-    $[3] = fields;
-    $[4] = t3;
-  } else {
-    t3 = $[4];
-  }
-  const mergedDefaultValues = t3;
-  let t4;
-  if ($[5] !== schema) {
-    t4 = a(schema);
-    $[5] = schema;
-    $[6] = t4;
-  } else {
-    t4 = $[6];
-  }
-  let t5;
-  if ($[7] !== mergedDefaultValues || $[8] !== mode || $[9] !== t4) {
-    t5 = {
-      resolver: t4,
-      defaultValues: mergedDefaultValues,
-      mode
-    };
-    $[7] = mergedDefaultValues;
-    $[8] = mode;
-    $[9] = t4;
-    $[10] = t5;
-  } else {
-    t5 = $[10];
-  }
-  const form = useForm(t5);
-  let t6;
-  if ($[11] !== className || $[12] !== disabled || $[13] !== fields || $[14] !== form || $[15] !== onSubmit || $[16] !== submitText) {
-    let t7;
-    if ($[18] !== onSubmit) {
-      t7 = async data => {
-        await onSubmit(data);
-      };
-      $[18] = onSubmit;
-      $[19] = t7;
-    } else {
-      t7 = $[19];
-    }
-    const handleSubmit = form.handleSubmit(t7);
-    const SubmitButton = getFormComponent("SubmitButton");
-    t6 = jsxRuntime.jsx(FormProvider, {
-      ...form,
-      children: jsxRuntime.jsxs("form", {
-        onSubmit: handleSubmit,
-        className,
-        children: [fields.map(_temp), jsxRuntime.jsx(SubmitButton, {
-          disabled: disabled || form.formState.isSubmitting,
-          isSubmitting: form.formState.isSubmitting,
-          children: submitText
-        })]
-      })
-    });
-    $[11] = className;
-    $[12] = disabled;
-    $[13] = fields;
-    $[14] = form;
-    $[15] = onSubmit;
-    $[16] = submitText;
-    $[17] = t6;
-  } else {
-    t6 = $[17];
-  }
-  return t6;
-}
-function _temp(item, index) {
-  return jsxRuntime.jsx(FormItemRenderer, {
-    item
-  }, getItemKey(item, index));
+    return defaultValues ? deepMerge(builtDefaults, defaultValues) : builtDefaults;
+  }, [fields, defaultValues]);
+  const form = useForm({
+    resolver: a(schema),
+    defaultValues: mergedDefaultValues,
+    mode
+  });
+  const handleSubmit = form.handleSubmit(async data => {
+    await onSubmit(data);
+  });
+  React.useImperativeHandle(ref, () => ({
+    setValues: values => {
+      Object.entries(values).forEach(([key, value]) => {
+        form.setValue(key, value, {
+          shouldValidate: true,
+          shouldDirty: true
+        });
+      });
+    },
+    getValues: () => form.getValues(),
+    reset: values_0 => {
+      if (values_0) {
+        form.reset(deepMerge(mergedDefaultValues, values_0));
+      } else {
+        form.reset(mergedDefaultValues);
+      }
+    },
+    submit: async () => {
+      await handleSubmit();
+    },
+    clearErrors: () => form.clearErrors(),
+    setError: (name, error) => form.setError(name, error),
+    isValid: () => form.formState.isValid,
+    isDirty: () => form.formState.isDirty,
+    form
+  }), [form, handleSubmit, mergedDefaultValues]);
+  const SubmitButton = getFormComponent('SubmitButton');
+  return jsxRuntime.jsx(FormProvider, {
+    ...form,
+    children: jsxRuntime.jsxs("form", {
+      ref: formRef,
+      onSubmit: handleSubmit,
+      className: className,
+      children: [fields.map((item, index) => jsxRuntime.jsx(FormItemRenderer, {
+        item: item
+      }, getItemKey(item, index))), jsxRuntime.jsx(SubmitButton, {
+        disabled: disabled || form.formState.isSubmitting,
+        isSubmitting: form.formState.isSubmitting,
+        children: submitText
+      })]
+    })
+  });
 }
+const FormGenerator = FormGeneratorImpl;
 
 Object.defineProperty(exports, "z", {
     enumerable: true,