@reformer/core 1.0.0-beta.1

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

@@ -0,0 +1,44 @@
+import { FormProxy, GroupNodeConfig, FormSchema } from '../types';
+/**
+ * Создать форму с полной конфигурацией (form, behavior, validation)
+ *
+ * @group Utilities
+ *
+ * @param config - Конфигурация формы с полями, поведением и валидацией
+ * @returns Типизированная форма с Proxy-доступом к полям
+ *
+ * @example
+ * ```typescript
+ * const form = createForm<UserForm>({
+ *   form: {
+ *     email: { value: '', component: Input },
+ *     password: { value: '', component: Input },
+ *   },
+ *   validation: (path) => {
+ *     required(path.email);
+ *     email(path.email);
+ *     required(path.password);
+ *     minLength(path.password, 8);
+ *   },
+ * });
+ *
+ * // TypeScript знает о полях:
+ * form.email.setValue('test@mail.com');
+ * ```
+ */
+export declare function createForm<T>(config: GroupNodeConfig<T>): FormProxy<T>;
+/**
+ * Создать форму только со схемой полей (обратная совместимость)
+ *
+ * @param schema - Схема полей формы
+ * @returns Типизированная форма с Proxy-доступом к полям
+ *
+ * @example
+ * ```typescript
+ * const form = createForm<UserForm>({
+ *   email: { value: '', component: Input },
+ *   password: { value: '', component: Input },
+ * });
+ * ```
+ */
+export declare function createForm<T>(schema: FormSchema<T>): FormProxy<T>;

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

