@reformer/core 10.2.0 → 11.0.0-beta.10

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

@@ -0,0 +1,89 @@
+## 1. API Reference
+
+### Imports (CRITICALLY IMPORTANT)
+
+Значения живут в **модели** (`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: 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`
+- Форму данных объявляй через `interface` или `type` — оба варианта работают, см.
+  `30-type-safety-recipes.md`
+
+### React Hooks Comparison (CRITICALLY IMPORTANT)
+
+| Hook | Return Type | Subscribes To | Use Case |
+|------|-------------|---------------|----------|
+| `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 }`.
+
+```typescript
+// WRONG - will always be undefined!
+const { value: loanType } = useFormControlValue(control.loanType);
+
+// CORRECT
+const loanType = useFormControlValue(control.loanType);
+
+// CORRECT - useFormControl returns object, destructuring OK
+const { value, issues, disabled } = useFormControl(control.loanType);
+```

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

@@ -0,0 +1,181 @@
+## 1.5 QUICK START - Minimal Working Form
+
+> **Schema-driven UI rule (read first)**: компонент И его пропсы (label, placeholder,
+> 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")`.
+
+**Модель данных** — источник истины значений. Схема — дерево узлов, привязанных к ручкам модели
+(`model: model.$.field`). Сборка идёт ОДНИМ вызовом `createForm`: он создаёт модель, строит форму,
+запускает поведение и собирает уровень формы — проверку и отправку. Правил в схеме нет — они
+живут в отдельной схеме `defineValidation` из `@reformer/core/validation` и уходят в сборку полем
+`validation`; запускает их `bundle.submission.submit(handler)` / `bundle.validate()`. Текста у
+правил нет: правило несёт код, строку по коду даёт словарь формы (`defineIssueMessages`).
+
+```typescript
+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. Form data type — `interface` or `type`, both work
+interface ContactForm {
+  name: string;
+  email: string;
+}
+
+// 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. Тексты замечаний по кодам — словарь формы (встроенный код `email` берёт текст из локали)
+const contactMessages = defineIssueMessages({
+  'name.required': 'Укажите имя',
+  'email.required': 'Укажите email',
+});
+
+// 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() {
+  // 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 (
+    <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: FormGroup<ContactForm>;
+};
+
+function FormStep({ form }: FormStepProps) {
+  return <FormField control={form.name} testId="name" />;
+}
+```
+
+> **Стабильность сборки.** Форму создают ОДИН раз: в React — `useFormBundle(фабрика)`, вне React —
+> константой модуля. Иначе форма пересоздаётся на каждый рендер. См. `28-submit-and-reset.md`,
+> `29-async-preload.md`.
+
+> **Проверка и отправка — уровень формы.** Отправка — отдельный объект сборки:
+> `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()`, когда форма больше не нужна.
+
+### 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;
+  estimatedValue: number;
+};
+
+type MyForm = { properties: PropertyItem[] };
+
+// шаблон новой строки — его кладёт `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 { model, form } = createForm<MyForm>({
+  initial: { properties: arrayOf(blankProperty) },
+  schema: (model) => ({
+    children: [{ model: model.$.properties, component: FieldArray, item: propertyRow }],
+  }),
+});
+
+// Операции над массивом — на модели:
+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")`.
+
+### When to write your own field components (advanced — rare)
+
+Свои компоненты нужны ТОЛЬКО если:
+
+- ты намеренно избегаешь `@reformer/ui-kit` (например, проект уже имеет свою design system)
+- нужен особый низкоуровневый input, который не покрывается `FormField` + `componentProps`
+
+В этом случае см. секцию `## 14.5 UI COMPONENT PATTERNS` ниже — но даже там
+паттерн **schema-driven** (label/options не из JSX-props, а из `componentProps` через
+`useFormControl(...).componentProps`).