@reformer/core 6.0.0 → 7.0.0-beta.2

package/dist/core/validation/validators/max-length.d.ts

@@ -2,12 +2,26 @@ import { Validator, ValidateOptions } from '../../types/validation-schema';
 /**
  * Фабрика валидатора максимальной длины строки или массива.
  *
- * Пустые значения пропускаются (используйте `required` для обязательности).
+ * Работает со строкой или массивом (проверяется `value.length`). Пустые значения
+ * (`null`/`undefined`/`''`) и значения без числового `length` пропускаются
+ * (используйте {@link required} для обязательности).
  *
- * @example
+ * @param maxLen - Максимально допустимая длина (включительно)
+ * @param options - Опции валидатора ({@link ValidateOptions}). В `params` ошибки автоматически
+ *   попадают `maxLength` и `actualLength`.
+ * @returns Чистый валидатор {@link Validator} для строки или массива
+ *
+ * @example Максимальная длина строки
  * ```typescript
- * validate(path.name, maxLength(50));
- * validate(path.bio, maxLength(500, { message: 'Max 500 символов' }));
+ * import { maxLength } from '@reformer/core/validators';
+ *
+ * // Внутри FieldConfig схемы формы:
+ * name: { value: model.$.name, component: Input, validators: [maxLength(50)] },
+ * bio: {
+ *   value: model.$.bio,
+ *   component: Textarea,
+ *   validators: [maxLength(500, { message: 'Максимум 500 символов' })],
+ * },
  * ```
  */
 export declare function maxLength<TForm = unknown, TField = unknown>(maxLen: number, options?: ValidateOptions): Validator<TForm, TField>;

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

@@ -2,15 +2,24 @@ import { Validator, ValidateOptions } from '../../types/validation-schema';
 /**
  * Фабрика валидатора максимального числового значения.
  *
- * Пустые значения пропускаются (используйте `required` для обязательности).
+ * Пустые значения (`null`/`undefined`) пропускаются (используйте {@link required} для обязательности).
  *
- * @example
+ * @param maxValue - Максимально допустимое значение (включительно)
+ * @param options - Опции валидатора ({@link ValidateOptions}). В `params` ошибки автоматически
+ *   попадают `max` и `actual`.
+ * @returns Чистый валидатор {@link Validator} для числового поля
+ *
+ * @example Максимальное значение числового поля
  * ```typescript
- * import { validate } from '@reformer/core';
- * import { max } from '@reformer/core/validators';
+ * import { required, max } from '@reformer/core/validators';
  *
- * validate(path.quantity, max(100));
- * validate(path.discount, max(50, { message: 'Не более 50%' }));
+ * // Внутри FieldConfig схемы формы:
+ * quantity: { value: model.$.quantity, component: Input, validators: [max(100)] },
+ * discount: {
+ *   value: model.$.discount,
+ *   component: Input,
+ *   validators: [required(), max(50, { message: 'Не более 50%' })],
+ * },
  * ```
  */
 export declare function max<TForm = unknown, TField extends number | undefined = number>(maxValue: number, options?: ValidateOptions): Validator<TForm, TField>;

package/dist/core/validation/validators/min-age.d.ts

@@ -2,12 +2,24 @@ import { Validator, ValidateOptions } from '../../types/validation-schema';
 /**
  * Фабрика валидатора минимального возраста (по дате рождения).
  *
- * Пустые и невалидные даты пропускаются.
+ * Возраст вычисляется по дате рождения относительно сегодняшнего дня. Пустые и невалидные
+ * даты пропускаются (используйте {@link required} и {@link isDate}).
  *
- * @example
+ * @param minAgeValue - Минимально допустимый возраст (в полных годах)
+ * @param options - Опции валидатора ({@link ValidateOptions}). В `params` ошибки автоматически
+ *   попадают `minAge` и `currentAge`.
+ * @returns Чистый валидатор {@link Validator} для поля даты рождения (`string | Date`)
+ *
+ * @example Минимальный возраст
  * ```typescript
- * validate(path.birthDate, minAge(18));
- * validate(path.birthDate, minAge(21, { message: 'Вам должно быть не менее 21 года' }));
+ * import { required, minAge } from '@reformer/core/validators';
+ *
+ * // Внутри FieldConfig схемы формы:
+ * birthDate: {
+ *   value: model.$.birthDate,
+ *   component: DatePicker,
+ *   validators: [required(), minAge(18, { message: 'Вам должно быть не менее 18 лет' })],
+ * },
  * ```
  */
 export declare function minAge<TForm = unknown, TField extends string | Date | null | undefined = string | Date>(minAgeValue: number, options?: ValidateOptions): Validator<TForm, TField>;

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

