@reformer/core 10.2.0 → 11.0.0-beta.10

package/docs/llms/09-formschema.md

@@ -0,0 +1,191 @@
+## 8. SCHEMA FORMAT (CRITICALLY IMPORTANT)
+
+Схема — **дерево узлов**. Узел привязан к части модели ключом `model` и держит UI-конфиг
+(`component` / `componentProps`). Значения принадлежат модели. Правил валидации в схеме НЕТ — они
+живут в отдельной схеме `defineValidation` из `@reformer/core/validation`.
+
+### Четыре вида узла
+
+Тип узла — `FormSchemaNode`, закрытый union. Вид определяют ключи `model`, `item`, `part` и
+`children`:
+
+| Вид             | Ключи                             | Пример                                              |
+| --------------- | --------------------------------- | --------------------------------------------------- |
+| поле            | `model` — лист или массив целиком | `{ model: model.$.email, component: Input }`        |
+| массив под-форм | `model` — массив + `item`         | `{ model: model.$.phones, item: phoneRow }`         |
+| подформа        | `model` — группа + `part`         | `{ model: model.$.address, part: address }`         |
+| контейнер       | `children`                        | `{ component: Section, children: [/* узлы */] }`    |
+
+Общие ключи любого узла: `component`, `componentProps`, `selector`. У поля ещё `disabled`, у
+массива под-форм — `initialValue` (запасной шаблон новой строки).
+
+```typescript
+// Поле
+{
+  model: model.$.fieldName,   // ручка значения из model.$ — обязательна
+  component: Input,           // React-компонент
+  componentProps?: object,    // пропсы (label, placeholder, options, type, ...)
+  disabled?: boolean,         // постоянная блокировка поля (вычисляемые total, fullName)
+  selector?: string,          // имя узла для поведения: schema.node('…')
+}
+```
+
+> **Вложенные узлы читаются только из `children` и из поддерева `part`.** В `componentProps` и под
+> произвольными ключами сборка не заглядывает: узел, положенный туда, полем не станет. В dev
+> сборка предупреждает о ключах узла, которые она не читает.
+
+> **Тип закрыт — ошибки ловит компилятор:** опечатка в ключе (`componnet`), группа без `part`,
+> `item` не на массиве, привязка value-фасадом (`model: model.email` вместо `model.$.email`) и
+> узлы под произвольными ключами (`{ email: { model, component } }`) не компилируются.
+
+> `disabled` — **ключ узла**, постоянная блокировка: `enable()` группы, массива или формы её не
+> снимает (цикл «выключить форму на время отправки → включить» вычисляемые поля не разблокирует).
+> Снимают её явный `form.field.enable()` и оператор `enableWhen` на этом поле. `componentProps.disabled` — это
+> UI-проп и на состояние поля **не влияет** (частая причина «computed-поле остаётся редактируемым»).
+
+### Primitive Fields
+
+```typescript
+import { createModel, createFormFromModel, type FormSchemaNode } from '@reformer/core';
+import { defineValidation, validate } from '@reformer/core/validation';
+import { required } from '@reformer/core/validators';
+import { Input, InputNumber, SelectAsync, CheckboxWithLabel } from '@reformer/ui-kit';
+
+const model = createModel<MyForm>({ name: '', age: null, agree: false, status: 'active' });
+
+// Валидация — отдельным слоем (запуск: await validateModel(model, myValidation))
+const myValidation = defineValidation<MyForm>(({ model }) => {
+  validate(model.$.name, [required()]);
+});
+
+const schema: FormSchemaNode = {
+  children: [
+    {
+      model: model.$.name,
+      component: Input,
+      componentProps: { label: 'Name', placeholder: 'Enter name' },
+    },
+    {
+      model: model.$.age,
+      component: InputNumber,
+      componentProps: { label: 'Age' },
+    },
+    {
+      model: model.$.agree,
+      component: CheckboxWithLabel,
+      componentProps: { label: 'I agree to terms' },
+    },
+    {
+      model: model.$.status,
+      component: SelectAsync,
+      componentProps: {
+        label: 'Status',
+        options: [
+          { value: 'active', label: 'Active' },
+          { value: 'inactive', label: 'Inactive' },
+        ],
+      },
+    },
+  ],
+};
+
+const form = createFormFromModel<MyForm>({ model, schema });
+```
+
+Поле данных может называться как угодно — `value`, `schema`, `form`, `model`, `children`: вид ноды
+определяет узел модели, а не имя.
+
+### Nested Objects — подформа `{ model, part }`
+
+Вложенная группа модели — под-модель `FormModel<Sub>`. Её разметку объявляют один раз функцией от
+под-модели и подключают к группе узлом-подформой. Привязки внутри части идут через `$` полученной
+под-модели:
+
+```typescript
+import type { FormModel, FormSchemaNode } from '@reformer/core';
+
+const address = (model: FormModel<Address>): FormSchemaNode => ({
+  children: [
+    { model: model.$.street, component: Input, componentProps: { label: 'Street' } },
+    { model: model.$.city, component: Input, componentProps: { label: 'City' } },
+    { model: model.$.zip, component: Input, componentProps: { label: 'ZIP' } },
+  ],
+});
+
+const schema: FormSchemaNode = {
+  children: [
+    // Одна часть подключается к любой группе той же формы данных — сколько угодно раз.
+    { model: model.$.registrationAddress, part: address },
+    { model: model.$.residenceAddress, part: address },
+  ],
+};
+```
+
+Поля группы можно привязать и напрямую, без подформы:
+`{ model: model.$.address.city, component: Input }`.
+
+### Arrays — массив под-форм `{ model, item }`
+
+`item` строит разметку строки из под-модели строки (`FormModel<Item>`):
+
+```typescript
+import type { FormModel, FormSchemaNode } from '@reformer/core';
+
+const itemRow = (item: FormModel<Item>): FormSchemaNode => ({
+  children: [
+    { model: item.$.id, component: Input, componentProps: { label: 'ID' } },
+    { model: item.$.name, component: Input, componentProps: { label: 'Name' } },
+  ],
+});
+
+const schema: FormSchemaNode = {
+  children: [{ model: model.$.items, component: FieldArray, item: itemRow }],
+};
+```
+
+Массив **без** `item` и с `component` — одно значение поля (мультивыбор, теги, список файлов):
+`{ model: model.$.tags, component: SelectMulti }`.
+
+### createForm API
+
+```typescript
+// Сборка одним вызовом: модель, форма, уровень формы и дерево для рендера
+const bundle = createForm<MyForm>({
+  initial,                 // либо готовая модель: model
+  schema: (model) => tree, // билдер дерева: узлы держат ручки модели
+  behavior: myBehavior,    // опционально: defineFormBehavior(...) из @reformer/core/behaviors
+  validation: myRules,     // опционально: схема либо { rules?, extras?, strategy? }
+  flow: { steps: [{ id: 'loan', rules: loanRules }] }, // опционально: шаги, id = selector шага
+});
+bundle.render.tree; // CompiledSchema — то же дерево после компиляции
+
+// Низкоуровневая фабрика: готовые модель и дерево
+const form = createFormFromModel<MyForm>({ model, schema, behavior: myBehavior });
+
+// Доступ к нодам
+form.name.setValue('John');
+form.address.city.value.value; // текущее значение (через сигнал)
+model.items.push({ id: '1', name: 'Item' }); // операции над массивом — на модели (или form.items.push)
+```
+
+Сборка компилирует дерево один раз (`compileSchema`): у каждого узла — вид (`field | array | part |
+container | text`), идентификатор (`selector` либо позиционный путь `#/0/2`) и область (`#`,
+`#/address`, `#/phones[<ключ>]`). Повтор `selector` в одной области (корень, строка массива,
+подформа) — исключение с путями обоих узлов. В dev правило поведения на узел, которого нет в
+дереве, и шаг `flow.steps`, для которого нет узла с таким `selector`, дают предупреждение в
+консоли. Подробно — [37-compiled-schema.md](./37-compiled-schema.md).
+
+### Ноды формы — типы и гарды
+
+```typescript
+const form = createFormFromModel<MyForm>({ model, schema });
+
+form.email;          // FormControl<string> — TypeScript знает тип
+form.address.city;   // FormControl<string> — вложенный доступ (form.address — FormGroup)
+form.items.at(0);    // FormGroup<ItemType> | undefined — форма строки массива
+form.$.value;        // поле с именем члена ноды (value, issues, reset, …) — через `$`
+
+// FormControl / FormGroup / FormArray — интерфейсы, instanceof не работает. Вид ноды — гардами:
+import { isFormControl, isFormGroup, isFormArray } from '@reformer/core';
+if (isFormControl(node)) { /* ... */ }
+```

