@reformer/core 10.2.0 → 11.0.0-beta.2

package/docs/llms/17-nonexistent-api.md

@@ -0,0 +1,93 @@
+## 15. NON-EXISTENT API (DO NOT USE)
+
+**Следующего API НЕТ в @reformer/core** (наследие старой path-based архитектуры,
+удалено при переходе на M1 и при разделении валидации/поведения):
+
+> ⚠️ Операторы валидации `validate`/`validateAsync`/`validateWhen`/`cross`/`each`/`apply`
+> **существуют** — но живут в сабпути `@reformer/core/validation` (ambient-схема
+> `defineValidationSchema(({ model }) => …)`, раннер `validateModel`), а НЕ в корне и НЕ
+> в `@reformer/core/validators`. Ниже перечислено то, чего действительно нет.
+
+| Wrong                            | Correct                                          | Notes                                          |
+| -------------------------------- | ------------------------------------------------ | ---------------------------------------------- |
+| `useForm`                        | `createModel` + `createForm`                     | Хука useForm нет                               |
+| `validateForm`, `validateFormModel` | `validateModel(model, schema)` из `@reformer/core/validation` | Legacy-движок дерева `{ value, validators }` удалён; внешний раннер — `validateModel` |
+| `validateModelSync`              | `await validateModel(model, schema)`             | Синхронного раннера нет — прогон асинхронный (`Promise<boolean>`) |
+| `applyWhen`                      | `validateWhen(() => cond, () => { … })`          | Условная валидация — оператором `validateWhen`, не узлом `{ when, children }` |
+| `validateItems`, `validateGroup`, `validateTree` | `each(model.arr, (im) => { … })` | Per-item — оператором `each`; под-схема — прямой вызов `sub({ model: model.child })` |
+| `ValidationSchemaFn`, `BehaviorSchemaFn` | `ValidationSchema<T>` (`defineValidationSchema`) / `defineFormBehavior` | Типы path-схем удалены |
+| `equalTo`, `custom`, `notEmpty` (validators) | inline `Rule<T>` `(value) => err \| null` в `validate(sig, [...])`; сравнение полей — `cross(sig, fn)` | Таких фабрик нет; кастомное правило — обычная функция значения, cross-field — `cross` |
+| `form.submit()` / `form.validate()` прогоняют схему | `await validateModel(model, schema)` перед submit/шагом | submit/validate НЕ запускают ambient-схему валидации |
+| `FieldPath`, `FieldPathNode`     | `model.$.field` (`PathAwareSignal`)              | Пути заменены сигналами                         |
+| `ctx.form.x.value.value`         | `model.x` / `model.$.x.value`                    | В behaviors читаем модель напрямую              |
+| `ctx.setFieldValue(name, value)` | `model.x = value` / `compute(...)`               | Не существует                                   |
+| `transformers`, `createTransformer` | `transformValue(signal, fn)`                  | Готового набора трансформеров нет               |
+| `useHiddenCondition`             | `useFormControlValue` + условный рендер в JSX    | Хука нет                                        |
+| `FormProvider`, `control` prop, `register()` | `<Component form={form} />`, `useFormControl(form.field)` | Форма передаётся через props |
+| `getFieldValue()`                | `model.field` / `useFormControlValue(form.field)`| Не существует                                   |
+
+### Common Import Errors
+
+```typescript
+// WRONG - этих символов / путей НЕ существует
+import { useForm, validateForm, validateFormModel } from '@reformer/core';        // NO!
+import { validate, applyWhen, equalTo } from '@reformer/core/validators';         // NO! операторов тут нет
+import { transformers } from '@reformer/core/behaviors';                          // NO!
+import type { FieldPath, ValidationSchemaFn } from '@reformer/core';              // NO!
+
+// CORRECT
+import { createModel, createForm, useFormControl } from '@reformer/core';
+import type { FormModel, ValidationError, FieldConfig } from '@reformer/core';
+// Операторы валидации + раннер + defineValidationSchema — отдельный сабпуть:
+import {
+  validate, validateAsync, validateWhen, cross, each, apply,
+  defineValidationSchema, validateModel,
+  type Rule, type AsyncRule, type ValidationSchema,
+} from '@reformer/core/validation';
+// Фабрики-валидаторы (value-only, принимают nullable):
+import { required, email, min, minLength, pattern } from '@reformer/core/validators';
+// Поведение (отдельный слой, контракт не менялся):
+import { defineFormBehavior, compute, onChange, revalidateWhen } from '@reformer/core/behaviors';
+```
+
+### Schema Common Mistakes
+
+Валидация и layout — **разные** контракты. Layout-узел привязывает поле к сигналу и
+НЕ несёт `validators`; правила живут в отдельной `defineValidationSchema`.
+
+```typescript
+// WRONG - примитив/литерал вместо сигнала, и validators прямо в layout-узле
+const schema = {
+  name:  '',                                       // нет привязки к сигналу
+  email: { value: '', validators: [required()] },  // value — литерал, а validators в layout больше нет
+};
+
+// CORRECT - layout только связывает поле с сигналом модели...
+const layout = {
+  name:  { value: model.$.name,  component: Input, componentProps: { label: 'Name' } },
+  email: { value: model.$.email, component: Input, componentProps: { label: 'Email' } },
+};
+
+// ...а правила — отдельная ambient-схема (прогоняется раннером validateModel):
+const validation = defineValidationSchema<Form>(({ model }) => {
+  validate(model.$.email, [required({ message: 'Email обязателен' }), email()]);
+});
+```
+
+### Behaviors Common Mistakes
+
+```typescript
+// WRONG - строковые пути и (form) => ... — старый API
+enableWhen(path.city, (form) => Boolean(form.country));
+
+// CORRECT - сигналы модели, условие читает model
+enableWhen(model.$.city, () => Boolean(model.country), { resetOnDisable: true });
+```
+
+Поведение **не владеет** валидацией. Чтобы поведение инициировало прогон схемы — мост
+`revalidateWhen` (validate/submit сами схему не запускают):
+
+```typescript
+// CORRECT - поведение дёргает внешний раннер валидации при изменении зависимости
+revalidateWhen([model.$.password], () => void validateModel(model, validation));
+```

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

