@reformer/core 1.1.0 → 2.0.0-beta.10

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';

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

@@ -1,12 +1,6 @@
-/**
- * Типы и интерфейсы для Behavior Schema API
- *
- * @group Behaviors
- * @category Behavior Types
- */
 import { GroupNode } from '../nodes/group-node';
-import type { FieldPath } from '../types/field-path';
-import type { FormContext } from '../types/form-context';
+import { FieldPath } from '../types/field-path';
+import { FormContext } from '../types/form-context';
 /**
  * Тип функции behavior схемы
  * Принимает FieldPath и описывает поведение формы

package/dist/core/factories/node-factory.d.ts

@@ -1,40 +1,17 @@
+import { FormNode } from '../nodes/form-node';
 /**
- * NodeFactory - фабрика для создания узлов формы
+ * Фабрика для создания узлов формы.
  *
- * Инкапсулирует логику определения типа конфига и создания соответствующего узла.
- * Используется в GroupNode и ArrayNode для создания дочерних узлов.
- *
- * Паттерн Factory Method упрощает создание узлов и делает код более читаемым:
- * - Вместо if-else в GroupNode/ArrayNode
- * - Единая точка для создания узлов
- * - Легко добавлять новые типы узлов
+ * Определяет тип конфига и создаёт соответствующий узел (FieldNode, GroupNode, ArrayNode).
+ * Используется внутри `getReformerForm`/`group`/`array` — явно вызывать обычно не нужно.
  *
  * @example
  * ```typescript
- * const factory = new NodeFactory();
- *
- * // Создание FieldNode
- * const field = factory.createNode({ value: '', component: Input });
- *
- * // Создание GroupNode
- * const group = factory.createNode({
- *   email: { value: '', component: Input },
- *   password: { value: '', component: Input }
- * });
+ * import { NodeFactory } from '@reformer/core';
  *
- * // Создание ArrayNode
- * const array = factory.createNode({
- *   schema: { title: { value: '', component: Input } },
- *   initialItems: []
- * });
+ * const node = NodeFactory.create({ value: '' }); // → FieldNode<string>
  * ```
  */
