@reformer/core 10.2.0 → 11.0.0-beta.10

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

@@ -1,294 +0,0 @@
-import { ReadonlySignal } from '@preact/signals-core';
-import { FormNode, SetValueOptions } from './form-node';
-import { FieldConfig, FieldStatus, ValidationError } from '../types/index';
-/**
- * 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 _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, unknown>>;
-    /**
-     * Вычисляемое свойство: нужно ли показывать ошибку
-     * Ошибка показывается если поле невалидно И (touched ИЛИ dirty)
-     */
-    readonly shouldShowError: ReadonlySignal<boolean>;
-    private validators;
-    private asyncValidators;
-    private updateOn;
-    private initialValue;
-    private currentAbortController?;
-    private debounceMs;
-    private validateDebounceTimer?;
-    /**
-     * Pending debounced validation state
-     * Contains resolve function and AbortController for cancellation
-     */
-    private pendingValidation?;
-    /**
-     * Менеджер подписок для централизованного 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;
-    /**
-     * 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 через AbortController.
-     * При быстром вводе только последняя валидация применяет результаты.
-     *
-     * @example
-     * ```typescript
-     * // Обычная валидация
-     * await field.validate();
-     *
-     * // С debounce
-     * await field.validate({ debounce: 300 });
-     * ```
-     */
-    validate(options?: {
-        debounce?: number;
-    }): Promise<boolean>;
-    /**
-     * Немедленная валидация без debounce
-     * @private
-     * @param providedController - AbortController from debounced validate()
-     * @remarks
-     * Защищена от race conditions через AbortController:
-     * - Отменяет предыдущую валидацию при запуске новой (if no controller provided)
-     * - Передаёт AbortSignal в async валидаторы для отмены операций (например, fetch)
-     * - Проверяет signal.aborted в ключевых точках
-     */
-    private validateImmediate;
-    setErrors(errors: ValidationError[]): void;
-    clearErrors(): void;
-    /**
-     * Hook: вызывается после markAsTouched()
-     *
-     * Для FieldNode: если updateOn === 'blur', запускаем валидацию
-     */
-    protected onMarkAsTouched(): void;
-    /**
-     * Hook: вызывается после disable()
-     *
-     * Для FieldNode: синхронизируем statusMachine и очищаем ошибки
-     */
-    protected onDisable(): void;
-    /**
-     * Hook: вызывается после enable()
-     *
-     * Для FieldNode: синхронизируем statusMachine и запускаем валидацию
-     */
-    protected onEnable(): void;
-    /**
-     * Обновляет свойства компонента (например, опции для Select)
-     *
-     * @example
-     * ```typescript
-     * // Обновление опций для Select после загрузки справочников
-     * form.registrationAddress.city.updateComponentProps({
-     *   options: cities
-     * });
-     * ```
-     */
-    updateComponentProps(props: Partial<Record<string, unknown>>): void;
-    /**
-     * Динамически изменяет триггер валидации (updateOn)
-     * Полезно для адаптивной валидации - например, переключиться на instant feedback после первого submit
-     *
-     * @param updateOn - новый триггер валидации: 'change' | 'blur' | 'submit'
-     *
-     * @example
-     * ```typescript
-     * // Сценарий 1: Instant feedback после submit
-     * const form = createForm({
-     *   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 - Функция, вызываемая при изменении значения.
-     *   Для 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, signal: AbortSignal) => 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 компонента
-     *
-     * @remarks
-     * Освобождает все ресурсы:
-     * - Отписывает все subscriptions через SubscriptionManager
-     * - Отменяет pending/running валидации через cancelPendingValidation()
-     *
-     * Использует try-finally для гарантированного cleanup даже при ошибках.
-     *
-     * @example
-     * ```typescript
-     * useEffect(() => {
-     *   return () => {
-     *     field.dispose();
-     *   };
-     * }, []);
-     * ```
-     */
-    dispose(): void;
-}

