@reformer/core 11.0.0-beta.1 → 11.0.0-beta.10

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

@@ -1,57 +1,5 @@
-import { FormSchema } from './deep-schema';
-import { FormNode } from '../nodes/form-node';
-export type { FormValue, ValidatorFn, AsyncValidatorOptions, AsyncValidatorFn, ValidationError, ErrorFilterOptions, FieldStatus, } from './contracts';
-export type { FieldConfig } from './deep-schema';
-export type { Validator, ValidateOptions } from './validation-schema';
-export type { FormSchema } from './deep-schema';
-export type { FormSchemaNode, SchemaArrayControl } from './schema-node';
-export type { FormControlsProxy, FormProxy, FormArrayProxy } from './form-proxy';
-/**
- * Конфигурация GroupNode.
- *
- * Под M1 группа создаётся из плоской {@link FormSchema} (дерево field-конфигов). Обёртка
- * `{ form }` сохранена для совместимости вызова, legacy behavior/validation-схемы удалены (Ф7).
- *
- * @group Types
- * @category Configuration Types
- */
-export interface GroupNodeConfig<T> {
-    /** Схема структуры формы (поля и их конфигурация) */
-    form: FormSchema<T>;
-}
-/**
- * Тип для Record с unknown значениями
- * Используется вместо инлайнового `Record<string, unknown>`
- * @internal
- */
-export type UnknownRecord = Record<string, unknown>;
-/**
- * Интерфейс для узлов, похожих на ArrayNode (с методом at)
- * Используется для duck typing при обходе путей
- * @internal
- */
-export interface ArrayNodeLike {
-    at(index: number): FormNode<unknown> | undefined;
-    length: unknown;
-}
-/**
- * Конфиг с полем schema (для ArrayConfig)
- * @internal
- */
-export interface ConfigWithSchema {
-    schema: unknown;
-    initialItems?: unknown[];
-}
-/**
- * Конфиг с полем value (для извлечения значений)
- * @internal
- */
-export interface ConfigWithValue {
-    value: unknown;
-}
-/**
- * Тип для проверки на функцию в conditional types
- * Используется вместо Function для type narrowing
- * @internal
- */
-export type AnyFunction = (...args: never[]) => unknown;
+export type { ValidationIssue } from './contracts';
+export type { FieldConfig } from './field-config';
+export type { RuleOptions } from './validation-schema';
+export type { ComponentRef, FormSchemaNode, SchemaFieldNode, SchemaArrayNode, SchemaPartNode, SchemaContainerNode, SchemaChild, SchemaValueHandle, SchemaArrayHandle, SchemaGroupHandle, SchemaArrayControl, } from './schema-node';
+export type { FormNode, FormControl, FormGroup, FormArray, FormFields } from './nodes';

package/dist/form/types/nodes.d.ts

