@reformer/core 1.0.0 → 1.1.0-beta.2

package/llms.txt

@@ -1,847 +1,606 @@
-# ReFormer
+# ReFormer - LLM Integration Guide
 
-> Signals-based reactive form state management library for React.
-> Built on Preact Signals Core for fine-grained reactivity with full TypeScript support.
-> Key features: type-safe schemas, declarative validation, reactive behaviors, nested forms, dynamic arrays.
+## 1. QUICK REFERENCE
 
-## Installation
+### Imports (CRITICALLY IMPORTANT)
 
-```bash
-npm install reformer
-```
-
-Peer dependencies:
-- React 18+ or React 19+
-- @preact/signals-core ^1.8.0
-
-## Quick Start
-
-```tsx
-import { createForm } from 'reformer';
-import { required, email, minLength } from 'reformer/validators';
-import { useFormControl } from 'reformer';
-
-// 1. Define your form type
-type ContactForm = {
-  name: string;
-  email: string;
-  message: string;
-};
-
-// 2. Create form with schema and validation
-const form = createForm<ContactForm>({
-  form: {
-    name: { value: '', component: Input, componentProps: { label: 'Name' } },
-    email: { value: '', component: Input, componentProps: { label: 'Email' } },
-    message: { value: '', component: Textarea, componentProps: { label: 'Message' } },
-  },
-  validation: (path) => {
-    required(path.name);
-    minLength(path.name, 2);
-    required(path.email);
-    email(path.email);
-    required(path.message);
-  },
-});
-
-// 3. Use in React component
-function ContactForm() {
-  const { value, errors, shouldShowError } = useFormControl(form.name);
-
-  return (
-    <input
-      value={value}
-      onChange={(e) => form.name.setValue(e.target.value)}
-      onBlur={() => form.name.markAsTouched()}
-    />
-  );
-}
-```
-
-## Architecture
-
-### Node Hierarchy
-
-ReFormer uses a tree-based node architecture:
-
-```
-GroupNode (Form)
-├── FieldNode (single values: string, number, boolean)
-├── GroupNode (nested objects)
-└── ArrayNode (dynamic arrays)
-```
-
-All nodes inherit from abstract `FormNode` base class.
-
-### Key Concepts
-
-1. **Form Schema** - Defines structure, components, and initial values
-2. **Validation Schema** - Declares validation rules (separate from structure)
-3. **Behavior Schema** - Reactive logic (computed fields, conditional visibility, sync)
+| What                                                                                        | Where                       |
+| ------------------------------------------------------------------------------------------- | --------------------------- |
+| `createForm`, `useFormControl`, `useFormControlValue`                                       | `@reformer/core`            |
+| `ValidationSchemaFn`, `BehaviorSchemaFn`, `FieldPath`, `GroupNodeWithControls`, `FieldNode` | `@reformer/core`            |
+| `FormSchema`, `FieldConfig`, `ArrayNode`                                                    | `@reformer/core`            |
+| `required`, `min`, `max`, `minLength`, `maxLength`, `email`                                 | `@reformer/core/validators` |
+| `pattern`, `url`, `phone`, `number`, `date`                                                 | `@reformer/core/validators` |
+| `validate`, `validateAsync`, `validateTree`, `applyWhen`                                    | `@reformer/core/validators` |
+| `notEmpty`, `validateItems`                                                                 | `@reformer/core/validators` |
+| `computeFrom`, `enableWhen`, `disableWhen`, `watchField`, `copyFrom`                        | `@reformer/core/behaviors`  |
+| `resetWhen`, `revalidateWhen`, `syncFields`                                                 | `@reformer/core/behaviors`  |
+| `transformValue`, `transformers`                                                            | `@reformer/core/behaviors`  |
 
-### Signals-based Reactivity
+### Type Values
 
-- Uses @preact/signals-core for fine-grained reactivity
-- Only affected components re-render when values change
-- React integration via useSyncExternalStore
+- Optional numbers: `number | undefined` (NOT `null`)
+- Optional strings: `string` (empty string by default)
+- Do NOT add `[key: string]: unknown` to form interfaces
 
-## Form Schema
+## 2. API SIGNATURES
 
-### FieldConfig<T>
+### Validators
 
 ```typescript
-interface FieldConfig<T> {
-  value: T | null;                    // Initial value
-  component: ComponentType<any>;       // React component to render
-  componentProps?: Record<string, any>; // Props passed to component
-  validators?: ValidatorFn<T>[];       // Sync validators
-  asyncValidators?: AsyncValidatorFn<T>[]; // Async validators
-  disabled?: boolean;                  // Initially disabled
-  updateOn?: 'change' | 'blur' | 'submit'; // When to validate (default: 'change')
-  debounce?: number;                   // Debounce validation in ms
-}
-```
+// Basic validators
+required(path, options?: { message?: string })
+min(path, value: number, options?: { message?: string })
+max(path, value: number, options?: { message?: string })
+minLength(path, length: number, options?: { message?: string })
+maxLength(path, length: number, options?: { message?: string })
+email(path, options?: { message?: string })
 
-### ArrayConfig<T>
+// Additional validators
+pattern(path, regex: RegExp, options?: { message?: string })
+url(path, options?: { message?: string })
+phone(path, options?: { message?: string; format?: PhoneFormat })
+number(path, options?: { message?: string })
+date(path, options?: { message?: string; minAge?: number; maxAge?: number; noFuture?: boolean; noPast?: boolean })
 
