@reformer/core 11.0.0-beta.1 → 11.0.0-beta.10

package/docs/llms/01-api-reference.md

@@ -2,52 +2,78 @@
 
 ### Imports (CRITICALLY IMPORTANT)
 
-Архитектура M1: значения живут в **модели** (`createModel`), а форма (`createForm`) строит ноды поверх сигналов модели. Behaviors работают на сигналах (`model.$.field`), а не на строковых путях.
-
-| What                                                                                                   | Where                       |
-| ------------------------------------------------------------------------------------------------------ | --------------------------- |
-| `createModel`, `createForm`                                                                            | `@reformer/core`            |
-| `validateModel`, `defineValidationSchema`, `validate`, `validateAsync`, `validateWhen`, `cross`, `each`, `apply` | `@reformer/core/validation` |
-| `Rule`, `AsyncRule`, `ValidationSchema` (типы)                                                         | `@reformer/core/validation` |
-| `useFormControl`, `useFormControlValue`, `useArrayLength`                                              | `@reformer/core`            |
-| `FormModel`, `FormProxy`, `FieldNode`, `GroupNode`, `ArrayNode`, `ModelArrayNode`                     | `@reformer/core`            |
-| `ModelSignals`, `ModelArray`, `ModelValue`, `ModelObject`, `PathAwareSignal`                          | `@reformer/core`            |
-| `ValidationError`, `FieldConfig`, `FormSchema`, `FieldControlState`                                    | `@reformer/core`            |
-| `computeFrom`, `copyFrom`, `watchField`, `enableWhen`, `disableWhen`                                   | `@reformer/core` (примитивы) |
-| `transformValue`, `resetWhen`, `syncFields`, `revalidateWhen`                                          | `@reformer/core` (примитивы) |
-| `required`, `min`, `max`, `minLength`, `maxLength`, `email`, `pattern`, `url`, `phone`                | `@reformer/core/validators` |
-| `isNumber`, `integer`, `multipleOf`, `nonNegative`, `nonZero`                                          | `@reformer/core/validators` |
-| `isDate`, `minDate`, `maxDate`, `pastDate`, `futureDate`, `minAge`, `maxAge`                           | `@reformer/core/validators` |
-| `defineFormBehavior`, `compute`, `computeFrom`, `copyFrom`, `onChange`, `enableWhen`, `disableWhen`   | `@reformer/core/behaviors`  |
-| `transformValue`, `resetWhen`, `syncFields`, `revalidateWhen`, `apply`, `applyEach`, `aggregateInto`  | `@reformer/core/behaviors`  |
-| `exclusiveFlag`, `onDispose`, `getScope`, `effect`, `defer`                                            | `@reformer/core/behaviors`  |
-
-> **Два способа писать behaviors.** Низкоуровневые примитивы (`computeFrom`, `copyFrom`, `watchField`,
-> `enableWhen`, …) экспортируются из `@reformer/core`, принимают **сигналы** (`model.$.x`), возвращают
-> **cleanup-функцию** и вызываются императивно (например, в `useEffect`). Декларативный DSL
-> (`defineFormBehavior` + операторы) экспортируется из `@reformer/core/behaviors`, регистрирует cleanup
-> сам и передаётся в `createForm({ behavior })`. См. `20-compute-vs-watch.md`.
-
-> **Валидация — отдельный слой.** Layout-схема `createForm` НЕ несёт валидаторов. Правила живут в
-> `defineValidationSchema<T>(({ model }) => { validate(model.$.x, [required(), min(50000)]); ... })`
+Значения живут в **модели** (`createModel`), а форма (`createForm`) строит ноды поверх сигналов модели. Схема, правила и поведение привязываются к ручкам модели (`model.$.field`), а не к строковым путям.
+
+| What                                                                                                   | Where                                            |
+| ------------------------------------------------------------------------------------------------------ | ------------------------------------------------ |
+| `createModel`, `createForm`, `createFormFromModel`, `disposeForm`, `arrayOf`, `modelOf`                | `@reformer/core`                                 |
+| `compileSchema`, `createFormFlow`, `createFormLevel`, `createSubmission`, `getNodeForSignal`           | `@reformer/core`                                 |
+| `isFormNode`, `isFormControl`, `isFormGroup`, `isFormArray` (гарды нод)                                | `@reformer/core`                                 |
+| `FormModel`, `FormBundle`, `FormNode`, `FormControl`, `FormGroup`, `FormArray`, `FormFields`           | `@reformer/core`                                 |
+| `ModelSignals`, `ModelArray`, `ModelValue`, `ModelObject`, `PathAwareSignal`                           | `@reformer/core`                                 |
+| `ValidationIssue`, `RuleOptions`, `FormSchemaNode`, `ComponentRef`, `CompiledSchema`                   | `@reformer/core`                                 |
+| `FormValidation`, `FormFlowConfig`, `FormFlow`, `FlowTransition`, `SubmitResult`                       | `@reformer/core`                                 |
+| `FormSubmission`, `SubmissionDependencies`, `ActionCheck` (отправка)                                   | `@reformer/core`                                 |
+| `defineValidation`, `validate`, `validateAsync`, `validateWhen`, `apply`, `applyEach`                  | `@reformer/core/validation`                      |
+| `validateModel`, `runValidation`, `applyValidationResult` (раннер), `createFormValidation`             | `@reformer/core/validation`                      |
+| `Rule`, `AsyncRule`, `ValidationDefinition`, `ValidationScope`, `ValidationResult` (типы)              | `@reformer/core/validation`                      |
+| `FormValidationController`, `FormValidationRunOptions`, `ValidationStrategyKind` (типы стратегии)      | `@reformer/core/validation`                      |
+| `useFormBundle`, `useFormControl`, `useFormControlValue`, `useArrayLength`, `useFormValidation`        | `@reformer/core/react`                           |
+| `useFormFlow`, `FormBundleContext`, `useFormBundleContext`                                             | `@reformer/core/react`                           |
+| `bindFieldProps`, `getFieldAdapter`, `FieldAdapter`, `FieldHandle`, `FieldControlState` (связка поля)  | `@reformer/core/react`                           |
+| `I18nProvider`, `useI18n`, `useMessages`, `useIssueMessage`                                            | `@reformer/core/react`                           |
+| `defineIssueMessages`, `resolveIssueMessage`, `createI18n`, `extendLocale`, `createLocaleLoader`       | `@reformer/core/i18n`                            |
+| `computeFrom`, `copyFrom`, `watchField`, `transformValue`, `resetWhen`, `syncFields`, `revalidateWhen` | `@reformer/core/model` (примитивы над сигналами) |
+| `deepEqual`, `deferredWritesSettled` (сравнение значений, ожидание отложенных записей поведения)       | `@reformer/core/model`                           |
+| `required`, `min`, `max`, `minLength`, `maxLength`, `email`, `pattern`, `url`, `phone`                 | `@reformer/core/validators`                      |
+| `isNumber`, `integer`, `multipleOf`, `nonNegative`, `nonZero`                                          | `@reformer/core/validators`                      |
+| `isDate`, `minDate`, `maxDate`, `pastDate`, `futureDate`, `minAge`, `maxAge`                           | `@reformer/core/validators`                      |
+| `defineFormBehavior`, `compute`, `computeFrom`, `copyFrom`, `onChange`, `enableWhen`, `disableWhen`    | `@reformer/core/behaviors`                       |
+| `transformValue`, `resetWhen`, `syncFields`, `revalidateWhen`, `apply`, `applyEach`, `aggregateInto`   | `@reformer/core/behaviors`                       |
+| `exclusiveFlag`, `onDispose`, `getScope`, `effect`, `defer`                                            | `@reformer/core/behaviors`                       |
+| `hideWhen`, `onComponentEvent`, `renderEffect`, `onInit`, `onMount`, `onUnmount` (узлы схемы)          | `@reformer/core/behaviors`                       |
+
+> **Корень `@reformer/core` без React.** Хуки, контекст сборки, связка поля с контролом и
+> провайдер локали — только из `@reformer/core/react`. Корень работает на сервере и с любым слоем
+> представления.
+
+> **Поведение формы — `@reformer/core/behaviors`.** Декларативный DSL (`defineFormBehavior` +
+> операторы) регистрирует cleanup сам и передаётся в `createForm({ behavior })`. Примитивы над
+> сигналами (`computeFrom`, `copyFrom`, `watchField`, …) в корень `@reformer/core` не входят: они
+> лежат в сабпате `@reformer/core/model`, принимают **сигналы** (`model.$.x`), возвращают
+> **cleanup-функцию** и нужны вне формы. `enableWhen` / `disableWhen` существуют только как
+> операторы поведения. См. `20-compute-vs-watch.md`.
+
+> **Валидация — отдельный слой.** Схема формы правил НЕ несёт. Правила живут в
+> `defineValidation<T>(({ model, cross }) => { validate(model.$.x, [required(), min(50000)]); ... })`
 > из `@reformer/core/validation`; фабрики `required()`, `min(50000)`, `email()` возвращают
