@reformer/core 1.1.0 → 2.0.0-beta.3

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

@@ -0,0 +1,48 @@
+/**
+ * FieldPath proxy - типобезопасный доступ к путям полей формы
+ *
+ * Единый модуль для validation и behavior схем.
+ * Предоставляет типизированную навигацию по структуре формы.
+ *
+ * @module utils/field-path
+ */
+import type { 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>;
+/**
+ * Извлечь путь из FieldPathNode
+ */
+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>;
+/**
+ * Извлечь ключ поля из FieldPathNode
+ */
+export declare function extractKey(node: FieldPathNode<unknown, unknown> | unknown): string;

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

@@ -4,6 +4,7 @@
  * Централизованные вспомогательные классы и функции.
  */
 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';

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

@@ -13,13 +13,19 @@ import { TreeValidatorFn, ValidateTreeOptions } from '../../types';
  * @group Validation
  * @category Core Functions
  *
+ * @remarks
+ * Параметр `ctx` в callback требует явной типизации для корректного вывода типов:
+ * ```typescript
+ * validateTree((ctx: { form: MyFormType }) => { ... });
+ * ```
+ *
  * @example
  * ```typescript
+ * // Явная типизация ctx для избежания implicit any
  * validateTree(
- *   (ctx: ValidationContext<TForm, TField>) => {
- *     const form = ctx.formValue();
- *     if (form.initialPayment && form.propertyValue) {
- *       if (form.initialPayment > form.propertyValue) {
+ *   (ctx: { form: MyForm }) => {
+ *     if (ctx.form.initialPayment && ctx.form.propertyValue) {
+ *       if (ctx.form.initialPayment > ctx.form.propertyValue) {
  *         return {
  *           code: 'initialPaymentTooHigh',
  *           message: 'Первоначальный взнос не может превышать стоимость',

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

@@ -1,43 +1,7 @@
 /**
  * FieldPath proxy - типобезопасный доступ к путям полей формы
- */
-import type { 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>;
-/**
- * Извлечь путь из FieldPathNode
- */
-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>;
-/**
- * Извлечь ключ поля из FieldPathNode
+ * @deprecated Импортируйте из '../utils/field-path' напрямую.
+ * Этот файл оставлен для обратной совместимости.
  */
-export declare function extractKey(node: FieldPathNode<unknown, unknown> | unknown): string;
+export { createFieldPath, extractPath, extractKey, toFieldPath } from '../utils/field-path';

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

@@ -45,3 +45,26 @@ export declare class TreeValidationContextImpl<TForm> implements FormContext<TFo
      */
     setFieldValue(path: string, value: unknown): void;
 }
+/**
+ * Реализация контекста валидации для ArrayNode
+ * Позволяет валидаторам типа notEmpty работать с массивами
+ */
+export declare class ArrayValidationContextImpl<TForm, TItem> implements FormContext<TForm> {
+    private _form;
+    private arrayValue;
+    /**
+     * Форма с типизированным Proxy-доступом к полям
+     */
+    readonly form: GroupNodeWithControls<TForm>;
+    constructor(form: GroupNode<TForm>, _fieldKey: keyof TForm, arrayValue: TItem[]);
+    /**
+     * Получить текущее значение массива (для валидатора)
+     * @internal
+     */
+    value(): TItem[];
+    /**
+     * Безопасно установить значение поля по строковому пути
+     * Автоматически использует emitEvent: false для предотвращения циклов
+     */
+    setFieldValue(path: string, value: unknown): void;
+}

package/dist/hooks/types.d.ts

@@ -0,0 +1,328 @@
+import type { ValidationError } from '../core/types';
+/**
+ * Состояние поля формы, возвращаемое хуком {@link useFormControl} для {@link FieldNode}.
+ *
+ * Содержит реактивные данные поля: значение, состояние валидации, флаги взаимодействия
+ * и пользовательские props для компонентов.
+ *
+ * @typeParam T - Тип значения поля (string, number, boolean и т.д.)
+ *
+ * @example Базовое использование
+ * ```tsx
+ * interface Props {
+ *   control: FieldNode<string>;
+ * }
+ *
+ * function TextField({ control }: Props) {
+ *   const state = useFormControl(control);
+ *
+ *   return (
+ *     <div>
+ *       <input
+ *         value={state.value}
+ *         disabled={state.disabled}
+ *         onChange={e => control.setValue(e.target.value)}
+ *       />
+ *       {state.shouldShowError && state.errors[0] && (
+ *         <span className="error">{state.errors[0].message}</span>
+ *       )}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @see {@link useFormControl} - хук для получения состояния
+ * @see {@link ArrayControlState} - состояние для массивов
+ *
+ * @group Types
+ */
+export interface FieldControlState<T> {
+    /**
+     * Текущее значение поля.
+     *
+     * @example
+     * ```tsx
+     * const { value } = useFormControl(emailField);
+     * console.log(value); // "user@example.com"
+     * ```
+     */
+    value: T;
+    /**
+     * Флаг асинхронной валидации или загрузки.
+     * `true` когда выполняется асинхронный валидатор.
+     *
+     * @example
+     * ```tsx
+     * const { pending } = useFormControl(usernameField);
+     *
+     * return (
+     *   <div>
+     *     <input {...props} />
+     *     {pending && <Spinner size="small" />}
+     *   </div>
+     * );
+     * ```
+     */
+    pending: boolean;
+    /**
+     * Флаг отключения поля.
+     * `true` когда поле недоступно для редактирования.
+     *
+     * @example
+     * ```tsx
+     * const { disabled, value } = useFormControl(field);
+     *
+     * return (
+     *   <input
+     *     value={value}
+     *     disabled={disabled}
+     *     className={disabled ? 'opacity-50' : ''}
+     *   />
+     * );
+     * ```
+     */
+    disabled: boolean;
+    /**
+     * Массив ошибок валидации.
+     * Пустой массив означает отсутствие ошибок.
+     *
+     * @example
+     * ```tsx
+     * const { errors } = useFormControl(field);
+     *
+     * return (
+     *   <ul className="error-list">
+     *     {errors.map((error, i) => (
+     *       <li key={i}>{error.message}</li>
+     *     ))}
+     *   </ul>
+     * );
+     * ```
+     */
+    errors: ValidationError[];
+    /**
+     * Флаг валидности поля.
+     * `true` когда поле прошло все валидации (errors.length === 0).
+     *
+     * @example
+     * ```tsx
+     * const { valid } = useFormControl(field);
+     *
+     * return (
+     *   <input className={valid ? 'border-green' : 'border-gray'} />
+     * );
+     * ```
+     */
+    valid: boolean;
+    /**
+     * Флаг невалидности поля.
+     * `true` когда есть ошибки валидации (errors.length > 0).
+     * Противоположность {@link valid}.
+     *
+     * @example
+     * ```tsx
+     * const { invalid } = useFormControl(field);
+     *
+     * return (
+     *   <input
+     *     aria-invalid={invalid}
+     *     className={invalid ? 'border-red' : ''}
+     *   />
+     * );
+     * ```
+     */
+    invalid: boolean;
+    /**
+     * Флаг взаимодействия с полем.
+     * `true` после того как поле потеряло фокус (blur) хотя бы один раз.
+     *
+     * @example
+     * ```tsx
+     * const { touched, invalid } = useFormControl(field);
+     *
+     * // Показываем ошибку только после взаимодействия
+     * const showError = touched && invalid;
+     * ```
+     */
+    touched: boolean;
+    /**
+     * Флаг для отображения ошибки.
+     * Комбинация touched && invalid - удобный shortcut для UI.
+     *
+     * @example
+     * ```tsx
+     * const { shouldShowError, errors } = useFormControl(field);
+     *
+     * return (
+     *   <div>
+     *     <input {...props} />
+     *     {shouldShowError && (
+     *       <span className="error">{errors[0]?.message}</span>
+     *     )}
+     *   </div>
+     * );
+     * ```
+     */
+    shouldShowError: boolean;
+    /**
+     * Пользовательские props для передачи в UI-компоненты.
+     * Устанавливаются через {@link FieldNode.setComponentProps}.
+     *
+     * @example
+     * ```tsx
+     * // Установка props
+     * field.setComponentProps({
+     *   placeholder: 'Enter email...',
+     *   maxLength: 100,
+     *   autoComplete: 'email'
+     * });
+     *
+     * // Использование в компоненте
+     * const { componentProps, value } = useFormControl(field);
+     *
+     * return (
+     *   <input
+     *     value={value}
+     *     placeholder={componentProps.placeholder}
+     *     maxLength={componentProps.maxLength}
+     *     autoComplete={componentProps.autoComplete}
+     *   />
+     * );
+     * ```
+     */
+    componentProps: Record<string, any>;
+}
+/**
+ * Состояние массива формы, возвращаемое хуком {@link useFormControl} для {@link ArrayNode}.
+ *
+ * Содержит реактивные данные массива: значения элементов, длину, состояние валидации
+ * и флаги взаимодействия.
+ *
+ * @typeParam T - Тип элемента массива (обычно объект с полями формы)
+ *
+ * @example Список с динамическим добавлением
+ * ```tsx
+ * interface Phone {
+ *   type: string;
+ *   number: string;
+ * }
+ *
+ * interface Props {
+ *   control: ArrayNode<Phone>;
+ * }
+ *
+ * function PhoneList({ control }: Props) {
+ *   const { length, valid } = useFormControl(control);
+ *
+ *   return (
+ *     <div>
+ *       {control.map((item, index) => (
+ *         <PhoneItem
+ *           key={item.id}
+ *           control={item}
+ *           onRemove={() => control.remove(index)}
+ *         />
+ *       ))}
+ *
+ *       {length === 0 && <p>No phones added</p>}
+ *
+ *       <button onClick={() => control.push({ type: 'mobile', number: '' })}>
+ *         Add Phone
+ *       </button>
+ *
+ *       {!valid && <p className="error">Please fix phone errors</p>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @see {@link useFormControl} - хук для получения состояния
+ * @see {@link FieldControlState} - состояние для полей
+ *
+ * @group Types
+ */
+export interface ArrayControlState<T> {
+    /**
+     * Массив текущих значений всех элементов.
+     *
+     * @example
+     * ```tsx
+     * const { value } = useFormControl(phonesArray);
+     * console.log(value);
+     * // [{ type: 'mobile', number: '+1234567890' }, { type: 'home', number: '+0987654321' }]
+     * ```
+     */
+    value: T[];
+    /**
+     * Количество элементов в массиве.
+     * Эквивалентно value.length, но оптимизировано для реактивности.
+     *
+     * @example
+     * ```tsx
+     * const { length } = useFormControl(itemsArray);
+     *
+     * return (
+     *   <div>
+     *     <span>Items: {length}</span>
+     *     {length >= 10 && <span>Maximum reached</span>}
+     *   </div>
+     * );
+     * ```
+     */
+    length: number;
+    /**
+     * Флаг асинхронной валидации.
+     * `true` когда выполняется асинхронный валидатор массива или любого элемента.
+     */
+    pending: boolean;
+    /**
+     * Массив ошибок валидации уровня массива.
+     * Не включает ошибки отдельных элементов.
+     *
+     * @example
+     * ```tsx
+     * // Валидатор массива
+     * validators.apply(phonesArray, {
+     *   validator: (phones) => phones.length >= 1,
+     *   message: 'At least one phone required'
+     * });
+     *
+     * // В компоненте
+     * const { errors } = useFormControl(phonesArray);
+     * // errors содержит ошибку "At least one phone required" если массив пуст
+     * ```
+     */
+    errors: ValidationError[];
+    /**
+     * Флаг валидности массива и всех его элементов.
+     * `true` только когда массив и все вложенные элементы валидны.
+     */
+    valid: boolean;
+    /**
+     * Флаг невалидности.
+     * `true` когда есть ошибки в массиве или любом элементе.
+     */
+    invalid: boolean;
+    /**
+     * Флаг взаимодействия.
+     * `true` после взаимодействия с любым элементом массива.
+     */
+    touched: boolean;
+    /**
+     * Флаг изменения.
+     * `true` когда значение массива отличается от начального.
+     *
+     * @example
+     * ```tsx
+     * const { dirty } = useFormControl(itemsArray);
+     *
+     * return (
+     *   <div>
+     *     {dirty && <span>* Unsaved changes</span>}
+     *     <button disabled={!dirty}>Save</button>
+     *   </div>
+     * );
+     * ```
+     */
+    dirty: boolean;
+}

package/dist/hooks/useFormControl.d.ts

@@ -1,48 +1,24 @@
 import type { FieldNode } from '../core/nodes/field-node';
 import type { ArrayNode } from '../core/nodes/array-node';
-import type { FormValue, ValidationError, FormFields } from '../core/types';
+import type { FormValue, FormFields } from '../core/types';
+import type { FieldControlState, ArrayControlState } from './types';
 /**
- * @internal
- */
-interface FieldControlState<T> {
-    value: T;
-    pending: boolean;
-    disabled: boolean;
-    errors: ValidationError[];
-    valid: boolean;
-    invalid: boolean;
-    touched: boolean;
-    shouldShowError: boolean;
-    componentProps: Record<string, any>;
-}
-/**
- * @internal
- */
-interface ArrayControlState<T> {
-    value: T[];
-    length: number;
-    pending: boolean;
-    errors: ValidationError[];
-    valid: boolean;
-    invalid: boolean;
-    touched: boolean;
-    dirty: boolean;
-}
-/**
- * Хук для получения только значения поля без подписки на errors, valid и т.д.
- * Используйте когда нужно только значение для условного рендеринга.
+ * React-хук для подписки на состояние {@link ArrayNode}.
+ *
+ * @typeParam T - Тип элемента массива
+ * @param control - ArrayNode или undefined
+ * @returns Состояние массива {@link ArrayControlState}
  *
- * @group React Hooks
- */
-export declare function useFormControlValue<T extends FormValue>(control: FieldNode<T>): T;
-/**
- * Хук для работы с ArrayNode - возвращает состояние массива с подписками на сигналы
  * @group React Hooks
  */
 export declare function useFormControl<T extends FormFields>(control: ArrayNode<T> | undefined): ArrayControlState<T>;
 /**
- * Хук для работы с FieldNode - возвращает состояние поля с подписками на сигналы
+ * React-хук для подписки на состояние {@link FieldNode}.
+ *
+ * @typeParam T - Тип значения поля
+ * @param control - FieldNode для подписки
+ * @returns Состояние поля {@link FieldControlState}
+ *
  * @group React Hooks
  */
 export declare function useFormControl<T extends FormValue>(control: FieldNode<T>): FieldControlState<T>;
-export {};