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

package/dist/model/model-signals-proxy.d.ts

@@ -1,6 +1,6 @@
 import { Signal } from '@preact/signals-core';
 import { PathAwareSignal } from './types';
-import { ModelNode, GroupNode, ArrayNode } from './model-nodes';
+import { ModelNode, ModelGroupNode, ModelArrayNode } from './model-nodes';
 /**
  * Узел дерева `$`: лист → сам {@link PathAwareSignal}, группа/массив → контейнерный узел —
  * {@link ReadonlySignal} агрегированного значения ПЛЮС доступ к детям по имени/индексу.
@@ -26,7 +26,7 @@ export declare function signalsProxy(node: ModelNode): any;
  *
  * @internal
  */
-export declare function containerNodeOf(handle: unknown): GroupNode | ArrayNode | undefined;
+export declare function containerNodeOf(handle: unknown): ModelGroupNode | ModelArrayNode | undefined;
 /**
  * Узел дерева `model.$` — контейнер (группа/массив), а не лист?
  *
@@ -44,12 +44,11 @@ export declare function isModelContainerSignal(value: unknown): boolean;
 /** Узел-массив дерева `model.$` — ручка значения массива целиком. */
 export declare function isModelArraySignal(value: unknown): boolean;
 /**
- * «Ручка значения», к которой можно привязать поле: лист (`instanceof Signal`) либо узел-массив
+ * «Ручка значения», к которой можно привязать поле: лист (сигнал, не контейнер) либо узел-массив
  * дерева `model.$` (значение — массив целиком, `.value` читается и пишется).
  *
  * Группа сюда не входит: она читается целиком, но не пишется и полем не бывает. Этой проверкой
- * `createForm` и рендереры отличают узел-поле схемы (`{ value, component }`) от контейнера —
- * вместо голого `value instanceof Signal`, который узел-массив не проходит.
+ * `createForm` и рендереры отличают узел-поле схемы (`{ model, component }`) от контейнера.
  *
  * @group Model
  * @example
@@ -61,4 +60,4 @@ export declare function isModelArraySignal(value: unknown): boolean;
  * ```
  */
 export declare function isValueSignal(value: unknown): value is Signal<unknown>;
-export declare function resolveSignalAt(root: GroupNode, path: string): PathAwareSignal<unknown> | undefined;
+export declare function resolveSignalAt(root: ModelGroupNode, path: string): PathAwareSignal<unknown> | undefined;

package/dist/model/model-value-proxy.d.ts

@@ -1,7 +1,7 @@
-import { GroupNode } from './model-nodes';
+import { ModelGroupNode } from './model-nodes';
 import { FormModel, ModelArray } from './types';
-export declare const rootByFacade: WeakMap<object, GroupNode>;
-export declare function makeFormModel(group: GroupNode): any;
+export declare const rootByFacade: WeakMap<object, ModelGroupNode>;
+export declare function makeFormModel(group: ModelGroupNode): any;
 /**
  * Value-фасад для ручки {@link modelOf}: массив → {@link ModelArray}, объект → под-модель
  * {@link FormModel}.
@@ -39,13 +39,6 @@ export type ModelOf<V> = NonNullable<V> extends ReadonlyArray<infer U> ? ModelAr
 export declare function modelOf<V extends object | null | undefined>(handle: {
     peek(): V;
 }): ModelOf<V>;
-/**
- * Ручка `$` по value-фасаду: под-модель → её `model.$`, фасад массива → узел-массив дерева `$`.
- * Для всего остального — `undefined`.
- *
- * @internal
- */
-export declare function signalsOf(facade: unknown): object | undefined;
 /**
  * Ручка массива по привязке: сама ручка `model.$.<массив>` либо value-фасад `model.<массив>`.
  * Для всего остального — `undefined`.
@@ -61,9 +54,10 @@ export declare function arrayHandleOf(binding: unknown): object | undefined;
  */
 export declare function groupHandleOf(binding: unknown): object | undefined;
 /**
- * Запасной шаблон нового элемента массива — `initialValue` узла-массива схемы. Действует, только
- * если модель своего шаблона не объявила (`arrayOf`): так живут формы, чья модель строится из
- * данных без кода.
+ * Запасной шаблон нового элемента массива — от того, кто строит модель извне: сборка формы
+ * передаёт сюда `initialValue` узла-массива. Действует, только если модель своего шаблона не
+ * объявила (`arrayOf`): так живут формы, чья модель строится из данных без кода. Что это узел
+ * схемы, модель не знает.
  *
  * @internal
  */
