@reformer/core 10.2.0 → 11.0.0-beta.10

package/docs/llms/29-async-preload.md

@@ -0,0 +1,203 @@
+# Async Preload — Загрузка начальных значений и справочников
+
+## Purpose
+
+Загрузка формы данными с сервера: (1) **initial values** в `createModel(...)` / `createForm({ initial })`; (2)
+**`model.set` / `model.patch`** для загрузки/обновления значений; (3) **external React-hook**
+для full-blown async preload (параллельный fetch заявки + справочников, обработка ошибок,
+race-guard через deps). Динамические `componentProps` (опции селектов) обновляются через
+`form.field.updateComponentProps({ options })` в `queueMicrotask`, чтобы не пересечься с
+реактивными эффектами от `set`/`patch`.
+
+## API
+
+```typescript
+// Модель:
+model.set(value: T): void;            // полная установка значений (load полного DTO). Не меняет initial.
+                                      // DTO без части ключей: поля остаются прежними, в dev — предупреждение.
+model.patch(value: DeepPartial<T>): void; // частичное слияние (только переданные ключи, на любой глубине групп; undefined — «не трогать»). Не меняет initial.
+model.reset(): void;                  // вернуть к initial-снимку
+model.captureInitial(): void;         // сделать текущие значения новым initial-снимком
+
+// Нода поля/группы:
+form.field.updateComponentProps(props: Record<string, unknown>): void; // динамические опции и т.п.
+```
+
+Initial values задаются в `createModel(initial)`; `reset()` возвращает к ним. Чтобы загруженные
+данные стали новой «точкой отсчёта» для `reset()` — вызови `model.captureInitial()` после load.
+
+## Examples
+
+### Initial values в модели
+
+```typescript
+import { createModel, createFormFromModel, type FormSchemaNode } from '@reformer/core';
+import { Input, SelectAsync, CheckboxWithLabel } from '@reformer/ui-kit';
+
+interface ProfileForm {
+  username: string;
+  language: 'ru' | 'en';
+  marketing: boolean;
+}
+
+const model = createModel<ProfileForm>({ username: '', language: 'ru', marketing: true });
+const schema: FormSchemaNode = {
+  children: [
+    { model: model.$.username, component: Input, componentProps: { label: 'Username' } },
+    {
+      model: model.$.language,
+      component: SelectAsync,
+      componentProps: {
+        label: 'Язык',
+        options: [
+          { value: 'ru', label: 'Русский' },
+          { value: 'en', label: 'English' },
+        ],
+      },
+    },
+    {
+      model: model.$.marketing,
+      component: CheckboxWithLabel,
+      componentProps: { label: 'Рассылка' },
+    },
+  ],
+};
+const form = createFormFromModel({ model, schema });
+// model.get() === { username: '', language: 'ru', marketing: true }
+// после правок: model.reset() возвращает к этим значениям
+```
+
+### Async preload через external hook + model.set
+
+```tsx
+import { useEffect, useState } from 'react';
+import type { FormModel, FormGroup } from '@reformer/core';
+
+interface LoadingState { isLoading: boolean; error: string | null }
+
+export function useLoadCreditApplication(
+  model: FormModel<CreditApplicationForm>,
+  form: FormGroup<CreditApplicationForm>,
+  applicationId: string | null
+): LoadingState {
+  const [state, setState] = useState<LoadingState>({ isLoading: !!applicationId, error: null });
+
+  useEffect(() => {
+    if (!applicationId) { setState({ isLoading: false, error: null }); return; }
+    let cancelled = false;
+
+    (async () => {
+      setState({ isLoading: true, error: null });
+      try {
+        const [appResp, dictsResp] = await Promise.all([
+          fetchCreditApplication(applicationId),
+          fetchDictionaries(),
+        ]);
+        if (cancelled) return; // race-guard: сменили applicationId / unmount
+        if (appResp.status !== 200 || dictsResp.status !== 200) throw new Error('Сервер вернул ошибку');
+
+        // Загрузка значений в модель
+        model.set(appResp.data);
+
+        // Динамические componentProps — через queueMicrotask (после реактивных эффектов от set)
+        queueMicrotask(() => {
+          if (cancelled) return;
+          form.registrationAddress.city.updateComponentProps({ options: dictsResp.data.cities });
+        });
+
+        setState({ isLoading: false, error: null });
+      } catch (err) {
+        if (cancelled) return;
+        setState({ isLoading: false, error: err instanceof Error ? err.message : 'Ошибка' });
+      }
+    })();
+
+    return () => { cancelled = true; };
+  }, [applicationId]); // model/form стабильны (сборка через useFormBundle)
+
+  return state;
+}
+```
+
+### Preload через behavior — onChange на поле
+
+Загрузка справочника при выборе другого поля (после preload) — через `onChange`:
+
+```typescript
+import { defineFormBehavior, onChange } from '@reformer/core/behaviors';
+
+export const addressBehavior = defineFormBehavior<AddressForm>(({ model, form }) => {
+  onChange(
+    model.$.region,
+    async (region, { signal }) => {
+      if (!region) { form.city.updateComponentProps({ options: [] }); return; }
+      try {
+        const cities = await fetchCities(region, { signal });
+        form.city.updateComponentProps({ options: cities });
+      } catch {
+        form.city.updateComponentProps({ options: [] });
+      }
+    },
+    { debounce: 300 }
+  );
+});
+```
+
+## Anti-patterns
+
+```typescript
+// ❌ model/form пересоздаются на каждый рендер → preload запускается каждый раз
+function MyForm() {
+  const bundle = createForm<T>({ initial, schema }); // КАЖДЫЙ рендер!
+}
+
+// ✅ Стабильная сборка: useFormBundle вызывает фабрику ровно один раз (useMemo React вправе
+// сбросить и пересобрать форму, потеряв введённое)
+function MyForm() {
+  const { model, form } = useFormBundle(() => createForm<T>({ initial, schema }));
+}
+```
+
+```typescript
+// ❌ updateComponentProps синхронно после set → возможный конфликт с реактивными эффектами
+model.set(data);
+form.region.updateComponentProps({ options: [...] });
+
+// ✅ queueMicrotask, чтобы реактивные эффекты от set завершились
+model.set(data);
+queueMicrotask(() => form.region.updateComponentProps({ options: [...] }));
+```
+
+```typescript
+// ❌ Нет race-guard в async useEffect
+useEffect(() => { fetchData(id).then((d) => model.set(d)); }, [id]);
+
+// ✅ Cleanup-флаг
+useEffect(() => {
+  let cancelled = false;
+  fetchData(id).then((d) => { if (!cancelled) model.set(d); });
+  return () => { cancelled = true; };
+}, [id]);
+```
+
+## Troubleshooting
+
+**Q: После `set`/`patch` не показываются замечания.**
+A: `set`/`patch` не запускают валидацию (кроме живой стратегии `change`). После загрузки вызови
+`await bundle.validate()`; без сборки — `await validateModel(model, schema)` из
+`@reformer/core/validation`.
+
+**Q: Опции в `<Select>` не появляются после `updateComponentProps`.**
+A: (1) Оберни вызов в `queueMicrotask`; (2) убедись, что компонент подписан через `useFormControl`;
+(3) для массивов — пройдись по элементам (`form.items.map`) и обнови каждый.
+
+**Q: При `reset()` теряются данные с сервера.**
+A: `reset()` возвращает к initial-снимку из `createModel`, не к последнему `set`. Чтобы «сбросить
+к данным с сервера» — после `set` вызови `model.captureInitial()` (новая точка отсчёта).
+
+## See also
+
+- [28-submit-and-reset.md](./28-submit-and-reset.md) — обратная сторона жизненного цикла
+- [11-async-watchfield.md](./11-async-watchfield.md) — `onChange` для динамики после preload
+- [22-cycle-detection.md](./22-cycle-detection.md) — почему `queueMicrotask` нужен
+- [16-ui-components.md](./16-ui-components.md) — `updateComponentProps` для динамических опций

