@reformer/core 8.0.0 → 9.0.0

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

@@ -1,4 +1,5 @@
 import { FormNode } from '../nodes/form-node';
+import { ConfigWithSchema, ConfigWithValue, UnknownRecord } from '../types';
 /**
  * Фабрика для создания узлов формы.
  *
@@ -59,7 +60,7 @@ export declare class NodeFactory {
      * ]);
      * ```
      */
-    createNode<T>(config: unknown): FormNode<T>;
+    createNode(config: unknown): FormNode<unknown>;
     /**
      * Создать ArrayNode из массива [schema, ...initialItems]
      *
@@ -135,7 +136,7 @@ export declare class NodeFactory {
      * factory.isFieldConfig(null); // false
      * ```
      */
-    isFieldConfig(config: unknown): boolean;
+    isFieldConfig(config: unknown): config is ConfigWithValue;
     /**
      * Проверяет, является ли конфиг конфигурацией массива (ArrayConfig)
      *
@@ -157,7 +158,7 @@ export declare class NodeFactory {
      * factory.isArrayConfig({ email: { value: '' } }); // false
      * ```
      */
-    isArrayConfig(config: unknown): boolean;
+    isArrayConfig(config: unknown): config is ConfigWithSchema;
     /**
      * Проверяет, является ли конфиг конфигурацией группы (GroupConfig)
      *
@@ -183,5 +184,5 @@ export declare class NodeFactory {
      * factory.isGroupConfig(null); // false
      * ```
      */
-    isGroupConfig(config: unknown): boolean;
+    isGroupConfig(config: unknown): config is UnknownRecord;
 }

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

