@reformer/core 10.2.0 → 11.0.0-beta.10

package/docs/llms/18-conditional-fields.md

@@ -0,0 +1,222 @@
+# Условные поля — видимость, доступность и валидация
+
+## Purpose
+
+«Показать поле X только если Y» решается тремя независимыми механизмами — выбирай по тому, что
+именно должно быть условным:
+
+1. **Видимость / доступность** (поле остаётся в модели, но выключается/включается и не валидируется)
+   — behaviors: `enableWhen`, а для условной записи значения — `compute` / `copyFrom` с опцией `{ when }`.
+2. **Условная валидация** (правила применяются только в истинной ветке) — оператор
+   `validateWhen(() => cond, () => {…})` внутри схемы `defineValidation`; прогон — уровнем формы
+   (`bundle.validate()` / `bundle.submission.submit`) либо раннером `validateModel`.
+3. **Скрытие из разметки** (узел вообще не рендерится) — в схеме под рендерером — оператор
+   `hideWhen(schema.node(selector), cond)`; при разметке в JSX — `useFormControlValue` + условный
+   рендер.
+
+> Условная **валидация** — оператор `validateWhen` из `@reformer/core/validation`; старого branch-узла
+> `{ when, children }` и хелпера `applyWhen` больше нет — см.
+> [Anti-patterns удалённого контракта валидации](#anti-patterns-удалённого-контракта-валидации) и `17-nonexistent-api.md`.
+
+## Видимость и доступность
+
+`enableWhen(target, () => condition, { resetOnDisable })` из `@reformer/core/behaviors`
+включает/выключает поле реактивно. При `disabled` поле не участвует в валидации; с
+`resetOnDisable: true` его значение сбрасывается при выключении (иначе — сохраняется).
+
+```typescript
+import { defineFormBehavior, enableWhen, compute, copyFrom } from '@reformer/core/behaviors';
+
+type CreditForm = {
+  loanType: 'mortgage' | 'car' | 'consumer';
+  propertyValue: number | null;
+  initialPayment: number | null;
+  sameEmail: boolean;
+  email: string;
+  emailAdditional: string;
+};
+
+export const creditBehavior = defineFormBehavior<CreditForm>(({ model }) => {
+  // один или несколько таргетов; условие читает model.* реактивно
+  enableWhen(
+    [model.$.propertyValue, model.$.initialPayment],
+    () => model.loanType === 'mortgage',
+    { resetOnDisable: true },
+  );
+
+  // условная ЗАПИСЬ производного значения — compute с { when }
+  compute(model.$.initialPayment, () => Math.round((model.propertyValue ?? 0) * 0.2), {
+    when: () => model.loanType === 'mortgage',
+  });
+
+  // условное КОПИРОВАНИЕ из другого поля — copyFrom с { when }
+  copyFrom(model.$.email, model.$.emailAdditional, { when: () => model.sameEmail === true });
+});
+```
+
+Требования:
+
+- **Все поля должны быть материализованы в модели** (`createModel`), даже те, что показываются
+  только под условием. `enableWhen`/`compute`/`copyFrom` принимают сигналы `model.$.field`, а не
+  строковые пути; сигнала для несуществующего поля нет.
+- Поведение подключается к форме через `createForm({ …, behavior })` (или
+  `createFormFromModel({ model, schema, behavior })`) — форма владеет жизненным циклом,
+  DSL-операторы регистрируют свой cleanup сами (ручной массив cleanup'ов не нужен).
+- Таргетом может быть и **группа**: `enableWhen(model.$.residenceAddress, () => model.sameAsRegistration === false)`
+  проходит по поддереву; без `resetOnDisable` значение группы сохраняется (удобно, когда оно копируется
+  из другого источника).
+
+> `enableWhen` / `disableWhen` существуют только как операторы поведения
+> (`@reformer/core/behaviors`): в корне `@reformer/core` и в `@reformer/core/model` их нет.
+
+Скрыть узел разметки, когда форму рисует рендерер, — оператор узла схемы в том же поведении:
+
+```typescript
+import { defineFormBehavior, enableWhen, hideWhen } from '@reformer/core/behaviors';
+
+export const mortgageBehavior = defineFormBehavior<CreditForm>(({ model, schema }) => {
+  const isMortgage = () => model.loanType === 'mortgage';
+  enableWhen([model.$.propertyValue, model.$.initialPayment], isMortgage, { resetOnDisable: true });
+  hideWhen(schema.node('mortgage'), () => !isMortgage()); // узел с selector: 'mortgage'
+});
+```
+
+`hideWhen` только записывает правило — исполняет его рендерер; при разметке в JSX он ничего не
+делает (см. раздел «Скрытие в JSX»).
+
+**Скрытие — только видимость.** Поля скрытого узла (`hideWhen` или
+`schema.node(sel).setHidden(true)`) остаются включёнными, и правила их проверяют: шаг с
+незаполненным скрытым полем не пройдёт, а замечаний на экране не будет. Поэтому узел с полями
+скрывают вместе с `enableWhen` по тому же условию — как в примере выше.
+
+## Условная валидация
+
+Правила, действующие только при выполнении условия, оборачиваются оператором
+`validateWhen(() => cond, () => {…})` внутри схемы `defineValidation<T>(({ model }) => …)`.
+Условие `cond` читает модель напрямую (`model.field` — снимок на момент прогона): при истинном условии
+раннер применяет вложенные `validate`/`cross`/…, при ложном — правила ветки **гасятся** (поля,
+затронутые ранее, получают `setIssues([])`). Прогон — уровнем формы (`createForm({ validation })`,
+затем `bundle.validate()` / `bundle.submission.submit(handler)`) либо раннером
+`validateModel(model, schema): Promise<boolean>`; замечания сами доезжают до нод формы.
+
+```typescript
+import {
+  validate,
+  validateWhen,
+  defineValidation,
+  validateModel,
+} from '@reformer/core/validation';
+import { required, min } from '@reformer/core/validators';
+
+const schema = defineValidation<CreditForm>(({ model }) => {
+  validate(model.$.loanType, [required()]);
+
+  // ветка применяется только для ипотеки
+  validateWhen(
+    () => model.loanType === 'mortgage',
+    () => {
+      validate(model.$.propertyValue, [required(), min(1_000_000)]);
+      validate(model.$.initialPayment, [required()]);
+    },
+  );
+});
+
+const ok: boolean = await validateModel(model, schema);
+```
+
+Переключение `loanType` с `mortgage` на другой тип автоматически снимает ошибки `required` с
+`propertyValue`/`initialPayment` — при ложном условии ветка `validateWhen` гасит их (`setIssues([])`).
+`validateWhen` управляет только **валидацией**; чтобы поля ещё и выпадали из состояния (сброс
+значения), держи их под `enableWhen` из раздела выше — слои независимы.
+
+Выключенное поле (`enableWhen`, `disable()`) в проверке **уровня формы** не участвует:
+`bundle.validate`, `validateStep`, `submission.submit`, `flow.next()` и живая проверка гасят его
+замечания, и статус прогона совпадает с `valid` формы. Значение выключенного поля при этом остаётся
+в модели и уходит в обработчик отправки — модель передаётся целиком; убрать его из отправки —
+забота обработчика либо `enableWhen(…, { resetOnDisable: true })`. `validateWhen` нужен, когда
+поле остаётся доступным, но правило по условию не действует, — и в независимом раннере
+`validateModel(model, rules)`, который о нодах не знает.
+
+## Скрытие в JSX
+
+Чтобы условный блок вообще не рендерился, читай значение-триггер хуком `useFormControlValue(form.field)`
+и делай ранний `return null`. Хук возвращает **только значение** (без деструктуризации `{ value }`).
+
+```tsx
+import type { FormGroup } from '@reformer/core';
+import { useFormControlValue } from '@reformer/core/react';
+
+function MortgageFields({ form }: { form: FormGroup<CreditForm> }) {
+  const loanType = useFormControlValue(form.loanType);
+  if (loanType !== 'mortgage') return null;
+
+  return (
+    <>
+      <PropertyValueField form={form} />
+      <InitialPaymentField form={form} />
+    </>
+  );
+}
+```
+
+Скрытие в JSX — чисто визуальное: если поле должно ещё и **выпадать из валидации/состояния**,
+сочетай его с `enableWhen({ resetOnDisable: true })` (доступность) или `validateWhen` (валидация).
+
+## Anti-patterns удалённого контракта валидации
+
+Условную валидацию раньше собирали иначе; эти формы удалены при переходе на `@reformer/core/validation`.
+Ниже — **как НЕ надо** (чтобы не регрессировать); рабочий вариант — `validateWhen` из раздела выше.
+
+- **Нет branch-узла `{ when, children }` в дереве схемы.** Старая схема была деревом
+  `{ value, validators: [...] }` с ветками `{ when: (scope, root) => boolean, children: [...] }`,
+  которое обходил `validateFormModel`. Теперь схема — функция `({ model, cross }) => void`, а условие —
+  оператор `validateWhen(() => cond, () => {…})`; отдельного объекта-узла нет.
+
+  ```typescript
+  // УДАЛЕНО — так больше нельзя
+  const schema = {
+    children: [
+      { value: model.$.loanType, validators: [required()] },
+      { when: (_s, root) => root.loanType === 'mortgage', children: [ /* … */ ] },
+    ],
+  };
+  await validateFormModel(model, schema); // символа нет
+  ```
+
+- **`applyWhen` не существует** — ни как экспорт, ни как локальный сахар: он эмитил branch-узел,
+  которого больше нет. Оборачивай условные правила оператором `validateWhen`.
+
+- **`ValidationSchemaFn` удалён** (тип старой path-схемы). Тип схемы — `ValidationDefinition<T>`
+  (`(scope: { model: FormModel<T>; cross }) => void`), фабрика-обёртка — `defineValidation<T>(fn)`.
+
+- **Cross-field — обычная функция над снимком, а не `ModelValidator (value, scope, root)`.**
+  Правило значения — `Rule<T> = (value: T) => error | null`, параметров `scope` / `root` у него нет.
+  Соседние поля читаются из снимка модели, а правило вешается оператором `cross(sig, check)` из
+  аргумента схемы. Каноничное использование — каталог `validation/` формы `complex-multy-step-form`.
+
+  ```typescript
+  import { defineValidation } from '@reformer/core/validation';
+  import type { ValidationIssue } from '@reformer/core';
+
+  type Passwords = { password: string; confirmPassword: string };
+
+  // (snapshot) => error — сравнение с соседним полем
+  const passwordsMatch = (passwords: Passwords): ValidationIssue | null =>
+    passwords.confirmPassword &&
+    passwords.password &&
+    passwords.confirmPassword !== passwords.password
+      ? { code: 'confirmPassword.mismatch' } // текст кода — в словаре формы
+      : null;
+
+  // cross — из аргумента схемы; check получает снимок модели области:
+  const passwordRules = defineValidation<Passwords>(({ model, cross }) => {
+    cross(model.$.confirmPassword, passwordsMatch);
+  });
+  ```
+
+## See also
+
+- [03-api-signatures.md](./03-api-signatures.md) — сигнатуры `enableWhen`/`compute`/`copyFrom` (поведение) и `validate`/`validateWhen`/`cross`/`validateModel` (валидация)
+- [17-nonexistent-api.md](./17-nonexistent-api.md) — полный список удалённого API (`applyWhen`, `ValidationSchemaFn`, `validateFormModel`, …)
+- [25-reset-when.md](./25-reset-when.md) — `resetWhen` как альтернатива, когда поле остаётся enabled
+- [19-reading-values.md](./19-reading-values.md) — `useFormControlValue` и чтение значений в React

package/docs/llms/19-reading-values.md

@@ -0,0 +1,100 @@
+## 16. READING FIELD VALUES (CRITICALLY IMPORTANT)
+
+Значения живут в модели. Есть три контекста чтения: value-доступ модели, сигналы, и React-хуки
+(`@reformer/core/react`).
+
+### В React-компоненте — хуки
+
+```typescript
+// Полное состояние поля (объект); текст замечания — useIssueMessage(messages)(issues[0])
+// shouldShowIssues — показывать ли тексты замечаний; shouldShowError — aria-invalid
+const { value, issues, disabled, touched, shouldShowIssues } = useFormControl(control.email);
+
+// Только значение (напрямую, БЕЗ деструктуризации!)
+const email = useFormControlValue(control.email);
+
+// Реактивная длина массива
+const count = useArrayLength(control.items);
+```
+
+### Вне React — нода формы
+
+```typescript
+form.email.value.value;      // сигнал значения ноды (реактивно в effect/computed)
+form.email.getValue();       // значение без подписки
+form.email.issues.value;     // замечания: ValidationIssue[] — код и параметры, без текста
+form.items.length;           // число строк массива (число; в эффекте подписывает)
+form.getValue();             // значение группы целиком
+```
+
+### Вне React — модель
+
+```typescript
+// value-доступ (реактивно внутри effect/computed, запись присваиванием)
+model.email;                 // читать
+model.email = 'a@b.c';       // писать
+model.address.city;          // вложенное поле (model.address — под-модель FormModel<Address>)
+
+// через сигнал (escape-hatch)
+model.$.email.value;         // реактивное чтение/запись
+model.$.email.peek();        // нереактивный снимок
+model.$.address.city.value;  // сигнал вложенного поля (≡ model.address.$.city у под-модели)
+
+// весь объект
+model.get();                 // НЕреактивный снимок { email, address: { city }, ... } — для submit
+```
+
+> ⚠️ `model.get()` и `model.isDirty()` читают через `peek()` — внутри `effect`/`computed` они НЕ
+> создают зависимостей. `computed(() => model.get())` никогда не пересчитается. Для реактивного
+> чтения всего объекта — узел дерева `$` (ниже).
+
+### Подписка на группу и на модель целиком
+
+Каждый узел дерева `$` — сигнал: лист отдаёт `PathAwareSignal`, а корень, вложенные объекты-группы
+и массивы — `ReadonlySignal` агрегированного значения поддерева. Поэтому подписаться можно на любом
+уровне, а не только на конкретном поле.
+
+```typescript
+model.$.subscribe((all) => autosave(all));      // любое изменение модели; all: T целиком
+model.$.address.subscribe((addr) => ...);       // только поддерево address
+model.$.address.value;                          // реактивный снимок группы
+model.$.address.peek();                         // нереактивный снимок группы
+model.$.items.subscribe((rows) => ...);         // массив: и правка элемента, и push/removeAt/move
+
+// узел — обычный ReadonlySignal, поэтому принимается операциями слоя данных
+watchField(model.$.address, (addr) => geocode(addr));
+```
+
+Дети узла доступны как раньше — `model.$.address.city` по-прежнему сигнал поля. Подписчик вызывается
+сразу с текущим значением (семантика `Signal.subscribe`), а `model.set(...)`/`model.reset()`
+уведомляют один раз, а не по разу на поле.
+
+> ⚠️ Доступ к полю выигрывает у свойства сигнала: если в форме есть поле с именем `value`, `peek`,
+> `subscribe`, `valueOf`, `toString`, `toJSON` или `brand`, то `model.$.<группа>.<это имя>` вернёт
+> сигнал поля. `subscribe` при этом продолжает работать.
+
+### В behaviors — читаем model напрямую
+
+`compute`/`onChange`/условия `when` читают значения из value-модели (`model.field`) —
+подписка на сигналы происходит автоматически внутри реактивного эффекта.
+
+```typescript
+import { defineFormBehavior, compute, onChange } from '@reformer/core/behaviors';
+
+const behavior = defineFormBehavior<MyForm>(({ model, form }) => {
+  // читаем несколько полей — compute сам подпишется на прочитанные сигналы
+  compute(model.$.fullName, () => `${model.firstName} ${model.lastName}`);
+
+  // onChange: 1-й аргумент — новое значение; остальные поля берём из model
+  onChange(model.$.loanAmount, (amount) => {
+    const term = model.loanTerm;
+    if (amount && term) {
+      form.monthlyPayment.updateComponentProps({ hint: `≈ ${amount / term}` });
+    }
+  });
+});
+```
+
+> Cross-field ЗАПИСЬ производного значения делай через `compute` (цель не входит в источники →
+> цикла нет). Для side-эффектов (загрузка опций, обновление componentProps) — `onChange`.
+> `computeFrom`/`copyFrom`/`enableWhen` принимают сигналы (`model.$.x`), НЕ строковые пути.

package/docs/llms/20-compute-vs-watch.md

@@ -0,0 +1,153 @@
+## 17. COMPUTE vs ONCHANGE
+
+Поведение работает на сигналах модели. Писать его можно двумя способами:
+
+- **декларативный DSL из `@reformer/core/behaviors`** — `defineFormBehavior(...)` + операторы,
+  cleanup управляется формой, передаётся в `createForm({ behavior })`. Это способ для формы;
+- **примитивы из `@reformer/core/model`** — принимают сигналы, возвращают cleanup, вызываются
+  императивно (например, в `useEffect`), cleanup складывается в массив. Нужны вне формы; в корне
+  `@reformer/core` их нет.
+
+Для производных значений — `compute`/`computeFrom`. Для side-эффектов на изменение (async,
+обновление componentProps) — `onChange` (DSL) или примитив `watchField`.
+
+### compute — auto-tracking (DSL)
+
+`compute(target, read)` подписывается на сигналы, прочитанные внутри `read()`, и пишет
+результат в `target`. Цель не входит в источники → цикла нет; запись идемпотентна (peek-guard).
+Кросс-уровневые вычисления работают так же — читай любые поля модели. Тип результата задаёт поле:
+`compute(model.$.total, () => model.amount)` при `amount: number | null` и `total: number` не
+компилируется — вычисление писало бы `null` в число (то же у `computeFrom`).
+
+```typescript
+import { defineFormBehavior, compute } from '@reformer/core/behaviors';
+
+const behavior = defineFormBehavior<MyForm>(({ model }) => {
+  // same-level
+  compute(model.$.total, () => (model.price ?? 0) * (model.quantity ?? 0));
+
+  // nested-to-nested / cross-level — просто читаем нужные поля
+  compute(model.$.fullName, () =>
+    [model.personalData.firstName, model.personalData.lastName].filter(Boolean).join(' ')
+  );
+
+  // условный пересчёт
+  compute(model.$.initialPayment, () => model.propertyValue * 0.2, {
+    when: () => model.loanType === 'mortgage',
+  });
+});
+```
+
+> **Не читай `model.get()` внутри `compute`/`when`** — это нереактивный снимок, зависимость не
+> отследится и пересчёта не будет. Читай поля по отдельности (`model.field` или `model.$.field.value`).
+> `model.get()` — только вне реактивного контекста (в `onChange`, обработчиках событий).
+
+### Computed sum over a FieldArray
+
+Агрегат по массиву (сумма доходов созаёмщиков и т.п.) считается **реактивно** через value-proxy
+массива — `model.<array>.map(...)`:
+
+```typescript
+compute(model.$.coBorrowersIncome, () =>
+  model.coBorrowers.map((cb) => cb.monthlyIncome ?? 0).reduce((s, v) => s + v, 0)
+);
+```
+
+Почему реактивно: `.map` читает сигнал самого массива (трекает `push`/`removeAt`/reorder) **и**
+внутри колбэка читает каждый `cb.<field>` (трекает правки элементов) → пересчёт срабатывает на оба
+вида изменений.
+
+Ключевой нюанс — **на каком proxy** живёт `.map`/`.reduce`(-via-`.map`):
+
+- **value-proxy `model.coBorrowers`** — есть `.map`/`.forEach`/`.at`/индексы (обходит элементы как
+  значения). Именно его читай в `compute`.
+- **signals-proxy `model.$.coBorrowers`** — только индексный доступ и `.length`, без `.map`. Для
+  агрегата не подходит.
+
+Если нужен только **счётчик** (пересчёт лишь на изменение длины, без чтения полей элементов) —
+`model.<array>.map(() => null)` (длина трекается, значения — нет):
+
+```typescript
+// зависит только от КОЛИЧЕСТВА элементов, не от их полей
+compute(model.$.interestRate, () => computeRate(model.properties.map(() => null).length));
+```
+
+> **Не агрегируй через `model.get()` / `model.<array>.peek()`** в `compute` — это нереактивный
+> снапшот массива, зависимость не отследится и сумма не пересчитается. Читай массив только через
+> value-proxy `model.<array>.map(...)`.
+
+### computeFrom — явный список источников
+
+Когда нужен явный контроль зависимостей — `computeFrom(sources, target, fn)`. Значения
+источников приходят в `fn` позиционно.
+
+```typescript
+import { computeFrom } from '@reformer/core/behaviors'; // примитив — из '@reformer/core/model'
+
+computeFrom(
+  [model.$.loanAmount, model.$.loanTerm, model.$.interestRate],
+  model.$.monthlyPayment,
+  (amount, term, rate) => annuityMonthly(amount ?? 0, term ?? 0, rate ?? 0)
+);
+```
+
+> Примитив `computeFrom` из `@reformer/core/model` имеет ту же сигнатуру и возвращает cleanup-функцию,
+> но цель вычисляемой НЕ помечает: `model.set` / `patch` / `reset` её перезаписывают, `isDirty()` её
+> учитывает — до следующей смены источников. Оператор из `@reformer/core/behaviors` цель помечает
+> (`markDerived`), и массовая запись её не трогает. В поведении формы — оператор.
+
+### onChange — реакция на изменение (async, side-effects)
+
+`onChange(source, cb, { debounce, immediate })` вызывает `cb(value, { signal })` при изменении.
+Колбэк выполняется ВНЕ effect-контекста — можно писать сигналы/ноды. `signal` (AbortSignal)
+аннулируется при следующей смене значения.
+
+```typescript
+import { defineFormBehavior, onChange } from '@reformer/core/behaviors';
+
+const behavior = defineFormBehavior<MyForm>(({ model, form }) => {
+  onChange(
+    model.$.country,
+    async (country, { signal }) => {
+      const cities = await fetchCities(country, { signal });
+      form.city.updateComponentProps({ options: cities });
+    },
+    { debounce: 300 }
+  );
+});
+```
+
+### Примитив watchField
+
+Низкоуровневая подписка из `@reformer/core/model` (без debounce/AbortSignal). `onChange` построен
+поверх неё. Для простых синхронных реакций:
+
+```typescript
+import { watchField } from '@reformer/core/model';
+const stop = watchField(model.$.country, () => { model.city = ''; });
+```
+
+Источником может быть не только поле: узлы-контейнеры дерева `$` (корень, группы, массивы) — тоже
+`ReadonlySignal`, поэтому за поддеревом целиком следят без перечисления полей.
+
+```typescript
+watchField(model.$.address, (addr) => geocode(addr));  // любое поле address
+watchField(model.$, (all) => autosave(all));           // любое поле формы
+```
+
+### Rule of Thumb
+
+| Scenario | Use |
+|----------|-----|
+| Производное значение (любой уровень) | `compute` (auto-tracking) |
+| Производное с явными зависимостями | `computeFrom` |
+| Async-реакция, обновление componentProps | `onChange` (debounce + AbortSignal) |
+| Простая синхронная реакция (примитив) | `watchField` |
+| Реакция на любое изменение группы/формы | `watchField(model.$.<группа>)` или `.subscribe` |
+
+### Chained computeds
+
+Если несколько вычислений зависят друг от друга (`interestRate` → `monthlyPayment` →
+`paymentToIncomeRatio`), объяви каждое отдельным `compute` — они выстроятся в правильном
+порядке через реактивный граф (цель одного = источник другого). Расходящиеся взаимные
+`compute` без стабилизации бросят понятную ошибку (см. `22-cycle-detection.md`).

package/docs/llms/21-array-operations.md

@@ -0,0 +1,163 @@
+## 18. ARRAY OPERATIONS
+
+Массивы объектов — model-owned. Мутации делаются через `ModelArray` (`model.arrayField`) либо через
+ноду формы `FormArray` (`form.items`) — она данными не владеет и передаёт мутацию в массив модели;
+рендер — через ноду формы (`form.items.map` / `.at` / `.keyAt`).
+
+### Array Access
+
+```typescript
+// Через ModelArray (данные)
+model.items.at(0);              // FormModel<Item> | undefined (под-модель элемента)
+model.items.map((item, i) => item.name);  // item — FormModel<Item>
+model.items.length;             // реактивная длина
+model.items.toArray();          // снимок значений
+
+// Через ноду формы (рендер / доступ к нодам полей)
+form.items.at(0);               // FormGroup<Item> | undefined
+form.items.map((item, i) => …); // item — FormGroup<Item>
+form.items.length;              // число строк (число, не сигнал; в эффекте подписывает)
+form.items.keyAt(0);            // стабильный ключ строки — не меняется при move/swap
+```
+
+### Array Methods
+
+```typescript
+// на модели
+model.items.push({ name: '', price: 0 });        // добавить в конец (ПЛОСКИЕ значения!)
+model.items.push();                              // по шаблону arrayOf(blank)
+model.items.insertAt(0, { name: '', price: 0 }); // вставить по индексу 0…length; за концом — RangeError
+model.items.removeAt(index);                     // удалить по индексу; нет такого — ничего
+model.items.move(fromIndex, toIndex);            // переместить; индекс за концом — RangeError
+model.items.swap(a, b);                          // поменять местами
+model.items.clear();                             // очистить
+
+// на ноде формы — те же мутации (вставка называется insert)
+form.items.push();
+form.items.insert(0, { name: '', price: 0 });
+form.items.removeAt(index);
+form.items.move(fromIndex, toIndex);
+form.items.swap(a, b);
+form.items.clear();
+```
+
+Формы строк держатся за под-модели элементов: после `move` / `swap` строка остаётся той же нодой
+со своими `touched` и замечаниями.
+
+Разница между путями — в `dirty`. Мутация через ноду, которая поменяла состав строк (в том числе
+перестановка), делает массив и форму изменёнными (`form.items.dirty`), снимает это `reset`. Запись в
+модель — нет, как и у поля: загрузка данных форму не «пачкает». Кнопки добавления и удаления в
+интерфейсе — через ноду.
+
+> **push принимает ПЛОСКИЕ значения** (`{ name, price }`), а НЕ FieldConfig-шаблон
+> (`{ value, component }`). У массива с шаблоном `arrayOf` переданный объект накладывается на
+> шаблон: недостающие ключи берутся из него (так `add({ type })` из cdk даёт полный элемент). Component/componentProps берутся из `item`-фабрики схемы.
+> Передача FieldConfig-объектов сломает рендер (`[object Object]` в инпутах).
+
+### Rendering Arrays
+
+```tsx
+import { useArrayLength } from '@reformer/core/react';
+
+function ItemsList({ form }: { form: FormGroup<MyForm> }) {
+  const length = useArrayLength(form.items);
+
+  return (
+    <div>
+      {form.items.map((item, index) => (
+        <div key={form.items.keyAt(index)}>
+          <FormField control={item.name} />
+          <FormField control={item.price} />
+          <button onClick={() => form.items.removeAt(index)}>Remove</button>
+        </div>
+      ))}
+      {length === 0 && <p>No items yet</p>}
+      <button onClick={() => form.items.push({ name: '', price: 0 })}>Add Item</button>
+    </div>
+  );
+}
+```
+
+> В монорепо используется `FieldArraySection` из `@reformer/ui-kit`: `control={form.items}`,
+> `itemComponent`, add/remove/reorder из коробки; шаблон новой строки — `arrayOf(blank)` в модели.
+> См. `find_recipe(topic="field-array")`.
+
+### Per-item behavior — applyEach
+
+Чтобы применить поведение к КАЖДОМУ элементу (реагируя на add/remove), используй `applyEach`:
+
+```typescript
+import { defineFormBehavior, applyEach, compute } from '@reformer/core/behaviors';
+
+const behavior = defineFormBehavior<MyForm>(({ model }) => {
+  applyEach(
+    model.$.items,
+    defineFormBehavior<Item>(({ model: row }) => {
+      compute(row.$.lineTotal, () => row.qty * row.price); // per-row value-op
+    })
+  );
+});
+```
+
+### Вложенные области — массив в группе и в строке массива
+
+Узел `{ model: model.$.<массив>, item }` и операторы `applyEach` / `apply` / `enableWhen` работают на любой глубине:
+цель оператора — **ручка** `model.$.…`, под-модель и нода находятся по её идентичности, а не по
+пути.
+
+```typescript
+const phoneBehavior = defineFormBehavior<Phone>(({ model: phone }) => {
+  enableWhen(phone.$.number, () => phone.primary);
+});
+
+const contactBehavior = defineFormBehavior<Contact>(({ model: contact }) => {
+  applyEach(contact.$.phones, phoneBehavior); // массив внутри строки
+  enableWhen(contact.$.address, () => contact.quantity > 0); // группа внутри строки
+  apply(contact.$.address, addressBehavior); // под-схема получает настоящую под-модель
+});
+
+const behavior = defineFormBehavior<MyForm>(({ model }) => {
+  applyEach(model.$.contacts, contactBehavior);
+});
+```
+
+Ручка → value-фасад: `modelOf(model.$.address)` — под-модель (`get` / `set` / `patch`),
+`modelOf(model.$.phones)` — фасад массива (`push` / `removeAt` / `at`). Нода формы по ручке —
+`getNodeForSignal(model.$.address)`.
+
+### Aggregate write — aggregateInto
+
+Агрегатная запись в строки (например, «последняя строка = 100 − Σ остальных»):
+
+```typescript
+import { aggregateInto } from '@reformer/core/behaviors';
+
+aggregateInto(model.$.rows, (rows) => {
+  const n = rows.length;
+  if (n === 0) return [];
+  const others = rows.slice(0, n - 1).reduce((s, r) => s + r.percent, 0);
+  return [{ index: n - 1, patch: { percent: 100 - others } }]; // derive должна сходиться
+});
+```
+
+### Array Cross-Validation
+
+Правило над всем массивом — оператор `cross(sig, check)` из аргумента схемы валидации: `check`
+получает снимок модели, ошибка вешается на скалярное поле-носитель `sig`. Правила строк —
+`applyEach(model.$.<массив>, схема строки)`.
+
+```typescript
+import { defineValidation } from '@reformer/core/validation';
+import type { ValidationIssue } from '@reformer/core';
+
+const percentagesSumTo100 = (form: MyForm): ValidationIssue | null => {
+  const total = form.items.reduce((sum, item) => sum + (item.percentage || 0), 0);
+  return Math.abs(total - 100) > 0.01
+    ? { code: 'items.percentTotal', params: { total } } // текст кода — в словаре формы
+    : null;
+};
+
+const itemsRules = defineValidation<MyForm>(({ model, cross }) => {
+  cross(model.$.totalPercent, percentagesSumTo100); // носитель — скалярное поле формы
+});
+```