@reformer/core 2.0.0-beta.7 → 2.0.0-beta.8

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

package/dist/core/utils/type-guards.d.ts

@@ -1,26 +1,8 @@
-/**
- * Type Guards - централизованные функции проверки типов узлов
- *
- * Устраняет дублирование между form-node.ts, validation-applicator.ts и validation-context.ts
- *
- * @group Utilities
- * @category Type Guards
- *
- * @example
- * ```typescript
- * import { isFieldNode, isGroupNode } from '@/core/utils/type-guards';
- *
- * if (isFieldNode(node)) {
- *   // TypeScript знает, что node это FieldNode
- *   node.validators;
- * }
- * ```
- */
-import type { FormNode } from '../nodes/form-node';
-import type { FieldNode } from '../nodes/field-node';
-import type { GroupNode } from '../nodes/group-node';
-import type { ArrayNode } from '../nodes/array-node';
-import type { FormFields, FormValue } from '../types';
+import { FormNode } from '../nodes/form-node';
+import { FieldNode } from '../nodes/field-node';
+import { GroupNode } from '../nodes/group-node';
+import { ArrayNode } from '../nodes/array-node';
+import { FormFields, FormValue } from '../types';
 /**
  * Проверить, является ли значение любым FormNode
  *

package/dist/core/utils/unique-id.d.ts

@@ -7,18 +7,45 @@
  *
  * @example
  * ```typescript
- * const key1 = uniqueId('watch'); // "watch-1"
- * const key2 = uniqueId('watch'); // "watch-2"
- * const key3 = uniqueId('effect'); // "effect-3"
+ * const key1 = uniqueId(SubscriptionKey.Watch); // "watch-1"
+ * const key2 = uniqueId(SubscriptionKey.Watch); // "watch-2"
+ * const key3 = uniqueId(SubscriptionKey.ComputeFrom); // "computeFrom-3"
  * ```
  */
 /**
- * Генерирует уникальный идентификатор с указанным префиксом
+ * Типобезопасные ключи для подписок
+ * Используются с uniqueId() для генерации уникальных идентификаторов
+ */
+export declare const SubscriptionKey: {
+    /** FieldNode.watch() */
+    readonly Watch: "watch";
+    /** FieldNode.computeFrom() */
+    readonly ComputeFrom: "computeFrom";
+    /** GroupNode.linkFields() */
+    readonly LinkFields: "linkFields";
+    /** GroupNode.watchField() */
+    readonly WatchField: "watchField";
+    /** ArrayNode.watchItems() */
+    readonly WatchItems: "watchItems";
+    /** ArrayNode.watchLength() */
+    readonly WatchLength: "watchLength";
+};
+export type SubscriptionKeyType = (typeof SubscriptionKey)[keyof typeof SubscriptionKey];
+/**
+ * Генерирует уникальный идентификатор с указанным префиксом.
  *
- * @param prefix - Префикс для идентификатора
- * @returns Уникальный идентификатор в формате `${prefix}-${counter}`
+ * @param prefix - Префикс для идентификатора (используйте {@link SubscriptionKey}).
+ * @returns Уникальный идентификатор в формате `${prefix}-${counter}`.
+ *
+ * @example
+ * ```typescript
+ * import { uniqueId, SubscriptionKey } from '@reformer/core';
+ *
+ * uniqueId(SubscriptionKey.WatchField); // → 'watchField-1'
+ * uniqueId(SubscriptionKey.WatchField); // → 'watchField-2'
+ * ```
  */
