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

package/docs/llms/33-validation-strategy.md

@@ -4,29 +4,52 @@
 
 Одна декларативная точка выбора «когда прогонять схему валидации» вместо ручной разводки
 `markAsTouched` + `validateModel` + `revalidateWhen` + `useState(pending)`. Аддитивный слой над
-функциональной схемой (`@reformer/core/validation`): переиспользует `validateModel` как
-ЕДИНСТВЕННЫЙ движок (роутинг ошибок в ноды, отмена устаревших прогонов, дедуп по `(model, schema)`),
-второго движка не заводит. Node-level `updateOn` / `debounce` на самой ноде поля (legacy-триггеры)
-этот API НЕ трогает.
+функциональной схемой (`@reformer/core/validation`): переиспользует раннер схемы как
+ЕДИНСТВЕННЫЙ движок (разнос ошибок по нодам, отмена устаревших прогонов, дедуп по `(model, schema)`),
+второго движка не заводит. Других триггеров валидации нет: у ноды поля собственных валидаторов,
+`updateOn` и `debounce` не бывает — когда запускать проверку, решает только стратегия.
 
 Стратегия определяет только момент запуска и раскрытие ошибок — сами правила остаются в отдельной
-`defineValidationSchema<T>(({ model }) => …)`.
+`defineValidation<T>(({ model }) => …)`.
 
 ## API
 
-Основной способ — React-хук `useFormValidation` из `@reformer/core` (рядом с `useFormControl`).
-Под ним — headless-фабрика `createFormValidation` из `@reformer/core/validation` (для SSR / тестов /
-не-React потребителей).
+Три точки входа к одному контроллеру:
+
+- **сборка `createForm`** — `validation: { rules?, extras?, strategy, debounce, liveAfterSubmit }`.
+  Контроллер собирает уровень формы, армирует `useFormBundle` (в эффекте, не при SSR);
+  `bundle.validate()` и `bundle.submission.submit(handler)` — полный прогон с раскрытием замечаний.
+  Это путь по умолчанию для формы со сборкой;
+- **React-хук `useFormValidation`** из `@reformer/core/react` — для формы без сборки
+  (`createFormFromModel` + своя схема);
+- **headless-фабрика `createFormValidation`** из `@reformer/core/validation` — для SSR / тестов /
+  не-React потребителей.
 
 ```typescript
-// React (@reformer/core)
+// Сборка (@reformer/core)
+createForm<T>({
+  …,
+  validation: {
+    rules?: ValidationDefinition<T>;       // полный набор; без него — правила шагов flow + extras
+    extras?: ValidationDefinition<T>;
+    strategy?: ValidationStrategyKind;     // default 'submit'
+    debounce?: number;
+    liveAfterSubmit?: 'change' | 'blur';
+  },
+});
+
+// React (@reformer/core/react)
 function useFormValidation<T>(args: {
   model: FormModel<T>;
-  schema: ValidationSchema<T>;         // СТАБИЛЬНАЯ ссылка (module-level const / useMemo)
+  schema: ValidationDefinition<T>;         // СТАБИЛЬНАЯ ссылка (module-level const / useMemo)
   strategy?: ValidationStrategyKind;   // default 'submit'
   debounce?: number;                   // мс, для live-фаз (change / live-часть afterFirstSubmit)
   liveAfterSubmit?: 'change' | 'blur'; // default 'change'
-}): { submit: () => Promise<boolean>; validate: () => Promise<boolean>; isValidating: boolean };
+}): {
+  submit: () => Promise<boolean>;   // попытка отправки: при отказе раскрыта вся форма, afterFirstSubmit → живая фаза
+  validate: () => Promise<boolean>; // проверка без отправки: раскрыты проверенные поля, фаза не меняется
+  isValidating: boolean;
+};
 
 // headless (@reformer/core/validation)
 type ValidationStrategyKind = 'submit' | 'blur' | 'change' | 'afterFirstSubmit';
@@ -35,51 +58,101 @@ interface ValidationStrategyOptions {
   debounce?: number;
   liveAfterSubmit?: 'change' | 'blur';
 }
+interface FormValidationRunOptions {
+  touch?: true | 'all'; // true (default) — проверенные поля; 'all' — при отказе ещё и вся форма
+  submit?: boolean;     // прогон — попытка отправки: afterFirstSubmit → живая фаза
+}
 interface FormValidationController {
-  validate(): Promise<boolean>;        // полный прогон, touch:true (раскрыть ВСЕ ошибки); переводит afterFirstSubmit в live-фазу
+  validate(): Promise<boolean>;        // нейтральная проверка: touch:true, фазу afterFirstSubmit не трогает; true — только valid
+  run(options?: FormValidationRunOptions): Promise<ValidationResult>; // valid | invalid | error | cancelled
   start(): () => void;                 // армит реактивные подписки (ТОЛЬКО на клиенте) → dispose
-  dispose(): void;
+  dispose(): void;                     // снять подписки и таймеры, отменить идущий прогон (он получит cancelled)
   readonly isValidating: boolean;
   readonly validating: ReadonlySignal<boolean>;
 }
 function createFormValidation<T>(
   model: FormModel<T>,
-  schema: ValidationSchema<T>,
+  schema: ValidationDefinition<T>,
   options?: ValidationStrategyOptions,
 ): FormValidationController;
 ```
 