@@ -0,0 +1,163 @@
+import { ValidationError } from '../types';
+/**
+ * Стратегия обработки ошибок
+ *
+ * Определяет, что делать с ошибкой после логирования
+ */
+export declare enum ErrorStrategy {
+    /**
+     * Пробросить ошибку дальше (throw)
+     * Используется когда ошибка критична и должна остановить выполнение
+     */
+    THROW = "throw",
+    /**
+     * Залогировать и проглотить ошибку (продолжить выполнение)
+     * Используется когда ошибка не критична
+     */
+    LOG = "log",
+    /**
+     * Конвертировать ошибку в ValidationError
+     * Используется в async validators для отображения ошибки валидации пользователю
+     */
+    CONVERT = "convert"
+}
+/**
+ * Централизованный обработчик ошибок для форм
+ *
+ * Обеспечивает:
+ * - Единообразное логирование ошибок в DEV режиме
+ * - Гибкие стратегии обработки (throw/log/convert)
+ * - Типобезопасное извлечение сообщений из Error/string/unknown
+ *
+ * @example
+ * ```typescript
+ * // В async validator (конвертировать в ValidationError)
+ * try {
+ *   await validateEmail(value);
+ * } catch (error) {
+ *   return FormErrorHandler.handle(error, 'EmailValidator', ErrorStrategy.CONVERT);
+ * }
+ *
+ * // В behavior applicator (пробросить критичную ошибку)
+ * try {
+ *   applyBehavior(schema);
+ * } catch (error) {
+ *   FormErrorHandler.handle(error, 'BehaviorApplicator', ErrorStrategy.THROW);
+ * }
+ *
+ * // В validator (залогировать и продолжить)
+ * try {
+ *   validator(value);
+ * } catch (error) {
+ *   FormErrorHandler.handle(error, 'Validator', ErrorStrategy.LOG);
+ * }
+ * ```
+ */
+export declare class FormErrorHandler {
+    /**
+     * Обработать ошибку согласно заданной стратегии
+     *
+     * @param error Ошибка для обработки (Error | string | unknown)
+     * @param context Контекст ошибки для логирования (например, 'AsyncValidator', 'BehaviorRegistry')
+     * @param strategy Стратегия обработки (THROW | LOG | CONVERT)
+     * @returns ValidationError если strategy = CONVERT, undefined если strategy = LOG, никогда не возвращается если strategy = THROW
+     *
+     * @example
+     * ```typescript
+     * // THROW - пробросить ошибку
+     * try {
+     *   riskyOperation();
+     * } catch (error) {
+     *   FormErrorHandler.handle(error, 'RiskyOperation', ErrorStrategy.THROW);
+     *   // Этот код никогда не выполнится
+     * }
+     *
+     * // LOG - залогировать и продолжить
+     * try {
+     *   nonCriticalOperation();
+     * } catch (error) {
+     *   FormErrorHandler.handle(error, 'NonCritical', ErrorStrategy.LOG);
+     *   // Продолжаем выполнение
+     * }
+     *
+     * // CONVERT - конвертировать в ValidationError
+     * try {
+     *   await validator(value);
+     * } catch (error) {
+     *   const validationError = FormErrorHandler.handle(
+     *     error,
+     *     'AsyncValidator',
+     *     ErrorStrategy.CONVERT
+     *   );
+     *   return validationError;
+     * }
+     * ```
+     */
+    static handle(error: unknown, context: string, strategy?: ErrorStrategy): ValidationError | never | void;
+    /**
+     * Извлечь сообщение из ошибки
+     *
+     * Обрабатывает различные типы ошибок:
+     * - Error объекты → error.message
+     * - Строки → возвращает как есть
+     * - Объекты с message → извлекает message
+     * - Другое → String(error)
+     *
+     * @param error Ошибка для извлечения сообщения
+     * @returns Сообщение ошибки
+     * @private
+     *
+     * @example
+     * ```typescript
+     * FormErrorHandler.extractMessage(new Error('Test'));
+     * // 'Test'
+     *
+     * FormErrorHandler.extractMessage('String error');
+     * // 'String error'
+     *
+     * FormErrorHandler.extractMessage({ message: 'Object error' });
+     * // 'Object error'
+     *
+     * FormErrorHandler.extractMessage(null);
+     * // 'null'
+     * ```
+     */
+    private static extractMessage;
+    /**
+     * Создать ValidationError с заданными параметрами
+     *
+     * Утилитная функция для создания ValidationError объектов
+     *
+     * @param code Код ошибки
+     * @param message Сообщение ошибки
+     * @param field Поле (опционально)
+     * @returns ValidationError объект
+     *
+     * @example
+     * ```typescript
+     * const error = FormErrorHandler.createValidationError(
+     *   'required',
+     *   'This field is required',
+     *   'email'
+     * );
+     * // { code: 'required', message: 'This field is required', field: 'email' }
+     * ```
+     */
+    static createValidationError(code: string, message: string, field?: string): ValidationError;
+    /**
+     * Проверить, является ли объект ValidationError
+     *
+     * Type guard для ValidationError
+     *
+     * @param value Значение для проверки
+     * @returns true если value является ValidationError
+     *
+     * @example
+     * ```typescript
+     * if (FormErrorHandler.isValidationError(result)) {
+     *   console.log(result.code); // OK, типобезопасно
+     * }
+     * ```
+     */
+    static isValidationError(value: unknown): value is ValidationError;
+}

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

