@reformer/core 1.0.0-beta.1

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

@@ -0,0 +1,340 @@
+import { ReadonlySignal, Signal } from '@preact/signals-core';
+import { FieldStatus, ValidationError, ErrorFilterOptions } from '../types';
+/**
+ * Опции для 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;
+}

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

@@ -0,0 +1,319 @@
+import { ReadonlySignal } from '@preact/signals-core';
+import { FormNode, SetValueOptions } from './form-node';
+import { ValidationError, FieldStatus, ValidationSchemaFn, ValidatorRegistration, FormSchema, GroupNodeConfig, FormValue } from '../types';
+import { FormProxy } from '../types/form-proxy';
+import { BehaviorSchemaFn } from '../behavior/types';
+import { SubmitOptions, SubmitResult } from '../utils/form-submitter';
+/**
+ * GroupNode - узел для группы полей
+ *
+ * Поддерживает два API:
+ * 1. Старый API (только schema) - обратная совместимость
+ * 2. Новый API (config с form, behavior, validation) - автоматическое применение схем
+ *
+ * @group Nodes
+ *
+ * @example
+ * ```typescript
+ * // 1. Старый способ (обратная совместимость)
+ * const simpleForm = new GroupNode({
+ *   email: { value: '', component: Input },
+ *   password: { value: '', component: Input },
+ * });
+ *
+ * // 2. Новый способ (с behavior и validation схемами)
+ * const fullForm = new GroupNode({
+ *   form: {
+ *     email: { value: '', component: Input },
+ *     password: { value: '', component: Input },
+ *   },
+ *   behavior: (path) => {
+ *     computeFrom(path.email, [path.email], (values) => values[0]?.trim());
+ *   },
+ *   validation: (path) => {
+ *     required(path.email, { message: 'Email обязателен' });
+ *     email(path.email);
+ *     required(path.password);
+ *     minLength(path.password, 8);
+ *   },
+ * });
+ *
+ * // Прямой доступ к полям через Proxy
+ * fullForm.email.setValue('test@mail.com');
+ * await fullForm.validate();
+ * console.log(fullForm.valid.value); // true
+ * ```
+ */
+export declare class GroupNode<T> extends FormNode<T> {
+    id: `${string}-${string}-${string}-${string}-${string}`;
+    /**
+     * Коллекция полей формы (упрощённый Map вместо FieldRegistry)
+     */
+    private readonly _fields;
+    /**
+     * Менеджер подписок для централизованного cleanup
+     */
+    private disposers;
+    /**
+     * Ссылка на Proxy-инстанс для использования в BehaviorContext
+     */
+    private _proxyInstance?;
+    /**
+     * Навигатор для работы с путями к полям
+     */
+    private readonly pathNavigator;
+    /**
+     * Фабрика для создания узлов формы
+     */
+    private readonly nodeFactory;
+    /**
+     * Реестр валидаторов для этой формы
+     * Может быть инжектирован через config._validationRegistry для тестирования
+     */
+    private readonly validationRegistry;
+    /**
+     * Реестр behaviors для этой формы
+     * Может быть инжектирован через config._behaviorRegistry для тестирования
+     */
+    private readonly behaviorRegistry;
+    /**
+     * Аппликатор для применения валидаторов к форме
+     */
+    private readonly validationApplicator;
+    /** Управление отправкой формы */
+    private readonly formSubmitter;
+    /** Флаг disabled состояния */
+    private readonly _disabled;
+    /** Form-level validation errors */
+    private readonly _formErrors;
+    readonly value: ReadonlySignal<T>;
+    readonly valid: ReadonlySignal<boolean>;
+    readonly invalid: ReadonlySignal<boolean>;
+    readonly touched: ReadonlySignal<boolean>;
+    readonly dirty: ReadonlySignal<boolean>;
+    readonly pending: ReadonlySignal<boolean>;
+    readonly errors: ReadonlySignal<ValidationError[]>;
+    readonly status: ReadonlySignal<FieldStatus>;
+    readonly submitting: ReadonlySignal<boolean>;
+    /**
+     * Создать GroupNode только со схемой формы (обратная совместимость)
+     */
+    constructor(schema: FormSchema<T>);
+    /**
+     * Создать GroupNode с полной конфигурацией (form, behavior, validation)
+     */
+    constructor(config: GroupNodeConfig<T>);
+    /**
+     * Создать Proxy для типобезопасного доступа к полям
+     * @see buildFormProxy
+     */
+    private buildProxy;
+    getValue(): T;
+    setValue(value: T, options?: SetValueOptions): void;
+    patchValue(value: Partial<T>): void;
+    /**
+     * Сбросить форму к указанным значениям (или к initialValues)
+     *
+     * @param value - опциональный объект со значениями для сброса
+     *
+     * @remarks
+     * Рекурсивно вызывает reset() для всех полей формы
+     *
+     * @example
+     * ```typescript
+     * // Сброс к initialValues
+     * form.reset();
+     *
+     * // Сброс к новым значениям
+     * form.reset({ email: 'new@mail.com', password: '' });
+     * ```
+     */
+    reset(value?: T): void;
+    /**
+     * Сбросить форму к исходным значениям (initialValues)
+     */
+    resetToInitial(): void;
+    validate(): Promise<boolean>;
+    /**
+     * Установить form-level validation errors
+     */
+    setErrors(errors: ValidationError[]): void;
+    /**
+     * Очистить все errors (form-level + field-level)
+     */
+    clearErrors(): void;
+    /**
+     * Получить поле по ключу
+     */
+    getField<K extends keyof T>(key: K): FormNode<T[K]> | undefined;
+    /**
+     * Получить Map всех полей формы (для совместимости)
+     */
+    get fields(): Map<keyof T, FormNode<FormValue>>;
+    /**
+     * Получить Proxy-инстанс для прямого доступа к полям
+     *
+     * Proxy позволяет обращаться к полям формы напрямую через точечную нотацию:
+     * - form.email вместо form.fields.get('email')
+     * - form.address.city вместо form.fields.get('address').fields.get('city')
+     *
+     * Используется в:
+     * - BehaviorApplicator для доступа к полям в behavior functions
+     * - ValidationApplicator для доступа к форме в tree validators
+     *
+     * @returns Proxy-инстанс с типобезопасным доступом к полям или сама форма, если proxy не доступен
+     *
+     * @example
+     * ```typescript
+     * const form = new GroupNode({
+     *   controls: {
+     *     email: new FieldNode({ value: '' }),
+     *     name: new FieldNode({ value: '' })
+     *   }
+     * });
+     *
+     * const proxy = form.getProxy();
+     * console.log(proxy.email.value); // Прямой доступ к полю
+     * ```
+     */
+    getProxy(): FormProxy<T>;
+    /**
+     * Получить все поля формы как итератор
+     */
+    getAllFields(): IterableIterator<FormNode<FormValue>>;
+    protected onMarkAsTouched(): void;
+    protected onMarkAsUntouched(): void;
+    protected onMarkAsDirty(): void;
+    protected onMarkAsPristine(): void;
+    /**
+     * Отправить форму
+     *
+     * @param onSubmit - Callback для отправки данных
+     * @param options - Опции submit (skipValidation, skipTouch)
+     * @returns Результат от onSubmit или null если валидация не пройдена
+     */
+    submit<R>(onSubmit: (values: T) => Promise<R> | R, options?: SubmitOptions): Promise<R | null>;
+    /**
+     * Отправить форму с расширенным результатом
+     *
+     * @param onSubmit - Callback для отправки данных
+     * @param options - Опции submit
+     * @returns Объект SubmitResult с данными, статусом и возможной ошибкой
+     */
+    submitWithResult<R>(onSubmit: (values: T) => Promise<R> | R, options?: SubmitOptions): Promise<SubmitResult<R>>;
+    /**
+     * Применить validation schema к форме
+     *
+     * Использует локальный реестр валидаторов (this.validationRegistry)
+     * вместо глобального Singleton для изоляции форм друг от друга.
+     */
+    applyValidationSchema(schemaFn: ValidationSchemaFn<T>): void;
+    /**
+     * Применить behavior schema к форме
+     * @returns Функция cleanup для отписки от всех behaviors
+     */
+    applyBehaviorSchema(schemaFn: BehaviorSchemaFn<T>): () => void;
+    /**
+     * Получить вложенное поле по пути
+     *
+     * Поддерживаемые форматы путей:
+     * - Simple: "email" - получить поле верхнего уровня
+     * - Nested: "address.city" - получить вложенное поле
+     * - Array index: "items[0]" - получить элемент массива по индексу
+     * - Combined: "items[0].name" - получить поле элемента массива
+     *
+     * @param path - Путь к полю
+     * @returns FormNode если найдено, undefined если путь не существует
+     *
+     * @example
+     * ```typescript
+     * const form = new GroupNode({
+     *   email: { value: '', component: Input },
+     *   address: {
+     *     city: { value: '', component: Input }
+     *   },
+     *   items: [{ name: { value: '', component: Input } }]
+     * });
+     *
+     * form.getFieldByPath('email');           // FieldNode
+     * form.getFieldByPath('address.city');    // FieldNode
+     * form.getFieldByPath('items[0]');        // GroupNode
+     * form.getFieldByPath('items[0].name');   // FieldNode
+     * form.getFieldByPath('invalid.path');    // undefined
+     * ```
+     */
+    getFieldByPath(path: string): FormNode<FormValue> | undefined;
+    /**
+     * Применить contextual валидаторы к полям
+     *
+     * ✅ РЕФАКТОРИНГ: Делегирование ValidationApplicator (SRP)
+     *
+     * Логика применения валидаторов извлечена в ValidationApplicator для:
+     * - Соблюдения Single Responsibility Principle
+     * - Уменьшения размера GroupNode (~120 строк)
+     * - Улучшения тестируемости
+     *
+     * @param validators Зарегистрированные валидаторы
+     */
+    applyContextualValidators(validators: ValidatorRegistration[]): Promise<void>;
+    /**
+     * Создать узел на основе конфигурации
+     *
+     * ✅ РЕФАКТОРИНГ: Полное делегирование NodeFactory
+     *
+     * NodeFactory теперь обрабатывает:
+     * - Массивы [schema, ...items]
+     * - FieldConfig
+     * - GroupConfig
+     * - ArrayConfig
+     *
+     * @param config Конфигурация узла
+     * @returns Созданный узел формы
+     * @private
+     */
+    private createNode;
+    /**
+     * Связывает два поля: при изменении source автоматически обновляется target
+     */
+    linkFields<K1 extends keyof T, K2 extends keyof T>(sourceKey: K1, targetKey: K2, transform?: (value: T[K1]) => T[K2]): () => void;
+    /**
+     * Подписка на изменения вложенного поля по строковому пути
+     * Поддерживает вложенные пути типа "address.city"
+     *
+     * @param fieldPath - Строковый путь к полю (например, "address.city")
+     * @param callback - Функция, вызываемая при изменении поля
+     * @returns Функция отписки для cleanup
+     *
+     * @example
+     * ```typescript
+     * // Подписка на изменение страны для загрузки городов
+     * const dispose = form.watchField(
+     *   'registrationAddress.country',
+     *   async (countryCode) => {
+     *     if (countryCode) {
+     *       const cities = await fetchCitiesByCountry(countryCode);
+     *       form.registrationAddress.city.updateComponentProps({
+     *         options: cities
+     *       });
+     *     }
+     *   }
+     * );
+     *
+     * // Cleanup
+     * useEffect(() => dispose, []);
+     * ```
+     */
+    watchField<K extends keyof T>(fieldPath: K extends string ? K : string, callback: (value: T[K]) => void | Promise<void>): () => void;
+    /**
+     * Hook: вызывается после disable()
+     */
+    protected onDisable(): void;
+    /**
+     * Hook: вызывается после enable()
+     */
+    protected onEnable(): void;
+    /**
+     * Очистить все ресурсы узла
+     */
+    dispose(): void;
+}