-import type { FormNode } from '../nodes/form-node';
-/**
- * Фабрика для создания узлов формы
- *
- * Определяет тип конфига и создает соответствующий узел (FieldNode, GroupNode, ArrayNode)
- */
 export declare class NodeFactory {
     /**
      * Создает узел формы на основе конфигурации

package/dist/core/nodes/array-node.d.ts

@@ -1,18 +1,8 @@
-/**
- * ArrayNode - узел формы для работы с массивами
- *
- * Управляет массивом форм с поддержкой:
- * - Динамического добавления/удаления элементов
- * - Валидации всех элементов
- * - Реактивного состояния через signals
- *
- * @group Nodes
- */
-import type { ReadonlySignal } from '@preact/signals-core';
-import { FormNode, type SetValueOptions } from './form-node';
-import type { FieldStatus, ValidationError, FormFields } from '../types';
-import type { FormSchema } from '../types/deep-schema';
-import type { GroupNodeWithControls } from '../types/group-node-proxy';
+import { ReadonlySignal } from '@preact/signals-core';
+import { FormNode, SetValueOptions } from './form-node';
+import { FieldStatus, ValidationError, FormFields } from '../types';
+import { FormSchema } from '../types/deep-schema';
+import { FormProxy } from '../types/form-proxy';
 /**
  * ArrayNode - массив форм с реактивным состоянием
  *
@@ -39,6 +29,8 @@ export declare class ArrayNode<T extends FormFields> extends FormNode<T[]> {
      * Использует SubscriptionManager вместо массива для управления подписками
      */
     private disposers;
+    /** Array-level validation errors (e.g., "минимум 1 элемент") */
+    private readonly _arrayErrors;
     private validationSchemaFn?;
     private behaviorSchemaFn?;
     readonly value: ReadonlySignal<T[]>;
@@ -59,6 +51,9 @@ export declare class ArrayNode<T extends FormFields> extends FormNode<T[]> {
     /**
      * Удалить элемент по индексу
      * @param index - Индекс элемента для удаления
+     *
+     * @remarks
+     * Вызывает dispose() на удаляемом элементе для очистки подписок
      */
     removeAt(index: number): void;
     /**
@@ -69,14 +64,17 @@ export declare class ArrayNode<T extends FormFields> extends FormNode<T[]> {
     insert(index: number, initialValue?: Partial<T>): void;
     /**
      * Удалить все элементы массива
+     *
+     * @remarks
+     * Вызывает dispose() на всех элементах для очистки подписок
      */
     clear(): void;
     /**
      * Получить элемент по индексу
      * @param index - Индекс элемента
-     * @returns Типизированный GroupNode или undefined если индекс вне границ
+     * @returns Типизированный GroupNode proxy или undefined если индекс вне границ
      */
-    at(index: number): GroupNodeWithControls<T> | undefined;
+    at(index: number): FormProxy<T> | undefined;
     getValue(): T[];
     setValue(values: T[], options?: SetValueOptions): void;
     patchValue(values: (T | undefined)[]): void;
@@ -128,7 +126,29 @@ export declare class ArrayNode<T extends FormFields> extends FormNode<T[]> {
      */
     resetToInitial(): void;
     validate(): Promise<boolean>;
-    setErrors(_errors: ValidationError[]): void;
+    /**
+     * Установить array-level validation errors
+     *
+     * @param errors - Массив ошибок валидации уровня массива
+     *
+     * @example
+     * ```typescript
+     * arrayNode.setErrors([{
+     *   code: 'minItems',
+     *   message: 'Минимум 1 элемент обязателен',
+     * }]);
+     * ```
+     */
+    setErrors(errors: ValidationError[]): void;
+    /**
+     * Очистить все errors (array-level + item-level)
+     *
+     * @example
+     * ```typescript
+     * arrayNode.clearErrors();
+     * console.log(arrayNode.errors.value); // []
+     * ```
+     */
     clearErrors(): void;
     /**
      * Hook: вызывается после markAsTouched()
@@ -156,15 +176,15 @@ export declare class ArrayNode<T extends FormFields> extends FormNode<T[]> {
     protected onMarkAsPristine(): void;
     /**
      * Итерировать по элементам массива
-     * @param callback - Функция, вызываемая для каждого элемента с типизированным GroupNode
+     * @param callback - Функция, вызываемая для каждого элемента с типизированным GroupNode proxy
      */
-    forEach(callback: (item: GroupNodeWithControls<T>, index: number) => void): void;
+    forEach(callback: (item: FormProxy<T>, index: number) => void): void;
     /**
      * Маппинг элементов массива
-     * @param callback - Функция преобразования с типизированным GroupNode
+     * @param callback - Функция преобразования с типизированным GroupNode proxy
      * @returns Новый массив результатов
      */
-    map<R>(callback: (item: GroupNodeWithControls<T>, index: number) => R): R[];
+    map<R>(callback: (item: FormProxy<T>, index: number) => R): R[];
     /**
      * Создать новый элемент массива на основе схемы
      * @param initialValue - Начальные значения

package/dist/core/nodes/field-node.d.ts

@@ -1,15 +1,6 @@
-/**
- * FieldNode - узел поля формы
- *
- * Представляет одно поле формы с валидацией и состоянием
- * Наследует от FormNode и реализует все его абстрактные методы
- *
- * @group Nodes
- */
-import type { ReadonlySignal } from '@preact/signals-core';
-import { FormNode } from './form-node';
-import type { SetValueOptions } from './form-node';
-import type { FieldConfig, ValidationError } from '../types';
+import { ReadonlySignal } from '@preact/signals-core';
+import { FormNode, SetValueOptions } from './form-node';
+import { FieldConfig, FieldStatus, ValidationError } from '../types';
 /**
  * FieldNode - узел для отдельного поля формы
  *
@@ -31,12 +22,18 @@ import type { FieldConfig, ValidationError } from '../types';
 export declare class FieldNode<T> extends FormNode<T> {
     private _value;
     private _errors;
-    private _pending;
     private _componentProps;
+    /**
+     * State machine для управления статусом поля
+     * Централизует логику переходов между valid/invalid/pending/disabled
+     */
+    private readonly statusMachine;
     readonly value: ReadonlySignal<T>;
     readonly valid: ReadonlySignal<boolean>;
     readonly invalid: ReadonlySignal<boolean>;
     readonly pending: ReadonlySignal<boolean>;
+    readonly status: ReadonlySignal<FieldStatus>;
+    readonly disabled: ReadonlySignal<boolean>;
     readonly errors: ReadonlySignal<ValidationError[]>;
     readonly componentProps: ReadonlySignal<Record<string, any>>;
     /**
@@ -48,10 +45,14 @@ export declare class FieldNode<T> extends FormNode<T> {
     private asyncValidators;
     private updateOn;
     private initialValue;
-    private currentValidationId;
+    private currentAbortController?;
     private debounceMs;
     private validateDebounceTimer?;
-    private validateDebounceResolve?;
+    /**
+     * Pending debounced validation state
+     * Contains resolve function and AbortController for cancellation
+     */
+    private pendingValidation?;
     /**
      * Менеджер подписок для централизованного cleanup
      * Использует SubscriptionManager вместо массива для управления подписками
@@ -112,13 +113,23 @@ export declare class FieldNode<T> extends FormNode<T> {
      * ```
      */
     resetToInitial(): void;
+    /**
+     * Cancel any pending validation (debounced or running)
+     * @private
+     * @remarks
+     * Centralizes all cancellation logic:
+     * - Aborts pending debounced validation and resolves its promise
+     * - Clears debounce timer
+     * - Aborts currently running async validation
+     */
+    private cancelPendingValidation;
     /**
      * Запустить валидацию поля
      * @param options - опции валидации
      * @returns `Promise<boolean>` - true если поле валидно
      *
      * @remarks
-     * Метод защищен от race conditions через validationId.
+     * Метод защищен от race conditions через AbortController.
      * При быстром вводе только последняя валидация применяет результаты.
      *
      * @example
@@ -136,13 +147,12 @@ export declare class FieldNode<T> extends FormNode<T> {
     /**
      * Немедленная валидация без debounce
      * @private
+     * @param providedController - AbortController from debounced validate()
      * @remarks
-     * Защищена от race conditions:
-     * - Проверка validationId после синхронной валидации
-     * - Проверка перед установкой pending
-     * - Проверка после Promise.all
-     * - Проверка перед обработкой async результатов
-     * - Проверка перед очисткой errors
+     * Защищена от race conditions через AbortController:
+     * - Отменяет предыдущую валидацию при запуске новой (if no controller provided)
+     * - Передаёт AbortSignal в async валидаторы для отмены операций (например, fetch)
+     * - Проверяет signal.aborted в ключевых точках
      */
     private validateImmediate;
     setErrors(errors: ValidationError[]): void;
@@ -156,13 +166,13 @@ export declare class FieldNode<T> extends FormNode<T> {
     /**
      * Hook: вызывается после disable()
      *
-     * Для FieldNode: очищаем ошибки валидации
+     * Для FieldNode: синхронизируем statusMachine и очищаем ошибки
      */
     protected onDisable(): void;
     /**
      * Hook: вызывается после enable()
      *
-     * Для FieldNode: запускаем валидацию
+     * Для FieldNode: синхронизируем statusMachine и запускаем валидацию
      */
     protected onEnable(): void;
     /**
@@ -215,20 +225,28 @@ export declare class FieldNode<T> extends FormNode<T> {
      * Подписка на изменения значения поля
      * Автоматически отслеживает изменения через @preact/signals effect
      *
-     * @param callback - Функция, вызываемая при изменении значения
+     * @param callback - Функция, вызываемая при изменении значения.
+     *   Для async операций передается AbortSignal во втором параметре.
      * @returns Функция отписки для cleanup
      *
      * @example
      * ```typescript
+     * // Синхронный callback
      * const unsubscribe = form.email.watch((value) => {
      *   console.log('Email changed:', value);
      * });
      *
+     * // Асинхронный callback с поддержкой отмены
+     * const unsubscribe = form.email.watch(async (value, signal) => {
+     *   const result = await fetch('/api/validate', { signal });
+     *   // ...
+     * });
+     *
      * // Cleanup
      * useEffect(() => unsubscribe, []);
      * ```
      */
-    watch(callback: (value: T) => void | Promise<void>): () => void;
+    watch(callback: (value: T, signal: AbortSignal) => void | Promise<void>): () => void;
     /**
      * Вычисляемое значение из других полей
      * Автоматически обновляет текущее поле при изменении источников
@@ -256,6 +274,13 @@ export declare class FieldNode<T> extends FormNode<T> {
      * Очистить все ресурсы и таймеры
      * Должен вызываться при unmount компонента
      *
+     * @remarks
+     * Освобождает все ресурсы:
+     * - Отписывает все subscriptions через SubscriptionManager
+     * - Отменяет pending/running валидации через cancelPendingValidation()
+     *
+     * Использует try-finally для гарантированного cleanup даже при ошибках.
+     *
      * @example
      * ```typescript
      * useEffect(() => {