@reformer/core 1.0.0-beta.3

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

@@ -0,0 +1,269 @@
+/**
+ * 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';
+/**
+ * FieldNode - узел для отдельного поля формы
+ *
+ * @group Nodes
+ *
+ * @example
+ * ```typescript
+ * const field = new FieldNode({
+ *   value: '',
+ *   component: Input,
+ *   validators: [required, email],
+ * });
+ *
+ * field.setValue('test@mail.com');
+ * await field.validate();
+ * console.log(field.valid.value); // true
+ * ```
+ */
+export declare class FieldNode<T> extends FormNode<T> {
+    private _value;
+    private _errors;
+    private _pending;
+    private _componentProps;
+    readonly value: ReadonlySignal<T>;
+    readonly valid: ReadonlySignal<boolean>;
+    readonly invalid: ReadonlySignal<boolean>;
+    readonly pending: ReadonlySignal<boolean>;
+    readonly errors: ReadonlySignal<ValidationError[]>;
+    readonly componentProps: ReadonlySignal<Record<string, any>>;
+    /**
+     * Вычисляемое свойство: нужно ли показывать ошибку
+     * Ошибка показывается если поле невалидно И (touched ИЛИ dirty)
+     */
+    readonly shouldShowError: ReadonlySignal<boolean>;
+    private validators;
+    private asyncValidators;
+    private updateOn;
+    private initialValue;
+    private currentValidationId;
+    private debounceMs;
+    private validateDebounceTimer?;
+    private validateDebounceResolve?;
+    /**
+     * Менеджер подписок для централизованного cleanup
+     * Использует SubscriptionManager вместо массива для управления подписками
+     */
+    private disposers;
+    readonly component: FieldConfig<T>['component'];
+    constructor(config: FieldConfig<T>);
+    getValue(): T;
+    setValue(value: T, options?: SetValueOptions): void;
+    patchValue(value: Partial<T>): void;
+    /**
+     * Сбросить поле к указанному значению (или к initialValue)
+     *
+     * @param value - опциональное значение для сброса. Если не указано, используется initialValue
+     *
+     * @remarks
+     * Этот метод:
+     * - Устанавливает значение в value или initialValue
+     * - Очищает ошибки валидации
+     * - Сбрасывает touched/dirty флаги
+     * - Устанавливает статус в 'valid'
+     *
+     * Если вам нужно сбросить к исходному значению, используйте resetToInitial()
+     *
+     * @example
+     * ```typescript
+     * // Сброс к initialValue
+     * field.reset();
+     *
+     * // Сброс к новому значению
+     * field.reset('new value');
+     * ```
+     */
+    reset(value?: T): void;
+    /**
+     * Сбросить поле к исходному значению (initialValue)
+     *
+     * @remarks
+     * Алиас для reset() без параметров, но более явный:
+     * - resetToInitial() - явно показывает намерение вернуться к начальному значению
+     * - reset() - может принимать новое значение
+     *
+     * Полезно когда:
+     * - Пользователь нажал "Cancel" - вернуть форму в исходное состояние
+     * - Форма была изменена через reset(newValue), но нужно вернуться к самому началу
+     * - Явное намерение показать "отмену всех изменений"
+     *
+     * @example
+     * ```typescript
+     * const field = new FieldNode({ value: 'initial', component: Input });
+     *
+     * field.setValue('changed');
+     * field.reset('temp value');
+     * console.log(field.value.value); // 'temp value'
+     *
+     * field.resetToInitial();
+     * console.log(field.value.value); // 'initial'
+     * ```
+     */
+    resetToInitial(): void;
+    /**
+     * Запустить валидацию поля
+     * @param options - опции валидации
+     * @returns `Promise<boolean>` - true если поле валидно
+     *
+     * @remarks
+     * Метод защищен от race conditions через validationId.
+     * При быстром вводе только последняя валидация применяет результаты.
+     *
+     * @example
+     * ```typescript
+     * // Обычная валидация
+     * await field.validate();
+     *
+     * // С debounce
+     * await field.validate({ debounce: 300 });
+     * ```
+     */
+    validate(options?: {
+        debounce?: number;
+    }): Promise<boolean>;
+    /**
+     * Немедленная валидация без debounce
+     * @private
+     * @remarks
+     * Защищена от race conditions:
+     * - Проверка validationId после синхронной валидации
+     * - Проверка перед установкой pending
+     * - Проверка после Promise.all
+     * - Проверка перед обработкой async результатов
+     * - Проверка перед очисткой errors
+     */
+    private validateImmediate;
+    setErrors(errors: ValidationError[]): void;
+    clearErrors(): void;
+    /**
+     * Hook: вызывается после markAsTouched()
+     *
+     * Для FieldNode: если updateOn === 'blur', запускаем валидацию
+     */
+    protected onMarkAsTouched(): void;
+    /**
+     * Hook: вызывается после disable()
+     *
+     * Для FieldNode: очищаем ошибки валидации
+     */
+    protected onDisable(): void;
+    /**
+     * Hook: вызывается после enable()
+     *
+     * Для FieldNode: запускаем валидацию
+     */
+    protected onEnable(): void;
+    /**
+     * Обновляет свойства компонента (например, опции для Select)
+     *
+     * @example
+     * ```typescript
+     * // Обновление опций для Select после загрузки справочников
+     * form.registrationAddress.city.updateComponentProps({
+     *   options: cities
+     * });
+     * ```
+     */
+    updateComponentProps(props: Partial<Record<string, any>>): void;
+    /**
+     * Динамически изменяет триггер валидации (updateOn)
+     * Полезно для адаптивной валидации - например, переключиться на instant feedback после первого submit
+     *
+     * @param updateOn - новый триггер валидации: 'change' | 'blur' | 'submit'
+     *
+     * @example
+     * ```typescript
+     * // Сценарий 1: Instant feedback после submit
+     * const form = new GroupNode({
+     *   email: {
+     *     value: '',
+     *     component: Input,
+     *     updateOn: 'submit', // Изначально валидация только при submit
+     *     validators: [required, email]
+     *   }
+     * });
+     *
+     * await form.submit(async (values) => {
+     *   // После submit переключаем на instant feedback
+     *   form.email.setUpdateOn('change');
+     *   await api.save(values);
+     * });
+     *
+     * // Теперь валидация происходит при каждом изменении
+     *
+     * // Сценарий 2: Прогрессивное улучшение
+     * form.email.setUpdateOn('blur');  // Сначала только при blur
+     * // ... пользователь начинает вводить ...
+     * form.email.setUpdateOn('change'); // Переключаем на change для real-time feedback
+     * ```
+     */
+    setUpdateOn(updateOn: 'change' | 'blur' | 'submit'): void;
+    getUpdateOn(): 'change' | 'blur' | 'submit';
+    /**
+     * Подписка на изменения значения поля
+     * Автоматически отслеживает изменения через @preact/signals effect
+     *
+     * @param callback - Функция, вызываемая при изменении значения
+     * @returns Функция отписки для cleanup
+     *
+     * @example
+     * ```typescript
+     * const unsubscribe = form.email.watch((value) => {
+     *   console.log('Email changed:', value);
+     * });
+     *
+     * // Cleanup
+     * useEffect(() => unsubscribe, []);
+     * ```
+     */
+    watch(callback: (value: T) => void | Promise<void>): () => void;
+    /**
+     * Вычисляемое значение из других полей
+     * Автоматически обновляет текущее поле при изменении источников
+     *
+     * @param sources - Массив ReadonlySignal для отслеживания
+     * @param computeFn - Функция вычисления нового значения
+     * @returns Функция отписки для cleanup
+     *
+     * @example
+     * ```typescript
+     * // Автоматический расчет первоначального взноса (20% от стоимости)
+     * const dispose = form.initialPayment.computeFrom(
+     *   [form.propertyValue.value],
+     *   (propertyValue) => {
+     *     return propertyValue ? propertyValue * 0.2 : null;
+     *   }
+     * );
+     *
+     * // Cleanup
+     * useEffect(() => dispose, []);
+     * ```
+     */
+    computeFrom<TSource extends readonly unknown[]>(sources: ReadonlySignal<TSource[number]>[], computeFn: (...values: TSource) => T): () => void;
+    /**
+     * Очистить все ресурсы и таймеры
+     * Должен вызываться при unmount компонента
+     *
+     * @example
+     * ```typescript
+     * useEffect(() => {
+     *   return () => {
+     *     field.dispose();
+     *   };
+     * }, []);
+     * ```
+     */
+    dispose(): void;
+}