@reformer/core 10.2.0 → 11.0.0-beta.10

package/docs/llms/04-common-patterns.md

@@ -0,0 +1,204 @@
+## 3. COMMON PATTERNS
+
+Значения живут в модели (`model.$.field`), поведение (`defineFormBehavior`) работает на живых
+сигналах, валидация — отдельная схема (`defineValidation`, прогон по требованию через
+раннер). Слои раздельны: схема формы правил НЕ несёт.
+
+### Conditional Fields with Auto-Reset
+
+`enableWhen` — оператор поведения: поле включается по условию, при выключении сбрасывается к
+initial. Вызывается внутри `defineFormBehavior`:
+
+```typescript
+import { defineFormBehavior, enableWhen } from '@reformer/core/behaviors';
+
+const behavior = defineFormBehavior<MyForm>(({ model }) => {
+  enableWhen(
+    [model.$.propertyValue, model.$.initialPayment],
+    () => model.loanType === 'mortgage',
+    { resetOnDisable: true }
+  );
+});
+```
+
+### Computed Field (same or cross level)
+
+`compute`/`computeFrom` пишут в целевой сигнал при изменении источников. Цель не входит
+в источники → цикла нет. Кросс-уровневые вычисления работают так же — источники берутся
+по сигналам из любого места модели.
+
+```typescript
+import { defineFormBehavior, compute, computeFrom } from '@reformer/core/behaviors';
+
+const behavior = defineFormBehavior<MyForm>(({ model }) => {
+  // compute: auto-tracking — читаем что нужно прямо из value-модели
+  compute(model.$.total, () => (model.price ?? 0) * (model.quantity ?? 0));
+
+  // computeFrom: явный список источников
+  computeFrom([model.$.price, model.$.quantity], model.$.total, (price, qty) => price * qty);
+
+  // кросс-уровневое: fullName из вложенной группы
+  compute(model.$.fullName, () =>
+    [model.personalData.firstName, model.personalData.lastName].filter(Boolean).join(' ')
+  );
+});
+```
+
+### Async reaction / dynamic options — `onChange`
+
+Для async-реакции на изменение поля (загрузка справочников, зависимые селекты) используй
+`onChange` из DSL. Колбэк выполняется вне effect-контекста (можно писать сигналы/ноды), а
+2-й аргумент — `{ signal }` (AbortSignal) для отмены устаревших запросов.
+
+```typescript
+import { defineFormBehavior, onChange } from '@reformer/core/behaviors';
+
+const behavior = defineFormBehavior<MyForm>(({ model, form }) => {
+  onChange(
+    model.$.region,
+    async (region, { signal }) => {
+      if (!region) {
+        form.city.updateComponentProps({ options: [] });
+        return;
+      }
+      const cities = await fetchCities(region, { signal });
+      form.city.updateComponentProps({ options: cities });
+    },
+    { debounce: 300 }
+  );
+});
+```
+
+> Низкоуровневый аналог — примитив `watchField(model.$.region, cb)` из `@reformer/core/model` (без debounce/AbortSignal;
+> для сети предпочтителен `onChange`). См. `20-compute-vs-watch.md`, `32-async-options-loading.md`.
+
+### Reading values
+
+```typescript
+// В React-компоненте — хуки (@reformer/core/react)
+const { value, issues, disabled } = useFormControl(form.email);
+const loanType = useFormControlValue(form.loanType); // значение напрямую
+
+// Вне React — из модели
+model.email;             // value-доступ (реактивно внутри effect/computed)
+model.$.email.value;     // через сигнал
+model.$.email.peek();    // нереактивный снимок
+model.get();             // весь объект-снимок
+```
+
+### Submit + validation
+
+Валидация — отдельная `ValidationDefinition<T>` (`defineValidation`), а не часть layout; в сборку
+она уходит полем `validation`. `bundle.submission.submit(handler)` прогоняет все правила один раз,
+разносит замечания по нодам и зовёт обработчик только при статусе `valid` (`severity: 'warning'` не
+блокирует). Результат — `SubmitResult`.
+
+```typescript
+async function handleSubmit(event: React.FormEvent) {
+  event.preventDefault();
+  const outcome = await bundle.submission.submit(async (values) => {
+    await api.send(values);
+    bundle.model.reset(); // к initial-снимку — только после успеха
+  });
+  if (outcome.status === 'invalid') showHint('Проверьте форму'); // поля уже подсвечены
+}
+```
+
+Без сборки — раннер `validateModel(model, schema)`: сам разносит замечания по нодам и отвечает
+`Promise<boolean>`.
+
+Multi-step: шаги и их правила — поток сборки `createForm({ flow: { steps: [{ id, rules }] } })`
+(`id` — `selector` шага), правила вне шагов — `validation: { extras }`. Сборка отдаёт
+`bundle.validateStep(id)`, `bundle.validate()` и поток `bundle.flow` (`next` / `previous` / `goTo`);
+визард принимает поток пропом `flow`. См. `13-multi-step.md`, `28-submit-and-reset.md`,
+`38-form-flow.md`.
+
+### Cross-field validation — через `cross`
+
+Cross-field правило — обычная функция над **снимком** модели. Оператор `cross` берётся из
+аргумента схемы и вешает правило на поле-носитель ошибки; тип снимка выведен из схемы:
+
+```typescript
+import { defineValidation, validate } from '@reformer/core/validation';
+import { required, min } from '@reformer/core/validators';
+import type { ValidationIssue } from '@reformer/core';
+
+// снимок формы читается напрямую — без каста, соседние поля доступны как поля объекта
+const initialPaymentVsProperty = (form: MyForm): ValidationIssue | null =>
+  form.initialPayment && form.propertyValue && form.initialPayment > form.propertyValue
+    ? { code: 'initialPaymentTooHigh' } // текст кода — в словаре формы (defineIssueMessages)
+    : null;
+
+const schema = defineValidation<MyForm>(({ model, cross }) => {
+  validate(model.$.initialPayment, [required(), min(0)]);
+  cross(model.$.initialPayment, initialPaymentVsProperty); // ошибка сядет на initialPayment
+});
+```
+
+> Правила строки массива и подформы — отдельная схема над их типом, подключённая через
+> `applyEach(model.$.items, rowRules)` / `apply(model.$.group, groupRules)`. У такой схемы своя
+> область: её `cross` получает снимок строки или группы.
+
+### Conditional validation — `validateWhen`
+
+Условная валидация — `validateWhen(() => cond, () => { … })`: правила внутри активны, только пока
+условие истинно; при `false` ранее тронутые поля гасятся. Это не `enable` (то — поведение), а
+включение/выключение самих проверок:
+
+```typescript
+import { defineValidation, validateWhen, validate } from '@reformer/core/validation';
+
+const loanRules = defineValidation<MyForm>(({ model, cross }) => {
+  validateWhen(
+    () => model.loanType === 'mortgage',
+    () => {
+      validate(model.$.propertyValue, [required(), min(1000000)]);
+      cross(model.$.initialPayment, initialPaymentVsProperty);
+    }
+  );
+});
+```
+
+### Перезапуск прогона — `revalidateWhen` (мост поведение → валидация)
+
+Схема прогоняется по требованию (submit/шаг) либо живой стратегией сборки
+(`validation: { strategy: 'change' }`, см. `33-validation-strategy.md`). Чтобы перезапустить
+отдельную схему при изменении зависимости — `revalidateWhen` из **поведения** (мост
+поведение → валидация):
+
+```typescript
+import { defineFormBehavior, revalidateWhen } from '@reformer/core/behaviors';
+import { validateModel } from '@reformer/core/validation';
+
+const behavior = defineFormBehavior<MyForm>(({ model }) => {
+  revalidateWhen([model.$.propertyValue], () => void validateModel(model, schema));
+});
+```
+
+### Extracting named rules
+
+Когда тело правила растёт — выноси в именованную функцию. Field-правило типизируй `Rule<T>`
+(`(value) => ValidationIssue | null`), cross-field — обычной `(f: Root) => ValidationIssue | null`.
+Схема остаётся плоской и читается как оглавление:
+
+```typescript
+import { defineValidation, validate } from '@reformer/core/validation';
+import { required } from '@reformer/core/validators';
+import type { Rule } from '@reformer/core/validation';
+
+// field-правило: (value) => error
+const validateAdultAge: Rule<string> = (value) => {
+  if (!value) return null;
+  const age = new Date().getFullYear() - new Date(value).getFullYear();
+  return age < 18 ? { code: 'tooYoung' } : null;
+};
+
+const schema = defineValidation<MyForm>(({ model }) => {
+  validate(model.$.birthDate, [required(), validateAdultAge]);
+});
+```
+
+**Naming convention** (camelCase, семантика, не эхо оператора):
+
+- Cross-field правило → инвариант: `initialPaymentVsPropertyValue`, `paymentToIncomeUnderHalf`.
+- Field-правило → проверка: `validateAdultAge`, `passwordsMatch`.

