@reformer/core 1.1.0-beta.3 → 1.1.0-beta.5

package/llms.txt

@@ -6,7 +6,7 @@
 
 | What                                                                                        | Where                       |
 | ------------------------------------------------------------------------------------------- | --------------------------- |
-| `createForm`, `useFormControl`, `useFormControlValue`                                       | `@reformer/core`            |
+| `createForm`, `useFormControl`, `useFormControlValue`, `validateForm`                       | `@reformer/core`            |
 | `ValidationSchemaFn`, `BehaviorSchemaFn`, `FieldPath`, `GroupNodeWithControls`, `FieldNode` | `@reformer/core`            |
 | `FormSchema`, `FieldConfig`, `ArrayNode`                                                    | `@reformer/core`            |
 | `required`, `min`, `max`, `minLength`, `maxLength`, `email`                                 | `@reformer/core/validators` |
@@ -23,6 +23,98 @@
 - Optional strings: `string` (empty string by default)
 - Do NOT add `[key: string]: unknown` to form interfaces
 
+### React Hooks Comparison (CRITICALLY IMPORTANT)
+
+| Hook | Return Type | Subscribes To | Use Case |
+|------|-------------|---------------|----------|
+| `useFormControl(field)` | `{ value, errors, disabled, touched, ... }` | All signals | Full field state, form inputs |
+| `useFormControlValue(field)` | `T` (value directly) | Only value signal | Conditional rendering |
+
+⚠️ **CRITICAL**: Do NOT destructure `useFormControlValue`! It returns `T` directly, NOT `{ value: T }`.
+
+```typescript
+// ❌ WRONG - will always be undefined!
+const { value: loanType } = useFormControlValue(control.loanType);
+
+// ✅ CORRECT
+const loanType = useFormControlValue(control.loanType);
+
+// ✅ CORRECT - useFormControl returns object, destructuring OK
+const { value, errors, disabled } = useFormControl(control.loanType);
+```
+
+## 1.5 QUICK START - Minimal Working Form
+
+```typescript
+import { createForm, useFormControl } from '@reformer/core';
+import { required, email } from '@reformer/core/validators';
+import type { GroupNodeWithControls } from '@reformer/core';
+
+// 1. Define form type
+interface ContactForm {
+  name: string;
+  email: string;
+}
+
+// 2. Create form schema with validation
+const form = createForm<ContactForm>({
+  form: {
+    name: { value: '', component: Input },
+    email: { value: '', component: Input },
+  },
+  validation: (path) => {
+    required(path.name, { message: 'Name is required' });
+    required(path.email, { message: 'Email is required' });
+    email(path.email, { message: 'Invalid email format' });
+  },
+});
+
+// 3. Use in React component
+function ContactFormComponent() {
+  const nameCtrl = useFormControl(form.name);
+  const emailCtrl = useFormControl(form.email);
+
+  const handleSubmit = async () => {
+    await form.submit((values) => {
+      console.log('Form submitted:', values);
+    });
+  };
+
+  return (
+    <form onSubmit={(e) => { e.preventDefault(); handleSubmit(); }}>
+      <div>
+        <input
+          value={nameCtrl.value}
+          onChange={(e) => form.name.setValue(e.target.value)}
+          disabled={nameCtrl.disabled}
+        />
+        {nameCtrl.errors.map((err) => <span key={err.code}>{err.message}</span>)}
+      </div>
+      <div>
+        <input
+          value={emailCtrl.value}
+          onChange={(e) => form.email.setValue(e.target.value)}
+          disabled={emailCtrl.disabled}
+        />
+        {emailCtrl.errors.map((err) => <span key={err.code}>{err.message}</span>)}
+      </div>
+      <button type="submit">Send</button>
+    </form>
+  );
+}
+
+// 4. Pass form to child components via props (NOT context!)
+interface FormStepProps {
+  form: GroupNodeWithControls<ContactForm>;
+}
+
+function FormStep({ form }: FormStepProps) {
+  // Access form fields directly
+  const { value } = useFormControl(form.name);
+  return <div>Name: {value}</div>;
+}
+```
+
 ## 2. API SIGNATURES
 
 ### Validators
