# ReFormer - LLM Integration Guide

## 1. QUICK REFERENCE

### Imports (CRITICALLY IMPORTANT)

| What                                                                                        | Where                       |
| ------------------------------------------------------------------------------------------- | --------------------------- |
| `ValidationSchemaFn`, `BehaviorSchemaFn`, `FieldPath`, `GroupNodeWithControls`, `FieldNode` | `@reformer/core`            |
| `required`, `min`, `max`, `minLength`, `email`, `validate`, `validateTree`                  | `@reformer/core/validators` |
| `computeFrom`, `enableWhen`, `disableWhen`, `copyFrom`, `watchField`                        | `@reformer/core/behaviors`  |

### Type Values

- Optional numbers: `number | undefined` (NOT `null`)
- Optional strings: `string` (empty string by default)
- Do NOT add `[key: string]: unknown` to form interfaces

## 2. API SIGNATURES

### Validators

```typescript
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 })
validate(path, validator: (value) => ValidationError | null)
validateTree(validator: (ctx) => ValidationError | null)
when(condition: (form) => boolean, validatorsFn: () => void)
```

### Behaviors

```typescript
enableWhen(path, condition: (form) => boolean, options?: { resetOnDisable?: boolean })
disableWhen(path, condition: (form) => boolean)
computeFrom(sourcePaths[], targetPath, compute: (values) => result)
watchField(path, callback: (value, ctx) => void)
copyFrom(sourcePath, targetPath, options?: { when?, fields?, transform? })
```

## 3. COMMON PATTERNS

### Conditional Fields with Auto-Reset

```typescript
enableWhen(path.mortgageFields, (form) => form.loanType === 'mortgage', {
  resetOnDisable: true,
});
```

### Computed Field from Nested to Root Level

```typescript
// DO NOT use computeFrom for cross-level computations
// Use watchField instead:
watchField(path.nested.field, (value, ctx) => {
  ctx.setFieldValue('rootField', computedValue);
});
```

### Type-Safe useFormControl

```typescript
const { value } = useFormControl(form.field as FieldNode<ExpectedType>);
```

## 4. ⚠️ COMMON MISTAKES

### Validators

```typescript
// ❌ WRONG
required(path.email, 'Email is required');

// ✅ CORRECT
required(path.email, { message: 'Email is required' });
```

### Types

```typescript
// ❌ WRONG
amount: number | null;
[key: string]: unknown;

// ✅ CORRECT
amount: number | undefined;
// No index signature
```

### computeFrom

```typescript
// ❌ WRONG - different nesting levels
computeFrom([path.nested.a, path.nested.b], path.root, ...)

// ✅ CORRECT - use watchField
watchField(path.nested.a, (_, ctx) => {
  ctx.setFieldValue('root', computed);
});
```

### Imports

```typescript
// ❌ WRONG - types are not in submodules
import { ValidationSchemaFn } from '@reformer/core/validators';

// ✅ CORRECT - types from main module
import type { ValidationSchemaFn } from '@reformer/core';
import { required, email } from '@reformer/core/validators';
```

## 5. TROUBLESHOOTING

| 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
// Types - always from @reformer/core
import type {
  ValidationSchemaFn,
  BehaviorSchemaFn,
  FieldPath,
  GroupNodeWithControls,
  FieldNode,
} from '@reformer/core';

// Core functions
import { createForm, useFormControl } from '@reformer/core';

// Validators - from /validators submodule
import { required, min, max, email, validate, when } from '@reformer/core/validators';

// Behaviors - from /behaviors submodule
import { computeFrom, enableWhen, watchField, copyFrom } from '@reformer/core/behaviors';
```

## 7. FORM TYPE DEFINITION

```typescript
// ✅ CORRECT form type definition
interface MyForm {
  // Required fields
  name: string;
  email: string;

  // Optional fields - use undefined, not null
  phone?: string;
  age?: number;

  // Enum/union types
  status: 'active' | 'inactive';

  // Nested objects
  address: {
    street: string;
    city: string;
  };

  // Arrays
  items: Array<{
    id: string;
    name: string;
  }>;
}
```