package/docs/llms/05-common-mistakes.md

@@ -0,0 +1,192 @@
+## 4. COMMON MISTAKES
+
+### Imports rule (#1 cause of cascading errors — read first)
+
+- Модель/форма/типы (`createForm`, `FormModel`, `FormSchemaNode`, `ValidationIssue`, `FormFlow`) — из `@reformer/core`.
+- Хуки (`useFormBundle`, `useFormControl`, `useFormFlow`, `useIssueMessage`, …) и `I18nProvider` — из `@reformer/core/react`.
+- Схема валидации (`defineValidation` + операторы `validate`/`validateAsync`/`validateWhen`/`apply`/`applyEach`) и раннер `validateModel` — из `@reformer/core/validation`. `cross` берётся из аргумента схемы.
+- Чистые фабрики валидаторов (`required`/`min`/`email`/…) — из `@reformer/core/validators`.
+- Словарь текстов замечаний (`defineIssueMessages`, `resolveIssueMessage`) — из `@reformer/core/i18n`.
+- Декларативный DSL поведения (`defineFormBehavior` + операторы) — из `@reformer/core/behaviors`.
+
+```typescript
+// ✅ CORRECT
+import {
+  createModel,
+  createForm,
+  type FormGroup,
+  type FormSchemaNode,
+  type FormModel,
+  type ValidationIssue,
+} from '@reformer/core';
+import { useFormBundle, useFormControl, useFormControlValue } from '@reformer/core/react';
+import { defineIssueMessages } from '@reformer/core/i18n';
+// схема валидации + раннер — отдельный слой:
+import {
+  defineValidation,
+  validate,
+  validateAsync,
+  validateWhen,
+  apply,
+  applyEach,
+  validateModel,
+  type Rule,
+  type AsyncRule,
+  type ValidationDefinition,
+} from '@reformer/core/validation';
+import { required, min, max, email } from '@reformer/core/validators';
+// поведение формы — декларативный DSL:
+import { defineFormBehavior, compute, enableWhen, copyFrom, onChange } from '@reformer/core/behaviors';
+// примитивы над сигналами (вне формы, возвращают cleanup) — отдельный сабпат:
+import { computeFrom, watchField } from '@reformer/core/model';
+```
+
+> **В корне `@reformer/core` операторов поведения нет.** `computeFrom`, `copyFrom`, `watchField`,
+> `transformValue`, `resetWhen`, `syncFields`, `revalidateWhen` — примитивы сабпата
+> `@reformer/core/model`; `enableWhen` / `disableWhen` — только операторы `@reformer/core/behaviors`.
+> В DSL для реакции на изменения используется `onChange`.
+
+### Значения — в модели, не в форме
+
+Источник истины значений — модель. Форма (ноды) отражает их; `form.x.setValue(v)` пишет в ту же
+модель.
+
+```typescript
+// ✅ читаем/пишем значение
+model.email = 'a@b.c';       // value-доступ
+model.$.email.value;         // сигнал
+model.get();                 // весь снимок для submit
+
+// В компоненте — реактивно через хуки
+const email = useFormControlValue(form.email);
+```
+
+### useFormControlValue (CRITICAL)
+
+```typescript
+// WRONG - useFormControlValue returns T directly, NOT { value: T }
+const { value: loanType } = useFormControlValue(control.loanType);
+// Result: loanType is ALWAYS undefined!
+
+// CORRECT
+const loanType = useFormControlValue(control.loanType);
+
+// ALSO CORRECT - useFormControl returns object
+const { value, issues } = useFormControl(control.loanType);
+```
+
+### Behaviors принимают СИГНАЛЫ, а не пути/форму
+
+```typescript
+// ❌ WRONG - строковые пути и (form) => ... это старый API, удалён
+enableWhen(path.city, (form) => Boolean(form.country));
+computeFrom(['price', 'quantity'], 'total', (values) => values.price * values.quantity);
+
+// ✅ CORRECT - сигналы модели, условие читает model напрямую
+enableWhen(model.$.city, () => Boolean(model.country), { resetOnDisable: true });
+computeFrom([model.$.price, model.$.quantity], model.$.total, (price, qty) => price * qty);
+```
+
+### Валидаторы — оператор `validate`, а не узел схемы
+
+Валидация — **отдельный слой** (`@reformer/core/validation`), а не ключ узла. Схема формы
+(билдер `createForm` / JSON-DSL) правил **не несёт**: они живут в `ValidationDefinition` и уходят в
+сборку полем `validation` (шаги — `flow`). Запуск — уровнем формы:
+`bundle.submission.submit(handler)`, `bundle.validate()`, `bundle.validateStep(id)`; без сборки —
+`validateModel(model, schema)`. У нод методов `validate()` / `submit()` нет.
+
+```typescript
+// ❌ WRONG - ключей value и validators у узла нет, как и записи «имя → узел»
+const schema = {
+  email: { value: model.$.email, component: Input, validators: [required(), email()] },
+};
+validate(path.email, required(), 'Email is required'); // старая сигнатура validate() — удалена
+required({ message: 'Email is required' }); // опции message нет — текст живёт в словаре формы
+
+// ✅ CORRECT - операторы validate/validateAsync внутри defineValidation; у правила — код
+const emailSchema = defineValidation<MyForm>(({ model }) => {
+  validate(model.$.email, [required({ code: 'email.required' }), email()]);
+  validateAsync(model.$.email, [
+    async (value, { signal }) => {
+      const res = await fetch(`/api/free?email=${value}`, { signal });
+      return (await res.json()).free ? null : { code: 'email.taken' };
+    },
+  ]);
+});
+// тексты кодов — словарь формы
+export const formMessages = defineIssueMessages({
+  'email.required': 'Укажите email',
+  'email.taken': 'Email уже занят',
+});
+
+// прогон — уровнем формы: замечания сами доезжают до нод, warnings не блокируют.
+// Отклонённое async-правило — сбой: статус `error`, на поле замечание `ruleFailed`.
+const outcome = await bundle.submission.submit(api.send); // createForm({ …, validation: emailSchema })
+```
+
+### Cross-field — оператор `cross`, а не `ctx.form`
+
+```typescript
+// ❌ WRONG - ctx.form / ctx.setFieldValue / value.value — старый API; ModelValidator(value,scope,root) удалён
+watchField(path.amount, (amount, ctx) => {
+  const rate = ctx.form.rate.value.value;
+  ctx.setFieldValue('total', amount * rate);
+});
+
+// ✅ CORRECT - compute (поведение) на сигналах; cross-field (валидация) через оператор cross
+compute(model.$.total, () => (model.amount ?? 0) * (model.rate ?? 0));
+
+// cross-field правило — обычная функция над снимком модели; `cross` берётся из аргумента схемы:
+const amountVsMax = (form: MyForm): ValidationIssue | null =>
+  form.amount != null && form.maxAmount != null && form.amount > form.maxAmount
+    ? { code: 'amount.tooBig', params: { max: form.maxAmount } }
+    : null;
+
+const amountSchema = defineValidation<MyForm>(({ model, cross }) => {
+  cross(model.$.amount, amountVsMax); // check получает снимок модели, ошибка — на model.$.amount
+});
+```
+
+### Form-shape types — `interface` или `type`
+
+Форму данных можно объявлять и `interface`, и `type` — оба работают с `createModel<T>`,
+`createForm<T>`, `FormGroup<T>` и `FormArray<T>`. Группу от поля `FormGroup` отличает по виду
+значения (обычный объект, а не массив, дата, файл или функция), а не по index signature. Эталонная
+форма (`CreditApplication`) объявлена через `interface`.
+
+```typescript
+// ✅ interface
+export interface PropertyItem {
+  type: PropertyType;
+  description: string;
+}
+
+// ✅ type alias — то же самое
+export type PropertyItem = {
+  type: PropertyType;
+  description: string;
+};
+```
+
+Единственная оговорка — свои обобщённые хелперы: `interface` не присваивается
+`Record<string, unknown>` (у него нет неявной index signature). Ограничение пиши через
+`T extends object`, а не `T extends Record<string, unknown>`.
+
+`number | null` — конвенциональный тип для очищенного поля; встроенные валидаторы
+(`min`, `max`, `minLength`, `maxLength`, `minDate`, `maxDate`, `minAge`, `maxAge`) пропускают
+пустые значения внутри.
+
+### Вид ноды — гардами, а не instanceof
+
+`FormControl`, `FormGroup`, `FormArray` — интерфейсы: классов нод в публичном API нет, проверка
+`instanceof` не скомпилируется. Вид ноды различают гарды по метке вида:
+
+```typescript
+// ❌ FormControl — тип, а не класс
+if (node instanceof FormControl) { ... }
+
+// ✅ type guards
+import { isFormNode, isFormControl, isFormGroup, isFormArray } from '@reformer/core';
+if (isFormControl(node)) node.updateComponentProps({ placeholder: 'Email' });
+if (isFormArray(node)) node.push();
+```

