@reformer/core 11.0.0-beta.8 → 11.0.0-beta.9

package/dist/form/signal-node-registry.d.ts

@@ -1,20 +1,19 @@
-import { FormNode } from './nodes/form-node';
+import { FormNode } from './types/nodes';
 /**
  * Связать ручку модели с её нодой формы.
  *
  * Вызывается движком при сборке формы (`createForm`/{@link createFormFromModel}) для каждого поля,
- * группы и массива под-форм. Прикладной код обычно этот реестр не заполняет напрямую.
+ * группы и массива под-форм; у группы в реестре лежит её лицо {@link FormGroup} с нодами полей.
+ * Прикладной код обычно этот реестр не заполняет напрямую.
  *
  * @param signal - Ручка из {@link FormModel}: сигнал листа, узел-массив или узел-группа дерева `model.$`
  * @param node - Нода формы, отвечающая за эту часть модели
  *
- * @example Привязка листовых полей при построении формы
+ * @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);
+ * registerSignalNode(model.$.profile.email, profileForm.email);
  * ```
  *
  * @see {@link getNodeForSignal} - обратный поиск ноды по ручке
@@ -37,7 +36,7 @@ export declare function registerSignalNode(signal: object, node: FormNode<any>):
  * import { getNodeForSignal } from '@reformer/core';
  *
  * const sig = model.$.email;
- * getNodeForSignal(sig)?.setErrors([{ code: 'required', message: 'Обязательно' }]);
+ * getNodeForSignal(sig)?.setIssues([{ code: 'required' }]);
  * ```
  *
  * @example Нода группы и строки массива

package/dist/form/submission.d.ts

@@ -0,0 +1,93 @@
+import { ReadonlySignal } from '@preact/signals-core';
+import { ValidationResult } from './validation/types';
+/**
+ * Итог отправки: `submitted` — обработчик отработал, `invalid` / `error` / `cancelled` —
+ * проверка не пропустила (обработчик не вызывался), `failed` — обработчик бросил исключение.
+ *
+ * `cancelled` — проверку отправки сменила следующая (вторая отправка, живой прогон) либо модель
+ * изменилась, пока проверка шла: правила видели прежние значения, и отправлять новые нельзя.
+ * Замечаний такой итог не несёт — отправку повторяют.
+ *
+ * @group Form
+ */
+export type SubmitResult<TResult> = {
+    readonly status: 'submitted';
+    readonly result: TResult;
+} | {
+    readonly status: 'invalid' | 'error' | 'cancelled';
+    readonly validation: ValidationResult;
+} | {
+    readonly status: 'failed';
+    readonly error: unknown;
+};
+/**
+ * Итог проверки для действия по её результату (отправка, переход шага).
+ *
+ * @group Form
+ */
+export interface ActionCheck<T> {
+    /** Результат проверки. */
+    readonly result: ValidationResult;
+    /** Значения модели после проверки; при `stale === false` — ровно те, что видели правила. */
+    readonly values: T;
+    /** Проверка успешна, но модель с тех пор изменилась: её успех относится к прежним значениям. */
+    readonly stale: boolean;
+}
+/**
+ * Зависимости отправки. Явные, чтобы модуль не тянул ни модель, ни ноды формы.
+ *
+ * @group Form
+ */
+export interface SubmissionDependencies<T> {
+    /**
+     * Проверка перед отправкой — попытка отправки: замечания раскрыты, при необходимости вся форма
+     * тронута. `undefined` — правил нет: обработчик получает {@link SubmissionDependencies.values}.
+     */
+    readonly check: (() => Promise<ActionCheck<T>>) | undefined;
+    /** Значения без проверки. */
+    readonly values: () => T;
+}
+/**
+ * Отправка формы.
+ *
+ * @group Form
+ */
+export interface FormSubmission<T> {
+    /** Идёт ли отправка: работает обработчик. Пока идёт проверка, — `false`. */
+    readonly submitting: ReadonlySignal<boolean>;
+    /**
+     * Отправить: один прогон всех правил; при успехе — обработчик со значениями модели.
+     *
+     * Обработчик получает ровно те значения, которые видели правила. Пока идёт async-правило,
+     * форма не заперта (`submitting` ещё `false`); если модель за это время изменилась — правкой
+     * пользователя, загрузкой, записью поведения после таймера или запроса, — итог `cancelled`,
+     * обработчик не вызывается.
+     *
+     * Значения — модель целиком, с выключенными полями: их правила не считаются, но данные
+     * принадлежат модели. Убрать их из отправки — забота обработчика либо
+     * `enableWhen(…, { resetOnDisable: true })`.
+     *
+     * Исключение обработчика наружу не выходит: итог `failed` с этим исключением.
+     */
+    submit<TResult>(handler: (values: T) => TResult | Promise<TResult>): Promise<SubmitResult<TResult>>;
+}
+/**
+ * Создать отправку формы.
+ *
+ * Обычно её создаёт сборка (`createForm` → `bundle.submission`). Прямой вызов нужен там, где
+ * сборки нет: визард в разметке без `createForm` отправляет значения формы без проверки.
+ *
+ * @typeParam T - Форма данных.
+ * @param dependencies - {@link SubmissionDependencies}: проверка перед действием и значения.
+ * @returns {@link FormSubmission}.
+ *
+ * @example Без проверки — значения формы как есть
+ * ```typescript
+ * const submission = createSubmission<Profile>({ check: undefined, values: () => form.getValue() });
+ * const outcome = await submission.submit(api.save);
+ * if (outcome.status === 'failed') showToast('Не удалось сохранить');
+ * ```
+ *
+ * @group Form
+ */
+export declare function createSubmission<T>(dependencies: SubmissionDependencies<T>): FormSubmission<T>;