@@ -0,0 +1,183 @@
+# Условные поля — видимость, доступность и валидация
+
+## Purpose
+
+«Показать поле X только если Y» под M1 решается тремя независимыми механизмами — выбирай по
+тому, что именно должно быть условным:
+
+1. **Видимость / доступность** (поле остаётся в модели, но выключается/включается и не валидируется)
+   — behaviors: `enableWhen`, а для условной записи значения — `compute` / `copyFrom` с опцией `{ when }`.
+2. **Условная валидация** (правила применяются только в истинной ветке) — оператор
+   `validateWhen(() => cond, () => {…})` внутри схемы `defineValidationSchema`, прогоняется раннером `validateModel`.
+3. **Скрытие из разметки** (узел вообще не рендерится) — `useFormControlValue` + условный рендер в JSX.
+
+> Условная **валидация** — оператор `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({ model, schema, behavior })` — форма владеет
+  жизненным циклом, DSL-операторы регистрируют свой cleanup сами (ручной массив cleanup'ов не нужен).
+- Таргетом может быть и **группа**: `enableWhen(model.$.residenceAddress, () => model.sameAsRegistration === false)`
+  проходит по поддереву; без `resetOnDisable` значение группы сохраняется (удобно, когда оно копируется
+  из другого источника).
+
+> **Групповой таргет работает только у DSL-`enableWhen` из `@reformer/core/behaviors`**, не у
+> одноимённого корневого `enableWhen` из `@reformer/core` (тот резолвит только leaf-сигналы через
+> реестр → на group-сигнале это тихий no-op). `get_symbol_docs("enableWhen")` возвращает именно
+> корневой, не group-capable вариант.
+
+## Условная валидация
+
+Правила, действующие только при выполнении условия, оборачиваются оператором
+`validateWhen(() => cond, () => {…})` внутри схемы `defineValidationSchema<T>(({ model }) => …)`.
+Условие `cond` читает модель напрямую (`model.field` — снимок на момент прогона): при истинном условии
+раннер применяет вложенные `validate`/`cross`/…, при ложном — правила ветки **гасятся** (поля,
+затронутые ранее, получают `setErrors([])`). Прогон — внешним раннером
+`validateModel(model, schema): Promise<boolean>` (ошибки сами роутятся в ноды формы).
+
+```typescript
+import {
+  validate,
+  validateWhen,
+  defineValidationSchema,
+  validateModel,
+} from '@reformer/core/validation';
+import { required, min } from '@reformer/core/validators';
+
+const schema = defineValidationSchema<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` гасит их (`setErrors([])`).
+`validateWhen` управляет только **валидацией**; чтобы поля ещё и выпадали из состояния (сброс
+значения), держи их под `enableWhen` из раздела выше — слои независимы.
+
+## Скрытие в JSX
+
+Чтобы условный блок вообще не рендерился, читай значение-триггер хуком `useFormControlValue(form.field)`
+и делай ранний `return null`. Хук возвращает **только значение** (без деструктуризации `{ value }`).
+
+```tsx
+import { useFormControlValue } from '@reformer/core';
+
+function MortgageFields({ form }: { form: 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 }) => 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-схемы). Тип схемы — `ValidationSchema<T>`
+  (`(ctx: { model: FormModel<T> }) => void`), фабрика-обёртка — `defineValidationSchema<T>(fn)`.
+
+- **Cross-field — обычная функция над снапшотом, а не `ModelValidator (value, scope, root)`.**
+  Соседние поля читаются из снимка модели (`f: Root`, эквивалент `model.get()`), а правило навешивается
+  оператором `cross(sig, fn)`. Каноничное использование — `complex-multy-step-form/schemas/validation.ts`.
+
+  ```typescript
+  import { cross } from '@reformer/core/validation';
+  import type { ValidationError } from '@reformer/core';
+
+  // (f: Root) => error — сравнение с соседним полем, без scope/root-параметров
+  const passwordsMatch = (f: { password: string; confirmPassword: string }): ValidationError | null =>
+    f.confirmPassword && f.password && f.confirmPassword !== f.password
+      ? { code: 'mismatch', message: 'Пароли не совпадают' }
+      : null;
+
+  // внутри defineValidationSchema — fn получает снапшот текущего scope (model.get()):
+  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,88 @@
+## 16. READING FIELD VALUES (CRITICALLY IMPORTANT)
+
+Под M1 значения живут в модели. Есть три контекста чтения: value-доступ модели, сигналы, и React-хуки.
+
+### В React-компоненте — хуки
+
+```typescript
+// Полное состояние поля (объект)
+const { value, errors, disabled, touched, shouldShowError } = useFormControl(control.email);
+
+// Только значение (напрямую, БЕЗ деструктуризации!)
+const email = useFormControlValue(control.email);
+
+// Реактивная длина массива
+const count = useArrayLength(control.items);
+```
+
+### Вне 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,147 @@
+## 17. COMPUTE vs ONCHANGE
+
+Под M1 behaviors работают на сигналах модели. Есть два способа их писать:
+
+- **примитивы из `@reformer/core`** — принимают сигналы, возвращают cleanup, вызываются
+  императивно (например, в `useEffect`), cleanup складывается в массив;
+- **декларативный DSL из `@reformer/core/behaviors`** — `defineFormBehavior(...)` + операторы,
+  cleanup управляется формой, передаётся в `createForm({ behavior })`.
+
+Для производных значений — `compute`/`computeFrom`. Для side-эффектов на изменение (async,
+обновление componentProps) — `onChange` (DSL) или примитив `watchField`.
+
+### compute — auto-tracking (DSL)
+
+`compute(target, read)` подписывается на сигналы, прочитанные внутри `read()`, и пишет
+результат в `target`. Цель не входит в источники → цикла нет; запись идемпотентна (peek-guard).
+Кросс-уровневые вычисления работают так же — читай любые поля модели.
+
+```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 FormArray
+
+Агрегат по массиву (сумма доходов созаёмщиков и т.п.) считается **реактивно** через 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' как примитив
+
+computeFrom(
+  [model.$.loanAmount, model.$.loanTerm, model.$.interestRate],
+  model.$.monthlyPayment,
+  (amount, term, rate) => annuityMonthly(amount ?? 0, term ?? 0, rate ?? 0)
+);
+```
+
+> Примитив `computeFrom` из `@reformer/core` имеет ту же сигнатуру и возвращает cleanup-функцию.
+
+### 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` (без debounce/AbortSignal). `onChange` построен
+поверх неё. Для простых синхронных реакций:
+
+```typescript
+import { watchField } from '@reformer/core';
+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,113 @@
+## 18. ARRAY OPERATIONS
+
+Массивы объектов — model-owned. Мутации делаются через `ModelArray` (`model.arrayField`);
+рендер — через ноду формы (`form.items.map` / `.at`).
+
+### 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);               // FormProxy<Item> | undefined
+form.items.map((item, i) => …); // item — FormProxy<Item>
+```
+
+### Array Methods (на модели)
+
+```typescript
+model.items.push({ name: '', price: 0 });        // добавить в конец (ПЛОСКИЕ значения!)
+model.items.insertAt(0, { name: '', price: 0 }); // вставить по индексу
+model.items.removeAt(index);                     // удалить по индексу
+model.items.move(fromIndex, toIndex);            // переместить
+model.items.swap(a, b);                          // поменять местами
+model.items.clear();                             // очистить
+```
+
+> **push принимает ПЛОСКИЕ значения** (`{ name, price }`), а НЕ FieldConfig-шаблон
+> (`{ value, component }`). Component/componentProps берутся из `item`-фабрики схемы.
+> Передача FieldConfig-объектов сломает рендер (`[object Object]` в инпутах).
+
+### Rendering Arrays
+
+```tsx
+import { useArrayLength } from '@reformer/core';
+
+function ItemsList({ form }: { form: FormProxy<MyForm> }) {
+  const length = useArrayLength(form.items);
+
+  return (
+    <div>
+      {form.items.map((item, index) => (
+        <div key={index}>
+          <FormField control={item.name} />
+          <FormField control={item.price} />
+          <button onClick={() => model.items.removeAt(index)}>Remove</button>
+        </div>
+      ))}
+      {length === 0 && <p>No items yet</p>}
+      <button onClick={() => model.items.push({ name: '', price: 0 })}>Add Item</button>
+    </div>
+  );
+}
+```
+
+> В монорепо используется `FormArraySection` из `@reformer/ui-kit`: `control={form.items}`,
+> `itemComponent`, `initialValue`, add/remove/reorder из коробки. См. `find_recipe(topic="form-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
+    })
+  );
+});
+```
+
+### 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
+
+Whole-array правило — оператор `cross(sig, (f) => ...)` из `@reformer/core/validation`:
+`f` — снапшот `model.get()`, ошибка вешается на скалярное поле-носитель `sig`. Per-item
+правила — `each(model.<array>, (im) => ...)`.
+
+```typescript
+import { cross } from '@reformer/core/validation';
+import type { ValidationError } from '@reformer/core';
+
+const percentagesSumTo100 = (f: MyForm): ValidationError | null => {
+  const total = f.items.reduce((sum, i) => sum + (i.percentage || 0), 0);
+  return Math.abs(total - 100) > 0.01
+    ? { code: 'invalid_total', message: 'Percentages must sum to 100%' }
+    : null;
+};
+
+// внутри defineValidationSchema<MyForm>(({ model }) => { ... })
+cross(model.$.totalPercent, percentagesSumTo100); // носитель — скалярное поле формы
+```