-Arrays use single-element tuple syntax in schema:
+// Custom validators
+validate(path, validator: (value, ctx) => ValidationError | null)
+validateAsync(path, validator: async (value, ctx) => ValidationError | null)
+validateTree(validator: (ctx) => ValidationError | null, options?: { targetField?: string })
 
-```typescript
-interface FormType {
-  phones: { type: string; number: string }[];
-}
+// Conditional validation
+applyWhen(fieldPath, condition: (fieldValue) => boolean, validatorsFn: (path) => void)
 
-const schema: FormSchema<FormType> = {
-  phones: [{
-    type: { value: 'mobile', component: Select },
-    number: { value: '', component: Input },
-  }],
-};
+// Array validators
+notEmpty(path, options?: { message?: string })
+validateItems(arrayPath, itemValidatorsFn: (itemPath) => void)
 ```
 
-### Complete Schema Example
+### Behaviors
 
 ```typescript
-import { createForm } from 'reformer';
+// Enable/disable fields conditionally
+enableWhen(path, condition: (form) => boolean, options?: { resetOnDisable?: boolean })
+disableWhen(path, condition: (form) => boolean)
 
-type UserForm = {
-  name: string;
-  email: string;
-  age: number;
-  address: {
-    street: string;
-    city: string;
-  };
-  phones: { type: string; number: string }[];
-};
-
-const form = createForm<UserForm>({
-  form: {
-    name: { value: '', component: Input },
-    email: { value: '', component: Input },
-    age: { value: 0, component: Input, componentProps: { type: 'number' } },
-    address: {
-      street: { value: '', component: Input },
-      city: { value: '', component: Input },
-    },
-    phones: [{
-      type: { value: 'mobile', component: Select },
-      number: { value: '', component: Input },
-    }],
-  },
-  validation: (path) => { /* validators */ },
-  behavior: (path) => { /* behaviors */ },
-});
-```
+// Computed fields (same nesting level)
+computeFrom(sourcePaths[], targetPath, compute: (values) => result, options?: { debounce?: number; condition?: (form) => boolean })
 
-## Node Types
+// Watch field changes
+watchField(path, callback: (value, ctx: BehaviorContext) => void, options?: { immediate?: boolean; debounce?: number })
 
-### FieldNode<T>
+// Copy values between fields
+copyFrom(sourcePath, targetPath, options?: { when?: (form) => boolean; fields?: string[]; transform?: (value) => value })
 
-Represents a single form field value.
+// Reset field when condition met
+resetWhen(path, condition: (form) => boolean, options?: { toValue?: any })
 
-**Properties (all are Signals):**
-- `value` - Current value
-- `valid` / `invalid` - Validation state
-- `touched` / `untouched` - User interaction state
-- `dirty` / `pristine` - Value changed from initial
-- `errors` - Array of ValidationError objects
-- `shouldShowError` - true when invalid AND (touched OR dirty)
-- `disabled` - Is field disabled
-- `pending` - Async validation in progress
-- `status` - 'valid' | 'invalid' | 'pending' | 'disabled'
-- `componentProps` - Props for component
+// Re-validate when another field changes
+revalidateWhen(triggerPath, targetPath)
 
-**Methods:**
-- `setValue(value, options?)` - Set new value
-- `reset()` - Reset to initial value
-- `markAsTouched()` - Mark as touched
-- `markAsDirty()` - Mark as dirty
-- `disable()` / `enable()` - Toggle disabled state
-- `validate()` - Run validation
-- `getErrors(filter?)` - Get filtered errors
+// Sync multiple fields
+syncFields(paths[], options?: { bidirectional?: boolean })
 
-### GroupNode<T>
+// Transform values
+transformValue(path, transformer: (value) => value, options?: { on?: 'change' | 'blur' })
+transformers.trim, transformers.toUpperCase, transformers.toLowerCase, transformers.toNumber
 
-Groups multiple fields into an object.
-
-**Properties:**
-- `controls` - Dictionary of child nodes
-- All FormNode properties (computed from children)
-
-**Methods:**
-- `getFieldByPath(path: string)` - Get field by dot-notation path
-- `patchValue(partial)` - Update subset of fields
-- `resetAll()` - Reset all children
-- All FormNode methods
-
-**Proxy Access:**
-```typescript
-// Type-safe field access via proxy
-form.name           // FieldNode<string>
-form.address.city   // FieldNode<string>
-form.phones         // ArrayNode
+// BehaviorContext interface:
+interface BehaviorContext<TForm> {
+  form: GroupNodeWithControls<TForm>;            // Form proxy with typed field access
+  setFieldValue: (path: string, value: any) => void;
+  getFieldValue: (path: string) => unknown;
+}
 ```
 
-### ArrayNode<T>
+## 3. COMMON PATTERNS
 
-Manages dynamic arrays.
-
-**Properties:**
-- `controls` - Array of GroupNode items
-- `length` - Number of items
-
-**Methods:**
-- `push(value)` - Add item to end
-- `insert(index, value)` - Insert at position
-- `removeAt(index)` - Remove at position
-- `move(from, to)` - Move item
-- `clear()` - Remove all items
-- `at(index)` - Get item at index
+### Conditional Fields with Auto-Reset
 
 ```typescript
-// Usage
-form.phones.push({ type: 'work', number: '' });
-form.phones.removeAt(0);
-form.phones.at(0).controls.number.setValue('123-456');
+enableWhen(path.mortgageFields, (form) => form.loanType === 'mortgage', {
+  resetOnDisable: true,
+});
 ```
 