package/dist/form/type-guards.d.ts

@@ -1,97 +1,38 @@
-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 { FormValue } from './types/index';
+import { FormArray, FormControl, FormGroup, FormNode } from './types/nodes';
 /**
- * Проверить, является ли значение любым FormNode
- *
- * Проверяет базовые свойства, общие для всех типов узлов
- *
- * @group Utilities
- * @category Type Guards
- *
- * @param value - Значение для проверки
- * @returns true если value является FormNode
- *
- * @example
- * ```typescript
- * if (isFormNode(value)) {
- *   value.setValue(newValue);
- *   value.validate();
- * }
- * ```
- */
-export declare function isFormNode(value: unknown): value is FormNode<FormValue>;
-/**
- * Проверить, является ли значение FieldNode (примитивное поле)
- *
- * FieldNode представляет примитивное поле формы (string, number, boolean и т.д.)
- * и имеет валидаторы, но не имеет вложенных полей или элементов массива
- *
- * @group Utilities
- * @category Type Guards
- *
- * @param value - Значение для проверки
- * @returns true если value является FieldNode
+ * Нода формы любого вида — поле, группа или массив под-форм.
  *
  * @example
  * ```typescript
- * if (isFieldNode(node)) {
- *   node.validators; //  OK
- *   node.asyncValidators; //  OK
- *   node.markAsTouched(); //  OK
- * }
+ * const node = getNodeForSignal(model.$.email);
+ * if (isFormNode(node)) node.markAsTouched();
  * ```
  */
-export declare function isFieldNode(value: unknown): value is FieldNode<FormValue>;
+export declare function isFormNode(value: unknown): value is FormNode<unknown>;
 /**
- * Проверить, является ли значение GroupNode (объект с вложенными полями)
- *
- * GroupNode представляет объект с вложенными полями формы: имеет навигацию по полям
- * (`getFieldByPath`/`fields`) и НЕ имеет array-методов (`items`/`push`/`removeAt`).
- *
- * @param value - Значение для проверки
- * @returns true если value является GroupNode
+ * Поле формы — нода над листом модели с пропсами компонента.
  *
  * @example
  * ```typescript
- * if (isGroupNode(node)) {
- *   node.getFieldByPath('user.email'); //  OK
- * }
+ * if (isFormControl(node)) node.updateComponentProps({ placeholder: 'Email' });
  * ```
  */