package/dist/form/nodes/form-node.d.ts

@@ -1,340 +0,0 @@
-import { ReadonlySignal, Signal } from '@preact/signals-core';
-import { FieldStatus, ValidationError, ErrorFilterOptions } from '../types/index';
-/**
- * Опции для setValue
- * @group Nodes
- */
-export interface SetValueOptions {
-    /** Не вызывать событие изменения (не триггерить валидацию) */
-    emitEvent?: boolean;
-    /** Обновить только этот узел, не распространять на родителей */
-    onlySelf?: boolean;
-}
-/**
- * Абстрактный базовый класс для всех узлов формы.
- *
- * Все узлы (поля, группы, массивы) наследуют от этого класса и реализуют
- * единый интерфейс для работы с состоянием и валидацией.
- *
- * Template Method паттерн используется для управления состоянием:
- * общие signals (`_touched`, `_dirty`, `_status`) живут в базовом классе,
- * publi-методы (`markAsTouched`, `disable`, …) реализованы здесь, а protected
- * hooks (`onMarkAsTouched`, `onDisable`, …) переопределяются в наследниках.
- *
- * @group Nodes
- *
- * @example
- * ```typescript
- * // FormNode не используется напрямую — экземпляры приходят из getReformerForm.
- * import { getReformerForm, FormNode } from '@reformer/core';
- *
- * const form = getReformerForm({ email: '' });
- * form.email instanceof FormNode; // true
- * form.email.markAsTouched();
- * ```
- */
-export declare abstract class FormNode<T> {
-    /**
-     * Пользователь взаимодействовал с узлом (touched)
-     * Protected: наследники могут читать/изменять через методы
-     */
-    protected _touched: Signal<boolean>;
-    /**
-     * Значение узла было изменено (dirty)
-     * Protected: наследники могут читать/изменять через методы
-     */
-    protected _dirty: Signal<boolean>;
-    /**
-     * Текущий статус узла
-     * Protected: наследники могут читать/изменять через методы
-     */
-    protected _status: Signal<FieldStatus>;
-    /**
-     * Пользователь взаимодействовал с узлом (touched)
-     * Computed из _touched для предоставления readonly интерфейса
-     */
-    readonly touched: ReadonlySignal<boolean>;
-    /**
-     * Пользователь не взаимодействовал с узлом (untouched)
-     */
-    readonly untouched: ReadonlySignal<boolean>;
-    /**
-     * Значение узла было изменено (dirty)
-     * Computed из _dirty для предоставления readonly интерфейса
-     */
-    readonly dirty: ReadonlySignal<boolean>;
-    /**
-     * Значение узла не было изменено (pristine)
-     */
-    readonly pristine: ReadonlySignal<boolean>;
-    /**
-     * Текущий статус узла
-     * Computed из _status для предоставления readonly интерфейса
-     */
-    readonly status: ReadonlySignal<FieldStatus>;
-    /**
-     * Узел отключен (disabled)
-     */
-    readonly disabled: ReadonlySignal<boolean>;
-    /**
-     * Узел включен (enabled)
-     */
-    readonly enabled: ReadonlySignal<boolean>;
-    /**
-     * Текущее значение узла
-     * - Для FieldNode: значение поля
-     * - Для GroupNode: объект со значениями всех полей
-     * - Для ArrayNode: массив значений элементов
-     */
-    abstract readonly value: ReadonlySignal<T>;
-    /**
-     * Узел валиден (все валидаторы прошли успешно)
-     */
-    abstract readonly valid: ReadonlySignal<boolean>;
-    /**
-     * Узел невалиден (есть ошибки валидации)
-     */
-    abstract readonly invalid: ReadonlySignal<boolean>;
-    /**
-     * Выполняется асинхронная валидация
-     */
-    abstract readonly pending: ReadonlySignal<boolean>;
-    /**
-     * Массив ошибок валидации
-     */
-    abstract readonly errors: ReadonlySignal<ValidationError[]>;
-    /**
-     * Получить значение узла (non-reactive)
-     * Использует .peek() для получения значения без создания зависимости
-     */
-    abstract getValue(): T;
-    /**
-     * Установить значение узла
-     * @param value - новое значение
-     * @param options - опции установки значения
-     */
-    abstract setValue(value: T, options?: SetValueOptions): void;
-    /**
-     * Частично обновить значение узла
-     * Для FieldNode: работает как setValue
-     * Для GroupNode: обновляет только указанные поля
-     * Для ArrayNode: обновляет только указанные элементы
-     *
-     * @param value - частичное значение для обновления
-     */
-    abstract patchValue(value: Partial<T>): void;
-    /**
-     * Сбросить узел к начальному состоянию
-     * @param value - опциональное новое начальное значение
-     */
-    abstract reset(value?: T): void;
-    /**
-     * Запустить валидацию узла
-     * @returns `Promise<boolean>` - true если валидация успешна
-     */
-    abstract validate(): Promise<boolean>;
-    /**
-     * Установить ошибки валидации извне
-     * @param errors - массив ошибок
-     */
-    abstract setErrors(errors: ValidationError[]): void;
-    /**
-     * Очистить ошибки валидации
-     */
-    abstract clearErrors(): void;
-    /**
-     * Получить ошибки валидации с фильтрацией
-     *
-     * Позволяет фильтровать ошибки по различным критериям:
-     * - По коду ошибки
-     * - По сообщению (частичное совпадение)
-     * - По параметрам
-     * - Через кастомный предикат
-     *
-     * Без параметров возвращает все ошибки (эквивалент errors.value)
-     *
-     * @param options - Опции фильтрации ошибок
-     * @returns Отфильтрованный массив ошибок валидации
-     *
-     * @example
-     * ```typescript
-     * // Все ошибки
-     * const allErrors = form.getErrors();
-     *
-     * // Ошибки с конкретным кодом
-     * const requiredErrors = form.getErrors({ code: 'required' });
-     *
-     * // Ошибки с несколькими кодами
-     * const errors = form.getErrors({ code: ['required', 'email'] });
-     *
-     * // Ошибки по сообщению
-     * const passwordErrors = form.getErrors({ message: 'Password' });
-     *
-     * // Ошибки по параметрам
-     * const minLengthErrors = form.getErrors({
-     *   params: { minLength: 8 }
-     * });
-     *
-     * // Кастомная фильтрация
-     * const customErrors = form.getErrors({
-     *   predicate: (err) => err.code.startsWith('custom_')
-     * });
-     * ```
-     */
-    getErrors(options?: ErrorFilterOptions): ValidationError[];
-    /**
-     * Отметить узел как touched (пользователь взаимодействовал)
-     *
-     * Template Method: обновляет signal в базовом классе,
-     * вызывает hook для кастомной логики в наследниках
-     */
-    markAsTouched(): void;
-    /**
-     * Отметить узел как untouched
-     *
-     * Template Method: обновляет signal в базовом классе,
-     * вызывает hook для кастомной логики в наследниках
-     */
-    markAsUntouched(): void;
-    /**
-     * Отметить узел как dirty (значение изменено)
-     *
-     * Template Method: обновляет signal в базовом классе,
-     * вызывает hook для кастомной логики в наследниках
-     */
-    markAsDirty(): void;
-    /**
-     * Отметить узел как pristine (значение не изменено)
-     *
-     * Template Method: обновляет signal в базовом классе,
-     * вызывает hook для кастомной логики в наследниках
-     */
-    markAsPristine(): void;
-    /**
-     * Пометить все поля (включая вложенные) как touched
-     * Алиас для markAsTouched(), но более явно показывает намерение
-     * пометить ВСЕ поля рекурсивно
-     *
-     * Полезно для:
-     * - Показа всех ошибок валидации перед submit
-     * - Принудительного отображения ошибок при нажатии "Validate All"
-     * - Отображения невалидных полей в wizard/step form
-     *
-     * @example
-     * ```typescript
-     * // Показать все ошибки перед submit
-     * form.touchAll();
-     * const isValid = await form.validate();
-     * if (!isValid) {
-     *   // Все ошибки теперь видны пользователю
-     * }
-     *
-     * // Или использовать submit() который уже вызывает touchAll
-     * await form.submit(async (values) => {
-     *   await api.save(values);
-     * });
-     * ```
-     */
-    touchAll(): void;
-    /**
-     * Отключить узел
-     *
-     * Template Method: обновляет статус в базовом классе,
-     * вызывает hook для кастомной логики в наследниках
-     *
-     * Отключенные узлы не проходят валидацию и не включаются в getValue()
-     */
-    disable(): void;
-    /**
-     * Включить узел
-     *
-     * Template Method: обновляет статус в базовом классе,
-     * вызывает hook для кастомной логики в наследниках
-     */
-    enable(): void;
-    /**
-     * Очистить все ресурсы узла
-     * Должен вызываться при unmount компонента для предотвращения memory leaks
-     *
-     * @example
-     * ```typescript
-     * // React component
-     * useEffect(() => {
-     *   return () => {
-     *     form.dispose(); // Cleanup при unmount
-     *   };
-     * }, []);
-     * ```
-     */
-    dispose?(): void;
-    /**
-     * Hook: вызывается после markAsTouched()
-     *
-     * Переопределите в наследниках для дополнительной логики:
-     * - GroupNode: пометить все дочерние узлы как touched
-     * - ArrayNode: пометить все элементы массива как touched
-     * - FieldNode: пустая реализация (нет дочерних узлов)
-     *
-     * @example
-     * ```typescript
-     * // GroupNode
-     * protected onMarkAsTouched(): void {
-     *   this.fields.forEach(field => field.markAsTouched());
-     * }
-     * ```
-     */
-    protected onMarkAsTouched(): void;
-    /**
-     * Hook: вызывается после markAsUntouched()
-     *
-     * Переопределите в наследниках для дополнительной логики:
-     * - GroupNode: пометить все дочерние узлы как untouched
-     * - ArrayNode: пометить все элементы массива как untouched
-     * - FieldNode: пустая реализация (нет дочерних узлов)
-     */
-    protected onMarkAsUntouched(): void;
-    /**
-     * Hook: вызывается после markAsDirty()
-     *
-     * Переопределите в наследниках для дополнительной логики:
-     * - GroupNode: может обновить родительскую форму
-     * - ArrayNode: может обновить родительскую форму
-     * - FieldNode: пустая реализация
-     */
-    protected onMarkAsDirty(): void;
-    /**
-     * Hook: вызывается после markAsPristine()
-     *
-     * Переопределите в наследниках для дополнительной логики:
-     * - GroupNode: пометить все дочерние узлы как pristine
-     * - ArrayNode: пометить все элементы массива как pristine
-     * - FieldNode: пустая реализация
-     */
-    protected onMarkAsPristine(): void;
-    /**
-     * Hook: вызывается после disable()
-     *
-     * Переопределите в наследниках для дополнительной логики:
-     * - GroupNode: отключить все дочерние узлы
-     * - ArrayNode: отключить все элементы массива
-     * - FieldNode: очистить ошибки валидации
-     *
-     * @example
-     * ```typescript
-     * // GroupNode
-     * protected onDisable(): void {
-     *   this.fields.forEach(field => field.disable());
-     * }
-     * ```
-     */
-    protected onDisable(): void;
-    /**
-     * Hook: вызывается после enable()
-     *
-     * Переопределите в наследниках для дополнительной логики:
-     * - GroupNode: включить все дочерние узлы
-     * - ArrayNode: включить все элементы массива
-     * - FieldNode: пустая реализация
-     */
-    protected onEnable(): void;
-}