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

package/dist/form/schema-subtree.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Поддерево схемы для под-модели: содержимое строки массива (`item`) или подформы (`part`).
+ *
+ * Билдер поддерева зовут два места — сборка формы и рендерер. Оба обязаны получить ОДНО дерево:
+ * на объектах его узлов держится идентичность (ключи рендера, записи схемы-контроллера), а сам
+ * билдер не обязан быть чистым. Поэтому дерево строится один раз на пару «билдер + под-модель»
+ * и дальше отдаётся из памяти.
+ *
+ * Память привязана к под-модели: исчезла строка массива — исчезли и её поддеревья.
+ *
+ * @group Utilities
+ * @module form/schema-subtree
+ */
+/**
+ * Поддерево схемы для под-модели — результат `builder(subModel)`, один на пару.
+ *
+ * @typeParam N - Тип узла, который возвращает билдер.
+ * @param builder - Билдер поддерева: `item` узла-массива или `part` узла-подформы.
+ * @param subModel - Под-модель строки массива или группы.
+ * @returns Узел поддерева; повторный вызов с той же парой отдаёт тот же объект.
+ *
+ * @example
+ * ```typescript
+ * const row = model.items.at(0);
+ * schemaSubtree(itemSchema, row) === schemaSubtree(itemSchema, row); // true
+ * ```
+ */
+export declare function schemaSubtree<N>(builder: (subModel: any) => N, subModel: object): N;

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

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

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

@@ -6,7 +6,7 @@ import { ValidatorFn, AsyncValidatorFn, AnyFunction } from './index';
  * @group Types
  * @category Configuration Types
  * @remarks
- * В схеме `createForm({ model, schema })` лист связывают через **`value: model.$.field`**: harvest
+ * В схеме `createFormFromModel({ model, schema })` лист связывают через **`value: model.$.field`**: harvest
  * ловит узел по идентичности `Signal` (`node.value instanceof Signal` — см. `create-form.ts`) и
  * нормализует его в `valueSignal`. Писать `valueSignal:` **в самой схеме `createForm` нельзя** —
  * harvest его не подхватит (проверка идёт по `node.value`), и `component`/`componentProps` этого
@@ -68,7 +68,7 @@ type NonEmptyFieldConfig<T> = RequireAtLeastOne<FieldConfig<T>>;
  * Использует NonNullable для корректной обработки опциональных полей.
  *
  * ⚠️ Не путать с {@link FormSchemaNode} — тот описывает **узел дерева** M1-схемы (лист/массив/
- * контейнер), передаваемой в `createForm({ model, schema })`. `FormSchema` — это data-shaped конфиг
+ * контейнер), передаваемой в `createFormFromModel({ model, schema })`. `FormSchema` — это data-shaped конфиг
  * (ключи = поля данных), а не узел дерева.
  *
  * @group Types

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

@@ -53,7 +53,7 @@ export type FormControlsProxy<T> = {
  *   };
  * }
  *
- * const form = createForm<UserForm>(schema);
+ * const form = createLegacyForm<UserForm>(schema);
  *
  * // Доступ к методам GroupNode
  * await form.validate();

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

