@reformer/core 7.0.0-beta.1 → 7.0.0-beta.3

package/dist/core/factories/node-factory.d.ts

@@ -9,7 +9,8 @@ import { FormNode } from '../nodes/form-node';
  * ```typescript
  * import { NodeFactory } from '@reformer/core';
  *
- * const node = NodeFactory.create({ value: '' }); // → FieldNode<string>
+ * const factory = new NodeFactory();
+ * const node = factory.createNode({ value: '', component: Input }); // → FieldNode<string>
  * ```
  */
 export declare class NodeFactory {

package/dist/core/model/behaviors.d.ts

@@ -67,9 +67,21 @@ export declare function enableWhen(target: ReadonlySignal<unknown>, condition: (
     resetOnDisable?: boolean;
 }): BehaviorCleanup;
 /**
- * Условное выключение поля (инверсия {@link enableWhen}).
+ * Условное выключение поля (инверсия {@link enableWhen}). Резолвит ноду по сигналу-цели через реестр
+ * сигнал→нода и вызывает `disable()`, когда `condition` истинно (+`reset()` при `resetOnDisable`).
+ * `condition` реактивен (читает свои сигналы модели).
  *
  * @group Model
+ * @param target Сигнал-цель поля (`model.$.<path>`).
+ * @param condition Реактивное условие; при `true` поле выключается.
+ * @param options.resetOnDisable Сбросить значение при выключении (по умолчанию `false`).
+ * @returns Cleanup для отписки.
+ *
+ * @example
+ * ```typescript
+ * // Поле скидки недоступно, пока не выбран промо-тариф
+ * disableWhen(model.$.discount, () => model.plan !== 'promo', { resetOnDisable: true });
+ * ```
  */
 export declare function disableWhen(target: ReadonlySignal<unknown>, condition: () => boolean, options?: {
     resetOnDisable?: boolean;

package/dist/core/model/validate-model.d.ts

@@ -21,6 +21,16 @@ export interface ModelValidationResult {
  * Синхронная headless-валидация данных. Асинхронные валидаторы пропускаются.
  *
  * @group Model
+ * @param model - Модель данных ({@link FormModel}), из сигналов которой читаются значения полей.
+ * @param schema - Единая схема формы (дерево узлов с `value`/`validators`, `{ when, children }`,
+ *   секциями массивов). Обходится один раз для сбора активных полей.
+ * @returns {@link ModelValidationResult} — `valid` + ошибки по пути поля (без async-валидаторов).
+ *
+ * @example Быстрая синхронная проверка (например, для gate «можно ли перейти на след. шаг»)
+ * ```typescript
+ * const res = validateModelSync(model, schema);
+ * if (!res.valid) console.log(res.errors); // { 'email': [{ code, message }], ... }
+ * ```
  */
 export declare function validateModelSync<T>(model: FormModel<T>, schema: unknown): ModelValidationResult;
 /**
@@ -40,7 +50,19 @@ export declare function validateModel<T>(model: FormModel<T>, schema: unknown):
  * И поля выключенных веток (`{ when, children }` с ложным условием). Дерево обходится ОДИН раз.
  *
  * @group Model
+ * @param model - Модель данных ({@link FormModel}) — источник значений полей.
+ * @param schema - Единая схема формы (та же, что передавалась в `createForm`).
+ * @returns {@link ModelValidationResult} — `valid` + ошибки по пути поля; побочный эффект — ошибки
+ *   разведены по нодам формы.
  * @remarks Поля, не материализованные в форме (элементы массива — строятся per-item), не роутятся
  * в родительскую форму; их ошибки доступны в возвращаемом результате по пути.
+ *
+ * @example Валидация перед submit (ошибки показываются в UI автоматически)
+ * ```typescript
+ * const form = createForm({ model, schema });
+ * form.touchAll();
+ * const res = await validateFormModel(model, schema);
+ * if (res.valid) await api.save(model.get());
+ * ```
  */
 export declare function validateFormModel<T>(model: FormModel<T>, schema: unknown): Promise<ModelValidationResult>;

package/dist/core/nodes/field-node.d.ts

@@ -196,13 +196,13 @@ export declare class FieldNode<T> extends FormNode<T> {
      * @example
      * ```typescript
      * // Сценарий 1: Instant feedback после submit
-     * const form = new GroupNode({
+     * const form = createForm({
      *   email: {
      *     value: '',
      *     component: Input,
      *     updateOn: 'submit', // Изначально валидация только при submit
-     *     validators: [required, email]
-     *   }
+     *     validators: [required, email],
+     *   },
      * });
      *
      * await form.submit(async (values) => {

package/dist/core/nodes/group-node.d.ts

@@ -134,14 +134,12 @@ export declare class GroupNode<T> extends FormNode<T> {
      * @example
      * ```typescript
      * const form = new GroupNode({
-     *   controls: {
-     *     email: new FieldNode({ value: '' }),
-     *     name: new FieldNode({ value: '' })
-     *   }
+     *   email: { value: '', component: Input },
+     *   name: { value: '', component: Input },
      * });
      *
      * const proxy = form.getProxy();
-     * console.log(proxy.email.value); // Прямой доступ к полю
+     * console.log(proxy.email.value.value); // Прямой доступ к полю
      * ```
      */
     getProxy(): FormProxy<T>;

package/dist/core/nodes/model-array-node.d.ts

@@ -15,6 +15,44 @@ export interface ModelArrayControl<TItem extends object> {
     clear(): void;
     toArray(): TItem[];
 }
+/**
+ * Узел массива, делегирующий данные массиву {@link FormModel} (архитектура M1).
+ *
+ * В отличие от {@link ArrayNode} (владеет элементами сам), `ModelArrayNode` НЕ владеет данными:
+ * массив принадлежит модели, а узел держит per-item формы элементов (привязанные к сигналам
+ * под-моделей) и синхронизирует их с длиной массива модели. Мутации (`push`/`removeAt`/`move`/…)
+ * делегируются массиву модели; per-item формы кэшируются по идентичности под-модели, поэтому при
+ * reorder/повторном рендере не пересоздаются (состояние и валидация сохраняются). Реализует тот же
+ * контракт, что ждут секции массива и `useFormControl` (`length`/`value`/`valid`/`errors`/`at`/`push`/…).
+ *
+ * Обычно создаётся не напрямую, а `createForm({ model, schema })`: когда в схеме встречается узел
+ * массива `{ array: model.<field>, item: (item) => itemSchema }`, форма материализует его как
+ * `ModelArrayNode` и кладёт под `form.<field>` (совместим с `FormArraySection`).
+ *
+ * @group Nodes
+ *
+ * @example Массив как часть формы (через createForm)
+ * ```typescript
+ * const model = createModel<{ rows: { name: string; qty: number }[] }>({ rows: [] });
+ *
+ * const rowItem = (item: FormModel<{ name: string; qty: number }>) => ({
+ *   name: { value: item.$.name, component: Input },
+ *   qty: { value: item.$.qty, component: Input },
+ * });
+ *
+ * const form = createForm({
+ *   model,
+ *   schema: {
+ *     children: [{ array: model.rows, item: rowItem }],
+ *   },
+ * });
+ *
+ * const rows = form.rows as unknown as ModelArrayNode<{ name: string; qty: number }>;
+ * rows.push({ name: 'A', qty: 1 });   // мутация уезжает в model.rows
+ * rows.at(0)?.name.setValue('B');     // правка поля элемента доезжает в под-модель
+ * rows.length.value;                  // 1 (реактивная длина)
+ * ```
+ */
 export declare class ModelArrayNode<T extends object> extends FormNode<T[]> {
     private readonly control;
     private readonly buildItem;

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

@@ -6,13 +6,19 @@ import { FormProxy } from './form-proxy';
  * Принимает значение поля, прокси текущего поля (control) и прокси корня формы (root).
  * Возвращает ValidationError либо null. Не знает про реестр валидации.
  *
- * @example
+ * @example Кастомный валидатор в массиве `validators` поля схемы
  * ```typescript
  * const isAdult: Validator<MyForm, number> = (value, control, root) => {
  *   if (value < 18) return { code: 'tooYoung', message: '18+' };
  *   return null;
  * };
- * validate(path.age, isAdult);
+ *
+ * // Фабрики и кастомные валидаторы кладутся в `validators: [...]` поля:
+ * const schema = {
+ *   children: [
+ *     { value: model.$.age, component: Input, validators: [required(), isAdult] },
+ *   ],
+ * };
  * ```
  */
 export type Validator<TForm, TField> = (value: TField, control: FormProxy<TField>, root: FormProxy<TForm>) => ValidationError | null;

package/dist/core/utils/create-form.d.ts

@@ -21,43 +21,108 @@ export interface CreateFormFromModelArgs<T> {
      */
     behavior?: FormBehavior<T>;
 }
+/**
+ * Собрать форму из {@link FormModel} и единой схемы (низкоуровневая фабрика архитектуры M1).
+ *
+ * Значения принадлежат модели (источник истины), ноды формы держат UI/валидационное состояние и
+ * ссылаются на сигналы модели по идентичности (`node.value === model.$.path`). Обходит структуру
+ * модели, привязывает конфиг поля (component/componentProps/validators) из схемы, материализует
+ * top-level массивы как {@link ModelArrayNode}, заполняет реестр сигнал→нода (для `enableWhen`/
+ * роутинга ошибок) и, при наличии, запускает декларативное поведение (cleanup живёт на форме).
+ *
+ * Обычно вызывается неявно через {@link createForm} с аргументом `{ model, schema }` — прямой вызов
+ * нужен редко (например, для построения формы элемента массива).
+ *
+ * @typeParam T - Тип модели данных формы
+ * @param args - Модель, единая схема и (опционально) декларативное поведение {@link CreateFormFromModelArgs}
+ * @returns Типизированная форма с Proxy-доступом к полям {@link FormProxy}
+ *
+ * @example Форма из модели + схемы (эквивалент `createForm({ model, schema })`)
+ * ```typescript
+ * import { createModel, createFormFromModel } from '@reformer/core';
+ *
+ * interface Form {
+ *   email: string;
+ *   profile: { name: string; age: number };
+ * }
+ *
+ * const model = createModel<Form>({ email: '', profile: { name: '', age: 0 } });
+ * const schema = {
+ *   component: Section,
+ *   children: [
+ *     { value: model.$.email, component: Input, validators: [required] },
+ *     { value: model.$.profile.name, component: Input },
+ *   ],
+ * };
+ *
+ * const form = createFormFromModel<Form>({ model, schema });
+ *
+ * // Двусторонняя связь нода ↔ модель:
+ * form.email.setValue('user@mail.com');
+ * console.log(model.email); // 'user@mail.com'
+ * ```
+ *
+ * @see {@link createForm} - основная фабрика (диспетчеризует сюда при аргументе `{ model, schema }`)
+ * @group Utilities
+ */
 export declare function createFormFromModel<T>(args: CreateFormFromModelArgs<T>): FormProxy<T>;
 /**
- * Создать форму с полной конфигурацией (form, behavior, validation)
+ * Создать форму из {@link FormModel} + единой схемы (архитектура M1, рекомендуемый путь).
  *
  * @group Utilities
  *
- * @param config - Конфигурация формы с полями, поведением и валидацией
+ * @param args - Модель данных, единая схема (component/componentProps/validators) и (опционально) поведение
  * @returns Типизированная форма с Proxy-доступом к полям
  *
- * @example
+ * @example Архитектура M1: `createModel` + единая схема + `createForm({ model, schema })`
  * ```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);
- *   },
- * });
+ * import { createModel, createForm, validateFormModel } from '@reformer/core';
+ * import { required, email, minLength } from '@reformer/core/validators';
+ *
+ * interface UserForm {
+ *   email: string;
+ *   password: string;
+ * }
  *
- * // TypeScript знает о полях:
+ * const model = createModel<UserForm>({ email: '', password: '' });
+ *
+ * const schema = {
+ *   children: [
+ *     {
+ *       value: model.$.email,
+ *       component: Input,
+ *       validators: [required(), email()],
+ *     },
+ *     {
+ *       value: model.$.password,
+ *       component: Input,
+ *       validators: [required(), minLength(8)],
+ *     },
+ *   ],
+ * };
+ *
+ * const form = createForm<UserForm>({ model, schema });
+ *
+ * // TypeScript знает о полях (нода привязана к сигналу модели):
  * form.email.setValue('test@mail.com');
+ *
+ * // Валидация всей модели по схеме (sync + async):
+ * const { valid } = await validateFormModel(model, schema);
  * ```
  */
 export declare function createForm<T>(args: CreateFormFromModelArgs<T>): FormProxy<T>;
 export declare function createForm<T>(config: GroupNodeConfig<T>): FormProxy<T>;
 /**
- * Создать форму только со схемой полей (обратная совместимость)
+ * Создать форму только со схемой полей.
+ *
+ * @deprecated Legacy / back-compat: плоская `FormSchema` с инлайн-значениями (`value: ''`) — путь
+ *   ДО архитектуры M1. Для нового кода используйте перегрузку `createForm({ model, schema })`
+ *   (значения принадлежат {@link FormModel}, валидаторы — фабрики в `validators: [...]`).
  *
  * @param schema - Схема полей формы
  * @returns Типизированная форма с Proxy-доступом к полям
  *
- * @example
+ * @example Legacy (back-compat) — плоская схема без модели
  * ```typescript
  * const form = createForm<UserForm>({
  *   email: { value: '', component: Input },

package/dist/core/utils/derived-registry.d.ts

@@ -1,5 +1,44 @@
 import { Signal } from '@preact/signals-core';
-/** Пометить сигнал производным (вызывают compute/computeFrom). */
+/**
+ * Пометить сигнал производным (вычисляемым).
+ *
+ * Вызывается операторами {@link computeFrom}/`compute` для их сигнала-цели. После этого
+ * bulk-сеттеры (`model.set`/`model.patch`, `patchValue`/`setValue`) пропускают это поле, чтобы
+ * значение из payload не затирало вычисляемое. Прикладной код напрямую обычно не вызывает.
+ *
+ * @param signal - Сигнал значения из {@link FormModel}, которым владеет compute
+ *
+ * @example
+ * ```typescript
+ * import { markDerived } from '@reformer/core';
+ *
+ * // Помечаем поле total как вычисляемое — bulk-set его не перезапишет
+ * markDerived(model.$.total);
+ * ```
+ *
+ * @see {@link isDerived} - проверка пометки
+ * @group Utilities
+ */
 export declare function markDerived(signal: Signal<any>): void;
-/** Производный ли сигнал (читают bulk-сеттеры, чтобы не затирать вычисляемые поля). */
+/**
+ * Производный ли сигнал (помечен через {@link markDerived}).
+ *
+ * Читается bulk-сеттерами модели/группы, чтобы не затирать вычисляемые (`computeFrom`) поля
+ * значениями из payload.
+ *
+ * @param signal - Сигнал значения из {@link FormModel}
+ * @returns `true`, если сигнал помечен производным
+ *
+ * @example
+ * ```typescript
+ * import { isDerived } from '@reformer/core';
+ *
+ * if (!isDerived(model.$.total)) {
+ *   model.$.total.value = payload.total; // писать в payload-значение только для «ручных» полей
+ * }
+ * ```
+ *
+ * @see {@link markDerived} - пометить сигнал производным
+ * @group Utilities
+ */
 export declare function isDerived(signal: Signal<any>): boolean;

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

@@ -4,7 +4,6 @@
  * Централизованные вспомогательные классы и функции.
  */
 export { SubscriptionManager } from './subscription-manager';
-export { RegistryStack } from './registry-stack';
 export { isFormNode, isFieldNode, isGroupNode, isArrayNode, getNodeType } from './type-guards';
 export { FormErrorHandler, ErrorStrategy } from './error-handler';
 export { createForm, createFormFromModel } from './create-form';
@@ -13,10 +12,7 @@ export { registerSignalNode, getNodeForSignal } from './signal-node-registry';
 export { markDerived, isDerived } from './derived-registry';
 export { uniqueId } from './unique-id';
 export { safeCallback, runOutsideEffect, safeDebouncedCallback } from './safe-effect';
-export { AbstractRegistry } from './abstract-registry';
 export { FormSubmitter } from './form-submitter';
 export type { SubmittableForm, SubmitOptions, SubmitResult } from './form-submitter';
 export { FormStatusMachine } from './status-machine';
 export type { StatusEvent } from './status-machine';
-export { FormObserver } from './form-observer';
-export type { FormChangeType, FormChangeEvent, FormChangeCallback, FormObserverOptions, ObservableForm, ObservableFormNode, } from './form-observer';

package/dist/core/utils/signal-node-registry.d.ts

@@ -1,12 +1,46 @@
 import { Signal } from '@preact/signals-core';
 import { FormNode } from '../nodes/form-node';
 /**
- * Связать сигнал модели с его FieldNode.
- * @internal
+ * Связать сигнал модели с его нодой формы.
+ *
+ * Вызывается движком при сборке формы (`createForm`/{@link createFormFromModel}) для каждого
+ * листового поля. Прикладной код обычно этот реестр не заполняет напрямую.
+ *
+ * @param signal - Сигнал значения из {@link FormModel} (ручка поля, `model.$.path`)
+ * @param node - Нода формы, отвечающая за это поле
+ *
+ * @example Привязка листовых полей при построении формы
+ * ```typescript
+ * import { registerSignalNode } from '@reformer/core';
+ *
+ * const sig = model.signalAt('profile.email');
+ * const node = group.getFieldByPath('profile.email');
+ * if (sig && node) registerSignalNode(sig, node);
+ * ```
+ *
+ * @see {@link getNodeForSignal} - обратный поиск ноды по сигналу
+ * @group Utilities
  */
 export declare function registerSignalNode(signal: Signal<any>, node: FormNode<any>): void;
 /**
- * Получить FieldNode по сигналу модели (или undefined, если форма не построена/поле не материализовано,
- * например элемент массива в родительской форме).
+ * Найти ноду формы по сигналу модели.
+ *
+ * Используется state-операциями behavior (`enableWhen`/`disableWhen`) и роутингом ошибок
+ * валидации в ноды. Возвращает `undefined`, если форма ещё не построена или поле не
+ * материализовано в этой форме (например, элемент массива, который строится per-item).
+ *
+ * @param signal - Сигнал значения из {@link FormModel}
+ * @returns Нода формы для этого поля или `undefined`
+ *
+ * @example Роутинг ошибок валидации в ноду поля
+ * ```typescript
+ * import { getNodeForSignal } from '@reformer/core';
+ *
+ * const sig = model.$.email;
+ * getNodeForSignal(sig)?.setErrors([{ code: 'required', message: 'Обязательно' }]);
+ * ```
+ *
+ * @see {@link registerSignalNode} - регистрация связи сигнал→нода
+ * @group Utilities
  */
 export declare function getNodeForSignal(signal: Signal<any>): FormNode<any> | undefined;

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

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

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

@@ -2,12 +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.eventDate, futureDate());
- * validate(path.appointmentDate, futureDate({ message: 'Дата записи должна быть в будущем' }));
+ * import { required, futureDate } from '@reformer/core/validators';
+ *
+ * // Внутри FieldConfig схемы формы:
+ * appointmentDate: {
+ *   value: model.$.appointmentDate,
+ *   component: DatePicker,
+ *   validators: [required(), futureDate({ message: 'Дата записи должна быть в будущем' })],
+ * },
  * ```
  */
 export declare function futureDate<TForm = unknown, TField extends string | Date | undefined = string | Date>(options?: ValidateOptions): Validator<TForm, TField>;

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

@@ -2,7 +2,8 @@
  * Reusable validator factories.
  *
  * Все примитивы — фабрики, возвращающие чистый Validator<TForm, TField>.
- * Использование: `validate(path.x, required())`, `validate(path.y, min(18))`.
+ * Импортируются из `@reformer/core/validators` и передаются в массив `validators`
+ * поля схемы формы: `validators: [required(), min(18)]`.
  */
 export { required } from './required';
 export { min } from './min';

package/dist/core/validation/validators/integer.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.age, integer());
- * validate(path.count, integer({ message: 'Должно быть целым числом' }));
+ * import { required, integer } from '@reformer/core/validators';
+ *
+ * // Внутри FieldConfig схемы формы:
+ * count: {
+ *   value: model.$.count,
+ *   component: Input,
+ *   validators: [required(), integer({ message: 'Должно быть целым числом' })],
+ * },
  * ```
  */
 export declare function integer<TForm = unknown, TField extends number | undefined = number>(options?: ValidateOptions): Validator<TForm, TField>;

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

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

package/dist/core/validation/validators/is-number.d.ts

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

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

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

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

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