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

package/docs/llms/21-array-operations.md

@@ -1,7 +1,8 @@
 ## 18. ARRAY OPERATIONS
 
-Массивы объектов — model-owned. Мутации делаются через `ModelArray` (`model.arrayField`);
-рендер — через ноду формы (`form.items.map` / `.at`).
+Массивы объектов — model-owned. Мутации делаются через `ModelArray` (`model.arrayField`) либо через
+ноду формы `FormArray` (`form.items`) — она данными не владеет и передаёт мутацию в массив модели;
+рендер — через ноду формы (`form.items.map` / `.at` / `.keyAt`).
 
 ### Array Access
 
@@ -13,51 +14,73 @@ model.items.length;             // реактивная длина
 model.items.toArray();          // снимок значений
 
 // Через ноду формы (рендер / доступ к нодам полей)
-form.items.at(0);               // FormProxy<Item> | undefined
-form.items.map((item, i) => …); // item — FormProxy<Item>
+form.items.at(0);               // FormGroup<Item> | undefined
+form.items.map((item, i) => …); // item — FormGroup<Item>
+form.items.length;              // число строк (число, не сигнал; в эффекте подписывает)
+form.items.keyAt(0);            // стабильный ключ строки — не меняется при move/swap
 ```
 
-### Array Methods (на модели)
+### Array Methods
 
 ```typescript
+// на модели
 model.items.push({ name: '', price: 0 });        // добавить в конец (ПЛОСКИЕ значения!)
-model.items.insertAt(0, { name: '', price: 0 }); // вставить по индексу
-model.items.removeAt(index);                     // удалить по индексу
-model.items.move(fromIndex, toIndex);            // переместить
+model.items.push();                              // по шаблону arrayOf(blank)
+model.items.insertAt(0, { name: '', price: 0 }); // вставить по индексу 0…length; за концом — RangeError
+model.items.removeAt(index);                     // удалить по индексу; нет такого — ничего
+model.items.move(fromIndex, toIndex);            // переместить; индекс за концом — RangeError
 model.items.swap(a, b);                          // поменять местами
 model.items.clear();                             // очистить
+
+// на ноде формы — те же мутации (вставка называется insert)
+form.items.push();
+form.items.insert(0, { name: '', price: 0 });
+form.items.removeAt(index);
+form.items.move(fromIndex, toIndex);
+form.items.swap(a, b);
+form.items.clear();
 ```
 
+Формы строк держатся за под-модели элементов: после `move` / `swap` строка остаётся той же нодой
+со своими `touched` и замечаниями.
+
+Разница между путями — в `dirty`. Мутация через ноду, которая поменяла состав строк (в том числе
+перестановка), делает массив и форму изменёнными (`form.items.dirty`), снимает это `reset`. Запись в
+модель — нет, как и у поля: загрузка данных форму не «пачкает». Кнопки добавления и удаления в
+интерфейсе — через ноду.
+
 > **push принимает ПЛОСКИЕ значения** (`{ name, price }`), а НЕ FieldConfig-шаблон
-> (`{ value, component }`). Component/componentProps берутся из `item`-фабрики схемы.
+> (`{ value, component }`). У массива с шаблоном `arrayOf` переданный объект накладывается на
+> шаблон: недостающие ключи берутся из него (так `add({ type })` из cdk даёт полный элемент). Component/componentProps берутся из `item`-фабрики схемы.
 > Передача FieldConfig-объектов сломает рендер (`[object Object]` в инпутах).
 
 ### Rendering Arrays
 
 ```tsx
-import { useArrayLength } from '@reformer/core';
+import { useArrayLength } from '@reformer/core/react';
 
