@reformer/core 3.0.0 → 4.0.0

package/dist/core/behavior/types.d.ts

@@ -1,12 +1,6 @@
-/**
- * Типы и интерфейсы для Behavior Schema API
- *
- * @group Behaviors
- * @category Behavior Types
- */
 import { GroupNode } from '../nodes/group-node';
-import type { FieldPath } from '../types/field-path';
-import type { FormContext } from '../types/form-context';
+import { FieldPath } from '../types/field-path';
+import { FormContext } from '../types/form-context';
 /**
  * Тип функции behavior схемы
  * Принимает FieldPath и описывает поведение формы

package/dist/core/factories/node-factory.d.ts

@@ -1,40 +1,17 @@
+import { FormNode } from '../nodes/form-node';
 /**
- * NodeFactory - фабрика для создания узлов формы
+ * Фабрика для создания узлов формы.
  *
- * Инкапсулирует логику определения типа конфига и создания соответствующего узла.
- * Используется в GroupNode и ArrayNode для создания дочерних узлов.
- *
- * Паттерн Factory Method упрощает создание узлов и делает код более читаемым:
- * - Вместо if-else в GroupNode/ArrayNode
- * - Единая точка для создания узлов
- * - Легко добавлять новые типы узлов
+ * Определяет тип конфига и создаёт соответствующий узел (FieldNode, GroupNode, ArrayNode).
+ * Используется внутри `getReformerForm`/`group`/`array` — явно вызывать обычно не нужно.
  *
  * @example
  * ```typescript
- * const factory = new NodeFactory();
- *
- * // Создание FieldNode
- * const field = factory.createNode({ value: '', component: Input });
- *
- * // Создание GroupNode
- * const group = factory.createNode({
- *   email: { value: '', component: Input },
- *   password: { value: '', component: Input }
- * });
+ * import { NodeFactory } from '@reformer/core';
  *
- * // Создание ArrayNode
- * const array = factory.createNode({
- *   schema: { title: { value: '', component: Input } },
- *   initialItems: []
- * });
+ * const node = NodeFactory.create({ value: '' }); // → FieldNode<string>
  * ```
  */