@@ -2,12 +2,24 @@ import { Validator, ValidateOptions } from '../../types/validation-schema';
 /**
  * Фабрика валидатора минимальной даты (включительно).
  *
- * Пустые и невалидные даты пропускаются (используйте `required` и `isDate`).
+ * Сравнение по нормализованным датам (время обнуляется). Пустые и невалидные даты
+ * пропускаются (используйте {@link required} и {@link isDate}).
  *
- * @example
+ * @param minDateValue - Минимально допустимая дата (включительно)
+ * @param options - Опции валидатора ({@link ValidateOptions}). В `params` ошибки автоматически
+ *   попадает `minDate`.
+ * @returns Чистый валидатор {@link Validator} для поля даты (`string | Date`)
+ *
+ * @example Минимальная дата
  * ```typescript
- * validate(path.eventDate, minDate(new Date('2024-01-01')));
- * validate(path.startDate, minDate(new Date(), { message: 'Дата должна быть не раньше сегодня' }));
+ * import { required, minDate } from '@reformer/core/validators';
+ *
+ * // Внутри FieldConfig схемы формы:
+ * startDate: {
+ *   value: model.$.startDate,
+ *   component: DatePicker,
+ *   validators: [required(), minDate(new Date(), { message: 'Дата не раньше сегодня' })],
+ * },
  * ```
  */
 export declare function minDate<TForm = unknown, TField extends string | Date | null | undefined = string | Date>(minDateValue: Date, options?: ValidateOptions): Validator<TForm, TField>;

package/dist/core/validation/validators/min-length.d.ts

@@ -2,12 +2,26 @@ import { Validator, ValidateOptions } from '../../types/validation-schema';
 /**
  * Фабрика валидатора минимальной длины строки или массива.
  *
- * Пустые значения пропускаются (используйте `required` для обязательности).
+ * Работает со строкой или массивом (проверяется `value.length`). Пустые значения
+ * (`null`/`undefined`/`''`) и значения без числового `length` пропускаются
+ * (используйте {@link required} для обязательности).
  *
- * @example
+ * @param minLen - Минимально допустимая длина (включительно)
+ * @param options - Опции валидатора ({@link ValidateOptions}). В `params` ошибки автоматически
+ *   попадают `minLength` и `actualLength`.
+ * @returns Чистый валидатор {@link Validator} для строки или массива
+ *
+ * @example Минимальная длина строки
  * ```typescript
- * validate(path.name, minLength(2));
- * validate(path.password, minLength(8, { message: 'Min 8 символов' }));
+ * import { required, minLength } from '@reformer/core/validators';
+ *
+ * // Внутри FieldConfig схемы формы:
+ * name: { value: model.$.name, component: Input, validators: [minLength(2)] },
+ * password: {
+ *   value: model.$.password,
+ *   component: Input,
+ *   validators: [required(), minLength(8, { message: 'Минимум 8 символов' })],
+ * },
  * ```
  */
 export declare function minLength<TForm = unknown, TField = unknown>(minLen: number, options?: ValidateOptions): Validator<TForm, TField>;

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