-function ItemsList({ form }: { form: FormProxy<MyForm> }) {
+function ItemsList({ form }: { form: FormGroup<MyForm> }) {
   const length = useArrayLength(form.items);
 
   return (
     <div>
       {form.items.map((item, index) => (
-        <div key={index}>
+        <div key={form.items.keyAt(index)}>
           <FormField control={item.name} />
           <FormField control={item.price} />
-          <button onClick={() => model.items.removeAt(index)}>Remove</button>
+          <button onClick={() => form.items.removeAt(index)}>Remove</button>
         </div>
       ))}
       {length === 0 && <p>No items yet</p>}
-      <button onClick={() => model.items.push({ name: '', price: 0 })}>Add Item</button>
+      <button onClick={() => form.items.push({ name: '', price: 0 })}>Add Item</button>
     </div>
   );
 }
 ```
 
-> В монорепо используется `FormArraySection` из `@reformer/ui-kit`: `control={form.items}`,
-> `itemComponent`, `initialValue`, add/remove/reorder из коробки. См. `find_recipe(topic="form-array")`.
+> В монорепо используется `FieldArraySection` из `@reformer/ui-kit`: `control={form.items}`,
+> `itemComponent`, add/remove/reorder из коробки; шаблон новой строки — `arrayOf(blank)` в модели.
+> См. `find_recipe(topic="field-array")`.
 
 ### Per-item behavior — applyEach
 
@@ -76,6 +99,32 @@ const behavior = defineFormBehavior<MyForm>(({ model }) => {
 });
 ```
 
+### Вложенные области — массив в группе и в строке массива
+
+Узел `{ model: model.$.<массив>, item }` и операторы `applyEach` / `apply` / `enableWhen` работают на любой глубине:
+цель оператора — **ручка** `model.$.…`, под-модель и нода находятся по её идентичности, а не по
+пути.
+
+```typescript
+const phoneBehavior = defineFormBehavior<Phone>(({ model: phone }) => {
+  enableWhen(phone.$.number, () => phone.primary);
+});
+
+const contactBehavior = defineFormBehavior<Contact>(({ model: contact }) => {
+  applyEach(contact.$.phones, phoneBehavior); // массив внутри строки
+  enableWhen(contact.$.address, () => contact.quantity > 0); // группа внутри строки
+  apply(contact.$.address, addressBehavior); // под-схема получает настоящую под-модель
+});
+
+const behavior = defineFormBehavior<MyForm>(({ model }) => {
+  applyEach(model.$.contacts, contactBehavior);
+});
+```
+
+Ручка → value-фасад: `modelOf(model.$.address)` — под-модель (`get` / `set` / `patch`),
+`modelOf(model.$.phones)` — фасад массива (`push` / `removeAt` / `at`). Нода формы по ручке —
+`getNodeForSignal(model.$.address)`.
+
 ### Aggregate write — aggregateInto
 
 Агрегатная запись в строки (например, «последняя строка = 100 − Σ остальных»):
@@ -93,21 +142,22 @@ aggregateInto(model.$.rows, (rows) => {
 
 ### Array Cross-Validation
 
-Whole-array правило — оператор `cross(sig, (f) => ...)` из `@reformer/core/validation`:
-`f` — снапшот `model.get()`, ошибка вешается на скалярное поле-носитель `sig`. Per-item
-правила — `each(model.<array>, (im) => ...)`.
+Правило над всем массивом — оператор `cross(sig, check)` из аргумента схемы валидации: `check`
+получает снимок модели, ошибка вешается на скалярное поле-носитель `sig`. Правила строк —
+`applyEach(model.$.<массив>, схема строки)`.
 
 ```typescript
-import { cross } from '@reformer/core/validation';
-import type { ValidationError } from '@reformer/core';
+import { defineValidation } from '@reformer/core/validation';
+import type { ValidationIssue } from '@reformer/core';
 
-const percentagesSumTo100 = (f: MyForm): ValidationError | null => {
-  const total = f.items.reduce((sum, i) => sum + (i.percentage || 0), 0);
+const percentagesSumTo100 = (form: MyForm): ValidationIssue | null => {
+  const total = form.items.reduce((sum, item) => sum + (item.percentage || 0), 0);
   return Math.abs(total - 100) > 0.01
-    ? { code: 'invalid_total', message: 'Percentages must sum to 100%' }
+    ? { code: 'items.percentTotal', params: { total } } // текст кода — в словаре формы
     : null;
 };
 
-// внутри defineValidationSchema<MyForm>(({ model }) => { ... })
-cross(model.$.totalPercent, percentagesSumTo100); // носитель — скалярное поле формы
+const itemsRules = defineValidation<MyForm>(({ model, cross }) => {
+  cross(model.$.totalPercent, percentagesSumTo100); // носитель — скалярное поле формы
+});
 ```

package/docs/llms/22-cycle-detection.md

@@ -1,6 +1,6 @@
 # Cycle Detection — предотвращение «Cycle detected»
 
-## Как устроено под M1
+## Как устроено
 
 Behaviors на сигналах уже защищены от типичных циклов:
 

package/docs/llms/23-copy-from.md

@@ -9,7 +9,7 @@
 
 ## API
 
-Есть две формы. **Примитив из `@reformer/core`** (сигнал → сигнал):
+Есть две формы. **Примитив из `@reformer/core/model`** (сигнал → сигнал):
 
 ```typescript
 function copyFrom<T>(
@@ -92,7 +92,7 @@ export const contactBehavior = defineFormBehavior<ContactForm>(({ model }) => {
 ### Как примитив (вне defineFormBehavior)
 
 ```typescript
-import { copyFrom } from '@reformer/core';
+import { copyFrom } from '@reformer/core/model';
 
 const cleanups = [
   copyFrom(model.$.email, model.$.emailAdditional, { when: () => model.sameEmail === true }),

package/docs/llms/24-sync-fields.md

@@ -10,17 +10,18 @@
 
 ## API
 
-Одинаково в примитиве (`@reformer/core`) и DSL (`@reformer/core/behaviors`):
+Одинаково в примитиве (`@reformer/core/model`) и DSL (`@reformer/core/behaviors`):
 
 ```typescript
 // примитив: возвращает cleanup
-function syncFields<T>(a: Signal<T>, b: Signal<T>, options?: { transform?: (value: T) => T }): () => void;
+function syncFields<T>(a: Signal<T>, b: Signal<NoInfer<T>>, options?: { transform?: (value: T) => T }): () => void;
 
 // DSL: cleanup управляется формой
-function syncFields<T>(a: Signal<T>, b: Signal<T>, options?: { transform?: (value: T) => T }): void;
+function syncFields<T>(a: Signal<T>, b: Signal<NoInfer<T>>, options?: { transform?: (value: T) => T }): void;
 ```
 
-`a`/`b` — сигналы (`model.$.field`) совместимого типа `T`. `transform` **асимметричен**:
+`a`/`b` — сигналы (`model.$.field`) совместимого типа `T`. Тип пары задаёт `a`: поле `number | null`
+вторым аргументом к `number` не компилируется — синхронизация писала бы `null` в `number`. `transform` **асимметричен**:
 применяется только при движении значения `a → b`. Опции `debounce`/`when` нет.
 
 ## Examples
@@ -57,7 +58,7 @@ export const codeBehavior = defineFormBehavior<DisplayForm>(({ model }) => {
 ### Как примитив (вне defineFormBehavior)
 
 ```typescript
-import { syncFields } from '@reformer/core';
+import { syncFields } from '@reformer/core/model';
 const stop = syncFields(model.$.syncField1, model.$.syncField2);
 // stop() — отписаться
 ```

package/docs/llms/25-reset-when.md

@@ -5,22 +5,29 @@
 `resetWhen` сбрасывает значение поля к `resetValue`, когда `condition` истинно. Это
 альтернатива `enableWhen({ resetOnDisable: true })`, когда поле остаётся **enabled**, но
 содержимое нужно очистить (например, переключение способа оплаты обнуляет «номер карты», но
-поле по-прежнему доступно). По умолчанию пишет `null`; `resetValue` задаёт произвольное значение.
+поле по-прежнему доступно). По умолчанию пишет `null`; `resetValue` задаёт произвольное значение
+и **обязателен по типу**, если `null` не входит в тип поля.
 
 ## API
 
-Одинаково в примитиве (`@reformer/core`) и DSL (`@reformer/core/behaviors`):
+Одинаково в примитиве (`@reformer/core/model`) и DSL (`@reformer/core/behaviors`):
 
 ```typescript
+// опции: поле с null — необязательны; поле без null — resetValue обязателен
+type ResetWhenOptionsArg<T> = null extends T
+  ? [options?: { resetValue?: NoInfer<T> }]
+  : [options: { resetValue: NoInfer<T> }];
+
 // примитив: возвращает cleanup
-function resetWhen<T>(target: Signal<T>, condition: () => boolean, options?: { resetValue?: T }): () => void;
+function resetWhen<T>(target: Signal<T>, condition: () => boolean, ...options: ResetWhenOptionsArg<T>): () => void;
 
 // DSL: cleanup управляется формой
-function resetWhen<T>(target: Signal<T>, condition: () => boolean, options?: { resetValue?: T }): void;
+function resetWhen<T>(target: Signal<T>, condition: () => boolean, ...options: ResetWhenOptionsArg<T>): void;
 ```
 
 `target` — сигнал (`model.$.field`). `condition` — реактивное условие (читает `model.*`).
-`resetValue` по умолчанию `null`. Опций `onlyIfDirty`/`debounce` нет; флаги dirty/touched
+`resetValue` по умолчанию `null` — поэтому полю без `null` в типе (`string`, `number`) его нужно
+задать явно, иначе код не компилируется. Опций `onlyIfDirty`/`debounce` нет; флаги dirty/touched
 поля не трогаются оператором (значения принадлежат модели).
 
 ## Examples
@@ -55,7 +62,7 @@ export const mortgageBehavior = defineFormBehavior<MortgageForm>(({ model }) =>
 ### Как примитив (вне defineFormBehavior)
 
 ```typescript
-import { resetWhen } from '@reformer/core';
+import { resetWhen } from '@reformer/core/model';
 const stop = resetWhen(model.$.cardNumber, () => model.paymentType !== 'card', { resetValue: '' });
 ```
 
@@ -79,7 +86,7 @@ resetWhen(model.$.amount, () => model.skipPayment, { resetValue: 0 });
 ```
 
 ```typescript
-// ❌ Для строкового поля без resetValue прилетит null, а Input ждёт string
+// ❌ Для строкового поля без resetValue прилетел бы null, а Input ждёт string — не компилируется
 resetWhen(model.$.cardNumber, () => model.paymentType !== 'card');
 
 // ✅ Явный resetValue для строк

package/docs/llms/26-transform-value.md

@@ -11,7 +11,7 @@
 
 ## API
 
-Одинаково в примитиве (`@reformer/core`) и DSL (`@reformer/core/behaviors`):
+Одинаково в примитиве (`@reformer/core/model`) и DSL (`@reformer/core/behaviors`):
 
 ```typescript
 // примитив: возвращает cleanup
@@ -22,7 +22,7 @@ function transformValue<T>(target: Signal<T>, transformer: (value: T) => T): voi
 ```
 
 `target` — сигнал (`model.$.field`). `transformer` — чистая идемпотентная функция значения.
-Дополнительных опций (`debounce`, `onUserChangeOnly`, `emitEvent`) и готового набора
+Дополнительных опций (`debounce`, `onUserChangeOnly`) и готового набора
 `transformers`/`createTransformer` НЕТ — трансформер пишется как обычная функция.
 
 ## Examples
@@ -70,7 +70,7 @@ export const contactBehavior = defineFormBehavior<ContactForm>(({ model }) => {
 ### Как примитив (вне defineFormBehavior)
 
 ```typescript
-import { transformValue } from '@reformer/core';
+import { transformValue } from '@reformer/core/model';
 const stop = transformValue(model.$.promoCode, (v) => (v ?? '').toUpperCase());
 ```
 
@@ -122,7 +122,7 @@ A: 99% — неидемпотентный transformer. Проверь `transform
 
 **Q: Трансформация не применяется.**
 A: Проверь, что behavior зарегистрирован (`createForm({ behavior })`) / примитив не отписан,
-и что форма не пересоздаётся на каждый рендер (используй `useMemo`).
+и что форма не пересоздаётся на каждый рендер (сборка — через `useFormBundle(() => createForm(…))`).
 
 **Q: Каретка input прыгает при наборе.**
 A: Симптом частых записей. Форматирование с динамическими разделителями (телефон, кредитка)

package/docs/llms/27-revalidate-when.md

@@ -11,7 +11,7 @@
 
 ## API
 
-`revalidateWhen` — оператор поведения (`@reformer/core/behaviors`, либо примитив `@reformer/core`).
+`revalidateWhen` — оператор поведения (`@reformer/core/behaviors`, либо примитив `@reformer/core/model`).
 Его сигнатура НЕ зависит от контракта валидации:
 
 ```typescript
@@ -23,7 +23,7 @@ function revalidateWhen(deps: ReadonlySignal<unknown>[], revalidate: () => void)
 ```
 
 `deps` — массив сигналов-триггеров (`model.$.field`). `revalidate` — колбэк (обычно
-`() => void validateModel(model, schema)`, где `schema` — `defineValidationSchema<T>(({ model }) => …)`).
+`() => void validateModel(model, schema)`, где `schema` — `defineValidation<T>(({ model }) => …)`).
 Вызывается при изменении любой зависимости (НЕ на инициализации), вне effect-контекста.
 
 ## Examples
@@ -43,7 +43,8 @@ export const paymentBehavior = defineFormBehavior<PaymentForm>(({ model }) => {
 
 Пример: `revalidateWhen([model.$.maxAmount], () => void validateModel(model, paymentSchema))`.
 Схема `paymentSchema` — стабильный module-level `const` (важно для отмены устаревших прогонов
-в `validateModel`), где правило amount навешано через `cross(model.$.amount, amountVsMax)`.
+в `validateModel`), где правило amount навешано оператором `cross` области схемы:
+`cross(model.$.amount, amountVsMax)`.
 
 ### Несколько триггеров
 
@@ -66,7 +67,7 @@ import { defineFormBehavior, revalidateWhen } from '@reformer/core/behaviors';
 import { validateModel } from '@reformer/core/validation';
 
 // правило совпадения — cross-field в схеме: cross(model.$.confirmPassword, passwordsMatch),
-// где passwordsMatch читает снапшот формы (см. 03-api-signatures.md)
+// где passwordsMatch получает снимок формы (см. 03-api-signatures.md)
 export const registrationBehavior = defineFormBehavior<RegistrationForm>(({ model }) => {
   // при смене password перевалидируем схему (confirm перепроверится)
   revalidateWhen([model.$.password], () => {
@@ -78,7 +79,7 @@ export const registrationBehavior = defineFormBehavior<RegistrationForm>(({ mode
 ### Как примитив (вне defineFormBehavior)
 
 ```typescript
-import { revalidateWhen } from '@reformer/core';
+import { revalidateWhen } from '@reformer/core/model';
 import { validateModel } from '@reformer/core/validation';
 
 const stop = revalidateWhen([model.$.maxAmount], () => void validateModel(model, schema));
@@ -100,13 +101,13 @@ revalidateWhen([model.$.maxAmount, model.$.discount], () => validateModel(model,
 revalidateWhen([model.$.maxAmount], () => validateModel(model, schema));
 // а валидатор amount — статичный max(1000), не читает maxAmount
 
-// ✅ Сначала cross-field правило (читает снапшот формы) в схеме валидации, потом revalidateWhen
-const amountVsMax = (f: Form): ValidationError | null =>
-  f.amount != null && f.maxAmount != null && f.amount > f.maxAmount
-    ? { code: 'tooBig', message: '...' }
+// ✅ Сначала cross-field правило (получает снимок формы) в схеме валидации, потом revalidateWhen
+const amountVsMax = (form: Form): ValidationIssue | null =>
+  form.amount != null && form.maxAmount != null && form.amount > form.maxAmount
+    ? { code: 'tooBig' }
     : null;
 
-const schema = defineValidationSchema<Form>(({ model }) => {
+const schema = defineValidation<Form>(({ model, cross }) => {
   cross(model.$.amount, amountVsMax); // навешиваем правило на поле amount
 });
 revalidateWhen([model.$.maxAmount], () => void validateModel(model, schema));
@@ -115,18 +116,18 @@ revalidateWhen([model.$.maxAmount], () => void validateModel(model, schema));
 ## Troubleshooting
 
 **Q: Ошибка target не пропадает после изменения триггера.**
-A: Проверьте, что (1) правило реально читает значение триггера — cross-field `cross(sig, fn)`,
-где `fn` берёт снапшот формы (`model.get()` / `f`); (2) в `deps` передан именно сигнал (`model.$.trigger`);
-(3) колбэк вызывает `validateModel` (роутит ошибки в ноды через `getNodeForSignal(sig).setErrors`).
+A: Проверьте, что (1) правило реально читает значение триггера — cross-field `cross(sig, check)`,
+где `check` получает снимок формы; (2) в `deps` передан именно сигнал (`model.$.trigger`);
+(3) колбэк вызывает `validateModel` (он разносит ошибки по нодам формы).
 
 **Q: Как перевалидировать только одно поле, а не всю схему?**
 A: Схема — обычная функция, поэтому опиши стабильную под-схему только для этого поля и прогони её:
 `validateModel(model, oneFieldSchema)`, где
-`const oneFieldSchema = defineValidationSchema<Form>(({ model }) => cross(model.$.amount, amountVsMax))`.
+`const oneFieldSchema = defineValidation<Form>(({ model, cross }) => cross(model.$.amount, amountVsMax))`.
 Раннер выставит/погасит ошибки только затронутых полей (гашение накапливается на пару `(model, schema)`).
 
 ## See also
 
-- [03-api-signatures.md](./03-api-signatures.md) — cross-field `cross(sig, fn)` и раннер `validateModel`
+- [03-api-signatures.md](./03-api-signatures.md) — cross-field `cross` области схемы и раннер `validateModel`
 - [28-submit-and-reset.md](./28-submit-and-reset.md) — полная валидация формы
 - [20-compute-vs-watch.md](./20-compute-vs-watch.md) — реактивные производные значения