@connect-soft/form-generator 1.0.0-alpha → 1.1.0-alpha10

package/README.md

@@ -1,61 +1,1135 @@
 # @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
+- **Array Fields**: Repeatable field groups with `useFieldArray` integration
+- **Custom Layouts**: Full control over form layout via render props
+- **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. Field components are fully responsible for rendering their own label, description, and error messages:
+
+```typescript
+import { registerFields, registerFormComponent } 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 - they handle their own rendering
+registerFields({
+  text: ({ field, formField, fieldState }) => (
+    <div className="form-field">
+      {field.label && <Label>{field.label}{field.required && ' *'}</Label>}
+      <Input
+        {...formField}
+        type={field.fieldType || 'text'}
+        placeholder={field.placeholder}
+        disabled={field.disabled}
+      />
+      {field.description && <p className="text-sm text-muted">{field.description}</p>}
+      {fieldState.error && <span className="text-red-500 text-sm">{fieldState.error.message}</span>}
+    </div>
+  ),
+  number: ({ field, formField, fieldState }) => (
+    <div className="form-field">
+      {field.label && <Label>{field.label}</Label>}
+      <Input
+        {...formField}
+        type="number"
+        min={field.min}
+        max={field.max}
+      />
+      {fieldState.error && <span className="text-red-500 text-sm">{fieldState.error.message}</span>}
+    </div>
+  ),
+  checkbox: ({ field, formField }) => (
+    <div className="flex items-center gap-2">
+      <Checkbox
+        checked={formField.value}
+        onCheckedChange={formField.onChange}
+        disabled={field.disabled}
+      />
+      {field.label && <Label>{field.label}</Label>}
+    </div>
+  ),
+});
+
+// Register the submit button component
+registerFormComponent('SubmitButton', Button);
+
+// Optional: Register field wrappers for custom styling
+registerFormComponent('FieldWrapper', ({ children, name, type, className }) => (
+  <div className={`field-wrapper field-${type}`} data-field={name}>
+    {children}
+  </div>
+));
+
+registerFormComponent('FieldsWrapper', ({ children }) => (
+  <div className="form-fields">
+    {children}
+  </div>
+));
+```
+
+---
+
+## Field Wrappers
+
+Customize how fields are wrapped without modifying individual field components:
+
+### FieldWrapper
+
+Wraps each individual field. Receives the field's `name`, `type`, and `className`:
+
+```typescript
+registerFormComponent('FieldWrapper', ({ children, name, type, className }) => (
+  <div className={`form-group ${className || ''}`} data-field-type={type}>
+    {children}
+  </div>
+));
+```
+
+### FieldsWrapper
+
+Wraps all fields together (excludes the submit button). Useful for grid layouts:
+
+```typescript
+registerFormComponent('FieldsWrapper', ({ children, className }) => (
+  <div className={`grid grid-cols-2 gap-4 ${className || ''}`}>
+    {children}
+  </div>
+));
+```
+
+Both default to `React.Fragment`, adding zero DOM overhead when not customized.
+
+---
+
+## 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;
+```
+
+Then register the component for your custom field:
+
+```typescript
+import { registerField } from '@connect-soft/form-generator';
+import { ColorPicker } from './components/ColorPicker';
+
+// Type-safe: 'color-picker' must exist in FieldTypeRegistry
+registerField('color-picker', ({ field, formField }) => (
+  <ColorPicker
+    value={formField.value}
+    onChange={formField.onChange}
+    swatches={field.swatches}
+    showAlpha={field.showAlpha}
+  />
+));
+
+// ❌ TypeScript error: 'unknown-type' is not in FieldTypeRegistry
+// registerField('unknown-type', MyComponent);
+```
+
+> **Note:** Both `registerField` and `registerFields` enforce that field types must be defined in `FieldTypeRegistry`. This ensures type safety between your type definitions and runtime registrations.
+
+### Field Type Validation Helpers
+
+Use helper functions for strict type checking without `as const`:
+
+```typescript
+import { createField, createArrayField, strictFields } from '@connect-soft/form-generator';
+
+// Create a single field with full type checking
+const emailField = createField({
+  type: 'email',
+  name: 'email',
+  label: 'Email',
+  placeholder: 'Enter your email'  // TypeScript knows this is valid for email
+});
+
+// Create an array field
+const contacts = createArrayField({
+  name: 'contacts',
+  fields: [
+    { type: 'text', name: 'name', label: 'Name' },
+    { type: 'email', name: 'email', label: 'Email' }
+  ],
+  minItems: 1,
+  maxItems: 5
+});
+
+// Create an array of fields with type checking
+const fields = strictFields([
+  { type: 'text', name: 'username', label: 'Username' },
+  { type: 'email', name: 'email', label: 'Email' },
+  // { type: 'unknown', name: 'bad' }  // TypeScript error!
+]);
+```
+
+### Runtime Field Type Validation
+
+Enable runtime validation to catch unregistered field types during development:
+
+```typescript
+// Warn in console for unregistered types (recommended for development)
+<FormGenerator
+  fields={fields}
+  onSubmit={handleSubmit}
+  validateTypes
+/>
+
+// Throw an error for unregistered types
+<FormGenerator
+  fields={fields}
+  onSubmit={handleSubmit}
+  validateTypes={{ throwOnError: true }}
+/>
+
+// Manual validation
+import { validateFieldTypes, getRegisteredFieldTypes } from '@connect-soft/form-generator';
+
+const registeredTypes = getRegisteredFieldTypes();
+validateFieldTypes(fields, registeredTypes, { throwOnError: true });
+```
+
+---
+
+## 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
+  }}
+/>
+```
+
+---
+
+## Array Fields
+
+Create repeatable field groups with `useFieldArray` integration:
+
+```typescript
+const fields = [
+  { type: 'text', name: 'name', label: 'Name' },
   {
-    type: 'number',
-    name: 'age',
-    label: 'Age',
-    min: 18,
+    type: 'array',
+    name: 'contacts',
+    label: 'Contacts',
+    fields: [
+      { type: 'text', name: 'email', label: 'Email' },
+      { type: 'text', name: 'phone', label: 'Phone' },
+    ],
+    minItems: 1,
+    maxItems: 5,
   },
 ] as const;
+```
 
