@connect-soft/form-generator 1.1.0-alpha9 → 1.1.1

package/README.md

@@ -13,7 +13,7 @@
 - **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.)
+- **Imperative API**: Control form via ref (`setValues`, `reset`, `setDefaultValues`, `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
@@ -524,6 +524,69 @@ Highlight specific fields while rendering the rest normally:
 </FormGenerator>
 ```
 
+### Hook-Based Field Access with useTemplateField
+
+When you need to access fields from **child components** (not inline in the render function), use the `useTemplateField` hook. It returns the pre-rendered field element and marks it as accessed, so it won't appear in remaining fields.
+
+```typescript
+import { FormGenerator, useTemplateField, RemainingFields } from '@connect-soft/form-generator';
+
+// Child component that claims a field
+function EmailSection() {
+  const email = useTemplateField('email');
+  return <div className="highlighted">{email}</div>;
+}
+
+function PasswordSection() {
+  const password = useTemplateField('password');
+  return <div className="special">{password}</div>;
+}
+
+<FormGenerator fields={fieldDefinitions} onSubmit={handleSubmit}>
+  {({ buttons }) => (
+    <div>
+      <EmailSection />
+      <PasswordSection />
+      <div className="other-fields">
+        <RemainingFields />
+      </div>
+      {buttons.submit}
+    </div>
+  )}
+</FormGenerator>
+```
+
+**Why not just use `fields.remaining` with hooks?** The render function runs before child components render, so `fields.remaining` is evaluated before any hooks in child components mark fields as accessed. `<RemainingFields />` is a component that evaluates at its own render time — after sibling components above it have already claimed their fields.
+
+You can freely mix proxy access in the render function with hook access in child components:
+
+```typescript
+<FormGenerator fields={fieldDefinitions} onSubmit={handleSubmit}>
+  {({ fields, buttons }) => (
+    <div>
+      {/* Proxy access in the render function */}
+      <div className="hero">{fields.email}</div>
+      {/* Hook access in a child component */}
+      <PasswordSection />
+      {/* RemainingFields excludes both email and password */}
+      <RemainingFields />
+      {buttons.submit}
+    </div>
+  )}
+</FormGenerator>
+```
+
+#### useTemplateField
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `name` | `string` | Field name to retrieve |
+| **Returns** | `ReactElement \| undefined` | The pre-rendered field element, or `undefined` if not found |
+
+#### RemainingFields
+
+A component that renders all fields not yet accessed via `useTemplateField` or the fields proxy. Must be used within a `FormGenerator` custom layout.
+
 ### Form State Access
 
 Use form state for conditional rendering:
@@ -751,8 +814,138 @@ const fields = [
 | 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 }
+// ]
+```
+
 ### Available Helpers
 
 | Helper | Description |
@@ -830,6 +1023,23 @@ function MyForm() {
     });
   };
 
+  // Set values without marking the form as dirty
+  const handleLoadData = () => {
+    formRef.current?.setValues(
+      { email: 'loaded@api.com', age: 30 },
+      { shouldDirty: false }
+    );
+  };
+
+  // Set values and make them the new baseline for isDirty
+  const handleSetDefaults = () => {
+    formRef.current?.setDefaultValues({
+      email: 'new-default@example.com',
+      age: 25,
+    });
+    // isDirty is now false — these are the new default values
+  };
+
   return (
     <>
       <FormGenerator
@@ -840,6 +1050,8 @@ function MyForm() {
       <button type="button" onClick={handleExternalSubmit}>Submit Externally</button>
       <button type="button" onClick={handleReset}>Reset Form</button>
       <button type="button" onClick={handleSetValues}>Set Values</button>
+      <button type="button" onClick={handleLoadData}>Load Data</button>
+      <button type="button" onClick={handleSetDefaults}>Set Defaults</button>
     </>
   );
 }
@@ -849,9 +1061,10 @@ function MyForm() {
 
 | Method | Description |
 |--------|-------------|
-| `setValues(values)` | Set form values (partial update) |
+| `setValues(values, options?)` | Set form values (partial update). Options: `{ shouldDirty?, shouldValidate? }` |
 | `getValues()` | Get current form values |
 | `reset(values?)` | Reset to default or provided values |
+| `setDefaultValues(values)` | Set values and make them the new baseline for `isDirty` |
 | `submit()` | Programmatically submit the form |
 | `clearErrors()` | Clear all validation errors |
 | `setError(name, error)` | Set error for a specific field |
@@ -859,6 +1072,24 @@ function MyForm() {
 | `isDirty()` | Check if form has unsaved changes |
 | `form` | Access underlying react-hook-form instance |
 
+### SetValuesOptions
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `shouldDirty` | `boolean` | `true` | Whether setting the value marks the field as dirty |
+| `shouldValidate` | `boolean` | `true` | Whether to trigger validation after setting values |
+
+### setDefaultValues vs reset vs setValues
+
+| Method | Sets values | Resets dirty state | New dirty baseline |
+|--------|-------------|--------------------|--------------------|
+| `setValues(v)` | Yes | No (marks dirty) | No |
+| `setValues(v, { shouldDirty: false })` | Yes | No (keeps current) | No |
+| `reset(v)` | Yes | Yes | Yes (merges with original defaults) |
+| `setDefaultValues(v)` | Yes | Yes | Yes (merges with original defaults) |
+
+Use `setDefaultValues` when loading data from an API and you want the loaded values to become the "clean" baseline (e.g., editing an existing record). Use `setValues` with `{ shouldDirty: false }` when you want to set a value without affecting dirty tracking at all.
+
 ### Watching Form Values
 
 Detect when field values change from the parent component:
@@ -954,6 +1185,44 @@ function ValueWatcher() {
 | `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