@reformer/core 3.0.0 → 4.0.0

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

@@ -1,3 +1,7 @@
+import { BehaviorSchemaFn } from '../behavior/types';
+import { FormSchema } from './deep-schema';
+import { ValidationSchemaFn } from './validation-schema';
+import { FormNode } from '../nodes/form-node';
 /**
  * Represents any valid form value type
  * Use this instead of 'any' for form values to maintain type safety
@@ -20,12 +24,46 @@ export type UnknownFormValue = unknown;
  * @category Validation Types
  */
 export type ValidatorFn<T = FormValue> = (value: T) => ValidationError | null;
+/**
+ * Опции для асинхронного валидатора
+ * @group Types
+ * @category Validation Types
+ */
+export interface AsyncValidatorOptions {
+    /**
+     * AbortSignal для отмены валидации
+     * Позволяет отменить асинхронную операцию при новой валидации
+     */
+    signal?: AbortSignal;
+}
 /**
  * Асинхронная функция валидации
+ *
+ * @param value - Значение для валидации
+ * @param options - Опции валидации (опционально)
+ * @returns Promise с ошибкой валидации или null если значение валидно
+ *
+ * @example
+ * ```typescript
+ * // Простой валидатор (без поддержки отмены)
+ * const emailExists: AsyncValidatorFn<string> = async (value) => {
+ *   const exists = await checkEmail(value);
+ *   return exists ? { code: 'exists', message: 'Email already exists' } : null;
+ * };
+ *
+ * // Валидатор с поддержкой отмены
+ * const emailExistsAbortable: AsyncValidatorFn<string> = async (value, options) => {
+ *   const exists = await fetch(`/api/check-email?email=${value}`, {
+ *     signal: options?.signal // Передаём signal в fetch для отмены запроса
+ *   });
+ *   return exists ? { code: 'exists', message: 'Email already exists' } : null;
+ * };
+ * ```
+ *
  * @group Types
  * @category Validation Types
  */
-export type AsyncValidatorFn<T = FormValue> = (value: T) => Promise<ValidationError | null>;
+export type AsyncValidatorFn<T = FormValue> = (value: T, options?: AsyncValidatorOptions) => Promise<ValidationError | null>;
 /**
  * Ошибка валидации
  * @group Types
@@ -65,9 +103,6 @@ export type { ContextualValidatorFn, ContextualAsyncValidatorFn, TreeValidatorFn
 export type { FormSchema, ArrayConfig } from './deep-schema';
 export type { FormContext } from './form-context';
 export type { FormControlsProxy, FormProxy, FormArrayProxy } from './form-proxy';
-import type { BehaviorSchemaFn } from '../behavior/types';
-import type { FormSchema } from './deep-schema';
-import type { ValidationSchemaFn } from './validation-schema';
 /**
  * Конфигурация GroupNode с поддержкой схем
  * Используется для создания форм с автоматическим применением behavior и validation схем
@@ -82,6 +117,18 @@ export interface GroupNodeConfig<T> {
     behavior?: BehaviorSchemaFn<T>;
     /** Схема валидации (required, email, minLength и т.д.) */
     validation?: ValidationSchemaFn<T>;