@@ -2,15 +2,24 @@ import { Validator, ValidateOptions } from '../../types/validation-schema';
 /**
  * Фабрика валидатора минимального числового значения.
  *
- * Пустые значения пропускаются (используйте `required` для обязательности).
+ * Пустые значения (`null`/`undefined`) пропускаются (используйте {@link required} для обязательности).
  *
- * @example
+ * @param minValue - Минимально допустимое значение (включительно)
+ * @param options - Опции валидатора ({@link ValidateOptions}). В `params` ошибки автоматически
+ *   попадают `min` и `actual`.
+ * @returns Чистый валидатор {@link Validator} для числового поля
+ *
+ * @example Минимальное значение числового поля
  * ```typescript
- * import { validate } from '@reformer/core';
- * import { min } from '@reformer/core/validators';
+ * import { required, min } from '@reformer/core/validators';
  *
- * validate(path.age, min(18));
- * validate(path.quantity, min(1, { message: 'Минимум 1' }));
+ * // Внутри FieldConfig схемы формы:
+ * age: { value: model.$.age, component: Input, validators: [min(18)] },
+ * quantity: {
+ *   value: model.$.quantity,
+ *   component: Input,
+ *   validators: [required(), min(1, { message: 'Минимум 1' })],
+ * },
  * ```
  */
 export declare function min<TForm = unknown, TField extends number | undefined = number>(minValue: number, options?: ValidateOptions): Validator<TForm, TField>;

package/dist/core/validation/validators/multiple-of.d.ts

@@ -2,12 +2,23 @@ import { Validator, ValidateOptions } from '../../types/validation-schema';
 /**
  * Фабрика валидатора, проверяющего что число кратно заданному.
  *
- * Пустые значения и не-числа пропускаются (используйте `required` и `isNumber`).
+ * Пустые значения и не-числа пропускаются (используйте {@link required} и {@link isNumber}).
  *
- * @example
+ * @param divisor - Делитель: значение должно быть кратно ему
+ * @param options - Опции валидатора ({@link ValidateOptions}). В `params` ошибки автоматически
+ *   попадает `multipleOf` (делитель).
+ * @returns Чистый валидатор {@link Validator} для числового поля
+ *
+ * @example Проверка кратности
  * ```typescript
- * validate(path.price, multipleOf(0.01));
- * validate(path.rating, multipleOf(0.5, { message: 'Только шаг 0.5' }));
+ * import { multipleOf } from '@reformer/core/validators';
+ *
+ * // Внутри FieldConfig схемы формы:
+ * rating: {
+ *   value: model.$.rating,
+ *   component: Input,
+ *   validators: [multipleOf(0.5, { message: 'Только шаг 0.5' })],
+ * },
  * ```
  */
 export declare function multipleOf<TForm = unknown, TField extends number | undefined = number>(divisor: number, options?: ValidateOptions): Validator<TForm, TField>;

package/dist/core/validation/validators/non-negative.d.ts

@@ -2,12 +2,21 @@ import { Validator, ValidateOptions } from '../../types/validation-schema';
 /**
  * Фабрика валидатора, проверяющего что число неотрицательное (`≥ 0`).
  *
- * Пустые значения и не-числа пропускаются (используйте `required` и `isNumber`).
+ * Пустые значения и не-числа пропускаются (используйте {@link required} и {@link isNumber}).
  *
- * @example
+ * @param options - Опции валидатора ({@link ValidateOptions}): `message`, `params`
+ * @returns Чистый валидатор {@link Validator} для числового поля
+ *
+ * @example Проверка неотрицательности
  * ```typescript
- * validate(path.quantity, nonNegative());
- * validate(path.balance, nonNegative({ message: 'Баланс не может быть отрицательным' }));
+ * import { nonNegative } from '@reformer/core/validators';
+ *
+ * // Внутри FieldConfig схемы формы:
+ * balance: {
+ *   value: model.$.balance,
+ *   component: Input,
+ *   validators: [nonNegative({ message: 'Баланс не может быть отрицательным' })],
+ * },
  * ```
  */
 export declare function nonNegative<TForm = unknown, TField extends number | undefined = number>(options?: ValidateOptions): Validator<TForm, TField>;

