@reformer/core 3.0.0 → 4.0.0

package/dist/core/behavior/behaviors/enable-when.d.ts

@@ -1,12 +1,5 @@
-/**
- * Условное включение/отключение полей
- *
- * @group Behaviors
- * @category Behavior Rules
- * @module behaviors/enableWhen
- */
-import type { FieldPathNode } from '../../types';
-import type { EnableWhenOptions } from '../types';
+import { FieldPathNode } from '../../types';
+import { EnableWhenOptions } from '../types';
 /**
  * Условное включение поля на основе значений других полей
  *
@@ -15,17 +8,68 @@ import type { EnableWhenOptions } from '../types';
  *
  * @param field - Поле для включения/выключения
  * @param condition - Функция условия (true = enable, false = disable)
- * @param options - Опции
+ * @param options - Опции (`resetOnDisable`, `debounce`)
  *
- * @example
+ * @example Базовый сценарий с `resetOnDisable: true`
  * ```typescript
- * const schema: BehaviorSchemaFn<MyForm> = (path) => {
- *   // Включить поле только для ипотеки
+ * import { enableWhen, type BehaviorSchemaFn } from '@reformer/core/behaviors';
+ *
+ * interface LoanForm {
+ *   loanType: 'mortgage' | 'consumer' | 'car';
+ *   propertyValue: number;
+ *   initialPayment: number;
+ * }
+ *
+ * export const loanBehavior: BehaviorSchemaFn<LoanForm> = (path) => {
+ *   // Поля ипотеки активны только для loanType === 'mortgage'.
+ *   // resetOnDisable: true гарантирует чистые initial values при переключении.
  *   enableWhen(path.propertyValue, (form) => form.loanType === 'mortgage', {
- *     resetOnDisable: true
+ *     resetOnDisable: true,
+ *   });
+ *   enableWhen(path.initialPayment, (form) => form.loanType === 'mortgage', {
+ *     resetOnDisable: true,
  *   });
  * };
  * ```
+ *
+ * @example Множественные independent условия + cycle prevention
+ * ```typescript
+ * import { enableWhen, type BehaviorSchemaFn } from '@reformer/core/behaviors';
+ *
+ * interface ProfileForm {
+ *   sameAsRegistration: boolean;
+ *   employmentStatus: 'employed' | 'selfEmployed' | 'unemployed';
+ *   residenceAddress: { city: string; street: string };
+ *   companyName: string;
+ *   companyInn: string;
+ *   businessType: string;
+ * }
+ *
+ * export const profileBehavior: BehaviorSchemaFn<ProfileForm> = (path) => {
+ *   // Адрес проживания: enabled, когда НЕ совпадает с регистрационным
+ *   enableWhen(path.residenceAddress, (form) => form.sameAsRegistration === false, {
+ *     resetOnDisable: true,
+ *   });
+ *
+ *   // Поля работодателя: только для employed
+ *   enableWhen(path.companyName, (form) => form.employmentStatus === 'employed', {
+ *     resetOnDisable: true,
+ *   });
+ *   enableWhen(path.companyInn, (form) => form.employmentStatus === 'employed', {
+ *     resetOnDisable: true,
+ *   });
+ *
+ *   // ИП-поля: только для selfEmployed
+ *   enableWhen(path.businessType, (form) => form.employmentStatus === 'selfEmployed', {
+ *     resetOnDisable: true,
+ *   });
+ *
+ *   // ВАЖНО: condition не должен читать значение САМОГО поля — иначе цикл.
+ *   // condition зависит ТОЛЬКО от независимых триггеров (loanType, employmentStatus, ...).
+ * };
+ * ```
+ *
+ * @see [docs/llms/22-cycle-detection.md](../../../../docs/llms/22-cycle-detection.md)
  */
 export declare function enableWhen<TForm>(field: FieldPathNode<TForm, any>, condition: (form: TForm) => boolean, options?: EnableWhenOptions): void;
 /**
@@ -36,13 +80,38 @@ export declare function enableWhen<TForm>(field: FieldPathNode<TForm, any>, cond
  *
  * @param field - Поле для выключения
  * @param condition - Функция условия (true = disable, false = enable)
- * @param options - Опции
+ * @param options - Опции (`resetOnDisable`, `debounce`)
  *
- * @example
+ * @example Базовый сценарий — readonly после подтверждения
  * ```typescript
- * const schema: BehaviorSchemaFn<MyForm> = (path) => {
- *   // Выключить поле для потребительского кредита
- *   disableWhen(path.propertyValue, (form) => form.loanType === 'consumer');
+ * import { disableWhen, type BehaviorSchemaFn } from '@reformer/core/behaviors';
+ *
+ * interface ConfirmForm {
+ *   isConfirmed: boolean;
+ *   editableField: string;
+ * }
+ *
+ * export const confirmBehavior: BehaviorSchemaFn<ConfirmForm> = (path) => {
+ *   // Поле блокируется после установки чекбокса подтверждения
+ *   disableWhen(path.editableField, (form) => form.isConfirmed === true);
+ *   // resetOnDisable НЕ ставим — сохраняем введённый текст
+ * };
+ * ```
+ *
+ * @example С `resetOnDisable` для очистки заблокированного поля
+ * ```typescript
+ * import { disableWhen, type BehaviorSchemaFn } from '@reformer/core/behaviors';
+ *
+ * interface PromoForm {
+ *   loanType: 'mortgage' | 'consumer';
+ *   promoCode: string;
+ * }
+ *
+ * export const promoBehavior: BehaviorSchemaFn<PromoForm> = (path) => {
+ *   // Промокод недоступен для потребительских кредитов и сбрасывается
+ *   disableWhen(path.promoCode, (form) => form.loanType === 'consumer', {
+ *     resetOnDisable: true,
+ *   });
  * };
  * ```
  */