@@ -0,0 +1,159 @@
+import { ReadonlySignal } from '@preact/signals-core';
+import { ValidationIssue } from './contracts';
+import { ComponentRef } from './schema-node';
+/**
+ * Общий контракт ноды формы — поля, группы и массива под-форм.
+ *
+ * Значением нода не владеет: источник истины — модель (`model.$.<путь>`), нода держит состояние
+ * взаимодействия (`touched`, `dirty`), доступность и замечания валидации.
+ *
+ * @typeParam T - Значение ноды
+ *
+ * @example
+ * ```typescript
+ * const { form } = createForm<{ email: string }>({ initial: { email: '' } });
+ * form.email.setValue('user@mail.com');
+ * form.email.markAsTouched();
+ * form.valid.value; // true — замечаний нет
+ * ```
+ */
+export interface FormNode<T> {
+    /** Текущее значение. */
+    readonly value: ReadonlySignal<T>;
+    /** Замечаний, которые блокируют отправку, нет; нода включена и не ждёт проверки. */
+    readonly valid: ReadonlySignal<boolean>;
+    /** Есть блокирующие замечания; нода включена и не ждёт проверки. */
+    readonly invalid: ReadonlySignal<boolean>;
+    /** Идёт асинхронная проверка. */
+    readonly pending: ReadonlySignal<boolean>;
+    /** Нода отключена: её замечания сняты, в проверку она не входит. */
+    readonly disabled: ReadonlySignal<boolean>;
+    /** Пользователь взаимодействовал с нодой. */
+    readonly touched: ReadonlySignal<boolean>;
+    /** Значение меняли после создания или сброса. */
+    readonly dirty: ReadonlySignal<boolean>;
+    /** Замечания ноды; у группы и массива — свои и всех детей. */
+    readonly issues: ReadonlySignal<readonly ValidationIssue[]>;
+    /**
+     * Собственные замечания ноды — без замечаний детей: у группы и массива это правила на их ручке
+     * (`minLength` массива, `cross` группы), у поля — то же, что `issues`.
+     */
+    readonly ownIssues: ReadonlySignal<readonly ValidationIssue[]>;
+    /** Значение без подписки. */
+    getValue(): T;
+    /** Записать значение в модель. */
+    setValue(value: T): void;
+    /**
+     * Вернуть значение и состояние к начальным; с аргументом — к переданному значению. В цель
+     * `compute` значение не пишется (кроме явного `reset(значение)` самого поля): ею владеет
+     * поведение — сбрасывается только состояние.
+     */
+    reset(value?: T): void;
+    markAsTouched(): void;
+    markAsUntouched(): void;
+    enable(): void;
+    disable(): void;
+    /** Поставить замечания извне (ответ сервера, своя проверка). */
+    setIssues(issues: readonly ValidationIssue[]): void;
+    clearIssues(): void;
+}
+/**
+ * Поле формы: нода над листом модели и состояние его компонента.
+ *
+ * @typeParam T - Значение поля
+ */
+export interface FormControl<T> extends FormNode<T> {
+    /** Компонент поля из узла схемы. */
+    readonly component: ComponentRef | undefined;
+    /** Пропсы компонента: из узла схемы и правок {@link FormControl.updateComponentProps}. */
+    readonly componentProps: ReadonlySignal<Readonly<Record<string, unknown>>>;
+    /**
+     * Показывать ли состояние ошибки (`aria-invalid`, рамка): поле невалидно и его трогали или
+     * меняли. Предупреждение (`severity: 'warning'`) поле невалидным не делает — тексты замечаний
+     * показывают по {@link FormControl.shouldShowIssues}.
+     */
+    readonly shouldShowError: ReadonlySignal<boolean>;
+    /**
+     * Показывать ли тексты замечаний: у поля есть замечания — ошибки или предупреждения, — и его
+     * трогали или меняли. Условия те же, что у {@link FormControl.shouldShowError} (не выключено,
+     * проверка не идёт), но в счёт идёт любое замечание, а не только блокирующее.
+     */
+    readonly shouldShowIssues: ReadonlySignal<boolean>;
+    /** Слить правку в пропсы компонента (например, опции после загрузки справочника). */
+    updateComponentProps(patch: Record<string, unknown>): void;
+}
+/**
+ * Массив под-форм: строка — {@link FormGroup} над элементом массива модели.
+ *
+ * Данными массив не владеет: мутации уходят в массив модели, формы строк держатся за под-модели
+ * и при `move`/`swap` не пересоздаются.
+ *
+ * Индексы (`at`, `keyAt`, `insert`, `removeAt`, `move`, `swap`) — по строкам формы. Элемент `null`
+ * в массиве модели строкой не становится, и индекс строки может не совпасть с индексом модели.
+ *
+ * @typeParam T - Элемент массива
+ */
+export interface FormArray<T extends object> extends FormNode<T[]> {
+    /** Число строк; чтение в эффекте или `computed` подписывает на изменения. */
+    readonly length: number;
+    at(index: number): FormGroup<T> | undefined;
+    map<R>(callback: (row: FormGroup<T>, index: number) => R): R[];
+    forEach(callback: (row: FormGroup<T>, index: number) => void): void;
+    /** Стабильный ключ строки: держится за элемент модели и не меняется при `move` и `swap`. */
+    keyAt(index: number): string;
+    /** Добавить строку; без значения — по шаблону массива модели (`arrayOf(blank)`). */
+    push(item?: T): void;
+    insert(index: number, item?: T): void;
+    removeAt(index: number): void;
+    move(from: number, to: number): void;
+    swap(first: number, second: number): void;
+    clear(): void;
+}
+/**
+ * Признак «объект-группа»: обычный объект, а не массив, дата, файл, функция или примитив.
+ * `extends object` ловит и `interface`, и `type` (интерфейс не приводится к `Record`).
+ * Значение неизвестной формы (`unknown`, `{}`) — поле: у него нет известных полей, и словарь
+ * `Record<string, unknown>` остаётся группой полей, а не группой групп — иначе такая группа не
+ * приводилась бы к `FormGroup<any>` внутри обобщённых типов (контекст React, элементы списка).
+ *
+ * @internal
+ */
+type IsGroupObject<V> = V extends ReadonlyArray<unknown> ? false : V extends Date | File | Blob ? false : V extends (...args: never[]) => unknown ? false : V extends object ? Record<never, never> extends V ? false : true : false;
+/** `T` — это `any`. @internal */
+type IsAny<T> = 0 extends 1 & T ? true : false;
+/**
+ * Ноды полей группы по именам полей данных: массив объектов — {@link FormArray}, объект —
+ * {@link FormGroup}, остальное (примитивы, массивы примитивов, даты, файлы) — {@link FormControl}.
+ * Опциональность снята: нода есть у каждого поля, опционально лишь значение.
+ *
+ * `FormFields<any>` — нестрогий словарь: так группа любой формы приводится к `FormGroup<any>`
+ * (контекст React, обобщённые компоненты), а не упирается в отображение полей типа `any`.
+ *
+ * @typeParam T - Значение группы
+ */
+export type FormFields<T> = IsAny<T> extends true ? Record<string, any> : {
+    [K in keyof T]-?: NonNullable<T[K]> extends ReadonlyArray<infer U> ? IsGroupObject<U> extends true ? FormArray<U & object> : FormControl<T[K]> : IsGroupObject<NonNullable<T[K]>> extends true ? FormGroup<NonNullable<T[K]>> : FormControl<T[K]>;
+};
+/**
+ * Группа полей: нода над группой модели и доступ к нодам полей.
+ *
+ * `form.email` — нода поля; поле с именем члена {@link FormNode} (`value`, `issues`, `reset`, …)
+ * недостижимо точкой и доступно через `form.$`: `form.$.value`. Остальные имена полей данных
+ * (`id`, `status`, `fields`, `submit`, …) ничем не затенены.
+ *
+ * @typeParam T - Значение группы
+ *
+ * @example
+ * ```typescript
+ * interface Order { status: string; value: number; customer: { name: string } }
+ * const { form } = createForm<Order>({ initial: { status: 'new', value: 0, customer: { name: '' } } });
+ * form.status.setValue('paid');      // поле данных
+ * form.$.value.setValue(100);        // поле, затенённое членом ноды
+ * form.customer.name.markAsTouched();
+ * ```
+ */
+export type FormGroup<T> = FormNode<T> & Omit<FormFields<T>, keyof FormNode<T>> & {
+    /** Ноды всех полей по имени, включая затенённые членами {@link FormNode}. */
+    readonly $: FormFields<T>;
+};
+export {};

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