-- `useFormValidation` мемоизирует контроллер по `[model, schema, strategy, debounce, liveAfterSubmit]`,
-  армит стратегию в `useEffect` (SSR-safe), а `submit()` = `controller.validate()`.
+- `useFormValidation` мемоизирует контроллер по
+  `[model, schema, strategy, debounce, liveAfterSubmit]` и армит стратегию в `useEffect`
+  (SSR-safe). `submit()` = `controller.run({ touch: 'all', submit: true })`, `validate()` =
+  `controller.validate()`; обе — стабильные ссылки, отвечают `true` только при `valid`.
 - `createFormValidation` ЧИСТА до `start()` (никаких подписок) → SSR-safe; `start()` возвращает
   `dispose` и арминует триггеры только на клиенте.
 
+### Живая фаза `afterFirstSubmit` — одно правило
+
+Живую фазу включает **только попытка отправки**:
+
+| Вызов                                                           | Попытка отправки | Касание при отказе |
+| --------------------------------------------------------------- | ---------------- | ------------------ |
+| `bundle.submission.submit(handler)`                             | да               | вся форма          |
+| `submit()` хука `useFormValidation`                             | да               | вся форма          |
+| `controller.run({ touch: 'all', submit: true })`                | да               | вся форма          |
+| `bundle.validate()`, `validate()` хука, `controller.validate()` | нет              | проверенные поля   |
+| `bundle.validateStep(id)`, `flow.next()`                        | нет              | поля шага          |
+
+Кнопка «Проверить» — `validate()`: показывает замечания, но форма остаётся в тихой фазе. Отменённая
+отправка (`cancelled`) форму тронутой не помечает.
+
 ### Стратегии
 
-| strategy | когда прогон | touch | раскрытие ошибок |
-| --- | --- | --- | --- |
-| `submit` (default) | только `validate()` / `submit()` | `true` | всё на submit |
-| `blur` | смена `touched` поля (потеря фокуса) | `false` | только сблюренные (по `touched`) |
-| `change` | на каждый ввод (+ `debounce`) | `false` | только редактированные (по `dirty`) |
-| `afterFirstSubmit` | тихо до 1-го submit, затем live (`liveAfterSubmit: 'change'` \| `'blur'`, default `'change'`) | `true` один раз на 1-м submit, дальше `false` | тихо → раскрыть всё на submit → далее live |
+| strategy           | когда прогон                                                                                                                                | touch                                                        | раскрытие замечаний                          |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | -------------------------------------------- |
+| `submit` (default) | только `validate()` / `submit()` (в сборке — `bundle.validate()` / `bundle.submission.submit()`)                                            | `true`                                                       | всё на submit                                |
+| `blur`             | каждый уход из поля (потеря фокуса), и повторный тоже                                                                                       | `false`                                                      | только сблюренные (по `touched`)             |
+| `change`           | на каждый ввод (+ `debounce`)                                                                                                               | `false`                                                      | только редактированные (по `dirty`)          |
+| `afterFirstSubmit` | тихо до первой попытки отправки, затем live (`liveAfterSubmit: 'change'` \| `'blur'`, default `'change'`); `validate()` фазу не переключает | при отправке — вся форма (при отказе), дальше live — `false` | тихо → раскрыть всё на отправке → далее live |
 
 ## Examples
 