-## Validation
-
-### ValidationSchemaFn
+### Computed Field from Nested to Root Level
 
 ```typescript
-import { required, email, minLength, validate, validateAsync } from 'reformer/validators';
-
-const form = createForm<FormType>({
-  form: { /* schema */ },
-  validation: (path) => {
-    // Built-in validators
-    required(path.name);
-    email(path.email);
-    minLength(path.password, 8);
-
-    // Custom validator
-    validate(path.age, (value) => {
-      if (value < 18) return { code: 'tooYoung', message: 'Must be 18+' };
-      return null;
-    });
-
-    // Async validator
-    validateAsync(path.username, async (value) => {
-      const available = await checkUsername(value);
-      if (!available) return { code: 'taken', message: 'Username taken' };
-      return null;
-    }, { debounce: 500 });
-  },
+// DO NOT use computeFrom for cross-level computations
+// Use watchField instead:
+watchField(path.nested.field, (value, ctx) => {
+  ctx.setFieldValue('rootField', computedValue);
 });
 ```
 
-### Built-in Validators
-
-All imported from `reformer/validators`:
-
-| Validator | Usage | Description |
-|-----------|-------|-------------|
-| `required(path)` | `required(path.name)` | Non-empty value |
-| `email(path)` | `email(path.email)` | Valid email format |
-| `minLength(path, n)` | `minLength(path.name, 2)` | Minimum string length |
-| `maxLength(path, n)` | `maxLength(path.bio, 500)` | Maximum string length |
-| `min(path, n)` | `min(path.age, 18)` | Minimum number value |
-| `max(path, n)` | `max(path.qty, 100)` | Maximum number value |
-| `pattern(path, regex)` | `pattern(path.code, /^[A-Z]+$/)` | Match regex |
-| `url(path)` | `url(path.website)` | Valid URL |
-| `phone(path)` | `phone(path.phone)` | Valid phone |
-| `number(path)` | `number(path.amount)` | Must be number |
-| `date(path)` | `date(path.birthDate)` | Valid date |
-
-### Custom Validator Example
+### Type-Safe useFormControl
 
 ```typescript
-// validators/password.ts
-export function strongPassword() {
-  return (value: string) => {
-    if (!value) return null; // Skip empty (use required() separately)
-
-    const errors: string[] = [];
-    if (!/[A-Z]/.test(value)) errors.push('uppercase');
-    if (!/[a-z]/.test(value)) errors.push('lowercase');
-    if (!/[0-9]/.test(value)) errors.push('number');
-    if (value.length < 8) errors.push('length');
-
-    if (errors.length) {
-      return { code: 'weakPassword', message: 'Password too weak', params: { missing: errors } };
-    }
-    return null;
-  };
-}
-
-// Usage
-validation: (path) => {
-  required(path.password);
-  validate(path.password, strongPassword());
-}
+const { value } = useFormControl(form.field as FieldNode<ExpectedType>);
 ```
 
-### Async Validation Example
-
-```typescript
-// Check username availability on server
-validation: (path) => {
-  required(path.username);
+## 4. ⚠️ COMMON MISTAKES
 
-  validateAsync(path.username, async (value, ctx) => {
-    if (!value || value.length < 3) return null;
+### Validators
 
-    const response = await fetch(`/api/check-username?u=${value}`);
-    const { available } = await response.json();
+```typescript
+// ❌ WRONG
+required(path.email, 'Email is required');
 
-    if (!available) {
-      return { code: 'usernameTaken', message: 'Username is already taken' };
-    }
-    return null;
-  }, { debounce: 500 });
-}
+// ✅ CORRECT
+required(path.email, { message: 'Email is required' });
 ```
 
-### Cross-field Validation
+### Types
 
 ```typescript
-import { validateTree } from 'reformer/validators';
-
-validation: (path) => {
-  required(path.password);
-  required(path.confirmPassword);
-
-  // Cross-field validation
-  validateTree((ctx) => {
-    const password = ctx.form.password.value.value;
-    const confirm = ctx.form.confirmPassword.value.value;
-
-    if (password && confirm && password !== confirm) {
-      return {
-        code: 'passwordMismatch',
-        message: 'Passwords do not match',
-        path: 'confirmPassword',
-      };
-    }
-    return null;
-  });
-}
-```
+// ❌ WRONG
+amount: number | null;
+[key: string]: unknown;
 
-## Behaviors
-
-Behaviors add reactive logic to forms. All imported from `reformer/behaviors`.
+// ✅ CORRECT
+amount: number | undefined;
+// No index signature
+```
 
 ### computeFrom
 
-Calculate field value from other fields:
-
 ```typescript
-import { computeFrom } from 'reformer/behaviors';
-
-behavior: (path) => {
-  // total = price * quantity
-  computeFrom(
-    [path.price, path.quantity],  // Watch these fields
-    path.total,                    // Update this field
-    ({ price, quantity }) => price * quantity  // Compute function
-  );
-}
-```
+// ❌ WRONG - different nesting levels
+computeFrom([path.nested.a, path.nested.b], path.root, ...)
 
