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

package/README.md

@@ -544,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: