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

package/docs/llms/23-copy-from.md

@@ -0,0 +1,141 @@
+# copyFrom — Копирование значений между полями
+
+## Purpose
+
+`copyFrom` декларативно копирует значение одного поля (или группы) в другое при выполнении
+условия `when`. Используется для UX-сценариев «совпадает с …»: «адрес проживания = адрес
+регистрации», «email для уведомлений = основной email», «billing = shipping». Оператор сам
+выходит из reactive-контекста (`runOutsideEffect`), поэтому не порождает «Cycle detected».
+
+## API
+
+Есть две формы. **Примитив из `@reformer/core`** (сигнал → сигнал):
+
+```typescript
+function copyFrom<T>(
+  source: ReadonlySignal<T>,
+  target: Signal<T>,
+  options?: { when?: () => boolean; transform?: (value: T) => T }
+): () => void; // возвращает cleanup
+```
+
+**DSL-оператор из `@reformer/core/behaviors`** (сигнал ИЛИ группа):
+
+```typescript
+function copyFrom<T>(
+  source: ReadonlySignal<T> | object,   // model.$.field или model.$.group
+  target: Signal<T> | object,
+  options?: { when?: () => boolean; transform?: (value: T) => T }
+): void; // cleanup управляется формой
+```
+
+`when` — реактивное условие (читает сигналы модели через `model.*`). `transform` применяется
+к значению перед записью в target. Отдельной опции `fields`/`debounce` нет.
+
+## Examples
+
+### Базовый сценарий — синхронизация двух адресов
+
+```typescript
+import { defineFormBehavior, copyFrom } from '@reformer/core/behaviors';
+
+type OrderForm = {
+  useShippingAsBilling: boolean;
+  shippingAddress: string;
+  billingAddress: string;
+};
+
+export const orderBehavior = defineFormBehavior<OrderForm>(({ model }) => {
+  copyFrom(model.$.shippingAddress, model.$.billingAddress, {
+    when: () => model.useShippingAsBilling === true,
+  });
+});
+```
+
+Пример: `copyFrom(model.$.shippingAddress, model.$.billingAddress, { when: () => model.useShippingAsBilling })`.
+
+### Копирование группы целиком
+
+Когда source/target — группы (`model.$.registrationAddress`), копируется всё значение группы:
+
+```typescript
+import { defineFormBehavior, copyFrom } from '@reformer/core/behaviors';
+
+type ProfileForm = {
+  sameAsRegistration: boolean;
+  registrationAddress: Address;
+  residenceAddress: Address;
+};
+
+export const profileBehavior = defineFormBehavior<ProfileForm>(({ model }) => {
+  copyFrom(model.$.registrationAddress, model.$.residenceAddress, {
+    when: () => model.sameAsRegistration === true,
+  });
+});
+```
+
+### Copy + transform — нормализация при копировании
+
+```typescript
+import { defineFormBehavior, copyFrom } from '@reformer/core/behaviors';
+
+type ContactForm = { sameEmail: boolean; email: string; emailAdditional: string };
+
+export const contactBehavior = defineFormBehavior<ContactForm>(({ model }) => {
+  copyFrom(model.$.email, model.$.emailAdditional, {
+    when: () => model.sameEmail === true,
+    transform: (value) => (typeof value === 'string' ? value.trim().toLowerCase() : value),
+  });
+});
+```
+
+### Как примитив (вне defineFormBehavior)
+
+```typescript
+import { copyFrom } from '@reformer/core';
+
+const cleanups = [
+  copyFrom(model.$.email, model.$.emailAdditional, { when: () => model.sameEmail === true }),
+];
+// teardown: cleanups.forEach((c) => c());
+```
+
+## Anti-patterns
+
+```typescript
+// ❌ Двусторонняя связь через два copyFrom — конфликт направлений
+copyFrom(model.$.a, model.$.b);
+copyFrom(model.$.b, model.$.a);
+
+// ✅ Двусторонняя синхронизация — это работа syncFields
+syncFields(model.$.a, model.$.b);
+```
+
+```typescript
+// ❌ when, читающий саму target — лишний триггер при перезаписи target
+copyFrom(model.$.source, model.$.target, { when: () => model.target === '' });
+
+// ✅ when опирается на независимый флаг
+copyFrom(model.$.source, model.$.target, { when: () => model.copyEnabled === true });
+```
+
+## Troubleshooting
+
+**Q: Скопированное значение не появляется в target.**
+A: Проверьте, что (1) behavior передан в `createForm({ behavior })` (или примитив вызван и не
+отписан); (2) `when` возвращает `true`; (3) типы source/target совместимы (`copyFrom` пишет как есть).
+
+**Q: «Cycle detected» при копировании.**
+A: Обычно `when` читает значение target (см. anti-pattern). Условие должно зависеть только от
+source и независимых флагов.
+
+**Q: Как откатить копию при снятии флага `when`?**
+A: `copyFrom` при `when === false` просто не пишет (не сбрасывает). Для сброса используй параллельно
+`resetWhen(model.$.target, () => !model.copyEnabled)` (см. `25-reset-when.md`).
+
+## See also
+
+- [24-sync-fields.md](./24-sync-fields.md) — двусторонняя синхронизация
+- [25-reset-when.md](./25-reset-when.md) — сброс target при выключенном условии
+- [20-compute-vs-watch.md](./20-compute-vs-watch.md) — `compute` для производных значений
+- [22-cycle-detection.md](./22-cycle-detection.md) — почему `runOutsideEffect` защищает от циклов