-### Простая форма — afterFirstSubmit + debounce
+### Сборка — стратегия полем `validation`
+
+```tsx
+import { createForm } from '@reformer/core';
+import { useFormBundle } from '@reformer/core/react';
+
+const createRegistration = () =>
+  createForm<RegistrationData>({
+    initial: { username: '', email: '', password: '' },
+    schema: registrationSchema,
+    validation: { rules: registrationValidation, strategy: 'afterFirstSubmit', debounce: 400 },
+  });
+
+function RegistrationForm() {
+  const registration = useFormBundle(createRegistration); // армирует живую стратегию в эффекте
+  const onSubmit = async (event: React.FormEvent) => {
+    event.preventDefault();
+    // первая отправка раскрывает все замечания и переводит форму в живую фазу;
+    // registration.validate() фазу не переключает
+    await registration.submission.submit(api.save);
+  };
+  /* … */
+}
+```
+
+### Без сборки — useFormValidation, afterFirstSubmit + debounce
 
-Тихо до первой отправки, `submit()` раскрывает все ошибки и переводит форму в живую фазу
-(дальше проверка на ввод с задержкой 400 мс). `submit()` сам метит `touched` — ручной
-`markAsTouched` не нужен.
+Тихо до первой отправки, `submit()` раскрывает все замечания и переводит форму в живую фазу
+(дальше проверка на ввод с задержкой 400 мс). `submit()` сам метит `touched` (при отказе — всю
+форму) — ручной `markAsTouched` не нужен. `validate()` — кнопка «Проверить»: раскрывает замечания
+проверенных полей, а форма остаётся в тихой фазе.
 
 ```tsx
-import { createModel, createForm, useFormValidation } from '@reformer/core';
-import { defineValidationSchema, validate } from '@reformer/core/validation';
+import { useMemo } from 'react';
+import { createModel, createFormFromModel } from '@reformer/core';
+import { useFormValidation } from '@reformer/core/react';
+import { defineValidation, validate } from '@reformer/core/validation';
 import { required, email, minLength } from '@reformer/core/validators';
 
 type RegistrationData = { username: string; email: string; password: string };
 
 // Схема — стабильный module-level const (иначе ломается дедуп раннера).
-const registrationValidation = defineValidationSchema<RegistrationData>(({ model }) => {
+const registrationValidation = defineValidation<RegistrationData>(({ model }) => {
   validate(model.$.username, [required(), minLength(3)]);
   validate(model.$.email, [required(), email()]);
   validate(model.$.password, [required(), minLength(8)]);
@@ -87,17 +160,17 @@ const registrationValidation = defineValidationSchema<RegistrationData>(({ model
 
 function RegistrationForm() {
   const model = useMemo(() => createModel<RegistrationData>({ username: '', email: '', password: '' }), []);
-  const form = useMemo(() => createForm({ model }), [model]);
+  const form = useMemo(() => createFormFromModel({ model }), [model]);
 
-  const { submit, isValidating } = useFormValidation({
+  const { submit, validate, isValidating } = useFormValidation({
     model,
     schema: registrationValidation,
     strategy: 'afterFirstSubmit',
     debounce: 400,
   });
 
-  const onSubmit = async (e: React.FormEvent) => {
-    e.preventDefault();
+  const onSubmit = async (event: React.FormEvent) => {
+    event.preventDefault();
     if (await submit()) await api.save(model.get()); // true = нет блокирующих ошибок
   };
 
@@ -106,49 +179,69 @@ function RegistrationForm() {
       <FormField control={form.username} />
       <FormField control={form.email} />
       <FormField control={form.password} />
-      <button type="submit" disabled={isValidating}>Отправить</button>
+      <button type="button" onClick={() => void validate()}>
+        Проверить
+      </button>
+      <button type="submit" disabled={isValidating}>
+        Отправить
+      </button>
     </form>
   );
 }
 ```
 