@@ -48,9 +140,48 @@ validate(path, validator: (value, ctx) => ValidationError | null)
 validateAsync(path, validator: async (value, ctx) => ValidationError | null)
 validateTree(validator: (ctx) => ValidationError | null, options?: { targetField?: string })
 
-// Conditional validation
+// Conditional validation (3 arguments!)
 applyWhen(fieldPath, condition: (fieldValue) => boolean, validatorsFn: (path) => void)
 
+// ⚠️ applyWhen Examples - CRITICALLY IMPORTANT
+// applyWhen takes 3 arguments: triggerField, condition, validators
+
+// Example 1: Simple condition
+applyWhen(
+  path.loanType,                    // 1st: field to watch
+  (type) => type === 'mortgage',    // 2nd: condition on field value
+  (p) => {                          // 3rd: validators to apply
+    required(p.propertyValue);
+    min(p.propertyValue, 100000);
+  }
+);
+
+// Example 2: Nested field as trigger
+applyWhen(
+  path.address.country,
+  (country) => country === 'US',
+  (p) => {
+    required(p.address.state);
+    pattern(p.address.zip, /^\d{5}(-\d{4})?$/);
+  }
+);
+
+// Example 3: Boolean trigger
+applyWhen(
+  path.hasInsurance,
+  (has) => has === true,
+  (p) => {
+    required(p.insuranceCompany);
+    required(p.policyNumber);
+  }
+);
+
+// ❌ WRONG - only 2 arguments (React Hook Form pattern)
+applyWhen(
+  (form) => form.loanType === 'mortgage',  // WRONG!
+  () => { required(path.propertyValue); }
+);
+
 // Array validators
 notEmpty(path, options?: { message?: string })
 validateItems(arrayPath, itemValidatorsFn: (itemPath) => void)
@@ -89,7 +220,7 @@ transformers.trim, transformers.toUpperCase, transformers.toLowerCase, transform
 interface BehaviorContext<TForm> {
   form: GroupNodeWithControls<TForm>;            // Form proxy with typed field access
   setFieldValue: (path: string, value: any) => void;
-  getFieldValue: (path: string) => unknown;
+  // ⚠️ To READ field values, use: ctx.form.fieldName.value.value
 }
 ```
 
@@ -121,6 +252,35 @@ const { value } = useFormControl(form.field as FieldNode<ExpectedType>);
 
 ## 4. ⚠️ COMMON MISTAKES
 
+### useFormControlValue (CRITICAL)
+
+```typescript
+// ❌ WRONG - useFormControlValue returns T directly, NOT { value: T }
+const { value: loanType } = useFormControlValue(control.loanType);
+// Result: loanType is ALWAYS undefined! Conditional rendering will fail.
+
+// ✅ CORRECT
+const loanType = useFormControlValue(control.loanType);
+
+// ✅ ALSO CORRECT - useFormControl returns object
+const { value, errors } = useFormControl(control.loanType);
+```
+
+### Reading Field Values in BehaviorContext (CRITICAL)
+
+```typescript
+// ❌ WRONG - getFieldValue does NOT exist!
+watchField(path.amount, (amount, ctx) => {
+  const rate = ctx.getFieldValue('rate'); // ERROR: Property 'getFieldValue' does not exist
+});
+
+// ✅ CORRECT - use ctx.form.fieldName.value.value
+watchField(path.amount, (amount, ctx) => {
+  const rate = ctx.form.rate.value.value;  // Read via signal
+  ctx.setFieldValue('total', amount * rate);
+});
+```
+
 ### Validators
 
 ```typescript