@@ -1,8 +1,22 @@
-import { ElementType } from 'react';
 import { Signal } from '../../signals';
 /**
- * Минимальный контракт реактивного массива модели ({@link FormSchemaNode.array}).
- * Совпадает по форме с рантайм-фасадом `model.<array>` (см. `ModelArray`); рендерерский
+ * Ссылка на компонент узла схемы: то, что слой представления умеет нарисовать. Для React это
+ * компонент (функция либо объект `forwardRef`/`memo`) или имя HTML-тега (`'div'`, `'h3'`).
+ *
+ * Ядро ссылку не интерпретирует и о слое представления не знает: она доезжает до рендерера как
+ * есть, а к типу своего UI-слоя её приводит уже он.
+ *
+ * @example
+ * ```ts
+ * const byComponent: ComponentRef = Input; // React-компонент
+ * const byTag: ComponentRef = 'section'; // HTML-тег
+ * ```
+ *
+ * @group Types
+ */
+export type ComponentRef = string | object;
+/**
+ * Контракт реактивного массива модели — фасада `model.<массив>`. Рендерерский
  * `RenderModelArrayControl` — его расширение (добавляет `move`).
  *
  * @group Types
@@ -13,68 +27,155 @@ export interface SchemaArrayControl {
     /** Реактивная длина. */
     readonly length: number;
     at(index: number): unknown;