-### enableWhen / disableWhen
+// ✅ CORRECT - use watchField
+watchField(path.nested.a, (_, ctx) => {
+  ctx.setFieldValue('root', computed);
+});
+```
 
-Conditional field enable/disable:
+### Imports
 
 ```typescript
-import { enableWhen, disableWhen } from 'reformer/behaviors';
-
-behavior: (path) => {
-  // Enable discount field only when total > 500
-  enableWhen(path.discount, (form) => form.total > 500);
+// ❌ WRONG - types are not in submodules
+import { ValidationSchemaFn } from '@reformer/core/validators';
 
-  // Disable shipping when pickup is selected
-  disableWhen(path.shippingAddress, (form) => form.deliveryMethod === 'pickup');
-}
+// ✅ CORRECT - types from main module
+import type { ValidationSchemaFn } from '@reformer/core';
+import { required, email } from '@reformer/core/validators';
 ```
 
-### watchField
+## 5. TROUBLESHOOTING
 
-React to field changes with custom logic:
+| Error                                                  | Cause                          | Solution                          |
+| ------------------------------------------------------ | ------------------------------ | --------------------------------- |
+| `'string' is not assignable to '{ message?: string }'` | Wrong validator format         | Use `{ message: 'text' }`         |
+| `'null' is not assignable to 'undefined'`              | Wrong optional type            | Replace `null` with `undefined`   |
+| `FormFields[]` instead of concrete type                | Type inference issue           | Use `as FieldNode<T>`             |
+| `Type 'X' is missing properties from type 'Y'`         | Cross-level computeFrom        | Use watchField instead            |
+| `Module has no exported member`                        | Wrong import source            | Types from core, functions from submodules |
+
+## 6. COMPLETE IMPORT EXAMPLE
 
 ```typescript
-import { watchField } from 'reformer/behaviors';
-
-behavior: (path) => {
-  // Load cities when country changes
-  watchField(path.country, async (value, ctx) => {
-    const cities = await fetchCities(value);
-    ctx.form.city.updateComponentProps({ options: cities });
-    ctx.form.city.setValue(''); // Reset city selection
-  }, { debounce: 300 });
-}
-```
+// Types - always from @reformer/core
+import type {
+  ValidationSchemaFn,
+  BehaviorSchemaFn,
+  FieldPath,
+  GroupNodeWithControls,
+  FieldNode,
+} from '@reformer/core';
 
-### copyFrom
+// Core functions
+import { createForm, useFormControl } from '@reformer/core';
 
-Copy values from one field/group to another:
+// Validators - from /validators submodule
+import { required, min, max, email, validate, applyWhen } from '@reformer/core/validators';
 
-```typescript
-import { copyFrom } from 'reformer/behaviors';
-
-behavior: (path) => {
-  // Copy billing address to shipping when checkbox is checked
-  copyFrom(path.billingAddress, path.shippingAddress, {
-    when: (form) => form.sameAsShipping === true,
-    fields: 'all', // or ['street', 'city', 'zip']
-  });
-}
+// Behaviors - from /behaviors submodule
+import { computeFrom, enableWhen, watchField, copyFrom } from '@reformer/core/behaviors';
 ```
 
-### syncFields
-
-Two-way field synchronization:
+## 7. FORM TYPE DEFINITION
 
 ```typescript
-import { syncFields } from 'reformer/behaviors';
-
-behavior: (path) => {
-  syncFields(path.field1, path.field2);
-}
-```
+// ✅ CORRECT form type definition
+interface MyForm {
+  // Required fields
+  name: string;
+  email: string;
 
-### resetWhen
+  // Optional fields - use undefined, not null
+  phone?: string;
+  age?: number;
 
-Reset field when condition is met:
+  // Enum/union types
+  status: 'active' | 'inactive';
 
-```typescript
-import { resetWhen } from 'reformer/behaviors';
+  // Nested objects
+  address: {
+    street: string;
+    city: string;
+  };
 
-behavior: (path) => {
-  // Reset city when country changes
-  resetWhen(path.city, [path.country]);
+  // Arrays - use tuple format for schema
+  items: Array<{
+    id: string;
+    name: string;
+  }>;
 }
 ```
 
-### revalidateWhen
+## 8. FORMSCHEMA FORMAT (CRITICALLY IMPORTANT)
 
-Trigger revalidation when another field changes:
+⚠️ **Every field MUST have `value` and `component` properties!**
 
-```typescript
-import { revalidateWhen } from 'reformer/behaviors';
+### FieldConfig Interface
 