package/docs/llms/24-sync-fields.md

@@ -0,0 +1,114 @@
+# syncFields — Двусторонняя синхронизация полей
+
+## Purpose
+
+`syncFields` создаёт двунаправленную связь между двумя полями: изменение любого из них
+переписывает второе. Применяется для дублей одного значения в разных частях формы
+(тех. поле + видимое представление, mirror-поля). Внутренний флаг + `runOutsideEffect`
+исключают петли. Для одностороннего копирования — [`copyFrom`](./23-copy-from.md); для
+расчётов — [`compute`](./20-compute-vs-watch.md).
+
+## API
+
+Одинаково в примитиве (`@reformer/core`) и DSL (`@reformer/core/behaviors`):
+
+```typescript
+// примитив: возвращает cleanup
+function syncFields<T>(a: Signal<T>, b: Signal<T>, options?: { transform?: (value: T) => T }): () => void;
+
+// DSL: cleanup управляется формой
+function syncFields<T>(a: Signal<T>, b: Signal<T>, options?: { transform?: (value: T) => T }): void;
+```
+
+`a`/`b` — сигналы (`model.$.field`) совместимого типа `T`. `transform` **асимметричен**:
+применяется только при движении значения `a → b`. Опции `debounce`/`when` нет.
+
+## Examples
+
+### Базовый сценарий — отзеркаливание текста
+
+```typescript
+import { defineFormBehavior, syncFields } from '@reformer/core/behaviors';
+
+type MirrorForm = { syncField1: string; syncField2: string };
+
+export const mirrorBehavior = defineFormBehavior<MirrorForm>(({ model }) => {
+  syncFields(model.$.syncField1, model.$.syncField2);
+});
+```
+
+Пример: `syncFields(model.$.syncField1, model.$.syncField2)`.
+
+### С трансформацией — нормализация при прямой записи
+
+```typescript
+import { defineFormBehavior, syncFields } from '@reformer/core/behaviors';
+
+type DisplayForm = { internalCode: string; displayCode: string };
+
+export const codeBehavior = defineFormBehavior<DisplayForm>(({ model }) => {
+  // internalCode → displayCode: uppercase; обратно значение пишется как есть
+  syncFields(model.$.internalCode, model.$.displayCode, {
+    transform: (value) => (typeof value === 'string' ? value.toUpperCase() : value),
+  });
+});
+```
+
+### Как примитив (вне defineFormBehavior)
+
+```typescript
+import { syncFields } from '@reformer/core';
+const stop = syncFields(model.$.syncField1, model.$.syncField2);
+// stop() — отписаться
+```
+
+## Anti-patterns
+
+```typescript
+// ❌ Симметрично через два copyFrom — конфликт направлений
+copyFrom(model.$.a, model.$.b);
+copyFrom(model.$.b, model.$.a);
+
+// ✅ syncFields умеет двустороннюю связь без петель
+syncFields(model.$.a, model.$.b);
+```
+
+```typescript
+// ❌ Ожидание, что transform применится в обе стороны
+syncFields(model.$.a, model.$.b, { transform: (v) => v.trim() });
+// при записи в b значение НЕ trim-ается
+
+// ✅ Симметричные трансформы — syncFields + transformValue на обоих полях
+syncFields(model.$.a, model.$.b);
+transformValue(model.$.a, (v) => (typeof v === 'string' ? v.trim() : v));
+transformValue(model.$.b, (v) => (typeof v === 'string' ? v.trim() : v));
+```
+
+```typescript
+// ❌ Поля разного типа — рантайм-приведение и баги
+syncFields(model.$.amountString, model.$.amountNumber); // string ↔ number
+
+// ✅ Для конвертации — compute в обе стороны или один канонический формат + computed отображение
+compute(model.$.amountNumber, () => Number(model.amountString));
+```
+
+## Troubleshooting
+
+**Q: Поля «дёргаются», несколько перезаписей.**
+A: Чаще всего на одном из полей висит `transformValue`/`compute`. Убедитесь, что transform
+идемпотентен (`f(f(x)) === f(x)`).
+
+**Q: «Cycle detected» при `syncFields`.**
+A: Не вешайте дополнительно `onChange`/`watchField`, которые сами пишут в эти же поля.
+`syncFields` уже занимает оба направления.
+
+**Q: Как ограничить sync условием (как `when` у copyFrom)?**
+A: У `syncFields` нет `when`. Эмулируй через два `copyFrom(a→b, { when })` / `copyFrom(b→a, { when })`
+с флагами, разрешающими только одну активную сторону, либо через `apply` под условием.
+
+## See also
+
+- [23-copy-from.md](./23-copy-from.md) — однонаправленное копирование с `when`
+- [26-transform-value.md](./26-transform-value.md) — нормализация значений на месте
+- [22-cycle-detection.md](./22-cycle-detection.md) — почему симметричный copy ломается
+- [20-compute-vs-watch.md](./20-compute-vs-watch.md) — `compute` для производных значений