+    /**
+     * Опциональный ValidationRegistry для dependency injection
+     * Используется для тестирования с mock-реестрами
+     * @internal
+     */
+    _validationRegistry?: unknown;
+    /**
+     * Опциональный BehaviorRegistry для dependency injection
+     * Используется для тестирования с mock-реестрами
+     * @internal
+     */
+    _behaviorRegistry?: unknown;
 }
 /**
  * Тип для Record с unknown значениями
@@ -112,7 +159,6 @@ export interface ArrayNodeLike {
     at(index: number): FormNode<unknown> | undefined;
     length: unknown;
 }
-import type { FormNode } from '../nodes/form-node';
 /**
  * Конфиг с полем schema (для ArrayConfig)
  * @internal

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

@@ -1,15 +1,6 @@
-/**
- * Типы для validation schema паттерна
- *
- * Основано на Angular Signal Forms подходе:
- * - Валидация определяется отдельно от схемы полей
- * - Поддержка условной валидации (applyWhen)
- * - Cross-field валидация (validateTree)
- * - Асинхронная валидация с контекстом
- */
-import type { FormFields, ValidationError } from './index';
-import type { FieldPath } from './field-path';
-import type { FormContext } from './form-context';
+import { FormFields, ValidationError } from './index';
+import { FieldPath } from './field-path';
+import { FormContext } from './form-context';
 /**
  * Функция валидации поля с контекстом
  *

package/dist/core/utils/abstract-registry.d.ts

@@ -0,0 +1,74 @@
+import { RegistryStack } from './registry-stack';
+/**
+ * Базовый класс для реестров (BehaviorRegistry, ValidationRegistry).
+ *
+ * Реализует паттерн Template Method для управления регистрацией:
+ * `beginRegistration()` → `onBeginRegistration()`, `endRegistration()` → `onEndRegistration()`.
+ *
+ * @typeParam TRegistration - Тип регистрируемых элементов.
+ *
+ * @example
+ * ```typescript
+ * import { AbstractRegistry } from '@reformer/core';
+ *
+ * class MyRegistry extends AbstractRegistry<{ name: string }> {
+ *   protected onEndRegistration(items: { name: string }[]) {
+ *     console.log('Registered', items.length);
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class AbstractRegistry<TRegistration> {
+    /** Флаг активной регистрации */
+    protected isRegistering: boolean;
+    /** Массив зарегистрированных элементов */
+    protected registrations: TRegistration[];
+    /**
+     * Получить стек для конкретного класса реестра
+     * Создает новый стек если не существует
+     *
+     * @param ctor - Конструктор класса реестра
+     * @returns RegistryStack для данного класса
+     */
+    protected static getStack<T extends AbstractRegistry<any>>(ctor: new (...args: any[]) => T): RegistryStack<T>;
+    /**
+     * Получить текущий активный реестр из стека
+     * Должен быть переопределен в наследниках как static метод
+     *
+     * @param ctor - Конструктор класса реестра
+     * @returns Текущий активный реестр или null
+     */
+    protected static getCurrentFromStack<T extends AbstractRegistry<any>>(ctor: new (...args: any[]) => T): T | null;
+    /**
+     * Начать регистрацию
+     *
+     * Помещает this в global stack для изоляции форм
+     * Вызывает hook onBeginRegistration()
+     */
+    beginRegistration(): void;
+    /**
+     * Проверить, активна ли регистрация
+     */
+    isActive(): boolean;
+    /**
+     * Получить зарегистрированные элементы
+     */
+    getRegistrations(): TRegistration[];
+    /**
+     * Hook: вызывается в начале регистрации
+     * Может быть переопределен в наследниках для инициализации
+     */
+    protected onBeginRegistration(): void;
+    /**
+     * Завершить регистрацию и извлечь из стека
+     *
+     * @param registryName - Имя реестра для отладки
+     */
+    protected completeRegistration(registryName: string): void;
+    /**
+     * Отменить регистрацию без применения
+     *
+     * @param registryName - Имя реестра для отладки
+     */
+    cancelRegistration(registryName: string): void;
+}

package/dist/core/utils/aggregate-signals.d.ts