-> `Rule<T> = (value) => ValidationError | null` и передаются массивом в `validate(sig, [...])`.
-> Запуск — только внешним раннером `await validateModel(model, schema)` (`Promise<boolean>`, ошибки
-> сам роутит в ноды; `form.validate()`/`form.submit()` schema-валидацию НЕ гоняют).
+> `Rule<T> = (value: T) => ValidationIssue | null` и передаются массивом в `validate(sig, [...])`.
+> Правила отдают сборке: `createForm({ validation, flow })`. Запуск — уровнем формы:
+> `bundle.validate()` (`ValidationResult` со статусом `valid` / `invalid` / `error` / `cancelled`),
+> `bundle.validateStep(id)`, отправка `bundle.submission.submit(handler)` (`SubmitResult`). Без
+> сборки — раннер `validateModel(model, rules)` (`Promise<boolean>`) либо `runValidation` (полный
+> результат). Снять сборку — `bundle.dispose()`. См. `38-form-flow.md`.
+
+> **Текста у замечания нет.** `ValidationIssue = { code, params?, severity? }`; строку по коду
+> даёт словарь формы (`defineIssueMessages`) поверх словаря локали. Опции правил —
+> `RuleOptions = { code?, params? }`. См. `36-issue-messages.md`.
 
 ### Type Values
 
 - Опциональные числа: `number | null` (конвенция «пользователь очистил поле»)
 - Опциональные строки: `string` (по умолчанию пустая строка) или `string | null`