@@ -343,6 +503,25 @@ form.address.city.value.value; // Get current value
 form.items.push({ id: '1', name: 'Item' }); // Array operations
 ```
 
+### ⚠️ createForm Returns a Proxy
+
+```typescript
+// createForm() returns GroupNodeWithControls<T> (a Proxy wrapper around GroupNode)
+// This enables type-safe field access:
+const form = createForm<MyForm>({...});
+
+form.email           // FieldNode<string> - TypeScript knows the type!
+form.address.city    // FieldNode<string> - nested access works
+form.items.at(0)     // GroupNodeWithControls<ItemType> - array items
+
+// ⚠️ IMPORTANT: Proxy doesn't pass instanceof checks!
+// Use type guards instead:
+import { isFieldNode, isGroupNode, isArrayNode } from '@reformer/core';
+
+if (isFieldNode(node)) { /* ... */ }   // ✅ Works with Proxy
+if (node instanceof FieldNode) { /* ... */ } // ❌ Fails with Proxy!
+```
+
 ## 9. ARRAY SCHEMA FORMAT
 
 **Array items are sub-forms!** Each array element is a complete sub-form with its own fields, validation, and behavior.
@@ -473,6 +652,61 @@ export const fullValidation: ValidationSchemaFn<Form> = (path) => {
   step1Validation(path);
   step2Validation(path);
 };
+
+// Using validateForm() for step validation
+import { validateForm } from '@reformer/core';
+
+const goToNextStep = async () => {
+  const currentValidation = STEP_VALIDATIONS[currentStep];
+  const isValid = await validateForm(form, currentValidation);
+
+  if (!isValid) {
+    form.markAsTouched();  // Show errors on current step fields
+    return;
+  }
+
+  setCurrentStep(currentStep + 1);
+};
+
+// Full form submit with all validations
+const handleSubmit = async () => {
+  const isValid = await validateForm(form, fullValidation);
+
+  if (isValid) {
+    await form.submit(onSubmit);
+  }
+};
+```
+
+### Multi-Step Component Example
+
+```tsx
+function MultiStepForm() {
+  const [step, setStep] = useState(1);
+
+  const nextStep = async () => {
+    const validation = STEP_VALIDATIONS[step];
+    if (await validateForm(form, validation)) {
+      setStep(step + 1);
+    } else {
+      form.markAsTouched();
+    }
+  };
+
+  return (
+    <div>
+      {step === 1 && <Step1Fields form={form} />}
+      {step === 2 && <Step2Fields form={form} />}
+
+      <button onClick={() => setStep(step - 1)} disabled={step === 1}>
+        Back
+      </button>
+      <button onClick={step === 2 ? handleSubmit : nextStep}>
+        {step === 2 ? 'Submit' : 'Next'}
+      </button>
+    </div>
+  );
+}
 ```
 
 ## 13. ⚠️ EXTENDED COMMON MISTAKES