@@ -0,0 +1,71 @@
+import { ReadonlySignal, Signal } from '@preact/signals-core';
+import { FieldStatus, ValidationError } from '../types';
+import { FormNode } from '../nodes/form-node';
+/**
+ * Функция получения дочерних узлов
+ * Возвращает массив FormNode для агрегации состояния
+ */
+type GetChildrenFn<T> = () => FormNode<T>[];
+/**
+ * Результат создания агрегированных сигналов
+ */
+export interface AggregateSignals {
+    /** Все дочерние узлы валидны и нет собственных ошибок */
+    valid: ReadonlySignal<boolean>;
+    /** Есть ошибки (инверсия valid) */
+    invalid: ReadonlySignal<boolean>;
+    /** Хотя бы один дочерний узел в состоянии pending */
+    pending: ReadonlySignal<boolean>;
+    /** Хотя бы один дочерний узел touched */
+    touched: ReadonlySignal<boolean>;
+    /** Хотя бы один дочерний узел dirty */
+    dirty: ReadonlySignal<boolean>;
+    /** Собственные ошибки + ошибки всех дочерних узлов */
+    errors: ReadonlySignal<ValidationError[]>;
+    /** Статус: disabled > pending > invalid > valid */
+    status: ReadonlySignal<FieldStatus>;
+}
+/**
+ * Опции для создания агрегированных сигналов
+ */
+export interface AggregateSignalsOptions<T> {
+    /** Функция получения дочерних узлов */
+    getChildren: GetChildrenFn<T>;
+    /** Signal с собственными ошибками контейнера (form-level или array-level) */
+    ownErrors: Signal<ValidationError[]>;
+    /** Опциональный signal disabled состояния (для GroupNode) */
+    disabled?: Signal<boolean>;
+}
+/**
+ * Создать агрегированные computed signals для контейнерного узла
+ *
+ * Используется в GroupNode и ArrayNode для унификации логики
+ * вычисления состояния на основе дочерних узлов.
+ *
+ * @param options - Опции конфигурации
+ * @returns Объект с computed signals
+ *
+ * @example GroupNode
+ * ```typescript
+ * const signals = createAggregateSignals({
+ *   getChildren: () => Array.from(this._fields.values()),
+ *   ownErrors: this._formErrors,
+ *   disabled: this._disabled,
+ * });
+ * this.valid = signals.valid;
+ * this.invalid = signals.invalid;
+ * // ...
+ * ```
+ *
+ * @example ArrayNode
+ * ```typescript
+ * const signals = createAggregateSignals({
+ *   getChildren: () => this.items.value,
+ *   ownErrors: this._arrayErrors,
+ * });
+ * this.valid = signals.valid;
+ * // ...
+ * ```
+ */
+export declare function createAggregateSignals<T>(options: AggregateSignalsOptions<T>): AggregateSignals;
+export {};

package/dist/core/utils/create-form.d.ts