-behavior: (path) => {
-  // Revalidate confirmPassword when password changes
-  revalidateWhen(path.confirmPassword, [path.password]);
+```typescript
+interface FieldConfig<T> {
+  value: T | null;              // Initial value (REQUIRED)
+  component: ComponentType;     // React component (REQUIRED)
+  componentProps?: object;      // Props passed to component
+  disabled?: boolean;           // Disable field initially
+  validators?: ValidatorFn[];   // Sync validators
+  asyncValidators?: AsyncValidatorFn[]; // Async validators
+  updateOn?: 'change' | 'blur' | 'submit';
+  debounce?: number;
 }
 ```
 
-### Custom Behavior
-
-Create reusable custom behaviors:
+### Primitive Fields
 
 ```typescript
-// behaviors/auto-save.ts
-import { Behavior } from 'reformer';
-
-interface AutoSaveOptions {
-  debounce?: number;
-  onSave: (data: any) => Promise<void>;
-}
-
-export function autoSave<T>(options: AutoSaveOptions): Behavior<T> {
-  const { debounce = 1000, onSave } = options;
-  let timeoutId: NodeJS.Timeout;
-
-  return {
-    key: 'autoSave',
-    paths: [], // Empty = listen to all fields
-    run: (values, ctx) => {
-      clearTimeout(timeoutId);
-      timeoutId = setTimeout(async () => {
-        await onSave(ctx.form.getValue());
-      }, debounce);
-    },
-    cleanup: () => clearTimeout(timeoutId),
-  };
-}
+import { Input, Select, Checkbox } from '@/components/ui';
 
-// Usage
-behaviors: (path, { use }) => [
-  use(autoSave({
-    debounce: 2000,
-    onSave: async (data) => {
-      await fetch('/api/save', { method: 'POST', body: JSON.stringify(data) });
+const schema: FormSchema<MyForm> = {
+  // String field
+  name: {
+    value: '',                    // Initial value (REQUIRED)
+    component: Input,             // React component (REQUIRED)
+    componentProps: {
+      label: 'Name',
+      placeholder: 'Enter name',
     },
-  })),
-];
-```
+  },
 
-## Recommended Project Structure
+  // Number field (optional)
+  age: {
+    value: undefined,             // Use undefined, NOT null
+    component: Input,
+    componentProps: { type: 'number', label: 'Age' },
+  },
 
-### Form Organization (Colocation)
+  // Boolean field
+  agree: {
+    value: false,
+    component: Checkbox,
+    componentProps: { label: 'I agree to terms' },
+  },
 
-```
-src/forms/
-├── user-profile/
-│   ├── UserProfileForm.tsx        # React component
-│   ├── type.ts                    # TypeScript interfaces
-│   ├── schema.ts                  # Form schema (createForm)
-│   ├── validators.ts              # Validation rules
-│   ├── behaviors.ts               # Reactive behaviors
-│   └── sub-forms/                 # Reusable nested schemas
-│       ├── address/
-│       │   ├── type.ts
-│       │   ├── schema.ts
-│       │   ├── validators.ts
-│       │   └── AddressForm.tsx
+  // Enum/Select field
+  status: {
+    value: 'active',
+    component: Select,
+    componentProps: {
+      label: 'Status',
+      options: [
+        { value: 'active', label: 'Active' },
+        { value: 'inactive', label: 'Inactive' },
+      ],
+    },
+  },
+};
 ```
 
-### Schema File Pattern
+### Nested Objects
 
 ```typescript
-// forms/user-profile/schema.ts
-import { createForm } from 'reformer';
-import { validation } from './validators';
-import { behavior } from './behaviors';
-import type { UserProfile } from './type';
-
-export const createUserProfileForm = (initial?: Partial<UserProfile>) =>
-  createForm<UserProfile>({
-    form: {
-      name: { value: initial?.name ?? '', component: Input },
-      email: { value: initial?.email ?? '', component: Input },
-      // ...
-    },
-    validation,
-    behavior,
-  });
+const schema: FormSchema<MyForm> = {
+  address: {
+    street: { value: '', component: Input, componentProps: { label: 'Street' } },
+    city: { value: '', component: Input, componentProps: { label: 'City' } },
+    zip: { value: '', component: Input, componentProps: { label: 'ZIP' } },
+  },
+};
 ```
 
-### Multi-step Form Structure
+### Arrays (Tuple Format)
 
-```
-src/forms/checkout/
-├── CheckoutForm.tsx              # Main form component
-├── type.ts                       # Combined type
-├── schema.ts                     # Combined schema
-├── validators.ts                 # Combined + cross-step validators
-├── behaviors.ts                  # Combined + cross-step behaviors
-├── steps/
-│   ├── shipping/
-│   │   ├── type.ts
-│   │   ├── schema.ts
-│   │   ├── validators.ts
-│   │   └── ShippingStep.tsx
-│   ├── payment/
-│   └── confirmation/
-└── hooks/
-    └── useCheckoutNavigation.ts
-```
-
-## React Integration
+```typescript
+const itemSchema = {
+  id: { value: '', component: Input, componentProps: { label: 'ID' } },
+  name: { value: '', component: Input, componentProps: { label: 'Name' } },
+};
 
-### useFormControl<T>
+const schema: FormSchema<MyForm> = {
+  items: [itemSchema],  // Array with ONE template item
+};
+```
 
-Subscribe to all field state changes:
+### ❌ WRONG - This will NOT compile
 
 ```typescript
-import { useFormControl } from 'reformer';
-
-function TextField({ field }: { field: FieldNode<string> }) {
-  const {
-    value,           // Current value
-    valid,           // Is valid
-    invalid,         // Has errors
-    errors,          // ValidationError[]
-    touched,         // User interacted
-    disabled,        // Is disabled
-    pending,         // Async validation running
-    shouldShowError, // Show error (touched && invalid)
-    componentProps,  // Custom props from schema
-  } = useFormControl(field);
-
-  return (
-    <div>
-      <input
-        value={value}
-        onChange={(e) => field.setValue(e.target.value)}
-        onBlur={() => field.markAsTouched()}
-        disabled={disabled}
-      />
-      {shouldShowError && errors[0] && (
-        <span className="error">{errors[0].message}</span>
-      )}
-    </div>
-  );
-}
+// Missing value and component - TypeScript will error!
+const schema = {
+  name: '',           // ❌ Wrong
+  email: '',          // ❌ Wrong
+};
 ```
 
