@reformer/core 11.0.0-beta.8 → 11.0.0-beta.9

package/docs/llms/35-unified-contract.md

@@ -7,8 +7,9 @@
 (`createForm`), поведение одно (`defineFormBehavior`). Способы отличаются только видом схемы
 (билдер или документ) и тем, кто рисует результат.
 
-Прежние записи — ключи `value` / `array`, оператор `each`, `createCoreForm` — пока принимаются.
-Новый код пишется так, как описано здесь.
+Прежние записи узла — ключи `value` / `array` и запись «имя поля → узел» — удалены: тип узла
+закрыт, сборка их не читает. Удалены и оператор `each`, свободный `cross` и имя `createCoreForm`:
+их заменяют `applyEach` со схемой строки, `cross` из аргумента схемы и `createForm`.
 
 | Слой      | поле                              | массив под-форм                           | подформа                              |
 | --------- | --------------------------------- | ----------------------------------------- | ------------------------------------- |
@@ -51,10 +52,10 @@ export const createCreditModel = () =>
 ## Схема — одно дерево
 
 ```typescript
-import type { FormModel } from '@reformer/core';
+import type { FormModel, FormSchemaNode } from '@reformer/core';
 
 // подформа: объявлена один раз, получает под-модель
-const address = (model: FormModel<Address>) => ({
+const address = (model: FormModel<Address>): FormSchemaNode => ({
   component: Box,
   children: [
     { model: model.$.city, component: Input, componentProps: { label: 'Город' } },
@@ -63,13 +64,13 @@ const address = (model: FormModel<Address>) => ({
 });
 
 // строка массива — такая же функция от под-модели
-const coBorrower = (model: FormModel<CoBorrower>) => ({
+const coBorrower = (model: FormModel<CoBorrower>): FormSchemaNode => ({
   selector: 'co-borrower',
   component: Box,
   children: [{ model: model.$.name, component: Input, componentProps: { label: 'ФИО' } }],
 });
 
-export const creditSchema = (model: FormModel<CreditForm>) => ({
+export const creditSchema = (model: FormModel<CreditForm>): FormSchemaNode => ({
   component: Box,
   children: [
     { model: model.$.loanType, component: SelectAsync, componentProps: { label: 'Тип' } }, // поле
@@ -80,7 +81,7 @@ export const creditSchema = (model: FormModel<CreditForm>) => ({
       componentProps: { title: 'Адрес регистрации' },
       children: [{ model: model.$.registrationAddress, part: address }], // подформа
     },
-    { model: model.$.coBorrowers, component: FormArray, item: coBorrower }, // массив под-форм
+    { model: model.$.coBorrowers, component: FieldArray, item: coBorrower }, // массив под-форм
   ],
 });
 ```
