@reformer/core 1.0.0-beta.3

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

@@ -0,0 +1,78 @@
+/**
+ * Типы для схемы формы (Deep Schema)
+ *
+ * Автоматическое определение типов схемы на основе структуры данных:
+ * - `[{...}]` → массив форм
+ * - `{...}` → вложенная группа
+ * - `{value, component}` → конфигурация поля
+ *
+ * @group Types
+ */
+import type { ComponentType } from 'react';
+import type { 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/deep-schema.js

@@ -0,0 +1,11 @@
+/**
+ * Типы для схемы формы (Deep Schema)
+ *
+ * Автоматическое определение типов схемы на основе структуры данных:
+ * - `[{...}]` → массив форм
+ * - `{...}` → вложенная группа
+ * - `{value, component}` → конфигурация поля
+ *
+ * @group Types
+ */
+export {};

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

@@ -0,0 +1,42 @@
+import type { 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/field-path.js

@@ -0,0 +1,4 @@
+// ============================================================================
+// FieldPath - proxy для доступа к путям полей
+// ============================================================================
+export {};

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

@@ -0,0 +1,83 @@
+/**
+ * Единый контекст для работы с формой
+ *
+ * Используется в:
+ * - 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 { GroupNodeWithControls } from './group-node-proxy';
+/**
+ * Единый контекст для работы с формой
+ *
+ * Предоставляет:
+ * - `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: GroupNodeWithControls<TForm>;
+    /**
+     * Безопасно установить значение поля по строковому пути
+     *
+     * Автоматически использует `emitEvent: false` для предотвращения
+     * бесконечных циклов в behavior схемах.
+     *
+     * @param path - Путь к полю (например, "address.city", "items[0].name")
+     * @param value - Новое значение
+     *
+     * @example
+     * ```typescript
+     * // Сброс города при смене страны
+     * watchField(path.country, (country, ctx) => {
+     *   ctx.setFieldValue('city', null);
+     * });
+     * ```
+     */
+    setFieldValue(path: string, value: unknown): void;
+}

package/dist/core/types/form-context.js

@@ -0,0 +1,25 @@
+/**
+ * Единый контекст для работы с формой
+ *
+ * Используется в:
+ * - 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;
+ * });
+ * ```
+ */
+export {};

package/dist/core/types/group-node-proxy.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Типы для Proxy-доступа к полям GroupNode
+ *
+ * Решает проблему типизации, когда GroupNode<T> использует Proxy для прямого доступа к полям.
+ * TypeScript не может автоматически определить правильные типы для вложенных форм и массивов.
+ *
+ * @group Types
+ *
+ * @example
+ * ```typescript
+ * interface MyForm {
+ *   name: string;
+ *   address: {
+ *     city: string;
+ *   };
+ *   items: Array<{ title: string }>;
+ * }
+ *
+ * const form: GroupNodeWithControls<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';
+type FieldNode<_T> = any;
+type GroupNode<_T> = any;
+type ArrayNode<_T> = any;
+/**
+ * Мапит тип модели данных T на правильные типы узлов формы
+ *
+ * Рекурсивно определяет типы узлов на основе структуры данных:
+ * - `T[K] extends Array<infer U>` где U - объект → `ArrayNodeWithControls<U>`
+ * - `T[K] extends Array<infer U>` где U - примитив → `FieldNode<T[K]>` (массив как обычное поле)
+ * - `T[K] extends object` → `GroupNodeWithControls<T[K]>` (вложенная форма с типизацией)
+ * - `T[K]` примитив → `FieldNode<T[K]>` (простое поле)
+ *
+ * Использует NonNullable для правильной обработки опциональных полей
+ *
+ * @group Types
+ * @category Proxy Types
+ *
+ * @template T - Тип модели данных формы
+ */
+export type FormNodeControls<T> = {
+    [K in keyof T]: NonNullable<T[K]> extends Array<infer U> ? U extends FormFields ? ArrayNodeWithControls<U> : FieldNode<T[K]> : NonNullable<T[K]> extends FormFields ? NonNullable<T[K]> extends Date | File | Blob ? FieldNode<T[K]> : GroupNodeWithControls<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: GroupNodeWithControls<UserForm> = new GroupNode(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 GroupNodeWithControls<T> = GroupNode<T> & FormNodeControls<T>;
+/**
+ * Комбинированный тип для ArrayNode с Proxy доступом к элементам
+ *
+ * Объединяет методы и свойства ArrayNode с типизированным доступом к элементам массива.
+ *
+ * @group Types
+ * @category Proxy Types
+ *
+ * @template T - Тип модели данных элемента массива
+ *
+ * @example
+ * ```typescript
+ * interface TodoItem {
+ *   title: string;
+ *   completed: boolean;
+ * }
+ *
+ * const todos: ArrayNodeWithControls<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 ArrayNodeWithControls<T extends FormFields> = ArrayNode<T> & {
+    /**
+     * Безопасный доступ к элементу массива по индексу
+     * Возвращает GroupNode с типизированными полями или undefined
+     */
+    at(index: number): GroupNodeWithControls<T> | undefined;
+    /**
+     * Итерация по элементам массива с типизированными элементами
+     */
+    forEach(callback: (item: GroupNodeWithControls<T>, index: number) => void): void;
+    /**
+     * Маппинг элементов массива с типизированными элементами
+     */
+    map<R>(callback: (item: GroupNodeWithControls<T>, index: number) => R): R[];
+};
+export {};

package/dist/core/types/group-node-proxy.js

@@ -0,0 +1,31 @@
+/**
+ * Типы для Proxy-доступа к полям GroupNode
+ *
+ * Решает проблему типизации, когда GroupNode<T> использует Proxy для прямого доступа к полям.
+ * TypeScript не может автоматически определить правильные типы для вложенных форм и массивов.
+ *
+ * @group Types
+ *
+ * @example
+ * ```typescript
+ * interface MyForm {
+ *   name: string;
+ *   address: {
+ *     city: string;
+ *   };
+ *   items: Array<{ title: string }>;
+ * }
+ *
+ * const form: GroupNodeWithControls<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' });
+ * ```
+ */
+export {};

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

@@ -0,0 +1,163 @@
+/**
+ * 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 type AsyncValidatorFn<T = FormValue> = (value: T) => 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 { FormNodeControls, GroupNodeWithControls, ArrayNodeWithControls, } from './group-node-proxy';
+import type { BehaviorSchemaFn } from '../behavior/types';
+import type { FormSchema } from './deep-schema';
+import type { ValidationSchemaFn } from './validation-schema';
+/**
+ * Конфигурация 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>;
+}
+/**
+ * Тип для 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;
+}
+import type { FormNode } from '../nodes/form-node';
+/**
+ * Конфиг с полем 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/index.js

@@ -0,0 +1,4 @@
+// ============================================================================
+// Form Value Types
+// ============================================================================
+export {};

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

@@ -0,0 +1,104 @@
+/**
+ * Типы для 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';
+/**
+ * Функция валидации поля с контекстом
+ *
+ * Новый паттерн: (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>;
+    };
+}