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

package/docs/llms/08-form-types.md

@@ -1,11 +1,12 @@
 ## 7. FORM TYPE DEFINITION
 
-Form-shape объявляй через `type`-alias (не `interface` — см. `30-type-safety-recipes.md`).
-Тип описывает форму ДАННЫХ (то, что кладётся в `createModel`), без узлов/сигналов.
+Форму данных объявляй через `interface` или `type`-alias — оба варианта работают одинаково (см.
+`30-type-safety-recipes.md`). Тип описывает форму ДАННЫХ (то, что кладётся в `createModel`), без
+узлов/сигналов.
 
 ```typescript
 // CORRECT form type definition
-type MyForm = {
+interface MyForm {
   // Required fields
   name: string;
   email: string;
@@ -28,7 +29,7 @@ type MyForm = {
     id: string;
     name: string;
   }>;
-};
+}
 
 // Модель создаётся из initial-значений этого типа
 const model = createModel<MyForm>({
@@ -45,3 +46,9 @@ const model = createModel<MyForm>({
 `number | null` / `string | null` работают со встроенными валидаторами напрямую —
 `min`/`max`/`minLength`/`minDate`/`minAge` пропускают пустые значения внутри, guard `if (v != null)`
 не нужен.
+
+Какой ноде формы соответствует поле, решает вид значения: объект — `FormGroup`
+(`form.address.city`), массив объектов — `FormArray` (`form.items.at(0)`), примитив, массив
+примитивов, `Date`, `File` — `FormControl`. Вычисляемые поля (цели `compute`) удобно держать
+отдельным типом и объявлять форму пересечением: `type MyFormFull = MyForm & MyFormDerived` — тогда
+на сервер уходит только ввод (`MyForm`), а вычисляемые ключи отрезаются перед отправкой.

package/docs/llms/09-formschema.md

@@ -1,143 +1,191 @@
 ## 8. SCHEMA FORMAT (CRITICALLY IMPORTANT)
 
-Под M1 схема **привязывает поле к сигналу модели** (`value: model.$.field`) и держит
-UI-конфиг (`component`/`componentProps`). Значения принадлежат модели. Валидаторов в
-layout-схеме НЕТ — правила живут в отдельной схеме `defineValidationSchema` из
-`@reformer/core/validation` и запускаются раннером `validateModel(model, schema)`.
+Схема — **дерево узлов**. Узел привязан к части модели ключом `model` и держит UI-конфиг
+(`component` / `componentProps`). Значения принадлежат модели. Правил валидации в схеме НЕТ — они
+живут в отдельной схеме `defineValidation` из `@reformer/core/validation`.
 
-### Field node
+### Четыре вида узла
+
+Тип узла — `FormSchemaNode`, закрытый union. Вид определяют ключи `model`, `item`, `part` и
+`children`:
+
+| Вид             | Ключи                             | Пример                                              |
+| --------------- | --------------------------------- | --------------------------------------------------- |
+| поле            | `model` — лист или массив целиком | `{ model: model.$.email, component: Input }`        |
+| массив под-форм | `model` — массив + `item`         | `{ model: model.$.phones, item: phoneRow }`         |
+| подформа        | `model` — группа + `part`         | `{ model: model.$.address, part: address }`         |
+| контейнер       | `children`                        | `{ component: Section, children: [/* узлы */] }`    |
+
+Общие ключи любого узла: `component`, `componentProps`, `selector`. У поля ещё `disabled`, у
+массива под-форм — `initialValue` (запасной шаблон новой строки).
 
 ```typescript
