@reformer/core 10.2.0 → 11.0.0-beta.2

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`.

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>` для тяжёлого форматирования