-    push(item: unknown): void;
+    push(item?: unknown): void;
     removeAt(index: number): void;
 }
 /**
- * Узел единой схемы M1 — layout-дерево, обходимое `createForm({ model, schema })`
- * и рендерерами (schema-валидация живёт отдельно — `@reformer/core/validation`).
+ * Ручка значения из дерева `model.$`: лист (`model.$.email`) или массив целиком
+ * (`model.$.tags`). Группа ручкой значения не является — у неё нет пути.
  *
- * Узел совмещает несколько ролей (различаются рантаймом по форме):
- *  - **поле** — несёт `value: Signal` (сигнал модели `model.$.x`) + `component`/`validators`;
- *  - **массив** — `{ array: model.<path>, item(itemModel) }`;
- *  - **контейнер/ветка** — вложенные узлы (`children`), опц. условие `when`;
- *  - **record-of-fields** — под-узлы под произвольными именованными ключами (индексная сигнатура).
+ * @group Types
+ */
+export type SchemaValueHandle = Signal<any> & {
+    readonly __path: string;
+};
+/**
+ * Ручка массива из дерева `model.$` (`model.$.phones`) — ручка значения с длиной.
  *
- * Индексная сигнатура (`[key: string]: unknown`) отражает свободный рекурсивный обход: под-узлы
- * допустимы под любым ключом. Известные поля типизированы (даёт автокомплит и проверку их типов).
+ * @group Types
+ */
+export type SchemaArrayHandle = SchemaValueHandle & {
+    readonly length: number;
+};
+/**
+ * Ручка группы из дерева `model.$` (`model.$.address`).
  *
  * @group Types
  */