@@ -71,9 +65,20 @@ export declare function provideArrayBlank(handle: unknown, initialValue: unknown
 /**
  * Value-фасад модели (под-модель или фасад массива), а не обычный объект?
  *
- * Обходчикам чужих деревьев (схема формы) в фасад спускаться нельзя: чтение его ключей — это
- * реактивное чтение значений модели.
+ * Обходчикам чужих деревьев, в которых могут лежать фасады модели, в фасад спускаться нельзя:
+ * чтение его ключей — это реактивное чтение значений модели.
  *
  * @internal
  */
+/**
+ * Точка отсчёта модели по ручке, к которой привязана нода формы: сигналу листа или фасаду
+ * массива. К ней сброс формы (`form.reset()`) возвращает ноду — к тому же, к чему `model.reset()`
+ * возвращает модель: последний `captureInitial` либо значение создания модели.
+ *
+ * `undefined` — ручка не из модели (нода над собственным сигналом): сбрасывать её не к чему,
+ * кроме значения, с которым она создана. @internal
+ */
+export declare function referenceOf(handle: unknown): {
+    readonly value: unknown;
+} | undefined;
 export declare function isModelFacade(value: unknown): boolean;

package/dist/model/safe-effect.d.ts

@@ -68,6 +68,38 @@ export declare function safeCallback<TArgs extends unknown[]>(callback: (...args
  * ```
  */
 export declare function runOutsideEffect(fn: () => void | Promise<void>): () => void;
+/**
+ * Дождаться, пока отработают отложенные записи текущего тика — вместе с теми, что они породили
+ * (цепочка расчётов: каждая запись будит следующий расчёт, а тот снова пишет отложенно).
+ *
+ * Ждёт только микротаски: запись после таймера (debounce) или после `await` в async-callback сюда не
+ * входит — это уже не «тот же тик».
+ *
+ * Счётчик общий для рантайма, а не для одной модели: отложенные записи ставит {@link runOutsideEffect},
+ * а он моделей не различает. Нужен проверкам «по действию» — отправке и переходу шага: правила должны
+ * увидеть модель после записей поведения того же тика (колбэк `onChange`, сброс `resetOnDisable`).
+ *
+ * @returns Промис ожидания; `undefined` — отложенных записей сейчас нет, ждать нечего.
+ *
+ * @example
+ * ```typescript
+ * model.loanType = 'mortgage'; // поведение допишет зависимые поля на микротаске
+ * await deferredWritesSettled();
+ * const values = model.get(); // уже с записями поведения
+ * ```
+ */
+export declare function deferredWritesSettled(): Promise<void> | undefined;
+/**
+ * Отложенные записи одной операции: задание выполняется на микротаске ({@link runOutsideEffect}),
+ * а `cancelAll` отменяет все ещё не выполненные — при снятии операции (запись после cleanup не
+ * случится) или когда новое задание делает ожидающие устаревшими (побеждает последнее).
+ *
+ * @internal
+ */
+export declare function deferredWrites(): {
+    schedule(job: () => void): void;
+    cancelAll(): void;
+};
 /**
  * Создает версию callback с поддержкой debounce, безопасную для effect
  *
@@ -76,7 +108,7 @@ export declare function runOutsideEffect(fn: () => void | Promise<void>): () =>
  * async-rejection) маршрутизируются dev-логгером (logDeferError).
  *
  * @param callback - Функция для выполнения
- * @param withDebounce - Функция debounce обёртки из BehaviorRegistry
+ * @param withDebounce - Обёртка, откладывающая вызов (debounce)
  * @returns Обёрнутая функция
  *
  * @example

package/dist/model/types.d.ts

@@ -14,6 +14,33 @@ export type PathAwareSignal<T> = Signal<T> & {
  * @internal
  */
 type Opaque = Date | File | Blob;
+/**
+ * Значение одного ключа в {@link DeepPartial}: вложенная группа — частично, массив и спец-объект
+ * (Date/File/Blob) — целиком.
+ * @internal
+ */
+type DeepPartialValue<V> = NonNullable<V> extends ReadonlyArray<unknown> | Opaque ? V : NonNullable<V> extends object ? DeepPartial<NonNullable<V>> | Extract<V, null | undefined> : V;
+/**
+ * Частичное значение модели для {@link ModelApi.patch}: любой ключ можно опустить на любой
+ * глубине вложенных групп. Массив передаётся целиком — он заменяется, а не сливается.
+ *
+ * @example
+ * ```typescript
+ * type Profile = { name: string; address: { city: string; street: string }; tags: string[] };
+ * const update: DeepPartial<Profile> = { address: { city: 'Казань' } };
+ * ```
+ *
+ * @group Model
+ */
+export type DeepPartial<T> = {
+    [K in keyof T]?: DeepPartialValue<T[K]>;
+};
+/**
+ * `null` входит в тип `V`. Без `strictNullChecks` у потребителя `null` подходит любому типу —
+ * тогда признак ложен, и тип контейнера остаётся фасадом, как без `null`.
+ * @internal
+ */
+type IncludesNull<V> = null extends string ? false : null extends V ? true : false;
 /**
  * Фасад элемента массива при обходе (`at`/`map`/`forEach`): массив → {@link ModelArray},
  * Opaque (Date/File/Blob) и примитив → значение, объект → под-модель {@link FormModel}.
@@ -21,7 +48,7 @@ type Opaque = Date | File | Blob;
  * чтобы `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;
+type ModelArrayItem<U> = IncludesNull<U> extends true ? 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}
@@ -29,10 +56,13 @@ type ModelArrayItem<U> = NonNullable<U> extends ReadonlyArray<infer E> ? ModelAr
  * - объект → под-модель {@link FormModel} (value-доступ + `.$`-сигналы + API get/set/patch/…);
  *   промоутится рантаймом (`makeFormModel`); сигналы идентичны `model.$.<path>`
  * - примитив → значение
+ * - тип с `null` (`File[] | null`, `Address | null`) → значение как есть, без фасада: поле,
+ *   которое бывает `null`, начинают с `null`, а такое поле в рантайме — лист (значение целиком).
+ *   Контейнер, созданный из `[]` или `{}`, стал бы фасадом — nullable-контейнер начинают с `null`.
  *
  * @group Model
  */
-export type ModelValue<V> = NonNullable<V> extends ReadonlyArray<infer U> ? ModelArray<U> : NonNullable<V> extends Opaque ? V : NonNullable<V> extends object ? FormModel<NonNullable<V>> : V;
+export type ModelValue<V> = IncludesNull<V> extends true ? V : NonNullable<V> extends ReadonlyArray<infer U> ? ModelArray<U> : NonNullable<V> extends Opaque ? V : NonNullable<V> extends object ? FormModel<NonNullable<V>> : V;
 /**
  * Карта value-полей объекта (value-половина {@link FormModel}): поля доступны как обычные свойства
  * (чтение реактивно внутри `effect`/`computed`, запись — присваиванием). Вложенные объекты-поля
@@ -80,6 +110,8 @@ export interface ModelArray<U> {
     forEach(fn: (item: ModelArrayItem<U>, index: number) => void): void;
     /** Снимок массива значений (без подписки). */
     toArray(): U[];
+    /** Обход `for…of` / spread — те же элементы, что у {@link forEach}. */
+    [Symbol.iterator](): IterableIterator<ModelArrayItem<U>>;
     /** Индексный value-доступ. */
     [index: number]: ModelValue<U>;
 }
@@ -115,13 +147,13 @@ export type ModelGroupSignals<T> = ModelSignals<T> & ContainerSignal<T, keyof T>
  * push/removeAt/move).
  *
  * В отличие от группы, узел ЗАПИСЫВАЕМ: `model.$.tags.value = ['a']` заменяет массив целиком. Это