-### useFormControlValue<T>
-
-Lightweight hook - returns only value (better performance):
+### createForm API
 
 ```typescript
-import { useFormControlValue } from 'reformer';
-
-function ConditionalField({ trigger, field }) {
-  // Re-renders only when trigger value changes
-  const showField = useFormControlValue(trigger);
+// Full config with behavior and validation
+const form = createForm<MyForm>({
+  form: formSchema,              // Required: form schema with FieldConfig
+  behavior: behaviorSchema,      // Optional: behavior rules
+  validation: validationSchema,  // Optional: validation rules
+});
 
-  if (showField !== 'yes') return null;
-  return <TextField field={field} />;
-}
+// Access form controls
+form.name.setValue('John');
+form.address.city.value.value; // Get current value
+form.items.push({ id: '1', name: 'Item' }); // Array operations
 ```
 
-### Performance Notes
-
-- Uses `useSyncExternalStore` for React 18+ integration
-- Fine-grained updates - only affected components re-render
-- Memoized state objects prevent unnecessary re-renders
-- Use `useFormControlValue` when you only need the value
-
-## API Reference
-
-### createForm<T>(config)
-
-Creates a new form instance with type-safe proxy access.
+## 9. ARRAY SCHEMA FORMAT
 
 ```typescript
-function createForm<T>(config: GroupNodeConfig<T>): GroupNodeWithControls<T>
+// ✅ CORRECT - use tuple format for arrays
+const schema = {
+  items: [itemSchema] as [typeof itemSchema],
+  properties: [propertySchema] as [typeof propertySchema],
+};
 
-interface GroupNodeConfig<T> {
-  form: FormSchema<T>;
-  validation?: ValidationSchemaFn<T>;
-  behavior?: BehaviorSchemaFn<T>;
-}
+// ❌ WRONG - object format is NOT supported
+const schema = {
+  items: { schema: itemSchema, initialItems: [] }, // This will NOT work
+};
 ```
 
-### Node Common Properties
-
-All nodes have these Signal properties:
-- `value` - Current value
-- `valid` / `invalid` - Validation state
-- `touched` / `untouched` - Interaction state
-- `dirty` / `pristine` - Changed state
-- `status` - 'valid' | 'invalid' | 'pending' | 'disabled'
-- `disabled` - Is disabled
-- `pending` - Async validation in progress
-
-### Node Common Methods
+## 10. ASYNC WATCHFIELD (CRITICALLY IMPORTANT)
 
 ```typescript
-setValue(value: T, options?: SetValueOptions): void
-reset(): void
-markAsTouched(): void
-markAsDirty(): void
-disable(): void
-enable(): void
-validate(): Promise<void>
-getErrors(filter?: (error: ValidationError) => boolean): ValidationError[]
-```
+// ✅ CORRECT - async watchField with ALL safeguards
+watchField(
+  path.parentField,
+  async (value, ctx) => {
+    if (!value) return;  // Guard clause
 
-### SetValueOptions
+    try {
+      const { data } = await fetchData(value);
+      ctx.form.dependentField.updateComponentProps({ options: data });
+    } catch (error) {
+      console.error('Failed:', error);
+      ctx.form.dependentField.updateComponentProps({ options: [] });
+    }
+  },
+  { immediate: false, debounce: 300 }  // REQUIRED options
+);
 
-```typescript
-interface SetValueOptions {
-  emitEvent?: boolean;  // Trigger change events (default: true)
-  onlySelf?: boolean;   // Don't propagate to parent (default: false)
-}
+// ❌ WRONG - missing safeguards
+watchField(path.field, async (value, ctx) => {
+  const { data } = await fetchData(value);  // Will fail silently!
+});
 ```
 
-### ValidationError
+### Required Options for async watchField:
+- `immediate: false` - prevents execution during initialization
+- `debounce: 300` - prevents excessive API calls (300-500ms recommended)
+- Guard clause - skip if value is empty
+- try-catch - handle errors explicitly
+
+## 11. ARRAY CLEANUP PATTERN
 
 ```typescript
-interface ValidationError {
-  code: string;                    // Error identifier
-  message: string;                 // Human-readable message
-  params?: Record<string, any>;    // Additional error data
-  severity?: 'error' | 'warning';  // Severity level
-  path?: string;                   // Field path (for cross-field)
-}
+// ✅ CORRECT - cleanup array when checkbox unchecked
+watchField(
+  path.hasItems,
+  (hasItems, ctx) => {
+    if (!hasItems && ctx.form.items) {
+      ctx.form.items.clear();
+    }
+  },
+  { immediate: false }
+);
+
+// ❌ WRONG - no immediate: false, no null check
+watchField(path.hasItems, (hasItems, ctx) => {
+  if (!hasItems) ctx.form.items.clear();  // May crash on init!
+});
 ```
 
-### FieldStatus
+## 12. MULTI-STEP FORM VALIDATION
 
 ```typescript
-type FieldStatus = 'valid' | 'invalid' | 'pending' | 'disabled';
-```
+// Step-specific validation schemas
+const step1Validation: ValidationSchemaFn<Form> = (path) => {
+  required(path.loanType);
+  required(path.loanAmount);
+};
 
