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

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

@@ -0,0 +1,307 @@
+# Единый контракт формы — одна схема, одна сборка, одно поведение
+
+## Purpose
+
+Форма описывается одинаково для всех способов реализации — разметка в JSX, рендерер по TS-схеме,
+рендерер по JSON. Схема одна (дерево узлов), привязка одна (ручка `model.$.…`), сборка одна
+(`createForm`), поведение одно (`defineFormBehavior`). Способы отличаются только видом схемы
+(билдер или документ) и тем, кто рисует результат.
+
+Прежние записи узла — ключи `value` / `array` и запись «имя поля → узел» — удалены: тип узла
+закрыт, сборка их не читает. Удалены и оператор `each`, свободный `cross` и имя `createCoreForm`:
+их заменяют `applyEach` со схемой строки, `cross` из аргумента схемы и `createForm`.
+
+| Слой      | поле                              | массив под-форм                           | подформа                              |
+| --------- | --------------------------------- | ----------------------------------------- | ------------------------------------- |
+| схема     | `{ model: model.$.x, component }` | `{ model: model.$.items, item }`          | `{ model: model.$.group, part }`      |
+| валидация | `validate(model.$.x, rules)`      | `applyEach(model.$.items, itemRules)`     | `apply(model.$.group, groupRules)`    |
+| поведение | `compute(model.$.x, …)`           | `applyEach(model.$.items, itemBehavior)`  | `apply(model.$.group, groupBehavior)` |
+
+Правило привязки: `model.$.…` — привязка (схема, правило, оператор). Без `$` — чтение значения
+(`model.loanType === 'mortgage'`), мутация (`model.items.push()`) и под-модель как область.
+
+## Модель — начальные значения и шаблоны элементов
+
+```typescript
+import { arrayOf, createModel } from '@reformer/core';
+
+const blankPhone = (): Phone => ({ number: '' });
+const blankCoBorrower = (): CoBorrower => ({ name: '', phones: arrayOf(blankPhone) });
+
+export const createCreditModel = () =>
+  createModel<CreditForm>({
+    loanType: 'consumer',
+    registrationAddress: { city: '', street: '' },
+    coBorrowers: arrayOf(blankCoBorrower), // пустой массив + шаблон нового элемента
+    tags: [], // массив как одно значение поля — шаблон не нужен
+  });
+```
+
+`arrayOf(blank, items?)` возвращает обычный массив `U[]` и запоминает фабрику нового элемента.
+После этого `push()` и `insertAt(i)` без значения кладут элемент по шаблону — в модели, в ноде
+массива формы и в кнопке «Добавить» секции массива.
+
+- Шаблон переживает `set` / `patch` / `reset` модели.
+- Вложенный массив объявляется внутри шаблона элемента; элементы, пришедшие обычными данными
+  (загрузка с сервера), получают его шаблон из шаблона родителя.
+- У массива без шаблона `push()` без значения бросает ошибку с подсказкой.
+- Шаблон привязан к самому массиву: до `createModel` его нельзя копировать. `structuredClone`,
+  `JSON.parse(JSON.stringify(…))` и `[...array]` отдают массив без шаблона. Начальные значения с
+  `arrayOf` держат в фабрике, а не в константе, которую клонируют.
+
+## Схема — одно дерево
+
+```typescript
+import type { FormModel, FormSchemaNode } from '@reformer/core';
+
+// подформа: объявлена один раз, получает под-модель
+const address = (model: FormModel<Address>): FormSchemaNode => ({
+  component: Box,
+  children: [
+    { model: model.$.city, component: Input, componentProps: { label: 'Город' } },
+    { model: model.$.street, component: Input, componentProps: { label: 'Улица' } },
+  ],
+});
+
+// строка массива — такая же функция от под-модели
+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>): FormSchemaNode => ({
+  component: Box,
+  children: [
+    { model: model.$.loanType, component: SelectAsync, componentProps: { label: 'Тип' } }, // поле
+    { model: model.$.tags, component: SelectMulti }, // массив как одно значение
+    {
+      selector: 'registration',
+      component: Section,
+      componentProps: { title: 'Адрес регистрации' },
+      children: [{ model: model.$.registrationAddress, part: address }], // подформа
+    },
+    { model: model.$.coBorrowers, component: FieldArray, item: coBorrower }, // массив под-форм
+  ],
+});
+```
+
+Чем узел является, решают ручка и соседние ключи:
+
+| Узел            | Как отличить                                  |
+| --------------- | --------------------------------------------- |
+| поле            | `model` — лист или массив; нет `item`, `part` |
+| массив под-форм | `model` — массив, `item` — функция            |
+| подформа        | `model` — группа, `part` — функция            |
+| контейнер       | есть `children`, нет `model`                  |
+
+- Тип узла `FormSchemaNode` закрыт: опечатка в ключе, группа без `part`, `item` не на массиве и
+  привязка value-фасадом (`model: model.email`) не компилируются.
+- Вложенные узлы читаются только из `children` и из поддерева `part`. В `componentProps` и под
+  произвольными ключами сборка не заглядывает; в dev она предупреждает о ключах узла, которые не
+  читает.
+- Вид ноды формы определяет узел модели, а не имя: поле данных может называться `value`, `schema`,
+  `form`, `model` или `children`.
+- Поля подформы принадлежат той же форме: `form.registrationAddress.city`.
+- Билдер `item` / `part` вызывается один раз на под-модель; сборка и рендерер получают одну и ту
+  же компиляцию поддерева: `content` подформы и `row(rowModel)` массива.
+- `initialValue` узла-массива — запасной шаблон нового элемента для форм, чья модель создаётся из
+  данных без кода. Шаблон модели (`arrayOf`) главнее.
+
+## Валидация — подформа и массив подключаются привязкой
+
+```typescript
+import {
+  apply,
+  applyEach,
+  defineValidation,
+  validate,
+  validateWhen,
+} from '@reformer/core/validation';
+
+const addressRules = defineValidation<Address>(({ model, cross }) => {
+  validate(model.$.city, [required()]);
+  // cross — из аргумента схемы: снимок области (Address) выведен, приведения не нужны
+  cross(model.$.street, (address) =>
+    address.city !== '' && address.street === '' ? streetRequired : null
+  );
+});
+
+const coBorrowerRules = defineValidation<CoBorrower>(({ model }) => {
+  validate(model.$.name, [required()]);
+});
+
+export const contactsRules = defineValidation<CreditForm>(({ model }) => {
+  apply(model.$.registrationAddress, addressRules);
+  validateWhen(
+    () => !model.sameAsRegistration,
+    () => apply(model.$.residenceAddress, addressRules)
+  );
+  applyEach(model.$.coBorrowers, coBorrowerRules);
+});
+```
+
+- У схемы, подключённой через `apply(ручка, схема)` / `applyEach`, своя область: `model` — под-модель,
+  `cross` из аргумента схемы получает её снимок. Захватывать снимок в замыкание не нужно.
+- Одна и та же схема подключается и к группе, и к элементам массива.
+- `apply(model.$.a, rules)` принимает и массив ручек: `apply([model.$.a, model.$.b], rules)`.
+- `apply(schemaA, schemaB)` — композиция схем над той же моделью — остаётся.
+- Правило значения — `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`.
+
+## Поведение — модель, форма и схема
+
+```typescript
+import {
+  apply,
+  applyEach,
+  defineFormBehavior,
+  enableWhen,
+  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, flow }) => {
+  const isMortgage = () => model.loanType === 'mortgage';
+
+  enableWhen(model.$.propertyValue, isMortgage, { resetOnDisable: true });
+  hideWhen(schema.node('mortgage'), () => !isMortgage());
+  // визард в рендерере зовёт 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);
+});
+```
+
+Операторы узлов схемы:
+
+| Оператор                                  | Что записывает                                             |
+| ----------------------------------------- | ---------------------------------------------------------- |
+| `hideWhen(node, condition)`               | узел скрыт, пока условие истинно                           |
+| `onComponentEvent(node, event, handler)`  | обработчик пропа-события компонента                        |
+| `onMount(node, fn)` / `onUnmount(node, fn)` | хуки монтирования узла                                   |
+| `onInit(node, fn)`                        | `fn` вызывается сразу, до первого рендера                  |
+| `renderEffect(schema, fn)`                | реактивный эффект, пока схема области смонтирована         |
+| `schema.node(sel).setHidden / patchProps` | принудительная видимость и пропсы узла                     |
+| `schema.node(sel).getRef()`               | ref на компонент узла — объект `{ current }`               |
+
+- Область поведения — `{ model, form, schema, flow }`: `flow` — поток шагов сборки, один на всю
+  сборку (его же получают поведения подформ и строк).
+- **Области изолированы.** `schema.node(selector)` ищет узел только в своей области: корневое
+  поведение — в корневом дереве, поведение подформы и строки массива — в своём поддереве. До узла
+  строки или части корень дотягивается через `applyEach` / `apply`. Два монтирования одной части
+  не конфликтуют.
+- **Исключение — ref по пути модели**: `schema.node('phones.0.number').getRef()` ищется от корня.
+- **Операторы узлов только записывают правило — исполняет его рендерер.** При разметке в JSX они
+  ничего не делают: видимость, отправка и загрузка данных остаются в JSX.
+- Правило на селектор, которого нет в дереве, ничего не делает; в dev — предупреждение.
+- **Несколько поведений на один узел.** Условия `hideWhen` на один селектор объединяются по «или»:
+  узел скрыт, пока истинно любое. Обработчики событий и хуки монтирования — стеком: действует
+  последний, его снятие возвращает прежний. Снятие поведения убирает только его правила.
+- **`setHidden` / `patchProps` поведения откатываются при его снятии** — вместе с записанным в
+  его `onDispose`. Значение, которое с тех пор переписал кто-то другой, остаётся.
+
+## Сборка — `createForm`
+
+```tsx
+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: { extras: crossRules }, // правила вне шагов; голая схема = { rules }
+    flow: { steps: [{ id: 'loan', rules: loanRules }, { id: 'contacts', rules: contactsRules }] },
+  })
+);
+// credit = { model, form, render, flow, validating, submission, validate, validateStep, dispose }
+
+<FormRenderer form={credit} settings={{ fieldWrapper: FormField }} />; // рендерер
+<FormField control={credit.form.loanType} />; // разметка в JSX — та же сборка
+```
+
+- Порядок: модель → `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 })` — форма из модели и готового дерева, без бандла.
+
+Формы без модели нет: значения принадлежат модели. `createForm` без `model` и `initial` либо с
+готовым деревом вместо билдера бросает ошибку с подсказкой.
+
+## Частые ошибки
+
+| ❌ Ошибка                                          | Как правильно                                           |
+| -------------------------------------------------- | ------------------------------------------------------- |
+| `model: model.address` (под-модель у поля)         | `model: model.$.address.city` — привязка всегда с `$`   |
+| `{ model: model.$.address, component }` без `part` | группа полем не бывает — нужен `part`                   |
+| `createForm({ model, schema: дерево })`            | `schema` — билдер `(model) => узел`                     |
+| `hideWhen(schema.node('row-узел'), …)` из корня    | внутри `applyEach(model.$.items, itemBehavior)`         |
+| `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`