-- Form-shape тип объявляй как `type`-alias — см. `30-type-safety-recipes.md`
+- Форму данных объявляй через `interface` или `type` — оба варианта работают, см.
+  `30-type-safety-recipes.md`
 
 ### React Hooks Comparison (CRITICALLY IMPORTANT)
 
 | Hook | Return Type | Subscribes To | Use Case |
 |------|-------------|---------------|----------|
-| `useFormControl(field)` | `{ value, errors, disabled, touched, valid, invalid, pending, shouldShowError, componentProps }` | Все сигналы поля | Полное состояние поля, инпуты |
+| `useFormControl(field)` | `{ value, issues, disabled, touched, dirty, valid, invalid, pending, shouldShowError, shouldShowIssues, componentProps }` | Все сигналы поля | Полное состояние поля, инпуты |
 | `useFormControlValue(field)` | `T` (значение напрямую) | Только сигнал value | Условный рендеринг |
 | `useArrayLength(array)` | `number` | Только длина массива | Реактивная длина массива |
+| `useFormFlow(bundle.flow)` | `{ current, index, completed, isFirst, isLast, validating }` | Сигналы потока шагов | Свои кнопки и индикатор шагов |
+| `useIssueMessage(messages?)` | `(issue) => string` | Локаль | Текст замечания в своём компоненте |
 
 **CRITICAL**: Не деструктурируй `useFormControlValue`! Он возвращает `T` напрямую, НЕ `{ value: T }`.
 