-### Type Guards
+const step2Validation: ValidationSchemaFn<Form> = (path) => {
+  required(path.personalData.firstName);
+  required(path.personalData.lastName);
+};
 
-```typescript
-import { isFieldNode, isGroupNode, isArrayNode, getNodeType } from 'reformer';
+// STEP_VALIDATIONS map for useStepForm hook
+export const STEP_VALIDATIONS = {
+  1: step1Validation,
+  2: step2Validation,
+};
 
-if (isFieldNode(node)) { /* node is FieldNode */ }
-if (isGroupNode(node)) { /* node is GroupNode */ }
-if (isArrayNode(node)) { /* node is ArrayNode */ }
-const type = getNodeType(node); // 'field' | 'group' | 'array'
+// Full validation (combines all steps)
+export const fullValidation: ValidationSchemaFn<Form> = (path) => {
+  step1Validation(path);
+  step2Validation(path);
+};
 ```
 
-## Common Patterns
+## 13. ⚠️ EXTENDED COMMON MISTAKES
 
-### Multi-step Form
+### Behavior Composition (Cycle Error)
 
 ```typescript
-function MultiStepForm() {
-  const form = useMemo(() => createCheckoutForm(), []);
-  const [step, setStep] = useState(0);
-
-  const validateStep = async () => {
-    const stepFields = getStepFields(step);
-    stepFields.forEach(f => f.markAsTouched());
-    await form.validate();
-    return stepFields.every(f => f.valid.value);
-  };
+// ❌ WRONG - apply() in behavior causes "Cycle detected"
+const mainBehavior: BehaviorSchemaFn<Form> = (path) => {
+  apply(addressBehavior, path.address);  // WILL FAIL!
+};
 
-  const handleNext = async () => {
-    if (await validateStep()) {
-      setStep(s => s + 1);
-    }
-  };
+// ✅ CORRECT - inline or use setup function
+const setupAddressBehavior = (path: FieldPath<Address>) => {
+  watchField(path.region, async (region, ctx) => {
+    // ...
+  }, { immediate: false });
+};
 
-  return (
-    <div>
-      {step === 0 && <ShippingStep form={form} />}
-      {step === 1 && <PaymentStep form={form} />}
-      {step === 2 && <ConfirmationStep form={form} />}
-
-      <button onClick={() => setStep(s => s - 1)} disabled={step === 0}>
-        Back
-      </button>
-      <button onClick={handleNext}>
-        {step === 2 ? 'Submit' : 'Next'}
-      </button>
-    </div>
-  );
-}
+const mainBehavior: BehaviorSchemaFn<Form> = (path) => {
+  setupAddressBehavior(path.address);  // Works!
+};
 ```
 
-### Nested Form with Reusable Schema
+### Infinite Loop in watchField
 
 ```typescript
-// sub-forms/address/schema.ts
-export const addressSchema = {
-  street: { value: '', component: Input, componentProps: { label: 'Street' } },
-  city: { value: '', component: Input, componentProps: { label: 'City' } },
-  zip: { value: '', component: Input, componentProps: { label: 'ZIP' } },
-};
-
-// main form
-const form = createForm<OrderForm>({
-  form: {
-    billingAddress: addressSchema,
-    shippingAddress: addressSchema,
-  },
+// ❌ WRONG - causes infinite loop
+watchField(path.field, (value, ctx) => {
+  ctx.form.field.setValue(value.toUpperCase());  // Loop!
 });
+
+// ✅ CORRECT - write to different field OR add guard
+watchField(path.input, (value, ctx) => {
+  const upper = value?.toUpperCase() || '';
+  if (ctx.form.display.value.value !== upper) {
+    ctx.form.display.setValue(upper);
+  }
+}, { immediate: false });
 ```
 
-### Dynamic Array (Add/Remove Items)
+### validateTree Typing
 
 ```typescript
-function PhoneList({ array }: { array: ArrayNode<Phone> }) {
-  const { length } = useFormControl(array);
-
-  return (
-    <div>
-      {array.controls.map((phone, index) => (
-        <div key={phone.id}>
-          <FormField field={phone.controls.type} />
-          <FormField field={phone.controls.number} />
-          <button onClick={() => array.removeAt(index)}>Remove</button>
-        </div>
-      ))}
-
-      <button onClick={() => array.push({ type: 'mobile', number: '' })}>
-        Add Phone
-      </button>
-    </div>
-  );
-}
-```
+// ❌ WRONG - implicit any
+validateTree((ctx) => { ... });
 