package/docs/llms/06-troubleshooting.md

@@ -0,0 +1,16 @@
+## 5. TROUBLESHOOTING
+
+| Error                                                          | Cause                                                    | Solution                                                                                                                                                                                                                |
+| -------------------------------------------------------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `'message' does not exist in type 'RuleOptions'`               | Текст передан в правило — у правил текста нет            | `required({ code: 'phone.required' })` + запись `'phone.required'` в `defineIssueMessages`; см. 36-issue-messages.md                                                                                                    |
+| `'string' is not assignable to 'RuleOptions'`                  | Валидатору передали строку вместо options                | `required({ code: 'field.required' })`                                                                                                                                                                                  |
+| `Module has no exported member`                                | Неверный источник импорта                                | хуки и `I18nProvider` — из `@reformer/core/react`; `watchField`/примитивы — из `@reformer/core/model`; DSL — из `@reformer/core/behaviors`; фабрики — из `@reformer/core/validators`; удалённое — 17-nonexistent-api.md |
+| `undefined` из `useFormControlValue`                           | Деструктурировали хук                                    | `const v = useFormControlValue(...)` — без деструктуризации                                                                                                                                                             |
+| `enableWhen`/`disableWhen` не срабатывает                      | Поле не материализовано в форме (элемент массива)        | Убедись, что поле есть в схеме `createForm`; для per-item — `applyEach`                                                                                                                                                 |
+| `Cycle detected`                                               | Взаимные `compute`/`computeFrom` без стабилизации        | Разорви цикл через условие `when` или `peek`; см. 22-cycle-detection.md                                                                                                                                                 |
+| Значение поля не пишется                                       | Пишем в форму вместо модели                              | Значения принадлежат модели: `model.field = ...` / `model.$.field.value = ...` / `form.field.setValue(...)`                                                                                                             |
+| Замечания не появляются после submit                           | Отправка в обход проверки (`api.send(model.get())`)      | `await bundle.submission.submit(handler)` — один прогон правил, при отказе вся форма помечается тронутой; без сборки — `await validateModel(model, schema)`                                                             |
+| На поле текст вида `loanAmount.required`                       | Свой код правила без записи в словаре формы              | Добавь код в `defineIssueMessages` и подключи `ValidationMessagesProvider messages` (cdk)                                                                                                                               |
+| `compileSchema: в области «#» селектор «X» повторяется`        | Два узла с одним `selector` в одной области схемы        | Разные селекторы; см. 37-compiled-schema.md                                                                                                                                                                             |
+| `createForm: шага «X» нет в потоке` / `FormFlow: шага «X» нет` | `validateStep(id)` / `flow.goTo(id)` с неизвестным шагом | `id` — из `flow.steps`; см. 38-form-flow.md                                                                                                                                                                             |
+| `flow.goTo(id)` вернул `reason: 'locked'`                      | Прыжок вперёд через непройденный шаг                     | Вперёд — `flow.next()`; `goTo` — назад и на открытые шаги                                                                                                                                                               |