+// Поле
 {
-  value: model.$.fieldName,   // сигнал модели (PathAwareSignal) — обязателен
+  model: model.$.fieldName,   // ручка значения из model.$ — обязательна
   component: Input,           // React-компонент
   componentProps?: object,    // пропсы (label, placeholder, options, type, ...)
-  disabled?: boolean,
-  updateOn?: 'change' | 'blur' | 'submit',
-  debounce?: number,
+  disabled?: boolean,         // постоянная блокировка поля (вычисляемые total, fullName)
+  selector?: string,          // имя узла для поведения: schema.node('…')
 }
 ```
 
-> `disabled` — **top-level поле узла** (начальное состояние); дальше управляется методами
-> `form.field.disable()`/`enable()` и оператором `enableWhen`. `componentProps.disabled` — это
-> UI-проп и на состояние узла **не влияет** (частая причина «computed-поле остаётся редактируемым»).
+> **Вложенные узлы читаются только из `children` и из поддерева `part`.** В `componentProps` и под
+> произвольными ключами сборка не заглядывает: узел, положенный туда, полем не станет. В dev
+> сборка предупреждает о ключах узла, которые она не читает.
+
+> **Тип закрыт — ошибки ловит компилятор:** опечатка в ключе (`componnet`), группа без `part`,
+> `item` не на массиве, привязка value-фасадом (`model: model.email` вместо `model.$.email`) и
+> узлы под произвольными ключами (`{ email: { model, component } }`) не компилируются.
+
+> `disabled` — **ключ узла**, постоянная блокировка: `enable()` группы, массива или формы её не
+> снимает (цикл «выключить форму на время отправки → включить» вычисляемые поля не разблокирует).
+> Снимают её явный `form.field.enable()` и оператор `enableWhen` на этом поле. `componentProps.disabled` — это
+> UI-проп и на состояние поля **не влияет** (частая причина «computed-поле остаётся редактируемым»).
 
 ### Primitive Fields
 
 ```typescript
-import { createModel, createForm } from '@reformer/core';
-import { defineValidationSchema, validate } from '@reformer/core/validation';
+import { createModel, createFormFromModel, type FormSchemaNode } from '@reformer/core';
+import { defineValidation, validate } from '@reformer/core/validation';
 import { required } from '@reformer/core/validators';
 import { Input, InputNumber, SelectAsync, CheckboxWithLabel } from '@reformer/ui-kit';
 
 const model = createModel<MyForm>({ name: '', age: null, agree: false, status: 'active' });
 
 // Валидация — отдельным слоем (запуск: await validateModel(model, myValidation))