@@ -1,21 +1,4 @@
-/**
- * Фабричная функция для создания формы с правильной типизацией
- *
- * Решает проблему с типизацией конструктора GroupNode, который возвращает
- * Proxy (FormProxy), но TypeScript не может это вывести автоматически.
- *
- * @group Utilities
- *
- * @example
- * ```typescript
- * // Вместо:
- * const form: FormProxy<MyForm> = new GroupNode<MyForm>(config);
- *
- * // Используйте:
- * const form = createForm<MyForm>(config);
- * ```
- */
-import type { FormProxy, GroupNodeConfig, FormSchema } from '../types';
+import { FormProxy, GroupNodeConfig, FormSchema } from '../types';
 /**
  * Создать форму с полной конфигурацией (form, behavior, validation)
  *

package/dist/core/utils/error-handler.d.ts

@@ -1,21 +1,4 @@
-/**
- * FormErrorHandler - централизованная обработка ошибок в формах
- *
- * Устраняет несогласованность обработки ошибок между:
- * - field-node.ts (логирует и конвертирует в ValidationError)
- * - behavior-applicator.ts (логирует и пробрасывает)
- * - validation-applicator.ts (логирует и проглатывает)
- *
- * @example
- * ```typescript
- * try {
- *   await validator(value);
- * } catch (error) {
- *   return FormErrorHandler.handle(error, 'AsyncValidator', ErrorStrategy.CONVERT);
- * }
- * ```
- */
-import type { ValidationError } from '../types';
+import { ValidationError } from '../types';
 /**
  * Стратегия обработки ошибок
  *

package/dist/core/utils/field-path-navigator.d.ts

@@ -1,4 +1,4 @@
-import type { UnknownRecord } from '../types';
+import { UnknownRecord } from '../types';
 /**
  * Сегмент пути к полю формы
  *

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

@@ -1,12 +1,4 @@
-/**
- * FieldPath proxy - типобезопасный доступ к путям полей формы
- *
- * Единый модуль для validation и behavior схем.
- * Предоставляет типизированную навигацию по структуре формы.
- *
- * @module utils/field-path
- */
-import type { FieldPath, FieldPathNode } from '../types';
+import { FieldPath, FieldPathNode } from '../types';
 /**
  * Создать FieldPath proxy для формы
  *
@@ -19,7 +11,17 @@ import type { FieldPath, FieldPathNode } from '../types';
  */
 export declare function createFieldPath<T>(): FieldPath<T>;
 /**
- * Извлечь путь из FieldPathNode
+ * Извлечь строковый путь из {@link FieldPathNode}.
+ *
+ * @param node - Узел `FieldPathNode` либо строка-путь.
+ * @returns Путь вида `"a.b.c"`.
+ *
+ * @example
+ * ```typescript
+ * import { extractPath } from '@reformer/core';
+ *
+ * const path = (renderPath) => extractPath(renderPath.user.email); // → 'user.email'
+ * ```
  */
 export declare function extractPath(node: FieldPathNode<unknown, unknown> | unknown): string;
 /**
@@ -43,6 +45,16 @@ export declare function extractPath(node: FieldPathNode<unknown, unknown> | unkn
  */
 export declare function toFieldPath<T>(node: FieldPathNode<unknown, T, never> | FieldPathNode<any, T, any>): FieldPath<T>;
 /**
- * Извлечь ключ поля из FieldPathNode
+ * Извлечь имя последнего сегмента ({@link FieldPathSegment}) пути.
+ *
+ * @param node - Узел `FieldPathNode` либо строка-путь.
+ * @returns Имя поля без префикса родителя (последний сегмент).
+ *
+ * @example
+ * ```typescript
+ * import { extractKey } from '@reformer/core';
+ *
+ * extractKey(path.user.email); // → 'email'
+ * ```
  */
 export declare function extractKey(node: FieldPathNode<unknown, unknown> | unknown): string;

package/dist/core/utils/form-observer.d.ts

