@reformer/core 1.0.0-beta.1

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;
+}

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

@@ -0,0 +1,22 @@
+/**
+ * Утилиты для работы с формами
+ *
+ * Централизованные вспомогательные классы и функции.
+ */
+export { FieldPathNavigator, type PathSegment } from './field-path-navigator';
+export { createFieldPath, extractPath, extractKey, toFieldPath } from './field-path';
+export { SubscriptionManager } from './subscription-manager';
+export { getCurrentValidationRegistry, getCurrentBehaviorRegistry } from './registry-helpers';
+export { RegistryStack } from './registry-stack';
+export { isFormNode, isFieldNode, isGroupNode, isArrayNode, getNodeType } from './type-guards';
+export { FormErrorHandler, ErrorStrategy } from './error-handler';
+export { createForm } from './create-form';
+export { uniqueId } from './unique-id';
+export { safeCallback, runOutsideEffect, safeDebouncedCallback } from './safe-effect';
+export { AbstractRegistry } from './abstract-registry';
+export { FormSubmitter } from './form-submitter';
+export type { SubmittableForm, SubmitOptions, SubmitResult } from './form-submitter';
+export { FormStatusMachine } from './status-machine';
+export type { StatusEvent } from './status-machine';
+export { FormObserver } from './form-observer';
+export type { FormChangeType, FormChangeEvent, FormChangeCallback, FormObserverOptions, ObservableForm, ObservableFormNode, } from './form-observer';

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

@@ -0,0 +1,43 @@
+import { ValidationRegistry } from '../validation/validation-registry';
+import { BehaviorRegistry } from '../behavior/behavior-registry';
+/**
+ * Получить текущий активный ValidationRegistry из context stack
+ *
+ * Используется внутри validation schema функций (validate, validateAsync, required и т.д.)
+ * для регистрации валидаторов в активном контексте GroupNode
+ *
+ * @returns Текущий ValidationRegistry или заглушка в production
+ * @throws Error если нет активного контекста (только в DEV режиме)
+ *
+ * @internal
+ *
+ * @example
+ * ```typescript
+ * function required(fieldPath, options) {
+ *   const registry = getCurrentValidationRegistry();
+ *   registry.registerSync(path, validator, options);
+ * }
+ * ```
+ */
+export declare function getCurrentValidationRegistry(): ValidationRegistry;
+/**
+ * Получить текущий активный BehaviorRegistry из context stack
+ *
+ * Используется внутри behavior schema функций (copyFrom, enableWhen, computeFrom и т.д.)
+ * для регистрации поведений в активном контексте GroupNode
+ *
+ * @returns Текущий BehaviorRegistry или заглушка в production
+ * @throws Error если нет активного контекста (только в DEV режиме)
+ *
+ * @internal
+ *
+ * @example
+ * ```typescript
+ * function copyFrom(target, source, options) {
+ *   const registry = getCurrentBehaviorRegistry();
+ *   const handler = createCopyBehavior(target, source, options);
+ *   registry.register(handler, { debounce: options?.debounce });
+ * }
+ * ```
+ */
+export declare function getCurrentBehaviorRegistry(): BehaviorRegistry;

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