@@ -0,0 +1,240 @@
+import { UnknownRecord } from '../types';
+/**
+ * Сегмент пути к полю формы
+ *
+ * Представляет один сегмент в пути к полю, например:
+ * - `"email" → { key: 'email' }`
+ * - `"items[0]" → { key: 'items', index: 0 }`
+ *
+ * @internal
+ *
+ * @example
+ * ```typescript
+ * // Путь "items[0].name" разбивается на:
+ * [
+ *   { key: 'items', index: 0 },
+ *   { key: 'name' }
+ * ]
+ * ```
+ */
+export interface PathSegment {
+    /**
+     * Ключ поля
+     */
+    key: string;
+    /**
+     * Индекс в массиве (опционально)
+     * Присутствует только для сегментов вида "items[0]"
+     */
+    index?: number;
+}
+/**
+ * Навигация по путям к полям формы
+ *
+ * Централизует логику парсинга и навигации по путям к полям формы.
+ * Используется в ValidationContext, BehaviorContext, GroupNode для единообразной
+ * обработки путей вида "address.city" или "items[0].name".
+ *
+ * Устраняет дублирование логики парсинга путей в 4 местах кодовой базы.
+ *
+ * @internal
+ *
+ * @example
+ * ```typescript
+ * const navigator = new FieldPathNavigator();
+ *
+ * // Парсинг пути
+ * const segments = navigator.parsePath('items[0].title');
+ * // [{ key: 'items', index: 0 }, { key: 'title' }]
+ *
+ * // Получение значения из объекта
+ * const obj = { items: [{ title: 'Item 1' }] };
+ * const value = navigator.getValueByPath(obj, 'items[0].title');
+ * // 'Item 1'
+ *
+ * // Получение узла формы
+ * const titleNode = navigator.getNodeByPath(form, 'items[0].title');
+ * titleNode?.setValue('New Title');
+ * ```
+ */
+export declare class FieldPathNavigator {
+    /**
+     * Парсит путь в массив сегментов
+     *
+     * Поддерживаемые форматы:
+     * - Простые пути: "name", "email"
+     * - Вложенные пути: "address.city", "user.profile.avatar"
+     * - Массивы: "items[0]", "items[0].name", "tags[1][0]"
+     * - Комбинации: "orders[0].items[1].price"
+     *
+     * @param path Путь к полю (строка с точками и квадратными скобками)
+     * @returns Массив сегментов пути
+     *
+     * @example
+     * ```typescript
+     * navigator.parsePath('email');
+     * // [{ key: 'email' }]
+     *
+     * navigator.parsePath('address.city');
+     * // [{ key: 'address' }, { key: 'city' }]
+     *
+     * navigator.parsePath('items[0].name');
+     * // [{ key: 'items', index: 0 }, { key: 'name' }]
+     * ```
+     */
+    parsePath(path: string): PathSegment[];
+    /**
+     * Добавляет сегмент в массив, обрабатывая массивы
+     * @private
+     */
+    private addSegment;
+    /**
+     * Получает значение по пути из объекта
+     *
+     * Проходит по всем сегментам пути и возвращает конечное значение.
+     * Если путь не найден, возвращает undefined.
+     *
+     * @param obj Объект для навигации
+     * @param path Путь к значению
+     * @returns Значение или undefined, если путь не найден
+     *
+     * @example
+     * ```typescript
+     * const obj = {
+     *   email: 'test@mail.com',
+     *   address: { city: 'Moscow' },
+     *   items: [{ title: 'Item 1' }]
+     * };
+     *
+     * navigator.getValueByPath(obj, 'email');
+     * // 'test@mail.com'
+     *
+     * navigator.getValueByPath(obj, 'address.city');
+     * // 'Moscow'
+     *
+     * navigator.getValueByPath(obj, 'items[0].title');
+     * // 'Item 1'
+     *
+     * navigator.getValueByPath(obj, 'invalid.path');
+     * // undefined
+     * ```
+     */
+    getValueByPath(obj: UnknownRecord, path: string): unknown;
+    /**
+     * Устанавливает значение по пути в объекте (мутирует объект)
+     *
+     * Создает промежуточные объекты, если они не существуют.
+     * Выбрасывает ошибку, если ожидается массив, но его нет.
+     *
+     * @param obj Объект для модификации
+     * @param path Путь к значению
+     * @param value Новое значение
+     *
+     * @throws {Error} Если ожидается массив по пути, но его нет
+     *
+     * @example
+     * ```typescript
+     * const obj = { address: { city: '' } };
+     * navigator.setValueByPath(obj, 'address.city', 'Moscow');
+     * // obj.address.city === 'Moscow'
+     *
+     * const obj2: UnknownRecord = {};
+     * navigator.setValueByPath(obj2, 'address.city', 'Moscow');
+     * // Создаст { address: { city: 'Moscow' } }
+     *
+     * const obj3 = { items: [{ title: 'Old' }] };
+     * navigator.setValueByPath(obj3, 'items[0].title', 'New');
+     * // obj3.items[0].title === 'New'
+     * ```
+     */
+    setValueByPath(obj: UnknownRecord, path: string, value: unknown): void;
+    /**
+     * Получить значение из FormNode по пути
+     *
+     * Автоматически извлекает значение из FormNode (через .value.value).
+     * Используется в ValidationContext и BehaviorContext для единообразного
+     * доступа к значениям полей формы.
+     *
+     * @param form Корневой узел формы (обычно GroupNode)
+     * @param path Путь к полю
+     * @returns Значение поля или undefined, если путь не найден
+     *
+     * @example
+     * ```typescript
+     * const form = new GroupNode({
+     *   email: { value: 'test@mail.com', component: Input },
+     *   address: {
+     *     city: { value: 'Moscow', component: Input }
+     *   },
+     *   items: [{ title: { value: 'Item 1', component: Input } }]
+     * });
+     *
+     * navigator.getFormNodeValue(form, 'email');
+     * // 'test@mail.com'
+     *
+     * navigator.getFormNodeValue(form, 'address.city');
+     * // 'Moscow'
+     *
+     * navigator.getFormNodeValue(form, 'items[0].title');
+     * // 'Item 1'
+     *
+     * navigator.getFormNodeValue(form, 'invalid.path');
+     * // undefined
+     * ```
+     */
+    getFormNodeValue(form: unknown, path: string): unknown;
+    /**
+     * Type guard для проверки, является ли объект FormNode
+     *
+     * Проверяет наличие характерных свойств FormNode:
+     * - value (Signal)
+     * - value.value (значение Signal)
+     *
+     * @param obj Объект для проверки
+     * @returns true, если объект является FormNode
+     * @private
+     */
+    private isFormNode;
+    /**
+     * Получает узел формы по пути
+     *
+     * Навигирует по структуре FormNode (GroupNode/FieldNode/ArrayNode)
+     * и возвращает узел по указанному пути.
+     *
+     * Поддерживает:
+     * - Доступ к полям GroupNode через fields Map
+     * - Доступ к элементам ArrayNode через индекс
+     * - Proxy-доступ к полям (для обратной совместимости)
+     *
+     * @param form Корневой узел формы (обычно GroupNode)
+     * @param path Путь к узлу
+     * @returns Узел формы или null, если путь не найден
+     *
+     * @example
+     * ```typescript
+     * const form = new GroupNode({
+     *   email: { value: '', component: Input },
+     *   address: {
+     *     city: { value: '', component: Input }
+     *   },
+     *   items: [{ title: { value: '', component: Input } }]
+     * });
+     *
+     * const emailNode = navigator.getNodeByPath(form, 'email');
+     * // FieldNode
+     *
+     * const cityNode = navigator.getNodeByPath(form, 'address.city');
+     * // FieldNode
+     *
+     * const itemNode = navigator.getNodeByPath(form, 'items[0]');
+     * // GroupNode
+     *
+     * const titleNode = navigator.getNodeByPath(form, 'items[0].title');
+     * // FieldNode
+     *
+     * const invalidNode = navigator.getNodeByPath(form, 'invalid.path');
+     * // null
+     * ```
+     */
+    getNodeByPath(form: unknown, path: string): unknown | null;
+}

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