@@ -0,0 +1,176 @@
+import { FormFields, FormValue, FieldStatus, ValidationError } from '../types';
+/**
+ * Тип события изменения в форме
+ */
+export type FormChangeType = 'value' | 'status' | 'errors' | 'touched' | 'dirty';
+/**
+ * Событие изменения в форме
+ */
+export interface FormChangeEvent {
+    /** Тип изменения */
+    type: FormChangeType;
+    /** Путь к полю */
+    path: string;
+    /** Timestamp события */
+    timestamp: number;
+    /** Старое значение */
+    oldValue?: unknown;
+    /** Новое значение */
+    newValue: unknown;
+}
+/**
+ * Интерфейс узла формы для observer
+ */
+export interface ObservableFormNode {
+    value: {
+        value: FormValue;
+    };
+    status: {
+        value: FieldStatus;
+    };
+    errors: {
+        value: ValidationError[];
+    };
+    touched: {
+        value: boolean;
+    };
+    dirty: {
+        value: boolean;
+    };
+}
+/**
+ * Интерфейс формы для observer
+ */
+export interface ObservableForm<T extends FormFields> {
+    value: {
+        value: T;
+    };
+    status: {
+        value: FieldStatus;
+    };
+    errors: {
+        value: ValidationError[];
+    };
+    touched: {
+        value: boolean;
+    };
+    dirty: {
+        value: boolean;
+    };
+    getFieldByPath(path: string): ObservableFormNode | undefined;
+}
+/**
+ * Callback для обработки событий изменения
+ */
+export type FormChangeCallback = (event: FormChangeEvent) => void;
+/**
+ * Опции для FormObserver
+ */
+export interface FormObserverOptions {
+    /** Включить логирование в консоль (по умолчанию true в DEV) */
+    enableLogging?: boolean;
+    /** Фильтр типов событий */
+    eventTypes?: FormChangeType[];
+    /** Фильтр путей полей (regex или массив) */
+    pathFilter?: RegExp | string[];
+}
+/**
+ * FormObserver - мониторинг изменений в форме
+ *
+ * Полезен для:
+ * - Отладки сложных форм
+ * - Логирования изменений для аудита
+ * - Синхронизации с внешними системами
+ *
+ * @example
+ * ```typescript
+ * const observer = new FormObserver(form, {
+ *   enableLogging: true,
+ *   eventTypes: ['value', 'errors']
+ * });
+ *
+ * // Подписка на события
+ * const unsubscribe = observer.subscribe((event) => {
+ *   console.log(`${event.type} at ${event.path}:`, event.newValue);
+ * });
+ *
+ * // Включить трассировку
+ * const disposeTracing = observer.enableTracing();
+ *
+ * // Cleanup
+ * unsubscribe();
+ * disposeTracing();
+ * ```
+ */
+export declare class FormObserver<T extends FormFields> {
+    private readonly form;
+    private listeners;
+    private disposers;
+    private options;
+    /**
+     * @param form - Форма для наблюдения
+     * @param options - Опции observer
+     */
+    constructor(form: ObservableForm<T>, options?: FormObserverOptions);
+    /**
+     * Подписаться на события изменения
+     *
+     * @param callback - Функция обработки события
+     * @returns Функция отписки
+     *
+     * @example
+     * ```typescript
+     * const unsubscribe = observer.subscribe((event) => {
+     *   // Отправить событие в analytics
+     *   analytics.track('form_change', event);
+     * });
+     * ```
+     */
+    subscribe(callback: FormChangeCallback): () => void;
+    /**
+     * Включить трассировку формы
+     *
+     * Подписывается на изменения основных сигналов формы
+     * и вызывает listeners при каждом изменении
+     *
+     * @returns Функция для отключения трассировки
+     *
+     * @example
+     * ```typescript
+     * const dispose = observer.enableTracing();
+     *
+     * // Позже, для отключения
+     * dispose();
+     * ```
+     */
+    enableTracing(): () => void;
+    /**
+     * Наблюдать за конкретным полем
+     *
+     * @param path - Путь к полю
+     * @returns Функция для отключения наблюдения
+     *
+     * @example
+     * ```typescript
+     * // Наблюдать за полем email
+     * const dispose = observer.watchField('email');
+     * ```
+     */
+    watchField(path: string): () => void;
+    /**
+     * Отправить событие всем listeners
+     */
+    private emit;
+    /**
+     * Проверить, нужно ли отслеживать тип события
+     */
+    private shouldTrack;
+    /**
+     * Проверить, соответствует ли путь фильтру
+     */
+    private matchesPathFilter;
+    /**
+     * Очистить все подписки и disposers
+     */
+    dispose(): void;
+}

package/dist/core/utils/form-proxy-builder.d.ts

@@ -0,0 +1,25 @@
+import { FormNode } from '../nodes/form-node';
+import { FormProxy } from '../types/form-proxy';
+/**
+ * Создать Proxy для типобезопасного доступа к полям GroupNode
+ *
+ * Proxy обеспечивает:
+ * - Доступ к полям через точечную нотацию (form.email, form.address.city)
+ * - Приоритет собственных свойств GroupNode над полями
+ * - Цепочку proxy для вложенных GroupNode
+ * - Блокировку прямого присваивания полям (только через setValue/patchValue)
+ *
+ * @param target - GroupNode для которого создаётся proxy
+ * @param fields - Map полей формы
+ * @returns Типизированный Proxy
+ *
+ * @internal
+ *
+ * @example
+ * ```typescript
+ * const proxy = buildFormProxy(groupNode, groupNode._fields);
+ * proxy.email.setValue('test@example.com');
+ * console.log(proxy.email.value.value);
+ * ```
+ */
+export declare function buildFormProxy<T>(target: FormNode<T>, fields: Map<keyof T, FormNode<unknown>>): FormProxy<T>;