package/docs/llms/10-arrays.md

@@ -0,0 +1,241 @@
+## 9. ARRAY SCHEMA FORMAT
+
+Массивы объектов — **model-owned**: данные принадлежат модели (`model.arrayField` — это
+`ModelArray<Item>` с реактивными `push`/`removeAt`/`length`). В схеме массив объявляется узлом
+`{ model: model.$.<path>, item: (itemModel) => узел }`, где `item` строит разметку одной строки
+из её под-модели (`FormModel<Item>`).
+
+```typescript
+import {
+  arrayOf,
+  createModel,
+  createFormFromModel,
+  type FormModel,
+  type FormSchemaNode,
+} from '@reformer/core';
+import { FieldArray, Input, InputNumber } from '@reformer/ui-kit';
+
+type Item = { id: string; name: string; price: number };
+type MyForm = { items: Item[] };
+
+// arrayOf(blank) — пустой список и шаблон строки для кнопки «Добавить»
+const blankItem = (): Item => ({ id: '', name: '', price: 0 });
+const model = createModel<MyForm>({ items: arrayOf(blankItem) });
+
+// разметка одной строки (item.$.field — ручка под-модели строки)
+const itemRow = (item: FormModel<Item>): FormSchemaNode => ({
+  children: [
+    { model: item.$.id, component: Input },
+    { model: item.$.name, component: Input },
+    { model: item.$.price, component: InputNumber },
+  ],
+});
+
+const schema: FormSchemaNode = {
+  children: [{ model: model.$.items, component: FieldArray, item: itemRow }],
+};
+
+const form = createFormFromModel<MyForm>({ model, schema });
+form.items; // FormArray<Item> — форма каждой строки: form.items.at(i)
+```
+
+> Привязка массива — **ручка** `model.$.items`, как у поля и подформы. `item` на привязке, которая
+> массивом не является (лист, группа), — ошибка компиляции.
+
+### Массив как ОДНО значение поля
+
+Массив бывает не набором под-форм, а одним значением: мультивыбор, теги, список файлов. Чем он
+является, решает **схема**, а не данные: `{ model, item }` — набор под-форм, а узел поля
+`{ model: model.$.<путь>, component }` без `item` — одно значение. Массив, к которому в схеме
+ничего не привязано, в форму не попадает.
+
+```typescript
+type MyForm = { tags: string[] };
+
+const model = createModel<MyForm>({ tags: [] });
+
+const schema: FormSchemaNode = {
+  children: [{ model: model.$.tags, component: SelectMulti }], // поле над массивом целиком
+};
+const form = createFormFromModel<MyForm>({ model, schema });
+
+form.tags.setValue(['a', 'b']); // FormControl<string[]>
+model.$.tags.value = ['c']; // ручка значения: заменяет массив целиком
+validate(model.$.tags, [required(), maxLength(3)]); // правило получает массив
+```
+
+- `model.$.<массив>` — записываемая ручка значения (`PathAwareSignal`): подходит для `model:` в
+  схеме, `validate`/`cross`, `enableWhen`/`copyFrom` и для `model.signalAt(path)`.
+- Узел-массив хранит только массив: запись `null`/`undefined` даёт `[]`. Нужно отличать «не
+  выбирали» от «выбрали ничего» — объявляй поле `T[] | null` с начальным `null`: в рантайме это
+  лист, и привязывается он так же.
+- **Контейнер с `null` в типе — значение как есть.** `model.tags` у поля `string[] | null` — это
+  `string[] | null`, а не фасад `ModelArray`; `model.$.tags` — лист `PathAwareSignal` без `length`
+  и индексов; группа `Address | null` — `Address | null` без под-модели. Такое поле начинают с
+  `null`: контейнер, созданный из `[]` или `{}`, в рантайме стал бы фасадом, а тип его не видит.
+- Запись в узел-ГРУППУ (`model.$.<группа>.value = …`) — ошибка: группа пишется по полям или через
+  `model.patch(...)`.
+
+### Массив в группе и в строке другого массива
+
+Узел `{ model, item }` стоит на любой глубине: массив в группе получает ноду `form.<группа>.<массив>`,
+массив в строке — `form.<массив>.at(i).<массив>`. Разметка строки объявляет свои массивы так же.
+
+```typescript
+const contactRow = (contact: FormModel<Contact>): FormSchemaNode => ({
+  children: [
+    { model: contact.$.name, component: Input },
+    { model: contact.$.phones, item: phoneRow }, // массив в строке массива
+  ],
+});
+
+const schema: FormSchemaNode = {
+  children: [
+    { model: model.$.details.hotlines, item: phoneRow }, // массив в группе
+    { model: model.$.contacts, item: contactRow },
+  ],
+};
+```
+
+Поведение строк вложенного массива — `applyEach` внутри схемы строки, см. `21-array-operations.md`.
+
+### Один массив — три слоя (три разных движка)
+
+Одна и та же коллекция описывается **тремя разными формами** — по одной на движок. Их легко
+перепутать, но каждая корректна только в своём контексте:
+
+1. **Схема формы** — узел `{ model: model.$.<path>, item: (itemModel) => узел }` среди `children`
+   дерева:
+
+   ```typescript
+   // узел схемы для createForm / createFormFromModel
+   { model: model.$.properties, component: FieldArray, item: propertyRow },
+   ```
+
+2. **Схема валидации (`@reformer/core/validation`)** — правила строки объявляются отдельной схемой
+   над типом строки и подключаются оператором `applyEach(model.$.<массив>, схема)`. У схемы строки
+   своя область: её `cross` получает снимок строки. Запуск — `validateModel(model, schema)`.
+
+   ```typescript
+   const propertyRules = defineValidation<Property>(({ model }) => {
+     validate(model.$.description, [required()]);
+     validate(model.$.estimatedValue, [required(), min(1)]);
+   });
+
+   // внутри defineValidation<MyForm>(({ model }) => { ... })
+   applyEach(model.$.properties, propertyRules);
+   ```
+
+3. **CDK / render** — работают с уже **материализованной** нодой `form.<array>` (`FormArray`),
+   а не со схемой: `<FieldArray.Root control={form.properties}>` (CDK) или `FieldArraySection` из
+   `@reformer/ui-kit` (`control={form.properties}`, `itemComponent`).
+
+> **Не путай запись по движку.** Схема формы — узел `{ model, item }`; правила строк —
+> `applyEach(model.$.<массив>, схема)` в схеме валидации; `FieldArray.Root control={form.x}` (или
+> `FieldArraySection`) — рендер. `applyEach` в схеме формы не подхватится, а узел `{ model, item }`
+> схема валидации не обходит.
+
+### Array operations — на модели или на ноде
+
+Мутации массива делаются через `ModelArray` (`model.items`) либо через ноду формы `FormArray`
+(`form.items`) — нода данными не владеет и передаёт мутацию в тот же массив модели:
+
+```typescript
+model.items.push({ id: '1', name: '', price: 0 });   // добавить в конец (плоские значения!)
+model.items.insertAt(0, { id: '2', name: '', price: 0 });
+model.items.removeAt(index);
+model.items.move(from, to);
+model.items.swap(a, b);
+model.items.clear();
+model.items.length;                                  // реактивная длина
+model.items.at(0);                                   // под-модель элемента (FormModel<Item>)
+model.items.map((item, i) => item.name);             // item — FormModel<Item>
+
+// та же мутация через ноду формы (у ноды вставка — insert, у модели — insertAt)
+form.items.push();                                   // строка по шаблону arrayOf(blank)
+form.items.insert(0, { id: '3', name: '', price: 0 });
+form.items.removeAt(index);
+form.items.length;                                   // число строк (число, не сигнал)
+form.items.keyAt(index);                             // стабильный ключ строки
+```
+
+Формы строк держатся за под-модели элементов и при `move` / `swap` не пересоздаются; ключ строки
+(`keyAt`) не меняется при перестановке — его и берут для React `key`.
+
+> **Плоские значения при push.** В `push`/`insertAt` передавай payload из **плоских значений**
+> (`{ id, name, price }`), а НЕ FieldConfig-шаблон (`{ value, component }`). Component/componentProps
+> берутся из `item`-фабрики схемы автоматически.
+
+> **Очистка массива в behavior.** Тот же `model.<array>.clear()` (см. список операций выше) —
+> способ очистить коллекцию **вне React**, из behavior: он мутирует модель напрямую, минуя ноды
+> формы. Типичный случай — сбросить массив при выключении флага:
+>
+> ```typescript
+> onChange(model.$.hasProperty, (on) => {
+>   if (!on) model.properties.clear();
+> });
+> ```
+
+### Rendering Arrays
+
+Каждый элемент массива — под-форма (`FormGroup<Item>`). Итерируй через `form.items.map`:
+
+```tsx
+import { useArrayLength } from '@reformer/core/react';
+
+function ItemsList({ form }: { form: FormGroup<MyForm> }) {
+  const length = useArrayLength(form.items);
+
+  return (
+    <div>
+      {form.items.map((item, index) => (
+        <div key={form.items.keyAt(index)}>
+          <FormField control={item.name} />
+          <FormField control={item.price} />
+          <button onClick={() => form.items.removeAt(index)}>Remove</button>
+        </div>
+      ))}
+
+      {length === 0 && <p>No items yet</p>}
+
+      <button onClick={() => form.items.push({ id: crypto.randomUUID(), name: '', price: 0 })}>
+        Add Item
+      </button>
+    </div>
+  );
+}
+```
+
+> В монорепо для массивов используется готовый `FieldArraySection` из `@reformer/ui-kit`
+> (`control={form.items}`, `itemComponent`, add/remove/reorder из коробки; шаблон новой строки —
+> `arrayOf(blank)` в модели, проп `initialValue` — запасной путь). В схеме массив под-форм рисует
+> компонент `FieldArray` узла `{ model, component: FieldArray, item }`.
+> См. `find_recipe(topic="field-array")`.
+
+### Array Cross-Validation
+
+Правило над всем массивом пишется оператором `cross` из аргумента схемы: `check` получает снимок
+модели области (`model.get()`, плоские значения), ошибка вешается на поле-носитель. Тип снимка
+выведен из схемы. Правила строк — `applyEach` (см. выше).
+
+Носитель — любое **скалярное** поле формы (флаг `hasItems`, итоговая сумма и т.п.), у которого
+есть ручка `model.$.<field>` и нода в форме:
+
+```typescript
+type MyForm = { hasItems: boolean; items: Item[] };
+
+defineValidation<MyForm>(({ model, cross }) => {
+  cross(model.$.hasItems, (form) => {
+    const names = form.items.map((item) => item.name);
+    return names.length !== new Set(names).size
+      ? { code: 'items.duplicate' }
+      : null;
+  });
+});
+```
+
+## See also
+
+- [03-api-signatures.md](./03-api-signatures.md) — сигнатуры нод `form.<array>` / `ModelArray`, правила строк `applyEach`
+- [37-compiled-schema.md](./37-compiled-schema.md) — область строки `#/items[<ключ>]` и `keyAt`
+- CDK / ui-kit field-array (`FieldArray.Root`, `FieldArraySection`) — `find_recipe(topic="field-array")`