@@ -0,0 +1,60 @@
+import { FieldPath, FieldPathNode } from '../types';
+/**
+ * Создать FieldPath proxy для формы
+ *
+ * @example
+ * ```typescript
+ * const path = createFieldPath<MyForm>();
+ * console.log(path.email.__path); // 'email'
+ * console.log(path.personalData.firstName.__path); // 'personalData.firstName'
+ * ```
+ */
+export declare function createFieldPath<T>(): FieldPath<T>;
+/**
+ * Извлечь строковый путь из {@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;
+/**
+ * Преобразовать FieldPathNode в FieldPath для переиспользования схем
+ *
+ * Позволяет композировать validation schemas:
+ *
+ * @example
+ * ```typescript
+ * const personalDataValidation = (path: FieldPath<PersonalData>) => {
+ *   required(path.firstName, { message: 'Имя обязательно' });
+ *   required(path.lastName, { message: 'Фамилия обязательна' });
+ * };
+ *
+ * const mainValidation = (path: FieldPath<MyForm>) => {
+ *   //  Переиспользуем схему
+ *   personalDataValidation(toFieldPath(path.personalData));
+ *   required(path.email);
+ * };
+ * ```
+ */
+export declare function toFieldPath<T>(node: FieldPathNode<unknown, T, never> | FieldPathNode<any, T, any>): FieldPath<T>;
+/**
+ * Извлечь имя последнего сегмента ({@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;