@reformer/core 1.0.0-beta.1

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

@@ -0,0 +1,328 @@
+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 - массив форм с реактивным состоянием
+ *
+ * @group Nodes
+ *
+ * @example
+ * ```typescript
+ * const array = new ArrayNode({
+ *   title: { value: '', component: Input },
+ *   price: { value: 0, component: Input },
+ * });
+ *
+ * array.push({ title: 'Item 1', price: 100 });
+ * array.at(0)?.title.setValue('Updated');
+ * console.log(array.length.value); // 1
+ * ```
+ */
+export declare class ArrayNode<T extends FormFields> extends FormNode<T[]> {
+    private items;
+    private itemSchema;
+    private initialItems;
+    /**
+     * Менеджер подписок для централизованного cleanup
+     * Использует SubscriptionManager вместо массива для управления подписками
+     */
+    private disposers;
+    /** Array-level validation errors (e.g., "минимум 1 элемент") */
+    private readonly _arrayErrors;
+    private validationSchemaFn?;
+    private behaviorSchemaFn?;
+    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 length: ReadonlySignal<number>;
+    constructor(schema: FormSchema<T>, initialItems?: Partial<T>[]);
+    /**
+     * Добавить элемент в конец массива
+     * @param initialValue - Начальные значения для нового элемента
+     */
+    push(initialValue?: Partial<T>): void;
+    /**
+     * Удалить элемент по индексу
+     * @param index - Индекс элемента для удаления
+     *
+     * @remarks
+     * Вызывает dispose() на удаляемом элементе для очистки подписок
+     */
+    removeAt(index: number): void;
+    /**
+     * Вставить элемент в массив
+     * @param index - Индекс для вставки
+     * @param initialValue - Начальные значения для нового элемента
+     */
+    insert(index: number, initialValue?: Partial<T>): void;
+    /**
+     * Удалить все элементы массива
+     *
+     * @remarks
+     * Вызывает dispose() на всех элементах для очистки подписок
+     */
+    clear(): void;
+    /**
+     * Получить элемент по индексу
+     * @param index - Индекс элемента
+     * @returns Типизированный GroupNode proxy или undefined если индекс вне границ
+     */
+    at(index: number): FormProxy<T> | undefined;
+    getValue(): T[];
+    setValue(values: T[], options?: SetValueOptions): void;
+    patchValue(values: (T | undefined)[]): void;
+    /**
+     * Сбросить массив к указанным значениям (или очистить)
+     *
+     * @param values - опциональный массив значений для сброса
+     *
+     * @remarks
+     * Очищает текущий массив и заполняет новыми элементами
+     *
+     * @example
+     * ```typescript
+     * // Очистить массив
+     * arrayNode.reset();
+     *
+     * // Сбросить к новым значениям
+     * arrayNode.reset([{ name: 'Item 1' }, { name: 'Item 2' }]);
+     * ```
+     */
+    reset(values?: T[]): void;
+    /**
+     * Сбросить массив к исходным значениям (initialItems)
+     *
+     * @remarks
+     * Восстанавливает массив в состояние, которое было при создании ArrayNode.
+     * Более явный способ сброса к начальным значениям по сравнению с reset()
+     *
+     * Полезно когда:
+     * - Пользователь нажал "Cancel" - вернуть массив к исходным элементам
+     * - Массив был изменен через reset(newValues), но нужно вернуться к началу
+     * - Явное намерение показать "отмена всех изменений"
+     *
+     * @example
+     * ```typescript
+     * const arrayNode = new ArrayNode(
+     *   { name: { value: '', component: Input } },
+     *   [{ name: 'Initial 1' }, { name: 'Initial 2' }]
+     * );
+     *
+     * arrayNode.push({ name: 'New Item' });
+     * arrayNode.reset([{ name: 'Temp' }]);
+     * console.log(arrayNode.length.value); // 1
+     *
+     * arrayNode.resetToInitial();
+     * console.log(arrayNode.length.value); // 2
+     * console.log(arrayNode.at(0)?.name.value.value); // 'Initial 1'
+     * ```
+     */
+    resetToInitial(): void;
+    validate(): Promise<boolean>;
+    /**
+     * Установить 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()
+     *
+     * Для ArrayNode: рекурсивно помечаем все элементы массива как touched
+     */
+    protected onMarkAsTouched(): void;
+    /**
+     * Hook: вызывается после markAsUntouched()
+     *
+     * Для ArrayNode: рекурсивно помечаем все элементы массива как untouched
+     */
+    protected onMarkAsUntouched(): void;
+    /**
+     * Hook: вызывается после markAsDirty()
+     *
+     * Для ArrayNode: рекурсивно помечаем все элементы массива как dirty
+     */
+    protected onMarkAsDirty(): void;
+    /**
+     * Hook: вызывается после markAsPristine()
+     *
+     * Для ArrayNode: рекурсивно помечаем все элементы массива как pristine
+     */
+    protected onMarkAsPristine(): void;
+    /**
+     * Итерировать по элементам массива
+     * @param callback - Функция, вызываемая для каждого элемента с типизированным GroupNode proxy
+     */
+    forEach(callback: (item: FormProxy<T>, index: number) => void): void;
+    /**
+     * Маппинг элементов массива
+     * @param callback - Функция преобразования с типизированным GroupNode proxy
+     * @returns Новый массив результатов
+     */
+    map<R>(callback: (item: FormProxy<T>, index: number) => R): R[];
+    /**
+     * Создать новый элемент массива на основе схемы
+     * @param initialValue - Начальные значения
+     */
+    private createItem;
+    /**
+     * Проверить, является ли схема групповой (объект полей)
+     * @param schema - Схема для проверки
+     */
+    private isGroupSchema;
+    /**
+     * Применить validation schema ко всем элементам массива
+     *
+     * Validation schema будет применена к:
+     * - Всем существующим элементам
+     * - Всем новым элементам, добавляемым через push/insert
+     *
+     * @param schemaFn - Функция валидации для элемента массива
+     *
+     * @example
+     * ```typescript
+     * import { propertyValidation } from './validation/property-validation';
+     *
+     * form.properties.applyValidationSchema(propertyValidation);
+     * ```
+     */
+    applyValidationSchema(schemaFn: unknown): void;
+    /**
+     * Применить behavior schema ко всем элементам ArrayNode
+     *
+     * Автоматически применяется к новым элементам при push/insert.
+     *
+     * @param schemaFn - Behavior schema функция
+     *
+     * @example
+     * ```typescript
+     * import { addressBehavior } from './behaviors/address-behavior';
+     *
+     * form.addresses.applyBehaviorSchema(addressBehavior);
+     * ```
+     */
+    applyBehaviorSchema(schemaFn: unknown): void;
+    /**
+     * Подписка на изменения конкретного поля во всех элементах массива
+     * Срабатывает при изменении значения поля в любом элементе
+     *
+     * @param fieldKey - Ключ поля для отслеживания
+     * @param callback - Функция, вызываемая при изменении, получает массив всех значений и индекс измененного элемента
+     * @returns Функция отписки для cleanup
+     *
+     * @example
+     * ```typescript
+     * // Автоматический пересчет общей стоимости при изменении цен
+     * const dispose = form.existingLoans.watchItems(
+     *   'remainingAmount',
+     *   (amounts) => {
+     *     const totalDebt = amounts.reduce((sum, amount) => sum + (amount || 0), 0);
+     *     form.totalDebt.setValue(totalDebt);
+     *   }
+     * );
+     *
+     * // При изменении любого remainingAmount → пересчитается totalDebt
+     * form.existingLoans.at(0)?.remainingAmount.setValue(500000);
+     *
+     * // Cleanup
+     * useEffect(() => dispose, []);
+     * ```
+     */
+    watchItems<K extends keyof T>(fieldKey: K, callback: (values: Array<T[K] | undefined>) => void | Promise<void>): () => void;
+    /**
+     * Подписка на изменение длины массива
+     * Срабатывает при добавлении/удалении элементов
+     *
+     * @param callback - Функция, вызываемая при изменении длины, получает новую длину
+     * @returns Функция отписки для cleanup
+     *
+     * @example
+     * ```typescript
+     * // Обновление счетчика элементов в UI
+     * const dispose = form.properties.watchLength((length) => {
+     *   console.log(`Количество объектов недвижимости: ${length}`);
+     *   form.propertyCount.setValue(length);
+     * });
+     *
+     * form.properties.push({ title: 'Квартира', value: 5000000 });
+     * // Выведет: "Количество объектов недвижимости: 1"
+     *
+     * // Cleanup
+     * useEffect(() => dispose, []);
+     * ```
+     */
+    watchLength(callback: (length: number) => void | Promise<void>): () => void;
+    /**
+     * Очистить все ресурсы узла
+     * Рекурсивно очищает все subscriptions и элементы массива
+     *
+     * @example
+     * ```typescript
+     * useEffect(() => {
+     *   return () => {
+     *     arrayNode.dispose();
+     *   };
+     * }, []);
+     * ```
+     */
+    dispose(): void;
+    /**
+     * Hook: вызывается после disable()
+     *
+     * Для ArrayNode: рекурсивно отключаем все элементы массива
+     *
+     * @example
+     * ```typescript
+     * // Отключить весь массив полей
+     * form.items.disable();
+     *
+     * // Все элементы становятся disabled
+     * form.items.forEach(item => {
+     *   console.log(item.status.value); // 'disabled'
+     * });
+     * ```
+     */
+    protected onDisable(): void;
+    /**
+     * Hook: вызывается после enable()
+     *
+     * Для ArrayNode: рекурсивно включаем все элементы массива
+     *
+     * @example
+     * ```typescript
+     * // Включить весь массив полей
+     * form.items.enable();
+     *
+     * // Все элементы становятся enabled
+     * form.items.forEach(item => {
+     *   console.log(item.status.value); // 'valid' или 'invalid'
+     * });
+     * ```
+     */
+    protected onEnable(): void;
+}

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

@@ -0,0 +1,294 @@
+import { ReadonlySignal } from '@preact/signals-core';
+import { FormNode, SetValueOptions } from './form-node';
+import { FieldConfig, FieldStatus, 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 _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>>;
+    /**
+     * Вычисляемое свойство: нужно ли показывать ошибку
+     * Ошибка показывается если поле невалидно И (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, 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 - Функция, вызываемая при изменении значения.
+     *   Для 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;
+}