@@ -59,5 +85,5 @@ const { value: loanType } = useFormControlValue(control.loanType);
 const loanType = useFormControlValue(control.loanType);
 
 // CORRECT - useFormControl returns object, destructuring OK
-const { value, errors, disabled } = useFormControl(control.loanType);
+const { value, issues, disabled } = useFormControl(control.loanType);
 ```

package/docs/llms/02-quick-start.md

@@ -1,80 +1,99 @@
 ## 1.5 QUICK START - Minimal Working Form
 
 > **Schema-driven UI rule (read first)**: компонент И его пропсы (label, placeholder,
-> options, type) объявляются в **схеме поля** (`component` + `componentProps`).
+> options, type) объявляются в **узле схемы** (`component` + `componentProps`).
 > В JSX рендерится один универсальный `<FormField control={form.x} />` из
 > `@reformer/ui-kit` БЕЗ дополнительных props. Не пиши свои `Input`/`Select`/
 > `Checkbox`-обёртки с `label`-prop'ами — это anti-pattern. См.
 > `find_recipe(package="@reformer/ui-kit", topic="form-field-integration")`.
 
-Архитектура M1: сначала создаётся **модель данных** (`createModel`), затем **форма**
-(`createForm({ model, schema })`), где схема привязывает поля к сигналам модели
-(`model.$.field`). Layout-схема НЕ несёт валидаторов — валидация живёт в отдельной
-схеме `defineValidationSchema` из `@reformer/core/validation` и запускается внешним
-раннером `validateModel(model, schema)`.
+**Модель данных** — источник истины значений. Схема — дерево узлов, привязанных к ручкам модели
+(`model: model.$.field`). Сборка идёт ОДНИМ вызовом `createForm`: он создаёт модель, строит форму,
+запускает поведение и собирает уровень формы — проверку и отправку. Правил в схеме нет — они
+живут в отдельной схеме `defineValidation` из `@reformer/core/validation` и уходят в сборку полем
+`validation`; запускает их `bundle.submission.submit(handler)` / `bundle.validate()`. Текста у
+правил нет: правило несёт код, строку по коду даёт словарь формы (`defineIssueMessages`).
 
 ```typescript
-import { createModel, createForm, type FormProxy } from '@reformer/core';
-import { defineValidationSchema, validate, validateModel } from '@reformer/core/validation';
+import { createForm, type FormModel, type FormGroup, type FormSchemaNode } from '@reformer/core';
+import { useFormBundle } from '@reformer/core/react';
+import { defineIssueMessages } from '@reformer/core/i18n';
+import { defineValidation, validate } from '@reformer/core/validation';
 import { required, email } from '@reformer/core/validators';
+import { ValidationMessagesProvider } from '@reformer/cdk';
 import { FormField, Input, Button } from '@reformer/ui-kit';
 
-// 1. Define form type as `type` alias (not `interface` — see Recipe 2)
-type ContactForm = {
+// 1. Form data type — `interface` or `type`, both work
+interface ContactForm {
   name: string;
   email: string;
-};
+}
 
-// 2. Model (источник истины значений)
-const model = createModel<ContactForm>({ name: '', email: '' });
-
-// 3. Layout-schema: привязка поля к сигналу (model.$.field) + component/componentProps.
-//    БЕЗ validators — валидация в отдельной схеме (шаг 4).
-const schema = {
-  name: {
-    value: model.$.name,
-    component: Input,
-    componentProps: { label: 'Name', placeholder: 'Your name' },
-  },
-  email: {
-    value: model.$.email,
-    component: Input,
-    componentProps: { label: 'Email', type: 'email' },
-  },
-};
+// 2. Схема — билдер (model) => дерево узлов. Узел поля: привязка `model` + component/componentProps.
+//    Вложенные узлы лежат в `children`. Правил здесь нет — они в отдельной схеме (шаг 3).
+const contactSchema = (model: FormModel<ContactForm>): FormSchemaNode => ({
+  children: [
+    {
+      model: model.$.name,
+      component: Input,
+      componentProps: { label: 'Name', placeholder: 'Your name' },
+    },
+    {
+      model: model.$.email,
+      component: Input,
+      componentProps: { label: 'Email', type: 'email' },
+    },
+  ],
+});
+
+// 3. Схема валидации — отдельный слой (@reformer/core/validation). Правило несёт код, не текст.
+const contactValidation = defineValidation<ContactForm>(({ model }) => {
+  validate(model.$.name, [required({ code: 'name.required' })]);
+  validate(model.$.email, [required({ code: 'email.required' }), email()]);
+});
 