-const myValidation = defineValidationSchema<MyForm>(({ model }) => {
+const myValidation = defineValidation<MyForm>(({ model }) => {
   validate(model.$.name, [required()]);
 });
 
-const schema = {
-  name: {
-    value: model.$.name,
-    component: Input,
-    componentProps: { label: 'Name', placeholder: 'Enter name' },
-  },
-  age: {
-    value: model.$.age,
-    component: InputNumber,
-    componentProps: { label: 'Age' },
-  },
-  agree: {
-    value: model.$.agree,
-    component: CheckboxWithLabel,
-    componentProps: { label: 'I agree to terms' },
-  },
-  status: {
-    value: model.$.status,
-    component: SelectAsync,
-    componentProps: {
-      label: 'Status',
-      options: [
-        { value: 'active', label: 'Active' },
-        { value: 'inactive', label: 'Inactive' },
-      ],
+const schema: FormSchemaNode = {
+  children: [
+    {
+      model: model.$.name,
+      component: Input,
+      componentProps: { label: 'Name', placeholder: 'Enter name' },
+    },
+    {
+      model: model.$.age,
+      component: InputNumber,
+      componentProps: { label: 'Age' },
+    },
+    {
+      model: model.$.agree,
+      component: CheckboxWithLabel,
+      componentProps: { label: 'I agree to terms' },
     },
-  },
+    {
+      model: model.$.status,
+      component: SelectAsync,
+      componentProps: {
+        label: 'Status',
+        options: [
+          { value: 'active', label: 'Active' },
+          { value: 'inactive', label: 'Inactive' },
+        ],
+      },
+    },
+  ],
 };
 
-const form = createForm<MyForm>({ model, schema });
+const form = createFormFromModel<MyForm>({ model, schema });
 ```
 
-### Nested Objects
+Поле данных может называться как угодно — `value`, `schema`, `form`, `model`, `children`: вид ноды
+определяет узел модели, а не имя.
 
-Вложенная группа модели — это сама по себе под-модель `FormModel<Sub>` (доступна как `model.<group>`,
-с `.$`/API). Удобно вынести в builder, принимающий `FormModel<Sub>` — симметрично builder'у элемента
-массива. Сигналы под-модели идентичны корневым: `model.address.$.city === model.$.address.city`.
+### Nested Objects — подформа `{ model, part }`
 
-```typescript
-import type { FormModel } from '@reformer/core';
+Вложенная группа модели — под-модель `FormModel<Sub>`. Её разметку объявляют один раз функцией от
+под-модели и подключают к группе узлом-подформой. Привязки внутри части идут через `$` полученной
+под-модели:
 
-const addressNodes = (m: FormModel<Address>) => ({
-  street: { value: m.$.street, component: Input, componentProps: { label: 'Street' } },
-  city:   { value: m.$.city,   component: Input, componentProps: { label: 'City' } },
-  zip:    { value: m.$.zip,    component: Input, componentProps: { label: 'ZIP' } },
+```typescript
+import type { FormModel, FormSchemaNode } from '@reformer/core';
+
+const address = (model: FormModel<Address>): FormSchemaNode => ({
+  children: [
+    { model: model.$.street, component: Input, componentProps: { label: 'Street' } },
+    { model: model.$.city, component: Input, componentProps: { label: 'City' } },
+    { model: model.$.zip, component: Input, componentProps: { label: 'ZIP' } },
+  ],
 });
 
-const schema = {
-  address: addressNodes(model.address),
+const schema: FormSchemaNode = {
+  children: [
+    // Одна часть подключается к любой группе той же формы данных — сколько угодно раз.
+    { model: model.$.registrationAddress, part: address },
+    { model: model.$.residenceAddress, part: address },
+  ],
 };
 ```
 
-### Arrays — `{ array, item }` node
+Поля группы можно привязать и напрямую, без подформы:
+`{ model: model.$.address.city, component: Input }`.
 
-Массив объектов объявляется узлом `{ array: model.<path>, item: (itemModel) => subSchema }`.
-`item` строит под-схему из под-модели элемента (`FormModel<Item>`):
+### Arrays — массив под-форм `{ model, item }`
+
+`item` строит разметку строки из под-модели строки (`FormModel<Item>`):
 
 ```typescript
-import type { FormModel } from '@reformer/core';
+import type { FormModel, FormSchemaNode } from '@reformer/core';
 
-const itemSchema = (item: FormModel<Item>) => ({
-  id:   { value: item.$.id,   component: Input, componentProps: { label: 'ID' } },
-  name: { value: item.$.name, component: Input, componentProps: { label: 'Name' } },
+const itemRow = (item: FormModel<Item>): FormSchemaNode => ({
+  children: [
+    { model: item.$.id, component: Input, componentProps: { label: 'ID' } },
+    { model: item.$.name, component: Input, componentProps: { label: 'Name' } },
+  ],
 });
 
-const schema = {
-  items: { array: model.items, item: itemSchema },
+const schema: FormSchemaNode = {
+  children: [{ model: model.$.items, component: FieldArray, item: itemRow }],
 };
 ```
 
+Массив **без** `item` и с `component` — одно значение поля (мультивыбор, теги, список файлов):
+`{ model: model.$.tags, component: SelectMulti }`.
+
 ### createForm API
 
 ```typescript
-// M1: данные из модели + схема (+ опциональный декларативный behavior)
-const form = createForm<MyForm>({
-  model,                 // FormModel<MyForm> — обязателен
-  schema,                // дерево узлов, привязанных к сигналам
-  behavior: myBehavior,  // опционально: defineFormBehavior(...) из @reformer/core/behaviors
+// Сборка одним вызовом: модель, форма, уровень формы и дерево для рендера
+const bundle = createForm<MyForm>({
+  initial,                 // либо готовая модель: model
+  schema: (model) => tree, // билдер дерева: узлы держат ручки модели
+  behavior: myBehavior,    // опционально: defineFormBehavior(...) из @reformer/core/behaviors
+  validation: myRules,     // опционально: схема либо { rules?, extras?, strategy? }
+  flow: { steps: [{ id: 'loan', rules: loanRules }] }, // опционально: шаги, id = selector шага
 });
+bundle.render.tree; // CompiledSchema — то же дерево после компиляции
+
+// Низкоуровневая фабрика: готовые модель и дерево
+const form = createFormFromModel<MyForm>({ model, schema, behavior: myBehavior });
 
-// Доступ к нодам через Proxy
+// Доступ к нодам
 form.name.setValue('John');
-form.address.city.value.value;  // текущее значение (через сигнал)
-model.items.push({ id: '1', name: 'Item' }); // операции над массивом — на модели
+form.address.city.value.value; // текущее значение (через сигнал)
+model.items.push({ id: '1', name: 'Item' }); // операции над массивом — на модели (или form.items.push)
 ```
 
-> **Тип `schema` в M1 — `unknown`, не `FormSchema<T>`.** Это осознанно: интерпретатор обходит
-> произвольную структуру и собирает листья `{ value: signal, component?, ... }`, поэтому обёртки
-> (`{ children: [...] }`, wizard/steps) компилируются. Строгий `FormSchema<T>` (keyed-map по полям
-> `T`) применяется только на legacy-пути `createForm(schema)` без модели.
+Сборка компилирует дерево один раз (`compileSchema`): у каждого узла — вид (`field | array | part |
+container | text`), идентификатор (`selector` либо позиционный путь `#/0/2`) и область (`#`,
+`#/address`, `#/phones[<ключ>]`). Повтор `selector` в одной области (корень, строка массива,
+подформа) — исключение с путями обоих узлов. В dev правило поведения на узел, которого нет в
+дереве, и шаг `flow.steps`, для которого нет узла с таким `selector`, дают предупреждение в
+консоли. Подробно — [37-compiled-schema.md](./37-compiled-schema.md).
 
-### createForm Returns a Proxy
+### Ноды формы — типы и гарды
 
 ```typescript
-const form = createForm<MyForm>({ model, schema });
+const form = createFormFromModel<MyForm>({ model, schema });
 
-form.email;          // FieldNode<string> — TypeScript знает тип
-form.address.city;   // FieldNode<string> — вложенный доступ
-form.items.at(0);    // FormProxy<ItemType> — элемент массива
+form.email;          // FormControl<string> — TypeScript знает тип
+form.address.city;   // FormControl<string> — вложенный доступ (form.address — FormGroup)
+form.items.at(0);    // FormGroup<ItemType> | undefined — форма строки массива
+form.$.value;        // поле с именем члена ноды (value, issues, reset, …) — через `$`
 
-// IMPORTANT: Proxy не проходит instanceof! Используй type guards:
-import { isFieldNode, isGroupNode, isArrayNode } from '@reformer/core';
-if (isFieldNode(node)) { /* ... */ }
+// FormControl / FormGroup / FormArray — интерфейсы, instanceof не работает. Вид ноды — гардами:
+import { isFormControl, isFormGroup, isFormArray } from '@reformer/core';
+if (isFormControl(node)) { /* ... */ }
 ```

package/docs/llms/10-arrays.md

@@ -2,105 +2,143 @@
 
 Массивы объектов — **model-owned**: данные принадлежат модели (`model.arrayField` — это
 `ModelArray<Item>` с реактивными `push`/`removeAt`/`length`). В схеме массив объявляется узлом
-`{ array: model.<path>, item: (itemModel) => subSchema }`, где `item` строит под-схему одного
-элемента из его под-модели (`FormModel<Item>`).
+`{ model: model.$.<path>, item: (itemModel) => узел }`, где `item` строит разметку одной строки
+из её под-модели (`FormModel<Item>`).
 
 ```typescript
-import { createModel, createForm, type FormModel } from '@reformer/core';
-import { Input, InputNumber } from '@reformer/ui-kit';
+import {
+  arrayOf,
+  createModel,
+  createFormFromModel,
+  type FormModel,
+  type FormSchemaNode,
+} from '@reformer/core';
+import { FieldArray, Input, InputNumber } from '@reformer/ui-kit';
 
 type Item = { id: string; name: string; price: number };
 type MyForm = { items: Item[] };
 
-const model = createModel<MyForm>({ items: [] });
-
-// под-схема одного элемента (item.$.field — сигнал под-модели)
-const itemSchema = (item: FormModel<Item>) => ({
-  id:    { value: item.$.id,    component: Input },
-  name:  { value: item.$.name,  component: Input },
-  price: { value: item.$.price, component: InputNumber },
+// arrayOf(blank) — пустой список и шаблон строки для кнопки «Добавить»
+const blankItem = (): Item => ({ id: '', name: '', price: 0 });
+const model = createModel<MyForm>({ items: arrayOf(blankItem) });
+
+// разметка одной строки (item.$.field — ручка под-модели строки)
+const itemRow = (item: FormModel<Item>): FormSchemaNode => ({
+  children: [
+    { model: item.$.id, component: Input },
+    { model: item.$.name, component: Input },
+    { model: item.$.price, component: InputNumber },
+  ],
 });
 
-const schema = {
-  items: { array: model.items, item: itemSchema },
+const schema: FormSchemaNode = {
+  children: [{ model: model.$.items, component: FieldArray, item: itemRow }],
 };
 
-const form = createForm<MyForm>({ model, schema });
+const form = createFormFromModel<MyForm>({ model, schema });
+form.items; // FormArray<Item> — форма каждой строки: form.items.at(i)
 ```
 
-> **Type constraint:** тип элемента `Item` объявляй через `type`-alias (не `interface`) — иначе
-> он не совместим с `Record<string, FormValue>` и `ArrayNode<Item>` его отвергнет.
-> См. `30-type-safety-recipes.md`.
+> Привязка массива — **ручка** `model.$.items`, как у поля и подформы. `item` на привязке, которая
+> массивом не является (лист, группа), — ошибка компиляции.
 
 ### Массив как ОДНО значение поля
 
 Массив бывает не набором под-форм, а одним значением: мультивыбор, теги, список файлов. Чем он
-является, решает **схема**, а не данные: `{ array, item }` — набор под-форм, а узел поля
-`{ value: model.$.<путь>, component }` — одно значение. Массив, к которому в схеме ничего не
-привязано, в форму не попадает.
+является, решает **схема**, а не данные: `{ model, item }` — набор под-форм, а узел поля
+`{ model: model.$.<путь>, component }` без `item` — одно значение. Массив, к которому в схеме
+ничего не привязано, в форму не попадает.
 
 ```typescript
 type MyForm = { tags: string[] };
 
 const model = createModel<MyForm>({ tags: [] });
 
-const schema = {
-  tags: { value: model.$.tags, component: SelectMulti }, // поле над массивом целиком
+const schema: FormSchemaNode = {
+  children: [{ model: model.$.tags, component: SelectMulti }], // поле над массивом целиком
 };
-const form = createForm<MyForm>({ model, schema });
+const form = createFormFromModel<MyForm>({ model, schema });
 
-form.tags.setValue(['a', 'b']); // FieldNode<string[]>
+form.tags.setValue(['a', 'b']); // FormControl<string[]>
 model.$.tags.value = ['c']; // ручка значения: заменяет массив целиком
 validate(model.$.tags, [required(), maxLength(3)]); // правило получает массив
 ```
 
-- `model.$.<массив>` — записываемая ручка значения (`PathAwareSignal`): подходит для `value:` в
+- `model.$.<массив>` — записываемая ручка значения (`PathAwareSignal`): подходит для `model:` в
   схеме, `validate`/`cross`, `enableWhen`/`copyFrom` и для `model.signalAt(path)`.
 - Узел-массив хранит только массив: запись `null`/`undefined` даёт `[]`. Нужно отличать «не
   выбирали» от «выбрали ничего» — объявляй поле `T[] | null` с начальным `null`: в рантайме это
   лист, и привязывается он так же.
+- **Контейнер с `null` в типе — значение как есть.** `model.tags` у поля `string[] | null` — это
+  `string[] | null`, а не фасад `ModelArray`; `model.$.tags` — лист `PathAwareSignal` без `length`
+  и индексов; группа `Address | null` — `Address | null` без под-модели. Такое поле начинают с
+  `null`: контейнер, созданный из `[]` или `{}`, в рантайме стал бы фасадом, а тип его не видит.
 - Запись в узел-ГРУППУ (`model.$.<группа>.value = …`) — ошибка: группа пишется по полям или через
   `model.patch(...)`.
 
+### Массив в группе и в строке другого массива
+
+Узел `{ model, item }` стоит на любой глубине: массив в группе получает ноду `form.<группа>.<массив>`,
+массив в строке — `form.<массив>.at(i).<массив>`. Разметка строки объявляет свои массивы так же.
+
+```typescript
+const contactRow = (contact: FormModel<Contact>): FormSchemaNode => ({
+  children: [
+    { model: contact.$.name, component: Input },
+    { model: contact.$.phones, item: phoneRow }, // массив в строке массива
+  ],
+});
+
+const schema: FormSchemaNode = {
+  children: [
+    { model: model.$.details.hotlines, item: phoneRow }, // массив в группе
+    { model: model.$.contacts, item: contactRow },
+  ],
+};
+```
+
+Поведение строк вложенного массива — `applyEach` внутри схемы строки, см. `21-array-operations.md`.
+
 ### Один массив — три слоя (три разных движка)
 
 Одна и та же коллекция описывается **тремя разными формами** — по одной на движок. Их легко
 перепутать, но каждая корректна только в своём контексте:
 
-1. **Layout-схема `createForm`** — единственная форма, которую ест `createForm`:
-   `{ array: model.<path>, item: (itemModel) => subSchema }`. Массив связывается через
-   **value-proxy** `model.properties` (он несёт `__path`), а **не** через сигнальный
-   `model.$.properties`.
+1. **Схема формы** — узел `{ model: model.$.<path>, item: (itemModel) => узел }` среди `children`
+   дерева:
 
    ```typescript
-   // узел схемы для createForm({ model, schema })
-   properties: { array: model.properties, item: propertyItem },
+   // узел схемы для createForm / createFormFromModel
+   { model: model.$.properties, component: FieldArray, item: propertyRow },
    ```
 
-2. **Validation-схема (`@reformer/core/validation`)** — per-item правила пишутся оператором
-   `each(arr, (im) => {...})` внутри `defineValidationSchema`; `im` — под-модель элемента
-   (`im.$.field` — его сигналы). Запуск — внешним `validateModel(model, schema)`.
+2. **Схема валидации (`@reformer/core/validation`)** — правила строки объявляются отдельной схемой
+   над типом строки и подключаются оператором `applyEach(model.$.<массив>, схема)`. У схемы строки
+   своя область: её `cross` получает снимок строки. Запуск — `validateModel(model, schema)`.
 
    ```typescript
-   // внутри defineValidationSchema<MyForm>(({ model }) => { ... })
-   each(model.properties, (im) => {
-     validate(im.$.description, [required()]);
-     validate(im.$.estimatedValue, [required(), min(1)]);
+   const propertyRules = defineValidation<Property>(({ model }) => {
+     validate(model.$.description, [required()]);
+     validate(model.$.estimatedValue, [required(), min(1)]);
    });
+
+   // внутри defineValidation<MyForm>(({ model }) => { ... })
+   applyEach(model.$.properties, propertyRules);
    ```
 
-3. **CDK / render** — работают с уже **материализованной** нодой `form.<array>` (`ModelArrayNode`),
-   а не со схемой: `<FormArray.Root control={form.properties}>` (CDK) или `FormArraySection` из
+3. **CDK / render** — работают с уже **материализованной** нодой `form.<array>` (`FormArray`),
+   а не со схемой: `<FieldArray.Root control={form.properties}>` (CDK) или `FieldArraySection` из
    `@reformer/ui-kit` (`control={form.properties}`, `itemComponent`).
 
-> **Не путай форму по движку.** `createForm` принимает **только** `{ array, item }`;
-> per-item валидация — это `each(model.<array>, (im) => ...)` в validation-схеме; `FormArray.Root
-> control={form.x}` (или `FormArraySection`) — рендер. `each` в layout-схеме `createForm`
-> не подхватится, а `{ array, item }` в validation-схеме не обходится.
+> **Не путай запись по движку.** Схема формы — узел `{ model, item }`; правила строк —
+> `applyEach(model.$.<массив>, схема)` в схеме валидации; `FieldArray.Root control={form.x}` (или
+> `FieldArraySection`) — рендер. `applyEach` в схеме формы не подхватится, а узел `{ model, item }`
+> схема валидации не обходит.
 
-### Array operations — на модели
+### Array operations — на модели или на ноде
 
-Мутации массива делаются через `ModelArray` (`model.items`), а не через ноду формы:
+Мутации массива делаются через `ModelArray` (`model.items`) либо через ноду формы `FormArray`
+(`form.items`) — нода данными не владеет и передаёт мутацию в тот же массив модели:
 
 ```typescript
 model.items.push({ id: '1', name: '', price: 0 });   // добавить в конец (плоские значения!)
@@ -112,8 +150,18 @@ model.items.clear();
 model.items.length;                                  // реактивная длина
 model.items.at(0);                                   // под-модель элемента (FormModel<Item>)
 model.items.map((item, i) => item.name);             // item — FormModel<Item>
+
+// та же мутация через ноду формы (у ноды вставка — insert, у модели — insertAt)
+form.items.push();                                   // строка по шаблону arrayOf(blank)
+form.items.insert(0, { id: '3', name: '', price: 0 });
+form.items.removeAt(index);
+form.items.length;                                   // число строк (число, не сигнал)
+form.items.keyAt(index);                             // стабильный ключ строки
 ```
 
+Формы строк держатся за под-модели элементов и при `move` / `swap` не пересоздаются; ключ строки
+(`keyAt`) не меняется при перестановке — его и берут для React `key`.
+
 > **Плоские значения при push.** В `push`/`insertAt` передавай payload из **плоских значений**
 > (`{ id, name, price }`), а НЕ FieldConfig-шаблон (`{ value, component }`). Component/componentProps
 > берутся из `item`-фабрики схемы автоматически.
@@ -130,27 +178,27 @@ model.items.map((item, i) => item.name);             // item — FormModel<Item>
 
 ### Rendering Arrays
 
-Каждый элемент массива — под-форма (`FormProxy<Item>`). Итерируй через `form.items.map`:
+Каждый элемент массива — под-форма (`FormGroup<Item>`). Итерируй через `form.items.map`:
 
 ```tsx
-import { useArrayLength } from '@reformer/core';
+import { useArrayLength } from '@reformer/core/react';
 
-function ItemsList({ form }: { form: FormProxy<MyForm> }) {
+function ItemsList({ form }: { form: FormGroup<MyForm> }) {
   const length = useArrayLength(form.items);
 
   return (
     <div>
       {form.items.map((item, index) => (
-        <div key={index}>
+        <div key={form.items.keyAt(index)}>
           <FormField control={item.name} />
           <FormField control={item.price} />
-          <button onClick={() => model.items.removeAt(index)}>Remove</button>
+          <button onClick={() => form.items.removeAt(index)}>Remove</button>
         </div>
       ))}
 
       {length === 0 && <p>No items yet</p>}
 
-      <button onClick={() => model.items.push({ id: crypto.randomUUID(), name: '', price: 0 })}>
+      <button onClick={() => form.items.push({ id: crypto.randomUUID(), name: '', price: 0 })}>
         Add Item
       </button>
     </div>
@@ -158,34 +206,36 @@ function ItemsList({ form }: { form: FormProxy<MyForm> }) {
 }
 ```
 
-> В монорепо для массивов используется готовый `FormArraySection` из `@reformer/ui-kit`
-> (`control={form.items}`, `itemComponent`, `initialValue`, add/remove/reorder из коробки).
-> См. `find_recipe(topic="form-array")`.
+> В монорепо для массивов используется готовый `FieldArraySection` из `@reformer/ui-kit`
+> (`control={form.items}`, `itemComponent`, add/remove/reorder из коробки; шаблон новой строки —
+> `arrayOf(blank)` в модели, проп `initialValue` — запасной путь). В схеме массив под-форм рисует
+> компонент `FieldArray` узла `{ model, component: FieldArray, item }`.
+> См. `find_recipe(topic="field-array")`.
 
 ### Array Cross-Validation
 
-Whole-array правило пишется оператором `cross(sig, (f) => ...)`: `f` — снапшот `model.get()`
-(плоские значения), ошибка вешается на поле-носитель `sig`. Per-item правила — `each`
-(см. выше, оба — из `@reformer/core/validation`).
+Правило над всем массивом пишется оператором `cross` из аргумента схемы: `check` получает снимок
+модели области (`model.get()`, плоские значения), ошибка вешается на поле-носитель. Тип снимка
+выведен из схемы. Правила строк — `applyEach` (см. выше).
 
 Носитель — любое **скалярное** поле формы (флаг `hasItems`, итоговая сумма и т.п.), у которого
-есть сигнал `model.$.<field>` и нода в форме:
+есть ручка `model.$.<field>` и нода в форме:
 
 ```typescript
-import { cross } from '@reformer/core/validation';
-
 type MyForm = { hasItems: boolean; items: Item[] };
 
-// внутри defineValidationSchema<MyForm>(({ model }) => { ... })
-cross(model.$.hasItems, (f: MyForm) => {
-  const names = f.items.map((i) => i.name);
-  return names.length !== new Set(names).size
-    ? { code: 'duplicate', message: 'Item names must be unique' }
-    : null;
+defineValidation<MyForm>(({ model, cross }) => {
+  cross(model.$.hasItems, (form) => {
+    const names = form.items.map((item) => item.name);
+    return names.length !== new Set(names).size
+      ? { code: 'items.duplicate' }
+      : null;
+  });
 });
 ```
 
 ## See also
 
-- [03-api-signatures.md](./03-api-signatures.md) — сигнатуры нод `form.<array>` / `ModelArray`, per-item валидация `each`
-- CDK / ui-kit form-array (`FormArray.Root`, `FormArraySection`) — `find_recipe(topic="form-array")`
+- [03-api-signatures.md](./03-api-signatures.md) — сигнатуры нод `form.<array>` / `ModelArray`, правила строк `applyEach`
+- [37-compiled-schema.md](./37-compiled-schema.md) — область строки `#/items[<ключ>]` и `keyAt`
+- CDK / ui-kit field-array (`FieldArray.Root`, `FieldArraySection`) — `find_recipe(topic="field-array")`