-### Wizard — live-стратегия внутри активного шага
+### Визард — стратегия формы и проверка шага потоком
 
-`defineSteps(..., { strategy })` задаёт ЖИВУЮ стратегию ВНУТРИ шага; `useWizardStepValidation`
-арминует её под текущий шаг (`currentStep` из `FormWizardContext`) и снимает при смене шага / unmount.
-Per-step gate (`validateStep` на «Далее») и `validateAll` (submit) при этом НЕ меняются — стратегия
-добавляет живой слой ПОВЕРХ них. No-op, если `strategy` не задана / `'submit'` / у шага нет правил.
+Живая стратегия — свойство формы, а не шага: она задаётся полем `validation` сборки и армируется
+`useFormBundle`. Проверку шага делает поток: «Далее» визарда — `flow.next()`, он прогоняет правила
+текущего шага и не пускает дальше при замечаниях. Отправка — `bundle.submission.submit` (все
+шаги + `extras`). Живую фазу `afterFirstSubmit` включает только она: `flow.next()` и
+`validateStep` фазу не переключают.
 
 ```tsx
-import { defineSteps, useWizardStepValidation, FormWizard } from '@reformer/cdk/form-wizard';
-
-const config = defineSteps<'loan' | 'applicant' | 'confirm', CreditForm>(model, {
-  steps: { loan: loanStep, applicant: applicantStep, confirm: null }, // confirm — без правил, ЯВНО
-  extras: crossFieldRules,   // применяются только в validateAll (submit)
-  strategy: 'blur',          // живая валидация полей текущего шага при потере фокуса
-});
+const createCredit = () =>
+  createForm<CreditForm>({
+    model: createCreditModel(),
+    schema: creditSchema,
+    validation: { extras: crossFieldRules, strategy: 'blur' }, // живая проверка при потере фокуса
+    flow: {
+      steps: [
+        { id: 'loan', rules: loanStep },
+        { id: 'applicant', rules: applicantStep },
+        { id: 'confirm' }, // без правил
+      ],
+    },
+  });
 
-function LoanStepBody() {
-  useWizardStepValidation(config); // армит 'blur' под активный шаг, снимает при переходе
-  return <>{/* поля шага */}</>;
+function CreditWizard() {
+  const credit = useFormBundle(createCredit);
+  return (
+    <FormWizard
+      form={credit.form}
+      flow={credit.flow}
+      steps={STEPS}
+      onSubmit={() => void credit.submission.submit(api.save)}
+    />
+  );
 }
-
-<FormWizard form={form} config={config}>
-  <LoanStepBody />
-</FormWizard>;
 ```
 
+Живая фаза прогоняет **полный** набор правил (все шаги + `extras`), а показ замечаний гейтится
+`touched` / `dirty` полей: поля следующих шагов пользователь ещё не трогал — их замечания не видны.
+Прежний per-step механизм (`defineSteps(…, { strategy })` + `useWizardStepValidation`) удалён.
+
 ### Headless / SSR / тесты — createFormValidation
 
 ```typescript
 import { createFormValidation } from '@reformer/core/validation';
 
-const ctrl = createFormValidation(model, registrationValidation, {
+const controller = createFormValidation(model, registrationValidation, {
   strategy: 'afterFirstSubmit',
   debounce: 300,
 });
-const dispose = ctrl.start();        // ТОЛЬКО на клиенте (в React — из useEffect)
-const ok = await ctrl.validate();    // submit → раскрыть все ошибки
+const dispose = controller.start(); // ТОЛЬКО на клиенте (в React — из useEffect)
+const checked = await controller.validate(); // проверка: замечания проверенных полей, фаза тихая
+const sent = await controller.run({ touch: 'all', submit: true }); // попытка отправки → живая фаза
 dispose();
 ```
 