-// 4. Validation-schema — отдельный слой (@reformer/core/validation)
-const contactValidation = defineValidationSchema<ContactForm>(({ model }) => {
-  validate(model.$.name, [required({ message: 'Name is required' })]);
-  validate(model.$.email, [required({ message: 'Email is required' }), email({ message: 'Invalid email' })]);
+// 4. Тексты замечаний по кодам — словарь формы (встроенный код `email` берёт текст из локали)
+const contactMessages = defineIssueMessages({
+  'name.required': 'Укажите имя',
+  'email.required': 'Укажите email',
 });
 
-// 5. Form — ноды поверх сигналов модели
-const form = createForm<ContactForm>({ model, schema });
+// 5. Сборка ОДНИМ вызовом: модель из initial + ноды поверх её сигналов + уровень формы.
+const createContactForm = () =>
+  createForm<ContactForm>({
+    initial: { name: '', email: '' },
+    schema: contactSchema,
+    validation: contactValidation,
+  });
 
 // 6. Use in React component — thin JSX, FormField does ALL heavy lifting
 function ContactFormComponent() {
-  const handleSubmit = async (e: React.FormEvent) => {
-    e.preventDefault();
-    // form.submit()/validate() НЕ гоняют schema-валидацию — только внешний validateModel
-    const ok = await validateModel(model, contactValidation); // Promise<boolean>, ошибки сам роутит в ноды
-    if (ok) {
-      console.log('Form submitted:', model.get());
-    }
+  // useFormBundle зовёт фабрику ровно один раз и держит сборку стабильной между рендерами.
+  const contact = useFormBundle(createContactForm);
+  const { form } = contact;
+
+  const handleSubmit = async (event: React.FormEvent) => {
+    event.preventDefault();
+    // Один прогон всех правил: при замечаниях обработчик не вызывается, а вся форма помечается
+    // тронутой — FormField покажет замечания.
+    const outcome = await contact.submission.submit((values) => api.send(values));
+    if (outcome.status === 'submitted') console.log('Form submitted');
   };
 
   return (
-    <form onSubmit={handleSubmit}>
-      <FormField control={form.name} testId="name" />
-      <FormField control={form.email} testId="email" />
-      <Button type="submit">Send</Button>
-    </form>
+    <ValidationMessagesProvider messages={contactMessages}>
+      <form onSubmit={handleSubmit}>
+        <FormField control={form.name} testId="name" />
+        <FormField control={form.email} testId="email" />
+        <Button type="submit">Send</Button>
+      </form>
+    </ValidationMessagesProvider>
   );
 }
 
 // 7. Pass form to child components via props (NOT context!)
 type FormStepProps = {
-  form: FormProxy<ContactForm>;
+  form: FormGroup<ContactForm>;
 };
 
 function FormStep({ form }: FormStepProps) {
@@ -82,16 +101,27 @@ function FormStep({ form }: FormStepProps) {
 }
 ```
 
-> **Стабильность инстанса.** В React создавай model/schema/form ОДИН раз через `useMemo(() => { … }, [])`
-> — иначе форма пересоздаётся на каждый рендер. См. `28-submit-and-reset.md`, `29-async-preload.md`.
+> **Стабильность сборки.** Форму создают ОДИН раз: в React — `useFormBundle(фабрика)`, вне React —
+> константой модуля. Иначе форма пересоздаётся на каждый рендер. См. `28-submit-and-reset.md`,
+> `29-async-preload.md`.
 
-### Arrays of objects — `{ array, item }` schema node
+> **Проверка и отправка — уровень формы.** Отправка — отдельный объект сборки:
+> `bundle.submission.submit(handler)` прогоняет все правила один раз и зовёт обработчик только при
+> статусе `valid`; результат — `SubmitResult` (`submitted` / `invalid` / `error` / `cancelled` /
+> `failed`). `bundle.validate()` проверяет всю форму и отвечает `ValidationResult`. У нод методов
+> `validate()` / `submit()` нет. Многошаговая форма — `createForm({ flow: { steps: [{ id, rules }] } })`,
+> см. `38-form-flow.md`. Вне React сборку снимают `bundle.dispose()`, когда форма больше не нужна.
 
-Массивы объектов принадлежат модели (`model.arrayField`). В схеме объявляются узлом
-`{ array: model.<path>, item: (itemModel) => itemSchema }`, где `item` строит под-схему
-для каждого элемента из его под-модели (`FormModel<Item>`):
+### Arrays of objects — узел `{ model, item }`
+
+Массивы объектов принадлежат модели (`model.arrayField`). В схеме массив под-форм объявляется узлом
+`{ model: model.$.<path>, item: (itemModel) => узел }`, где `item` строит разметку одной строки из
+её под-модели (`FormModel<Item>`):
 
 ```typescript
+import { arrayOf, createForm, type FormModel, type FormSchemaNode } from '@reformer/core';
+import { FieldArray, InputNumber, SelectAsync, Textarea } from '@reformer/ui-kit';
+
 type PropertyItem = {
   type: 'apartment' | 'house';
   description: string;
@@ -100,33 +130,41 @@ type PropertyItem = {
 
 type MyForm = { properties: PropertyItem[] };
 
-const model = createModel<MyForm>({ properties: [] });
-
-// под-схема одного элемента: item.$.field — сигнал под-модели элемента
-const propertyItem = (item: FormModel<PropertyItem>) => ({
-  type: {
-    value: item.$.type,
-    component: Select,
-    componentProps: { label: 'Тип', options: [/* ... */] },
-  },
-  description: { value: item.$.description, component: Textarea, componentProps: { label: 'Описание' } },
-  estimatedValue: {
-    value: item.$.estimatedValue,
-    component: Input,
-    componentProps: { label: 'Стоимость', type: 'number' },
-  },
+// шаблон новой строки — его кладёт `push()` без значения и кнопка «Добавить»
+const blankProperty = (): PropertyItem => ({ type: 'apartment', description: '', estimatedValue: 0 });
+
+// разметка одной строки: item.$.field — ручка под-модели строки
+const propertyRow = (item: FormModel<PropertyItem>): FormSchemaNode => ({
+  children: [
+    {
+      model: item.$.type,
+      component: SelectAsync,
+      componentProps: { label: 'Тип', options: [/* ... */] },
+    },
+    { model: item.$.description, component: Textarea, componentProps: { label: 'Описание' } },
+    {
+      model: item.$.estimatedValue,
+      component: InputNumber,
+      componentProps: { label: 'Стоимость' },
+    },
+  ],
 });
 
-const schema = {
-  properties: { array: model.properties, item: propertyItem },
-};
-
-const form = createForm<MyForm>({ model, schema });
+const { model, form } = createForm<MyForm>({
+  initial: { properties: arrayOf(blankProperty) },
+  schema: (model) => ({
+    children: [{ model: model.$.properties, component: FieldArray, item: propertyRow }],
+  }),
+});
 
 // Операции над массивом — на модели:
-model.properties.push({ type: 'apartment', description: '', estimatedValue: 0 });
+model.properties.push(); // новая строка по шаблону
+model.properties.push({ type: 'house', description: '', estimatedValue: 0 });
 model.properties.removeAt(0);
 model.properties.length; // реактивная длина
+form.properties.at(0); // форма строки (FormGroup<PropertyItem>)
+form.properties.length; // число строк (число, не сигнал)
+form.properties.keyAt(0); // стабильный ключ строки — для React `key`
 ```
 
 Подробнее в `10-arrays.md`, `21-array-operations.md` и `find_recipe(topic="form-array")`.