@@ -0,0 +1,69 @@
+/**
+ * Generic Registry Stack - утилита для управления стеком регистрации
+ *
+ * Используется ValidationRegistry и BehaviorRegistry для tracking активного контекста.
+ * Устраняет дублирование кода между параллельными системами.
+ *
+ * @template T - Тип элементов в стеке (ValidationRegistry или BehaviorRegistry)
+ *
+ * @internal
+ *
+ * @example
+ * ```typescript
+ * class ValidationRegistry {
+ *   private static registryStack = new RegistryStack<ValidationRegistry>();
+ *
+ *   static getCurrent() {
+ *     return ValidationRegistry.registryStack.getCurrent();
+ *   }
+ *
+ *   beginRegistration() {
+ *     ValidationRegistry.registryStack.push(this);
+ *   }
+ *
+ *   endRegistration() {
+ *     ValidationRegistry.registryStack.verify(this, 'ValidationRegistry');
+ *   }
+ * }
+ * ```
+ */
+export declare class RegistryStack<T> {
+    private stack;
+    /**
+     * Добавить элемент в стек
+     * @param item - Элемент для добавления
+     */
+    push(item: T): void;
+    /**
+     * Извлечь элемент из стека
+     * @returns Извлеченный элемент или undefined если стек пуст
+     */
+    pop(): T | undefined;
+    /**
+     * Получить текущий элемент (вершину стека) без извлечения
+     * @returns Текущий элемент или null если стек пуст
+     */
+    getCurrent(): T | null;
+    /**
+     * Извлечь элемент из стека с проверкой
+     * Выводит предупреждение в DEV режиме если извлеченный элемент не совпадает с ожидаемым
+     *
+     * @param expected - Ожидаемый элемент
+     * @param name - Имя реестра для отладки (например, 'ValidationRegistry')
+     */
+    verify(expected: T, name: string): void;
+    /**
+     * Получить длину стека
+     * @returns Количество элементов в стеке
+     */
+    get length(): number;
+    /**
+     * Проверить, пуст ли стек
+     * @returns true если стек пуст
+     */
+    isEmpty(): boolean;
+    /**
+     * Очистить стек
+     */
+    clear(): void;
+}

package/dist/core/utils/safe-effect.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Утилиты для безопасной работы с сигналами в effect контексте
+ *
+ * Эти утилиты решают проблему "Cycle detected" в @preact/signals-core,
+ * которая возникает при модификации сигналов внутри effect.
+ *
+ * @group Utils
+ * @module utils/safe-effect
+ */
+/**
+ * Создает callback, который выполняется вне контекста effect
+ *
+ * Использует queueMicrotask для отложенного выполнения,
+ * что позволяет модифицировать сигналы без вызова "Cycle detected"
+ *
+ * @param callback - Функция для выполнения
+ * @returns Обёрнутая функция, безопасная для вызова внутри effect
+ *
+ * @example
+ * ```typescript
+ * // Вместо:
+ * effect(() => {
+ *   queueMicrotask(() => {
+ *     callback(value, context);
+ *   });
+ * });
+ *
+ * // Используем:
+ * effect(() => {
+ *   safeCallback(callback)(value, context);
+ * });
+ * ```
+ */
+export declare function safeCallback<TArgs extends unknown[]>(callback: (...args: TArgs) => void | Promise<void>): (...args: TArgs) => void;
+/**
+ * Выполняет функцию вне контекста effect
+ *
+ * Более простой вариант для одиночного вызова
+ *
+ * @param fn - Функция для выполнения
+ *
+ * @example
+ * ```typescript
+ * effect(() => {
+ *   const value = signal.value;
+ *   runOutsideEffect(() => {
+ *     otherSignal.value = transform(value);
+ *   });
+ * });
+ * ```
+ */
+export declare function runOutsideEffect(fn: () => void | Promise<void>): void;
+/**
+ * Создает версию callback с поддержкой debounce, безопасную для effect
+ *
+ * Комбинирует debounce логику с выходом из effect контекста
+ *
+ * @param callback - Функция для выполнения
+ * @param withDebounce - Функция debounce обёртки из BehaviorRegistry
+ * @returns Обёрнутая функция
+ *
+ * @example
+ * ```typescript
+ * return effect(() => {
+ *   const value = node.value.value;
+ *   safeDebouncedCallback(
+ *     () => callback(value, context),
+ *     withDebounce
+ *   )();
+ * });
+ * ```
+ */
+export declare function safeDebouncedCallback(callback: () => void | Promise<void>, withDebounce: (fn: () => void) => void): () => void;

package/dist/core/utils/status-machine.d.ts

