@connect-soft/form-generator 1.1.0-alpha5 → 1.1.0-alpha7

package/README.md

@@ -16,7 +16,8 @@
 - **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
+- **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
 
@@ -69,58 +70,105 @@ function MyForm() {
 
 ## Registering Custom Components
 
-Register your own UI components to replace the HTML fallbacks:
+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, registerFormComponents } from '@connect-soft/form-generator';
+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
+// Register field components - they handle their own rendering
 registerFields({
-  text: ({ field, formField }) => (
-    <Input
-      {...formField}
-      type={field.fieldType || 'text'}
-      placeholder={field.placeholder}
-      disabled={field.disabled}
-    />
+  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 }) => (
-    <Input
-      {...formField}
-      type="number"
-      min={field.min}
-      max={field.max}
-    />
+  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: {
-    component: ({ field, formField }) => (
+  checkbox: ({ field, formField }) => (
+    <div className="flex items-center gap-2">
       <Checkbox
         checked={formField.value}
         onCheckedChange={formField.onChange}
         disabled={field.disabled}
       />
-    ),
-    options: {
-      className: 'flex items-center gap-2',
-    }
-  },
+      {field.label && <Label>{field.label}</Label>}
+    </div>
+  ),
 });
 
-// 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,
-});
+// 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:
@@ -230,40 +278,96 @@ const schema = z.object({
 
 ---
 
-## Layouts
+## Array Fields
 
-Organize fields with sections and columns:
+Create repeatable field groups with `useFieldArray` integration:
 
 ```typescript
 const fields = [
+  { type: 'text', name: 'name', label: 'Name' },
   {
-    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' },
-        ],
-      },
+    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;
+```
+
+### 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
@@ -297,7 +401,7 @@ The render function receives:
 | Property | Type | Description |
 |----------|------|-------------|
 | `fields` | `TemplateFields` | Pre-rendered fields (see below) |
-| `layouts` | `TemplateLayouts` | Pre-rendered named layouts |
+| `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 |
@@ -306,7 +410,8 @@ The render function receives:
 | `isValid` | `boolean` | Form validity state |
 | `isDirty` | `boolean` | Form dirty state |
 | `renderField` | `function` | Manual field renderer |
-| `renderLayout` | `function` | Manual layout renderer |
+| `FieldWrapper` | `ComponentType` | Registered FieldWrapper component |
+| `FieldsWrapper` | `ComponentType` | Registered FieldsWrapper component |
 
 ### Fields Object