@reformer/core 1.0.0-beta.3

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

@@ -0,0 +1,494 @@
+/**
+ * GroupNode - узел группы полей формы
+ *
+ * Представляет группу полей (объект), где каждое поле может быть:
+ * - FieldNode (простое поле)
+ * - GroupNode (вложенная группа)
+ * - ArrayNode (массив форм)
+ *
+ * Наследует от FormNode и реализует все его абстрактные методы
+ *
+ * @group Nodes
+ */
+import type { ReadonlySignal } from '@preact/signals-core';
+import { FormNode, type SetValueOptions } from './form-node';
+import type { ValidationError, FieldStatus, ValidationSchemaFn, ValidatorRegistration, FormSchema, GroupNodeConfig, FormValue } from '../types';
+import type { GroupNodeWithControls } from '../types/group-node-proxy';
+import type { BehaviorSchemaFn } from '../behavior/types';
+import { FieldRegistry } from './group-node/field-registry';
+/**
+ * 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;
+    /**
+     * Реестр полей формы
+     * Использует FieldRegistry для инкапсуляции логики управления коллекцией полей
+     */
+    private fieldRegistry;
+    /**
+     * Строитель Proxy для типобезопасного доступа к полям
+     * Использует ProxyBuilder для создания Proxy с расширенной функциональностью
+     */
+    private proxyBuilder;
+    /**
+     * Менеджер состояния формы
+     * Инкапсулирует всю логику создания и управления сигналами состояния
+     * Извлечен из GroupNode для соблюдения SRP
+     */
+    private stateManager;
+    /**
+     * Менеджер подписок для централизованного cleanup
+     * Использует SubscriptionManager вместо массива для управления подписками
+     */
+    private disposers;
+    /**
+     * Ссылка на Proxy-инстанс для использования в BehaviorContext
+     * Устанавливается в конструкторе до применения behavior schema
+     */
+    private _proxyInstance?;
+    /**
+     * Навигатор для работы с путями к полям
+     * Использует композицию вместо дублирования логики парсинга путей
+     */
+    private readonly pathNavigator;
+    /**
+     * Фабрика для создания узлов формы
+     * Использует композицию для централизованного создания FieldNode/GroupNode/ArrayNode
+     */
+    private readonly nodeFactory;
+    /**
+     * Реестр валидаторов для этой формы
+     * Использует композицию вместо глобального Singleton
+     * Обеспечивает полную изоляцию форм друг от друга
+     */
+    private readonly validationRegistry;
+    /**
+     * Реестр behaviors для этой формы
+     * Использует композицию вместо глобального Singleton
+     * Обеспечивает полную изоляцию форм друг от друга
+     */
+    private readonly behaviorRegistry;
+    /**
+     * Аппликатор для применения валидаторов к форме
+     * Извлечен из GroupNode для соблюдения SRP
+     * Использует композицию для управления процессом валидации
+     */
+    private readonly validationApplicator;
+    /**
+     * Аппликатор для применения behavior схемы к форме
+     * Извлечен из GroupNode для соблюдения SRP
+     * Использует композицию для управления процессом применения behaviors
+     */
+    private readonly behaviorApplicator;
+    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>);
+    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)
+     *
+     * @remarks
+     * Рекурсивно вызывает resetToInitial() для всех полей формы.
+     * Более явный способ сброса к начальным значениям по сравнению с reset()
+     *
+     * Полезно когда:
+     * - Пользователь нажал "Cancel" - полная отмена изменений
+     * - Форма была изменена через reset(newValues), но нужно вернуться к самому началу
+     * - Явное намерение показать "отмена всех изменений"
+     *
+     * @example
+     * ```typescript
+     * const form = new GroupNode({
+     *   email: { value: 'initial@mail.com', component: Input },
+     *   name: { value: 'John', component: Input }
+     * });
+     *
+     * form.email.setValue('changed@mail.com');
+     * form.reset({ email: 'temp@mail.com', name: 'Jane' });
+     * console.log(form.getValue()); // { email: 'temp@mail.com', name: 'Jane' }
+     *
+     * form.resetToInitial();
+     * console.log(form.getValue()); // { email: 'initial@mail.com', name: 'John' }
+     * ```
+     */
+    resetToInitial(): void;
+    validate(): Promise<boolean>;
+    /**
+     * Установить form-level validation errors
+     * Используется для server-side validation или кросс-полевых ошибок
+     *
+     * @param errors - массив ошибок уровня формы
+     *
+     * @example
+     * ```typescript
+     * // Server-side validation после submit
+     * try {
+     *   await api.createUser(form.getValue());
+     * } catch (error) {
+     *   form.setErrors([
+     *     { code: 'duplicate_email', message: 'Email уже используется' }
+     *   ]);
+     * }
+     * ```
+     */
+    setErrors(errors: ValidationError[]): void;
+    /**
+     * Очистить все errors (form-level + field-level)
+     */
+    clearErrors(): void;
+    /**
+     * Получить поле по ключу
+     *
+     * Публичный метод для доступа к полю из fieldRegistry
+     *
+     * @param key - Ключ поля
+     * @returns FormNode или undefined, если поле не найдено
+     *
+     * @example
+     * ```typescript
+     * const emailField = form.getField('email');
+     * if (emailField) {
+     *   console.log(emailField.value.value);
+     * }
+     * ```
+     */
+    getField<K extends keyof T>(key: K): FormNode<T[K]> | undefined;
+    /**
+     * Получить Map всех полей формы
+     *
+     * Используется в FieldPathNavigator для навигации по полям
+     *
+     * @returns Map полей формы
+     */
+    get fields(): FieldRegistry<T>;
+    /**
+     * Получить 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(): GroupNodeWithControls<T>;
+    /**
+     * Получить все поля формы как итератор
+     *
+     * Предоставляет доступ к внутренним полям для валидации и других операций
+     *
+     * @returns Итератор по всем полям формы
+     *
+     * @example
+     * ```typescript
+     * // Валидация всех полей
+     * await Promise.all(
+     *   Array.from(form.getAllFields()).map(field => field.validate())
+     * );
+     * ```
+     */
+    getAllFields(): IterableIterator<FormNode<FormValue>>;
+    /**
+     * Hook: вызывается после markAsTouched()
+     *
+     * Для GroupNode: рекурсивно помечаем все дочерние поля как touched
+     */
+    protected onMarkAsTouched(): void;
+    /**
+     * Hook: вызывается после markAsUntouched()
+     *
+     * Для GroupNode: рекурсивно помечаем все дочерние поля как untouched
+     */
+    protected onMarkAsUntouched(): void;
+    /**
+     * Hook: вызывается после markAsDirty()
+     *
+     * Для GroupNode: рекурсивно помечаем все дочерние поля как dirty
+     */
+    protected onMarkAsDirty(): void;
+    /**
+     * Hook: вызывается после markAsPristine()
+     *
+     * Для GroupNode: рекурсивно помечаем все дочерние поля как pristine
+     */
+    protected onMarkAsPristine(): void;
+    /**
+     * Отправить форму
+     * Валидирует форму и вызывает onSubmit если форма валидна
+     */
+    submit<R>(onSubmit: (values: T) => Promise<R> | R): Promise<R | null>;
+    /**
+     * Применить validation schema к форме
+     *
+     * Использует локальный реестр валидаторов (this.validationRegistry)
+     * вместо глобального Singleton для изоляции форм друг от друга.
+     */
+    applyValidationSchema(schemaFn: ValidationSchemaFn<T>): void;
+    /**
+     * Применить behavior schema к форме
+     *
+     * ✅ РЕФАКТОРИНГ: Делегирование BehaviorApplicator (SRP)
+     *
+     * Логика применения behavior схемы извлечена в BehaviorApplicator для:
+     * - Соблюдения Single Responsibility Principle
+     * - Уменьшения размера GroupNode (~50 строк)
+     * - Улучшения тестируемости
+     * - Консистентности с ValidationApplicator
+     *
+     * @param schemaFn Функция описания поведения формы
+     * @returns Функция cleanup для отписки от всех behaviors
+     *
+     * @example
+     * ```typescript
+     * import { copyFrom, enableWhen, computeFrom } from '@/lib/forms/core/behaviors';
+     *
+     * const behaviorSchema: BehaviorSchemaFn<MyForm> = (path) => {
+     *   copyFrom(path.residenceAddress, path.registrationAddress, {
+     *     when: (form) => form.sameAsRegistration === true
+     *   });
+     *
+     *   enableWhen(path.propertyValue, (form) => form.loanType === 'mortgage');
+     *
+     *   computeFrom(
+     *     path.initialPayment,
+     *     [path.propertyValue],
+     *     (propertyValue) => propertyValue ? propertyValue * 0.2 : null
+     *   );
+     * };
+     *
+     * const cleanup = form.applyBehaviorSchema(behaviorSchema);
+     *
+     * // Cleanup при unmount
+     * useEffect(() => cleanup, []);
+     * ```
+     */
+    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
+     * Поддерживает опциональную трансформацию значения
+     *
+     * @param sourceKey - Ключ поля-источника
+     * @param targetKey - Ключ поля-цели
+     * @param transform - Опциональная функция трансформации значения
+     * @returns Функция отписки для cleanup
+     *
+     * @example
+     * ```typescript
+     * // Автоматический расчет минимального взноса от стоимости недвижимости
+     * const dispose = form.linkFields(
+     *   'propertyValue',
+     *   'initialPayment',
+     *   (propertyValue) => propertyValue ? propertyValue * 0.2 : null
+     * );
+     *
+     * // При изменении propertyValue → автоматически обновится initialPayment
+     * form.propertyValue.setValue(1000000);
+     * // initialPayment станет 200000
+     *
+     * // Cleanup
+     * useEffect(() => dispose, []);
+     * ```
+     */
+    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()
+     *
+     * Для GroupNode: рекурсивно отключаем все дочерние поля
+     */
+    protected onDisable(): void;
+    /**
+     * Hook: вызывается после enable()
+     *
+     * Для GroupNode: рекурсивно включаем все дочерние поля
+     */
+    protected onEnable(): void;
+    /**
+     * Очистить все ресурсы узла
+     * Рекурсивно очищает все subscriptions и дочерние узлы
+     *
+     * @example
+     * ```typescript
+     * useEffect(() => {
+     *   return () => {
+     *     form.dispose();
+     *   };
+     * }, []);
+     * ```
+     */
+    dispose(): void;
+}