@reformer/core 10.2.0 → 11.0.0-beta.2

package/docs/llms/02-quick-start.md

@@ -0,0 +1,143 @@
+## 1.5 QUICK START - Minimal Working Form
+
+> **Schema-driven UI rule (read first)**: компонент И его пропсы (label, placeholder,
+> options, type) объявляются в **схеме поля** (`component` + `componentProps`).
+> В JSX рендерится один универсальный `<FormField control={form.x} />` из
+> `@reformer/ui-kit` БЕЗ дополнительных props. Не пиши свои `Input`/`Select`/
+> `Checkbox`-обёртки с `label`-prop'ами — это anti-pattern. См.
+> `find_recipe(package="@reformer/ui-kit", topic="form-field-integration")`.
+
+Архитектура M1: сначала создаётся **модель данных** (`createModel`), затем **форма**
+(`createForm({ model, schema })`), где схема привязывает поля к сигналам модели
+(`model.$.field`). Layout-схема НЕ несёт валидаторов — валидация живёт в отдельной
+схеме `defineValidationSchema` из `@reformer/core/validation` и запускается внешним
+раннером `validateModel(model, schema)`.
+
+```typescript
+import { createModel, createForm, type FormProxy } from '@reformer/core';
+import { defineValidationSchema, validate, validateModel } from '@reformer/core/validation';
+import { required, email } from '@reformer/core/validators';
+import { FormField, Input, Button } from '@reformer/ui-kit';
+
+// 1. Define form type as `type` alias (not `interface` — see Recipe 2)
+type ContactForm = {
+  name: string;
+  email: string;
+};
+
+// 2. Model (источник истины значений)
+const model = createModel<ContactForm>({ name: '', email: '' });
+
+// 3. Layout-schema: привязка поля к сигналу (model.$.field) + component/componentProps.
+//    БЕЗ validators — валидация в отдельной схеме (шаг 4).
+const schema = {
+  name: {
+    value: model.$.name,
+    component: Input,
+    componentProps: { label: 'Name', placeholder: 'Your name' },
+  },
+  email: {
+    value: model.$.email,
+    component: Input,
+    componentProps: { label: 'Email', type: 'email' },
+  },
+};
+
+// 4. Validation-schema — отдельный слой (@reformer/core/validation)
+const contactValidation = defineValidationSchema<ContactForm>(({ model }) => {
+  validate(model.$.name, [required({ message: 'Name is required' })]);
+  validate(model.$.email, [required({ message: 'Email is required' }), email({ message: 'Invalid email' })]);
+});
+
+// 5. Form — ноды поверх сигналов модели
+const form = createForm<ContactForm>({ model, schema });
+
+// 6. Use in React component — thin JSX, FormField does ALL heavy lifting
+function ContactFormComponent() {
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    // form.submit()/validate() НЕ гоняют schema-валидацию — только внешний validateModel
+    const ok = await validateModel(model, contactValidation); // Promise<boolean>, ошибки сам роутит в ноды
+    if (ok) {
+      console.log('Form submitted:', model.get());
+    }
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <FormField control={form.name} testId="name" />
+      <FormField control={form.email} testId="email" />
+      <Button type="submit">Send</Button>
+    </form>
+  );
+}
+
+// 7. Pass form to child components via props (NOT context!)
+type FormStepProps = {
+  form: FormProxy<ContactForm>;
+};
+
+function FormStep({ form }: FormStepProps) {
+  return <FormField control={form.name} testId="name" />;
+}
+```
+
+> **Стабильность инстанса.** В React создавай model/schema/form ОДИН раз через `useMemo(() => { … }, [])`
+> — иначе форма пересоздаётся на каждый рендер. См. `28-submit-and-reset.md`, `29-async-preload.md`.
+
+### Arrays of objects — `{ array, item }` schema node
+
+Массивы объектов принадлежат модели (`model.arrayField`). В схеме объявляются узлом
+`{ array: model.<path>, item: (itemModel) => itemSchema }`, где `item` строит под-схему
+для каждого элемента из его под-модели (`FormModel<Item>`):
+
+```typescript
+type PropertyItem = {
+  type: 'apartment' | 'house';
+  description: string;
+  estimatedValue: number;
+};
+
+type MyForm = { properties: PropertyItem[] };
+
+const model = createModel<MyForm>({ properties: [] });
+
+// под-схема одного элемента: item.$.field — сигнал под-модели элемента
+const propertyItem = (item: FormModel<PropertyItem>) => ({
+  type: {
+    value: item.$.type,
+    component: Select,
+    componentProps: { label: 'Тип', options: [/* ... */] },
+  },
+  description: { value: item.$.description, component: Textarea, componentProps: { label: 'Описание' } },
+  estimatedValue: {
+    value: item.$.estimatedValue,
+    component: Input,
+    componentProps: { label: 'Стоимость', type: 'number' },
+  },
+});
+
+const schema = {
+  properties: { array: model.properties, item: propertyItem },
+};
+
+const form = createForm<MyForm>({ model, schema });
+
+// Операции над массивом — на модели:
+model.properties.push({ type: 'apartment', description: '', estimatedValue: 0 });
+model.properties.removeAt(0);
+model.properties.length; // реактивная длина
+```
+
+Подробнее в `10-arrays.md`, `21-array-operations.md` и `find_recipe(topic="form-array")`.
+
+### When to write your own field components (advanced — rare)
+
+Свои компоненты нужны ТОЛЬКО если:
+
+- ты намеренно избегаешь `@reformer/ui-kit` (например, проект уже имеет свою design system)
+- нужен особый низкоуровневый input, который не покрывается `FormField` + `componentProps`
+
+В этом случае см. секцию `## 14.5 UI COMPONENT PATTERNS` ниже — но даже там
+паттерн **schema-driven** (label/options не из JSX-props, а из `componentProps` через
+`useFormControl(...).componentProps`).