package/docs/llms/25-reset-when.md

@@ -0,0 +1,115 @@
+# resetWhen — Условный сброс полей
+
+## Purpose
+
+`resetWhen` сбрасывает значение поля к `resetValue`, когда `condition` истинно. Это
+альтернатива `enableWhen({ resetOnDisable: true })`, когда поле остаётся **enabled**, но
+содержимое нужно очистить (например, переключение способа оплаты обнуляет «номер карты», но
+поле по-прежнему доступно). По умолчанию пишет `null`; `resetValue` задаёт произвольное значение.
+
+## API
+
+Одинаково в примитиве (`@reformer/core`) и DSL (`@reformer/core/behaviors`):
+
+```typescript
+// примитив: возвращает cleanup
+function resetWhen<T>(target: Signal<T>, condition: () => boolean, options?: { resetValue?: T }): () => void;
+
+// DSL: cleanup управляется формой
+function resetWhen<T>(target: Signal<T>, condition: () => boolean, options?: { resetValue?: T }): void;
+```
+
+`target` — сигнал (`model.$.field`). `condition` — реактивное условие (читает `model.*`).
+`resetValue` по умолчанию `null`. Опций `onlyIfDirty`/`debounce` нет; флаги dirty/touched
+поля не трогаются оператором (значения принадлежат модели).
+
+## Examples
+
+### Базовый сценарий — сброс номера карты при смене способа оплаты
+
+```typescript
+import { defineFormBehavior, resetWhen } from '@reformer/core/behaviors';
+
+type CheckoutForm = { paymentType: 'card' | 'cash'; cardNumber: string };
+
+export const checkoutBehavior = defineFormBehavior<CheckoutForm>(({ model }) => {
+  resetWhen(model.$.cardNumber, () => model.paymentType !== 'card', { resetValue: '' });
+});
+```
+
+Пример: `resetWhen(model.$.cardNumber, () => model.paymentType !== 'card', { resetValue: '' })`.
+
+### resetValue для числовых полей
+
+```typescript
+import { defineFormBehavior, resetWhen } from '@reformer/core/behaviors';
+
+type MortgageForm = { propertyValue: number | null; initialPayment: number };
+
+export const mortgageBehavior = defineFormBehavior<MortgageForm>(({ model }) => {
+  // initialPayment теряет смысл без propertyValue — сбрасываем в 0
+  resetWhen(model.$.initialPayment, () => !model.propertyValue, { resetValue: 0 });
+});
+```
+
+### Как примитив (вне defineFormBehavior)
+
+```typescript
+import { resetWhen } from '@reformer/core';
+const stop = resetWhen(model.$.cardNumber, () => model.paymentType !== 'card', { resetValue: '' });
+```
+
+## Anti-patterns
+
+```typescript
+// ❌ resetWhen вместо enableWhen для disable-сценария
+resetWhen(model.$.field, () => !model.show);
+// поле останется enabled и валидируемым — ошибка required всё равно прилетит
+
+// ✅ Если поле должно «исчезнуть» — блокируем + сбрасываем
+enableWhen(model.$.field, () => model.show, { resetOnDisable: true });
+```
+
+```typescript
+// ❌ resetValue с типом, отличным от поля
+resetWhen(model.$.amount, () => model.skipPayment, { resetValue: 'none' }); // amount: number ← string
+
+// ✅ resetValue совместим с типом поля
+resetWhen(model.$.amount, () => model.skipPayment, { resetValue: 0 });
+```
+
+```typescript
+// ❌ Для строкового поля без resetValue прилетит null, а Input ждёт string
+resetWhen(model.$.cardNumber, () => model.paymentType !== 'card');
+
+// ✅ Явный resetValue для строк
+resetWhen(model.$.cardNumber, () => model.paymentType !== 'card', { resetValue: '' });
+```
+
+```typescript
+// ❌ condition читает саму цель — самотриггер (см. 22-cycle-detection.md)
+resetWhen(model.$.cardNumber, () => model.cardNumber !== '');
+
+// ✅ condition зависит только от независимого поля
+resetWhen(model.$.cardNumber, () => model.paymentType !== 'card', { resetValue: '' });
+```
+
+## Troubleshooting
+
+**Q: Сброс не срабатывает, хотя `condition` возвращает true.**
+A: Проверьте, что behavior зарегистрирован (`createForm({ behavior })`) или примитив не отписан,
+и что `condition` читает реактивные поля (`model.*`), а не снимок `model.get()`.
+
+**Q: Реактивная цепочка resetWhen → compute → resetWhen ломается.**
+A: Убедитесь, что `condition` не зависит от значения самого поля, иначе после сброса попадёте
+в новый триггер.
+
+**Q: Сбросить вложенную группу целиком?**
+A: `resetWhen` рассчитан на скалярные сигналы. Для группы используй `enableWhen({ resetOnDisable: true })`
+(проходит по поддереву) или `model.reset()` для сброса всей формы к initial-снимку.
+
+## See also
+
+- [04-common-patterns.md](./04-common-patterns.md) — `enableWhen({ resetOnDisable: true })` как альтернатива
+- [23-copy-from.md](./23-copy-from.md) — копирование, у которого нет встроенного отката
+- [22-cycle-detection.md](./22-cycle-detection.md) — почему `condition` не должен читать целевое поле

