@reformer/core 10.2.0 → 11.0.0-beta.10

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`

package/docs/llms/37-compiled-schema.md

@@ -0,0 +1,332 @@
+# Скомпилированная схема — compileSchema, виды узлов и области
+
+## Purpose
+
+Авторская схема (`FormSchemaNode`) описывает вид узла ключами: `model`, `item`, `part`,
+`children`. Разбирать их по-своему раньше приходилось каждому, кто обходил дерево. Теперь дерево
+разбирает один компилятор — `compileSchema(tree, model)` — и все читают его итог,
+`CompiledSchema`: у каждого узла явный вид (`kind`), нормализованная привязка к модели,
+идентификатор и область.
+
+`createForm` компилирует дерево **один раз**: ноды формы и рендерер читают одну и ту же
+компиляцию, она лежит в `bundle.render.tree`. Сам `compileSchema` нужен редко — своему
+рендереру, инструментам (инспектор дерева, проверка селекторов в тестах) и фабрикам, которые
+собирают форму без `createForm`.
+
+## API
+
+```typescript
+import {
+  compileSchema,
+  isCompiledNode,
+  type CompiledSchema,
+  type CompiledNode,
+  type CompiledChild,
+  type SchemaNodeId,
+  type SchemaScopeId,
+} from '@reformer/core';
+
+function compileSchema(
+  tree: FormSchemaNode,
+  model?: object, // модель области: корень сборки, под-модель строки или группы
+  options?: { scope?: SchemaScopeId } // по умолчанию корень '#'
+): CompiledSchema;
+
+function isCompiledNode(value: unknown): value is CompiledNode; // узел компилятора, а не автора
+
+interface CompiledSchema {
+  readonly scope: SchemaScopeId; // '#', '#/address', '#/phones[3]'
+  readonly model: object | undefined; // модель области
+  readonly root: CompiledNode; // корневой узел области
+  readonly nodes: ReadonlyMap<SchemaNodeId, CompiledNode>; // узлы ЭТОЙ области по id
+  readonly fields: ReadonlyMap<object, CompiledFieldNode>; // поля по ручке — области и её подформ
+  readonly arrays: ReadonlyMap<object, CompiledArrayNode>; // массивы под-форм по ручке
+}
+```
+
+### Виды узлов — `kind`
+
+| `kind`      | Узел автора                                              | Что добавляет компилятор                                          |
+| ----------- | -------------------------------------------------------- | ----------------------------------------------------------------- |
+| `field`     | `{ model: model.$.<лист или массив целиком>, component }` | `handle` (ручка значения), `disabled`                            |
+| `array`     | `{ model: model.$.<массив>, item: (row) => узел }`       | `handle`, `control` (фасад массива модели), `initialValue`, `row(rowModel)` |
+| `part`      | `{ model: model.$.<группа>, part: (sub) => узел }`       | `handle`, `model` (под-модель группы), `content` — схема части   |
+| `container` | всё остальное: `children`, `component`                   | `children: CompiledChild[]` — узлы и текст по порядку            |
+| `text`      | подряд идущие строки, числа, сигналы среди `children`    | `parts` — склеенные части; только ребёнок контейнера             |
+
+Общие поля узла (кроме `text`): `id`, `path` (позиционный путь `#/0/2`), `selector`, `scope`,
+`component` (как есть — ядро его не интерпретирует), `props` (`componentProps` автора, без них —
+пустой объект), `source` (авторский узел).
+
+Порядок распознавания важен: ручка массива — тоже ручка значения, поэтому сначала проверяется
+`item` (массив под-форм), затем `part` (подформа), затем привязка-значение (поле), остальное —
+контейнер. Контейнер без `component` рендерер рисует как одних детей.
+
+### Идентификатор узла — `id`
+
+- Узел с `selector` — `id` равен `selector`.
+- Узел без `selector` — позиционный путь от корня области: `#`, `#/0`, `#/0/2`.
+- Текст — позиционный путь первой части.
+- `SchemaNodeId` — строка с брендом: в `compiled.nodes.get(...)` ключ приводят
+  (`'email' as SchemaNodeId`).
+
+### Области — `scope`
+
+| Область          | Идентификатор                | Что в ней                               |
+| ---------------- | ---------------------------- | --------------------------------------- |
+| корень сборки    | `#`                          | дерево `schema(model)`                  |
+| подформа (`part`) | `#/registrationAddress`     | содержимое части; путь группы от модели области |
+| строка массива   | `#/phones[<ключ>]`           | разметка строки из `item(rowModel)`     |
+| вложенные        | `#/coBorrowers[3]/phones[7]` | область внутри области                  |
+
+- В скобках строки — **стабильный ключ** строки, а не индекс: он держится за элемент модели и не
+  меняется при `move` / `swap`. Тот же ключ отдаёт `FormArray.keyAt(index)`.
+- **`selector` уникален в своей области.** Повтор в одной области — исключение при сборке с путями
+  обоих узлов. Селекторы строк массива и подформ живут в своих областях и с корнем не
+  пересекаются: одна часть, подключённая дважды, даёт две области без конфликта.
+- По `selector` узел адресуют поведение (`schema.node(selector)` — в своей области) и шаги потока
+  (`flow.steps[].id` — `selector` узла шага в корневой области).
+
+### Подформы и строки
+
+- **Подформа** компилируется сразу; её содержимое — `content` (своя `CompiledSchema`). Поля и
+  массивы части попадают и в `fields` / `arrays` родителя: у части нет отдельной формы, её поля
+  принадлежат той же сборке (`form.registrationAddress.city`). Подформа на самой модели области
+  (`model: model.# Скомпилированная схема — compileSchema, виды узлов и области
+
+## Purpose
+
+Авторская схема (`FormSchemaNode`) описывает вид узла ключами: `model`, `item`, `part`,
+`children`. Разбирать их по-своему раньше приходилось каждому, кто обходил дерево. Теперь дерево
+разбирает один компилятор — `compileSchema(tree, model)` — и все читают его итог,
+`CompiledSchema`: у каждого узла явный вид (`kind`), нормализованная привязка к модели,
+идентификатор и область.
+
+`createForm` компилирует дерево **один раз**: ноды формы и рендерер читают одну и ту же
+компиляцию, она лежит в `bundle.render.tree`. Сам `compileSchema` нужен редко — своему
+рендереру, инструментам (инспектор дерева, проверка селекторов в тестах) и фабрикам, которые
+собирают форму без `createForm`.
+
+## API
+
+```typescript
+import {
+  compileSchema,
+  isCompiledNode,
+  type CompiledSchema,
+  type CompiledNode,
+  type CompiledChild,
+  type SchemaNodeId,
+  type SchemaScopeId,
+} from '@reformer/core';
+
+function compileSchema(
+  tree: FormSchemaNode,
+  model?: object, // модель области: корень сборки, под-модель строки или группы
+  options?: { scope?: SchemaScopeId } // по умолчанию корень '#'
+): CompiledSchema;
+
+function isCompiledNode(value: unknown): value is CompiledNode; // узел компилятора, а не автора
+
+interface CompiledSchema {
+  readonly scope: SchemaScopeId; // '#', '#/address', '#/phones[3]'
+  readonly model: object | undefined; // модель области
+  readonly root: CompiledNode; // корневой узел области
+  readonly nodes: ReadonlyMap<SchemaNodeId, CompiledNode>; // узлы ЭТОЙ области по id
+  readonly fields: ReadonlyMap<object, CompiledFieldNode>; // поля по ручке — области и её подформ
+  readonly arrays: ReadonlyMap<object, CompiledArrayNode>; // массивы под-форм по ручке
+}
+```
+
+### Виды узлов — `kind`
+
+| `kind`      | Узел автора                                              | Что добавляет компилятор                                          |
+| ----------- | -------------------------------------------------------- | ----------------------------------------------------------------- |
+| `field`     | `{ model: model.$.<лист или массив целиком>, component }` | `handle` (ручка значения), `disabled`                            |
+| `array`     | `{ model: model.$.<массив>, item: (row) => узел }`       | `handle`, `control` (фасад массива модели), `initialValue`, `row(rowModel)` |
+| `part`      | `{ model: model.$.<группа>, part: (sub) => узел }`       | `handle`, `model` (под-модель группы), `content` — схема части   |
+| `container` | всё остальное: `children`, `component`                   | `children: CompiledChild[]` — узлы и текст по порядку            |
+| `text`      | подряд идущие строки, числа, сигналы среди `children`    | `parts` — склеенные части; только ребёнок контейнера             |
+
+Общие поля узла (кроме `text`): `id`, `path` (позиционный путь `#/0/2`), `selector`, `scope`,
+`component` (как есть — ядро его не интерпретирует), `props` (`componentProps` автора, без них —
+пустой объект), `source` (авторский узел).
+
+Порядок распознавания важен: ручка массива — тоже ручка значения, поэтому сначала проверяется
+`item` (массив под-форм), затем `part` (подформа), затем привязка-значение (поле), остальное —
+контейнер. Контейнер без `component` рендерер рисует как одних детей.
+
+### Идентификатор узла — `id`
+
+- Узел с `selector` — `id` равен `selector`.
+- Узел без `selector` — позиционный путь от корня области: `#`, `#/0`, `#/0/2`.
+- Текст — позиционный путь первой части.
+- `SchemaNodeId` — строка с брендом: в `compiled.nodes.get(...)` ключ приводят
+  (`'email' as SchemaNodeId`).
+
+### Области — `scope`
+
+| Область          | Идентификатор                | Что в ней                               |
+| ---------------- | ---------------------------- | --------------------------------------- |
+| корень сборки    | `#`                          | дерево `schema(model)`                  |
+| подформа (`part`) | `#/registrationAddress`     | содержимое части; путь группы от модели области |
+| строка массива   | `#/phones[<ключ>]`           | разметка строки из `item(rowModel)`     |
+| вложенные        | `#/coBorrowers[3]/phones[7]` | область внутри области                  |
+
+- В скобках строки — **стабильный ключ** строки, а не индекс: он держится за элемент модели и не
+  меняется при `move` / `swap`. Тот же ключ отдаёт `FormArray.keyAt(index)`.
+- **`selector` уникален в своей области.** Повтор в одной области — исключение при сборке с путями
+  обоих узлов. Селекторы строк массива и подформ живут в своих областях и с корнем не
+  пересекаются: одна часть, подключённая дважды, даёт две области без конфликта.
+- По `selector` узел адресуют поведение (`schema.node(selector)` — в своей области) и шаги потока
+  (`flow.steps[].id` — `selector` узла шага в корневой области).
+
+### Подформы и строки
+
+) делит с ней область: правило к её узлу из поведения области работает.
+- **Строка массива** компилируется при первом обращении: `arrayNode.row(rowModel)` — одна
+  компиляция на под-модель строки; форма строки и рендерер получают один и тот же объект. Узлы
+  строк в `nodes` корня не лежат.
+
+### Что компилятор проверяет
+
+| Ситуация                                                  | Итог                                                   |
+| --------------------------------------------------------- | ------------------------------------------------------ |
+| повтор `selector` в одной области                         | исключение с путями обоих узлов                        |
+| узел содержит сам себя                                    | исключение — дерево зациклено                          |
+| ключ узла, который сборка не читает (`value`, `array`, …) | dev-предупреждение с подсказкой замены (у строк массива — одно на шаблон) |
+| узел без `component` и без `children`                     | dev-предупреждение: ничего не рисует; пустая секция — `children: []` |
+| одна ручка модели в двух узлах                            | dev-предупреждение; нода берёт `component`, `componentProps` и `disabled` последней привязки |
+| `item` на привязке не-массиве, `part` на не-группе        | dev-предупреждение, узел становится контейнером        |
+| нераспознанная привязка (`model: model.email` без `$`)    | dev-предупреждение, узел становится контейнером        |
+| ребёнок — группа модели или под-модель вместо узла        | dev-предупреждение, ребёнок пропущен                   |
+| `null` / `undefined` / `boolean` среди `children`         | пропускается молча — условная вставка `cond && узел`   |
+
+Вложенные узлы читаются только из `children` и из поддерева `part`; в `componentProps` и под
+произвольными ключами компилятор не заглядывает.
+
+## Examples
+
+### Компиляция и поиск узлов
+
+```typescript
+import { compileSchema, createModel, type SchemaNodeId } from '@reformer/core';
+
+const model = createModel({ email: '', phones: [{ number: '' }] });
+
+const compiled = compileSchema(
+  {
+    children: [
+      { selector: 'email', model: model.$.email, component: Input },
+      { model: model.$.phones, item: (row) => ({ model: row.$.number, component: Input }) },
+    ],
+  },
+  model
+);
+
+compiled.nodes.get('email' as SchemaNodeId)?.kind; // 'field'
+compiled.fields.get(model.$.email)?.component; // Input
+compiled.arrays.get(model.$.phones)?.row(model.phones.at(0)!).scope; // '#/phones[<ключ строки>]'
+compiled.nodes.get('#/1' as SchemaNodeId)?.kind; // 'array' — узел без selector: позиционный id
+```
+
+### Схема сборки — `bundle.render.tree`
+
+```typescript
+const bundle = createForm<CreditForm>({ model: createCreditModel(), schema: creditSchema });
+
+bundle.render.tree; // CompiledSchema корневой области; без schema — undefined
+bundle.render.node('wizard'); // управление узлом корневой области по selector
+```
+
+Своему рендереру и инструментам нужна именно эта компиляция: повторный `compileSchema` того же
+дерева даёт другие объекты и другой кэш строк.
+
+### Обход дерева — список селекторов
+
+```typescript
+import type { CompiledNode, CompiledSchema } from '@reformer/core';
+
+function selectorsOf(schema: CompiledSchema): string[] {
+  const out: string[] = [];
+  const walk = (node: CompiledNode): void => {
+    if (node.selector !== undefined) out.push(`${node.scope} ${node.selector}`);
+    if (node.kind === 'container') {
+      for (const child of node.children) if (child.kind !== 'text') walk(child);
+    }
+    if (node.kind === 'part') walk(node.content.root); // часть — своя область
+    // строки массива — node.row(rowModel) для каждой под-модели строки
+  };
+  walk(schema.root);
+  return out;
+}
+```
+
+### Свой рендерер — разбор по `kind`
+
+```tsx
+function renderNode(node: CompiledChild): ReactNode {
+  switch (node.kind) {
+    case 'text':
+      return node.parts.map((part) => (typeof part === 'object' ? part.value : part)).join('');
+    case 'field':
+      return <Field key={node.id} handle={node.handle} component={node.component} props={node.props} />;
+    case 'array': // у каждой строки своя область: node.row(под-модель строки)
+      return Array.from({ length: node.control.length }, (_, i) =>
+        renderNode(node.row(node.control.at(i) as object).root)
+      );
+    case 'part':
+      return renderNode(node.content.root);
+    case 'container':
+      return node.children.map(renderNode);
+  }
+}
+```
+
+## Anti-patterns
+
+```typescript
+// ❌ Два узла с одним selector в корне — исключение при сборке
+children: [
+  { selector: 'address', model: model.$.registrationAddress, part: address },
+  { selector: 'address', model: model.$.residenceAddress, part: address },
+];
+
+// ✅ Разные селекторы; внутри части селекторы свои — повтор в двух частях не конфликтует
+children: [
+  { selector: 'registration', model: model.$.registrationAddress, part: address },
+  { selector: 'residence', model: model.$.residenceAddress, part: address },
+];
+```
+
+```typescript
+// ❌ Индекс строки в идентификаторе области: после move/swap он указывает на чужую строку
+const scope = `#/phones[${index}]`;
+
+// ✅ Ключ строки — FormArray.keyAt(index); он же стоит в скобках области строки
+const scope = `#/phones[${form.phones.keyAt(index)}]`;
+```
+
+```typescript
+// ❌ Узел строки массива ищется в nodes корня — его там нет
+bundle.render.tree?.nodes.get('co-borrower' as SchemaNodeId); // undefined
+
+// ✅ Узел строки — в схеме строки; в поведении — applyEach + schema.node(...) строки
+const coBorrowers = bundle.render.tree?.arrays.get(model.$.coBorrowers);
+coBorrowers?.row(model.coBorrowers.at(0)!).nodes.get('co-borrower' as SchemaNodeId);
+```
+
+```typescript
+// ❌ Узлы в componentProps — компилятор туда не заглядывает, поле не появится
+{ component: Section, componentProps: { content: { model: model.$.email, component: Input } } }
+
+// ✅ Вложенные узлы — только в children
+{ component: Section, children: [{ model: model.$.email, component: Input }] }
+```
+
+## See also
+
+- [09-formschema.md](./09-formschema.md) — авторский формат узлов
+- [35-unified-contract.md](./35-unified-contract.md) — одна схема, одна сборка, одно поведение
+- [38-form-flow.md](./38-form-flow.md) — шаги потока адресуются `selector` узлов шагов
+- [10-arrays.md](./10-arrays.md) — массивы под-форм и `keyAt`