package/docs/llms/03-api-signatures.md

@@ -0,0 +1,273 @@
+## 2. API SIGNATURES
+
+### Model & Form
+
+```typescript
+// Модель данных (источник истины значений)
+createModel<T extends object>(initial: T): FormModel<T>
+// model.get() / model.set(full) / model.patch(partial) / model.isDirty()
+// model.reset() / model.captureInitial() / model.signalAt(path)
+// model.$.field            → PathAwareSignal<FieldType>  (escape-hatch к сигналу)
+// model.arrayField         → ModelArray<Item>            (push/removeAt/insertAt/move/swap/clear/at/map/length)
+
+// Форма (ноды поверх сигналов модели)
+createForm<T>({ model, schema, behavior? }): FormProxy<T>
+// form.<field>             → FieldNode / GroupNode / FormArrayProxy
+// form.<field>.setValue(v) / .value.value / .errors.value / .disabled.value
+// form.<field>.enable() / .disable() / .reset() / .markAsTouched() / .setErrors([...])
+// form.<field>.updateComponentProps({ ... })
+
+// Валидация данных — ОТДЕЛЬНЫЙ контракт `@reformer/core/validation` (НЕ дерево createForm: то несёт
+// только layout, без validators). Схема — функция над моделью; внешний раннер разносит ошибки по нодам
+// формы (setErrors), warning не блокирует submit, устаревший прогон отменяется.
+validateModel<T>(model: FormModel<T>, schema: ValidationSchema<T>): Promise<boolean>   // из @reformer/core/validation
+// schema = defineValidationSchema<T>(({ model }) => { validate(...); ... })
+// ⚠️ form.submit() / form.validate() БОЛЬШЕ НЕ прогоняют schema-валидацию — гоняйте validateModel(model, schema) снаружи.
+```
+
+### Validators
+
+Валидаторы — **чистые фабрики** из `@reformer/core/validators`: возвращают правило `Rule<T>` =
+`(value) => ValidationError | null` (принимают nullable value). Передаются оператору
+`validate(sig, [required(), min(50000)])` внутри схемы валидации, а **не** в layout-дерево `createForm`.
+
+```typescript
+required(options?: { message?: string })
+min(value: number, options?: { message?: string })
+max(value: number, options?: { message?: string })
+minLength(length: number, options?: { message?: string })
+maxLength(length: number, options?: { message?: string })
+email(options?: { message?: string })
+pattern(regex: RegExp, options?: { message?: string })
+url(options?: { message?: string; requireProtocol?: boolean })
+phone(options?: { message?: string; format?: PhoneFormat })
+// Number validator factories
+isNumber(options?: { message?: string })
+integer(options?: { message?: string })
+multipleOf(divisor: number, options?: { message?: string })
+nonNegative(options?: { message?: string })       // value >= 0
+nonZero(options?: { message?: string })            // value !== 0
+// Date validator factories
+isDate(options?: { message?: string })
+minDate(date: Date | string, options?: { message?: string })
+maxDate(date: Date | string, options?: { message?: string })
+pastDate(options?: { message?: string })
+futureDate(options?: { message?: string })
+minAge(years: number, options?: { message?: string })
+maxAge(years: number, options?: { message?: string })
+```
+
+Использование: layout-дерево `createForm` привязывает поля к сигналам, правила живут отдельной
+`ValidationSchema` и гоняются раннером `validateModel` по требованию.
+
+```typescript
+import { createModel, createForm } from '@reformer/core';
+import { defineValidationSchema, validate, validateModel } from '@reformer/core/validation';
+import { required, min, max, email } from '@reformer/core/validators';
+
+type Loan = { email: string; age: number; amount: number };
+const model = createModel<Loan>({ email: '', age: 0, amount: 0 });
+
+// layout-схема createForm НЕ несёт validators — только привязка поля к сигналу + компонент
+const form = createForm({
+  model,
+  schema: {
+    email:  { value: model.$.email,  component: Input },
+    age:    { value: model.$.age,    component: Input },
+    amount: { value: model.$.amount, component: Input },
+  },
+});
+
+// правила — в ОТДЕЛЬНОЙ схеме валидации (не в layout)
+const loanValidation = defineValidationSchema<Loan>(({ model }) => {
+  validate(model.$.email,  [required(), email()]);
+  validate(model.$.age,    [required(), min(18)]);
+  validate(model.$.amount, [min(0), max(1000)]);
+});
+
+const ok = await validateModel(model, loanValidation);   // Promise<boolean>; ошибки сами доедут до form.<field>.errors
+```
+
+### Custom & cross-field validators
+
+Контракт валидации — `@reformer/core/validation`. Схема (`ValidationSchema<T>`) — обычная функция над
+(под)моделью; внутри вызываются свободные операторы, которые сами пишут ошибки в ноды текущего прогона
+(`getNodeForSignal(sig).setErrors(...)` — автор коллектора не видит).
+
+```typescript
+type Rule<T>      = (value: T, scope: never, root: never) => ValidationError | null;   // scope/root = never (см. ниже)
+type AsyncRule<T> = (value: T, ctx: { signal: AbortSignal }) => Promise<ValidationError | null>;
+type ValidationSchema<T> = (ctx: { model: FormModel<T> }) => void;
+```
+
+Операторы (ambient — валидны только внутри прогона `validateModel`):
+
+| Оператор | Назначение |
+|---|---|
+| `validate(sig, rules: Rule<T>[])` | синхронные правила поля |
+| `validateAsync(sig, rules: AsyncRule<T>[])` | асинхронные правила (раннер дожидается, прокидывает `AbortSignal`) |
+| `validateWhen(cond: () => boolean, cb: () => void)` | условная ветка: правила внутри активны/гасятся по `cond` (не трогает enable — это поведение) |
+| `cross(sig, fn: (form) => err \| null)` | cross-field; `fn` получает снапшот модели текущего scope (`model.get()`) |
+| `each(arr, itemFn: (im: FormModel<U>) => void)` | per-item по элементам массива модели |
+| `apply(...schemas: ValidationSchema<T>[])` | композиция под-схем над той же моделью |
+| `defineValidationSchema<T>(fn): ValidationSchema<T>` | тонкая identity-обёртка (типизация/discoverability) |
+| `validateModel<T>(model, schema): Promise<boolean>` | внешний раннер (warning не блокирует, устаревший прогон отменяется) |
+
+> `Rule<T>` намеренно несёт `scope: never, root: never` — так value-only фабрики (`required()` = `(value, model, root)`)
+> и inline `(value) => err` ОБА присваиваются в `Rule<T>[]`, сохраняя проверку типа поля
+> (`validate(model.$.age, [email()])` подсветится). Ментальная модель автора — `(value) => error`.
+
+Кастомные правила, cross-field и async — в схеме:
+
+```typescript
+import { type ValidationError } from '@reformer/core';
+import {
+  defineValidationSchema, validate, validateAsync, cross,
+  type Rule, type AsyncRule,
+} from '@reformer/core/validation';
+import { required } from '@reformer/core/validators';
+
+type Signup = { password: string; confirm: string; email: string };
+
+// Value-only правило (Rule<T>)
+const strongPassword: Rule<string> = (value) =>
+  !value || value.length < 8 ? { code: 'too-short', message: 'Минимум 8 символов' } : null;
+
+// Cross-field: обычная функция над снапшотом модели (model.get()), вешается через cross(sig, fn)
+const passwordsMatch = (f: Signup): ValidationError | null =>
+  f.confirm && f.password && f.confirm !== f.password
+    ? { code: 'mismatch', message: 'Пароли не совпадают' }
+    : null;
+
+// Async (AsyncRule<T>): получает { signal }; сетевой сбой → null (submit не блокируется)
+const emailUnique: AsyncRule<string> = async (value, { signal }) => {
+  if (!value) return null;
+  try {
+    const res = await fetch(`/api/check-email?email=${encodeURIComponent(value)}`, { signal });
+    return (await res.json()).available ? null : { code: 'taken', message: 'Email уже зарегистрирован' };
+  } catch {
+    return null;
+  }
+};
+
+const signupValidation = defineValidationSchema<Signup>(({ model }) => {
+  validate(model.$.password, [required(), strongPassword]);
+  validate(model.$.confirm, [required()]);
+  cross(model.$.confirm, passwordsMatch);        // ошибка вешается на confirm
+  validateAsync(model.$.email, [emailUnique]);
+});
+```
+
+### Conditional & array validation
+
+Условные ветки и массивы — операторы `validateWhen` / `each` / `apply` внутри схемы (не узлы дерева):
+
+- **условная ветка** `validateWhen(() => cond, () => { validate(...) })` — правила внутри активны только
+  при истинном условии; при ложном ошибки полей ветки гасятся (`setErrors([])`). Enable/сброс поля — дело поведения;
+- **массив** `each(model.arr, (im) => { validate(im.$.field, [...]) })` — правила применяются к каждому
+  элементу; `im` — под-модель элемента. Для cross-field над элементом захватывайте снапшот в замыкание (`const item = im.get()`);
+- **композиция** `apply(...schemas)` — объединяет под-схемы над той же моделью (напр. полную схему из per-step).
+
+```typescript
+import {
+  defineValidationSchema, validate, validateWhen, cross, each, apply, validateModel,
+} from '@reformer/core/validation';
+import { required, min } from '@reformer/core/validators';
+
+// Условная валидация — ипотечная ветка активна только при loanType === 'mortgage'
+const step1 = defineValidationSchema<LoanForm>(({ model }) => {
+  validate(model.$.loanType, [required()]);
+  validateWhen(
+    () => model.loanType === 'mortgage',
+    () => {
+      validate(model.$.propertyValue, [required(), min(1_000_000)]);
+      validate(model.$.initialPayment, [required()]);
+    },
+  );
+});
+
+// Per-item валидация элементов массива (each над ModelArray)
+const step5 = defineValidationSchema<LoanForm>(({ model }) => {
+  each(model.coBorrowers, (im) => {
+    const item = im.get();                          // снапшот элемента для cross
+    validate(im.$.income, [required(), min(10_000)]);
+    cross(im.$.income, () =>
+      item.income < item.loanShare ? { code: 'tooLow', message: 'Доход ниже доли' } : null);
+  });
+});
+
+// Полная схема формы = композиция шагов (apply над той же моделью)
+const formValidation = defineValidationSchema<LoanForm>(() => apply(step1, step5));
+```
+
+Wizard-конфиг (per-step + полная валидация) — поверх того же раннера `validateModel`:
+
+```typescript
+const STEP_SCHEMAS = [step1, /* step2, … */ step5] as const;
+
+function makeValidationConfig(model: FormModel<LoanForm>) {
+  return {
+    validateStep: (n: number) => validateModel(model, STEP_SCHEMAS[n - 1]),
+    validateAll: () => validateModel(model, formValidation),   // formValidation = apply(...STEP_SCHEMAS, extras)
+  };
+}
+```
+
+Операторы `validate`/`validateAsync`/`validateWhen`/`cross`/`each`/`apply` экспортируются напрямую из
+`@reformer/core/validation` — это публичный API, а не локальный сахар примера.
+
+### Behaviors
+
+Два способа. **Примитивы из `@reformer/core`** (принимают сигналы, возвращают cleanup):
+
+```typescript
+computeFrom(sources: ReadonlySignal[], target: Signal, fn: (...vals) => R, options?: { when?: (...vals) => boolean }): () => void
+copyFrom(source: ReadonlySignal, target: Signal, options?: { when?: () => boolean; transform?: (v) => v }): () => void
+watchField(source: ReadonlySignal, cb: (value) => void, options?: { immediate?: boolean }): () => void
+enableWhen(target: ReadonlySignal, condition: () => boolean, options?: { resetOnDisable?: boolean }): () => void
+disableWhen(target: ReadonlySignal, condition: () => boolean, options?: { resetOnDisable?: boolean }): () => void
+transformValue(target: Signal, transformer: (value) => value): () => void
+resetWhen(target: Signal, condition: () => boolean, options?: { resetValue?: T }): () => void
+syncFields(a: Signal, b: Signal, options?: { transform?: (v) => v }): () => void
+revalidateWhen(deps: ReadonlySignal[], revalidate: () => void): () => void
+```
+
+```typescript
+import { computeFrom, enableWhen, copyFrom } from '@reformer/core';
+
+const cleanups = [
+  computeFrom([model.$.price, model.$.quantity], model.$.total, (p, q) => p * q),
+  enableWhen(model.$.city, () => Boolean(model.country), { resetOnDisable: true }),
+  copyFrom(model.$.email, model.$.emailAdditional, { when: () => model.sameEmail === true }),
+];
+// при teardown: cleanups.forEach((c) => c());
+```
+
+**Декларативный DSL из `@reformer/core/behaviors`** (регистрирует cleanup сам, передаётся в `createForm({ behavior })`):
+
+```typescript
+import { defineFormBehavior, compute, enableWhen, onChange } from '@reformer/core/behaviors';
+
+const behavior = defineFormBehavior<MyForm>(({ model, form }) => {
+  compute(model.$.total, () => model.price * model.quantity);
+  enableWhen(model.$.city, () => Boolean(model.country), { resetOnDisable: true });
+  onChange(model.$.country, async (country) => {
+    form.city.updateComponentProps({ options: await loadCities(country) });
+  });
+});
+
+const form = createForm({ model, schema, behavior });
+```
+
+DSL-операторы: `compute` (auto-tracking, без явного списка источников), `computeFrom`, `copyFrom`,
+`onChange` (реакция на изменение; `{ debounce, immediate }`, 2-й аргумент колбэка — `{ signal }` AbortSignal),
+`enableWhen`/`disableWhen`, `transformValue`, `resetWhen`, `syncFields`, `revalidateWhen`,
+`apply` (под-схема для группы), `applyEach` (per-item для массива), `exclusiveFlag`, `aggregateInto`.
+См. `20-compute-vs-watch.md`.
+
+Поведение **не владеет** валидацией — это отдельный слой. Мост «поведение инициирует валидацию» — через
+`revalidateWhen`, который просто вызывает внешний раннер валидации:
+
+```typescript
+revalidateWhen([model.$.dep], () => void validateModel(model, schema));
+```

