@reformer/core 10.2.0 → 11.0.0-beta.10

package/docs/llms/34-i18n.md

@@ -0,0 +1,298 @@
+# i18n — локаль, загрузка словарей и провайдер
+
+## Purpose
+
+Подпуть `@reformer/core/i18n` — общий рантайм локализации для всех пакетов `@reformer/*` без React:
+объект локали, загрузка словарей, перевод и форматирование, тексты замечаний валидации. React-часть
+— провайдер `I18nProvider` и хуки `useI18n`, `useMessages`, `useIssueMessage` — отдаёт
+`@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; не BCP 47 — по en
+  messages: Record<string, string>; // плоский словарь: ключ → сообщение ICU
+  weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+  dateLocale?: unknown; // необязательно: объект локали react-day-picker / date-fns
+  dateFormat?: string; // необязательно: токены date-fns для DatePicker
+}
+```
+
+Функций в локали нет, поэтому её можно положить JSON-файлом на сервер и получить по сети:
+
+```json
+{ "code": "ru", "weekStartsOn": 1, "messages": { "profile.title": "Профиль" } }
+```
+
+`extendLocale(base, patch)` возвращает новую локаль: словари сливаются (ключи из `patch` важнее),
+остальные поля заменяются.
+
+## Формат сообщений — подмножество ICU
+
+| Конструкция         | Пример                                                                    |
+| ------------------- | ------------------------------------------------------------------------- |
+| подстановка         | `Открыт файл {name}`                                                      |
+| множественные формы | `{count, plural, one{# файл} few{# файла} many{# файлов} other{# файла}}` |
+| точное значение     | `{count, plural, =0{файлов нет} other{# файлов}}`                         |
+| выбор               | `{gender, select, male{он} female{она} other{оно}}`                       |
+| экранирование       | `'{'` → `{`, `'}'` → `}`, `''` → `'`                                      |
+
+- Ветка `other` обязательна. `#` внутри `plural` — число, отформатированное по языку.
+- Типы `number`, `date`, `time`, `selectordinal` не поддерживаются: числа и даты форматируйте
+  отдельно (`useI18n().number`, `.date`) и передавайте готовой строкой.
+- Категории (`one`/`few`/`many`) берутся из `Intl.PluralRules` языка локали.
+
+## Загрузка локалей
+
+Откуда брать словарь, решает приложение: источник — функция `(code) => локаль | словарь`.
+
+```typescript
+import { createLocaleLoader, fetchMessages } from '@reformer/core/i18n';
+import { loadCoreLocale } from '@reformer/core/locale';
+
+export const loadLocale = createLocaleLoader([
+  loadCoreLocale, // встроенные словари ядра — чанк нужного языка
+  fetchMessages((code) => `/locales/${code}.json`), // ключи приложения и правки — с сервера
+]);
+```
+
+- Источники опрашиваются параллельно, сливаются по порядку: поздний перекрывает ранний.
+- Источник отдаёт локаль целиком (`{ code, messages, … }`) или голый словарь (`{ "a.b": "…" }`);
+  `null` означает «для этого языка у меня ничего нет» и ошибкой не считается.
+- Результат кэшируется по коду языка, идущий запрос не дублируется.
+- Отказ любого источника — отказ загрузки. Источник, которому можно промахнуться, оборачивайте:
+  `(code) => source(code).catch(() => null)`.
+- `loadLocale.peek(code)` — уже загруженная локаль или `undefined`; `loadLocale.preload(code)` — то
+  же, что вызов загрузчика.
+
+Ядро отдаёт свои локали в трёх видах:
+
+| Вид               | Импорт                                      | Для чего                                        |
+| ----------------- | ------------------------------------------- | ----------------------------------------------- |
+| загрузчик         | `loadCoreLocale` из `@reformer/core/locale` | основной путь: чанк языка по запросу            |
+| JSON-файл         | `@reformer/core/locale/ru.json`             | выложить на свой сервер, править без пересборки |
+| синхронный модуль | `ru` из `@reformer/core/locale/ru`          | SSR и тесты                                     |
+
+Встроенные языки ядра — `en` и `ru`. Словарь ядра несёт тексты ошибок валидации
+(`validation.<code>`) и единицы размера файла (`format.fileSize.b|kb|mb|gb|tb`).
+
+Пакеты выше отдают локаль накопительно и в тех же трёх видах, поэтому источник встроенных словарей
+в загрузчике всегда один — самого верхнего из используемых пакетов:
+
+| Пакеты приложения               | Источник                                     | Что в локали                      |
+| ------------------------------- | -------------------------------------------- | --------------------------------- |
+| только ядро                     | `loadCoreLocale` из `@reformer/core/locale`  | ошибки валидации, размер файла    |
+| ядро + `@reformer/cdk`          | `loadCdkLocale` из `@reformer/cdk/locale`    | то же плюс строки cdk (`cdk.*`)   |
+| ядро + cdk + `@reformer/ui-kit` | `loadKitLocale` из `@reformer/ui-kit/locale` | то же плюс подписи кита (`kit.*`) |
+
+## Провайдер
+
+```tsx
+import { I18nProvider } from '@reformer/core/react';
+
+function App() {
+  const [lang, setLang] = useState('ru');
+  return (
+    <I18nProvider lang={lang} load={loadLocale}>
+      <LangSwitch value={lang} onChange={setLang} />
+      <CreditForm />
+    </I18nProvider>
+  );
+}
+```
+
+| Проп            | Назначение                                                               |
+| --------------- | ------------------------------------------------------------------------ |
+| `lang` + `load` | провайдер грузит локаль сам; `load` — стабильная ссылка (константа модуля) |
+| `fallback`      | что показать, пока не загружена самая первая локаль; по умолчанию ничего |
+| `onError`       | отказ загрузки `(error, lang)`                                           |
+| `locale`        | готовый объект вместо `lang` + `load` — SSR, тесты                       |
+
+Поведение при `lang` + `load`:
+
+- при смене `lang` на экране остаётся прежний язык, пока новый не загрузится;
+  `useI18n().pending` — для индикатора;
+- при быстром переключении применяется только последний запрос;
+- ошибка загрузки язык не меняет и попадает в `useI18n().error` и `onError`; повторить запрос
+  того же языка — `useI18n().retry()`;
+- упала самая первая загрузка — дети показываются на встроенном английском (а не `fallback`),
+  ошибка — в `useI18n().error`;
+- новая ссылка `load` — новое хранилище: язык запрашивается у нового загрузчика, на экране тем
+  временем прежняя локаль;
+- если локаль уже в кэше (`await loadLocale.preload(lang)` до монтирования), первый рендер
+  синхронный и `fallback` не показывается.
+
+SSR: эффекты на сервере не выполняются, поэтому там передавайте готовый объект —
+`<I18nProvider locale={ru}>` — либо заранее вызовите `preload`.
+
+Вложенный провайдер заменяет локаль для своего поддерева целиком.
+
+## Хуки
+
+```typescript
+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 }); // с подстановками
+t('cart.empty', undefined, 'Your cart is empty'); // английский текст на случай промаха
+number(1234.5); // '1 234,5' в ru
+date(new Date(), { dateStyle: 'long' }); // '15 января 2024 г.' в ru
+fileSize(1536); // '1,5 КБ' в ru, '1.5 KB' без провайдера
+```
+
+`useMessages(builtinEn)` — для авторов пакетов и китов: ищет ключ в локали провайдера, а при
+промахе берёт встроенную английскую таблицу пакета. Тип ключа выводится из таблицы.
+
+```tsx
+import en from './locale/en.json';
+
+function ClearButton() {
+  const t = useMessages(en);
+  return <button aria-label={t('kit.select.clear')} />;
+}
+```
+
+## Тексты замечаний валидации
+
+Замечание валидации — `ValidationIssue = { code, params?, severity? }`: текста у него нет. Правила из
+`@reformer/core/validators` несут только `code` и `params`, свой код задаёт опция `code`. Строку
+даёт резолвер при отображении:
+
+1. словарь формы (`defineIssueMessages`) — запись по коду замечания;
+2. `validation.<code>` из словаря локали;
+3. `validation.<code>` из встроенной английской таблицы ядра;
+4. сам код — для своих кодов, которых нет ни в одном словаре.
+
+```typescript
+import { defineIssueMessages } from '@reformer/core/i18n';
+
+validate(model.$.email, [
+  required(), // «Обязательное поле» в ru, английская фраза без провайдера
+  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`) резолвит замечание сам; словарь формы подключает
+  `<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 г.`), массив — перечнем,
+  размеры в байтах (`maxFileSize`, `minFileSize`, `actualSize`, `maxTotalFileSize`, `actualTotal`) —
+  строкой с единицей (`5 МБ`). Числа остаются числами, поэтому в сообщении работает `plural`.
+
+```tsx
+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` с `messages` накладывает словарь формы поверх
+локали (вложенные провайдеры накладываются друг на друга); с `resolver` — заменяет резолвер
+целиком, и локаль для замечаний его поддерева не участвует. Подробно — коды, встроенные параметры,
+шаблоны и функции словаря — [36-issue-messages.md](./36-issue-messages.md).
+
+## Что показывается, когда ключа нет
+
+| Ключ                       | Нет в локали                                                    | Сообщение не разбирается                              |
+| -------------------------- | --------------------------------------------------------------- | ----------------------------------------------------- |
+| пакета (`useMessages`)     | встроенный английский пакета                                    | встроенный английский, `console.error` вне production |
+| приложения (`useI18n().t`) | `defaultMessage`, затем сам ключ; `console.warn` вне production | то же, `console.error`                                |
+
+Пропущенная подстановка выводится как `{name}`, значение, которое нельзя привести к строке
+(`Object.create(null)`), — пустой строкой. Код языка не BCP 47 (пришёл из адресной строки) — числа,
+даты и формы слов форматируются по `en`, в dev — предупреждение. Форма не падает ни в одном из
+случаев: неполный словарь, пришедший по сети, — законный сценарий.
+
+## Проверка словаря в тестах
+
+```typescript
+import { validateLocale } from '@reformer/core/i18n';
+
+expect(validateLocale(ruJson, enJson)).toEqual([]);
+// находит: syntax (не разбирается), missing / extra (ключи), arguments (потерянная подстановка);
+// битое сообщение образца — тоже syntax («в образце: …»), проверка остальных ключей продолжается
+```
+
+## Описатели сообщений (низкий уровень)
+
+`msg(key, values?, defaultMessage?)` создаёт описатель сообщения, `defineMessages(appEn)` — `msg` с
+типизированными ключами, `resolveLocalized(value, i18n)` раскрывает описатели в объекте пропсов.
+
+> ⚠️ Рендереры и `FormField` описатели сами пока НЕ раскрывают. Не кладите `msg(...)` в
+> `componentProps` схемы: компонент получит объект вместо строки. До появления раскрытия в
+> рендерерах вызывайте `resolveLocalized` вручную или используйте `useI18n().t`.
+
+## Anti-patterns
+
+```typescript
+// ❌ Импорт из главной бочки — React-части локализации там нет
+import { I18nProvider } from '@reformer/core';
+
+// ✅ Провайдер и хуки — из @reformer/core/react, локаль и перевод — из @reformer/core/i18n
+```
+
+```tsx
+// ❌ Новый загрузчик на каждый рендер: кэш теряется, локаль запрашивается заново на каждый рендер
+<I18nProvider lang={lang} load={createLocaleLoader([loadCoreLocale])}>
+
+// ✅ Загрузчик — константа модуля: один кэш на приложение
+const loadLocale = createLocaleLoader([loadCoreLocale]);
+<I18nProvider lang={lang} load={loadLocale}>
+```
+
+```typescript
+// ❌ Число или дата типами ICU внутри сообщения — не поддерживается, сообщение не разберётся
+const message = 'Итого: {total, number}';
+
+// ✅ Отформатировать отдельно и передать готовой строкой
+t('cart.total', { total: number(total, { style: 'currency', currency: 'RUB' }) });
+```
+
+```tsx
+// ❌ Текст в правиле: у RuleOptions и ValidationIssue нет message — не скомпилируется
+required({ message: 'Укажите телефон' });
+
+// ✅ Свой код в правиле, текст — в словаре формы (константа модуля), на экран — через резолвер
+required({ code: 'phone.required' });
+const phoneMessages = defineIssueMessages({ 'phone.required': 'Укажите телефон' }); // в модуле
+const message = useIssueMessage(phoneMessages); // в компоненте
+<span>{message(issues[0])}</span>;
+```
+
+```typescript
+// ❌ Настройки локали без словаря: объект без поля messages принимается за словарь сообщений
+const source = () => ({ weekStartsOn: 1 });
+
+// ✅ Часть локали узнаётся по полю messages — отдавайте его хотя бы пустым
+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) — когда запускается валидация

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

@@ -0,0 +1,309 @@
+# Единый контракт формы — одна схема, одна сборка, одно поведение
+
+## Purpose
+
+Форма описывается одинаково для всех способов реализации — разметка в JSX, рендерер по TS-схеме,
+рендерер по JSON. Схема одна (дерево узлов), привязка одна (ручка `model.$.…`), сборка одна
+(`createForm`), поведение одно (`defineFormBehavior`). Способы отличаются только видом схемы
+(билдер или документ) и тем, кто рисует результат.
+
+Прежние записи узла — ключи `value` / `array` и запись «имя поля → узел» — удалены: тип узла
+закрыт, сборка их не читает. Удалены и оператор `each`, свободный `cross`, фабрики слоёв
+(`createCoreForm`, `createReactForm`, `createJsonForm`) и отдельное поведение рендера
+(`renderBehavior`): их заменяют `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)`                                     |