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

package/README.md

@@ -220,12 +220,13 @@ const fields = [
 ] as const;
 ```
 
-Don't forget to register the component for your custom field:
+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}
@@ -234,6 +235,71 @@ registerField('color-picker', ({ field, formField }) => (
     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 });
 ```
 
 ---
@@ -478,6 +544,225 @@ 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 |
+| Use case | Quick prototyping | Production apps |
+
+### 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:
@@ -574,6 +859,63 @@ function MyForm() {
 | `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
@@ -595,6 +937,7 @@ function MyForm() {
 | `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