package/dist/core/validation/validators/non-zero.d.ts

@@ -2,12 +2,21 @@ import { Validator, ValidateOptions } from '../../types/validation-schema';
 /**
  * Фабрика валидатора, проверяющего что число не равно нулю.
  *
- * Пустые значения и не-числа пропускаются (используйте `required` и `isNumber`).
+ * Пустые значения и не-числа пропускаются (используйте {@link required} и {@link isNumber}).
  *
- * @example
+ * @param options - Опции валидатора ({@link ValidateOptions}): `message`, `params`
+ * @returns Чистый валидатор {@link Validator} для числового поля
+ *
+ * @example Проверка «не ноль»
  * ```typescript
- * validate(path.quantity, nonZero());
- * validate(path.divisor, nonZero({ message: 'Не может быть нулём' }));
+ * import { nonZero } from '@reformer/core/validators';
+ *
+ * // Внутри FieldConfig схемы формы:
+ * divisor: {
+ *   value: model.$.divisor,
+ *   component: Input,
+ *   validators: [nonZero({ message: 'Не может быть нулём' })],
+ * },
  * ```
  */
 export declare function nonZero<TForm = unknown, TField extends number | undefined = number>(options?: ValidateOptions): Validator<TForm, TField>;

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

@@ -2,11 +2,22 @@ import { Validator, ValidateOptions } from '../../types/validation-schema';
 /**
  * Фабрика валидатора, проверяющего что дата не в будущем.
  *
- * Пустые и невалидные даты пропускаются.
+ * Дата не должна быть позже сегодняшнего дня (сравнение по нормализованным датам).
+ * Пустые и невалидные даты пропускаются (используйте {@link required} и {@link isDate}).
  *
- * @example
+ * @param options - Опции валидатора ({@link ValidateOptions}): `message`, `params`
+ * @returns Чистый валидатор {@link Validator} для поля даты (`string | Date`)
+ *
+ * @example Дата не в будущем
  * ```typescript
- * validate(path.birthDate, pastDate({ message: 'Дата рождения не может быть в будущем' }));
+ * import { required, pastDate } from '@reformer/core/validators';
+ *
+ * // Внутри FieldConfig схемы формы:
+ * birthDate: {
+ *   value: model.$.birthDate,
+ *   component: DatePicker,
+ *   validators: [required(), pastDate({ message: 'Дата рождения не может быть в будущем' })],
+ * },
  * ```
  */
 export declare function pastDate<TForm = unknown, TField extends string | Date | undefined = string | Date>(options?: ValidateOptions): Validator<TForm, TField>;

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

@@ -2,12 +2,32 @@ import { Validator, ValidateOptions } from '../../types/validation-schema';
 /**
  * Фабрика валидатора регулярного выражения.
  *
- * Пустые значения пропускаются (используйте `required` для обязательности).
+ * Пустые значения (`''`/`null`/`undefined`) пропускаются (используйте {@link required}
+ * для обязательности).
  *
- * @example
+ * @param regex - Регулярное выражение для проверки значения
+ * @param options - Опции валидатора ({@link ValidateOptions}). В `params` ошибки автоматически
+ *   попадает `pattern` (строка-источник regex).
+ * @returns Чистый валидатор {@link Validator} для строкового поля
+ *
+ * @example Проверка по регулярному выражению
  * ```typescript
- * validate(path.name, pattern(/^[а-яА-Яa-zA-Z]+$/));
- * validate(path.code, pattern(/^\d+$/, { message: 'Только цифры' }));
+ * import { required, pattern } from '@reformer/core/validators';
+ *
+ * // Внутри FieldConfig схемы формы:
+ * name: {
+ *   value: model.$.name,
+ *   component: Input,
+ *   validators: [pattern(/^[a-zA-Zа-яА-Я]+$/, { message: 'Только буквы' })],
+ * },
+ * phone: {
+ *   value: model.$.phone,
+ *   component: InputMask,
+ *   validators: [
+ *     required(),
+ *     pattern(/^\+7 \(\d{3}\) \d{3}-\d{2}-\d{2}$/, { message: 'Формат +7 (999) 123-45-67' }),
+ *   ],
+ * },
  * ```
  */
 export declare function pattern<TForm = unknown, TField extends string | undefined = string>(regex: RegExp, options?: ValidateOptions): Validator<TForm, TField>;

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

