@connect-soft/form-generator 1.1.0-alpha8 → 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:
@@ -544,6 +607,355 @@ Use form state for conditional rendering:
 
 ---
 
+## 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 }
+// ]
+```
+
+### 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:
@@ -611,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
@@ -621,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>
     </>
   );
 }
@@ -630,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 |
@@ -640,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:
@@ -735,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