package/docs/llms/26-transform-value.md

@@ -0,0 +1,136 @@
+# transformValue — Автоматическая трансформация значений
+
+## Purpose
+
+`transformValue` подписывается на изменение поля и переписывает его трансформированной
+версией: uppercase для кодов, trim+toLowerCase для email, округление для чисел. Применяется
+единообразно ко всем источникам изменения (пользователь, `model.field = …`, `model.set/patch`,
+`copyFrom`). **Идемпотентность (`f(f(x)) === f(x)`) обязательна** — иначе бесконечный цикл.
+Оператор откладывает запись вне effect-контекста (`runOutsideEffect`) и не пишет, если
+`transformer(value) === value` — базовый guard от циклов.
+
+## API
+
+Одинаково в примитиве (`@reformer/core`) и DSL (`@reformer/core/behaviors`):
+
+```typescript
+// примитив: возвращает cleanup
+function transformValue<T>(target: Signal<T>, transformer: (value: T) => T): () => void;
+
+// DSL: cleanup управляется формой
+function transformValue<T>(target: Signal<T>, transformer: (value: T) => T): void;
+```
+
+`target` — сигнал (`model.$.field`). `transformer` — чистая идемпотентная функция значения.
+Дополнительных опций (`debounce`, `onUserChangeOnly`, `emitEvent`) и готового набора
+`transformers`/`createTransformer` НЕТ — трансформер пишется как обычная функция.
+
+## Examples
+
+### Базовый сценарий — uppercase для кода
+
+```typescript
+import { defineFormBehavior, transformValue } from '@reformer/core/behaviors';
+
+type PromoForm = { uppercaseField: string };
+
+export const promoBehavior = defineFormBehavior<PromoForm>(({ model }) => {
+  transformValue(model.$.uppercaseField, (value) => (value ?? '').toUpperCase());
+});
+```
+
+Пример: `transformValue(model.$.uppercaseField, (v) => (v ?? '').toUpperCase())`.
+
+### Несколько трансформаций
+
+```typescript
+import { defineFormBehavior, transformValue } from '@reformer/core/behaviors';
+
+type ContactForm = { email: string; phone: string; amount: number };
+
+export const contactBehavior = defineFormBehavior<ContactForm>(({ model }) => {
+  // email: trim + lowercase
+  transformValue(model.$.email, (value) => (value ?? '').trim().toLowerCase());
+
+  // телефон: только цифры → формат
+  transformValue(model.$.phone, (value) => {
+    if (!value) return value;
+    const digits = value.replace(/\D/g, '');
+    if (digits.length === 11) {
+      return `+7 (${digits.slice(1, 4)}) ${digits.slice(4, 7)}-${digits.slice(7, 9)}-${digits.slice(9)}`;
+    }
+    return value;
+  });
+
+  // округление до целого
+  transformValue(model.$.amount, (value) => (typeof value === 'number' ? Math.round(value) : value));
+});
+```
+
+### Как примитив (вне defineFormBehavior)
+
+```typescript
+import { transformValue } from '@reformer/core';
+const stop = transformValue(model.$.promoCode, (v) => (v ?? '').toUpperCase());
+```
+
+### Переиспользуемые трансформеры — обычные функции
+
+Готового набора нет, но легко собрать свои и применять их к любому сигналу:
+
+```typescript
+const toUpper = (target: Signal<string>) => transformValue(target, (v) => (v ?? '').toUpperCase());
+const trim = (target: Signal<string>) => transformValue(target, (v) => (v ?? '').trim());
+
+// в схеме поведения:
+toUpper(model.$.promoCode);
+trim(model.$.username);
+```
+
+## Anti-patterns
+
+```typescript
+// ❌ Неидемпотентный transformer — бесконечный цикл
+transformValue(model.$.field, (v) => `prefix-${v}`); // f(f(x)) ≠ f(x)
+
+// ✅ Guard внутри transformer
+transformValue(model.$.field, (v) => (v?.startsWith('prefix-') ? v : `prefix-${v}`));
+```
+
+```typescript
+// ❌ transformValue ОДНОВРЕМЕННО с syncFields на том же поле
+syncFields(model.$.a, model.$.b);
+transformValue(model.$.b, (v) => v.toUpperCase()); // взаимные перезаписи
+
+// ✅ Трансформируй источник ДО синхронизации
+transformValue(model.$.a, (v) => v.toUpperCase());
+syncFields(model.$.a, model.$.b);
+```
+
+```typescript
+// ❌ transformValue для производных полей (нет доступа к другим полям)
+transformValue(model.$.fullName, () => `${model.firstName} ${model.lastName}`);
+
+// ✅ Для зависимостей от других полей — compute
+compute(model.$.fullName, () => `${model.firstName} ${model.lastName}`);
+```
+
+## Troubleshooting
+
+**Q: «Cycle detected» при transformValue.**
+A: 99% — неидемпотентный transformer. Проверь `transformer(transformer(x)) === transformer(x)`.
+
+**Q: Трансформация не применяется.**
+A: Проверь, что behavior зарегистрирован (`createForm({ behavior })`) / примитив не отписан,
+и что форма не пересоздаётся на каждый рендер (используй `useMemo`).
+
+**Q: Каретка input прыгает при наборе.**
+A: Симптом частых записей. Форматирование с динамическими разделителями (телефон, кредитка)
+лучше делать через `<InputMask>` из `@reformer/ui-kit`, а не `transformValue`.
+
+## See also
+
+- [24-sync-fields.md](./24-sync-fields.md) — порядок применения с syncFields
+- [23-copy-from.md](./23-copy-from.md) — `transform`-опция при копировании
+- [22-cycle-detection.md](./22-cycle-detection.md) — про идемпотентность
+- [16-ui-components.md](./16-ui-components.md) — `<InputMask>` для тяжёлого форматирования