@@ -13,16 +13,17 @@ 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 })`
+ * Узел единой схемы M1 — layout-дерево, обходимое `createFormFromModel({ model, schema })`
  * и рендерерами (schema-валидация живёт отдельно — `@reformer/core/validation`).
  *
  * Узел совмещает несколько ролей (различаются рантаймом по форме):
- *  - **поле** — несёт `value: Signal` (сигнал модели `model.$.x`) + `component`/`validators`;
- *  - **массив** — `{ array: model.<path>, item(itemModel) }`;
+ *  - **поле** — `{ model: model.$.x, component, componentProps }`;
+ *  - **массив под-форм** — `{ model: model.$.items, item: (model) => узел }`;
+ *  - **подформа** — `{ model: model.$.group, part: (model) => узел }`;
  *  - **контейнер/ветка** — вложенные узлы (`children`), опц. условие `when`;
  *  - **record-of-fields** — под-узлы под произвольными именованными ключами (индексная сигнатура).
  *
@@ -33,9 +34,20 @@ export interface SchemaArrayControl {
  */
 export interface FormSchemaNode {
     /**
-     * «Ручка» значения поля — маркер узла-поля. Обычно сигнал модели (`model.$.<path>`), но форма
-     * зависит от таргета (для массива `model.$.x` — дерево сигналов; в renderer-типах сужается до
-     * `Signal`). Движок разбирает узел как поле рантаймом по `value instanceof Signal`.
+     * Привязка узла к части модели — ручка из дерева `model.$`. Чем узел является, решают ручка и
+     * соседние ключи:
+     *  - лист или массив (`model.$.email`, `model.$.tags`) — **поле**;
+     *  - массив вместе с {@link FormSchemaNode.item} — **массив под-форм**;
+     *  - группа вместе с {@link FormSchemaNode.part} — **подформа**.
+     *
+     * Узел распознаётся по значению, а не по имени ключа: в записи «имя поля → узел» поле данных
+     * может называться `model`, и тогда под этим ключом лежит обычный вложенный узел.
+     */
+    model?: unknown;
+    /**
+     * Прежняя запись привязки поля — то же, что {@link FormSchemaNode.model}.
+     *
+     * @deprecated Пишите `model: model.$.<path>`.
      */
     value?: unknown;
     /**
@@ -65,14 +77,27 @@ export interface FormSchemaNode {
      * выводит на своём месте в порядке следования.
      */
     children?: readonly (FormSchemaNode | string | number | Signal<any>)[];
-    /** Реактивный массив модели (`model.<path>`) — маркер узла-массива (вместе с `item`). */
+    /**
+     * Прежняя запись привязки массива под-форм — фасад `model.<path>` (вместе с `item`).
+     *
+     * @deprecated Пишите `model: model.$.<path>`.
+     */
     array?: SchemaArrayControl;
     /** Схема элемента массива: под-модель элемента → узел поддерева. */
-    item?: (itemModel: any) => FormSchemaNode;
+    item?: (model: any) => FormSchemaNode;
+    /**
+     * Подформа: под-модель группы → узел поддерева. Часть объявляется один раз и подключается к
+     * любой группе той же формы данных: `{ model: model.$.registrationAddress, part: address }`.
+     * Привязки внутри части идут через `$` полученной под-модели.
+     */
+    part?: (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 и произвольные под-узлы. */

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

@@ -1,8 +1,13 @@
 import { FormModel, PathAwareSignal, ValidationError } from '../../index';
 /** Сток одного прогона: модель scope, накопленные ошибки, незавершённые async-правила, гейты. */
 export interface VContext {
-    /** Модель текущего scope — источник снапшота для `cross` и модель для `apply`. */
+    /**
+     * Модель текущей области — источник снапшота для `cross` и модель для `apply`. В корне прогона
+     * это вся модель; внутри `apply(ручка, схема)` / `applyEach` — под-модель группы или строки.
+     */
     model: FormModel<unknown>;
+    /** Корень прогона — модель, с которой вызван раннер. Правило получает его третьим аргументом. */
+    root: FormModel<unknown>;
     /** Накопленные ошибки по сигналу (ключ — идентичность `PathAwareSignal`). */
     errors: Map<PathAwareSignal<unknown>, ValidationError[]>;
     /** Незавершённые async-правила (раннер их дожидается). */

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

@@ -18,6 +18,6 @@
  * @module form/validation
  */
 export type { Rule, AsyncRule, ValidationSchema } from './types';
-export { validate, validateAsync, validateWhen, cross, each, apply } from './operators';
+export { validate, validateAsync, validateWhen, cross, each, apply, applyEach } from './operators';
 export { defineValidationSchema, validateModel } from './run';
 export * from './strategy';

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

@@ -32,16 +32,78 @@ export declare function validateAsync<TField>(sig: PathAwareSignal<TField>, rule
  */
 export declare function validateWhen(cond: () => boolean, cb: () => void): void;
 /**
- * Cross-field правило: `fn` получает СНАПШОТ модели текущего scope (`model.get()`) и вешает ошибку на `sig`.
- * Для элементов массива / под-моделей захватывайте нужный снапшот в замыкание (`const item = im.get()`),
- * т.к. `fn` всегда получает модель ТЕКУЩЕГО scope (корень прогона), а не под-модель.
+ * Cross-field правило: `fn` получает СНАПШОТ модели текущей области (`model.get()`) и вешает
+ * ошибку на `sig`.
+ *
+ * Область — та модель, с которой запущена схема: в корне прогона это вся форма, а в схеме,
+ * подключённой через {@link apply} / {@link applyEach}, — под-модель группы или строки массива.
+ * Поэтому правила подформы пишутся один раз и не знают, где она стоит.
  */
 export declare function cross<TSnapshot>(sig: PathAwareSignal<unknown>, fn: (form: TSnapshot) => ValidationError | null): void;
+/** Привязка к группе: ручка `model.$.<группа>` (тип значения — из её `peek()`). */
+interface GroupBinding<V> {
+    peek(): V;
+}
+/** Привязка к массиву под-форм: ручка `model.$.<массив>`. */
+interface ArrayBinding<U> {
+    peek(): readonly U[] | null | undefined;
+}
+/**
+ * Применить схему к КАЖДОМУ элементу массива под-форм. Схема элемента — обычная
+ * `ValidationSchema` над типом элемента: тот же набор правил подключается и к группе через
+ * {@link apply}.
+ *
+ * У каждого элемента своя область: `cross` внутри схемы получает снапшот элемента.
+ *
+ * @example
+ * ```ts
+ * const propertyRules = defineValidationSchema<Property>(({ model }) => {
+ *   validate(model.$.type, [required()]);
+ *   cross<Property>(model.$.estimatedValue, (property) =>
+ *     property.hasEncumbrance && property.estimatedValue < 100_000 ? tooCheap : null
+ *   );
+ * });
+ *
+ * applyEach(model.$.properties, propertyRules);
+ * ```
+ */
+export declare function applyEach<U extends object>(array: ArrayBinding<U> | ModelArray<U>, schema: ValidationSchema<U>): void;
+/**
+ * Применить под-правила к КАЖДОМУ элементу массива — прежняя запись {@link applyEach}.
+ *
+ * Колбэк получает под-модель элемента, но области не создаёт: `cross` внутри него видит снапшот
+ * корня прогона.
+ *
+ * @deprecated Пишите `applyEach(model.$.<массив>, schema)`.
+ */
+export declare function each<U extends object>(arr: ArrayBinding<U> | ModelArray<U>, itemFn: (item: FormModel<U>) => void): void;
 /**
- * Применить под-правила к КАЖДОМУ элементу текущего массива модели.
- * `U extends object` — элементы должны быть под-моделями (объектами); массив примитивов — одно
- * значение поля, его проверяют целиком: `validate(model.$.<массив>, [...])`.
+ * Подключить схему подформы к группе модели — одной или нескольким.
+ *
+ * Схема запускается в области группы: `model` в ней — под-модель, `cross` получает снапшот
+ * группы. Привязка — ручка `model.$.<группа>`, как у узла-подформы схемы и у `apply` поведения.
+ *
+ * @example
+ * ```ts
+ * const addressRules = defineValidationSchema<Address>(({ model }) => {
+ *   validate(model.$.city, [required()]);
+ * });
+ *
+ * apply(model.$.registrationAddress, addressRules);
+ * validateWhen(
+ *   () => !model.sameAsRegistration,
+ *   () => apply(model.$.residenceAddress, addressRules)
+ * );
+ * ```
+ */
+export declare function apply<V extends object | null | undefined>(group: GroupBinding<V> | GroupBinding<V>[], schema: ValidationSchema<NonNullable<V>>): void;
+/**
+ * Композиция схем над ТОЙ ЖЕ моделью области — так форма собирается из схем шагов.
+ *
+ * @example
+ * ```ts
+ * const formRules = defineValidationSchema<Form>(() => apply(loanRules, contactsRules));
+ * ```
  */
-export declare function each<U extends object>(arr: ModelArray<U>, itemFn: (item: FormModel<U>) => void): void;
-/** Композиция под-схем в текущую (над той же моделью scope). Заменяет пошаговую группировку. */
 export declare function apply<T>(...schemas: ValidationSchema<T>[]): void;
+export {};

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

@@ -12,7 +12,8 @@ export type CallableRule = (value: unknown, model: unknown, root: unknown) => Va
  * (`required()`/`min()`/… — они `(value, model, root) => …`) и inline-правила `(value) => …`
  * ОБА присваиваются в `Rule<TField>[]` без `any`, при этом сохраняется проверка типа поля
  * (`validate(model.$.age, [email()])` подсветится — `email` ждёт `string`, поле `number`).
- * На вызове раннер приводит правило к callable и передаёт `(value, model, model)`.
+ * На вызове раннер приводит правило к callable и передаёт `(value, scope, root)`: модель текущей
+ * области (в корне прогона — вся модель) и корень прогона.
  */
 export type Rule<TField> = (value: TField, scope: never, root: never) => ValidationError | null;
 /**