@@ -1,17 +1,41 @@
 import { Validator, ValidateOptions } from '../../types/validation-schema';
+/**
+ * Формат проверки номера телефона для валидатора {@link phone}.
+ *
+ * - `international` — международный формат E.164 (`+?[1-9]\d{1,14}`);
+ * - `ru` — российские номера (`+7`/`7`/`8`, коды `4`/`8`/`9`, с разделителями);
+ * - `us` — североамериканские номера (NANP);
+ * - `any` — свободный формат: цифры, скобки и разделители (по умолчанию).
+ */
 export type PhoneFormat = 'international' | 'ru' | 'us' | 'any';
+/**
+ * Опции валидатора {@link phone}. Расширяют {@link ValidateOptions} (`message`, `params`)
+ * выбором формата номера.
+ */
 export interface PhoneValidatorOptions extends ValidateOptions {
+    /** Формат проверки {@link PhoneFormat}. По умолчанию `'any'`. */
     format?: PhoneFormat;
 }
 /**
  * Фабрика валидатора номера телефона.
  *
- * Пустые значения пропускаются (используйте `required` для обязательности).
+ * Проверяет значение по regex выбранного {@link PhoneFormat}. Пустые значения
+ * (`''`/`null`/`undefined`) пропускаются (используйте {@link required} для обязательности).
+ *
+ * @param options - Опции валидатора {@link PhoneValidatorOptions}. В `params` ошибки
+ *   автоматически попадает выбранный `format`.
+ * @returns Чистый валидатор {@link Validator} для строкового поля
  *
- * @example
+ * @example Проверка номера телефона
  * ```typescript
- * validate(path.phone, phone());
- * validate(path.phone, phone({ format: 'ru' }));
+ * import { required, phone } from '@reformer/core/validators';
+ *
+ * // Внутри FieldConfig схемы формы:
+ * phone: {
+ *   value: model.$.phone,
+ *   component: Input,
+ *   validators: [required(), phone({ format: 'ru' })],
+ * },
  * ```
  */
 export declare function phone<TForm = unknown, TField extends string | undefined = string>(options?: PhoneValidatorOptions): Validator<TForm, TField>;

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

@@ -7,14 +7,25 @@ import { Validator, ValidateOptions } from '../../types/validation-schema';
  * Пустыми считаются: `null`, `undefined`, `''` (пустая строка).
  * Для boolean полей требуется значение `true`.
  *
- * @example
+ * @param options - Опции валидатора ({@link ValidateOptions}): `message`, `params`
+ * @returns Чистый валидатор {@link Validator} для поля схемы
+ *
+ * @example Обязательные поля в схеме формы
  * ```typescript
- * import { validate } from '@reformer/core';
  * import { required } from '@reformer/core/validators';
  *
- * validate(path.email, required());
- * validate(path.phone, required({ message: 'Укажите номер телефона' }));
- * validate(path.agreeToTerms, required({ message: 'Необходимо принять условия' }));
+ * // Внутри FieldConfig схемы формы:
+ * email: { value: model.$.email, component: Input, validators: [required()] },
+ * phone: {
+ *   value: model.$.phone,
+ *   component: Input,
+ *   validators: [required({ message: 'Укажите номер телефона' })],
+ * },
+ * agreeToTerms: {
+ *   value: model.$.agreeToTerms,
+ *   component: Checkbox,
+ *   validators: [required({ message: 'Необходимо принять условия' })],
+ * },
  * ```
  */
 export declare function required<TForm = unknown, TField = unknown>(options?: ValidateOptions): Validator<TForm, TField>;

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

