@reformer/core 1.0.0-beta.1

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

@@ -0,0 +1,68 @@
+import { ComponentType } from 'react';
+import { ValidatorFn, AsyncValidatorFn, FormFields, AnyFunction } from './index';
+/**
+ * Конфигурация поля
+ * @group Types
+ * @category Configuration Types
+ */
+export interface FieldConfig<T> {
+    value: T | null;
+    component: ComponentType<any>;
+    componentProps?: any;
+    validators?: ValidatorFn<T>[];
+    asyncValidators?: AsyncValidatorFn<T>[];
+    disabled?: boolean;
+    updateOn?: 'change' | 'blur' | 'submit';
+    /** Задержка (в мс) перед запуском асинхронной валидации */
+    debounce?: number;
+}
+/**
+ * Конфигурация массива
+ * @group Types
+ * @category Configuration Types
+ */
+export interface ArrayConfig<T extends FormFields> {
+    itemSchema: FormSchema<T>;
+    initial?: Partial<T>[];
+}
+/**
+ * Автоматически определяет тип схемы на основе TypeScript типа:
+ * - `T[] -> [FormSchema<T>]` (массив с одним элементом)
+ * - `object -> FormSchema<T>` (группа)
+ * - `primitive -> FieldConfig<T>` (поле)
+ *
+ * Использует NonNullable для корректной обработки опциональных полей
+ *
+ * @group Types
+ * @category Configuration Types
+ *
+ * @example
+ * ```typescript
+ * interface Form {
+ *   name: string;                    // → FieldConfig<string>
+ *   address: {                       // → FormSchema<Address>
+ *     city: string;
+ *     street: string;
+ *   };
+ *   items?: Array<{                  // → [FormSchema<Item>] (опциональный)
+ *     title: string;
+ *     price: number;
+ *   }>;
+ * }
+ *
+ * const schema: FormSchema<Form> = {
+ *   name: { value: '', component: Input },
+ *   address: {
+ *     city: { value: '', component: Input },
+ *     street: { value: '', component: Input },
+ *   },
+ *   items: [{
+ *     title: { value: '', component: Input },
+ *     price: { value: 0, component: Input },
+ *   }],
+ * };
+ * ```
+ */
+export type FormSchema<T> = {
+    [K in keyof T]: NonNullable<T[K]> extends string | number | boolean ? FieldConfig<T[K]> : NonNullable<T[K]> extends Array<infer U> ? U extends string | number | boolean ? FieldConfig<T[K]> : U extends Date | File | Blob | AnyFunction ? FieldConfig<T[K]> : [FormSchema<U>] : NonNullable<T[K]> extends Date | File | Blob | AnyFunction ? FieldConfig<T[K]> : FormSchema<NonNullable<T[K]>>;
+};

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

@@ -0,0 +1,42 @@
+import { AnyFunction } from './index';
+/**
+ * FieldPath предоставляет типобезопасный доступ к путям полей формы
+ *
+ * Рекурсивно обрабатывает вложенные объекты для поддержки вложенных форм.
+ *
+ * Использование:
+ * ```typescript
+ * const validation = (path: FieldPath<MyForm>) => {
+ *   required(path.email, { message: 'Email обязателен' });
+ *
+ *   // Вложенные объекты
+ *   required(path.registrationAddress.city);
+ *   minLength(path.registrationAddress.street, 3);
+ *
+ *   applyWhen(
+ *     path.loanType,
+ *     (type) => type === 'mortgage',
+ *     (path) => {
+ *       required(path.propertyValue, { message: 'Укажите стоимость' });
+ *     }
+ *   );
+ * };
+ * ```
+ */
+export type FieldPath<T> = {
+    [K in keyof T]: NonNullable<T[K]> extends Array<unknown> ? FieldPathNode<T, T[K], K> : NonNullable<T[K]> extends Date | File | Blob | AnyFunction ? FieldPathNode<T, T[K], K> : NonNullable<T[K]> extends object ? FieldPathNode<T, T[K], K> & FieldPath<NonNullable<T[K]>> : FieldPathNode<T, T[K], K>;
+};
+/**
+ * Узел в пути поля
+ * Содержит метаинформацию о поле для валидации
+ */
+export interface FieldPathNode<TForm, TField, TKey = unknown> {
+    /** Ключ поля */
+    readonly __key: TKey;
+    /** Путь к полю (для вложенных объектов) */
+    readonly __path: string;
+    /** Тип формы */
+    readonly __formType?: TForm;
+    /** Тип поля */
+    readonly __fieldType?: TField;
+}

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