- * делает его {@link PathAwareSignal} — к нему привязывают поле (`{ value: model.$.tags, component }`),
+ * делает его {@link PathAwareSignal} — к нему привязывают поле (`{ model: model.$.tags, component }`),
  * правило (`validate(model.$.tags, …)`) и поведение, как к листу. Так массив служит ОДНИМ значением
  * поля: мультивыбор, теги, список файлов.
  *
- * `V` — объявленный тип поля, включая `null`/`undefined`: поле `string[] | null` с начальным `null`
- * в рантайме — лист с тем же `.value`/`peek`/`subscribe`, поэтому общая часть честна для обоих
- * случаев. `length` и индексы есть только у настоящего узла-массива (начальное значение — массив).
+ * `V` — объявленный тип поля, включая `undefined`. Поле с `null` в типе (`string[] | null`) — не
+ * узел-массив, а лист {@link PathAwareSignal}: его начинают с `null`, и `length` с индексами у него
+ * в рантайме нет (см. {@link ModelValue}).
  *
  * @group Model
  */
@@ -135,10 +167,11 @@ export type ModelArraySignals<U, V> = Signal<V> & {
  * Узел дерева сигналов `model.$`: массив → {@link ModelArraySignals}, Opaque (Date/File/Blob)
  * и примитив → {@link PathAwareSignal}, объект → {@link ModelGroupSignals}. Для примитивных
  * и Opaque массивов элемент — сам сигнал листа (а не под-дерево), поэтому `model.$.tags[0]` — это
- * `PathAwareSignal<string>`, а не `ModelGroupSignals<never>`.
+ * `PathAwareSignal<string>`, а не `ModelGroupSignals<never>`. Тип с `null` — лист
+ * {@link PathAwareSignal}: такое поле начинают с `null`, и под-сигналов у него нет.
  * @internal
  */
-type ModelSignalNode<V> = NonNullable<V> extends ReadonlyArray<infer U> ? ModelArraySignals<U, V> : NonNullable<V> extends Opaque ? PathAwareSignal<V> : NonNullable<V> extends object ? ModelGroupSignals<NonNullable<V>> : PathAwareSignal<V>;
+type ModelSignalNode<V> = IncludesNull<V> extends true ? PathAwareSignal<V> : NonNullable<V> extends ReadonlyArray<infer U> ? ModelArraySignals<U, V> : NonNullable<V> extends Opaque ? PathAwareSignal<V> : NonNullable<V> extends object ? ModelGroupSignals<NonNullable<V>> : PathAwareSignal<V>;
 /**
  * API уровня модели (доступно на корне, под-моделях вложенных объектов-групп и элементов массива).
  *
@@ -159,18 +192,35 @@ export interface ModelApi<T> {
      * Полная установка значений: принимает объект целиком (все ключи `T`) и записывает их в модель.
      * Производными полями (цели `compute`) владеет compute — их значения из payload игнорируются.
      * Не меняет initial-снимок. Для частичного обновления (только переданные ключи) — {@link ModelApi.patch}.
+     *
+     * Если в объекте не хватает ключей (значение пришло без типа — например, с сервера), эти поля
+     * остаются прежними, а в dev выводится предупреждение со списком.
      */
     set(value: T): void;
     /**
      * Частичное слияние значений (load/patch с сервера): обновляет только переданные ключи,
-     * отсутствующие ключи НЕ трогаются. Не меняет initial-снимок.
+     * отсутствующие ключи НЕ трогаются. Вложенные группы сливаются так же, массив заменяется
+     * целиком. Не меняет initial-снимок.
+     */
+    patch(value: DeepPartial<T>): void;
+    /**
+     * Отличаются ли текущие значения от initial-снимка (value-diff). Производные поля — цели
+     * `compute` / `computeFrom` и поля с `markDerived` — не в счёт: их пишет поведение, а не
+     * пользователь, и форма без единой правки изменённой не считается.
      */
-    patch(value: Partial<T>): void;
-    /** Отличаются ли текущие значения от initial-снимка (value-diff). */
     isDirty(): boolean;
-    /** Сбросить значения к initial-снимку. */
+    /**
+     * Сбросить значения к initial-снимку. Производные поля сброс не пишет, как `set` и `patch`:
+     * цель `compute` пересчитает поведение, когда вернутся её источники.
+     *
+     * Ноды формы не трогает: замечания погаснут при следующей проверке. Сброс для пользователя —
+     * `form.reset()`: та же точка отсчёта и чистые ноды.
+     */
     reset(): void;
-    /** Зафиксировать текущие значения как новый initial-снимок («точка отсчёта»). */
+    /**
+     * Зафиксировать текущие значения как новый initial-снимок («точка отсчёта»). К нему возвращают
+     * и `model.reset()`, и `form.reset()`.
+     */
     captureInitial(): void;
     /**
      * Резолв строкового пути в сигнал (для error-routing/мостов): лист либо массив целиком

package/dist/model.js

@@ -1,25 +1,27 @@
-import { c as s, e as r, a as l } from "./create-model-BBRHhHwK.js";
-import { a as o, d as c, i as d, b as n, c as t, m as f, u as m } from "./model-value-proxy-caTmAiUd.js";
-import { c as b, a as h, r as p, b as g, d as k, e as v, f as D, s as F, t as S, w as x } from "./behaviors-value-C7dSEhCc.js";
+import { c as s, e as r, a as l } from "./create-model-BvcbNPgL.js";
+import { a as d, g as o, f as t, d as c, i as f, b as n, c as m, m as u, r as p, s as b, e as g, u as h } from "./safe-effect-BbtX3KuN.js";
+import { c as k, a as v, r as D, b as F, s as x, t as y, w as C } from "./behaviors-value-HA_Q03hc.js";
 export {
-  o as arrayOf,
-  b as computeFrom,
-  h as copyFrom,
+  d as arrayOf,
+  k as computeFrom,
+  v as copyFrom,
   s as createModel,
+  o as deepEqual,
+  t as deferredWritesSettled,
   r as eachLeafSignal,
   l as eachValueSignal,
   c as isDerived,
-  d as isModelContainerSignal,
+  f as isModelContainerSignal,
   n as isValueSignal,
-  t as markDerived,
-  f as modelOf,
-  p as resetWhen,
-  g as revalidateWhen,
-  k as runOutsideEffect,
-  v as safeCallback,
-  D as safeDebouncedCallback,
-  F as syncFields,
-  S as transformValue,
-  m as unmarkDerived,
-  x as watchField
+  m as markDerived,
+  u as modelOf,
+  D as resetWhen,
+  F as revalidateWhen,
+  p as runOutsideEffect,
+  b as safeCallback,
+  g as safeDebouncedCallback,
+  x as syncFields,
+  y as transformValue,
+  h as unmarkDerived,
+  C as watchField
 };

package/dist/node-kind-C-r6ZMdo.js

@@ -0,0 +1,15 @@
+const n = Symbol.for("@reformer/core/form-node-kind"), e = Symbol.for("@reformer/core/form-node-raw");
+function t(r) {
+  if (typeof r != "object" || r === null) return;
+  const o = r[n];
+  return o === "control" || o === "group" || o === "array" ? o : void 0;
+}
+function f(r) {
+  return r[e] ?? r;
+}
+export {
+  n as N,
+  e as R,
+  t as k,
+  f as r
+};

package/dist/platforms/react/field-binding/field-adapter.d.ts

@@ -41,7 +41,7 @@ export interface FieldAdapter {
     strip?: string[];
     /**
      * Передавать ли контролу ноду формы пропом `control` (только рендерер). По умолчанию `false`:
-     * errors/touched обслуживает обёртка поля. Ставь `true`, если контрол сам вызывает
+     * issues/touched обслуживает обёртка поля. Ставь `true`, если контрол сам вызывает
      * `useFormControl(control)`.
      */
     passControl?: boolean;

package/dist/platforms/react/field-binding/field-handle.d.ts

@@ -43,8 +43,11 @@ export declare function makeElementFieldHandle(el: RefObject<HTMLElement | null>
 export declare function useFieldHandleRef<H = FieldHandle>(outerRef: Ref<H> | undefined): RefObject<unknown>;
 /**
  * Что публиковать потребителю по ref контрола: handle композита как есть, иначе (DOM-узел или
- * ещё пусто) — базовый {@link FieldHandle}, читающий узел лениво из `inner`.
+ * ещё пусто) — базовый {@link FieldHandle}, читающий узел лениво из `inner`. С `cache` базовый
+ * handle создаётся один раз и дальше переиспользуется.
  *
  * @internal Экспортируется для юнит-тестов.
  */
-export declare function resolveFieldHandle(inner: RefObject<unknown>): unknown;
+export declare function resolveFieldHandle(inner: RefObject<unknown>, cache?: {
+    current: FieldHandle | null;
+}): unknown;

package/dist/platforms/react/form-bundle-context.d.ts

@@ -12,7 +12,7 @@ import { FormBundle } from '../../form/form-bundle';
 export declare const FormBundleContext: import('react').Context<FormBundle<any> | null>;
 /**
  * Бандл сборки, внутри которой отрисован компонент; `null` — компонент стоит вне рендерера
- * (например, визард в разметке React-руками получает форму и валидацию пропсами).
+ * (например, визард в разметке React-руками получает форму и поток шагов пропсами).
  *
  * @typeParam T - Форма данных модели.
  *
@@ -20,7 +20,7 @@ export declare const FormBundleContext: import('react').Context<FormBundle<any>
  * ```tsx
  * function StepFooter() {
  *   const bundle = useFormBundleContext<CreditForm>();
- *   return <button onClick={() => bundle?.validation?.validateAll()}>Проверить</button>;
+ *   return <button onClick={() => void bundle?.validate()}>Проверить</button>;
  * }
  * ```
  */

package/dist/platforms/react/hooks/types.d.ts

@@ -1,6 +1,6 @@
-import { ValidationError } from '../../../form/types/index';
+import { ValidationIssue } from '../../../form/types/index';
 /**
- * Состояние поля формы, возвращаемое хуком {@link useFormControl} для {@link FieldNode}.
+ * Состояние поля формы, возвращаемое хуком {@link useFormControl} для {@link FormControl}.
  *
  * Содержит реактивные данные поля: значение, состояние валидации, флаги взаимодействия
  * и пользовательские props для компонентов.
@@ -10,12 +10,12 @@ import { ValidationError } from '../../../form/types/index';
  * @example Базовое использование
  * ```tsx
  * interface Props {
- *   control: FieldNode<string>;
+ *   control: FormControl<string>;
  * }
  *
  * function TextField({ control }: Props) {
  *   const state = useFormControl(control);
- *   const message = useValidationMessage(); // из '@reformer/core/i18n'
+ *   const message = useIssueMessage(); // из '@reformer/core/react'
  *
  *   return (
  *     <div>
@@ -24,8 +24,8 @@ import { ValidationError } from '../../../form/types/index';
  *         disabled={state.disabled}
  *         onChange={e => control.setValue(e.target.value)}
  *       />
- *       {state.shouldShowError && state.errors[0] && (
- *         <span className="error">{message(state.errors[0])}</span>
+ *       {state.shouldShowIssues && state.issues[0] && (
+ *         <span className="error">{message(state.issues[0])}</span>
  *       )}
  *     </div>
  *   );
@@ -89,22 +89,22 @@ export interface FieldControlState<T> {
      *
      * @example
      * ```tsx
-     * const { errors } = useFormControl(field);
-     * const message = useValidationMessage(); // из '@reformer/core/i18n'
+     * const { issues } = useFormControl(field);
+     * const message = useIssueMessage(); // из '@reformer/core/react'
      *
      * return (
      *   <ul className="error-list">
-     *     {errors.map((error, i) => (
+     *     {issues.map((error, i) => (
      *       <li key={i}>{message(error)}</li>
      *     ))}
      *   </ul>
      * );
      * ```
      */
-    errors: ValidationError[];
+    issues: ValidationIssue[];
     /**
      * Флаг валидности поля.
-     * `true` когда поле прошло все валидации (errors.length === 0).
+     * `true` когда поле прошло все валидации (issues.length === 0).
      *
      * @example
      * ```tsx
@@ -118,7 +118,7 @@ export interface FieldControlState<T> {
     valid: boolean;
     /**
      * Флаг невалидности поля.
-     * `true` когда есть ошибки валидации (errors.length > 0).
+     * `true` когда есть ошибки валидации (issues.length > 0).
      * Противоположность {@link valid}.
      *
      * @example
@@ -148,28 +148,44 @@ export interface FieldControlState<T> {
      */
     touched: boolean;
     /**
-     * Флаг для отображения ошибки.
-     * Комбинация touched && invalid - удобный shortcut для UI.
+     * Показывать ли состояние ошибки — `aria-invalid`, рамку: поле невалидно и его трогали или
+     * меняли. Предупреждение (`severity: 'warning'`) поле невалидным не делает, поэтому для текстов
+     * замечаний есть {@link FieldControlState.shouldShowIssues}.
      *
      * @example
      * ```tsx
-     * const { shouldShowError, errors } = useFormControl(field);
-     * const message = useValidationMessage(); // из '@reformer/core/i18n'
+     * const { shouldShowError } = useFormControl(field);
+     *
+     * return <input {...props} aria-invalid={shouldShowError} />;
+     * ```
+     */
+    shouldShowError: boolean;
+    /**
+     * Показывать ли тексты замечаний: у поля есть замечания — ошибки или предупреждения, — и его
+     * трогали или меняли.
+     *
+     * @example
+     * ```tsx
+     * const { shouldShowError, shouldShowIssues, issues } = useFormControl(field);
+     * const message = useIssueMessage(); // из '@reformer/core/react'
      *
      * return (
      *   <div>
-     *     <input {...props} />
-     *     {shouldShowError && (
-     *       <span className="error">{message(errors[0])}</span>
-     *     )}
+     *     <input {...props} aria-invalid={shouldShowError} />
+     *     {shouldShowIssues &&
+     *       issues.map((issue) => (
+     *         <span key={issue.code} className={issue.severity === 'warning' ? 'warning' : 'error'}>
+     *           {message(issue)}
+     *         </span>
+     *       ))}
      *   </div>
      * );
      * ```
      */
-    shouldShowError: boolean;
+    shouldShowIssues: boolean;
     /**
      * Пользовательские props для передачи в UI-компоненты.
-     * Устанавливаются через {@link FieldNode.updateComponentProps}.
+     * Устанавливаются через {@link FormControl.updateComponentProps}.
      *
      * @example
      * ```tsx
@@ -210,7 +226,7 @@ export interface FieldControlState<T> {
     dirty: boolean;
 }
 /**
- * Состояние массива формы, возвращаемое хуком {@link useFormControl} для {@link ArrayNode}.
+ * Состояние массива формы, возвращаемое хуком {@link useFormControl} для {@link FormArray}.
  *
  * Содержит реактивные данные массива: значения элементов, длину, состояние валидации
  * и флаги взаимодействия.
@@ -225,7 +241,7 @@ export interface FieldControlState<T> {
  * }
  *
  * interface Props {
- *   control: ArrayNode<Phone>;
+ *   control: FormArray<Phone>;
  * }
  *
  * function PhoneList({ control }: Props) {
@@ -235,7 +251,7 @@ export interface FieldControlState<T> {
  *     <div>
  *       {control.map((item, index) => (
  *         <PhoneItem
- *           key={item.id}
+ *           key={control.keyAt(index)}
  *           control={item}
  *           onRemove={() => control.removeAt(index)}
  *         />
@@ -247,7 +263,7 @@ export interface FieldControlState<T> {
  *         Add Phone
  *       </button>
  *
- *       {!valid && <p className="error">Please fix phone errors</p>}
+ *       {!valid && <p className="error">Please fix phone issues</p>}
  *     </div>
  *   );
  * }
@@ -293,23 +309,24 @@ export interface ArrayControlState<T> {
      */
     pending: boolean;
     /**
-     * Массив ошибок валидации уровня массива.
-     * Не включает ошибки отдельных элементов.
+     * Замечания массива: собственные (правила на ручке массива) и замечания всех его строк.
      *
      * @example
      * ```tsx
-     * // Валидатор массива
-     * validators.apply(phonesArray, {
-     *   validator: (phones) => phones.length >= 1,
-     *   message: 'At least one phone required'
-     * });
+     * // Правило массива — в схеме валидации
+     * validate(model.$.phones, [minLength(1, { code: 'phones.minLength' })]);
      *
      * // В компоненте
-     * const { errors } = useFormControl(phonesArray);
-     * // errors содержит ошибку "At least one phone required" если массив пуст
+     * const { issues } = useFormControl(phonesArray);
+     * // для пустого массива issues содержит замечание с кодом 'phones.minLength'
      * ```
      */
-    errors: ValidationError[];
+    issues: ValidationIssue[];
+    /**
+     * Собственные замечания массива — только правила на его ручке (`minLength` и т.п.), без
+     * замечаний строк. Их показывает ошибка уровня массива (`FieldArray.Error`).
+     */
+    ownIssues: ValidationIssue[];
     /**
      * Флаг валидности массива и всех его элементов.
      * `true` только когда массив и все вложенные элементы валидны.
@@ -327,7 +344,9 @@ export interface ArrayControlState<T> {
     touched: boolean;
     /**
      * Флаг изменения.
-     * `true` когда значение массива отличается от начального.
+     * `true` после правки любого элемента или изменения состава через форму (`push`, `removeAt`,
+     * `move`, `setValue`…). Как у поля, запись в модель (загрузка данных) и операция, которая состав
+     * не поменяла, изменением не считаются; снимает `reset`.
      *
      * @example
      * ```tsx
@@ -344,7 +363,7 @@ export interface ArrayControlState<T> {
     dirty: boolean;
     /**
      * Флаг отключения массива.
-     * `true` когда массив отключён (`ArrayNode.disable()`), в том числе через
+     * `true` когда массив отключён (`FormArray.disable()`), в том числе через
      * распространение disable от родительской группы.
      *
      * Используйте для отключения UI-действий добавления/удаления, когда массив