-export const MyForm = () => (
-  <FormGenerator
-    fields={fields}
-    onSubmit={(values) => {
-      // values is fully typed!
-      console.log(values);
-    }}
-  />
-);
+### Default Array Rendering
+
+Array fields render automatically with add/remove functionality:
+
+```typescript
+<FormGenerator
+  fields={fields}
+  onSubmit={(values) => {
+    console.log(values.contacts); // Array<{ email: string, phone: string }>
+  }}
+/>
+```
+
+### Custom Array Rendering with useArrayField
+
+For full control, use the `useArrayField` hook in a custom layout:
+
+```typescript
+import { FormGenerator, useArrayField } from '@connect-soft/form-generator';
+
+<FormGenerator fields={fields} onSubmit={handleSubmit}>
+  {({ fields, arrays, buttons }) => {
+    const contacts = useArrayField(arrays.contacts.field);
+
+    return (
+      <div>
+        {fields.name}
+
+        <h3>Contacts</h3>
+        {contacts.items.map(({ id, index, remove, fields: itemFields }) => (
+          <div key={id} className="contact-row">
+            {itemFields.email}
+            {itemFields.phone}
+            {contacts.canRemove && (
+              <button type="button" onClick={remove}>Remove</button>
+            )}
+          </div>
+        ))}
+
+        {contacts.canAppend && (
+          <button type="button" onClick={contacts.append}>
+            Add Contact
+          </button>
+        )}
+
+        {buttons.submit}
+      </div>
+    );
+  }}
+</FormGenerator>
+```
+
+### useArrayField Return Values
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `items` | `Array<{ id, index }>` | Array items with unique ids |
+| `append` | `() => void` | Add new empty item |
+| `appendWith` | `(values) => void` | Add item with values |
+| `prepend` | `() => void` | Add item at beginning |
+| `remove` | `(index) => void` | Remove item at index |
+| `move` | `(from, to) => void` | Move item |
+| `swap` | `(a, b) => void` | Swap two items |
+| `insert` | `(index, values?) => void` | Insert at index |
+| `canAppend` | `boolean` | Can add more items (respects maxItems) |
+| `canRemove` | `boolean` | Can remove items (respects minItems) |
+| `renderField` | `(index, name) => ReactElement` | Render single field |
+| `renderItem` | `(index) => Record<string, ReactElement>` | Render all fields for item |
+
+---
+
+## Custom Layouts
+
+For full control over form layout, pass a render function as `children`:
+
+```typescript
+<FormGenerator
+  fields={[
+    { type: 'text', name: 'email', label: 'Email' },
+    { type: 'password', name: 'password', label: 'Password' },
+  ] as const}
+  title="Login"
+  onSubmit={handleSubmit}
+>
+  {({ fields, buttons, title }) => (
+    <div className="login-form">
+      <h1>{title}</h1>
+      <div className="field-row">{fields.email}</div>
+      <div className="field-row">{fields.password}</div>
+      <div className="actions">{buttons.submit}</div>
+    </div>
+  )}
+</FormGenerator>
+```
+
+### Render Props API
+
+The render function receives:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `fields` | `TemplateFields` | Pre-rendered fields (see below) |
+| `arrays` | `Record<string, TemplateArrayField>` | Array field definitions (use with `useArrayField`) |
+| `buttons` | `{ submit, reset? }` | Pre-rendered buttons |
+| `title` | `string` | Form title prop |
+| `description` | `string` | Form description prop |
+| `form` | `UseFormReturn` | react-hook-form instance |
+| `isSubmitting` | `boolean` | Form submission state |
+| `isValid` | `boolean` | Form validity state |
+| `isDirty` | `boolean` | Form dirty state |
+| `renderField` | `function` | Manual field renderer |
+| `FieldWrapper` | `ComponentType` | Registered FieldWrapper component |
+| `FieldsWrapper` | `ComponentType` | Registered FieldsWrapper component |
+
+### Fields Object
+
+Access fields by name or use helper methods:
+
+```typescript
+{({ fields }) => (
+  <div>
+    {/* Access individual fields */}
+    {fields.email}
+    {fields.password}
+
+    {/* Render all fields */}
+    {fields.all}
+
+    {/* Render only fields not yet accessed */}
+    {fields.remaining}
+
+    {/* Check if field exists */}
+    {fields.has('email') && fields.email}
+
+    {/* Get all field names */}
+    {fields.names.map(name => <div key={name}>{fields[name]}</div>)}
+
+    {/* Render specific fields */}
+    {fields.render('email', 'password')}
+  </div>
+)}
+```
+
+### Mixed Layout Example
+
+Highlight specific fields while rendering the rest normally:
+
+```typescript
+<FormGenerator fields={fieldDefinitions} onSubmit={handleSubmit}>
+  {({ fields, buttons }) => (
+    <div>
+      <div className="highlighted">{fields.email}</div>
+      <div className="other-fields">{fields.remaining}</div>
+      {buttons.submit}
+    </div>
+  )}
+</FormGenerator>
+```
+
+### Form State Access
+
+Use form state for conditional rendering:
+
+```typescript
+<FormGenerator fields={fieldDefinitions} onSubmit={handleSubmit}>
+  {({ fields, buttons, isSubmitting, isValid, isDirty }) => (
+    <div>
+      {fields.all}
+      <button type="submit" disabled={isSubmitting || !isValid}>
+        {isSubmitting ? 'Saving...' : 'Submit'}
+      </button>
+      {isDirty && <span>You have unsaved changes</span>}
+    </div>
+  )}
+</FormGenerator>
+```
+
+---
+
+## Raw Field Props with useFieldProps
+
+For complete control over field rendering, use the `useFieldProps` hook to get raw form binding props. This is useful when you want to create custom field components without registering them globally.
+
+```typescript
+import { FormGenerator, useFieldProps } from '@connect-soft/form-generator';
+
+const fields = [
+  { type: 'text', name: 'email', label: 'Email', required: true },
+  { type: 'password', name: 'password', label: 'Password' },
+] as const;
+
+// Custom component using the hook
+function CustomEmailField() {
+  const { value, onChange, onBlur, ref, field, fieldState } = useFieldProps<string>('email');
+
+  return (
+    <div className="my-custom-field">
+      <label>{field.label}{field.required && ' *'}</label>
+      <input
+        ref={ref}
+        type="email"
+        value={value ?? ''}
+        onChange={(e) => onChange(e.target.value)}
+        onBlur={onBlur}
+        placeholder={field.placeholder}
+      />
+      {fieldState.error && (
+        <span className="error">{fieldState.error.message}</span>
+      )}
+    </div>
+  );
+}
+
+// Use in FormGenerator with custom layout
+<FormGenerator fields={fields} onSubmit={handleSubmit}>
+  {({ fields, buttons }) => (
+    <div>
+      <CustomEmailField />
+      {fields.password}  {/* Mix with pre-rendered fields */}
+      {buttons.submit}
+    </div>
+  )}
+</FormGenerator>
+```
+
+### useFieldProps Return Value
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `name` | `string` | Field name (with any prefix applied) |
+| `value` | `TValue` | Current field value |
+| `onChange` | `(value: TValue) => void` | Change handler |
+| `onBlur` | `() => void` | Blur handler |
+| `ref` | `Ref<any>` | Ref to attach to input element |
+| `field` | `BaseField` | Full field definition (type, label, required, etc.) |
+| `fieldState` | `FieldState` | Validation state (see below) |
+
+### FieldState Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `invalid` | `boolean` | Whether the field has validation errors |
+| `error` | `{ type: string; message?: string }` | Error details if invalid |
+| `isDirty` | `boolean` | Whether the value has changed from default |
+| `isTouched` | `boolean` | Whether the field has been focused and blurred |
+
+### When to Use useFieldProps vs Registered Components
+
+| Use Case | Approach |
+|----------|----------|
+| Reusable field component across forms | Register with `registerField` |
+| One-off custom field in a specific form | Use `useFieldProps` |
+| Need full control over a single field | Use `useFieldProps` |
+| Consistent field styling across app | Register with `registerField` |
+
+### Example: Complete Custom Form
+
+```typescript
+import { FormGenerator, useFieldProps } from '@connect-soft/form-generator';
+
+const fields = [
+  { type: 'text', name: 'firstName', label: 'First Name', required: true },
+  { type: 'text', name: 'lastName', label: 'Last Name', required: true },
+  { type: 'email', name: 'email', label: 'Email', required: true },
+] as const;
+
+function NameFields() {
+  const firstName = useFieldProps<string>('firstName');
+  const lastName = useFieldProps<string>('lastName');
+
+  return (
+    <div className="name-row">
+      <div className="field">
+        <label>{firstName.field.label}</label>
+        <input
+          ref={firstName.ref}
+          value={firstName.value ?? ''}
+          onChange={(e) => firstName.onChange(e.target.value)}
+          onBlur={firstName.onBlur}
+        />
+        {firstName.fieldState.error && (
+          <span className="error">{firstName.fieldState.error.message}</span>
+        )}
+      </div>
+      <div className="field">
+        <label>{lastName.field.label}</label>
+        <input
+          ref={lastName.ref}
+          value={lastName.value ?? ''}
+          onChange={(e) => lastName.onChange(e.target.value)}
+          onBlur={lastName.onBlur}
+        />
+        {lastName.fieldState.error && (
+          <span className="error">{lastName.fieldState.error.message}</span>
+        )}
+      </div>
+    </div>
+  );
+}
+
+function MyForm() {
+  return (
+    <FormGenerator fields={fields} onSubmit={handleSubmit}>
+      {({ fields, buttons, isSubmitting }) => (
+        <div className="custom-form">
+          <NameFields />
+          {fields.email}
+          <button type="submit" disabled={isSubmitting}>
+            {isSubmitting ? 'Submitting...' : 'Submit'}
+          </button>
+        </div>
+      )}
+    </FormGenerator>
+  );
+}
+```
+
+---
+
+## Type-Safe Forms with StrictFormGenerator
+
+For maximum type safety, use `StrictFormGenerator` which requires a Zod schema. This ensures field names match your schema and provides fully typed form values.
+
+```typescript
+import { StrictFormGenerator } from '@connect-soft/form-generator';
+import { z } from 'zod';
+
+const userSchema = z.object({
+  email: z.string().email('Invalid email'),
+  password: z.string().min(8, 'Password must be at least 8 characters'),
+  age: z.number().min(18, 'Must be 18 or older'),
+});
+
+<StrictFormGenerator
+  schema={userSchema}
+  fields={[
+    { type: 'email', name: 'email', label: 'Email' },      // name must be keyof schema
+    { type: 'password', name: 'password', label: 'Password' },
+    { type: 'number', name: 'age', label: 'Age' },
+    // { type: 'text', name: 'invalid' }  // TypeScript error: 'invalid' not in schema
+  ]}
+  onSubmit={(values) => {
+    // values: { email: string; password: string; age: number }
+    console.log(values.email);  // Fully typed!
+  }}
+/>
+```
+
+### Typed Field Helpers
+
+Use helper functions for even stricter type checking:
+
+```typescript
+import { StrictFormGenerator, createFieldFactory } from '@connect-soft/form-generator';
+import { z } from 'zod';
+
+const loginSchema = z.object({
+  email: z.string().email(),
+  password: z.string(),
+  rememberMe: z.boolean(),
+});
+
+// Create a typed field factory from schema
+const defineField = createFieldFactory(loginSchema);
+
+// Each field is validated against the schema
+const fields = [
+  defineField({ type: 'email', name: 'email', label: 'Email' }),
+  defineField({ type: 'password', name: 'password', label: 'Password' }),
+  defineField({ type: 'checkbox', name: 'rememberMe', label: 'Remember Me' }),
+];
+
+<StrictFormGenerator
+  schema={loginSchema}
+  fields={fields}
+  onSubmit={handleSubmit}
+/>
+```
+
+### StrictFormGenerator vs FormGenerator
+
+| Feature | FormGenerator | StrictFormGenerator |
+|---------|---------------|---------------------|
+| Schema | No (infers from fields) | Required (Zod) |
+| Field name checking | Inferred from fields | Enforced at compile-time |
+| Type inference | From field definitions | From Zod schema |
+| Constraint detection | No | Yes (automatic) |
+| Use case | Quick prototyping | Production apps |
+
+### Automatic Schema Constraint Detection
+
+`StrictFormGenerator` automatically extracts constraints from your Zod schema and propagates them to field components. This means you don't need to duplicate constraints in both your schema and field definitions.
+
+#### Supported Constraints
+
+**Number fields** (`z.number()`):
+| Zod Method | Field Property | Example |
+|------------|----------------|---------|
+| `.min(n)` | `min` | `z.number().min(0)` → `{ min: 0 }` |
+| `.max(n)` | `max` | `z.number().max(100)` → `{ max: 100 }` |
+| `.int()` | `step: 1` | `z.number().int()` → `{ step: 1 }` |
+| `.multipleOf(n)` | `step` | `z.number().multipleOf(0.01)` → `{ step: 0.01 }` |
+| `.positive()` | `min` | `z.number().positive()` → `{ min: 0 }` (exclusive) |
+| `.nonnegative()` | `min: 0` | `z.number().nonnegative()` → `{ min: 0 }` |
+
+**String fields** (`z.string()`):
+| Zod Method | Field Property | Example |
+|------------|----------------|---------|
+| `.min(n)` | `minLength` | `z.string().min(3)` → `{ minLength: 3 }` |
+| `.max(n)` | `maxLength` | `z.string().max(100)` → `{ maxLength: 100 }` |
+| `.length(n)` | `minLength` + `maxLength` | `z.string().length(6)` → `{ minLength: 6, maxLength: 6 }` |
+| `.regex(pattern)` | `pattern` | `z.string().regex(/^[A-Z]+$/)` → `{ pattern: '^[A-Z]+$' }` |
+
+**Date fields** (`z.date()`):
+| Zod Method | Field Property | Example |
+|------------|----------------|---------|
+| `.min(date)` | `min` (ISO string) | `z.date().min(new Date('2020-01-01'))` → `{ min: '2020-01-01' }` |
+| `.max(date)` | `max` (ISO string) | `z.date().max(new Date('2030-12-31'))` → `{ max: '2030-12-31' }` |
+
+#### Example
+
+```typescript
+import { StrictFormGenerator } from '@connect-soft/form-generator';
+import { z } from 'zod';
+
+const userSchema = z.object({
+  username: z.string().min(3).max(20).regex(/^[a-z0-9_]+$/),
+  age: z.number().int().min(18).max(120),
+  price: z.number().multipleOf(0.01).min(0),
+  birthDate: z.date().min(new Date('1900-01-01')).max(new Date()),
+});
+
+// No need to specify min/max/minLength/maxLength in fields!
+// They are automatically extracted from the schema
+<StrictFormGenerator
+  schema={userSchema}
+  fields={[
+    { type: 'text', name: 'username', label: 'Username' },
+    { type: 'number', name: 'age', label: 'Age' },
+    { type: 'number', name: 'price', label: 'Price' },
+    { type: 'date', name: 'birthDate', label: 'Birth Date' },
+  ]}
+  onSubmit={handleSubmit}
+/>
+
+// Field components receive:
+// username: { minLength: 3, maxLength: 20, pattern: '^[a-z0-9_]+$', required: true }
+// age: { min: 18, max: 120, step: 1, required: true }
+// price: { min: 0, step: 0.01, required: true }
+// birthDate: { min: '1900-01-01', max: '2026-02-02', required: true }
+```
+
+#### Using Constraints in Field Components
+
+Your registered field components can use these constraints directly:
+
+```typescript
+registerField('number', ({ field, formField, fieldState }) => (
+  <div>
+    <label>{field.label}</label>
+    <input
+      type="number"
+      {...formField}
+      min={field.min}
+      max={field.max}
+      step={field.step}
+    />
+    {fieldState.error && <span>{fieldState.error.message}</span>}
+  </div>
+));
+
+registerField('text', ({ field, formField, fieldState }) => (
+  <div>
+    <label>{field.label}</label>
+    <input
+      type="text"
+      {...formField}
+      minLength={field.minLength}
+      maxLength={field.maxLength}
+      pattern={field.pattern}
+    />
+    {fieldState.error && <span>{fieldState.error.message}</span>}
+  </div>
+));
+```
+
+#### Manual Constraint Merging
+
+You can also manually merge constraints using the utility functions:
+
+```typescript
+import { mergeSchemaConstraints, analyzeSchema } from '@connect-soft/form-generator';
+
+const schema = z.object({
+  age: z.number().min(0).max(120),
+  name: z.string().min(1).max(100),
+});
+
+// Analyze schema to get field info
+const fieldInfo = analyzeSchema(schema);
+// => [
+//   { name: 'age', type: 'number', required: true, min: 0, max: 120 },
+//   { name: 'name', type: 'string', required: true, minLength: 1, maxLength: 100 }
+// ]
+
+// Or merge constraints into existing fields
+const fields = [
+  { type: 'number', name: 'age', label: 'Age' },
+  { type: 'text', name: 'name', label: 'Name' },
+];
+
+const fieldsWithConstraints = mergeSchemaConstraints(schema, fields);
+// => [
+//   { type: 'number', name: 'age', label: 'Age', required: true, min: 0, max: 120 },
+//   { type: 'text', name: 'name', label: 'Name', required: true, minLength: 1, maxLength: 100 }
+// ]
 ```
 