-export declare function uniqueId(prefix: string): string;
+export declare function uniqueId(prefix: SubscriptionKeyType): string;
 /**
  * Сбросить счётчик (только для тестов)
  * @internal

package/dist/core/validation/core/apply-when.d.ts

@@ -1,12 +1,6 @@
-/**
- * Условная валидация
- *
- * @group Validation
- * @category Core Functions
- */
-import type { FieldPath } from '../../types/field-path';
-import type { ConditionFn } from '../../types/validation-schema';
-import type { FieldPathNode } from '../../types';
+import { FieldPath } from '../../types/field-path';
+import { ConditionFn } from '../../types/validation-schema';
+import { FieldPathNode } from '../../types';
 /**
  * Применить валидацию только при выполнении условия
  *

package/dist/core/validation/core/apply.d.ts

@@ -1,16 +1,5 @@
-/**
- * Композиция validation схем
- *
- * Предоставляет функции для переиспользования validation схем:
- * - apply: применение схемы к полям (новый API)
- *
- * Дополняет существующий toFieldPath и applyWhen.
- *
- * @group Validation
- * @category Core Functions
- */
-import type { FieldPathNode, FieldPath } from '../../types';
-import type { ValidationSchemaFn } from '../../types/validation-schema';
+import { FieldPathNode, FieldPath } from '../../types';
+import { ValidationSchemaFn } from '../../types/validation-schema';
 /**
  * Применить validation схему к корневому path формы
  *

package/dist/core/validation/core/validate-async.d.ts

@@ -1,11 +1,5 @@
-/**
- * Асинхронная валидация поля
- *
- * @group Validation
- * @category Core Functions
- */
-import type { ContextualAsyncValidatorFn, ValidateAsyncOptions } from '../../types/validation-schema';
-import type { FieldPathNode } from '../../types';
+import { ContextualAsyncValidatorFn, ValidateAsyncOptions } from '../../types/validation-schema';
+import { FieldPathNode } from '../../types';
 /**
  * Зарегистрировать асинхронный валидатор для поля
  *

package/dist/core/validation/core/validate-tree.d.ts

@@ -1,9 +1,3 @@
-/**
- * Cross-field валидация
- *
- * @group Validation
- * @category Core Functions
- */
 import { TreeValidatorFn, ValidateTreeOptions } from '../../types';
 /**
  * Зарегистрировать cross-field валидатор

package/dist/core/validation/core/validate.d.ts

@@ -1,10 +1,4 @@
-/**
- * Кастомная синхронная валидация поля
- *
- * @group Validation
- * @category Core Functions
- */
-import type { ContextualValidatorFn, FieldPathNode, ValidateOptions } from '../../types';
+import { ContextualValidatorFn, FieldPathNode, ValidateOptions } from '../../types';
 /**
  * Зарегистрировать кастомный синхронный валидатор для поля
  * Поддерживает опциональные поля

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

@@ -13,9 +13,15 @@ export { pattern } from './validators/pattern';
 export { url } from './validators/url';
 export { phone, type PhoneFormat } from './validators/phone';
 export { number } from './validators/number';
-export { date } from './validators/date';
+export { isDate } from './validators/is-date';
+export { minDate } from './validators/min-date';
+export { maxDate } from './validators/max-date';
+export { pastDate } from './validators/past-date';
+export { futureDate } from './validators/future-date';
+export { minAge } from './validators/min-age';
+export { maxAge } from './validators/max-age';
 export { notEmpty, validateItems } from './validators/array-validators';
-export { createFieldPath, extractPath, extractKey, toFieldPath } from './field-path';
+export { createFieldPath, extractPath, extractKey, toFieldPath } from '../utils/field-path';
 export { validateForm } from './validate-form';
 export { ValidationRegistry } from './validation-registry';
 export { ValidationContextImpl, TreeValidationContextImpl } from './validation-context';

package/dist/core/validation/validate-form.d.ts

@@ -1,42 +1,5 @@
-/**
- * validateForm - утилита для валидации формы в соответствии со схемой
- *
- * Позволяет применить validation schema к форме без изменения
- * зарегистрированной схемы в ValidationRegistry.
- *
- * ## Использование
- *
- * - **Multi-step формы**: валидация только полей текущего шага
- * - **Условная валидация**: применение разных схем в зависимости от состояния
- * - **Временная валидация**: проверка без сохранения в реестр
- *
- * ## Как это работает
- *
- * 1. Создаётся временный ValidationRegistry для схемы
- * 2. Валидируются все FieldNode (field-level валидаторы из FieldConfig)
- * 3. Применяются ТОЛЬКО contextual validators из переданной схемы
- * 4. Временный реестр отменяется (не сохраняется в форму)
- *
- * ## Важно для multi-step форм
- *
- * Форма может быть создана С полной схемой валидации:
- * ```typescript
- * createForm({
- *   form: schema,
- *   validation: fullValidation, // Полная схема
- * });
- * ```
- *
- * При этом `validateForm(form, stepSchema)` будет применять
- * только валидаторы из `stepSchema`, игнорируя валидаторы
- * из других шагов.
- *
- * @see docs/multi-step-validation.md для подробной документации
- *
- * @module validation
- */
 import { GroupNode } from '../nodes/group-node';