@@ -0,0 +1,153 @@
+import { ReadonlySignal } from '@preact/signals-core';
+import { FieldStatus } from '../types';
+/**
+ * События для State Machine
+ */
+export type StatusEvent = {
+    type: 'START_VALIDATION';
+} | {
+    type: 'VALIDATION_SUCCESS';
+} | {
+    type: 'VALIDATION_FAILURE';
+} | {
+    type: 'DISABLE';
+} | {
+    type: 'ENABLE';
+    hasErrors?: boolean;
+} | {
+    type: 'SET_ERRORS';
+    hasErrors: boolean;
+};
+/**
+ * FormStatusMachine - управляет состоянием поля формы
+ *
+ * Предоставляет:
+ * - Единый источник истины для статуса
+ * - Computed signals для derived состояний (valid, invalid, pending, disabled)
+ * - Валидацию переходов между состояниями
+ *
+ * @example
+ * ```typescript
+ * const statusMachine = new FormStatusMachine('valid');
+ *
+ * // Начало валидации
+ * statusMachine.startValidation();
+ * console.log(statusMachine.pending.value); // true
+ *
+ * // Завершение валидации с ошибками
+ * statusMachine.completeValidation(true);
+ * console.log(statusMachine.invalid.value); // true
+ *
+ * // Отключение поля
+ * statusMachine.disable();
+ * console.log(statusMachine.disabled.value); // true
+ * ```
+ */
+export declare class FormStatusMachine {
+    /** Внутренний сигнал статуса */
+    private readonly _status;
+    /** Публичный read-only сигнал статуса */
+    readonly status: ReadonlySignal<FieldStatus>;
+    /** Поле валидно */
+    readonly valid: ReadonlySignal<boolean>;
+    /** Поле невалидно */
+    readonly invalid: ReadonlySignal<boolean>;
+    /** Идет валидация */
+    readonly pending: ReadonlySignal<boolean>;
+    /** Поле отключено */
+    readonly disabled: ReadonlySignal<boolean>;
+    /**
+     * @param initial - Начальный статус (по умолчанию 'valid')
+     */
+    constructor(initial?: FieldStatus);
+    /**
+     * Начать валидацию
+     *
+     * Переводит статус в 'pending' если поле не отключено
+     *
+     * @example
+     * ```typescript
+     * statusMachine.startValidation();
+     * // status: 'pending'
+     * ```
+     */
+    startValidation(): void;
+    /**
+     * Завершить валидацию
+     *
+     * @param hasErrors - Есть ли ошибки валидации
+     *
+     * @example
+     * ```typescript
+     * // Валидация успешна
+     * statusMachine.completeValidation(false);
+     * // status: 'valid'
+     *
+     * // Есть ошибки
+     * statusMachine.completeValidation(true);
+     * // status: 'invalid'
+     * ```
+     */
+    completeValidation(hasErrors: boolean): void;
+    /**
+     * Установить ошибки напрямую (без перехода через pending)
+     *
+     * Используется для синхронной валидации или установки ошибок извне
+     *
+     * @param hasErrors - Есть ли ошибки
+     *
+     * @example
+     * ```typescript
+     * statusMachine.setErrors(true);
+     * // status: 'invalid'
+     * ```
+     */
+    setErrors(hasErrors: boolean): void;
+    /**
+     * Отключить поле
+     *
+     * Переводит статус в 'disabled'
+     *
+     * @example
+     * ```typescript
+     * statusMachine.disable();
+     * // status: 'disabled'
+     * ```
+     */
+    disable(): void;
+    /**
+     * Включить поле
+     *
+     * @param hasErrors - Есть ли ошибки (определяет valid/invalid)
+     *
+     * @example
+     * ```typescript
+     * statusMachine.enable(false);
+     * // status: 'valid'
+     *
+     * statusMachine.enable(true);
+     * // status: 'invalid'
+     * ```
+     */
+    enable(hasErrors?: boolean): void;
+    /**
+     * Обработать событие (альтернативный API)
+     *
+     * @param event - Событие для обработки
+     *
+     * @example
+     * ```typescript
+     * statusMachine.dispatch({ type: 'START_VALIDATION' });
+     * statusMachine.dispatch({ type: 'VALIDATION_FAILURE' });
+     * ```
+     */
+    dispatch(event: StatusEvent): void;
+    /**
+     * Получить текущий статус
+     */
+    getStatus(): FieldStatus;
+    /**
+     * Проверить, можно ли начать валидацию
+     */
+    canValidate(): boolean;
+}