-import type { FormNode } from '../nodes/form-node';
-/**
- * Фабрика для создания узлов формы
- *
- * Определяет тип конфига и создает соответствующий узел (FieldNode, GroupNode, ArrayNode)
- */
 export declare class NodeFactory {
     /**
      * Создает узел формы на основе конфигурации

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

@@ -1,18 +1,8 @@
-/**
- * ArrayNode - узел формы для работы с массивами
- *
- * Управляет массивом форм с поддержкой:
- * - Динамического добавления/удаления элементов
- * - Валидации всех элементов
- * - Реактивного состояния через signals
- *
- * @group Nodes
- */
-import type { ReadonlySignal } from '@preact/signals-core';
-import { FormNode, type SetValueOptions } from './form-node';
-import type { FieldStatus, ValidationError, FormFields } from '../types';
-import type { FormSchema } from '../types/deep-schema';
-import type { FormProxy } from '../types/form-proxy';
+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 - массив форм с реактивным состоянием
  *
@@ -39,6 +29,8 @@ export declare class ArrayNode<T extends FormFields> extends FormNode<T[]> {
      * Использует SubscriptionManager вместо массива для управления подписками
      */
     private disposers;
+    /** Array-level validation errors (e.g., "минимум 1 элемент") */
+    private readonly _arrayErrors;
     private validationSchemaFn?;
     private behaviorSchemaFn?;
     readonly value: ReadonlySignal<T[]>;
@@ -59,6 +51,9 @@ export declare class ArrayNode<T extends FormFields> extends FormNode<T[]> {
     /**
      * Удалить элемент по индексу
      * @param index - Индекс элемента для удаления
+     *
+     * @remarks
+     * Вызывает dispose() на удаляемом элементе для очистки подписок
      */
     removeAt(index: number): void;
     /**
@@ -69,12 +64,15 @@ export declare class ArrayNode<T extends FormFields> extends FormNode<T[]> {
     insert(index: number, initialValue?: Partial<T>): void;
     /**
      * Удалить все элементы массива
+     *
+     * @remarks
+     * Вызывает dispose() на всех элементах для очистки подписок
      */
     clear(): void;
     /**
      * Получить элемент по индексу
      * @param index - Индекс элемента
-     * @returns Типизированный GroupNode или undefined если индекс вне границ
+     * @returns Типизированный GroupNode proxy или undefined если индекс вне границ
      */
     at(index: number): FormProxy<T> | undefined;
     getValue(): T[];
@@ -128,7 +126,29 @@ export declare class ArrayNode<T extends FormFields> extends FormNode<T[]> {
      */
     resetToInitial(): void;
     validate(): Promise<boolean>;
-    setErrors(_errors: ValidationError[]): void;
+    /**
+     * Установить 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()
@@ -156,12 +176,12 @@ export declare class ArrayNode<T extends FormFields> extends FormNode<T[]> {
     protected onMarkAsPristine(): void;
     /**
      * Итерировать по элементам массива
-     * @param callback - Функция, вызываемая для каждого элемента с типизированным GroupNode
+     * @param callback - Функция, вызываемая для каждого элемента с типизированным GroupNode proxy
      */
     forEach(callback: (item: FormProxy<T>, index: number) => void): void;
     /**
      * Маппинг элементов массива
-     * @param callback - Функция преобразования с типизированным GroupNode
+     * @param callback - Функция преобразования с типизированным GroupNode proxy
      * @returns Новый массив результатов
      */
     map<R>(callback: (item: FormProxy<T>, index: number) => R): R[];

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

@@ -1,15 +1,6 @@
-/**
- * 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';
+import { ReadonlySignal } from '@preact/signals-core';
+import { FormNode, SetValueOptions } from './form-node';
+import { FieldConfig, FieldStatus, ValidationError } from '../types';
 /**
  * FieldNode - узел для отдельного поля формы
  *
@@ -31,12 +22,18 @@ import type { FieldConfig, ValidationError } from '../types';
 export declare class FieldNode<T> extends FormNode<T> {
     private _value;
     private _errors;
-    private _pending;
     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>>;
     /**
@@ -48,10 +45,14 @@ export declare class FieldNode<T> extends FormNode<T> {
     private asyncValidators;
     private updateOn;
     private initialValue;
-    private currentValidationId;
+    private currentAbortController?;
     private debounceMs;
     private validateDebounceTimer?;
-    private validateDebounceResolve?;
+    /**
+     * Pending debounced validation state
+     * Contains resolve function and AbortController for cancellation
+     */
+    private pendingValidation?;
     /**
      * Менеджер подписок для централизованного cleanup
      * Использует SubscriptionManager вместо массива для управления подписками
@@ -112,13 +113,23 @@ export declare class FieldNode<T> extends FormNode<T> {
      * ```
      */
     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 через validationId.
+     * Метод защищен от race conditions через AbortController.
      * При быстром вводе только последняя валидация применяет результаты.
      *
      * @example
@@ -136,13 +147,12 @@ export declare class FieldNode<T> extends FormNode<T> {
     /**
      * Немедленная валидация без debounce
      * @private
+     * @param providedController - AbortController from debounced validate()
      * @remarks
-     * Защищена от race conditions:
-     * - Проверка validationId после синхронной валидации
-     * - Проверка перед установкой pending
-     * - Проверка после Promise.all
-     * - Проверка перед обработкой async результатов
-     * - Проверка перед очисткой errors
+     * Защищена от race conditions через AbortController:
+     * - Отменяет предыдущую валидацию при запуске новой (if no controller provided)
+     * - Передаёт AbortSignal в async валидаторы для отмены операций (например, fetch)
+     * - Проверяет signal.aborted в ключевых точках
      */
     private validateImmediate;
     setErrors(errors: ValidationError[]): void;
@@ -156,13 +166,13 @@ export declare class FieldNode<T> extends FormNode<T> {
     /**
      * Hook: вызывается после disable()
      *
-     * Для FieldNode: очищаем ошибки валидации
+     * Для FieldNode: синхронизируем statusMachine и очищаем ошибки
      */
     protected onDisable(): void;
     /**
      * Hook: вызывается после enable()
      *
-     * Для FieldNode: запускаем валидацию
+     * Для FieldNode: синхронизируем statusMachine и запускаем валидацию
      */
     protected onEnable(): void;
     /**
@@ -215,20 +225,28 @@ export declare class FieldNode<T> extends FormNode<T> {
      * Подписка на изменения значения поля
      * Автоматически отслеживает изменения через @preact/signals effect
      *
-     * @param callback - Функция, вызываемая при изменении значения
+     * @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) => void | Promise<void>): () => void;
+    watch(callback: (value: T, signal: AbortSignal) => void | Promise<void>): () => void;
     /**
      * Вычисляемое значение из других полей
      * Автоматически обновляет текущее поле при изменении источников
@@ -256,6 +274,13 @@ export declare class FieldNode<T> extends FormNode<T> {
      * Очистить все ресурсы и таймеры
      * Должен вызываться при unmount компонента
      *
+     * @remarks
+     * Освобождает все ресурсы:
+     * - Отписывает все subscriptions через SubscriptionManager
+     * - Отменяет pending/running валидации через cancelPendingValidation()
+     *
+     * Использует try-finally для гарантированного cleanup даже при ошибках.
+     *
      * @example
      * ```typescript
      * useEffect(() => {

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

@@ -1,17 +1,5 @@
-/**
- * FormNode - абстрактный базовый класс для всех узлов формы
- *
- * Аналог AbstractControl из Angular Forms
- * Унифицирует работу с полями (FieldNode), группами (GroupNode) и массивами (ArrayNode)
- *
- * Использует Template Method паттерн для управления состоянием:
- * - Публичные методы (markAsTouched, disable и т.д.) реализованы в базовом классе
- * - Protected hooks (onMarkAsTouched, onDisable и т.д.) переопределяются в наследниках
- *
- * @group Nodes
- */
-import { type ReadonlySignal, type Signal } from '@preact/signals-core';
-import type { FieldStatus, ValidationError, ErrorFilterOptions } from '../types';
+import { ReadonlySignal, Signal } from '@preact/signals-core';
+import { FieldStatus, ValidationError, ErrorFilterOptions } from '../types';
 /**
  * Опции для setValue
  * @group Nodes
@@ -23,17 +11,27 @@ export interface SetValueOptions {
     onlySelf?: boolean;
 }
 /**
- * Абстрактный базовый класс для всех узлов формы
+ * Абстрактный базовый класс для всех узлов формы.
  *
- * Все узлы (поля, группы, массивы) наследуют от этого класса
- * и реализуют единый интерфейс для работы с состоянием и валидацией
+ * Все узлы (поля, группы, массивы) наследуют от этого класса и реализуют
+ * единый интерфейс для работы с состоянием и валидацией.
  *
  * Template Method паттерн используется для управления состоянием:
- * - Общие signals (_touched, _dirty, _status) определены в базовом классе
- * - Публичные методы (markAsTouched, disable и т.д.) реализованы здесь
- * - Protected hooks (onMarkAsTouched, onDisable и т.д.) переопределяются в наследниках
+ * общие 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> {
     /**

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

@@ -1,20 +1,9 @@
-/**
- * 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 { FormProxy } from '../types/form-proxy';
-import type { BehaviorSchemaFn } from '../behavior/types';
+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 - узел для группы полей
  *
@@ -56,7 +45,7 @@ import type { BehaviorSchemaFn } from '../behavior/types';
  * ```
  */
 export declare class GroupNode<T> extends FormNode<T> {
-    id: string;
+    id: `${string}-${string}-${string}-${string}-${string}`;
     /**
      * Коллекция полей формы (упрощённый Map вместо FieldRegistry)
      */
@@ -79,18 +68,20 @@ export declare class GroupNode<T> extends FormNode<T> {
     private readonly nodeFactory;
     /**
      * Реестр валидаторов для этой формы
+     * Может быть инжектирован через config._validationRegistry для тестирования
      */
     private readonly validationRegistry;
     /**
      * Реестр behaviors для этой формы
+     * Может быть инжектирован через config._behaviorRegistry для тестирования
      */
     private readonly behaviorRegistry;
     /**
      * Аппликатор для применения валидаторов к форме
      */
     private readonly validationApplicator;
-    /** Флаг отправки формы */
-    private readonly _submitting;
+    /** Управление отправкой формы */
+    private readonly formSubmitter;
     /** Флаг disabled состояния */
     private readonly _disabled;
     /** Form-level validation errors */
@@ -114,6 +105,7 @@ export declare class GroupNode<T> extends FormNode<T> {
     constructor(config: GroupNodeConfig<T>);
     /**
      * Создать Proxy для типобезопасного доступа к полям
+     * @see buildFormProxy
      */
     private buildProxy;
     getValue(): T;
@@ -195,8 +187,20 @@ export declare class GroupNode<T> extends FormNode<T> {
     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 с данными, статусом и возможной ошибкой
      */
-    submit<R>(onSubmit: (values: T) => Promise<R> | R): Promise<R | null>;
+    submitWithResult<R>(onSubmit: (values: T) => Promise<R> | R, options?: SubmitOptions): Promise<SubmitResult<R>>;
     /**
      * Применить validation schema к форме
      *

package/dist/core/types/deep-schema.d.ts

@@ -1,15 +1,5 @@
-/**
- * Типы для схемы формы (Deep Schema)
- *
- * Автоматическое определение типов схемы на основе структуры данных:
- * - `[{...}]` → массив форм
- * - `{...}` → вложенная группа
- * - `{value, component}` → конфигурация поля
- *
- * @group Types
- */
-import type { ComponentType } from 'react';
-import type { ValidatorFn, AsyncValidatorFn, FormFields, AnyFunction } from './index';
+import { ComponentType } from 'react';
+import { ValidatorFn, AsyncValidatorFn, FormFields, AnyFunction } from './index';
 /**
  * Конфигурация поля
  * @group Types

package/dist/core/types/field-path.d.ts

@@ -1,4 +1,4 @@
-import type { AnyFunction } from './index';
+import { AnyFunction } from './index';
 /**
  * FieldPath предоставляет типобезопасный доступ к путям полей формы
  *

package/dist/core/types/form-context.d.ts

@@ -1,29 +1,7 @@
-/**
- * Единый контекст для работы с формой
- *
- * Используется в:
- * - Behavior схемах (watchField, copyFrom, transformValue, etc.)
- * - Validation схемах (validate, validateAsync, validateTree)
- *
- * @example
- * ```typescript
- * // Behavior
- * watchField(path.country, (country, ctx) => {
- *   ctx.form.city.updateComponentProps({ options: cities });
- *   ctx.setFieldValue('city', null);
- * });
- *
- * // Validation
- * validate(path.email, (value, ctx) => {
- *   if (!value) return { code: 'required', message: 'Required' };
- *   const confirm = ctx.form.confirmEmail.value.value;
- *   if (value !== confirm) return { code: 'mismatch', message: 'Emails must match' };
- *   return null;
- * });
- * ```
- */
-import type { FormProxy } from './form-proxy';
-import type { FieldPathNode } from './field-path';
+import { FormProxy } from './form-proxy';
+import { FieldPathNode } from './field-path';
+import { FormNode } from '../nodes/form-node';
+import { FormValue } from './index';
 /**
  * Единый контекст для работы с формой
  *
@@ -86,4 +64,26 @@ export interface FormContext<TForm> {
      * ```
      */
     setFieldValue(path: string | FieldPathNode<TForm, unknown>, value: unknown): void;
+    /**
+     * Получить поле формы по строковому пути
+     *
+     * Используется для динамического доступа к вложенным полям,
+     * особенно в модульных behavior схемах, применяемых через apply().
+     *
+     * @param path - Строковый путь к полю (например "address.city")
+     * @returns FormNode или undefined если поле не найдено
+     *
+     * @example
+     * ```typescript
+     * // В модульной behavior схеме, применяемой к вложенному полю:
+     * // apply([path.registrationAddress, path.residenceAddress], addressBehavior)
+     *
+     * watchField(path.region, (region, ctx) => {
+     *   // path.city.__path = "registrationAddress.city" или "residenceAddress.city"
+     *   const cityField = ctx.getFieldByPath(path.city.__path);
+     *   cityField?.updateComponentProps({ options: cities });
+     * });
+     * ```
+     */
+    getFieldByPath(path: string): FormNode<FormValue> | undefined;
 }

package/dist/core/types/form-proxy.d.ts

@@ -1,34 +1,4 @@
-/**
- * Типы для Proxy-доступа к полям формы
- *
- * Решает проблему типизации, когда GroupNode<T> использует Proxy для прямого доступа к полям.
- * TypeScript не может автоматически определить правильные типы для вложенных форм и массивов.
- *
- * @group Types
- *
- * @example
- * ```typescript
- * interface MyForm {
- *   name: string;
- *   address: {
- *     city: string;
- *   };
- *   items: Array<{ title: string }>;
- * }
- *
- * const form: FormProxy<MyForm> = new GroupNode(schema);
- *
- * //  TypeScript знает, что это FieldNode<string>
- * form.name.setValue('John');
- *
- * //  TypeScript знает, что это GroupNode<{city: string}>
- * form.address.city.setValue('Moscow');
- *
- * //  TypeScript знает, что это ArrayNode<{title: string}>
- * form.items.push({ title: 'New Item' });
- * ```
- */
-import type { FormFields } from './index';
+import { FormFields } from './index';
 type FieldNode<_T> = any;
 type GroupNode<_T> = any;
 type ArrayNode<_T> = any;
@@ -72,7 +42,7 @@ export type FormControlsProxy<T> = {
  *   };
  * }
  *
- * const form: FormProxy<UserForm> = new GroupNode(schema);
+ * const form = createForm<UserForm>(schema);
  *
  * // Доступ к методам GroupNode
  * await form.validate();