package/dist/core/utils/form-submitter.d.ts

@@ -0,0 +1,121 @@
+import { ReadonlySignal } from '@preact/signals-core';
+import { FormFields } from '../types';
+/**
+ * Интерфейс формы для FormSubmitter
+ * Минимальный контракт для работы с любой формой
+ */
+export interface SubmittableForm<T extends FormFields> {
+    /** Пометить все поля как touched */
+    markAsTouched(): void;
+    /** Валидировать форму */
+    validate(): Promise<boolean>;
+    /** Получить значения формы */
+    getValue(): T;
+}
+/**
+ * Опции для submit
+ */
+export interface SubmitOptions {
+    /** Пропустить валидацию перед submit */
+    skipValidation?: boolean;
+    /** Пропустить markAsTouched перед submit */
+    skipTouch?: boolean;
+}
+/**
+ * Результат submit
+ */
+export interface SubmitResult<R> {
+    /** Успешно ли выполнен submit */
+    success: boolean;
+    /** Результат от onSubmit callback */
+    data: R | null;
+    /** Ошибка, если submit не удался */
+    error?: Error;
+}
+/**
+ * FormSubmitter - управляет процессом отправки формы
+ *
+ * @example
+ * ```typescript
+ * const submitter = new FormSubmitter(form);
+ *
+ * // Простой submit
+ * const result = await submitter.submit(async (values) => {
+ *   return await api.saveForm(values);
+ * });
+ *
+ * // Проверка состояния
+ * if (submitter.submitting.value) {
+ *   console.log('Форма отправляется...');
+ * }
+ * ```
+ */
+export declare class FormSubmitter<T extends FormFields> {
+    private readonly form;
+    /** Внутренний сигнал состояния отправки */
+    private readonly _submitting;
+    /** Публичный read-only сигнал состояния отправки */
+    readonly submitting: ReadonlySignal<boolean>;
+    /**
+     * @param form - Форма для отправки
+     */
+    constructor(form: SubmittableForm<T>);
+    /**
+     * Отправить форму
+     *
+     * Процесс:
+     * 1. Помечает все поля как touched (для отображения ошибок)
+     * 2. Валидирует форму
+     * 3. Если валидация успешна - вызывает onSubmit
+     * 4. Управляет состоянием submitting
+     *
+     * @param onSubmit - Callback для отправки данных
+     * @param options - Опции submit
+     * @returns Результат от onSubmit или null если валидация не пройдена
+     *
+     * @example
+     * ```typescript
+     * const result = await submitter.submit(async (values) => {
+     *   const response = await fetch('/api/form', {
+     *     method: 'POST',
+     *     body: JSON.stringify(values)
+     *   });
+     *   return response.json();
+     * });
+     *
+     * if (result === null) {
+     *   console.log('Форма не прошла валидацию');
+     * }
+     * ```
+     */
+    submit<R>(onSubmit: (values: T) => Promise<R> | R, options?: SubmitOptions): Promise<R | null>;
+    /**
+     * Отправить форму с расширенным результатом
+     *
+     * В отличие от submit(), возвращает объект с информацией об успехе/ошибке
+     *
+     * @param onSubmit - Callback для отправки данных
+     * @param options - Опции submit
+     * @returns Объект SubmitResult с данными и статусом
+     *
+     * @example
+     * ```typescript
+     * const result = await submitter.submitWithResult(async (values) => {
+     *   return await api.saveForm(values);
+     * });
+     *
+     * if (result.success) {
+     *   console.log('Сохранено:', result.data);
+     * } else if (result.error) {
+     *   console.error('Ошибка:', result.error.message);
+     * } else {
+     *   console.log('Валидация не пройдена');
+     * }
+     * ```
+     */
+    submitWithResult<R>(onSubmit: (values: T) => Promise<R> | R, options?: SubmitOptions): Promise<SubmitResult<R>>;
+    /**
+     * Проверить, идет ли отправка формы
+     */
+    isSubmitting(): boolean;
+}