package/docs/llms/11-async-watchfield.md

@@ -0,0 +1,53 @@
+## 10. ASYNC REACTION — onChange (CRITICALLY IMPORTANT)
+
+Для async-реакции на изменение поля (загрузка зависимых опций, справочников) используй
+`onChange` из `@reformer/core/behaviors`. Колбэк выполняется ВНЕ effect-контекста (можно
+безопасно писать сигналы/ноды), а 2-й аргумент — `{ signal }` (AbortSignal): при следующей
+смене значения предыдущий вызов аннулируется — передавай `signal` в `fetch`.
+
+```typescript
+import { defineFormBehavior, onChange } from '@reformer/core/behaviors';
+
+const behavior = defineFormBehavior<MyForm>(({ model, form }) => {
+  // CORRECT — async onChange со всеми safeguards
+  onChange(
+    model.$.parentField,
+    async (value, { signal }) => {
+      if (!value) {
+        form.dependentField.updateComponentProps({ options: [] });
+        return;
+      }
+      try {
+        const data = await fetchData(value, { signal }); // отмена устаревших запросов
+        form.dependentField.updateComponentProps({ options: data });
+      } catch (error) {
+        if ((error as Error).name === 'AbortError') return;
+        form.dependentField.updateComponentProps({ options: [] });
+      }
+    },
+    { debounce: 300 } // не fetch на каждое нажатие
+  );
+});
+```
+
+### Опции onChange
+
+- `debounce: 300` — не дёргать сеть на каждый keystroke (300–500 мс рекомендуется).
+- `immediate: true` — вызвать колбэк сразу при регистрации (по умолчанию `false`).
+- Guard-clause — пропустить пустое значение.
+- try/catch + проверка `AbortError` — обработка отмены и ошибок.
+
+### Низкоуровневый примитив watchField
+
+`watchField` из `@reformer/core/model` — базовая подписка на изменение сигнала (без debounce и
+AbortSignal). `onChange` построен поверх него. Для простых синхронных реакций:
+
+```typescript
+import { watchField } from '@reformer/core/model';
+
+// вызывается при каждом изменении (по умолчанию НЕ на инициализации)
+const stop = watchField(model.$.country, (country) => {
+  model.city = ''; // сброс зависимого поля
+});
+// stop() — отписаться
+```

package/docs/llms/12-array-cleanup.md

@@ -0,0 +1,31 @@
+## 11. ARRAY CLEANUP PATTERN
+
+Очистка массива при выключении флага — через `onChange` на сигнале флага + `clear()` на
+модели-массиве. Колбит выполняется вне effect-контекста, поэтому мутировать массив безопасно.
+
+```typescript
+import { defineFormBehavior, onChange } from '@reformer/core/behaviors';
+
+const behavior = defineFormBehavior<MyForm>(({ model }) => {
+  // при снятии флага — очистить массив
+  onChange(model.$.hasItems, (hasItems) => {
+    if (!hasItems) model.items.clear();
+  });
+});
+```
+
+Переиспользуемый оператор (как в монорепо):
+
+```typescript
+import { onChange } from '@reformer/core/behaviors';
+import type { ReadonlySignal } from '@reformer/core/behaviors';
+
+function clearWhenOff(flag: ReadonlySignal<boolean>, array: { clear(): void }): void {
+  onChange(flag, (on) => {
+    if (!on) array.clear();
+  });
+}
+
+// в схеме поведения:
+clearWhenOff(model.$.hasProperty, model.properties);
+```