package/docs/llms/04-common-patterns.md

@@ -0,0 +1,202 @@
+## 3. COMMON PATTERNS
+
+Все паттерны — на архитектуре M1: значения в модели (`model.$.field`), поведение (`defineFormBehavior`)
+на живых сигналах, валидация — отдельной ambient-схемой (`defineValidationSchema`, прогон по требованию
+через `validateModel`). Слои раздельны: layout НЕ несёт validators.
+
+### Conditional Fields with Auto-Reset
+
+```typescript
+import { enableWhen } from '@reformer/core';
+
+// поле включается по условию; при выключении — сброс к initial
+enableWhen(model.$.propertyValue, () => model.loanType === 'mortgage', {
+  resetOnDisable: true,
+});
+```
+
+Или декларативно внутри `defineFormBehavior`:
+
+```typescript
+import { defineFormBehavior, enableWhen } from '@reformer/core/behaviors';
+
+const behavior = defineFormBehavior<MyForm>(({ model }) => {
+  enableWhen(
+    [model.$.propertyValue, model.$.initialPayment],
+    () => model.loanType === 'mortgage',
+    { resetOnDisable: true }
+  );
+});
+```
+
+### Computed Field (same or cross level)
+
+`compute`/`computeFrom` пишут в целевой сигнал при изменении источников. Цель не входит
+в источники → цикла нет. Кросс-уровневые вычисления работают так же — источники берутся
+по сигналам из любого места модели.
+
+```typescript
+import { defineFormBehavior, compute, computeFrom } from '@reformer/core/behaviors';
+
+const behavior = defineFormBehavior<MyForm>(({ model }) => {
+  // compute: auto-tracking — читаем что нужно прямо из value-модели
+  compute(model.$.total, () => (model.price ?? 0) * (model.quantity ?? 0));
+
+  // computeFrom: явный список источников
+  computeFrom([model.$.price, model.$.quantity], model.$.total, (price, qty) => price * qty);
+
+  // кросс-уровневое: fullName из вложенной группы
+  compute(model.$.fullName, () =>
+    [model.personalData.firstName, model.personalData.lastName].filter(Boolean).join(' ')
+  );
+});
+```
+
+### Async reaction / dynamic options — `onChange`
+
+Для async-реакции на изменение поля (загрузка справочников, зависимые селекты) используй
+`onChange` из DSL. Колбэк выполняется вне effect-контекста (можно писать сигналы/ноды), а
+2-й аргумент — `{ signal }` (AbortSignal) для отмены устаревших запросов.
+
+```typescript
+import { defineFormBehavior, onChange } from '@reformer/core/behaviors';
+
+const behavior = defineFormBehavior<MyForm>(({ model, form }) => {
+  onChange(
+    model.$.region,
+    async (region, { signal }) => {
+      if (!region) {
+        form.city.updateComponentProps({ options: [] });
+        return;
+      }
+      const cities = await fetchCities(region, { signal });
+      form.city.updateComponentProps({ options: cities });
+    },
+    { debounce: 300 }
+  );
+});
+```
+
+> Низкоуровневый аналог — примитив `watchField(model.$.region, cb)` из `@reformer/core` (без debounce/AbortSignal;
+> для сети предпочтителен `onChange`). См. `20-compute-vs-watch.md`, `32-async-options-loading.md`.
+
+### Reading values
+
+```typescript
+// В React-компоненте — хуки
+const { value, errors, disabled } = useFormControl(form.email);
+const loanType = useFormControlValue(form.loanType); // значение напрямую
+
+// Вне React — из модели
+model.email;             // value-доступ (реактивно внутри effect/computed)
+model.$.email.value;     // через сигнал
+model.$.email.peek();    // нереактивный снимок
+model.get();             // весь объект-снимок
+```
+
+### Submit + validation
+
+Валидация — отдельная `ValidationSchema<T>` (`defineValidationSchema`), а не часть layout. Раннер
+`validateModel(model, schema)` сам роутит ошибки в ноды формы и возвращает `Promise<boolean>`
+(`false` = есть блокирующая ошибка; `severity: 'warning'` не блокирует).
+
+```typescript
+import { validateModel } from '@reformer/core/validation';
+
+async function handleSubmit(e: React.FormEvent) {
+  e.preventDefault();
+  const ok = await validateModel(model, schema); // ошибки сами доезжают до нод формы (UI подсветит)
+  if (!ok) return;                               // false → есть блокирующая ошибка
+  await api.send(model.get());
+  model.reset(); // к initial-снимку
+}
+```
+
+Multi-step: держи отдельные под-схемы на шаг и вызывай `validateModel(model, stepSchema)`. Для wizard'а —
+`makeValidationConfig(model)` → `{ validateStep, validateAll }` (`validateAll` прогоняет полную
+`apply(...STEP_SCHEMAS, extras)`). См. `13-multi-step.md`, `28-submit-and-reset.md`.
+
+### Cross-field validation — через `cross`
+
+Cross-field правило — обычная функция над **снапшотом** модели (`fn` получает `model.get()`),
+навешивается оператором `cross(sig, fn)` на поле-носитель ошибки внутри схемы:
+
+```typescript
+import { defineValidationSchema, validate, cross } from '@reformer/core/validation';
+import { required, min } from '@reformer/core/validators';
+import type { ValidationError } from '@reformer/core';
+
+// снапшот формы читается напрямую — без каста, соседние поля доступны как поля объекта
+const initialPaymentVsProperty = (f: MyForm): ValidationError | null =>
+  f.initialPayment && f.propertyValue && f.initialPayment > f.propertyValue
+    ? { code: 'tooHigh', message: 'Взнос не может превышать стоимость' }
+    : null;
+
+const schema = defineValidationSchema<MyForm>(({ model }) => {
+  validate(model.$.initialPayment, [required(), min(0)]);
+  cross(model.$.initialPayment, initialPaymentVsProperty); // ошибка сядет на initialPayment
+});
+```
+
+> Для элемента массива / под-модели захвати нужный снапшот в замыкание (`const item = im.get();
+> cross(im.$.x, () => rule(item))`) — `fn` всегда получает модель ТЕКУЩЕГО scope, а не под-модель.
+
+### Conditional validation — `validateWhen`
+
+Условная валидация — `validateWhen(() => cond, () => { … })`: правила внутри активны, только пока
+условие истинно; при `false` ранее тронутые поля гасятся. Это не `enable` (то — поведение), а
+включение/выключение самих проверок:
+
+```typescript
+import { validateWhen, validate, cross } from '@reformer/core/validation';
+
+validateWhen(
+  () => model.loanType === 'mortgage',
+  () => {
+    validate(model.$.propertyValue, [required(), min(1000000)]);
+    cross(model.$.initialPayment, initialPaymentVsProperty);
+  }
+);
+```
+
+### Перезапуск прогона — `revalidateWhen` (мост поведение → валидация)
+
+Схема прогоняется по требованию (submit/шаг). Чтобы перезапустить её при изменении зависимости —
+`revalidateWhen` из **поведения** (единственный мост поведение → валидация):
+
+```typescript
+import { defineFormBehavior, revalidateWhen } from '@reformer/core/behaviors';
+import { validateModel } from '@reformer/core/validation';
+
+const behavior = defineFormBehavior<MyForm>(({ model }) => {
+  revalidateWhen([model.$.propertyValue], () => void validateModel(model, schema));
+});
+```
+
+### Extracting named rules
+
+Когда тело правила растёт — выноси в именованную функцию. Field-правило типизируй `Rule<T>`
+(`(value) => ValidationError | null`), cross-field — обычной `(f: Root) => ValidationError | null`.
+Схема остаётся плоской и читается как оглавление:
+
+```typescript
+import { defineValidationSchema, validate } from '@reformer/core/validation';
+import { required } from '@reformer/core/validators';
+import type { Rule } from '@reformer/core/validation';
+
+// field-правило: (value) => error
+const validateAdultAge: Rule<string> = (value) => {
+  if (!value) return null;
+  const age = new Date().getFullYear() - new Date(value).getFullYear();
+  return age < 18 ? { code: 'tooYoung', message: 'Минимум 18 лет' } : null;
+};
+
+const schema = defineValidationSchema<MyForm>(({ model }) => {
+  validate(model.$.birthDate, [required(), validateAdultAge]);
+});
+```
+
+**Naming convention** (camelCase, семантика, не эхо оператора):
+
+- Cross-field правило → инвариант: `initialPaymentVsPropertyValue`, `paymentToIncomeUnderHalf`.
+- Field-правило → проверка: `validateAdultAge`, `passwordsMatch`.