package/docs/llms/30-type-safety-recipes.md

@@ -0,0 +1,213 @@
+## 30. TYPE-SAFETY RECIPES
+
+Идиоматичные паттерны, которые держат сгенерированный код без `any` и `as`-кастов.
+
+### Recipe 1 — Imports (root cause prevention)
+
+- Модель/форма/типы — из `@reformer/core`; хуки — из `@reformer/core/react`; примитивы над
+  сигналами — из `@reformer/core/model`.
+- Схема валидации (операторы + раннер `validateModel`) — из `@reformer/core/validation`.
+- Чистые фабрики валидаторов — из `@reformer/core/validators`.
+- Словарь текстов замечаний (`defineIssueMessages`) — из `@reformer/core/i18n`.
+- Декларативный DSL (`defineFormBehavior` + операторы) — из `@reformer/core/behaviors`.
+
+```typescript
+import {
+  createModel,
+  createForm,
+  type FormModel,
+  type FormGroup,
+  type FormSchemaNode,
+} from '@reformer/core';
+import { useFormBundle, useFormControl } from '@reformer/core/react';
+import {
+  defineValidation,
+  validate,
+  validateModel,
+  type Rule,
+} from '@reformer/core/validation';
+import { required, min, max, email } from '@reformer/core/validators';
+import { defineFormBehavior, compute, enableWhen, onChange } from '@reformer/core/behaviors';
+```
+
+> **watchField — из `@reformer/core/model`** (примитив), НЕ из `@reformer/core/behaviors` (там `onChange`)
+> и не из корня `@reformer/core`.
+
+### Recipe 2 — Form-shape types: `interface` или `type`
+
+Оба варианта работают одинаково. Ограничения `Record<string, …>` у `createModel<T>`,
+`createForm<T>`, `FormGroup<T>` и `FormArray<T>` нет (`createModel` и `createForm` требуют только
+`T extends object`). Вид ноды поля `FormFields<T>` выводит по виду значения: обычный объект —
+`FormGroup`, массив объектов — `FormArray`, остальное (примитив, массив примитивов, `Date`, `File`)
+— `FormControl`. Index signature здесь не участвует, поэтому `interface` распознаётся так же, как
+`type`. Эталонная форма объявлена через `interface`.
+
+```typescript
+export interface PropertyItem {
+  type: 'apartment' | 'house' | 'car';
+  description: string;
+  estimatedValue: number;
+}
+
+export interface CreditApplication {
+  loanAmount: number | null;
+  properties: PropertyItem[]; // form.properties — FormArray<PropertyItem>
+  address: Address; // form.address — FormGroup<Address>
+  tags: string[]; // form.tags — FormControl<string[]>
+  // ...
+}
+
+// вычисляемые поля — отдельным типом; форма — пересечение
+export interface CreditApplicationDerived {
+  monthlyPayment: number;
+}
+export type CreditApplicationForm = CreditApplication & CreditApplicationDerived;
+```
+
+Оговорка только для своих обобщённых хелперов: `interface` не присваивается
+`Record<string, unknown>` (неявной index signature у него нет). Ограничение пиши через
+`T extends object`:
+
+```typescript
+// ❌ interface-форму этот хелпер не примет
+function snapshot<T extends Record<string, unknown>>(form: FormGroup<T>): T { return form.getValue(); }
+
+// ✅
+function snapshot<T extends object>(form: FormGroup<T>): T { return form.getValue(); }
+```
+
+### Recipe 3 — Схема привязана к ручкам модели
+
+Привязка узла — ручка модели (`model: model.$.field`), а не литерал. Тип узла `FormSchemaNode`
+закрыт: вид узла (поле, массив под-форм, подформа) сверяется с тем, чем является привязка, а
+опечатка в ключе не компилируется. Правил в схеме нет — они живут в отдельной схеме валидации.
+
+```typescript
+const creditSchema = (model: FormModel<CreditApplicationForm>): FormSchemaNode => ({
+  children: [
+    { model: model.$.loanAmount, component: InputNumber },
+    // вложенная группа — подформа: билдер получает под-модель FormModel<PersonalData>
+    { model: model.$.personalData, part: personalData },
+    // массив под-форм — { model, item }: билдер получает под-модель строки
+    { model: model.$.properties, component: FieldArray, item: propertyRow },
+  ],
+});
+
+// правила — отдельно; тип правила сверяется с типом поля
+const LOAN_AMOUNT_RULES: Rule<number | null>[] = [required(), min(50000)];
+
+const validation = defineValidation<CreditApplicationForm>(({ model }) => {
+  validate(model.$.loanAmount, LOAN_AMOUNT_RULES);
+});
+```
+
+### Recipe 4 — Cross-field валидаторы: `cross` над типизированным снимком
+
+Правило — обычная функция `(snapshot: T) => ValidationIssue | null`. Оператор `cross` берётся из
+аргумента схемы: тип снимка выведен из схемы, соседние поля читаются без `as`, ошибка вешается на
+поле-носитель:
+
+```typescript
+import type { ValidationIssue } from '@reformer/core';
+
+const initialPaymentVsProperty = (application: CreditApplicationForm): ValidationIssue | null =>
+  application.initialPayment &&
+  application.propertyValue &&
+  application.initialPayment > application.propertyValue
+    ? { code: 'initialPaymentTooHigh' } // текст — в словаре формы (defineIssueMessages)
+    : null;
+
+const loanRules = defineValidation<CreditApplicationForm>(({ model, cross }) => {
+  cross(model.$.initialPayment, initialPaymentVsProperty);
+});
+```
+
+### Recipe 5 — `compute` читает модель напрямую (без аннотаций)
+
+`compute(target, () => …)` читает value-модель (`model.field`) — типы полей выводятся из типа
+модели, `as`-касты не нужны:
+
+```typescript
+compute(model.$.monthlyPayment, () =>
+  annuityMonthly(model.loanAmount ?? 0, model.loanTerm ?? 0, model.interestRate ?? 0)
+);
+
+// nested reads — тоже напрямую
+compute(model.$.fullName, () =>
+  [model.personalData.firstName, model.personalData.lastName].filter(Boolean).join(' ')
+);
+```
+
+### Recipe 6 — `null` vs `undefined` для опциональных полей
+
+Оба работают. `null` — конвенция «пользователь очистил поле». Встроенные валидаторы
+(`min`, `max`, `minLength`, `maxLength`, `minDate`, `maxDate`, `minAge`, `maxAge`) пропускают
+пустые значения — guard `if (value != null)` не нужен.
+
+```typescript
+export interface CreditForm {
+  loanAmount: number | null;   // validate(model.$.loanAmount, [min(50000)]) — ок
+  loanPurpose: string | null;  // minLength — ок
+  birthDate: string | null;    // minAge — ок
+}
+```
+
+### Recipe 7 — Нода поля для кастомных компонентов
+
+`useFormControl(control)` типизируется по `FormControl<T>`. В props компонента используй `FormControl<T>`:
+
+```typescript
+import type { FormControl } from '@reformer/core';
+import { useFormControl } from '@reformer/core/react';
+
+type MyFieldProps<T> = { control: FormControl<T> };
+function MyField<T>({ control }: MyFieldProps<T>) {
+  const { value, issues, disabled } = useFormControl(control);
+  // ...
+}
+```
+
+Для массива под-форм — `FormArray<Item>` (`useFormControl` отдаёт `ArrayControlState`), для группы —
+`FormGroup<Group>`. Вид неизвестной ноды сужают гарды `isFormControl` / `isFormGroup` /
+`isFormArray`.
+
+### Recipe 8 — Вынос правил в именованные функции
+
+Field-правила — именованные `Rule<T>`, validation-схема остаётся плоской:
+
+```typescript
+import type { Rule } from '@reformer/core/validation';
+
+const validateAdultAge: Rule<string | null> = (value) => {
+  if (!value) return null;
+  const age = new Date().getFullYear() - new Date(value).getFullYear();
+  return age < 18 ? { code: 'birthDate.adult', params: { minAge: 18 } } : null;
+};
+
+// внутри defineValidation<MyForm>(({ model }) => { ... }):
+validate(model.$.birthDate, [validateAdultAge]);
+```
+
+### Recipe 9 — Результаты уровня формы — сужение по `status`
+
+`bundle.validate()`, `bundle.submission.submit(handler)` и `flow.next()` отвечают
+дискриминированными объединениями: поле результата доступно после проверки `status`, без `as`.
+
+```typescript
+const outcome = await bundle.submission.submit(api.send); // SubmitResult<Awaited<ReturnType<typeof api.send>>>
+if (outcome.status === 'submitted') use(outcome.result);
+else if (outcome.status === 'failed') report(outcome.error);
+else showIssues(outcome.validation.issues); // 'invalid' | 'error' | 'cancelled'
+
+const transition = await bundle.flow!.next(); // FlowTransition
+if (transition.status === 'stayed') console.log(transition.reason); // 'invalid' | 'error' | …
+```
+
+### Anti-patterns to avoid
+
+- `import { computeFrom } from '@reformer/core/behaviors'` для примитива, вызываемого вне
+  `defineFormBehavior` → примитив живёт в `@reformer/core/model` (возвращает cleanup).
+- `T extends Record<string, unknown>` в своих хелперах формы → `T extends object` (Recipe 2).
+- `as`-касты значений полей внутри `compute` → читай `model.field` напрямую (Recipe 5).
+- строковые пути / `(form) => ...` в behaviors → это удалённый API, используй сигналы (`model.$.x`).
+- `node instanceof …` → ноды — интерфейсы; гарды `isFormControl` / `isFormGroup` / `isFormArray`.