@@ -0,0 +1,89 @@
+import { FormProxy } from './form-proxy';
+import { FieldPathNode } from './field-path';
+import { FormNode } from '../nodes/form-node';
+import { FormValue } from './index';
+/**
+ * Единый контекст для работы с формой
+ *
+ * Предоставляет:
+ * - `form` - типизированный Proxy-доступ к полям формы
+ * - `setFieldValue` - безопасная установка значения (emitEvent: false)
+ */
+export interface FormContext<TForm> {
+    /**
+     * Форма с типизированным Proxy-доступом к полям
+     *
+     * Позволяет обращаться к полям напрямую через точечную нотацию:
+     * - `ctx.form.email` → FieldNode
+     * - `ctx.form.address.city` → FieldNode (вложенный)
+     * - `ctx.form.items` → ArrayNode
+     *
+     * @example
+     * ```typescript
+     * // Получить значение
+     * ctx.form.email.value.value
+     *
+     * // Установить значение (⚠️ может вызвать цикл в behavior!)
+     * ctx.form.email.setValue('new@mail.com')
+     *
+     * // Безопасно установить значение
+     * ctx.form.email.setValue('new@mail.com', { emitEvent: false })
+     *
+     * // Обновить пропсы компонента
+     * ctx.form.city.updateComponentProps({ options: cities })
+     *
+     * // Валидация поля
+     * await ctx.form.email.validate()
+     *
+     * // Работа с массивами
+     * ctx.form.items.push({ title: 'New' })
+     * ctx.form.items.clear()
+     * ```
+     */
+    readonly form: FormProxy<TForm>;
+    /**
+     * Безопасно установить значение поля по строковому пути или FieldPath
+     *
+     * Автоматически использует `emitEvent: false` для предотвращения
+     * бесконечных циклов в behavior схемах.
+     *
+     * @param path - Путь к полю (строка или FieldPath)
+     * @param value - Новое значение
+     *
+     * @example
+     * ```typescript
+     * // Сброс города при смене страны (строковый путь)
+     * watchField(path.country, (country, ctx) => {
+     *   ctx.setFieldValue('city', null);
+     * });
+     *
+     * // Использование FieldPath напрямую (более типобезопасно)
+     * watchField(path.country, (country, ctx) => {
+     *   ctx.setFieldValue(path.city, null);
+     * });
+     * ```
+     */
+    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

@@ -0,0 +1,105 @@
+import { FormFields } from './index';
+type FieldNode<_T> = any;
+type GroupNode<_T> = any;
+type ArrayNode<_T> = any;
+/**
+ * Мапит тип модели данных T на правильные типы узлов формы
+ *
+ * Рекурсивно определяет типы узлов на основе структуры данных:
+ * - `T[K] extends Array<infer U>` где U - объект → `FormArrayProxy<U>`
+ * - `T[K] extends Array<infer U>` где U - примитив → `FieldNode<T[K]>` (массив как обычное поле)
+ * - `T[K] extends object` → `FormProxy<T[K]>` (вложенная форма с типизацией)
+ * - `T[K]` примитив → `FieldNode<T[K]>` (простое поле)
+ *
+ * Использует NonNullable для правильной обработки опциональных полей
+ *
+ * @group Types
+ * @category Proxy Types
+ *
+ * @template T - Тип модели данных формы
+ */
+export type FormControlsProxy<T> = {
+    [K in keyof T]: NonNullable<T[K]> extends Array<infer U> ? U extends FormFields ? FormArrayProxy<U> : FieldNode<T[K]> : NonNullable<T[K]> extends FormFields ? NonNullable<T[K]> extends Date | File | Blob ? FieldNode<T[K]> : FormProxy<NonNullable<T[K]>> : FieldNode<T[K]>;
+};
+/**
+ * Комбинированный тип для GroupNode с Proxy доступом к полям
+ *
+ * Объединяет методы и свойства GroupNode с типизированными полями формы.
+ * Это позволяет использовать как API GroupNode, так и прямой доступ к полям.
+ *
+ * @group Types
+ * @category Proxy Types
+ *
+ * @template T - Тип модели данных формы
+ *
+ * @example
+ * ```typescript
+ * interface UserForm {
+ *   email: string;
+ *   profile: {
+ *     name: string;
+ *     age: number;
+ *   };
+ * }
+ *
+ * const form = createForm<UserForm>(schema);
+ *
+ * // Доступ к методам GroupNode
+ * await form.validate();
+ * const values = form.getValue();
+ * console.log(form.valid.value);
+ *
+ * // Прямой доступ к полям (через Proxy)
+ * form.email.setValue('test@mail.com');
+ * form.profile.name.setValue('John');
+ * ```
+ */
+export type FormProxy<T> = GroupNode<T> & FormControlsProxy<T>;
+/**
+ * Комбинированный тип для ArrayNode с Proxy доступом к элементам
+ *
+ * Объединяет методы и свойства ArrayNode с типизированным доступом к элементам массива.
+ *
+ * @group Types
+ * @category Proxy Types
+ *
+ * @template T - Тип модели данных элемента массива
+ *
+ * @example
+ * ```typescript
+ * interface TodoItem {
+ *   title: string;
+ *   completed: boolean;
+ * }
+ *
+ * const todos: FormArrayProxy<TodoItem> = new ArrayNode(schema);
+ *
+ * // Доступ к методам ArrayNode
+ * todos.push({ title: 'New todo', completed: false });
+ * todos.removeAt(0);
+ *
+ * // Доступ к элементам (через Proxy)
+ * todos.at(0)?.title.setValue('Updated title');
+ *
+ * // Итерация
+ * todos.forEach((item, i) => {
+ *   console.log(item.title.value.value);
+ * });
+ * ```
+ */
+export type FormArrayProxy<T extends FormFields> = ArrayNode<T> & {
+    /**
+     * Безопасный доступ к элементу массива по индексу
+     * Возвращает GroupNode с типизированными полями или undefined
+     */
+    at(index: number): FormProxy<T> | undefined;
+    /**
+     * Итерация по элементам массива с типизированными элементами
+     */
+    forEach(callback: (item: FormProxy<T>, index: number) => void): void;
+    /**
+     * Маппинг элементов массива с типизированными элементами
+     */
+    map<R>(callback: (item: FormProxy<T>, index: number) => R): R[];
+};
+export {};

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

@@ -0,0 +1,209 @@
+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
+ *
+ * @group Types
+ * @category Core Types
+ */
+export type FormValue = string | number | boolean | null | undefined | Date | File | FormValue[] | {
+    [key: string]: FormValue;
+};
+/**
+ * Type-safe alternative to 'any' for unknown form values
+ * Requires explicit type checking before use
+ * @internal
+ */
+export type UnknownFormValue = unknown;
+/**
+ * Синхронная функция валидации
+ * @group Types
+ * @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, options?: AsyncValidatorOptions) => Promise<ValidationError | null>;
+/**
+ * Ошибка валидации
+ * @group Types
+ * @category Validation Types
+ */
+export interface ValidationError {
+    code: string;
+    message: string;
+    params?: FormFields;
+    /** Severity level: 'error' (default) blocks submission, 'warning' shows message but allows submission */
+    severity?: 'error' | 'warning';
+}
+/**
+ * Опции для фильтрации ошибок в методе getErrors()
+ * @group Types
+ * @category Validation Types
+ */
+export interface ErrorFilterOptions {
+    /** Фильтр по коду ошибки */
+    code?: string | string[];
+    /** Фильтр по сообщению (поддерживает частичное совпадение) */
+    message?: string;
+    /** Фильтр по параметрам ошибки */
+    params?: FormFields;
+    /** Кастомный предикат для фильтрации */
+    predicate?: (error: ValidationError) => boolean;
+}
+/**
+ * Статус поля формы
+ * @group Types
+ * @category Core Types
+ */
+export type FieldStatus = 'valid' | 'invalid' | 'pending' | 'disabled';
+export type { FieldConfig } from './deep-schema';
+export type { FieldPath, FieldPathNode } from '../types/field-path';
+export type { ContextualValidatorFn, ContextualAsyncValidatorFn, TreeValidatorFn, ConditionFn, ValidateOptions, ValidateAsyncOptions, ValidateTreeOptions, ValidationSchemaFn, ValidatorRegistration, } from './validation-schema';
+export type { FormSchema, ArrayConfig } from './deep-schema';
+export type { FormContext } from './form-context';
+export type { FormControlsProxy, FormProxy, FormArrayProxy } from './form-proxy';
+/**
+ * Конфигурация GroupNode с поддержкой схем
+ * Используется для создания форм с автоматическим применением behavior и validation схем
+ *
+ * @group Types
+ * @category Configuration Types
+ */
+export interface GroupNodeConfig<T> {
+    /** Схема структуры формы (поля и их конфигурация) */
+    form: FormSchema<T>;
+    /** Схема реактивного поведения (copyFrom, enableWhen, computeFrom и т.д.) */
+    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 значениями
+ * Используется вместо инлайнового `Record<string, unknown>`
+ * @internal
+ */
+export type UnknownRecord = Record<string, any>;
+/**
+ * Интерфейс для узлов с методом applyValidationSchema
+ * @internal
+ */
+export interface WithValidationSchema {
+    applyValidationSchema(schemaFn: unknown): void;
+}
+/**
+ * Интерфейс для узлов с методом applyBehaviorSchema
+ * @internal
+ */
+export interface WithBehaviorSchema {
+    applyBehaviorSchema(schemaFn: unknown): void;
+}
+/**
+ * Интерфейс для узлов, похожих на ArrayNode (с методом at)
+ * Используется для duck typing при обходе путей
+ * @internal
+ */
+export interface ArrayNodeLike {
+    at(index: number): FormNode<unknown> | undefined;
+    length: unknown;
+}
+/**
+ * Конфиг с полем schema (для ArrayConfig)
+ * @internal
+ */
+export interface ConfigWithSchema {
+    schema: unknown;
+    initialItems?: unknown[];
+}
+/**
+ * Конфиг с полем value (для извлечения значений)
+ * @internal
+ */
+export interface ConfigWithValue {
+    value: unknown;
+}
+/**
+ * Тип для конфига с полями (FormSchema generic constraint)
+ * Используется вместо `Record<string, any>` для схем форм
+ * @deprecated
+ * @internal
+ */
+export type FormFields = Record<string, FormValue>;
+/**
+ * Тип для путей к полям (field paths)
+ * Используется в навигации по полям вместо any
+ * @internal
+ */
+export type FieldPathSegment = {
+    key: string;
+    index?: number;
+};
+/**
+ * Тип для коллбэков и обработчиков событий
+ * Используется вместо (...args: any[]) => any
+ * @internal
+ */
+export type UnknownCallback = (...args: unknown[]) => unknown;
+/**
+ * Тип для проверки на функцию в conditional types
+ * Используется вместо Function для type narrowing
+ * @internal
+ */
+export type AnyFunction = (...args: never[]) => unknown;
+/**
+ * Тип для результатов загрузки ресурсов
+ * @internal
+ */
+export type ResourceLoadResult = unknown;

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

@@ -0,0 +1,95 @@
+import { FormFields, ValidationError } from './index';
+import { FieldPath } from './field-path';
+import { FormContext } from './form-context';
+/**
+ * Функция валидации поля с контекстом
+ *
+ * Новый паттерн: (value, ctx: FormContext) => ValidationError | null
+ *
+ * @example
+ * ```typescript
+ * validate(path.email, (value, ctx) => {
+ *   if (!value) return { code: 'required', message: 'Email required' };
+ *   const confirm = ctx.form.confirmEmail.value.value;
+ *   if (value !== confirm) return { code: 'mismatch', message: 'Must match' };
+ *   return null;
+ * });
+ * ```
+ */
+export type ContextualValidatorFn<TForm, TField> = (value: TField, ctx: FormContext<TForm>) => ValidationError | null;
+/**
+ * Асинхронная функция валидации поля с контекстом
+ *
+ * @example
+ * ```typescript
+ * validateAsync(path.email, async (value, ctx) => {
+ *   const exists = await checkEmailExists(value);
+ *   if (exists) return { code: 'exists', message: 'Email already taken' };
+ *   return null;
+ * });
+ * ```
+ */
+export type ContextualAsyncValidatorFn<TForm, TField> = (value: TField, ctx: FormContext<TForm>) => Promise<ValidationError | null>;
+/**
+ * Функция cross-field валидации
+ *
+ * @example
+ * ```typescript
+ * validateTree((ctx) => {
+ *   const password = ctx.form.password.value.value;
+ *   const confirm = ctx.form.confirmPassword.value.value;
+ *   if (password !== confirm) {
+ *     return { code: 'mismatch', message: 'Passwords must match' };
+ *   }
+ *   return null;
+ * });
+ * ```
+ */
+export type TreeValidatorFn<TForm> = (ctx: FormContext<TForm>) => ValidationError | null;
+/**
+ * Функция условия для applyWhen
+ */
+export type ConditionFn<T> = (value: T) => boolean;
+/**
+ * Опции для функции validate
+ */
+export interface ValidateOptions {
+    /** Сообщение об ошибке */
+    message?: string;
+    /** Параметры ошибки */
+    params?: FormFields;
+}
+/**
+ * Опции для функции validateAsync
+ */
+export interface ValidateAsyncOptions extends ValidateOptions {
+    /** Задержка перед выполнением валидации (в мс) */
+    debounce?: number;
+}
+/**
+ * Опции для функции validateTree
+ */
+export interface ValidateTreeOptions {
+    /** Поле, к которому привязать ошибку */
+    targetField?: string;
+}
+/**
+ * Функция validation schema
+ *
+ * Принимает FieldPath и определяет все правила валидации для формы
+ */
+export type ValidationSchemaFn<T> = (path: FieldPath<T>) => void;
+/**
+ * Регистрация валидатора в системе
+ * @internal
+ */
+export interface ValidatorRegistration {
+    fieldPath: string;
+    type: 'sync' | 'async' | 'tree';
+    validator: ContextualValidatorFn<unknown, unknown> | ContextualAsyncValidatorFn<unknown, unknown> | TreeValidatorFn<unknown>;
+    options?: ValidateOptions | ValidateAsyncOptions | ValidateTreeOptions;
+    condition?: {
+        fieldPath: string;
+        conditionFn: ConditionFn<unknown>;
+    };
+}

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