-import type { ValidationSchemaFn, FormFields } from '../types';
+import { ValidationSchemaFn, FormFields } from '../types';
 /**
  * Валидировать форму в соответствии с указанной схемой
  *

package/dist/core/validation/validation-applicator.d.ts

@@ -1,24 +1,5 @@
-/**
- * Применение валидаторов к форме
- *
- * Извлечено из GroupNode для соблюдения SRP (Single Responsibility Principle).
- * Отвечает только за логику применения валидаторов к полям формы.
- *
- * @template T Тип формы
- *
- * @example
- * ```typescript
- * class GroupNode {
- *   private readonly validationApplicator = new ValidationApplicator(this);
- *
- *   async applyContextualValidators(validators: ValidatorRegistration[]) {
- *     await this.validationApplicator.apply(validators);
- *   }
- * }
- * ```
- */
-import type { GroupNode } from '../nodes/group-node';
-import type { ValidatorRegistration } from '../types';
+import { GroupNode } from '../nodes/group-node';
+import { ValidatorRegistration } from '../types';
 /**
  * Класс для применения валидаторов к форме
  *

package/dist/core/validation/validation-context.d.ts

@@ -1,13 +1,7 @@
-/**
- * Реализация контекста валидации
- *
- * Использует паттерн наследования для устранения дублирования кода
- * между различными типами контекстов валидации.
- */
-import type { GroupNode } from '../nodes/group-node';
-import type { FieldNode } from '../nodes/field-node';
-import type { FormProxy } from '../types/form-proxy';
-import type { FormContext } from '../types/form-context';
+import { GroupNode } from '../nodes/group-node';
+import { FieldNode } from '../nodes/field-node';
+import { FormProxy } from '../types/form-proxy';
+import { FormContext } from '../types/form-context';
 /**
  * Базовый класс контекста валидации
  * Содержит общую логику для всех типов контекстов
@@ -25,10 +19,27 @@ declare abstract class BaseValidationContext<TForm> implements FormContext<TForm
      * Автоматически использует emitEvent: false для предотвращения циклов
      */
     setFieldValue(path: string, value: unknown): void;