package/docs/llms/31-async-validator-debounce.md

@@ -0,0 +1,178 @@
+## 31. ASYNC VALIDATOR
+
+Для проверок типа «уникальность email», «валидация ИНН через API», «проверка адреса» —
+async-правило это `AsyncRule<T>` = `(value, { signal }) => Promise<ValidationIssue | null>`.
+Оно регистрируется оператором `validateAsync(sig, [asyncRules])` внутри схемы валидации
+(`@reformer/core/validation`) и исполняется прогоном — уровнем формы (`bundle.validate()`,
+`bundle.submission.submit(handler)`, `flow.next()`) либо раннером `validateModel`. Async-правила
+прогоняются параллельно через `Promise.all`, прогон их дожидается.
+
+Слои разделены: схема формы (билдер `createForm` / JSON) правил НЕ несёт — они живут в
+отдельной функции-схеме `defineValidation<T>(({ model }) => …)`.
+
+**Сбой async-правила блокирует.** Если правило отклонило промис (сеть, исключение), прогон получает
+статус `error`, а поле — замечание `{ code: 'ruleFailed' }` («Не удалось проверить поле. Повторите
+попытку»): форму, которую не удалось проверить, прогон валидной не считает.
+
+```ts
+import { createForm, createModel } from '@reformer/core';
+import {
+  validate,
+  validateAsync,
+  defineValidation,
+  validateModel,
+  type AsyncRule,
+} from '@reformer/core/validation';
+import { required, email } from '@reformer/core/validators';
+
+// async-правило: (value, { signal }) => Promise<ValidationIssue | null>.
+// `signal` — AbortSignal устаревшего прогона: прокинь его в fetch, чтобы отменить in-flight.
+const checkEmailUnique: AsyncRule<string> = async (value, { signal }) => {
+  if (!value) return null; // пусто = валидно (sync `required` отдельно)
+  // try/catch не нужен: отклонённый запрос раннер запишет сбоем правила (статус `error`,
+  // ошибка `ruleFailed` на поле), а отмену устаревшего прогона отличит сам по `signal`.
+  const res = await fetch(`/api/check-email?email=${encodeURIComponent(value)}`, { signal });
+  const { available } = (await res.json()) as { available: boolean };
+  return available ? null : { code: 'email.taken' }; // текст кода — в словаре формы
+};
+
+// Схема — обычная функция над моделью; sync и async — разными операторами на одном сигнале.
+const schema = defineValidation<{ email: string }>(({ model }) => {
+  validate(model.$.email, [required(), email()]); // sync-фабрики
+  validateAsync(model.$.email, [checkEmailUnique]); // async-правило
+});
+
+// В сборке — прогон уровнем формы:
+const signup = createForm<{ email: string }>({ initial: { email: '' }, validation: schema });
+const outcome = await signup.submission.submit(api.signup); // обработчик — только при valid
+
+// Без сборки — раннер:
+const model = createModel<{ email: string }>({ email: '' });
+const ok = await validateModel(model, schema); // Promise<boolean>
+```
+
+### Как это исполняется
+
+1. Прогон (`bundle.validate()` / `validateModel(model, schema)`) открывает ambient-окно и
+   **синхронно** прогоняет схему:
+   `validate`/`validateAsync`/`cross` регистрируют правила своих полей.
+2. Sync-правила выполняются сразу; async-правила из `validateAsync` собираются и после закрытия
+   ambient-окна дожидаются параллельно (`Promise.all`) с прокинутым `AbortSignal`.
+3. Пока async-правила поля не завершились, его нода в состоянии `pending`
+   (`form.email.pending.value`, `useFormControl(form.email).pending`).
+4. Замечания разносятся по нодам формы, UI подсвечивает поле; поля, ставшие валидными, гасятся.
+   Отклонённое правило даёт на своём поле замечание `ruleFailed`.
+5. Итог — `ValidationResult` со статусом (`bundle.validate()`, `runValidation`) либо `boolean`
+   (`validateModel`: `true` только при `valid`; `severity:'warning'` не блокирует). Замечания
+   (`invalid`), сбой правила (`error`) и устаревший отменённый прогон (`cancelled`) — не `valid`.
+
+Синхронного варианта у контракта нет: прогон всегда `async`.
+
+### Результат прогона и сбой правила
+
+Когда нужно отличить «в форме замечания» от «проверить не удалось», бери полный результат —
+`bundle.validate()` / `bundle.validateStep(id)` сборки, а для отправки — статус `SubmitResult`:
+
+```ts
+const outcome = await bundle.submission.submit(api.send);
+if (outcome.status === 'error') {
+  // outcome.validation.failures: [{ handle, error }] — какое правило и почему не вернуло результат
+  showToast('Не удалось проверить форму. Повторите попытку');
+}
+```
+
+Без сборки — `runValidation(model, schema)` (только сбор) и `applyValidationResult`:
+
+```ts
+import { applyValidationResult, runValidation } from '@reformer/core/validation';
+
+const result = await runValidation(model, schema); // только сбор: ни замечаний, ни pending на нодах
+if (result.status === 'cancelled') return; // вытеснен более новым прогоном — не разносится
+applyValidationResult(result, { touch: true }); // замечания (и ruleFailed) — на поля
+if (result.status === 'valid') await send(model.get());
+```
+
+Если сбой сети НЕ должен блокировать отправку (проверка необязательна), перехвати его в самом
+правиле и верни `null` — это явное решение автора правила, а не поведение по умолчанию:
+
+```ts
+const softCheck: AsyncRule<string> = async (value, { signal }) => {
+  try {
+    const res = await fetch(`/api/check?value=${encodeURIComponent(value)}`, { signal });
+    return (await res.json()).ok ? null : { code: 'rejected' };
+  } catch {
+    return null; // осознанно: недоступность сервиса проверку не проваливает
+  }
+};
+```
+
+### Sync и async — два оператора
+
+Разделение sync/async делается не полем схемы, а разными операторами на одном сигнале:
+`validate(sig, [syncRules])` и `validateAsync(sig, [asyncRules])`. Раннер прогоняет sync-правила
+инлайн, а async — дожидается. Держи async-правило дешёвым: ранний `if (!value) return null`
+пропускает сетевой вызов, пока `required()`/формат ещё не пройдены.
+
+```ts
+validate(model.$.inn, [required(), pattern(/^\d{12}$/)]); // формат — sync, мгновенно
+validateAsync(model.$.inn, [checkInnInRegistry]); // обращение к API — отдельным оператором
+```
+
+### UI integration
+
+Пока идут async-правила поля, раннер держит его ноду в `pending` — индикатор проверки поля
+берётся из состояния ноды, свой флаг не нужен:
+
+```tsx
+const { issues, pending, shouldShowIssues } = useFormControl(form.email);
+const message = useIssueMessage(formMessages); // @reformer/core/react
+
+return pending ? <Spinner /> : shouldShowIssues ? <Error text={message(issues[0])} /> : null;
+```
+
+Индикатор прогона всей формы — сигнал `bundle.validating` сборки (`createForm`): он истинен,
+пока идёт полный прогон либо прогон шага; `bundle.submission.submitting` — пока работает обработчик
+отправки.
+
+### Debounce и отмена
+
+- **Отмена устаревших — бесплатно.** Быстрый повторный прогон той же пары `(model, schema)`
+  отменяет предыдущий in-flight прогон через `AbortController`; его `AbortSignal` прокинут в
+  `validateAsync`-правила, поэтому `fetch(url, { signal })` рвётся сам. Ручной debounce для
+  КОРРЕКТНОСТИ не нужен — держи схему стабильным `const` (`defineValidation`), иначе отмена не
+  сматчит прогоны по идентичности.
+- Валидация запускается on-demand (submit / шаг / через `revalidateWhen`) либо живой стратегией
+  сборки — `validation: { rules, strategy: 'change', debounce: 300 }` (см. `33-validation-strategy.md`):
+  у живой фазы debounce встроен.
+- Если нужно дебаунсить дорогой async-валидатор относительно частых изменений одного поля — триггерь
+  прогон из поведения через `onChange`, который даёт debounce из коробки:
+
+  ```ts
+  import { defineFormBehavior, onChange } from '@reformer/core/behaviors';
+  import { validateModel } from '@reformer/core/validation';
+
+  export const behavior = defineFormBehavior<{ username: string }>(({ model }) => {
+    onChange(model.$.username, () => void validateModel(model, schema), { debounce: 300 });
+  });
+  ```
+
+  Либо оборачивай в свой debounce колбэк `revalidateWhen([...], () => void validateModel(...))`.
+- **Async cross-field** — инлайн `validateAsync`-правило, замыкающее `model` и читающее снимок
+  соседей `model.get()` до первого `await` (`AsyncRule` получает только `value` и `signal`;
+  `cross` — синхронный):
+
+  ```ts
+  validateAsync(model.$.email, [
+    async (email, { signal }) => {
+      const { username } = model.get(); // снапшот соседних полей до await
+      const res = await fetch(`/api/check?email=${email}&user=${username}`, { signal });
+      return (await res.json()).ok ? null : { code: 'conflict' };
+    },
+  ]);
+  ```
+
+### See also
+
+- [27-revalidate-when.md](27-revalidate-when.md) — перезапуск `validateModel` по триггерам
+- [29-async-preload.md](29-async-preload.md) — async preload данных при init формы
+- [32-async-options-loading.md](32-async-options-loading.md) — `onChange` с debounce + AbortSignal