@@ -14,6 +14,14 @@ export type PathAwareSignal<T> = Signal<T> & {
  * @internal
  */
 type Opaque = Date | File | Blob;
+/**
+ * Фасад элемента массива при обходе (`at`/`map`/`forEach`): массив → {@link ModelArray},
+ * Opaque (Date/File/Blob) и примитив → значение, объект → под-модель {@link FormModel}.
+ * Зеркалит листовой/объектный сплит {@link ModelValue} (но объект → под-модель с API),
+ * чтобы `files: File[]`/`dates: Date[]`/вложенные массивы не мис-типизировались как `FormModel`.
+ * @internal
+ */
+type ModelArrayItem<U> = NonNullable<U> extends ReadonlyArray<infer E> ? ModelArray<E> : NonNullable<U> extends Opaque ? U : NonNullable<U> extends object ? FormModel<NonNullable<U>> : U;
 /**
  * Значение поля в value-доступе модели:
  * - массив → {@link ModelArray}
@@ -40,6 +48,11 @@ export type ModelObject<T> = {
  * @group Model
  */
 export interface ModelArray<U> {
+    /**
+     * Путь массива в модели (dot-нотация). Предоставляется рантаймом (value-прокси) и требуется
+     * рендер-слою для резолва узла массива (напр. `ArrayRenderNode` в `@reformer/renderer-react`).
+     */
+    readonly __path: string;
     /** Реактивная длина. */
     readonly length: number;
     /** Добавить элемент в конец (значение элемента целиком). */
@@ -54,12 +67,12 @@ export interface ModelArray<U> {
     swap(a: number, b: number): void;
     /** Очистить массив. */
     clear(): void;
-    /** Под-модель элемента по индексу (для объектных элементов) или значение (для примитивных). */
-    at(index: number): U extends object ? FormModel<U> : U | undefined;
-    /** Map по элементам: объектные → {@link FormModel}, примитивные → значение. */
-    map<R>(fn: (item: U extends object ? FormModel<U> : U, index: number) => R): R[];
-    /** Итерация по элементам. */
-    forEach(fn: (item: U extends object ? FormModel<U> : U, index: number) => void): void;
+    /** Элемент по индексу: объект → под-модель, массив → {@link ModelArray}, лист → значение. */
+    at(index: number): NonNullable<U> extends object ? ModelArrayItem<U> : ModelArrayItem<U> | undefined;
+    /** Map по элементам (объект → {@link FormModel}, Opaque/примитив → значение, массив → {@link ModelArray}). */
+    map<R>(fn: (item: ModelArrayItem<U>, index: number) => R): R[];
+    /** Итерация по элементам (см. {@link ModelArrayItem}). */
+    forEach(fn: (item: ModelArrayItem<U>, index: number) => void): void;
     /** Снимок массива значений (без подписки). */
     toArray(): U[];
     /** Индексный value-доступ. */
@@ -72,11 +85,19 @@ export interface ModelArray<U> {
  * @group Model
  */
 export type ModelSignals<T> = {
-    [K in keyof T]: NonNullable<T[K]> extends ReadonlyArray<infer U> ? {
-        readonly length: number;
-        readonly [index: number]: ModelSignals<U & object>;
-    } : NonNullable<T[K]> extends Opaque ? PathAwareSignal<T[K]> : NonNullable<T[K]> extends object ? ModelSignals<NonNullable<T[K]>> : PathAwareSignal<T[K]>;
+    [K in keyof T]: ModelSignalNode<T[K]>;
 };
+/**
+ * Узел дерева сигналов `model.$`: массив → индексируемый узел под-сигналов, Opaque (Date/File/Blob)
+ * и примитив → {@link PathAwareSignal}, объект → вложенное дерево {@link ModelSignals}. Для примитивных
+ * и Opaque массивов элемент — сам сигнал листа (а не под-дерево), поэтому `model.$.tags[0]` — это
+ * `PathAwareSignal<string>`, а не `ModelSignals<never>`.
+ * @internal
+ */
+type ModelSignalNode<V> = NonNullable<V> extends ReadonlyArray<infer U> ? {
+    readonly length: number;
+    readonly [index: number]: ModelSignalNode<U>;
+} : NonNullable<V> extends Opaque ? PathAwareSignal<V> : NonNullable<V> extends object ? ModelSignals<NonNullable<V>> : PathAwareSignal<V>;
 /**
  * API уровня модели (доступно на корне и под-моделях элементов массива).
  *
@@ -90,9 +111,17 @@ export interface ModelApi<T> {
     readonly $: ModelSignals<T>;
     /** Снимок значений (без подписки) — для submit. */
     get(): T;
-    /** Массовая замена значений (load с сервера). Не меняет initial-снимок. */
+    /**
+     * @deprecated Алиас {@link ModelApi.patch}: `set` выполняет то же частичное **слияние** —
+     *   обновляет только переданные ключи, отсутствующие НЕ трогает (это НЕ полная замена, вопреки
+     *   старому названию). Используйте `patch`; для замены с обнулением лишних полей делайте
+     *   `patch({ ...defaults, ...dto })` явно. Не меняет initial-снимок.
+     */
     set(value: Partial<T>): void;
-    /** Частичное слияние значений. */
+    /**
+     * Частичное слияние значений (load/patch с сервера): обновляет только переданные ключи,
+     * отсутствующие ключи НЕ трогаются. Не меняет initial-снимок.
+     */
     patch(value: Partial<T>): void;
     /** Отличаются ли текущие значения от initial-снимка (value-diff). */
     isDirty(): boolean;

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

@@ -1,9 +1,13 @@
 import { ValidationError } from '../types';
+import { FormSchemaNode } from '../types/schema-node';
 import { FormModel } from './types';
 /**
- * Валидатор слоя данных. `value` — значение поля; `model` — ближайший scope (под-модель элемента
+ * Валидатор слоя **данных**. `value` — значение поля; `model` — ближайший scope (под-модель элемента
  * массива или корень); `root` — корневая модель.
  *
+ * Отличие от {@link Validator}: 2-й/3-й аргументы — сами данные ({@link FormModel}/scope), а не
+ * `FormProxy`-узлы формы. Оба совместимы с полем `validators` узла схемы (см. {@link SchemaValidator}).
+ *
  * @group Model
  */
 export type ModelValidator<TValue = unknown, TModel = unknown, TRoot = unknown> = (value: TValue, model: TModel, root: TRoot) => ValidationError | null | Promise<ValidationError | null>;
@@ -32,7 +36,7 @@ export interface ModelValidationResult {
  * if (!res.valid) console.log(res.errors); // { 'email': [{ code, message }], ... }
  * ```
  */
-export declare function validateModelSync<T>(model: FormModel<T>, schema: unknown): ModelValidationResult;
+export declare function validateModelSync<T>(model: FormModel<T>, schema: FormSchemaNode): ModelValidationResult;
 /**
  * Headless-валидация данных (sync + async). Работает без UI/нод.
  *
@@ -43,7 +47,7 @@ export declare function validateModelSync<T>(model: FormModel<T>, schema: unknow
  * if (!res.valid) console.log(res.errors); // { 'email': [{ code, message }], ... }
  * ```
  */
-export declare function validateModel<T>(model: FormModel<T>, schema: unknown): Promise<ModelValidationResult>;
+export declare function validateModel<T>(model: FormModel<T>, schema: FormSchemaNode): Promise<ModelValidationResult>;
 /**
  * In-form валидация: прогоняет {@link validateModel} и роутит ошибки в ноды формы
  * (через реестр сигнал→нода): `node.setErrors(errors[path] ?? [])` — заодно очищает прошедшие поля
@@ -65,4 +69,4 @@ export declare function validateModel<T>(model: FormModel<T>, schema: unknown):
  * if (res.valid) await api.save(model.get());
  * ```
  */
-export declare function validateFormModel<T>(model: FormModel<T>, schema: unknown): Promise<ModelValidationResult>;
+export declare function validateFormModel<T>(model: FormModel<T>, schema: FormSchemaNode): Promise<ModelValidationResult>;

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

@@ -35,7 +35,7 @@ export declare class FieldNode<T> extends FormNode<T> {
     readonly status: ReadonlySignal<FieldStatus>;
     readonly disabled: ReadonlySignal<boolean>;
     readonly errors: ReadonlySignal<ValidationError[]>;
-    readonly componentProps: ReadonlySignal<Record<string, any>>;
+    readonly componentProps: ReadonlySignal<Record<string, unknown>>;
     /**
      * Вычисляемое свойство: нужно ли показывать ошибку
      * Ошибка показывается если поле невалидно И (touched ИЛИ dirty)
@@ -186,7 +186,7 @@ export declare class FieldNode<T> extends FormNode<T> {
      * });
      * ```
      */
-    updateComponentProps(props: Partial<Record<string, any>>): void;
+    updateComponentProps(props: Partial<Record<string, unknown>>): void;
     /**
      * Динамически изменяет триггер валидации (updateOn)
      * Полезно для адаптивной валидации - например, переключиться на instant feedback после первого submit

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

@@ -244,7 +244,13 @@ export declare class GroupNode<T> extends FormNode<T> {
      * useEffect(() => dispose, []);
      * ```
      */
-    watchField<K extends keyof T>(fieldPath: K extends string ? K : string, callback: (value: T[K]) => void | Promise<void>): () => void;
+    /** Подписка на top-level поле — value типизирован как `T[K]`. */
+    watchField<K extends keyof T & string>(fieldPath: K, callback: (value: T[K]) => void | Promise<void>): () => void;
+    /**
+     * Подписка на вложенное поле по строковому пути ("address.city").
+     * Путь нельзя выразить в типах узла → value честно `unknown`, потребитель сужает.
+     */
+    watchFieldByPath(path: string, callback: (value: unknown) => void | Promise<void>): () => void;
     /**
      * Hook: вызывается после disable()
      */

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

@@ -104,6 +104,11 @@ export declare class ModelArrayNode<T extends object> extends FormNode<T[]> {
     setErrors(errors: ValidationError[]): void;
     clearErrors(): void;
     protected onMarkAsTouched(): void;
+    protected onMarkAsUntouched(): void;
+    protected onMarkAsDirty(): void;
+    protected onMarkAsPristine(): void;
+    protected onDisable(): void;
+    protected onEnable(): void;
     /** Очистка подписки синхронизации. */
     dispose(): void;
 }

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

@@ -1,10 +1,17 @@
 import { ComponentType } from 'react';
 import { Signal } from '@preact/signals-core';
-import { ValidatorFn, AsyncValidatorFn, FormFields, AnyFunction } from './index';
+import { ValidatorFn, AsyncValidatorFn, AnyFunction } from './index';
 /**
  * Конфигурация поля
  * @group Types
  * @category Configuration Types
+ * @remarks
+ * В схеме `createForm({ model, schema })` лист связывают через **`value: model.$.field`**: harvest
+ * ловит узел по идентичности `Signal` (`node.value instanceof Signal` — см. `create-form.ts`) и
+ * нормализует его в `valueSignal`. Писать `valueSignal:` **в самой схеме `createForm` нельзя** —
+ * harvest его не подхватит (проверка идёт по `node.value`), и `component`/`componentProps` этого
+ * узла молча отбросятся. `value`/`valueSignal` на прямом FieldNode-конфиге — это
+ * post-normalization / legacy-слой, а не форма записи в схеме `createForm`.
  */
 export interface FieldConfig<T> {
     /**
@@ -35,17 +42,22 @@ export interface FieldConfig<T> {
  * @group Types
  * @category Configuration Types
  */
-export interface ArrayConfig<T extends FormFields> {
+export interface ArrayConfig<T extends object> {
     itemSchema: FormSchema<T>;
     initial?: Partial<T>[];
 }
 /**
- * Автоматически определяет тип схемы на основе TypeScript типа:
+ * **Data-shaped** конфиг формы: ключи повторяют структуру данных `T`, значения — {@link FieldConfig}
+ * (или вложенный `FormSchema`). Форма конфига, из которой строится {@link GroupNode}.
  * - `T[] -> [FormSchema<T>]` (массив с одним элементом)
  * - `object -> FormSchema<T>` (группа)
  * - `primitive -> FieldConfig<T>` (поле)
  *
- * Использует NonNullable для корректной обработки опциональных полей
+ * Использует NonNullable для корректной обработки опциональных полей.
+ *
+ * ⚠️ Не путать с {@link FormSchemaNode} — тот описывает **узел дерева** M1-схемы (лист/массив/
+ * контейнер), передаваемой в `createForm({ model, schema })`. `FormSchema` — это data-shaped конфиг
+ * (ключи = поля данных), а не узел дерева.
  *
  * @group Types
  * @category Configuration Types

package/dist/core/types/form-proxy.d.ts

@@ -12,7 +12,7 @@ import { ArrayNode } from '../nodes/array-node';
  *
  * @internal
  */
-type IsGroupObject<V> = V extends ReadonlyArray<unknown> ? false : V extends Date | File | Blob ? false : V extends object ? true : false;
+type IsGroupObject<V> = V extends ReadonlyArray<unknown> ? false : V extends Date | File | Blob ? false : V extends (...args: never[]) => unknown ? false : V extends object ? true : false;
 /**
  * Мапит тип модели данных T на правильные типы узлов формы
  *

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

@@ -70,7 +70,7 @@ export type AsyncValidatorFn<T = FormValue> = (value: T, options?: AsyncValidato
 export interface ValidationError {
     code: string;
     message: string;
-    params?: FormFields;
+    params?: Record<string, FormValue>;
     /** Severity level: 'error' (default) blocks submission, 'warning' shows message but allows submission */
     severity?: 'error' | 'warning';
 }
@@ -85,7 +85,7 @@ export interface ErrorFilterOptions {
     /** Фильтр по сообщению (поддерживает частичное совпадение) */
     message?: string;
     /** Фильтр по параметрам ошибки */
-    params?: FormFields;
+    params?: Record<string, FormValue>;
     /** Кастомный предикат для фильтрации */
     predicate?: (error: ValidationError) => boolean;
 }
@@ -98,6 +98,7 @@ export type FieldStatus = 'valid' | 'invalid' | 'pending' | 'disabled';
 export type { FieldConfig } from './deep-schema';
 export type { Validator, AsyncValidator, ConditionFn, ValidateOptions, ValidateAsyncOptions, } from './validation-schema';
 export type { FormSchema, ArrayConfig } from './deep-schema';
+export type { FormSchemaNode, SchemaArrayControl, SchemaValidator } from './schema-node';
 export type { FormControlsProxy, FormProxy, FormArrayProxy } from './form-proxy';
 /**
  * Конфигурация GroupNode.
@@ -117,7 +118,7 @@ export interface GroupNodeConfig<T> {
  * Используется вместо инлайнового `Record<string, unknown>`
  * @internal
  */
-export type UnknownRecord = Record<string, any>;
+export type UnknownRecord = Record<string, unknown>;
 /**
  * Интерфейс для узлов с методом applyValidationSchema
  * @internal
@@ -156,13 +157,6 @@ export interface ConfigWithSchema {
 export interface ConfigWithValue {
     value: unknown;
 }
-/**
- * Тип для конфига с полями (FormSchema generic constraint)
- * Используется вместо `Record<string, any>` для схем форм
- * @deprecated
- * @internal
- */
-export type FormFields = Record<string, FormValue>;
 /**
  * Тип для путей к полям (field paths)
  * Используется в навигации по полям вместо any

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

@@ -0,0 +1,79 @@
+import { ComponentType } from 'react';
+import { ValidationError } from './index';
+/**
+ * Валидатор поля схемы. Узел хранит validators гетерогенно: движок `validate*` вызывает их как
+ * `(value, scope, root)`, но сюда кладут любой контракт — `ValidatorFn` (value),
+ * `Validator` (value, control, root) или `ModelValidator` (value, model, root). Поэтому тип
+ * намеренно широкий по параметрам.
+ *
+ * @group Types
+ */
+export type SchemaValidator = (value: any, ...rest: any[]) => ValidationError | null | Promise<ValidationError | null>;
+/**
+ * Минимальный контракт реактивного массива модели ({@link FormSchemaNode.array}).
+ * Совпадает по форме с рантайм-фасадом `model.<array>` (см. `ModelArray`); рендерерский
+ * `RenderModelArrayControl` — его расширение (добавляет `move`).
+ *
+ * @group Types
+ */
+export interface SchemaArrayControl {
+    /** Путь массива в модели (dot-нотация) — нужен для резолва узла массива. */
+    readonly __path: string;
+    /** Реактивная длина. */
+    readonly length: number;
+    at(index: number): unknown;
+    push(item: unknown): void;
+    removeAt(index: number): void;
+}
+/**
+ * Узел единой схемы M1 — дерево, обходимое `createForm({ model, schema })`,
+ * `validateModel`/`validateFormModel` и рендерерами.
+ *
+ * Узел совмещает несколько ролей (различаются рантаймом по форме):
+ *  - **поле** — несёт `value: Signal` (сигнал модели `model.$.x`) + `component`/`validators`;
+ *  - **массив** — `{ array: model.<path>, item(itemModel) }`;
+ *  - **контейнер/ветка** — вложенные узлы (`children`), опц. условие `when`;
+ *  - **record-of-fields** — под-узлы под произвольными именованными ключами (индексная сигнатура).
+ *
+ * Индексная сигнатура (`[key: string]: unknown`) отражает свободный рекурсивный обход: под-узлы
+ * допустимы под любым ключом. Известные поля типизированы (даёт автокомплит и проверку их типов).
+ *
+ * @group Types
+ */
+export interface FormSchemaNode {
+    /**
+     * «Ручка» значения поля — маркер узла-поля. Обычно сигнал модели (`model.$.<path>`), но форма
+     * зависит от таргета (для массива `model.$.x` — дерево сигналов; в renderer-типах сужается до
+     * `Signal`). Движок разбирает узел как поле рантаймом по `value instanceof Signal`.
+     */
+    value?: unknown;
+    /** UI-компонент. Опционален: core-часть работает без UI (значение/валидация). */
+    component?: ComponentType<any>;
+    /** Props компонента. Также «клапан» для вложенности под-узлов (напр. steps визарда). */
+    componentProps?: Record<string, unknown>;
+    validators?: SchemaValidator[];
+    asyncValidators?: SchemaValidator[];
+    updateOn?: 'change' | 'blur' | 'submit';
+    disabled?: boolean;
+    /** Задержка (мс) перед запуском асинхронной валидации. */
+    debounce?: number;
+    /** Идентификатор узла (для wizard/tabs/renderBehavior). */
+    selector?: string;
+    testId?: string;
+    /** Дочерние узлы (даёт контекстную типизацию вложенным литералам — value/validators/when). */
+    children?: readonly FormSchemaNode[];
+    /** Условие включения поддерева (branch-узел `{ when, children }`). */
+    when?: (scope: any, root: any) => boolean;
+    /** Реактивный массив модели (`model.<path>`) — маркер узла-массива (вместе с `item`). */
+    array?: SchemaArrayControl;
+    /** Схема элемента массива: под-модель элемента → узел поддерева. */
+    item?: (itemModel: any) => FormSchemaNode;
+    /**
+     * Значение нового элемента массива для кнопки «Добавить»: либо готовое значение,
+     * либо фабрика `() => value`. Тип не различает варианты (union `unknown | (() => unknown)`
+     * схлопывается в `unknown`) — рантайм различает по `typeof initialValue === 'function'`.
+     */
+    initialValue?: unknown;
+    /** Свободная вложенность: record-of-fields и произвольные под-узлы. */
+    [key: string]: unknown;
+}

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

@@ -1,15 +1,26 @@
-import { FormFields, ValidationError } from './index';
-import { FormProxy } from './form-proxy';
+import { FormValue, ValidationError } from './index';
+import { FormModel } from '../model/types';
 /**
  * Чистый синхронный валидатор поля.
  *
- * Принимает значение поля, прокси текущего поля (control) и прокси корня формы (root).
- * Возвращает ValidationError либо null. Не знает про реестр валидации.
+ * Сигнатура зеркалит то, что реально вызывает движок M1
+ * (`validateModel`/`validateFormModel`/`validateModelSync`): `validator(value, scope, root)`.
+ * - `value` — значение поля (`TField`);
+ * - `scope` — ближайшая scope-**модель** (под-модель элемента массива или корень). Из `TForm`/`TField`
+ *   её тип не выводится, поэтому `unknown` — потребитель сужает сам (для типизированного scope
+ *   используйте {@link ModelValidator}`<TField, TScope, TForm>`);
+ * - `root` — корневая модель формы `FormModel<TForm>` (реактивный value-proxy: `root.field` читает
+ *   значение). Возвращает `ValidationError` либо `null`. Не знает про реестр валидации.
+ *
+ * Совместим с полем `validators` узла схемы (см. `SchemaValidator`) — там же лежат `ModelValidator`
+ * и `ValidatorFn`. Встроенные фабрики (`required()`/`email()`/…) возвращают `(value) => …` и
+ * дополнительные аргументы игнорируют.
  *
  * @example Кастомный валидатор в массиве `validators` поля схемы
  * ```typescript
- * const isAdult: Validator<MyForm, number> = (value, control, root) => {
+ * const isAdult: Validator<MyForm, number> = (value, _scope, root) => {
  *   if (value < 18) return { code: 'tooYoung', message: '18+' };
+ *   // root — FormModel<MyForm>: root.someOtherField читается как значение
  *   return null;
  * };
  *
@@ -21,13 +32,13 @@ import { FormProxy } from './form-proxy';
  * };
  * ```
  */
-export type Validator<TForm, TField> = (value: TField, control: FormProxy<TField>, root: FormProxy<TForm>) => ValidationError | null;
+export type Validator<TForm, TField> = (value: TField, scope: unknown, root: FormModel<TForm>) => ValidationError | null;
 /**
- * Чистый асинхронный валидатор поля.
- *
- * Регистрируется через `validateAsync(path, validator, { debounce })`.
+ * Чистый асинхронный валидатор поля. Та же тройка аргументов `(value, scope, root)`, что у
+ * {@link Validator}, но возвращает `Promise`. Регистрируется через
+ * `validateAsync(path, validator, { debounce })`.
  */
-export type AsyncValidator<TForm, TField> = (value: TField, control: FormProxy<TField>, root: FormProxy<TForm>) => Promise<ValidationError | null>;
+export type AsyncValidator<TForm, TField> = (value: TField, scope: unknown, root: FormModel<TForm>) => Promise<ValidationError | null>;
 /**
  * Функция условия для applyWhen.
  */
@@ -39,7 +50,7 @@ export interface ValidateOptions {
     /** Сообщение об ошибке */
     message?: string;
     /** Параметры ошибки */
-    params?: FormFields;
+    params?: Record<string, FormValue>;
 }
 /**
  * Опции для функции validateAsync.

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

@@ -1,4 +1,5 @@
 import { FormProxy, GroupNodeConfig, FormSchema } from '../types';
+import { FormSchemaNode } from '../types/schema-node';
 import { FormModel } from '../model/types';
 import { FormBehavior } from '../../behaviors';
 /**
@@ -11,10 +12,10 @@ export interface CreateFormFromModelArgs<T> {
     /** Реактивная модель данных (источник истины значений). */
     model: FormModel<T>;
     /**
-     * Единая Schema (дерево узлов). createForm обходит её и привязывает конфиг поля к ноде
-     * по идентичности сигнала (`node.value === model.$.path`). Опциональна.
+     * Единая Schema (дерево узлов {@link FormSchemaNode}). createForm обходит её и привязывает конфиг
+     * поля к ноде по идентичности сигнала (`node.value === model.$.path`). Опциональна.
      */
-    schema?: unknown;
+    schema?: FormSchemaNode;
     /**
      * Декларативная схема поведения ({@link defineFormBehavior}). Запускается ПОСЛЕ построения нод и
      * заполнения реестра сигнал→нода; cleanup живёт на форме и вызывается в `form.dispose()`.

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

@@ -93,7 +93,10 @@ export declare class FormErrorHandler {
      * }
      * ```
      */
-    static handle(error: unknown, context: string, strategy?: ErrorStrategy): ValidationError | never | void;
+    static handle(error: unknown, context: string, strategy: ErrorStrategy.CONVERT): ValidationError;
+    static handle(error: unknown, context: string, strategy: ErrorStrategy.THROW): never;
+    static handle(error: unknown, context: string, strategy: ErrorStrategy.LOG): void;
+    static handle(error: unknown, context: string): never;
     /**
      * Извлечь сообщение из ошибки
      *

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

@@ -1,10 +1,9 @@
 import { ReadonlySignal } from '@preact/signals-core';
-import { FormFields } from '../types';
 /**
  * Интерфейс формы для FormSubmitter
  * Минимальный контракт для работы с любой формой
  */
-export interface SubmittableForm<T extends FormFields> {
+export interface SubmittableForm<T extends object> {
     /** Пометить все поля как touched */
     markAsTouched(): void;
     /** Валидировать форму */
@@ -50,7 +49,7 @@ export interface SubmitResult<R> {
  * }
  * ```
  */
-export declare class FormSubmitter<T extends FormFields> {
+export declare class FormSubmitter<T extends object> {
     private readonly form;
     /** Внутренний сигнал состояния отправки */
     private readonly _submitting;

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

@@ -2,7 +2,7 @@ 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';
+import { FormValue } from '../types';
 /**
  * Проверить, является ли значение любым FormNode
  *
@@ -61,7 +61,7 @@ export declare function isFieldNode(value: unknown): value is FieldNode<FormValu
  * }
  * ```
  */
-export declare function isGroupNode(value: unknown): value is GroupNode<FormFields>;
+export declare function isGroupNode(value: unknown): value is GroupNode<object>;
 /**
  * Проверить, является ли значение ArrayNode (массив форм)
  *
@@ -80,7 +80,7 @@ export declare function isGroupNode(value: unknown): value is GroupNode<FormFiel
  * }
  * ```
  */
-export declare function isArrayNode(value: unknown): value is ArrayNode<FormFields>;
+export declare function isArrayNode(value: unknown): value is ArrayNode<object>;
 /**
  * Получить тип узла как строку (для отладки)
  *

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

@@ -21,6 +21,10 @@ export declare function getToday(): Date;
  */
 export declare function normalizeDate(date: Date): Date;
 /**
- * Вычисляет возраст на основе даты рождения
+ * Вычисляет полный возраст (в годах) по календарным полям.
+ *
+ * Считаем по годам/месяцам/дням, а не делением миллисекунд на усреднённый год (365.25 дн): усреднение
+ * даёт off-by-one на границе — в день N-летия накопленных реальных дней меньше `N * 365.25`, и `floor`
+ * роняет возраст до `N - 1` (т.е. `minAge(18)` ошибочно отклонял 18-летнего в его день рождения).
  */
 export declare function calculateAge(birthDate: Date): number;

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

@@ -19,4 +19,4 @@ import { Validator, ValidateOptions } from '../../types/validation-schema';
  * },
  * ```
  */
-export declare function integer<TForm = unknown, TField extends number | undefined = number>(options?: ValidateOptions): Validator<TForm, TField>;
+export declare function integer<TForm = unknown, TField extends number | null | undefined = number>(options?: ValidateOptions): Validator<TForm, TField>;

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

@@ -21,4 +21,4 @@ import { Validator, ValidateOptions } from '../../types/validation-schema';
  * },
  * ```
  */
-export declare function isNumber<TForm = unknown, TField extends number | undefined = number>(options?: ValidateOptions): Validator<TForm, TField>;
+export declare function isNumber<TForm = unknown, TField extends number | null | undefined = number>(options?: ValidateOptions): Validator<TForm, TField>;

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

@@ -22,4 +22,4 @@ import { Validator, ValidateOptions } from '../../types/validation-schema';
  * },
  * ```
  */
-export declare function max<TForm = unknown, TField extends number | undefined = number>(maxValue: number, options?: ValidateOptions): Validator<TForm, TField>;
+export declare function max<TForm = unknown, TField extends number | null | undefined = number>(maxValue: number, options?: ValidateOptions): Validator<TForm, TField>;

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

@@ -22,4 +22,4 @@ import { Validator, ValidateOptions } from '../../types/validation-schema';
  * },
  * ```
  */
-export declare function min<TForm = unknown, TField extends number | undefined = number>(minValue: number, options?: ValidateOptions): Validator<TForm, TField>;
+export declare function min<TForm = unknown, TField extends number | null | undefined = number>(minValue: number, options?: ValidateOptions): Validator<TForm, TField>;

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

@@ -21,4 +21,4 @@ import { Validator, ValidateOptions } from '../../types/validation-schema';
  * },
  * ```
  */
-export declare function multipleOf<TForm = unknown, TField extends number | undefined = number>(divisor: number, options?: ValidateOptions): Validator<TForm, TField>;
+export declare function multipleOf<TForm = unknown, TField extends number | null | undefined = number>(divisor: number, options?: ValidateOptions): Validator<TForm, TField>;

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

@@ -19,4 +19,4 @@ import { Validator, ValidateOptions } from '../../types/validation-schema';
  * },
  * ```
  */
-export declare function nonNegative<TForm = unknown, TField extends number | undefined = number>(options?: ValidateOptions): Validator<TForm, TField>;
+export declare function nonNegative<TForm = unknown, TField extends number | null | undefined = number>(options?: ValidateOptions): Validator<TForm, TField>;

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

@@ -19,4 +19,4 @@ import { Validator, ValidateOptions } from '../../types/validation-schema';
  * },
  * ```
  */
-export declare function nonZero<TForm = unknown, TField extends number | undefined = number>(options?: ValidateOptions): Validator<TForm, TField>;
+export declare function nonZero<TForm = unknown, TField extends number | null | undefined = number>(options?: ValidateOptions): Validator<TForm, TField>;