+    /**
+     * Получить поле формы по строковому пути
+     */
+    getFieldByPath(path: string): import('../..').FormNode<import('../types').FormValue> | undefined;
 }
 /**
- * Контекст валидации для отдельного поля
- * Предоставляет доступ к значению конкретного поля
+ * Контекст валидации одного поля. Создаётся фреймворком и передаётся в валидаторы
+ * (`required`, `validate`, …) — напрямую инстанцировать не нужно.
+ *
+ * @example
+ * ```typescript
+ * import { validate } from '@reformer/core/validators';
+ *
+ * validate(path.password, (value, ctx) => {
+ *   // ctx — экземпляр ValidationContextImpl, доступ к ctx.form для cross-field логики
+ *   if (value !== ctx.form.confirmPassword.value) {
+ *     return { code: 'mismatch', message: 'Пароли не совпадают' };
+ *   }
+ *   return null;
+ * });
+ * ```
  */
 export declare class ValidationContextImpl<TForm, TField> extends BaseValidationContext<TForm> {
     private control;
@@ -40,8 +51,21 @@ export declare class ValidationContextImpl<TForm, TField> extends BaseValidation
     value(): TField;
 }
 /**
- * Контекст для cross-field валидации
- * Не предоставляет доступ к конкретному полю, только к форме целиком
+ * Контекст cross-field валидации. Передаётся в `validateTree`/`validateForm`
+ * callback'и — напрямую инстанцировать не нужно.
+ *
+ * @example
+ * ```typescript
+ * import { validateForm } from '@reformer/core';
+ *
+ * validateForm(form, (ctx) => {
+ *   // ctx — экземпляр TreeValidationContextImpl
+ *   if (ctx.form.startDate.value > ctx.form.endDate.value) {
+ *     return [{ code: 'date-range', message: 'Дата начала позже даты окончания' }];
+ *   }
+ *   return [];
+ * });
+ * ```
  */
 export declare class TreeValidationContextImpl<TForm> extends BaseValidationContext<TForm> {
     constructor(form: GroupNode<TForm>);

package/dist/core/validation/validation-registry.d.ts

@@ -1,16 +1,10 @@
-/**
- * ValidationRegistry - система регистрации и применения валидаторов
- *
- * Работает как стек контекстов:
- * 1. При вызове validation schema функции создается новый контекст
- * 2. Все вызовы validate(), applyWhen() и т.д. регистрируют валидаторы в текущем контексте
- * 3. После завершения схемы валидаторы применяются к GroupNode
- */
-import type { GroupNode } from '../nodes/group-node';
+import { GroupNode } from '../nodes/group-node';
 import { FormFields } from '../types';
-import type { ValidatorRegistration, ContextualValidatorFn, ContextualAsyncValidatorFn, TreeValidatorFn, ConditionFn, ValidateOptions, ValidateAsyncOptions, ValidateTreeOptions } from '../types/validation-schema';
+import { AbstractRegistry } from '../utils/abstract-registry';
+import { ValidatorRegistration, ContextualValidatorFn, ContextualAsyncValidatorFn, TreeValidatorFn, ConditionFn, ValidateOptions, ValidateAsyncOptions, ValidateTreeOptions } from '../types/validation-schema';
 /**
  * Контекст регистрации валидаторов
+ * Управляет condition stack для условных валидаторов
  */
 declare class RegistrationContext {
     private validators;
@@ -38,10 +32,9 @@ declare class RegistrationContext {
  * Каждый экземпляр GroupNode создает собственный реестр (композиция).
  * Устраняет race conditions и изолирует формы друг от друга.
  *
- * Context stack используется для tracking текущего активного реестра:
- * - beginRegistration() помещает this в global stack
- * - endRegistration() извлекает из global stack
- * - getCurrent() возвращает текущий активный реестр
+ * Наследует AbstractRegistry для унификации:
+ * - Управления global stack
+ * - Template methods begin/end registration
  *
  * @example
  * ```typescript
@@ -56,13 +49,10 @@ declare class RegistrationContext {
  * }
  * ```
  */
-export declare class ValidationRegistry {
-    /**
-     * Global stack активных реестров
-     * Используется для изоляции форм друг от друга
-     */
-    private static registryStack;
+export declare class ValidationRegistry extends AbstractRegistry<ValidatorRegistration> {
+    /** Внутренний стек контекстов для управления condition blocks */
     private contextStack;
+    /** Финальные валидаторы после завершения регистрации */
     private validators;
     /**
      * Получить текущий активный реестр из global stack
@@ -85,6 +75,7 @@ export declare class ValidationRegistry {
      * Начать регистрацию валидаторов для формы
      *
      * Помещает this в global stack для изоляции форм
+     * Создает новый RegistrationContext для condition management
      */
     beginRegistration(): RegistrationContext;
     /**

package/dist/core/validation/validators/array-validators.d.ts

@@ -1,15 +1,5 @@
-/**
- * Валидаторы для массивов
- *
- * Предоставляет специализированные функции для валидации ArrayNode:
- * - notEmpty: проверка что массив не пустой
- * - validateItems: применение validation schema к каждому элементу
- *
- * @group Validation
- * @category Validators
- */
-import type { ValidateOptions, ValidationSchemaFn } from '../../types/validation-schema';
-import type { FieldPathNode } from '../../types';
+import { ValidateOptions, ValidationSchemaFn } from '../../types/validation-schema';
+import { FieldPathNode } from '../../types';
 /**
  * Проверить что массив содержит хотя бы один элемент
  *

package/dist/core/validation/validators/date-utils.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Утилиты для работы с датами в валидаторах
+ *
+ * @group Validation
+ * @category Validators
+ * @module validators/date-utils
+ */
+/**
+ * Парсит значение в объект Date
+ *
+ * @param value - Значение для парсинга (Date, string или undefined)
+ * @returns Date объект или null если парсинг не удался
+ */
+export declare function parseDate(value: string | Date | null | undefined): Date | null;
+/**
+ * Возвращает сегодняшнюю дату с обнулённым временем
+ */
+export declare function getToday(): Date;
+/**
+ * Нормализует дату, обнуляя время
+ */
+export declare function normalizeDate(date: Date): Date;
+/**
+ * Вычисляет возраст на основе даты рождения
+ */
+export declare function calculateAge(birthDate: Date): number;

package/dist/core/validation/validators/email.d.ts

@@ -1,12 +1,5 @@
-/**
- * Валидатор формата email
- *
- * @group Validation
- * @category Validators
- * @module validators/email
- */
-import type { ValidateOptions } from '../../types/validation-schema';
-import type { FieldPathNode } from '../../types';
+import { ValidateOptions } from '../../types/validation-schema';
+import { FieldPathNode } from '../../types';
 /**
  * Валидатор формата email
  *

package/dist/core/validation/validators/future-date.d.ts

@@ -0,0 +1,35 @@
+import { ValidateOptions } from '../../types/validation-schema';
+import { FieldPathNode } from '../../types';
+/**
+ * Проверяет, что дата находится в будущем (не в прошлом)
+ *
+ * Пустые значения и невалидные даты пропускаются (используйте `required` и `isDate`).
+ *
+ * @group Validation
+ * @category Validators
+ *
+ * @param fieldPath - Путь к полю для валидации
+ * @param options - Опции валидации (message, params)
+ *
+ * @example
+ * ```typescript
+ * // Базовое использование - дата события должна быть в будущем
+ * validationSchema: (path) => [
+ *   futureDate(path.eventDate),
+ * ]
+ *
+ * // С кастомным сообщением
+ * futureDate(path.appointmentDate, { message: 'Дата записи должна быть в будущем' })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Ошибка валидации
+ * {
+ *   code: 'date_past',
+ *   message: 'Дата не может быть в прошлом',
+ *   params: {}
+ * }
+ * ```
+ */
+export declare function futureDate<TForm, TField extends string | Date | undefined = string | Date>(fieldPath: FieldPathNode<TForm, TField> | undefined, options?: ValidateOptions): void;

package/dist/core/validation/validators/index.d.ts

@@ -11,4 +11,10 @@ export { pattern } from './pattern';
 export { url } from './url';
 export { phone, type PhoneFormat } from './phone';
 export { number } from './number';
-export { date } from './date';
+export { isDate } from './is-date';
+export { minDate } from './min-date';
+export { maxDate } from './max-date';
+export { pastDate } from './past-date';
+export { futureDate } from './future-date';
+export { minAge } from './min-age';
+export { maxAge } from './max-age';