@@ -94,11 +95,16 @@ export const creditSchema = (model: FormModel<CreditForm>) => ({
 | подформа        | `model` — группа, `part` — функция            |
 | контейнер       | есть `children`, нет `model`                  |
 
-- Узел узнаётся по ЗНАЧЕНИЮ: в записи «имя поля → узел» поле данных может называться `model`,
-  `item`, `part` или `value` — под таким ключом лежит обычный вложенный узел.
+- Тип узла `FormSchemaNode` закрыт: опечатка в ключе, группа без `part`, `item` не на массиве и
+  привязка value-фасадом (`model: model.email`) не компилируются.
+- Вложенные узлы читаются только из `children` и из поддерева `part`. В `componentProps` и под
+  произвольными ключами сборка не заглядывает; в dev она предупреждает о ключах узла, которые не
+  читает.
+- Вид ноды формы определяет узел модели, а не имя: поле данных может называться `value`, `schema`,
+  `form`, `model` или `children`.
 - Поля подформы принадлежат той же форме: `form.registrationAddress.city`.
-- Билдер `item` / `part` вызывается один раз на под-модель; сборка и рендерер получают одно и то
-  же поддерево (`schemaSubtree(builder, subModel)`).
+- Билдер `item` / `part` вызывается один раз на под-модель; сборка и рендерер получают одну и ту
+  же компиляцию поддерева: `content` подформы и `row(rowModel)` массива.
 - `initialValue` узла-массива — запасной шаблон нового элемента для форм, чья модель создаётся из
   данных без кода. Шаблон модели (`arrayOf`) главнее.
 
@@ -108,24 +114,24 @@ export const creditSchema = (model: FormModel<CreditForm>) => ({
 import {
   apply,
   applyEach,
-  cross,
-  defineValidationSchema,
+  defineValidation,
   validate,
   validateWhen,
 } from '@reformer/core/validation';
 
-const addressRules = defineValidationSchema<Address>(({ model }) => {
+const addressRules = defineValidation<Address>(({ model, cross }) => {
   validate(model.$.city, [required()]);
-  cross<Address>(model.$.street, (address) =>
+  // cross — из аргумента схемы: снимок области (Address) выведен, приведения не нужны
+  cross(model.$.street, (address) =>
     address.city !== '' && address.street === '' ? streetRequired : null
   );
 });
 
-const coBorrowerRules = defineValidationSchema<CoBorrower>(({ model }) => {
+const coBorrowerRules = defineValidation<CoBorrower>(({ model }) => {
   validate(model.$.name, [required()]);
 });
 
-export const contactsRules = defineValidationSchema<CreditForm>(({ model }) => {
+export const contactsRules = defineValidation<CreditForm>(({ model }) => {
   apply(model.$.registrationAddress, addressRules);
   validateWhen(
     () => !model.sameAsRegistration,
@@ -136,13 +142,36 @@ export const contactsRules = defineValidationSchema<CreditForm>(({ model }) => {
 ```
 
 - У схемы, подключённой через `apply(ручка, схема)` / `applyEach`, своя область: `model` — под-модель,
-  `cross` получает её снапшот. Захватывать снапшот в замыкание больше не нужно.
+  `cross` из аргумента схемы получает её снимок. Захватывать снимок в замыкание не нужно.
 - Одна и та же схема подключается и к группе, и к элементам массива.
 - `apply(model.$.a, rules)` принимает и массив ручек: `apply([model.$.a, model.$.b], rules)`.
 - `apply(schemaA, schemaB)` — композиция схем над той же моделью — остаётся.
-- Правило получает `(value, scope, root)`: модель области и корень прогона.
-- `each(model.items, (item) => …)` — прежняя запись `applyEach`: принимает фасад и ручку, области
-  не создаёт.
+- Правило значения — `Rule<T> = (value: T) => ValidationIssue | null`: один аргумент. Тип значения
+  сверяется с типом поля; набор правил объявляют типом поля (`Rule<LoanType>[]`,
+  `Rule<number | null>[]`).
+- Текста у замечания нет: `ValidationIssue = { code, params?, severity? }`. Правило несёт код
+  (встроенный либо свой — `required({ code: 'street.required' })`), строку по коду даёт словарь
+  формы (`defineIssueMessages`) поверх словаря локали — см. `36-issue-messages.md`.
+- `cross` берётся только из аргумента схемы: свободного оператора с таким именем в
+  `@reformer/core/validation` нет. Нет и `each` — правила строки подключает `applyEach`.
+
+### Результат прогона
+
+```typescript
+const result = await credit.validate(); // либо credit.validateStep('loan'), runValidation(model, rules)
+// result.status: 'valid' | 'invalid' | 'error' | 'cancelled'
+// result.issues: Map<ручка поля, замечания>;  result.failures: правила, не вернувшие результат
+
+const outcome = await credit.submission.submit(sendApplication); // SubmitResult
+// outcome.status: 'submitted' | 'invalid' | 'error' | 'cancelled' | 'failed'
+```
+
+- `validateModel()` (раннер без сборки) отвечает `boolean`: `true` только для `valid`.
+- **Сбой async-правила блокирует**: статус `error`, на поле — замечание `{ code: 'ruleFailed' }`.
+- Отменённый прогон (`cancelled`) по нодам не разносится.
+- Пока идут async-правила поля, его нода в `pending`; `credit.validating` — идёт ли проверка.
+- У нод методов `validate()` / `submit()` нет: проверка и отправка — уровень формы, см.
+  `38-form-flow.md`.
 
 ## Поведение — модель, форма и схема
 
@@ -155,19 +184,27 @@ import {
   hideWhen,
   onComponentEvent,
   onMount,
+  renderEffect,
 } from '@reformer/core/behaviors';
 
 const addressBehavior = defineFormBehavior<Address>(({ model, schema }) => {
   hideWhen(schema.node('street'), () => model.city === ''); // узел ищется внутри части
 });
 
-export const creditBehavior = defineFormBehavior<CreditForm>(({ model, form, schema }) => {
+export const creditBehavior = defineFormBehavior<CreditForm>(({ model, form, schema, flow }) => {
   const isMortgage = () => model.loanType === 'mortgage';
 
   enableWhen(model.$.propertyValue, isMortgage, { resetOnDisable: true });
   hideWhen(schema.node('mortgage'), () => !isMortgage());
-  onComponentEvent(schema.node('wizard'), 'onSubmit', () => submitApplication(model.get()));
+  // визард в рендерере зовёт onSubmit через bundle.submission.submit — только после успешной
+  // проверки; values — модель целиком, с выключенными полями
+  onComponentEvent(schema.node('wizard'), 'onSubmit', (values: CreditForm) =>
+    sendApplication(values)
+  );
   onMount(schema.node('data-boundary'), () => void loadApplication(model));
+  renderEffect(schema, () => {
+    if (isMortgage()) flow?.goTo('loan'); // поток шагов сборки; без flow — undefined
+  });
 
   apply([model.$.registrationAddress, model.$.residenceAddress], addressBehavior);
   applyEach(model.$.coBorrowers, coBorrowerBehavior);
@@ -186,6 +223,8 @@ export const creditBehavior = defineFormBehavior<CreditForm>(({ model, form, sch
 | `schema.node(sel).setHidden / patchProps` | принудительная видимость и пропсы узла                     |
 | `schema.node(sel).getRef()`               | ref на компонент узла — объект `{ current }`               |
 
+- Область поведения — `{ model, form, schema, flow }`: `flow` — поток шагов сборки, один на всю
+  сборку (его же получают поведения подформ и строк).
 - **Области изолированы.** `schema.node(selector)` ищет узел только в своей области: корневое
   поведение — в корневом дереве, поведение подформы и строки массива — в своём поддереве. До узла
   строки или части корень дотягивается через `applyEach` / `apply`. Два монтирования одной части
@@ -194,48 +233,62 @@ export const creditBehavior = defineFormBehavior<CreditForm>(({ model, form, sch
 - **Операторы узлов только записывают правило — исполняет его рендерер.** При разметке в JSX они
   ничего не делают: видимость, отправка и загрузка данных остаются в JSX.
 - Правило на селектор, которого нет в дереве, ничего не делает; в dev — предупреждение.
+- **Несколько поведений на один узел.** Условия `hideWhen` на один селектор объединяются по «или»:
+  узел скрыт, пока истинно любое. Обработчики событий и хуки монтирования — стеком: действует
+  последний, его снятие возвращает прежний. Снятие поведения убирает только его правила.
+- **`setHidden` / `patchProps` поведения откатываются при его снятии** — вместе с записанным в
+  его `onDispose`. Значение, которое с тех пор переписал кто-то другой, остаётся.
 
 ## Сборка — `createForm`
 
 ```tsx
-import { createForm, useFormBundle } from '@reformer/core';
+import { createForm } from '@reformer/core';
+import { useFormBundle } from '@reformer/core/react';
 
 const credit = useFormBundle(() =>
   createForm<CreditForm>({
     model: createCreditModel(), // либо initial: { … }
     schema: creditSchema, // (model) => узел; для JSON — документ + registry
     behavior: creditBehavior,
-    validation: { steps: { loan: loanRules, contacts: contactsRules }, extras: crossRules },
+    validation: { extras: crossRules }, // правила вне шагов; голая схема = { rules }
+    flow: { steps: [{ id: 'loan', rules: loanRules }, { id: 'contacts', rules: contactsRules }] },
   })
 );
-// credit = { model, form, validation, render }
+// credit = { model, form, render, flow, validating, submission, validate, validateStep, dispose }
 
 <FormRenderer form={credit} settings={{ fieldWrapper: FormField }} />; // рендерер
 <FormField control={credit.form.loanType} />; // разметка в JSX — та же сборка
 ```
 
-- Порядок: модель → `seed` → дерево схемы → ноды формы → поведение → валидация → `setup`. Дерево
-  строится один раз.
-- `validation` в бандле типизирована по конфигу: правила переданы — поле есть всегда.
-- `render` — `{ tree, controller, node(selector) }`: готовое дерево и схема-контроллер сборки.
+- Порядок: модель → `seed` → дерево схемы → компиляция → уровень формы (правила, поток шагов) →
+  ноды формы → поведение → `setup`. Дерево строится и компилируется один раз. Ноды строятся по
+  виду узла модели: лист и массив-значение — `FormControl`, группа — `FormGroup`, массив
+  под-форм — `FormArray`.
+- Повтор `selector` в одной области — исключение при сборке. В dev правило поведения на узел,
+  которого нет, и шаг `flow.steps` без узла с таким `selector` дают предупреждение.
+- Уровень формы: `validate()` и `validateStep(id)` → `ValidationResult`, отправка — отдельный
+  объект `submission`: `submission.submit(handler)` → `SubmitResult`, `submission.submitting`;
+  `flow` — поток шагов (`next` / `previous` / `goTo`). См. `38-form-flow.md`.
+- `dispose()` снимает сборку: поведение формы, подписки нод, живую проверку; идущие проверки
+  получают `cancelled`, значения модели остаются. Вне React владелец сборки зовёт его сам;
+  `useFormBundle` сборку при размонтировании не снимает.
+- `render` — `{ tree, controller, node(selector) }`: скомпилированная схема (`CompiledSchema`, см.
+  `37-compiled-schema.md`) и схема-контроллер сборки.
 - JSON: `createForm({ model, schema: document, registry })` — дерево собирает
   `registry.resolveSchema`. Ядро документ не разбирает.
 - Внутри рендерера бандл доступен компонентам через `useFormBundleContext()` — так визард берёт
-  форму и валидацию сам.
+  форму и поток шагов сам и отправляет через `bundle.submission.submit`.
 
-### Низкоуровневые фабрики
+### Низкоуровневая фабрика
 
-| Задача                                         | Фабрика                                  |
-| ---------------------------------------------- | ---------------------------------------- |
-| форма из модели и готового дерева, без бандла  | `createFormFromModel({ model, schema })` |
-| форма без модели — плоская схема полей         | `createLegacyForm(schema)`               |
+`createFormFromModel({ model, schema })` — форма из модели и готового дерева, без бандла.
 
-`createForm` с готовым деревом вместо билдера или без модели бросает ошибку с отсылкой к нужной
-фабрике.
+Формы без модели нет: значения принадлежат модели. `createForm` без `model` и `initial` либо с
+готовым деревом вместо билдера бросает ошибку с подсказкой.
 
 ## Частые ошибки
 
-| Ошибка                                             | Как правильно                                           |
+| ❌ Ошибка                                          | Как правильно                                           |
 | -------------------------------------------------- | ------------------------------------------------------- |
 | `model: model.address` (под-модель у поля)         | `model: model.$.address.city` — привязка всегда с `$`   |
 | `{ model: model.$.address, component }` без `part` | группа полем не бывает — нужен `part`                   |
@@ -244,3 +297,11 @@ const credit = useFormBundle(() =>
 | `push({})` для новой строки                        | `arrayOf(blank)` в модели и `push()` без значения       |
 | `createModel(structuredClone(INITIAL))` с `arrayOf` | фабрика начальных значений — клон теряет шаблон массива |
 | `cross` в подформе читает корень                   | `apply(model.$.group, rules)` — область подформы        |
+| `{ value: model.$.x }`, `{ array: model.items }`   | `{ model: model.$.x }`, `{ model: model.$.items, item }` |
+| узлы записью `{ email: { model, component } }`     | `{ children: [{ model, component }] }`                  |
+| `Rule<unknown>[]` и `(form: Root)` с приведением   | `Rule<ТипПоля>[]`, `cross` из аргумента схемы           |
+| `try { … } catch { return null }` в async-правиле «на всякий случай» | сбой правила блокирует сам; `catch` — только если проверка необязательна |
+| `validation: { steps: { loan: rules } }`                             | `flow: { steps: [{ id: 'loan', rules }] }`                               |
+| `required({ message: '…' })`                                         | `required({ code: '<поле>.required' })` + `defineIssueMessages`          |
+| два узла с одним `selector` в одной области                          | разные селекторы — повтор бросает исключение                             |
+| отправка `api.send(model.get())` в обход проверки                    | `bundle.submission.submit(api.send)`                                     |

package/docs/llms/36-issue-messages.md

@@ -0,0 +1,284 @@
+# Тексты замечаний валидации — коды, словарь формы и резолвер
+
+## Purpose
+
+Замечание валидации текста не несёт. Правило сообщает **что** нарушено (`code`) и **с какими
+числами** (`params`), а отображаемую строку по коду собирает резолвер в момент показа:
+
+```typescript
+interface ValidationIssue {
+  readonly code: string; // встроенный ('required', 'minLength') либо свой ('loanAmount.required')
+  readonly params?: Readonly<Record<string, unknown>>; // порог правила, фактическое значение
+  readonly severity?: 'error' | 'warning'; // 'warning' показывается, но отправку не блокирует
+}
+```
+
+Отсюда два следствия:
+
+- смена языка переводит уже показанные замечания — повторная валидация не нужна;
+- одно и то же правило получает разный текст у разных полей: правилу дают свой код, а текст кода
+  кладут в словарь формы.
+
+Опций `message` / `messageKey` у правил нет, у замечания нет поля `message` — см.
+[17-nonexistent-api.md](./17-nonexistent-api.md).
+
+## API
+
+```typescript
+// @reformer/core — опции фабрик @reformer/core/validators (второй или последний аргумент)
+interface RuleOptions {
+  code?: string; // свой код вместо встроенного; принято `<поле>.<правило>`
+  params?: Readonly<Record<string, unknown>>; // доп. параметры — поверх параметров правила
+}
+
+// @reformer/core/i18n — без React
+type IssueMessage =
+  | string // шаблон: 'Не меньше {minLength} символов', plural, select
+  | ((params: Readonly<Record<string, unknown>>, i18n: I18nHandle) => string);
+type IssueMessages = Readonly<Record<string, IssueMessage>>; // код → текст
+
+function defineIssueMessages<const M extends IssueMessages>(messages: M): M; // возвращает аргумент
+function resolveIssueMessage(
+  issue: ValidationIssue,
+  i18n: I18nHandle, // createI18n(locale)
+  messages?: IssueMessages // словарь формы
+): string;
+
+// @reformer/core/react
+function useIssueMessage(messages?: IssueMessages): (issue: ValidationIssue) => string;
+
+// @reformer/cdk — словарь формы для поддерева; FormField читает его сам
+function ValidationMessagesProvider(props: {
+  messages?: IssueMessages;
+  resolver?: (issue: ValidationIssue) => string; // полное переопределение
+  children: ReactNode;
+}): ReactNode;
+function useIssueMessageResolver(): (issue: ValidationIssue) => string;
+```
+
+### Порядок поиска текста
+
+| Шаг | Источник                                                   | Когда срабатывает                                   |
+| --- | ---------------------------------------------------------- | --------------------------------------------------- |
+| 1   | словарь формы (`defineIssueMessages`) — запись по `code`   | у поля свой текст                                   |
+| 2   | `validation.<code>` из словаря активной локали             | встроенный код либо свой код в словаре приложения   |
+| 3   | `validation.<code>` из встроенной английской таблицы ядра  | встроенный код без провайдера локали                |
+| 4   | сам `code`                                                 | свой код, которого нет ни в одном словаре           |
+
+Свой код **не** падает обратно на текст встроенного правила: `required({ code: 'phone.required' })`
+без записи `'phone.required'` в словаре покажет строку `phone.required`. Каждый свой код получает
+запись в словаре формы (или ключ `validation.<код>` в словаре приложения).
+
+### Встроенные коды и параметры
+
+| Фабрика                         | `code`             | `params`                                   |
+| ------------------------------- | ------------------ | ------------------------------------------ |
+| `required()`                    | `required`         | —                                          |
+| `min(n)` / `max(n)`             | `min` / `max`      | `min` / `max`, `actual`                    |
+| `minLength(n)` / `maxLength(n)` | `minLength` / `maxLength`; у массива — `minItems` / `maxItems` | `minLength` / `maxLength`, `actualLength` |
+| `email()`                       | `email`            | —                                          |
+| `pattern(re)`                   | `pattern`          | `pattern` (исходник регулярки)             |
+| `url()`                         | `url`, `url_protocol` | `allowedProtocols` (у `url_protocol`)   |
+| `phone()`                       | `phone`            | `format`                                   |
+| `isNumber()` / `integer()`      | `isNumber` / `integer` | —                                      |
+| `multipleOf(n)`                 | `multipleOf`       | `multipleOf`                               |
+| `nonNegative()` / `nonZero()`   | `nonNegative` / `nonZero` | —                                   |
+| `isDate()`                      | `date_invalid`     | —                                          |
+| `minDate(d)` / `maxDate(d)`     | `date_min` / `date_max` | `minDate` / `maxDate`                 |
+| `pastDate()` / `futureDate()`   | `date_future` / `date_past` | — (код называет нарушение)        |
+| `minAge(n)` / `maxAge(n)`       | `date_min_age` / `date_max_age` | `minAge` / `maxAge`, `currentAge` |
+| `minAge(n)`, рождение в будущем | `date_future`     | `minAge`                                  |
+| `fileType(accept)`              | `fileType`         | `accept`, `fileName`                       |
+| `maxFileSize(b)` / `minFileSize(b)` | `maxFileSize` / `minFileSize` | `maxFileSize` / `minFileSize`, `fileName`, `actualSize` |
+| `maxFiles(n)` / `minFiles(n)`   | `maxFiles` / `minFiles` | `maxFiles` / `minFiles`, `actualCount` |
+| `maxTotalFileSize(b)`           | `maxTotalFileSize` | `maxTotalFileSize`, `actualTotal`          |
+| отклонённое async-правило       | `ruleFailed`       | —                                          |
+
+Свой код (`{ code }`) заменяет только код: параметры правила остаются, `params` из опций
+накладываются поверх них.
+
+### Шаблон и функция
+
+- Шаблон — тот же формат, что в словарях локали (подмножество ICU): подстановка `{minLength}`,
+  `{count, plural, one{…} other{…}}`, `{kind, select, …}`.
+- Параметры готовятся до подстановки: `Date` — по языку, массив — перечнем, размеры в байтах
+  (`maxFileSize`, `minFileSize`, `actualSize`, `maxTotalFileSize`, `actualTotal`) — строкой с
+  единицей. Числа остаются числами (иначе не сработал бы `plural`) и печатаются **без разрядов**.
+- Число с разрядами, валюта, вычисление — функция `(params, i18n) => string`; `i18n` — ручка
+  активной локали (`i18n.number`, `i18n.date`, `i18n.t`).
+- Битый шаблон в словаре формы текст поля не прячет: резолвер идёт дальше по порядку поиска.
+
+## Examples
+
+### Свой код у правила и словарь формы
+
+```typescript
+// validation/loan.ts — правила несут коды
+import { defineValidation, validate } from '@reformer/core/validation';
+import { max, min, minLength, required } from '@reformer/core/validators';
+
+export const loanRules = defineValidation<CreditForm>(({ model }) => {
+  validate(model.$.loanAmount, [
+    required({ code: 'loanAmount.required' }),
+    min(50_000, { code: 'loanAmount.min' }),
+  ]);
+  validate(model.$.loanPurpose, [minLength(10, { code: 'loanPurpose.minLength' })]);
+  validate(model.$.carYear, [max(new Date().getFullYear(), { code: 'carYear.max' })]);
+  validate(model.$.email, [required()]); // встроенный код: текст даёт локаль
+});
+```
+
+```typescript
+// validation/messages.ts — тексты по кодам; константа модуля (стабильная ссылка)
+import { defineIssueMessages } from '@reformer/core/i18n';
+
+export const creditMessages = defineIssueMessages({
+  'loanAmount.required': 'Укажите сумму кредита',
+  'loanAmount.min': (params, i18n) => `Минимум ${i18n.number(Number(params.min))} ₽`,
+  'loanPurpose.minLength': 'Минимум {minLength} символов',
+  'carYear.max': 'Не позднее {max}',
+  // встроенный код тоже можно переопределить — для всей формы
+  required: 'Заполните поле',
+});
+```
+
+### Подключение словаря — провайдер cdk
+
+`FormField` из `@reformer/cdk` и `@reformer/ui-kit` резолвит замечания сам; словарь формы
+подключается один раз на корне формы:
+
+```tsx
+import { ValidationMessagesProvider } from '@reformer/cdk';
+import { creditMessages } from './validation/messages';
+
+<ValidationMessagesProvider messages={creditMessages}>
+  <FormRenderer form={credit} settings={{ fieldWrapper: FormField }} />
+</ValidationMessagesProvider>;
+```
+
+- Вложенные провайдеры с `messages` накладываются друг на друга: ближний важнее, код, которого в
+  ближнем словаре нет, ищется во внешнем, затем в локали.
+- `resolver` заменяет резолвер поддерева целиком: локаль и внешние провайдеры для его замечаний не
+  участвуют (кроме `messages` этого же провайдера).
+- Язык задаёт `I18nProvider` из `@reformer/core/react`; без него тексты английские — см.
+  [34-i18n.md](./34-i18n.md).
+
+### Свой компонент замечаний — `useIssueMessage`
+
+```tsx
+import type { FormControl } from '@reformer/core';
+import { useFormControl, useIssueMessage } from '@reformer/core/react';
+import { creditMessages } from './validation/messages';
+
+function FieldIssues({ control }: { control: FormControl<string> }) {
+  const message = useIssueMessage(creditMessages); // словарь формы → локаль → английский → код
+  // shouldShowIssues — и у поля с одним предупреждением; shouldShowError — только у невалидного
+  const { issues, shouldShowIssues } = useFormControl(control);
+  if (!shouldShowIssues) return null;
+  return (
+    <ul role="alert">
+      {issues.map((issue) => (
+        <li key={issue.code}>{message(issue)}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+Внутри дерева с `ValidationMessagesProvider` — `useIssueMessageResolver()` из `@reformer/cdk`: он
+учитывает словари всех провайдеров выше.
+
+### Вне React
+
+```typescript
+import { createI18n, resolveIssueMessage } from '@reformer/core/i18n';
+import { ru } from '@reformer/core/locale/ru';
+
+const i18n = createI18n(ru);
+resolveIssueMessage({ code: 'minLength', params: { minLength: 8 } }, i18n); // 'Не меньше 8 символов'
+resolveIssueMessage({ code: 'loanAmount.required' }, i18n, creditMessages); // 'Укажите сумму кредита'
+```
+
+### Замечание из своего правила и с сервера
+
+Своё правило, `cross` и ответ сервера возвращают тот же `ValidationIssue` — код и параметры; текст
+кода — в словаре формы:
+
+```typescript
+const initialPaymentTooHigh = (loan: CreditForm): ValidationIssue | null =>
+  loan.initialPayment !== null &&
+  loan.propertyValue !== null &&
+  loan.initialPayment > loan.propertyValue
+    ? { code: 'initialPaymentTooHigh', params: { max: loan.propertyValue } }
+    : null;
+
+// ответ сервера — в ноду поля
+form.email.setIssues([{ code: 'email.taken' }]);
+```
+
+### Несколько языков в словаре формы
+
+Запись словаря — функция, получающая ручку локали, поэтому текст поля можно взять из словаря
+приложения и переключать вместе с языком:
+
+```typescript
+export const creditMessages = defineIssueMessages({
+  'loanAmount.required': (_params, i18n) => i18n.t('credit.loanAmount.required'),
+});
+```
+
+Другой путь — ключ `validation.loanAmount.required` в словаре приложения (шаг 2 порядка поиска).
+
+## Anti-patterns
+
+```typescript
+// ❌ Текст в правиле: у RuleOptions нет message — не скомпилируется
+required({ message: 'Укажите телефон' });
+
+// ✅ Свой код в правиле, текст — в словаре формы
+required({ code: 'phone.required' });
+const messages = defineIssueMessages({ 'phone.required': 'Укажите телефон' });
+```
+
+```tsx
+// ❌ Словарь, собранный в рендере: новая ссылка — резолвер пересоздаётся на каждый рендер
+const message = useIssueMessage(defineIssueMessages({ 'phone.required': 'Укажите телефон' }));
+
+// ✅ Словарь — константа модуля
+const messages = defineIssueMessages({ 'phone.required': 'Укажите телефон' });
+function PhoneIssues() {
+  const message = useIssueMessage(messages);
+  /* … */
+}
+```
+
+```tsx
+// ❌ Показ замечания как строки: текста у замечания нет
+<span>{issues[0].message}</span>
+
+// ✅ Текст — через резолвер
+<span>{message(issues[0])}</span>
+```
+
+```typescript
+// ❌ Свой код без записи в словаре — на экране сам код «loanAmount.required»
+validate(model.$.loanAmount, [required({ code: 'loanAmount.required' })]);
+
+// ✅ Каждому своему коду — запись в словаре формы (или validation.<код> в локали приложения)
+defineIssueMessages({ 'loanAmount.required': 'Укажите сумму кредита' });
+```
+
+```typescript
+// ❌ Число с разрядами шаблоном — шаблон печатает 50000 без пробелов
+'loanAmount.min': 'Минимум {min} ₽',
+
+// ✅ Функция форматирует число сама
+'loanAmount.min': (params, i18n) => `Минимум ${i18n.number(Number(params.min))} ₽`,
+```
+
+## See also
+
+- [34-i18n.md](./34-i18n.md) — локаль, загрузка словарей, `I18nProvider`
+- [03-api-signatures.md](./03-api-signatures.md) — фабрики правил и `RuleOptions`
+- [38-form-flow.md](./38-form-flow.md) — `bundle.submission.submit` и проверка шагов
+- [17-nonexistent-api.md](./17-nonexistent-api.md) — удалённые `message`, `messageKey`, `ValidationError`