package/dist/core/behavior/behaviors/reset-when.d.ts

@@ -1,11 +1,4 @@
-/**
- * Условный сброс полей
- *
- * @group Behaviors
- * @category Behavior Rules
- * @module behaviors/resetWhen
- */
-import type { FieldPathNode, FormFields, FormValue } from '../../types';
+import { FieldPathNode, FormFields, FormValue } from '../../types';
 /**
  * Опции для resetWhen
  *
@@ -26,25 +19,45 @@ export interface ResetWhenOptions {
  *
  * @param field - Поле для сброса
  * @param condition - Функция условия (true = reset)
- * @param options - Опции
+ * @param options - Опции (`resetValue`, `onlyIfDirty`, `debounce`)
  *
- * @example
+ * @example Сброс зависимого поля при смене типа платежа
  * ```typescript
- * const schema: BehaviorSchemaFn<MyForm> = (path) => {
- *   // Сбросить поле при изменении типа кредита
- *   resetWhen(path.propertyValue, (form) => form.loanType !== 'mortgage');
+ * import { resetWhen, type BehaviorSchemaFn } from '@reformer/core/behaviors';
+ *
+ * interface CheckoutForm {
+ *   paymentType: 'card' | 'cash';
+ *   cardNumber: string;
+ * }
  *
- *   // Сбросить с кастомным значением
- *   resetWhen(path.initialPayment, (form) => !form.propertyValue, {
- *     resetValue: 0
+ * export const checkoutBehavior: BehaviorSchemaFn<CheckoutForm> = (path) => {
+ *   // Когда выбрано НЕ card — обнуляем номер карты в пустую строку
+ *   resetWhen(path.cardNumber, (form) => form.paymentType !== 'card', {
+ *     resetValue: '',
  *   });
+ * };
+ * ```
+ *
+ * @example `onlyIfDirty` — не трогаем нетронутые initial значения
+ * ```typescript
+ * import { resetWhen, type BehaviorSchemaFn } from '@reformer/core/behaviors';
+ *
+ * interface CarForm {
+ *   loanType: 'mortgage' | 'car' | 'consumer';
+ *   carPrice: number;
+ * }
  *
- *   // Сбросить только если поле было изменено пользователем
+ * export const carBehavior: BehaviorSchemaFn<CarForm> = (path) => {
+ *   // Если пользователь не вводил carPrice — оставляем default из схемы.
+ *   // Сбрасываем только если поле dirty (была пользовательская правка).
  *   resetWhen(path.carPrice, (form) => form.loanType !== 'car', {
- *     onlyIfDirty: true
+ *     resetValue: 0,
+ *     onlyIfDirty: true,
  *   });
  * };
  * ```
+ *
+ * @see [docs/llms/25-reset-when.md](../../../../docs/llms/25-reset-when.md)
  */
 export declare function resetWhen<TForm extends FormFields>(field: FieldPathNode<TForm, FormValue>, condition: (form: TForm) => boolean, options?: ResetWhenOptions & {
     debounce?: number;

package/dist/core/behavior/behaviors/revalidate-when.d.ts

@@ -1,12 +1,5 @@
-/**
- * Перевалидация полей при изменениях
- *
- * @group Behaviors
- * @category Behavior Rules
- * @module behaviors/revalidateWhen
- */
-import type { FieldPathNode, FormValue } from '../../types';
-import type { RevalidateWhenOptions } from '../types';
+import { FieldPathNode, FormValue } from '../../types';
+import { RevalidateWhenOptions } from '../types';
 /**
  * Перевалидирует поле при изменении других полей
  *
@@ -14,17 +7,47 @@ import type { RevalidateWhenOptions } from '../types';
  * @category Behavior Rules
  *
  * @param target - Поле для перевалидации
- * @param triggers - Поля-триггеры
- * @param options - Опции
+ * @param triggers - Поля-триггеры (НЕ должно содержать `target`)
+ * @param options - Опции (`debounce`)
+ *
+ * @example Парная перевалидация — confirmPassword при смене password
+ * ```typescript
+ * import { revalidateWhen, type BehaviorSchemaFn } from '@reformer/core/behaviors';
+ * import { equalTo } from '@reformer/core/validators';
+ * import type { FieldPath } from '@reformer/core';
+ *
+ * interface RegistrationForm { password: string; confirmPassword: string }
  *
- * @example
+ * export const validation = (path: FieldPath<RegistrationForm>) => {
+ *   equalTo(path.confirmPassword, path.password, { message: 'Пароли не совпадают' });
+ * };
+ *
+ * export const behavior: BehaviorSchemaFn<RegistrationForm> = (path) => {
+ *   // Если пользователь сначала ввёл confirm, потом меняет password —
+ *   // без revalidateWhen ошибка confirmPassword останется устаревшей.
+ *   revalidateWhen(path.confirmPassword, [path.password]);
+ * };
+ * ```
+ *
+ * @example Несколько триггеров + `debounce` для async-валидаторов
  * ```typescript
- * const schema: BehaviorSchemaFn<MyForm> = (path) => {
- *   // Перевалидировать initialPayment при изменении propertyValue
- *   revalidateWhen(path.initialPayment, [path.propertyValue], {
- *     debounce: 300
- *   });
+ * import { revalidateWhen, type BehaviorSchemaFn } from '@reformer/core/behaviors';
+ *
+ * interface MortgageForm {
+ *   propertyValue: number;
+ *   loanAmount: number;
+ *   initialPayment: number; // правило: initialPayment >= propertyValue * 0.2 - loanAmount
+ * }
+ *
+ * export const mortgageBehavior: BehaviorSchemaFn<MortgageForm> = (path) => {
+ *   revalidateWhen(
+ *     path.initialPayment,
+ *     [path.propertyValue, path.loanAmount],
+ *     { debounce: 300 }, // не дёргаем сервер на каждый keystroke
+ *   );
  * };
  * ```
+ *
+ * @see [docs/llms/27-revalidate-when.md](../../../../docs/llms/27-revalidate-when.md)
  */
 export declare function revalidateWhen<TForm>(target: FieldPathNode<TForm, FormValue>, triggers: FieldPathNode<TForm, FormValue>[], options?: RevalidateWhenOptions): void;

package/dist/core/behavior/behaviors/sync-fields.d.ts

@@ -1,12 +1,5 @@
-/**
- * Двусторонняя синхронизация полей
- *
- * @group Behaviors
- * @category Behavior Rules
- * @module behaviors/syncFields
- */
-import type { FieldPathNode, FormFields, FormValue } from '../../types';
-import type { SyncFieldsOptions } from '../types';
+import { FieldPathNode, FormFields, FormValue } from '../../types';
+import { SyncFieldsOptions } from '../types';
 /**
  * Двусторонняя синхронизация двух полей
  *
@@ -15,14 +8,41 @@ import type { SyncFieldsOptions } from '../types';
  *
  * @param field1 - Первое поле
  * @param field2 - Второе поле
- * @param options - Опции
+ * @param options - Опции (`transform` асимметричен — применяется только field1 → field2; `debounce`)
+ *
+ * @example Базовый mirror двух текстовых полей
+ * ```typescript
+ * import { syncFields, type BehaviorSchemaFn } from '@reformer/core/behaviors';
  *
- * @example
+ * interface MirrorForm {
+ *   syncField1: string;
+ *   syncField2: string;
+ * }
+ *
+ * export const mirrorBehavior: BehaviorSchemaFn<MirrorForm> = (path) => {
+ *   syncFields(path.syncField1, path.syncField2);
+ * };
+ * ```
+ *
+ * @example С `transform` (асимметричный) и `debounce` для защиты от частых перезаписей
  * ```typescript
- * const schema: BehaviorSchemaFn<MyForm> = (path) => {
- *   // Синхронизировать два поля
- *   syncFields(path.email, path.emailCopy);
+ * import { syncFields, type BehaviorSchemaFn } from '@reformer/core/behaviors';
+ *
+ * interface CodeForm {
+ *   internalCode: string;  // канонический формат
+ *   displayCode: string;   // показываем пользователю
+ * }
+ *
+ * export const codeBehavior: BehaviorSchemaFn<CodeForm> = (path) => {
+ *   // internalCode → displayCode: применяется toUpperCase
+ *   // displayCode → internalCode: пишется как есть
+ *   syncFields(path.internalCode, path.displayCode, {
+ *     transform: (value) => (typeof value === 'string' ? value.toUpperCase() : value),
+ *     debounce: 150, // сглаживает дёргание каретки
+ *   });
  * };
  * ```
+ *
+ * @see [docs/llms/24-sync-fields.md](../../../../docs/llms/24-sync-fields.md)
  */
 export declare function syncFields<TForm extends FormFields, T extends FormValue>(field1: FieldPathNode<TForm, T>, field2: FieldPathNode<TForm, T>, options?: SyncFieldsOptions<T>): void;

package/dist/core/behavior/behaviors/transform-value.d.ts

@@ -1,11 +1,4 @@
-/**
- * Трансформация значений полей
- *
- * @group Behaviors
- * @category Behavior Rules
- * @module behaviors/transformValue
- */
-import type { FieldPathNode, FormFields, FormValue } from '../../types';
+import { FieldPathNode, FormFields, FormValue } from '../../types';
 /**
  * Опции для transformValue
  *
@@ -26,34 +19,52 @@ export interface TransformValueOptions {
  * @category Behavior Rules
  *
  * @param field - Поле для трансформации
- * @param transformer - Функция трансформации
- * @param options - Опции
+ * @param transformer - Функция трансформации (ОБЯЗАТЕЛЬНО идемпотентная: f(f(x)) === f(x))
+ * @param options - Опции (`onUserChangeOnly`, `emitEvent`, `debounce`)
+ *
+ * @example Базовая нормализация — uppercase + trim email
+ * ```typescript
+ * import { transformValue, type BehaviorSchemaFn } from '@reformer/core/behaviors';
+ *
+ * interface RegistrationForm {
+ *   promoCode: string;
+ *   email: string;
+ * }
+ *
+ * export const registrationBehavior: BehaviorSchemaFn<RegistrationForm> = (path) => {
+ *   // Идемпотентно: toUpperCase(toUpperCase(x)) === toUpperCase(x) ✓
+ *   transformValue(path.promoCode, (value) => (value ?? '').toUpperCase());
+ *   transformValue(path.email, (value) => (value ?? '').trim().toLowerCase());
+ * };
+ * ```
  *
- * @example
+ * @example `onUserChangeOnly` + idempotent guard для не-тривиальных форматов
  * ```typescript
- * const schema: BehaviorSchemaFn<MyForm> = (path) => {
- *   // Автоматически переводить текст в верхний регистр
- *   transformValue(path.code, (value) => value?.toUpperCase());
- *
- *   // Форматировать номер телефона
- *   transformValue(path.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;
- *   });
- *
- *   // Удалять пробелы из email
- *   transformValue(path.email, (value) => value?.trim().toLowerCase());
- *
- *   // Округлять числа
- *   transformValue(path.amount, (value) => {
- *     return typeof value === 'number' ? Math.round(value) : value;
- *   });
+ * import { transformValue, type BehaviorSchemaFn } from '@reformer/core/behaviors';
+ *
+ * interface ProfileForm {
+ *   inn: string; // ИНН — только цифры
+ *   prefixedCode: string; // должен иметь префикс "ID-"
+ * }
+ *
+ * export const profileBehavior: BehaviorSchemaFn<ProfileForm> = (path) => {
+ *   // Цифры из ИНН: трансформер идемпотентный естественно
+ *   transformValue(path.inn, (v) => (v ?? '').replace(/\D/g, ''));
+ *
+ *   // Префикс — ВАЖНО guard «уже преобразовано», иначе бесконечный цикл
+ *   // f("ID-123") должно === "ID-123", а не "ID-ID-123"
+ *   transformValue(
+ *     path.prefixedCode,
+ *     (v) => (v?.startsWith('ID-') ? v : `ID-${v ?? ''}`),
+ *     {
+ *       onUserChangeOnly: true, // не трогаем значение из patchValue/preload
+ *       debounce: 200,
+ *     },
+ *   );
  * };
  * ```
+ *
+ * @see [docs/llms/26-transform-value.md](../../../../docs/llms/26-transform-value.md)
  */
 export declare function transformValue<TForm extends FormFields, TValue extends FormValue = FormValue>(field: FieldPathNode<TForm, TValue>, transformer: (value: TValue) => TValue, options?: TransformValueOptions & {
     debounce?: number;
@@ -64,18 +75,42 @@ export declare function transformValue<TForm extends FormFields, TValue extends
  * @group Behaviors
  * @category Behavior Rules
  *
- * @example
+ * @param transformer - Идемпотентная функция преобразования значения
+ * @param defaultOptions - Опции, применяемые ко всем вызовам созданного трансформера
+ *
+ * @example Доменно-специфичные трансформеры (банковский счёт, СНИЛС)
  * ```typescript
- * // Создаем переиспользуемые трансформеры
- * const toUpperCase = createTransformer<string>((value) => value?.toUpperCase());
- * const toLowerCase = createTransformer<string>((value) => value?.toLowerCase());
- * const trim = createTransformer<string>((value) => value?.trim());
- *
- * // Используем в форме
- * const schema: BehaviorSchemaFn<MyForm> = (path) => {
- *   toUpperCase(path.code);
- *   toLowerCase(path.email);
- *   trim(path.username);
+ * import { createTransformer, type BehaviorSchemaFn } from '@reformer/core/behaviors';
+ *
+ * // Сохраняем только цифры и форматируем СНИЛС: 000-000-000 00
+ * const formatSnils = createTransformer<string>((v) => {
+ *   const d = (v ?? '').replace(/\D/g, '').slice(0, 11);
+ *   if (d.length < 9) return d;
+ *   return `${d.slice(0, 3)}-${d.slice(3, 6)}-${d.slice(6, 9)}${d.length > 9 ? ' ' + d.slice(9) : ''}`;
+ * });
+ *
+ * interface ProfileForm { snils: string }
+ *
+ * export const profileBehavior: BehaviorSchemaFn<ProfileForm> = (path) => {
+ *   formatSnils(path.snils, { debounce: 100 });
+ * };
+ * ```
+ *
+ * @example С `defaultOptions` — единые настройки на серию полей
+ * ```typescript
+ * import { createTransformer, type BehaviorSchemaFn } from '@reformer/core/behaviors';
+ *
+ * // Все коды должны быть uppercase, но только после правки пользователем
+ * const upperOnUserEdit = createTransformer<string>(
+ *   (v) => (v ?? '').toUpperCase(),
+ *   { onUserChangeOnly: true, debounce: 100 },
+ * );
+ *
+ * interface PromoForm { promoCode: string; partnerCode: string }
+ *
+ * export const promoBehavior: BehaviorSchemaFn<PromoForm> = (path) => {
+ *   upperOnUserEdit(path.promoCode);
+ *   upperOnUserEdit(path.partnerCode);
  * };
  * ```
  */
@@ -83,10 +118,47 @@ export declare function createTransformer<TValue extends FormValue = FormValue>(
     debounce?: number;
 }) => void;
 /**
- * Готовые трансформеры для частых случаев
+ * Готовые трансформеры для частых случаев. Все идемпотентны и безопасны для повторного применения.
  *
  * @group Behaviors
  * @category Behavior Rules
+ *
+ * @example Готовые трансформеры в схеме формы
+ * ```typescript
+ * import { transformers, type BehaviorSchemaFn } from '@reformer/core/behaviors';
+ *
+ * interface RegistrationForm {
+ *   username: string;
+ *   email: string;
+ *   promoCode: string;
+ *   inn: string;
+ *   amount: number;
+ * }
+ *
+ * export const behavior: BehaviorSchemaFn<RegistrationForm> = (path) => {
+ *   transformers.trim(path.username);
+ *   transformers.toLowerCase(path.email);
+ *   transformers.toUpperCase(path.promoCode);
+ *   transformers.digitsOnly(path.inn);
+ *   transformers.roundTo2(path.amount);
+ * };
+ * ```
+ *
+ * @example Композиция готовых трансформеров через createTransformer
+ * ```typescript
+ * import { createTransformer, type BehaviorSchemaFn } from '@reformer/core/behaviors';
+ *
+ * // trim + lowercase в одном трансформере (применяется как одна операция)
+ * const normalizeEmail = createTransformer<string>(
+ *   (v) => (v ?? '').trim().toLowerCase(),
+ * );
+ *
+ * interface ContactForm { email: string }
+ *
+ * export const contactBehavior: BehaviorSchemaFn<ContactForm> = (path) => {
+ *   normalizeEmail(path.email);
+ * };
+ * ```
  */
 export declare const transformers: {
     /** Перевести в верхний регистр */

package/dist/core/behavior/behaviors/watch-field.d.ts

@@ -1,12 +1,5 @@
-/**
- * Отслеживание изменений поля
- *
- * @group Behaviors
- * @category Behavior Rules
- * @module behaviors/watchField
- */
-import type { FieldPathNode } from '../../types';
-import type { BehaviorContext, WatchFieldOptions } from '../types';
+import { FieldPathNode } from '../../types';
+import { BehaviorContext, WatchFieldOptions } from '../types';
 /**
  * Выполняет callback при изменении поля
  *
@@ -15,21 +8,73 @@ import type { BehaviorContext, WatchFieldOptions } from '../types';
  *
  * @param field - Поле для отслеживания
  * @param callback - Функция обратного вызова
- * @param options - Опции
+ * @param options - Опции (`debounce`, `immediate`)
+ *
+ * @example Async loader with try/catch + guard + debounce
+ * ```typescript
+ * import { watchField, type BehaviorSchemaFn } from '@reformer/core/behaviors';
+ *
+ * interface AddressForm { region: string; city: string }
  *
- * @example
+ * export const addressBehavior: BehaviorSchemaFn<AddressForm> = (path) => {
+ *   watchField(
+ *     path.region,
+ *     async (region, ctx) => {
+ *       if (!region) {
+ *         ctx.form.city.updateComponentProps({ options: [] });
+ *         return; // guard: пустое значение не триггерит fetch
+ *       }
+ *       try {
+ *         const { data: cities } = await fetchCities(region);
+ *         ctx.form.city.updateComponentProps({ options: cities });
+ *       } catch (error) {
+ *         console.error('[addressBehavior] failed to load cities:', error);
+ *         ctx.form.city.updateComponentProps({ options: [] });
+ *       }
+ *     },
+ *     { immediate: false, debounce: 300 }, // обязательные опции для async
+ *   );
+ * };
+ * ```
+ *
+ * @example Sync handler с консолидацией нескольких зависимостей в один watcher
  * ```typescript
- * const schema: BehaviorSchemaFn<MyForm> = (path) => {
- *   // Динамическая загрузка городов при изменении страны
- *   watchField(path.registrationAddress.country, async (country, ctx) => {
- *     if (country) {
- *       const cities = await fetchCities(country);
- *       ctx.updateComponentProps(path.registrationAddress.city, {
- *         options: cities
- *       });
- *     }
- *   });
+ * import { watchField, type BehaviorSchemaFn } from '@reformer/core/behaviors';
+ *
+ * interface InsuranceForm {
+ *   insuranceType: 'casco' | 'osago' | 'property' | '';
+ *   vehicleVin: string;
+ *   propertyType: string;
+ * }
+ *
+ * export const insuranceBehavior: BehaviorSchemaFn<InsuranceForm> = (path) => {
+ *   // ОДИН watchField на trigger-поле — несколько watcher'ов на одно поле = "Cycle detected"
+ *   watchField(
+ *     path.insuranceType,
+ *     (type, ctx) => {
+ *       const isVehicle = type === 'casco' || type === 'osago';
+ *       const isProperty = type === 'property';
+ *
+ *       // Guard — ставим только если состояние реально меняется
+ *       if (isVehicle) {
+ *         if (ctx.form.vehicleVin.disabled.value) ctx.form.vehicleVin.enable();
+ *       } else {
+ *         if (!ctx.form.vehicleVin.disabled.value) ctx.form.vehicleVin.disable();
+ *         if (ctx.form.vehicleVin.getValue() !== '') ctx.form.vehicleVin.setValue('');
+ *       }
+ *
+ *       if (isProperty) {
+ *         if (ctx.form.propertyType.disabled.value) ctx.form.propertyType.enable();
+ *       } else {
+ *         if (!ctx.form.propertyType.disabled.value) ctx.form.propertyType.disable();
+ *         if (ctx.form.propertyType.getValue() !== '') ctx.form.propertyType.setValue('');
+ *       }
+ *     },
+ *     { immediate: false }, // CRITICAL: предотвращает запуск во время инициализации
+ *   );
  * };
  * ```
+ *
+ * @see [docs/llms/22-cycle-detection.md](../../../../docs/llms/22-cycle-detection.md)
  */
 export declare function watchField<TForm, TField>(field: FieldPathNode<TForm, TField>, callback: (value: TField, ctx: BehaviorContext<TForm>) => void | Promise<void>, options?: WatchFieldOptions): void;

package/dist/core/behavior/compose-behavior.d.ts

@@ -1,15 +1,5 @@
-/**
- * Композиция behavior схем
- *
- * Предоставляет функции для переиспользования behavior схем:
- * - toBehaviorFieldPath: преобразование FieldPath во вложенный путь
- * - apply: применение схемы к полям
- * - applyWhen: условное применение схемы
- *
- * Аналог toFieldPath и applyWhen из validation API.
- */
-import type { FieldPath, FieldPathNode, FormFields, FormValue } from '../types';
-import type { BehaviorSchemaFn } from './types';
+import { FieldPath, FieldPathNode, FormFields, FormValue } from '../types';
+import { BehaviorSchemaFn } from './types';
 /**
  * Преобразовать FieldPath во вложенный путь для композиции behavior схем
  *

package/dist/core/behavior/index.d.ts

@@ -9,4 +9,3 @@ export * from './behaviors';
 export { apply, applyWhen, toBehaviorFieldPath } from './compose-behavior';
 export { BehaviorRegistry } from './behavior-registry';
 export { BehaviorContextImpl } from './behavior-context';
-export { createFieldPath } from './create-field-path';