-export declare function isGroupNode(value: unknown): value is GroupNode<object>;
+export declare function isFormControl(value: unknown): value is FormControl<unknown>;
 /**
- * Проверить, является ли значение ArrayNode (массив форм)
- *
- * ArrayNode представляет массив вложенных форм (обычно GroupNode)
- * и имеет array-like методы (push, removeAt, at)
- *
- * @param value - Значение для проверки
- * @returns true если value является ArrayNode
+ * Группа полей — её прокси с нодами полей по именам.
  *
  * @example
  * ```typescript
- * if (isArrayNode(node)) {
- *   node.push(); //  OK - добавить элемент
- *   node.removeAt(0); //  OK - удалить элемент
- *   const item = node.at(0); //  OK - получить элемент
- * }
+ * if (isFormGroup(node)) node.markAsTouched();
  * ```
  */
-export declare function isArrayNode(value: unknown): value is ArrayNode<object>;
+export declare function isFormGroup(value: unknown): value is FormGroup<Record<string, unknown>>;
 /**
- * Получить тип узла как строку (для отладки)
- *
- * Полезно для логирования и отладки
- *
- * @param node - Узел для проверки
- * @returns Строковое название типа узла
+ * Массив под-форм.
  *
  * @example
  * ```typescript
- * console.log('Node type:', getNodeType(node)); // "FieldNode" | "GroupNode" | "ArrayNode" | "FormNode" | "Unknown"
+ * if (isFormArray(node)) node.push();
  * ```
  */
-export declare function getNodeType(node: unknown): string;
+export declare function isFormArray(value: unknown): value is FormArray<object>;

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

@@ -1,109 +1,36 @@
 /**
- * Общие контракт-типы значения и валидации.
+ * Контракт замечания валидации.
  *
- * Базовый словарь «значение + ошибка + статус», на который опираются узлы формы
- * (`FormNode.getErrors`, `FieldNode`, `FormStatusMachine`, `aggregate-signals`), слой валидации
- * и платформенные биндинги. Файл не импортирует ничего — это лист графа зависимостей.
+ * Базовый словарь, на который опираются ноды формы, слой валидации и платформенные биндинги.
+ * Файл не импортирует ничего — это лист графа зависимостей.
  *
- * Живёт в `form/types/`, а не в слое модели: `FieldStatus`/`ErrorFilterOptions` — понятия формы,
- * а модель этих типов не использует (и импортировать их оттуда запрещено границей model⇏form).
+ * Живёт в `form/types/`, а не в слое модели: замечание — понятие формы, а модель этих типов
+ * не использует (и импортировать их оттуда запрещено границей model⇏form).
  * Наружу отдаётся через `form/types/index`.
  *
  * @group Types
  * @module form/types/contracts
  */
 /**
- * Represents any valid form value type
- * Use this instead of 'any' for form values to maintain type safety
- *
- * @group Types
- * @category Core Types
- */
-export type FormValue = string | number | boolean | null | undefined | Date | File | FormValue[] | {
-    [key: string]: FormValue;
-};
-/**
- * Синхронная функция валидации
- * @group Types
- * @category Validation Types
- */
-export type ValidatorFn<T = FormValue> = (value: T) => ValidationError | null;
-/**
- * Опции для асинхронного валидатора
- * @group Types
- * @category Validation Types
- */
-export interface AsyncValidatorOptions {
-    /**
-     * AbortSignal для отмены валидации
-     * Позволяет отменить асинхронную операцию при новой валидации
-     */
-    signal?: AbortSignal;
-}
-/**
- * Асинхронная функция валидации
- *
- * @param value - Значение для валидации
- * @param options - Опции валидации (опционально)
- * @returns Promise с ошибкой валидации или null если значение валидно
+ * Замечание валидации: что нарушено (`code`) и с какими числами (`params`). Текста у замечания
+ * нет — отображаемую строку по коду даёт слой представления (`resolveIssueMessage` из
+ * `@reformer/core/i18n`): словарь формы → словарь локали → встроенный английский → сам код.
+ * Поэтому одно и то же замечание показывается на любом языке без повторной проверки.
  *
  * @example
- * ```typescript
- * // Простой валидатор (без поддержки отмены)
- * const emailExists: AsyncValidatorFn<string> = async (value) => {
- *   const exists = await checkEmail(value);
- *   return exists ? { code: 'exists', message: 'Email already exists' } : null;
- * };
- *
- * // Валидатор с поддержкой отмены
- * const emailExistsAbortable: AsyncValidatorFn<string> = async (value, options) => {
- *   const exists = await fetch(`/api/check-email?email=${value}`, {
- *     signal: options?.signal // Передаём signal в fetch для отмены запроса
- *   });
- *   return exists ? { code: 'exists', message: 'Email already exists' } : null;
- * };
+ * ```ts
+ * const tooShort: ValidationIssue = { code: 'minLength', params: { minLength: 8 } };
+ * const softLimit: ValidationIssue = { code: 'loanAmount.high', severity: 'warning' };
  * ```
  *
  * @group Types
  * @category Validation Types
  */