-### Conditional Fields
+// ✅ CORRECT - explicit typing
+validateTree((ctx: { form: MyForm }) => {
+  if (ctx.form.field1 > ctx.form.field2) {
+    return { code: 'error', message: 'Invalid' };
+  }
+  return null;
+});
+```
 
-```typescript
-behavior: (path) => {
-  // Show company fields only for business accounts
-  enableWhen(path.companyName, (form) => form.accountType === 'business');
-  enableWhen(path.taxId, (form) => form.accountType === 'business');
-
-  // Reset company fields when switching to personal
-  resetWhen(path.companyName, [path.accountType]);
-  resetWhen(path.taxId, [path.accountType]);
+## 14. PROJECT STRUCTURE (COLOCATION)
+
+```
+src/
+├── components/ui/                    # Reusable UI components
+│   ├── FormField.tsx
+│   └── FormArrayManager.tsx
+│
+├── forms/
+│   └── [form-name]/                  # Form module
+│       ├── type.ts                   # Main form type
+│       ├── schema.ts                 # Main schema
+│       ├── validators.ts             # Validators
+│       ├── behaviors.ts              # Behaviors
+│       ├── [FormName]Form.tsx        # Main component
+│       │
+│       ├── steps/                    # Multi-step wizard
+│       │   ├── loan-info/
+│       │   │   ├── type.ts
+│       │   │   ├── schema.ts
+│       │   │   ├── validators.ts
+│       │   │   ├── behaviors.ts
+│       │   │   └── LoanInfoForm.tsx
+│       │   └── ...
+│       │
+│       └── sub-forms/                # Reusable sub-forms
+│           ├── address/
+│           └── personal-data/
+```
+
+### Key Files
+
+```typescript
+// forms/credit-application/type.ts
+export type { LoanInfoStep } from './steps/loan-info/type';
+export interface CreditApplicationForm {
+  loanType: LoanType;
+  loanAmount: number;
+  // ...
 }
-```
 
-## Troubleshooting / FAQ
+// forms/credit-application/schema.ts
+import { loanInfoSchema } from './steps/loan-info/schema';
+export const creditApplicationSchema = {
+  ...loanInfoSchema,
+  monthlyPayment: { value: 0, disabled: true },
+};
 
-### Q: Field not updating in React?
-A: Ensure you're using `useFormControl()` hook to subscribe to changes. Direct signal access (`.value.value`) won't trigger re-renders.
+// forms/credit-application/validators.ts
+import { loanValidation } from './steps/loan-info/validators';
+export const creditApplicationValidation: ValidationSchemaFn<Form> = (path) => {
+  loanValidation(path);
+  // Cross-step validation...
+};
+```
 
-### Q: Validation not triggering?
-A: Check `updateOn` option in field config. Default is 'change'. For blur-triggered validation use `updateOn: 'blur'`.
+### Scaling
 
-### Q: How to access nested field by path string?
-A: Use `form.getFieldByPath('address.city')` for dynamic string-based access. For type-safe access use proxy: `form.address.city`.
+| Complexity | Structure |
+|------------|-----------|
+| Simple | Single file: `ContactForm.tsx` |
+| Medium | Separate files: `type.ts`, `schema.ts`, `validators.ts`, `Form.tsx` |
+| Complex | Full colocation with `steps/` and `sub-forms/` |
 
-### Q: TypeScript errors with schema?
-A: Ensure your type interface matches the schema structure exactly. Use `createForm<YourType>()` for proper type inference.
+## 15. NON-EXISTENT API (DO NOT USE)
 
-### Q: How to reset form to initial values?
-A: Call `form.reset()` for single field or `form.resetAll()` for GroupNode to reset all children.
+⚠️ **The following APIs do NOT exist in @reformer/core:**
 
-### Q: How to get all form values?
-A: Access `form.value.value` (it's a Signal) or use `form.getValue()` method.
+| ❌ Wrong | ✅ Correct | Notes |
+|----------|-----------|-------|
+| `useForm` | `createForm` | There is no useForm hook |
+| `FieldSchema` | `FieldConfig<T>` | Type for individual field config |
+| `when()` | `applyWhen()` | Conditional validation function |
+| `FormFields` | `FieldNode<T>` | Type for field nodes |
 
-### Q: How to programmatically set multiple values?
-A: Use `form.patchValue({ field1: 'value1', field2: 'value2' })` to update multiple fields at once.
+### Common Import Errors
 
-### Q: Form instance recreated on every render?
-A: Wrap `createForm()` in `useMemo()`:
 ```typescript
-const form = useMemo(() => createForm<MyForm>({ form: schema }), []);
+// ❌ WRONG - These do NOT exist
+import { useForm } from '@reformer/core';           // NO!
+import { when } from '@reformer/core/validators';   // NO!
+import type { FieldSchema } from '@reformer/core';  // NO!
+import type { FormFields } from '@reformer/core';   // NO!
+
+// ✅ CORRECT
+import { createForm, useFormControl } from '@reformer/core';
+import { applyWhen } from '@reformer/core/validators';
+import type { FieldConfig, FieldNode } from '@reformer/core';
 ```
 
-### Q: How to handle form submission?
-A:
+### FormSchema Common Mistakes
+
 ```typescript
-const handleSubmit = async (e: React.FormEvent) => {
-  e.preventDefault();
-  form.markAsTouched(); // Show all errors
-  await form.validate(); // Run all validators
-
-  if (form.valid.value) {
-    const data = form.value.value;
-    await submitToServer(data);
-  }
+// ❌ WRONG - Simple values don't work
+const schema = {
+  name: '',           // Missing { value, component }
+  email: '',          // Missing { value, component }
 };
-```
 
-## Links
-
-- Repository: https://github.com/AlexandrBukhtatyy/ReFormer
-- Documentation: https://alexandrbukhtatyy.github.io/ReFormer/
-- Issues: https://github.com/AlexandrBukhtatyy/ReFormer/issues
+// ✅ CORRECT - Every field needs value and component
+const schema: FormSchema<MyForm> = {
+  name: {
+    value: '',
+    component: Input,
+    componentProps: { label: 'Name' },
+  },
+  email: {
+    value: '',
+    component: Input,
+    componentProps: { label: 'Email', type: 'email' },
+  },
+};
+```