@@ -157,32 +250,50 @@ dispose();
 ```typescript
 // ❌ schema пересоздаётся каждый рендер → контроллер и дедуп раннера ломаются
 function MyForm() {
-  const schema = defineValidationSchema<Form>(({ model }) => { … }); // новая ссылка на каждый рендер
+  const schema = defineValidation<Form>(({ model }) => { … }); // новая ссылка на каждый рендер
   useFormValidation({ model, schema, strategy: 'change' });
 }
 
 // ✅ Стабильная ссылка: module-level const (или useMemo с пустыми deps)
-const formValidation = defineValidationSchema<Form>(({ model }) => { … });
+const formValidation = defineValidation<Form>(({ model }) => { … });
 function MyForm() {
   useFormValidation({ model, schema: formValidation, strategy: 'change' });
 }
 ```
 
 ```typescript
-// ❌ Node-level updateOn (Слой B) И активная schema-стратегия на ОДНОМ поле → оба пишут ошибки в ноду → мерцание
-// узел поля: { updateOn: 'blur', … } + useFormValidation({ strategy: 'blur', schema: включает это же поле })
+// ❌ updateOn / debounce / validators в узле схемы — таких ключей у узла нет, сборка их не читает
+// { model: model.$.email, component: Input, updateOn: 'blur', validators: [required()] }
 
-// ✅ Одно поле обслуживает ОДИН слой: либо node-level updateOn, либо schema-стратегия — не оба сразу
+// ✅ Момент запуска — стратегия формы; правила — схема валидации
+// createForm({ …, validation: { rules: formValidation, strategy: 'blur', debounce: 300 } })
+```
+
+```typescript
+// ❌ Своя стратегия поверх сборки: второй контроллер на ту же модель и правила
+const bundle = useFormBundle(() => createForm({ …, validation: rules }));
+useFormValidation({ model: bundle.model, schema: rules, strategy: 'change' });
+
+// ✅ Стратегия — полем validation сборки; армирует useFormBundle
+const bundle = useFormBundle(() => createForm({ …, validation: { rules, strategy: 'change' } }));
 ```
 
 ```typescript
 // ❌ start() на сервере — арминует реактивные подписки при SSR
-const ctrl = createFormValidation(model, schema, { strategy: 'change' });
-ctrl.start(); // на сервере подписок быть не должно
+const controller = createFormValidation(model, schema, { strategy: 'change' });
+controller.start(); // на сервере подписок быть не должно
 
 // ✅ Фабрика чиста до start(); армить только на клиенте (useFormValidation делает это в useEffect)
-const ctrl = createFormValidation(model, schema, { strategy: 'change' });
-if (typeof window !== 'undefined') ctrl.start();
+const controller = createFormValidation(model, schema, { strategy: 'change' });
+if (typeof window !== 'undefined') controller.start();
+```
+
+```typescript
+// ❌ afterFirstSubmit: ждать живой фазы после проверки — validate() фазу не переключает
+await bundle.validate(); // форма в тихой фазе, ввод не перепроверяется
+
+// ✅ Живую фазу включает попытка отправки
+await bundle.submission.submit(api.save); // без сборки — submit() хука useFormValidation
 ```
 
 ## See also
@@ -190,4 +301,5 @@ if (typeof window !== 'undefined') ctrl.start();
 - [28-submit-and-reset.md](./28-submit-and-reset.md) — submit-флоу и `validateModel` (движок под стратегией)
 - [27-revalidate-when.md](./27-revalidate-when.md) — ручные триггеры перевалидации (низкоуровневый примитив)
 - [31-async-validator-debounce.md](./31-async-validator-debounce.md) — async-правила и отмена устаревших прогонов
-- [13-multi-step.md](./13-multi-step.md) — per-step / полная валидация wizard (`validateStep` / `validateAll`)
+- [13-multi-step.md](./13-multi-step.md) — многошаговая форма: поток `flow`, `bundle.validateStep(id)`
+- [38-form-flow.md](./38-form-flow.md) — уровень формы: `validate`, `submission`, поток шагов

package/docs/llms/34-i18n.md

@@ -2,20 +2,23 @@
 
 ## Purpose
 
-Подпуть `@reformer/core/i18n` — общий рантайм локализации для всех пакетов `@reformer/*`: объект
-локали, загрузка словарей, React-провайдер, перевод и форматирование. Язык задаётся провайдером,
-подгружается динамически и переключается на лету; узлы формы при этом не пересоздаются.
+Подпуть `@reformer/core/i18n` — общий рантайм локализации для всех пакетов `@reformer/*` без React:
+объект локали, загрузка словарей, перевод и форматирование, тексты замечаний валидации. React-часть
+— провайдер `I18nProvider` и хуки `useI18n`, `useMessages`, `useIssueMessage` — отдаёт
+`@reformer/core/react`. Язык задаётся провайдером, подгружается динамически и переключается на лету;
+узлы формы при этом не пересоздаются.
 
 Без провайдера всё работает на английском: у каждого пакета есть встроенная английская таблица.
 