package/docs/llms/07-complete-import.md

@@ -0,0 +1,130 @@
+## Import Patterns
+
+```typescript
+// Модель, форма, уровень формы, типы — из @reformer/core. React здесь нет: корень работает и на сервере
+import {
+  createModel,
+  createForm,
+  createFormFromModel,
+  disposeForm, // снять форму из createFormFromModel; сборку снимает bundle.dispose()
+  createSubmission, // отправка без сборки (визард в разметке без createForm)
+  arrayOf, // массив модели с шаблоном новой строки
+  compileSchema, // авторское дерево → CompiledSchema (обычно не нужен: createForm компилирует сам)
+  createFormFlow, // поток шагов без сборки
+  isFormControl,
+  isFormGroup,
+  isFormArray,
+} from '@reformer/core';
+
+// Привязка к React — хуки, контекст сборки, связка поля с контролом, провайдер локали — из /react
+import {
+  useFormBundle,
+  useFormControl,
+  useFormControlValue,
+  useArrayLength,
+  useFormFlow, // снимок потока шагов для рендера
+  useFormValidation, // стратегия без сборки: submit() — попытка отправки, validate() — проверка
+  useIssueMessage, // текст замечания: словарь формы → локаль → английский → код
+  I18nProvider,
+} from '@reformer/core/react';
+import type { FieldControlState } from '@reformer/core/react';
+
+// Типы
+import type {
+  FormModel, // реактивная модель данных
+  FormBundle, // результат createForm: { model, form, render, flow, validate, validateStep, submission, dispose, … }
+  FormNode, // общий контракт ноды
+  FormControl, // нода одного поля
+  FormGroup, // нода группы — тип формы для props компонентов
+  FormArray, // нода массива под-форм
+  ModelArray, // реактивный массив модели (push/removeAt/at/map/length)
+  ModelSignals, // дерево ручек ($)
+  PathAwareSignal, // ручка, знающая свой путь
+  ValidationIssue, // { code, params?, severity? } — без текста
+  RuleOptions, // { code?, params? } — опции фабрик правил
+  FormSchemaNode, // узел схемы: поле | массив под-форм | подформа | контейнер
+  CompiledSchema, // скомпилированная схема: bundle.render.tree
+  FormValidation, // правила формы как данные: { rules?, extras?, strategy?, debounce? }
+  FormFlowConfig, // поток шагов в конфиге: { steps: [{ id, rules? }] }
+  FormFlow, // поток шагов сборки: current, next(), previous(), goTo(id)
+  FlowTransition, // итог перехода: moved | stayed
+  FormSubmission, // отправка сборки (bundle.submission): submit(handler), submitting
+  SubmitResult, // итог bundle.submission.submit: submitted | invalid | error | cancelled | failed
+} from '@reformer/core';
+
+// Схема валидации: операторы + раннер — из /validation
+import {
+  defineValidation,
+  validate,
+  validateAsync,
+  validateWhen,
+  apply, // правила подформы: apply(model.$.group, rules); композиция: apply(rulesA, rulesB)
+  applyEach, // правила строк массива: applyEach(model.$.items, rules)
+  validateModel, // раннер без сборки: сбор + разнос, Promise<boolean>
+  runValidation, // только сбор: Promise<ValidationResult>
+  applyValidationResult, // разнос собранного результата по нодам
+} from '@reformer/core/validation';
+import type {
+  Rule, // (value) => ValidationIssue | null
+  AsyncRule, // (value, { signal }) => Promise<ValidationIssue | null>
+  ValidationDefinition, // ({ model, cross }) => void — cross берётся из аргумента схемы
+  ValidationResult, // { status, issues, failures }
+} from '@reformer/core/validation';
+
+// Валидаторы — чистые фабрики из /validators (кладутся в validate(sig, [...]))
+import { required, min, max, email, minLength, pattern } from '@reformer/core/validators';
+
+// Тексты замечаний и локаль без React — из /i18n
+import { defineIssueMessages, resolveIssueMessage, createI18n } from '@reformer/core/i18n';
+
+// Декларативный DSL behaviors — из /behaviors
+import {
+  defineFormBehavior,
+  compute,
+  computeFrom,
+  copyFrom,
+  onChange,
+  enableWhen,
+  disableWhen,
+  transformValue,
+  resetWhen,
+  syncFields,
+  revalidateWhen,
+  apply,
+  applyEach,
+  aggregateInto,
+  exclusiveFlag,
+  hideWhen, // операторы узлов схемы — исполняет рендерер
+  renderEffect,
+} from '@reformer/core/behaviors';
+
+// Примитивы над сигналами (принимают сигналы, возвращают cleanup) — из /model, в корне их нет
+import { computeFrom, copyFrom, watchField } from '@reformer/core/model';
+// Утилиты значений модели — тоже из /model
+import {
+  deepEqual, // сравнение значений модели (на нём isDirty)
+  deferredWritesSettled, // дождаться отложенных записей поведения тика; undefined — ждать нечего
+} from '@reformer/core/model';
+```
+
+### Форма данных — `interface` или `type`
+
+Оба варианта работают одинаково: `createModel<T>`, `createForm<T>`, `FormGroup<T>` и `FormArray<T>`
+принимают и `interface`, и `type`-alias — для корня, вложенных групп и элементов массивов. Группу
+от поля сборка отличает по виду значения (обычный объект — группа; массив объектов — массив
+под-форм; примитив, массив примитивов, дата, файл — поле), а не по index signature.
+
+```typescript
+export interface AddressForm {
+  street: string;
+  city: string;
+}
+
+export interface CoBorrower {
+  fullName: string;
+  phone: string;
+}
+```
+
+Оговорка для своих обобщённых хелперов: `interface` не присваивается `Record<string, unknown>`, поэтому
+ограничение пиши `T extends object`. См. `30-type-safety-recipes.md`.