@@ -593,6 +827,123 @@ export const creditApplicationValidation: ValidationSchemaFn<Form> = (path) => {
 | Medium | Separate files: `type.ts`, `schema.ts`, `validators.ts`, `Form.tsx` |
 | Complex | Full colocation with `steps/` and `sub-forms/` |
 
+## 14.5 UI COMPONENT PATTERNS
+
+ReFormer does NOT provide UI components - you create them yourself or use a UI library.
+
+### Generic FormField Component
+
+```tsx
+import type { FieldNode } from '@reformer/core';
+import { useFormControl } from '@reformer/core';
+
+interface FormFieldProps<T> {
+  control: FieldNode<T>;
+  label?: string;
+  type?: 'text' | 'email' | 'number' | 'password';
+  placeholder?: string;
+}
+
+function FormField<T extends string | number>({
+  control,
+  label,
+  type = 'text',
+  placeholder
+}: FormFieldProps<T>) {
+  const { value, errors, disabled, touched } = useFormControl(control);
+  const showError = touched && errors.length > 0;
+
+  return (
+    <div className="form-field">
+      {label && <label>{label}</label>}
+      <input
+        type={type}
+        value={value ?? ''}
+        onChange={(e) => {
+          const val = type === 'number'
+            ? Number(e.target.value) as T
+            : e.target.value as T;
+          control.setValue(val);
+        }}
+        onBlur={() => control.markAsTouched()}
+        disabled={disabled}
+        placeholder={placeholder}
+        className={showError ? 'error' : ''}
+      />
+      {showError && (
+        <span className="error-message">{errors[0].message}</span>
+      )}
+    </div>
+  );
+}
+
+// Usage
+<FormField control={form.email} label="Email" type="email" />
+<FormField control={form.age} label="Age" type="number" />
+```
+
+### FormField for Select
+
+```tsx
+interface SelectFieldProps<T extends string> {
+  control: FieldNode<T>;
+  label?: string;
+  options: Array<{ value: T; label: string }>;
+}
+
+function SelectField<T extends string>({
+  control,
+  label,
+  options
+}: SelectFieldProps<T>) {
+  const { value, errors, disabled, touched } = useFormControl(control);
+
+  return (
+    <div className="form-field">
+      {label && <label>{label}</label>}
+      <select
+        value={value}
+        onChange={(e) => control.setValue(e.target.value as T)}
+        disabled={disabled}
+      >
+        {options.map((opt) => (
+          <option key={opt.value} value={opt.value}>
+            {opt.label}
+          </option>
+        ))}
+      </select>
+      {touched && errors[0] && (
+        <span className="error-message">{errors[0].message}</span>
+      )}
+    </div>
+  );
+}
+```
+
+### Integration with UI Libraries
+
+```tsx
+// With shadcn/ui
+import { Input } from '@/components/ui/input';
+import { Label } from '@/components/ui/label';
+
+function ShadcnFormField({ control, label }: FormFieldProps<string>) {
+  const { value, errors, disabled } = useFormControl(control);
+
+  return (
+    <div className="space-y-2">
+      <Label>{label}</Label>
+      <Input
+        value={value}
+        onChange={(e) => control.setValue(e.target.value)}
+        disabled={disabled}
+      />
+      {errors[0] && <p className="text-red-500">{errors[0].message}</p>}
+    </div>
+  );
+}
+```
+
 ## 15. NON-EXISTENT API (DO NOT USE)
 
 ⚠️ **The following APIs do NOT exist in @reformer/core:**
@@ -603,6 +954,13 @@ export const creditApplicationValidation: ValidationSchemaFn<Form> = (path) => {
 | `FieldSchema` | `FieldConfig<T>` | Type for individual field config |
 | `when()` | `applyWhen()` | Conditional validation function |
 | `FormFields` | `FieldNode<T>` | Type for field nodes |
+| `FormInstance<T>` | `GroupNodeWithControls<T>` | Form type for component props |
+| `useArrayField()` | `form.items.push/map/removeAt` | Use ArrayNode methods directly |
+| `FormProvider` | `<Component form={form} />` | Pass form via props, no context |
+| `formState` | `form.valid`, `form.dirty`, etc. | Separate signals on form |
+| `control` prop | Not needed | Form IS the control |
+| `register('field')` | `useFormControl(form.field)` | Type-safe field access |
+| `getFieldValue()` | `ctx.form.field.value.value` | Read via signals |
 
 ### Common Import Errors
 
@@ -642,3 +1000,295 @@ const schema: FormSchema<MyForm> = {
   },
 };
 ```
+
+## 15.5 REACT HOOK FORM MIGRATION
+
+If you're familiar with React Hook Form, here's how to translate patterns to ReFormer:
+
+| React Hook Form | ReFormer | Notes |
+|-----------------|----------|-------|
+| `const { register, handleSubmit } = useForm()` | `const form = createForm({...})` | Call OUTSIDE component |
+| `register('fieldName')` | `useFormControl(form.fieldName)` | Returns control object |
+| `watch('fieldName')` | `useFormControlValue(form.fieldName)` | Returns value directly (NOT `{ value }`) |
+| `setValue('field', value)` | `form.field.setValue(value)` | Direct method call |
+| `getValues('field')` | `form.field.value.value` | Signal-based |
+| `formState.errors` | `useFormControl(form.field).errors` | Per-field errors array |
+| `formState.isValid` | `form.valid.value` | Signal |
+| `formState.isDirty` | `form.dirty.value` | Signal |
+| `handleSubmit(onSubmit)` | `form.submit(onSubmit)` | Built-in validation |
+| `<FormProvider form={...}>` | `<Component form={form} />` | Props, NOT context |
+| `useFormContext()` | Not needed | Pass form via props |
+| `useFieldArray({ name: 'items' })` | `form.items` (ArrayNode) | Direct array access |
+| `fields.map((field, index) => ...)` | `form.items.map((item, index) => ...)` | item is sub-form |
+| `append(data)` | `form.items.push(data)` | Add item |
+| `remove(index)` | `form.items.removeAt(index)` | Remove item |
+| `control` prop | Not needed | Form IS the control |
+
+### Key Differences
+
+1. **No Provider/Context** - Pass form directly via props
+   ```typescript
+   // ❌ React Hook Form pattern - doesn't exist in ReFormer
+   <FormProvider form={form}>
+     <NestedComponent />
+   </FormProvider>
+
+   // ✅ ReFormer pattern - pass via props
+   <NestedComponent form={form} />
+   ```
+
+2. **Form Creation Location** - Create outside component
+   ```typescript
+   // ❌ WRONG - creates new form on every render
+   function MyComponent() {
+     const form = createForm({...});
+   }
+
+   // ✅ CORRECT - create once, outside component
+   const form = createForm({...});
+   function MyComponent() {
+     const ctrl = useFormControl(form.name);
+   }
+   ```
+
+3. **Type-Safe Field Access** - No string paths
+   ```typescript
+   // React Hook Form
+   register('user.address.city')
+
+   // ReFormer - fully typed
+   form.user.address.city.setValue('New York')
+   ```
+
+4. **Array Items are Sub-Forms**
+   ```typescript
+   // React Hook Form
+   fields.map((field, index) => (
+     <input {...register(`items.${index}.name`)} />
+   ))
+
+   // ReFormer - each item is a typed GroupNode
+   form.items.map((item, index) => (
+     <FormField control={item.name} />  // item.name is FieldNode
+   ))
+   ```
+
+5. **Reading Values in Behaviors**
+   ```typescript
+   // React Hook Form
+   watch('fieldName')
+
+   // ReFormer in watchField callback
+   watchField(path.trigger, (value, ctx) => {
+     const other = ctx.form.otherField.value.value;  // Signal access
+   });
+   ```
+
+## 16. READING FIELD VALUES (CRITICALLY IMPORTANT)
+
+### Why .value.value?
+
+ReFormer uses `@preact/signals-core` for reactivity:
+- `field.value` → `Signal<T>` (reactive container)
+- `field.value.value` → `T` (actual value)
+- `field.getValue()` → `T` (shorthand method, non-reactive)
+
+```typescript
+// Reading values in different contexts:
+
+// In React components - use hooks
+const { value } = useFormControl(control.email);     // Object with value
+const email = useFormControlValue(control.email);    // Value directly
+
+// In BehaviorContext (watchField, etc.)
+watchField(path.firstName, (firstName, ctx) => {
+  // ⚠️ ctx.form is typed as the PARENT GROUP of the watched field!
+  // For path.nested.field: ctx.form = NestedType, NOT RootForm!
+
+  const lastName = ctx.form.lastName.value.value;  // Read sibling field
+
+  // Use setFieldValue with full path for root-level fields
+  ctx.setFieldValue('fullName', `${firstName} ${lastName}`);
+});
+
+// Direct access on form controls
+form.email.value.value;           // Read current value
+form.address.city.value.value;    // Read nested value
+```
+
+### Reading Nested Values in watchField
+
+```typescript
+// ⚠️ IMPORTANT: ctx.form type depends on the watched path!
+
+// Watching root-level field
+watchField(path.loanAmount, (amount, ctx) => {
+  // ctx.form is MyForm - can access all fields
+  const rate = ctx.form.interestRate.value.value;
+  ctx.setFieldValue('monthlyPayment', amount * rate / 12);
+});
+
+// Watching nested field
+watchField(path.personalData.lastName, (lastName, ctx) => {
+  // ctx.form is PersonalData, NOT MyForm!
+  const firstName = ctx.form.firstName.value.value;   // ✅ Works
+  const middleName = ctx.form.middleName.value.value; // ✅ Works
+
+  // For root-level field, use setFieldValue with full path
+  ctx.setFieldValue('fullName', `${lastName} ${firstName}`);
+});
+```
+
+## 17. COMPUTE FROM vs WATCH FIELD
+
+### computeFrom - Same Nesting Level Only
+
+```typescript
+// ✅ Works: all source fields and target at same level
+computeFrom(
+  [path.price, path.quantity],
+  path.total,
+  ({ price, quantity }) => (price || 0) * (quantity || 0)
+);
+
+// ✅ Works: all nested at same level
+computeFrom(
+  [path.address.houseNumber, path.address.streetName],
+  path.address.fullAddress,
+  ({ houseNumber, streetName }) => `${houseNumber} ${streetName}`
+);
+
+// ❌ FAILS: different nesting levels
+computeFrom(
+  [path.nested.price, path.nested.quantity],
+  path.rootTotal,  // Different level - won't work!
+  ...
+);
+```
+
+### watchField - Any Level
+
+```typescript
+// ✅ Works for cross-level computation
+watchField(path.nested.price, (price, ctx) => {
+  const quantity = ctx.form.quantity.value.value;  // Sibling in nested
+  ctx.setFieldValue('rootTotal', price * quantity); // Full path to root
+});
+
+// ✅ Works for multiple dependencies
+watchField(path.loanAmount, (amount, ctx) => {
+  const term = ctx.form.loanTerm.value.value;
+  const rate = ctx.form.interestRate.value.value;
+
+  if (amount && term && rate) {
+    const monthly = calculateMonthlyPayment(amount, term, rate);
+    ctx.setFieldValue('monthlyPayment', monthly);
+  }
+});
+```
+
+### Rule of Thumb
+
+| Scenario | Use |
+|----------|-----|
+| All fields share same parent | `computeFrom` (simpler, auto-cleanup) |
+| Fields at different levels | `watchField` (more flexible) |
+| Multiple dependencies | `watchField` |
+| Async computation | `watchField` with async callback |
+
+## 18. ARRAY OPERATIONS
+
+### ⚠️ Array Access - CRITICAL
+
+```typescript
+// ❌ WRONG - bracket notation does NOT work!
+const first = form.items[0];        // undefined or error
+const second = form.items[1];       // undefined or error
+
+// ✅ CORRECT - use .at() method
+const first = form.items.at(0);     // GroupNodeWithControls<ItemType> | undefined
+const second = form.items.at(1);    // GroupNodeWithControls<ItemType> | undefined
+
+// ✅ CORRECT - iterate with map (most common pattern)
+form.items.map((item, index) => {
+  // item is fully typed GroupNode
+  item.name.setValue('New Name');
+  item.price.value.value;  // read value
+});
+```
+
+### Array Methods
+
+```typescript
+// Add items
+form.items.push({ name: '', price: 0 });           // Add to end
+form.items.insert(0, { name: '', price: 0 });      // Insert at index
+
+// Remove items
+form.items.removeAt(index);                         // Remove by index
+form.items.clear();                                 // Remove all items
+
+// Reorder
+form.items.move(fromIndex, toIndex);                // Move item
+
+// Access (use .at(), NOT brackets!)
+form.items.length.value;                            // Current length (Signal)
+form.items.map((item, index) => ...);               // Iterate items
+form.items.at(index);                               // Get item at index (NOT items[index]!)
+```
+
+### Rendering Arrays
+
+```tsx
+function ItemsList({ form }: { form: GroupNodeWithControls<MyForm> }) {
+  const { length } = useFormControl(form.items);
+
+  return (
+    <div>
+      {form.items.map((item, index) => (
+        // item is GroupNode (sub-form) - each field is a control
+        <div key={item.id || index}>
+          <FormField control={item.name} />
+          <FormField control={item.price} />
+          <button onClick={() => form.items.removeAt(index)}>Remove</button>
+        </div>
+      ))}
+
+      {length === 0 && <p>No items yet</p>}
+
+      <button onClick={() => form.items.push({ name: '', price: 0 })}>
+        Add Item
+      </button>
+    </div>
+  );
+}
+```
+
+### Array Cross-Validation
+
+```typescript
+// Validate uniqueness across array items
+validateTree((ctx: { form: MyForm }) => {
+  const items = ctx.form.items;
+  const names = items.map(item => item.name.value.value);
+  const uniqueNames = new Set(names);
+
+  if (names.length !== uniqueNames.size) {
+    return { code: 'duplicate', message: 'Item names must be unique' };
+  }
+  return null;
+}, { targetField: 'items' });
+
+// Validate sum of percentages
+validateTree((ctx: { form: MyForm }) => {
+  const items = ctx.form.items;
+  const totalPercent = items.reduce(
+    (sum, item) => sum + (item.percentage.value.value || 0),
+    0
+  );
+
+  if (Math.abs(totalPercent - 100) > 0.01) {
+    return { code: 'invalid_total', message: 'Percentages must sum to 100%' };
+  }
+  return null;
+}, { targetField: 'items' });