@@ -1,20 +1,43 @@
 import { Validator, ValidateOptions } from '../../types/validation-schema';
+/**
+ * Опции валидатора {@link url}. Расширяют {@link ValidateOptions} (`message`, `params`)
+ * настройками проверки протокола.
+ */
 export interface UrlValidatorOptions extends ValidateOptions {
-    /** Требовать наличие протокола (http:// или https://) */
+    /** Требовать наличие протокола (`http://` или `https://`). По умолчанию `false`. */
     requireProtocol?: boolean;
-    /** Разрешенные протоколы */
+    /**
+     * Список разрешённых протоколов (без `://`), например `['https']`. Если задан,
+     * значение с иным протоколом даёт ошибку с кодом `url_protocol`.
+     */
     allowedProtocols?: string[];
 }
 /**
  * Фабрика валидатора URL.
  *
- * Пустые значения пропускаются (используйте `required` для обязательности).
+ * Пустые значения (`''`/`null`/`undefined`) пропускаются (используйте {@link required}
+ * для обязательности). При `requireProtocol` протокол обязателен; `allowedProtocols`
+ * дополнительно ограничивает набор допустимых протоколов.
  *
- * @example
+ * @param options - Опции валидатора {@link UrlValidatorOptions}
+ * @returns Чистый валидатор {@link Validator} для строкового поля
+ *
+ * @example Проверка URL
  * ```typescript
- * validate(path.website, url());
- * validate(path.website, url({ requireProtocol: true }));
- * validate(path.website, url({ allowedProtocols: ['https'] }));
+ * import { required, url } from '@reformer/core/validators';
+ *
+ * // Внутри FieldConfig схемы формы:
+ * website: {
+ *   value: model.$.website,
+ *   component: Input,
+ *   validators: [required(), url({ message: 'Введите корректный URL' })],
+ * },
+ * // Требовать протокол и ограничить схему только https:
+ * homepage: {
+ *   value: model.$.homepage,
+ *   component: Input,
+ *   validators: [url({ requireProtocol: true, allowedProtocols: ['https'] })],
+ * },
  * ```
  */
 export declare function url<TForm = unknown, TField extends string | undefined = string>(options?: UrlValidatorOptions): Validator<TForm, TField>;

package/dist/hooks/useFormControlValue.d.ts

@@ -84,23 +84,28 @@ import { FormValue } from '../core/types';
  * }
  * ```
  *
- * @example Отображение суммы в реальном времени
+ * @example Отображение суммы позиции в реальном времени
  * ```tsx
  * interface OrderItem {
- *   quantity: FieldNode<number>;
- *   price: FieldNode<number>;
+ *   quantity: number;
+ *   price: number;
  * }
  *
- * function OrderTotal({ items }: { items: ArrayNode<OrderItem> }) {
- *   // Для каждого элемента получаем только значения
- *   const quantities = items.map(item => useFormControlValue(item.controls.quantity));
- *   const prices = items.map(item => useFormControlValue(item.controls.price));
+ * // Хук вызывается на уровне компонента-строки (не в цикле — Rules of Hooks).
+ * // Доступ к полям элемента — через Proxy: item.quantity, item.price.
+ * function OrderRow({ item }: { item: FormProxy<OrderItem> }) {
+ *   const quantity = useFormControlValue(item.quantity);
+ *   const price = useFormControlValue(item.price);
  *
- *   const total = quantities.reduce((sum, qty, i) => sum + qty * prices[i], 0);
+ *   return <span>Итого: ${(quantity * price).toFixed(2)}</span>;
+ * }
  *
+ * function OrderList({ items }: { items: ArrayNode<OrderItem> }) {
  *   return (
- *     <div className="order-total">
- *       <strong>Total: ${total.toFixed(2)}</strong>
+ *     <div>
+ *       {items.map((item, index) => (
+ *         <OrderRow key={index} item={item} />
+ *       ))}
  *     </div>
  *   );
  * }