package/docs/llms/08-form-types.md

@@ -0,0 +1,54 @@
+## 7. FORM TYPE DEFINITION
+
+Форму данных объявляй через `interface` или `type`-alias — оба варианта работают одинаково (см.
+`30-type-safety-recipes.md`). Тип описывает форму ДАННЫХ (то, что кладётся в `createModel`), без
+узлов/сигналов.
+
+```typescript
+// CORRECT form type definition
+interface MyForm {
+  // Required fields
+  name: string;
+  email: string;
+
+  // Optional fields — конвенция для форм: null («пользователь очистил»)
+  phone: string | null;
+  age: number | null;
+
+  // Enum/union types
+  status: 'active' | 'inactive';
+
+  // Nested objects
+  address: {
+    street: string;
+    city: string;
+  };
+
+  // Arrays of objects — model-owned (см. 10-arrays.md)
+  items: Array<{
+    id: string;
+    name: string;
+  }>;
+}
+
+// Модель создаётся из initial-значений этого типа
+const model = createModel<MyForm>({
+  name: '',
+  email: '',
+  phone: null,
+  age: null,
+  status: 'active',
+  address: { street: '', city: '' },
+  items: [],
+});
+```
+
+`number | null` / `string | null` работают со встроенными валидаторами напрямую —
+`min`/`max`/`minLength`/`minDate`/`minAge` пропускают пустые значения внутри, guard `if (v != null)`
+не нужен.
+
+Какой ноде формы соответствует поле, решает вид значения: объект — `FormGroup`
+(`form.address.city`), массив объектов — `FormArray` (`form.items.at(0)`), примитив, массив
+примитивов, `Date`, `File` — `FormControl`. Вычисляемые поля (цели `compute`) удобно держать
+отдельным типом и объявлять форму пересечением: `type MyFormFull = MyForm & MyFormDerived` — тогда
+на сервер уходит только ввод (`MyForm`), а вычисляемые ключи отрезаются перед отправкой.