@reformer/core 10.0.0-beta.3 → 10.0.0-beta.4

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,59 @@
+## 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
+```
+
+### В 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,138 @@
+## 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 = ''; });
+```
+
+### Rule of Thumb
+
+| Scenario | Use |
+|----------|-----|
+| Производное значение (любой уровень) | `compute` (auto-tracking) |
+| Производное с явными зависимостями | `computeFrom` |
+| Async-реакция, обновление componentProps | `onChange` (debounce + AbortSignal) |
+| Простая синхронная реакция (примитив) | `watchField` |
+
+### 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); // носитель — скалярное поле формы
+```

package/docs/llms/22-cycle-detection.md

@@ -0,0 +1,86 @@
+# Cycle Detection — предотвращение «Cycle detected»
+
+## Как устроено под M1
+
+Behaviors на сигналах уже защищены от типичных циклов:
+
+- `compute`/`computeFrom` пишут в цель только если значение изменилось (**peek-guard**), а цель
+  не входит в источники → сходящийся пересчёт не зацикливается;
+- `transformValue`/`resetWhen`/`syncFields`/`enableWhen` откладывают запись состояния вне
+  effect-контекста (`runOutsideEffect` / микротаск) — эффект «читает и пишет один сигнал» не падает;
+- `onChange`-колбэк выполняется вне effect-контекста, поэтому в нём можно свободно писать сигналы/ноды.
+
+Тебе НЕ нужно вручную ставить `{ immediate: false }`, guard'ить `disabled.value` перед
+`disable()` или сравнивать значения перед записью — это делается внутри операторов.
+
+## Когда всё-таки возникает «Cycle detected»
+
+### 1. Расходящийся взаимный compute
+
+Два вычисления, которые бесконечно гоняют значение друг у друга без стабилизации:
+
+```typescript
+// ❌ расходится → preact бросает «Cycle detected»
+compute(model.$.a, () => model.b + 1);
+compute(model.$.b, () => model.a + 1);
+```
+
+DSL перехватывает это и заменяет понятной ошибкой с именем поля и подсказкой. Решение —
+однонаправленная зависимость или стабилизирующее условие `when`:
+
+```typescript
+// ✅ одно направление
+compute(model.$.total, () => model.price * model.qty);
+
+// ✅ стабилизация условием
+compute(model.$.a, () => model.b + 1, { when: () => model.a !== model.b + 1 });
+```
+
+### 2. Неидемпотентный transformValue
+
+`transformValue` пишет обратно в то же поле. Если `f(f(x)) !== f(x)` — цикл:
+
+```typescript
+// ❌ f(f(x)) = "prefix-prefix-x" ≠ f(x)
+transformValue(model.$.field, (v) => `prefix-${v}`);
+
+// ✅ guard «уже преобразовано»
+transformValue(model.$.field, (v) => (v?.startsWith('prefix-') ? v : `prefix-${v}`));
+```
+
+### 3. Условие `resetWhen`/`copyFrom`, читающее собственную цель
+
+Если условие зависит от значения целевого поля — сброс/копия триггерит своё же условие:
+
+```typescript
+// ❌ самотриггер — условие читает cardNumber (цель)
+resetWhen(model.$.cardNumber, () => model.cardNumber !== '');
+
+// ✅ условие зависит только от независимого поля
+resetWhen(model.$.cardNumber, () => model.paymentType !== 'card', { resetValue: '' });
+```
+
+## Prefer built-in operators over manual logic
+
+Вместо ручной сборки reset-on-disable через `onChange` — используй `enableWhen({ resetOnDisable })`:
+
+```typescript
+// ✅ SIMPLE — enableWhen с resetOnDisable (рекомендуется)
+enableWhen(model.$.vehicleVin, () => model.insuranceType === 'casco', { resetOnDisable: true });
+enableWhen(model.$.vehicleBrand, () => model.insuranceType === 'casco', { resetOnDisable: true });
+```
+
+`enableWhen` принимает и **массив** целей, и группу — можно включать несколько полей одним условием:
+
+```typescript
+enableWhen([model.$.propertyValue, model.$.initialPayment], () => model.loanType === 'mortgage', {
+  resetOnDisable: true,
+});
+```
+
+## Key Rules
+
+1. Производные значения — через `compute`/`computeFrom` (peek-guard встроен), не ручным `onChange` + запись.
+2. `transformValue`-трансформер должен быть идемпотентным (`f(f(x)) === f(x)`).
+3. Условие `resetWhen`/`copyFrom`/`enableWhen` НЕ должно читать собственную цель.
+4. Расходящийся взаимный `compute` — разорви однонаправленной зависимостью или `when`.