-export type AsyncValidatorFn<T = FormValue> = (value: T, options?: AsyncValidatorOptions) => Promise<ValidationError | null>;
-/**
- * Ошибка валидации
- * @group Types
- * @category Validation Types
- */
-export interface ValidationError {
-    code: string;
-    /**
-     * Готовый текст ошибки. Пустая строка — «автор правила текста не задавал»: отображаемую строку
-     * тогда даёт резолвер по `code` (словарь локали `validation.<code>`).
-     */
-    message: string;
-    /** Ключ сообщения в словаре приложения; при наличии в активной локали важнее `message`. */
-    messageKey?: string;
-    params?: Record<string, FormValue>;
-    /** Severity level: 'error' (default) blocks submission, 'warning' shows message but allows submission */
-    severity?: 'error' | 'warning';
+export interface ValidationIssue {
+    /** Код правила: встроенный (`required`, `minLength`) либо свой (`loanAmount.required`). */
+    readonly code: string;
+    /** Значения для подстановки в текст: порог правила, фактическое значение. */
+    readonly params?: Readonly<Record<string, unknown>>;
+    /** `'error'` (по умолчанию) блокирует отправку, `'warning'` показывается, но не блокирует. */
+    readonly severity?: 'error' | 'warning';
 }
-/**
- * Опции для фильтрации ошибок в методе getErrors()
- * @group Types
- * @category Validation Types
- */
-export interface ErrorFilterOptions {
-    /** Фильтр по коду ошибки */
-    code?: string | string[];
-    /** Фильтр по сообщению (поддерживает частичное совпадение) */
-    message?: string;
-    /** Фильтр по параметрам ошибки */
-    params?: Record<string, FormValue>;
-    /** Кастомный предикат для фильтрации */
-    predicate?: (error: ValidationError) => boolean;
-}
-/**
- * Статус поля формы
- * @group Types
- * @category Core Types
- */
-export type FieldStatus = 'valid' | 'invalid' | 'pending' | 'disabled';

package/dist/form/types/field-config.d.ts

@@ -0,0 +1,27 @@
+import { Signal } from '@preact/signals-core';
+import { ComponentRef } from './schema-node';
+/**
+ * Конфигурация поля формы ({@link FormControl}): сигнал значения из модели и то, что нода берёт
+ * из узла схемы.
+ *
+ * В схеме формы поле записывают узлом `{ model: model.$.field, component, componentProps }`;
+ * сборка `createFormFromModel` превращает узел в этот конфиг сама. Правил валидации в конфиге нет —
+ * они живут в схеме валидации (`defineValidation`, `@reformer/core/validation`).
+ *
+ * @group Types
+ * @category Configuration Types
+ */
+export interface FieldConfig<T> {
+    /**
+     * Сигнал значения из {@link FormModel} — источник истины значения поля. Нода значением не
+     * владеет, а ссылается на этот сигнал.
+     */
+    valueSignal: Signal<T>;
+    /**
+     * UI-компонент поля. Опционален: core-часть можно использовать без ссылки на компонент
+     * (значение и состояние работают без UI; компонент нужен только для рендеринга).
+     */
+    component?: ComponentRef;
+    componentProps?: any;
+    disabled?: boolean;
+}

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 {};