package/docs/llms/27-revalidate-when.md

@@ -0,0 +1,132 @@
+# revalidateWhen — Перевалидация по триггерам
+
+## Purpose
+
+`revalidateWhen` вызывает переданный колбэк ревалидации, когда изменяется любая из
+зависимостей. Применяется, когда правило зависит от значений других полей
+(`amount <= maxAmount`, `confirmPassword === password`, `initialPayment >= propertyValue * 0.2`).
+Валидация — отдельная функция-схема (`@reformer/core/validation`), прогоняемая по требованию через
+`validateModel(model, schema)`. Поэтому ревалидация выражается явным колбэком, а не автоматической
+привязкой к полю: поведение (`revalidateWhen`) лишь _инициирует_ прогон схемы валидации при изменении зависимости.
+
+## API
+
+`revalidateWhen` — оператор поведения (`@reformer/core/behaviors`, либо примитив `@reformer/core`).
+Его сигнатура НЕ зависит от контракта валидации:
+
+```typescript
+// примитив: возвращает cleanup
+function revalidateWhen(deps: ReadonlySignal<unknown>[], revalidate: () => void): () => void;
+
+// DSL: cleanup управляется формой
+function revalidateWhen(deps: ReadonlySignal<unknown>[], revalidate: () => void): void;
+```
+
+`deps` — массив сигналов-триггеров (`model.$.field`). `revalidate` — колбэк (обычно
+`() => void validateModel(model, schema)`, где `schema` — `defineValidationSchema<T>(({ model }) => …)`).
+Вызывается при изменении любой зависимости (НЕ на инициализации), вне effect-контекста.
+
+## Examples
+
+### Базовый сценарий — перевалидация amount при смене maxAmount
+
+```typescript
+import { defineFormBehavior, revalidateWhen } from '@reformer/core/behaviors';
+import { validateModel } from '@reformer/core/validation';
+
+export const paymentBehavior = defineFormBehavior<PaymentForm>(({ model }) => {
+  revalidateWhen([model.$.maxAmount], () => {
+    void validateModel(model, paymentSchema);
+  });
+});
+```
+
+Пример: `revalidateWhen([model.$.maxAmount], () => void validateModel(model, paymentSchema))`.
+Схема `paymentSchema` — стабильный module-level `const` (важно для отмены устаревших прогонов
+в `validateModel`), где правило amount навешано через `cross(model.$.amount, amountVsMax)`.
+
+### Несколько триггеров
+
+```typescript
+import { defineFormBehavior, revalidateWhen } from '@reformer/core/behaviors';
+import { validateModel } from '@reformer/core/validation';
+
+export const mortgageBehavior = defineFormBehavior<MortgageForm>(({ model }) => {
+  // initialPayment зависит и от propertyValue, и от loanAmount
+  revalidateWhen([model.$.propertyValue, model.$.loanAmount], () => {
+    void validateModel(model, mortgageSchema);
+  });
+});
+```
+
+### Парная перевалидация — confirmPassword
+
+```typescript
+import { defineFormBehavior, revalidateWhen } from '@reformer/core/behaviors';
+import { validateModel } from '@reformer/core/validation';
+
+// правило совпадения — cross-field в схеме: cross(model.$.confirmPassword, passwordsMatch),
+// где passwordsMatch читает снапшот формы (см. 03-api-signatures.md)
+export const registrationBehavior = defineFormBehavior<RegistrationForm>(({ model }) => {
+  // при смене password перевалидируем схему (confirm перепроверится)
+  revalidateWhen([model.$.password], () => {
+    void validateModel(model, registrationSchema);
+  });
+});
+```
+
+### Как примитив (вне defineFormBehavior)
+
+```typescript
+import { revalidateWhen } from '@reformer/core';
+import { validateModel } from '@reformer/core/validation';
+
+const stop = revalidateWhen([model.$.maxAmount], () => void validateModel(model, schema));
+```
+
+## Anti-patterns
+
+```typescript
+// ❌ Триггер == поле, которое и так меняется само
+revalidateWhen([model.$.amount], () => validateModel(model, schema));
+// amount и так валидируется при собственном изменении в общем прогоне
+
+// ✅ Триггеры — ДРУГИЕ поля, от которых зависит правило amount
+revalidateWhen([model.$.maxAmount, model.$.discount], () => validateModel(model, schema));
+```
+
+```typescript
+// ❌ Правило только через revalidateWhen, но в схеме нет зависимости от триггера
+revalidateWhen([model.$.maxAmount], () => validateModel(model, schema));
+// а валидатор amount — статичный max(1000), не читает maxAmount
+
+// ✅ Сначала cross-field правило (читает снапшот формы) в схеме валидации, потом revalidateWhen
+const amountVsMax = (f: Form): ValidationError | null =>
+  f.amount != null && f.maxAmount != null && f.amount > f.maxAmount
+    ? { code: 'tooBig', message: '...' }
+    : null;
+
+const schema = defineValidationSchema<Form>(({ model }) => {
+  cross(model.$.amount, amountVsMax); // навешиваем правило на поле amount
+});
+revalidateWhen([model.$.maxAmount], () => void validateModel(model, schema));
+```
+
+## Troubleshooting
+
+**Q: Ошибка target не пропадает после изменения триггера.**
+A: Проверьте, что (1) правило реально читает значение триггера — cross-field `cross(sig, fn)`,
+где `fn` берёт снапшот формы (`model.get()` / `f`); (2) в `deps` передан именно сигнал (`model.$.trigger`);
+(3) колбэк вызывает `validateModel` (роутит ошибки в ноды через `getNodeForSignal(sig).setErrors`).
+
+**Q: Как перевалидировать только одно поле, а не всю схему?**
+A: Схема — обычная функция, поэтому опиши стабильную под-схему только для этого поля и прогони её:
+`validateModel(model, oneFieldSchema)`, где
+`const oneFieldSchema = defineValidationSchema<Form>(({ model }) => cross(model.$.amount, amountVsMax))`.
+Раннер выставит/погасит ошибки только затронутых полей (гашение накапливается на пару `(model, schema)`).
+
+## See also
+
+- [03-api-signatures.md](./03-api-signatures.md) — cross-field `cross(sig, fn)` и раннер `validateModel`
+- [28-submit-and-reset.md](./28-submit-and-reset.md) — полная валидация формы
+- [20-compute-vs-watch.md](./20-compute-vs-watch.md) — реактивные производные значения