-export interface FormSchemaNode {
+export interface SchemaGroupHandle {
+    peek(): object | null | undefined;
+    /** Признак «не ручка значения»: у листа и массива путь есть, у группы — нет. */
+    readonly __path?: never;
+}
+/** Ключи, общие для узла любого вида. */
+interface SchemaNodeBase {
     /**
-     * «Ручка» значения поля — маркер узла-поля. Обычно сигнал модели (`model.$.<path>`), но форма
-     * зависит от таргета (для массива `model.$.x` — дерево сигналов; в renderer-типах сужается до
-     * `Signal`). Движок разбирает узел как поле рантаймом по `value instanceof Signal`.
+     * UI-компонент либо нативный HTML-тег (`'div'`, `'p'`, `'h3'`) для презентационной вёрстки
+     * прямо в схеме. Опционален: ядро работает без UI и `component` не интерпретирует — он доезжает
+     * до рендерера как есть.
      */
-    value?: unknown;
+    component?: ComponentRef;
     /**
-     * UI-компонент либо нативный HTML-тег (`'div'`, `'p'`, `'h3'`) для презентационной вёрстки
-     * прямо в схеме. Опционален: core-часть работает без UI (значение/валидация) и `component`
-     * не интерпретирует — он доезжает до рендерера как есть.
+     * Пропсы компонента. Вложенных узлов здесь нет: обход схемы в пропсы не заглядывает, дети узла
+     * пишутся в `children`.
      */
-    component?: ElementType;
-    /** Props компонента. Также «клапан» для вложенности под-узлов (напр. steps визарда). */
     componentProps?: Record<string, unknown>;
-    updateOn?: 'change' | 'blur' | 'submit';
-    disabled?: boolean;
-    /** Задержка (мс) перед запуском асинхронной валидации. */
-    debounce?: number;
-    /** Идентификатор узла (для wizard/tabs/renderBehavior). */
+    /** Идентификатор узла: по нему узел адресуют поведение (`schema.node(...)`) и шаги визарда. */
     selector?: string;
     /**
-     * ⚠️ Рантайм этого поля НЕ ЧИТАЕТ — `renderer-react` берёт testId из `componentProps.testId`
-     * (иначе выводит из пути сигнала). Поле оставлено только потому, что `RenderSchemaNode`
-     * рендерера объявляет свой одноимённый; пишите `componentProps: { testId: '…' }`.
+     * Прежний ключ привязки поля — его нет: пишите `model: model.$.<поле>`.
+     *
+     * Запрет объявлен явно: в `children` узел стоит в объединении с реактивным текстом
+     * (`Signal`, у которого есть `value`), и без него прежний ключ проходил проверку лишних ключей.
      */
-    testId?: string;
+    value?: never;
+    /** Прежний ключ привязки массива — его нет: пишите `model: model.$.<массив>` вместе с `item`. */
+    array?: never;
+}
+/**
+ * Поле: узел, привязанный к ручке значения — листу или массиву целиком (мультивыбор, теги, файлы).
+ *
+ * @example
+ * ```ts
+ * { model: model.$.email, component: Input, componentProps: { label: 'Email' } }
+ * ```
+ *
+ * @group Types
+ */
+export interface SchemaFieldNode extends SchemaNodeBase {
+    /** Привязка поля — ручка значения `model.$.<лист | массив>`. */
+    model: SchemaValueHandle;
     /**
-     * Содержимое узла: под-узлы (даёт контекстную типизацию вложенным литералам — value/validators/when)
-     * и текстовые части. Текст (литерал, число, сигнал модели) — такой же ребёнок, как узел: core его
-     * не интерпретирует (обход пропускает примитивы и не спускается внутрь сигнала), а рендерер
-     * выводит на своём месте в порядке следования.
+     * Поле создаётся отключённым — и остаётся: это постоянная блокировка (вычисляемые `total`,
+     * `fullName`). `enable()` группы, массива или формы её не снимает; снимает только явный
+     * `enable()` самого поля либо оператор `enableWhen` на нём.
      */
-    children?: readonly (FormSchemaNode | string | number | Signal<any>)[];
-    /** Реактивный массив модели (`model.<path>`) — маркер узла-массива (вместе с `item`). */
-    array?: SchemaArrayControl;
-    /** Схема элемента массива: под-модель элемента → узел поддерева. */
-    item?: (itemModel: any) => FormSchemaNode;
+    disabled?: boolean;
+    item?: never;
+    part?: never;
+    children?: never;
+}
+/**
+ * Массив под-форм: у каждой строки своя форма, разметку строки строит `item`.
+ *
+ * @example
+ * ```ts
+ * { model: model.$.phones, component: FieldArray, item: (row) => ({ children: [...] }) }
+ * ```
+ *
+ * @group Types
+ */
+export interface SchemaArrayNode extends SchemaNodeBase {
+    /** Привязка — ручка массива `model.$.<массив>`. */
+    model: SchemaArrayHandle;
+    /** Схема строки: под-модель строки → узел поддерева. */
+    item: (model: any) => FormSchemaNode;
     /**
-     * Значение нового элемента массива для кнопки «Добавить»: либо готовое значение,
-     * либо фабрика `() => value`. Тип не различает варианты (union `unknown | (() => unknown)`
-     * схлопывается в `unknown`) — рантайм различает по `typeof initialValue === 'function'`.
+     * Шаблон нового элемента массива для кнопки «Добавить»: либо готовое значение, либо фабрика
+     * `() => value`. Запасной путь — для форм, чья модель создаётся из данных без кода: шаблон,
+     * объявленный в модели (`arrayOf(blank)`), главнее.
+     *
+     * Тип не различает варианты (union `unknown | (() => unknown)` схлопывается в `unknown`) —
+     * рантайм различает по `typeof initialValue === 'function'`.
      */
     initialValue?: unknown;
-    /** Свободная вложенность: record-of-fields и произвольные под-узлы. */
-    [key: string]: unknown;
+    part?: never;
+    children?: never;
+}
+/**
+ * Подформа: часть схемы, подключённая к группе модели. Часть объявляется один раз и подключается
+ * к любой группе той же формы данных; привязки внутри части идут через `$` полученной под-модели.
+ *
+ * @example
+ * ```ts
+ * { model: model.$.registrationAddress, part: address }
+ * ```
+ *
+ * @group Types
+ */
+export interface SchemaPartNode extends SchemaNodeBase {
+    /** Привязка — ручка группы `model.$.<группа>`. */
+    model: SchemaGroupHandle;
+    /** Часть схемы: под-модель группы → узел поддерева. */
+    part: (model: any) => FormSchemaNode;
+    item?: never;
+    children?: never;
+}
+/** Ребёнок контейнера: вложенный узел либо текстовая часть — литерал, число, сигнал модели. */
+export type SchemaChild = FormSchemaNode | string | number | Signal<any>;
+/**
+ * Контейнер: узел с детьми (секция, шаг визарда, html-тег). Текст — такой же ребёнок, как узел:
+ * ядро его не интерпретирует, а рендерер выводит на своём месте в порядке следования.
+ *
+ * @example
+ * ```ts
+ * { component: Section, componentProps: { title: 'Контакты' }, children: [phoneField, emailField] }
+ * ```
+ *
+ * @group Types
+ */
+export interface SchemaContainerNode extends SchemaNodeBase {
+    children?: readonly SchemaChild[];
+    model?: never;
+    item?: never;
+    part?: never;
 }
+/**
+ * Узел схемы формы: поле, массив под-форм, подформа или контейнер — см. описание модуля.
+ *
+ * Тип закрыт: опечатка в ключе, группа без `part` и `item` не на массиве — ошибки компиляции.
+ *
+ * @group Types
+ */
+export type FormSchemaNode = SchemaFieldNode | SchemaArrayNode | SchemaPartNode | SchemaContainerNode;
+export {};

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

@@ -1,24 +1,32 @@
-import { FormValue, ValidationError } from './index';
-import { FormModel } from '../../state/types';
 /**
- * Чистый синхронный валидатор поля (legacy-сигнатура `(value, scope, root)`).
+ * Типы фабрик валидаторов (`@reformer/core/validators`).
  *
- * @deprecated Осиротевший остаток удалённого дерево-движка (`validateFormModel`). Живой контракт —
- * `Rule<T> = (value) => ValidationError | null` из `@reformer/core/validation`: правила
- * передаются в `validate(sig, [rules])` внутри `defineValidationSchema` и запускаются
- * `validateModel(model, schema)`. Cross-field — оператор `cross(sig, (f) => …)` над снапшотом
- * `model.get()` (третий аргумент `root` больше не нужен). Тип экспортируется только ради
- * обратной совместимости (`SchemaValidator`-union).
+ * Контракт валидации — `@reformer/core/validation`: `defineValidation` + операторы
+ * (`validate`/`validateAsync`/`validateWhen`/`cross`/`apply`/`applyEach`) и раннер
+ * `validateModel(model, definition)`; правила там — `Rule<T> = (value) => issue | null`.
  */
-export type Validator<TForm, TField> = (value: TField, scope: unknown, root: FormModel<TForm>) => ValidationError | null;
 /**
  * Опции валидатора-фабрики (`required()`/`pattern()`/…). Передаются вторым (или последним)
- * аргументом в фабрику и попадают в возвращаемую {@link ValidationError}.
+ * аргументом в фабрику и попадают в возвращаемое {@link ValidationIssue}.
+ *
+ * Текста среди опций нет: правило сообщает только код и параметры, а строку по коду даёт слой
+ * представления (`resolveIssueMessage` из `@reformer/core/i18n`). Нужен свой текст для
+ * конкретного поля — дайте правилу свой код и запись в словаре формы.
+ *
+ * @example
+ * ```ts
+ * // правило
+ * required({ code: 'loanAmount.required' });
+ * // словарь формы (`defineIssueMessages`)
+ * const messages = defineIssueMessages({ 'loanAmount.required': 'Укажите сумму кредита' });
+ * ```
  */
-export interface ValidateOptions {
-    /** Готовое сообщение об ошибке. Если не задано, валидаторы кладут `''`, и отображаемый текст
-     * резолвится из `code` (см. резолвер сообщений в `@reformer/cdk`). */
-    message?: string;
-    /** Параметры ошибки (подстановка в шаблон сообщения / i18n). */
-    params?: Record<string, FormValue>;
+export interface RuleOptions {
+    /**
+     * Свой код вместо встроенного. По нему текст ищется сначала в словаре формы, затем в локали
+     * (`validation.<code>`); принято именовать `<поле>.<правило>`.
+     */
+    code?: string;
+    /** Дополнительные параметры замечания: подставляются в текст поверх параметров правила. */
+    params?: Readonly<Record<string, unknown>>;
 }

package/dist/form/validation/context.d.ts

@@ -0,0 +1,67 @@
+import { FormModel, PathAwareSignal } from '../../model/types';
+import { ValidationIssue } from '../types/contracts';
+import { ValidationFailure } from './types';
+/** Сток одного прогона: модель scope, накопленные ошибки, незавершённые async-правила, гейты. */
+export interface VContext {
+    /**
+     * Модель текущей области — источник снапшота для `cross` и модель для `apply`. В корне прогона
+     * это вся модель; внутри `apply(ручка, схема)` / `applyEach` — под-модель группы или строки.
+     */
+    model: FormModel<unknown>;
+    /**
+     * Накопленные ошибки по сигналу (ключ — идентичность `PathAwareSignal`). Здесь и поля выключенной
+     * ветки `validateWhen` — с пустым списком: при разносе их прежние ошибки гасятся.
+     */
+    issues: Map<PathAwareSignal<unknown>, ValidationIssue[]>;
+    /**
+     * Поля, правила которых в этом прогоне действительно выполнялись — ветка активна. Только их разнос
+     * с `touch` помечает тронутыми: поле выключенной ветки пользователь не видел.
+     */
+    checked: Set<PathAwareSignal<unknown>>;
+    /** Незавершённые async-правила (раннер их дожидается). */
+    pending: Promise<void>[];
+    /** Поля с async-правилами: на время ожидания раннер держит их ноды в `pending`. */
+    asyncFields: Set<PathAwareSignal<unknown>>;
+    /**
+     * Правила, которые не вернули результат. Список — один на весь прогон: области `apply` /
+     * `applyEach` получают поверхностную копию контекста и пишут в ту же ссылку.
+     */
+    failures: ValidationFailure[];
+    /** Стек активных условий `validateWhen` (все должны быть истинны, чтобы правило сработало). */
+    whenStack: Array<() => boolean>;
+    /** Отмена устаревшего прогона: прокидывается в async-правила, гасит роутинг после await. */
+    signal: AbortSignal;
+    /**
+     * Определение, правила которого исполняются сейчас: корень прогона либо схема, подключённая
+     * `apply` / `applyEach`. Замечание помечается им: так разнос отличает замечания одного
+     * определения, полученные разными прогонами (шаг и вся форма), от замечаний чужого.
+     */
+    origin: object;
+    /** Замечания по полю и определению-источнику. Одна ссылка на весь прогон, как `failures`. */
+    origins: Map<PathAwareSignal<unknown>, Map<object, ValidationIssue[]>>;
+    /** Определения, исполненные в прогоне: за их замечания на проверенных полях прогон отвечает. */
+    executed: Set<object>;
+}
+/**
+ * Открыть ambient-окно на время `fn` и закрыть его в `finally`.
+ *
+ * Единственный способ установить контекст: прямое присваивание `current` из другого модуля
+ * невозможно. Сохранение/восстановление `prev` делает вложенный прогон безопасным.
+ */
+export declare function runWithContext<R>(ctx: VContext, fn: () => R): R;
+/** Контекст активного прогона либо понятная ошибка, если оператор вызван вне схемы. */
+export declare function requireCtx(op: string): VContext;
+/**
+ * «Тронуть» сигнал: гарантирует его наличие в замечаниях прогона (даже пустым) → он попадёт в
+ * очистку. Возвращает список текущего определения ({@link VContext.origin}): в него и пишут правила.
+ */
+export declare function touch(ctx: VContext, sig: PathAwareSignal<unknown>): ValidationIssue[];
+/** Исполнить определение: его замечания помечаются им же. */
+export declare function withOrigin(ctx: VContext, origin: object, fn: () => void): void;
+/** Активна ли текущая ветка (все `validateWhen`-условия истинны). */
+export declare const gated: (ctx: VContext) => boolean;
+/**
+ * Правила поля выполняются: ветка активна. Поле запоминается проверенным ({@link VContext.checked}).
+ * Без активной ветки — `false`, и поле остаётся только в `issues` для гашения.
+ */
+export declare function checking(ctx: VContext, sig: PathAwareSignal<unknown>): boolean;

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

@@ -1,28 +1,24 @@
-export { required } from './validators/required';
-export { min } from './validators/min';
-export { max } from './validators/max';
-export { minLength } from './validators/min-length';
-export { maxLength } from './validators/max-length';
-export { email } from './validators/email';
-export { pattern } from './validators/pattern';
-export { url } from './validators/url';
-export { phone, type PhoneFormat } from './validators/phone';
-export { isNumber } from './validators/is-number';
-export { integer } from './validators/integer';
-export { multipleOf } from './validators/multiple-of';
-export { nonNegative } from './validators/non-negative';
-export { nonZero } from './validators/non-zero';
-export { isDate } from './validators/is-date';
-export { minDate } from './validators/min-date';
-export { maxDate } from './validators/max-date';
-export { pastDate } from './validators/past-date';
-export { futureDate } from './validators/future-date';
-export { minAge } from './validators/min-age';
-export { maxAge } from './validators/max-age';
-export { maxFileSize } from './validators/max-file-size';
-export { minFileSize } from './validators/min-file-size';
-export { fileType } from './validators/file-type';
-export { maxFiles } from './validators/max-files';
-export { minFiles } from './validators/min-files';
-export { maxTotalFileSize } from './validators/max-total-file-size';
-export { isFileLike, matchesFileAccept, toFileArray, type FileLike } from './validators/file-utils';
+/**
+ * Декларативный контракт СХЕМЫ ВАЛИДАЦИИ — `@reformer/core/validation`.
+ *
+ * Схема валидации — обычная функция `({ model, cross }) => void`. Внутри вызываются свободные операторы
+ * (`validate`/`validateAsync`/`validateWhen`/`apply`/`applyEach`) и `cross` области, которые САМИ пишут ошибки в
+ * ambient-сток текущего прогона — автор не видит ни коллектора, ни `getNodeForSignal`, ни `.push`.
+ * Раннер открывает ambient-окно на время СИНХРОННОГО прогона схемы и дожидается async-правил
+ * ({@link runValidation} — сбор результата), затем разносит ошибки по нодам формы, гася поля, ставшие
+ * валидными ({@link applyValidationResult}); {@link validateModel} делает оба шага и отвечает `boolean`.
+ *
+ * Зеркалит контракт поведения (`@reformer/core/behaviors`): тот же ambient-стиль, но отдельный слой —
+ * валидация НЕ реактивна (прогон по требованию: submit/шаг), поведение — реактивно (живые подписки).
+ *
+ * Модуль разложен по зонам ответственности: `./types` — контракт правил и схемы, `./context` —
+ * ambient-сток прогона, `./operators` — операторы схемы, `./run` — раннер, `./strategy` — КОГДА
+ * запускать (реэкспортируется отсюда, тот же сабпат).
+ *
+ * @group Validation
+ * @module form/validation
+ */
+export type { Rule, AsyncRule, ValidationDefinition, ValidationScope, ValidationStatus, ValidationFailure, ValidationResult, } from './types';
+export { validate, validateAsync, validateWhen, apply, applyEach } from './operators';
+export { defineValidation, runValidation, applyValidationResult, validateModel } from './run';
+export * from './strategy';