-## Documentation
+### Available Helpers
+
+| Helper | Description |
+|--------|-------------|
+| `createFieldFactory(schema)` | Create a field factory for a schema |
+| `typedField<typeof schema>()` | Create a single typed field |
+| `typedFields<typeof schema>([...])` | Create an array of typed fields |
+
+---
+
+## 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;
+
+<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>
+    </>
+  );
+}
+```
+
+### 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 |
+
+### Watching Form Values
+
+Detect when field values change from the parent component:
+
+```typescript
+import { useRef, useEffect } from 'react';
+import { FormGenerator, FormGeneratorRef } from '@connect-soft/form-generator';
+
+function MyForm() {
+  const formRef = useRef<FormGeneratorRef>(null);
+
+  useEffect(() => {
+    // Watch all fields for changes
+    const subscription = formRef.current?.form.watch((values, { name, type }) => {
+      console.log('Changed field:', name);
+      console.log('New values:', values);
+    });
+
+    return () => subscription?.unsubscribe();
+  }, []);
+
+  return (
+    <FormGenerator
+      ref={formRef}
+      fields={fields}
+      onSubmit={handleSubmit}
+    />
+  );
+}
+```
+
+Or use `useWatch` inside a custom layout:
+
+```typescript
+import { FormGenerator, useWatch } from '@connect-soft/form-generator';
+
+function ValueWatcher() {
+  const email = useWatch({ name: 'email' }); // Watch specific field
+
+  useEffect(() => {
+    console.log('Email changed:', email);
+  }, [email]);
+
+  return null;
+}
+
+<FormGenerator fields={fields} onSubmit={handleSubmit}>
+  {({ fields, buttons }) => (
+    <>
+      {fields.all}
+      <ValueWatcher />
+      {buttons.submit}
+    </>
+  )}
+</FormGenerator>
+```
+
+---
+
+## 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 |
+| `children` | `TemplateRenderFn` | - | Render function for custom layout |
+| `title` | `string` | - | Form title (available in render props) |
+| `description` | `string` | - | Form description (available in render props) |
+| `showReset` | `boolean` | `false` | Include reset button in `buttons.reset` |
+| `resetText` | `string` | `'Reset'` | Reset button text |
+| `validateTypes` | `boolean \| ValidateTypesOptions` | `false` | Runtime validation of field types |
+
+### 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 |
+
+### Field Type-Specific Properties
+
+**Text fields** (`text`, `email`, `password`, `tel`, `url`, `search`):
+| Property | Type | Description |
+|----------|------|-------------|
+| `placeholder` | `string` | Placeholder text |
+| `minLength` | `number` | Minimum character length |
+| `maxLength` | `number` | Maximum character length |
+| `pattern` | `string` | HTML5 validation pattern |
+
+**Number fields** (`number`, `range`):
+| Property | Type | Description |
+|----------|------|-------------|
+| `placeholder` | `string` | Placeholder text |
+| `min` | `number` | Minimum value |
+| `max` | `number` | Maximum value |
+| `step` | `number` | Step increment |
+
+**Date fields** (`date`, `datetime`, `datetime-local`):
+| Property | Type | Description |
+|----------|------|-------------|
+| `min` | `string` | Minimum date (ISO format: YYYY-MM-DD) |
+| `max` | `string` | Maximum date (ISO format: YYYY-MM-DD) |
+
+### Schema Analysis Utilities
+
+| Function | Description |
+|----------|-------------|
+| `analyzeSchema(schema)` | Extract detailed field info from Zod schema |
+| `mergeSchemaConstraints(schema, fields)` | Merge schema constraints into field definitions |
+| `mergeSchemaRequirements(schema, fields)` | Merge only required status (legacy) |
+| `getNumberConstraints(schema)` | Extract min/max/step from number schema |
+| `getStringConstraints(schema)` | Extract minLength/maxLength/pattern from string schema |
+| `getDateConstraints(schema)` | Extract min/max dates from date schema |
+| `isSchemaRequired(schema)` | Check if schema field is required |
+| `unwrapSchema(schema)` | Unwrap optional/nullable wrappers |
+| `getSchemaTypeName(schema)` | Get base type name (string, number, etc.) |
+
+---
+
+## 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