-> Импорт всегда из `@reformer/core/i18n`. Из главной бочки `@reformer/core` этот модуль не
-> реэкспортируется: React-контекст локализации обязан существовать в одном экземпляре.
+> Импорт локали и перевода — из `@reformer/core/i18n`, провайдера и хуков — из
+> `@reformer/core/react`. Из главной бочки `@reformer/core` ни то, ни другое не реэкспортируется:
+> React-контекст локализации обязан существовать в одном экземпляре.
 
 ## Локаль — это данные
 
 ```typescript
 interface FormLocale {
-  code: string; // BCP 47: 'en', 'ru', 'pt-BR' — по нему работают Intl и plural
+  code: string; // BCP 47: 'en', 'ru', 'pt-BR' — по нему работают Intl и plural; не BCP 47 — по en
   messages: Record<string, string>; // плоский словарь: ключ → сообщение ICU
   weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
   dateLocale?: unknown; // необязательно: объект локали react-day-picker / date-fns
@@ -93,7 +96,7 @@ export const loadLocale = createLocaleLoader([
 ## Провайдер
 
 ```tsx
-import { I18nProvider } from '@reformer/core/i18n';
+import { I18nProvider } from '@reformer/core/react';
 
 function App() {
   const [lang, setLang] = useState('ru');
@@ -108,7 +111,7 @@ function App() {
 
 | Проп            | Назначение                                                               |
 | --------------- | ------------------------------------------------------------------------ |
-| `lang` + `load` | провайдер грузит локаль сам                                              |
+| `lang` + `load` | провайдер грузит локаль сам; `load` — стабильная ссылка (константа модуля) |
 | `fallback`      | что показать, пока не загружена самая первая локаль; по умолчанию ничего |
 | `onError`       | отказ загрузки `(error, lang)`                                           |
 | `locale`        | готовый объект вместо `lang` + `load` — SSR, тесты                       |
@@ -118,7 +121,12 @@ function App() {
 - при смене `lang` на экране остаётся прежний язык, пока новый не загрузится;
   `useI18n().pending` — для индикатора;
 - при быстром переключении применяется только последний запрос;
-- ошибка загрузки язык не меняет и попадает в `useI18n().error` и `onError`;
+- ошибка загрузки язык не меняет и попадает в `useI18n().error` и `onError`; повторить запрос
+  того же языка — `useI18n().retry()`;
+- упала самая первая загрузка — дети показываются на встроенном английском (а не `fallback`),
+  ошибка — в `useI18n().error`;
+- новая ссылка `load` — новое хранилище: язык запрашивается у нового загрузчика, на экране тем
+  временем прежняя локаль;
 - если локаль уже в кэше (`await loadLocale.preload(lang)` до монтирования), первый рендер
   синхронный и `fallback` не показывается.
 
@@ -130,7 +138,9 @@ SSR: эффекты на сервере не выполняются, поэто
 ## Хуки
 
 ```typescript
-const { code, locale, pending, error, t, has, number, date, fileSize } = useI18n();
+import { useI18n, useMessages, useIssueMessage } from '@reformer/core/react';
+
+const { code, locale, pending, error, retry, t, has, number, date, fileSize } = useI18n();
 
 t('profile.title'); // ключ приложения
 t('cart.items', { count: 3 }); // с подстановками
@@ -152,31 +162,40 @@ function ClearButton() {
 }
 ```
 
-## Тексты ошибок валидации
+## Тексты замечаний валидации
 
-Правила из `@reformer/core/validators` несут только `code` и `params`; готового текста у них нет
-(`message` по умолчанию — пустая строка). Строку даёт резолвер при отображении ошибки:
+Замечание валидации — `ValidationIssue = { code, params?, severity? }`: текста у него нет. Правила из
+`@reformer/core/validators` несут только `code` и `params`, свой код задаёт опция `code`. Строку
+даёт резолвер при отображении:
 
-1. `messageKey` автора правила — если такой ключ есть в активной локали;
-2. явное `message` автора правила;
-3. `validation.<code>` из словаря локали;
-4. `validation.<code>` из встроенной английской таблицы ядра;
-5. сам код — для своих кодов, которых нет ни в одном словаре.
+1. словарь формы (`defineIssueMessages`) — запись по коду замечания;
+2. `validation.<code>` из словаря локали;
+3. `validation.<code>` из встроенной английской таблицы ядра;
+4. сам код — для своих кодов, которых нет ни в одном словаре.
 
 ```typescript
+import { defineIssueMessages } from '@reformer/core/i18n';
+
 validate(model.$.email, [
   required(), // «Обязательное поле» в ru, английская фраза без провайдера
-  minLength(5, { message: 'Слишком коротко' }), // явный текст: важнее словаря, но языком не переключается
-  email({ messageKey: 'profile.email.invalid' }), // ключ словаря приложения: переключается вместе с языком
+  minLength(5, { code: 'email.minLength' }), // свой код: текст поля — в словаре формы
 ]);
+
+// Словарь формы: шаблон с параметрами либо функция (числа с разрядами — функцией)
+export const formMessages = defineIssueMessages({
+  'email.minLength': 'Не меньше {minLength} символов',
+  'loanAmount.min': (params, i18n) => `Минимум ${i18n.number(Number(params.min))} ₽`,
+});
 ```
 
 - Текст получается при отображении, а не при проверке: смена языка переводит уже показанные
   ошибки без повторной валидации.
-- `FormField` (`@reformer/cdk`, `@reformer/ui-kit`) резолвит ошибку сам. В своём компоненте —
-  `useValidationMessage()`; вне React — `resolveValidationError(error, createI18n(locale))`.
-- Свой код ошибки локализуется ключом `validation.<свой_код>` в словаре приложения либо
-  `messageKey` в самом правиле.
+- `FormField` (`@reformer/cdk`, `@reformer/ui-kit`) резолвит замечание сам; словарь формы подключает
+  `<ValidationMessagesProvider messages={formMessages}>` из `@reformer/cdk`. В своём компоненте —
+  `useIssueMessage(formMessages)` из `@reformer/core/react`; вне React —
+  `resolveIssueMessage(issue, createI18n(locale), formMessages)`.
+- Свой код локализуется записью словаря формы либо ключом `validation.<свой_код>` в словаре
+  приложения — второй вариант переключается вместе с языком.
 - Встроенный текст меняется тем же ключом в словаре приложения:
   `extendLocale(ru, { messages: { 'validation.required': 'Заполните поле' } })`.
 - Параметры готовятся до подстановки: `Date` — по языку (`15 янв. 2030 г.`), массив — перечнем,
@@ -184,15 +203,17 @@ validate(model.$.email, [
   строкой с единицей (`5 МБ`). Числа остаются числами, поэтому в сообщении работает `plural`.
 
 ```tsx
-function FieldErrors({ control }: { control: FieldNode<string> }) {
-  const message = useValidationMessage();
-  const { errors, shouldShowError } = useFormControl(control);
-  return shouldShowError ? <span role="alert">{message(errors[0])}</span> : null;
+function FieldIssues({ control }: { control: FormControl<string> }) {
+  const message = useIssueMessage(formMessages);
+  const { issues, shouldShowIssues } = useFormControl(control);
+  return shouldShowIssues ? <span role="alert">{message(issues[0])}</span> : null;
 }
 ```
 
-Смонтированный `ValidationMessagesProvider` из `@reformer/cdk` заменяет этот резолвер целиком:
-локаль для ошибок в его поддереве не участвует.
+`ValidationMessagesProvider` из `@reformer/cdk` с `messages` накладывает словарь формы поверх
+локали (вложенные провайдеры накладываются друг на друга); с `resolver` — заменяет резолвер
+целиком, и локаль для замечаний его поддерева не участвует. Подробно — коды, встроенные параметры,
+шаблоны и функции словаря — [36-issue-messages.md](./36-issue-messages.md).
 
 ## Что показывается, когда ключа нет
 
@@ -201,8 +222,10 @@ function FieldErrors({ control }: { control: FieldNode<string> }) {
 | пакета (`useMessages`)     | встроенный английский пакета                                    | встроенный английский, `console.error` вне production |
 | приложения (`useI18n().t`) | `defaultMessage`, затем сам ключ; `console.warn` вне production | то же, `console.error`                                |
 
-Пропущенная подстановка выводится как `{name}`. Форма не падает ни в одном из случаев: неполный
-словарь, пришедший по сети, — законный сценарий.
+Пропущенная подстановка выводится как `{name}`, значение, которое нельзя привести к строке
+(`Object.create(null)`), — пустой строкой. Код языка не BCP 47 (пришёл из адресной строки) — числа,
+даты и формы слов форматируются по `en`, в dev — предупреждение. Форма не падает ни в одном из
+случаев: неполный словарь, пришедший по сети, — законный сценарий.
 
 ## Проверка словаря в тестах
 
@@ -210,7 +233,8 @@ function FieldErrors({ control }: { control: FieldNode<string> }) {
 import { validateLocale } from '@reformer/core/i18n';
 
 expect(validateLocale(ruJson, enJson)).toEqual([]);
-// находит: syntax (не разбирается), missing / extra (ключи), arguments (потерянная подстановка)
+// находит: syntax (не разбирается), missing / extra (ключи), arguments (потерянная подстановка);
+// битое сообщение образца — тоже syntax («в образце: …»), проверка остальных ключей продолжается
 ```
 
 ## Описатели сообщений (низкий уровень)
@@ -225,15 +249,14 @@ expect(validateLocale(ruJson, enJson)).toEqual([]);
 ## Anti-patterns
 
 ```typescript
-// ❌ Импорт из главной бочки — i18n там нет, а второй путь импорта дал бы вторую копию контекста
+// ❌ Импорт из главной бочки — React-части локализации там нет
 import { I18nProvider } from '@reformer/core';
 
-// ✅ Единственный путь импорта — подпуть i18n
-import { I18nProvider } from '@reformer/core/i18n';
+// ✅ Провайдер и хуки — из @reformer/core/react, локаль и перевод — из @reformer/core/i18n
 ```
 
 ```tsx
-// ❌ Новый загрузчик на каждый рендер: кэш теряется, локаль грузится заново, первый кадр — fallback
+// ❌ Новый загрузчик на каждый рендер: кэш теряется, локаль запрашивается заново на каждый рендер
 <I18nProvider lang={lang} load={createLocaleLoader([loadCoreLocale])}>
 
 // ✅ Загрузчик — константа модуля: один кэш на приложение
@@ -250,12 +273,14 @@ t('cart.total', { total: number(total, { style: 'currency', currency: 'RUB' }) }
 ```
 
 ```tsx
-// ❌ Ошибка выводится полем message: у правил без своего текста оно пустое — на экране ничего
-<span>{errors[0].message}</span>;
-
-// ✅ Текст ошибки — через резолвер: он знает словарь локали, messageKey и явное сообщение
-const message = useValidationMessage();
-<span>{message(errors[0])}</span>;
+// ❌ Текст в правиле: у RuleOptions и ValidationIssue нет message — не скомпилируется
+required({ message: 'Укажите телефон' });
+
+// ✅ Свой код в правиле, текст — в словаре формы (константа модуля), на экран — через резолвер
+required({ code: 'phone.required' });
+const phoneMessages = defineIssueMessages({ 'phone.required': 'Укажите телефон' }); // в модуле
+const message = useIssueMessage(phoneMessages); // в компоненте
+<span>{message(issues[0])}</span>;
 ```
 
 ```typescript
@@ -268,5 +293,6 @@ const source = () => ({ weekStartsOn: 1, messages: {} });
 
 ## See also
 
+- [36-issue-messages.md](./36-issue-messages.md) — тексты замечаний: коды, словарь формы, резолвер
 - [28-submit-and-reset.md](./28-submit-and-reset.md) — жизненный цикл формы; смена языка его не затрагивает
 - [33-validation-strategy.md](./33-validation-strategy.md) — когда запускается валидация