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

package/docs/llms/13-multi-step.md

@@ -1,91 +1,162 @@
 ## 12. MULTI-STEP FORM VALIDATION
 
-Каждый шаг — своя `ValidationSchema<Form>` (обычная функция `({ model }) => void`, обёрнутая
-`defineValidationSchema`). Переход к следующему шагу проверяется `validateModel(model, stepSchema)`;
-полный submit — по общей схеме (композиция шагов через `apply(...)`). `validateModel` сам разносит
-ошибки по нодам формы (`getNodeForSignal(sig).setErrors(...)`), поэтому UI подсветит проблемные поля
-текущего шага автоматически. Валидация живёт ОТДЕЛЬНО от layout: сам `RenderNode`/JSON-узел валидаторов
-не несёт — схема инъектируется в рантайме и роутит ошибки по тем же нодам.
+Многошаговая форма — **поток шагов** сборки: `createForm({ flow: { steps: [{ id, rules }] } })`.
+Каждый шаг — идентификатор и своя `ValidationDefinition<Form>` (обычная функция
+`({ model, cross }) => void`, обёрнутая `defineValidation`). Идентификатор шага — `selector` узла
+шага в схеме. Правила вне шагов (межшаговые) — `validation: { extras }`: они проверяются только
+целиком, при отправке. Валидация живёт ОТДЕЛЬНО от схемы формы: узел схемы (TS или JSON) правил не
+несёт.
+
+Сборка отдаёт поток `bundle.flow` (`next` / `previous` / `goTo`), проверку шага
+`bundle.validateStep(id)`, полную проверку `bundle.validate()` и отправку
+`bundle.submission.submit(handler)`. Замечания разносятся по нодам сами — UI подсветит поля
+текущего шага. Полный справочник — [38-form-flow.md](./38-form-flow.md).
+
+### Поток шагов сборки
 
 ```typescript
-import { type FormModel } from '@reformer/core';
-import {
-  validate,
-  apply,
-  defineValidationSchema,
-  validateModel,
-  type ValidationSchema,
-} from '@reformer/core/validation';
-import { required, min } from '@reformer/core/validators';
+import { createForm } from '@reformer/core';
+import { useFormBundle } from '@reformer/core/react';
 
-// Под-схема шага — обычная функция ({ model }) => void. Значения проверяет оператор validate(sig, [rules]).
-const step1Schema = defineValidationSchema<Form>(({ model }) => {
-  validate(model.$.loanType, [required()]);
-  validate(model.$.loanAmount, [required(), min(50000)]);
-});
+const createLoanForm = () =>
+  createForm<Form>({
+    initial,
+    schema: formSchema, // узлы шагов несут selector: 'loan', 'applicant', 'confirm'
+    validation: { extras: crossStepRules }, // правила всей формы — только целиком
+    flow: {
+      steps: [
+        { id: 'loan', rules: loanRules },
+        { id: 'applicant', rules: applicantRules },
+        { id: 'confirm' }, // шаг без правил
+      ],
+    },
+  });
 
-const step2Schema = defineValidationSchema<Form>(({ model }) => {
-  validate(model.$.personalData.firstName, [required()]);
-  validate(model.$.personalData.lastName, [required()]);
-});
+// в компоненте: фабрика вызывается один раз, сборка стабильна между рендерами
+const loan = useFormBundle(createLoanForm);
 
-// Карта шагов + полная схема (композиция под-схем через apply — заменяет пошаговую группировку деревом)
-const STEP_SCHEMAS: readonly ValidationSchema<Form>[] = [step1Schema, step2Schema];
-const fullSchema = defineValidationSchema<Form>(() => apply(...STEP_SCHEMAS));
+// в обработчиках событий
+await loan.flow?.next(); // проверить правила текущего шага и перейти → FlowTransition
+await loan.validateStep('loan'); // правила одного шага → ValidationResult
+await loan.validate(); // все шаги + extras → ValidationResult
+await loan.submission.submit(sendLoan); // один прогон всех правил; обработчик — только при valid
+loan.validating.value; // идёт ли проверка — полная либо шага
 ```
 
-```typescript
-// Переход к следующему шагу. validateModel возвращает Promise<boolean> (true = нет блокирующих ошибок;
-// severity:'warning' не блокирует). Устаревшие прогоны той же (model, schema) отменяются автоматически.
-const goToNextStep = async () => {
-  const ok = await validateModel(model, STEP_SCHEMAS[currentStep - 1]);
-  if (!ok) return; // ошибки уже проставлены в ноды текущего шага
-  setCurrentStep(currentStep + 1);
-};
-
-// Полный submit — по общей схеме
-const handleSubmit = async () => {
-  const ok = await validateModel(model, fullSchema);
-  if (ok) {
-    await onSubmit(model.get());
-  }
-};
-```
+- Полный набор правил — правила всех шагов и `extras`; свой полный набор задаёт
+  `validation: { rules }` (тогда правила шагов работают только для `validateStep` / `next`).
+- `next()` на шаге с замечаниями остаётся на месте: `{ status: 'stayed', reason: 'invalid',
+  validation }`; поля шага помечаются тронутыми. Переход — `{ status: 'moved', from, to }`.
+- Поле правили, пока шла проверка шага (async-правило), — `next()` остаётся на шаге с
+  `reason: 'cancelled'`: правила этого значения не видели. Следующий `next()` проверит новое.
+- Стратегия `afterFirstSubmit` переходит в живую фазу только от отправки
+  (`bundle.submission.submit`): `next()`, `validateStep` и `validate` её не переключают.
+- `goTo(id)` открывает первый шаг и шаги после пройденных; прыжок вперёд через непройденный шаг —
+  `reason: 'locked'`. Назад — всегда.
+- В dev сборка предупреждает о шаге `flow.steps`, для которого в схеме нет узла с таким `selector`.
+- Правила (`loanRules`, `extras`) — стабильные ссылки: константы модуля через `defineValidation`.
 
-Слой-потребитель (`FormWizard`) обычно оборачивает это в конфиг с per-step и полной валидацией:
+В большой форме шаг объявляют один раз — в списке шагов (`flow/`): из него строятся и узлы шагов
+схемы, и `flow.steps` сборки. См. `15-project-structure.md`.
 
-```typescript
-function makeValidationConfig(model: FormModel<Form>) {
-  return {
-    validateStep: (n: number): Promise<boolean> => validateModel(model, STEP_SCHEMAS[n - 1]),
-    validateAll: (): Promise<boolean> => validateModel(model, fullSchema),
+### Визард — адаптер потока
+
+`FormWizard` из `@reformer/cdk` и `@reformer/ui-kit` рисует поток и зовёт его переходы:
+
+```tsx
+import { FormWizard } from '@reformer/ui-kit';
+
+function LoanWizard() {
+  const loan = useFormBundle(createLoanForm);
+  const send = async () => {
+    const outcome = await loan.submission.submit(sendLoan);
+    if (outcome.status !== 'submitted') showHint('Проверьте форму');
   };
+  return <FormWizard form={loan.form} flow={loan.flow} steps={STEPS} onSubmit={send} />;
 }
 ```
 
-### Multi-Step Component Example
+- В JSX — `form`, `flow={bundle.flow}` и `steps` пропсами; отправку проверяет приложение через
+  `bundle.submission.submit(handler)`.
+- В схеме формы — узел `{ selector: 'wizard', component: FormWizard, children: [шаги] }`, шаг —
+  `{ selector: 'loan', component: Step, componentProps: { title }, children: [...] }`. Внутри
+  рендерера визард берёт форму и поток из сборки сам, а его `onSubmit` зовётся через
+  `bundle.submission.submit` — только после успешной проверки всей формы.
+- Без `flow` и без сборки в контексте визард строит позиционный поток **без правил**.
+- Навигация снаружи визарда — через сам поток: `bundle.flow?.goTo('loan')`; в поведении — `flow` из
+  области (`defineFormBehavior(({ model, flow }) => …)`).
+
+### Шаги без визарда — `useFormFlow`
 
 ```tsx
-function MultiStepForm() {
-  const [step, setStep] = useState(1);
+import { useFormFlow } from '@reformer/core/react';
 
-  const nextStep = async () => {
-    const ok = await validateModel(model, STEP_SCHEMAS[step - 1]);
-    if (ok) setStep(step + 1);
-  };
+function MultiStepForm() {
+  const loan = useFormBundle(createLoanForm);
+  const flow = loan.flow!;
+  const { current, isFirst, isLast, validating } = useFormFlow(flow);
 
   return (
     <div>
-      {step === 1 && <Step1Fields form={form} />}
-      {step === 2 && <Step2Fields form={form} />}
+      {current === 'loan' && <LoanFields form={loan.form} />}
+      {current === 'applicant' && <ApplicantFields form={loan.form} />}
+      {current === 'confirm' && <Summary form={loan.form} />}
 
-      <button onClick={() => setStep(step - 1)} disabled={step === 1}>
+      <button onClick={() => flow.previous()} disabled={isFirst}>
         Back
       </button>
-      <button onClick={step === 2 ? handleSubmit : nextStep}>
-        {step === 2 ? 'Submit' : 'Next'}
-      </button>
+      {isLast ? (
+        <button onClick={() => void loan.submission.submit(sendLoan)}>Submit</button>
+      ) : (
+        <button onClick={() => void flow.next()} disabled={validating}>
+          Next
+        </button>
+      )}
     </div>
   );
 }
 ```
+
+### Без сборки — `validateModel` по схеме шага
+
+Тот же результат без `createForm`: переход проверяется `validateModel(model, stepSchema)`, полный
+submit — по общей схеме (композиция шагов через `apply(...)`).
+
+```typescript
+import {
+  validate,
+  apply,
+  defineValidation,
+  validateModel,
+  type ValidationDefinition,
+} from '@reformer/core/validation';
+import { required, min } from '@reformer/core/validators';
+
+const loanRules = defineValidation<Form>(({ model }) => {
+  validate(model.$.loanType, [required()]);
+  validate(model.$.loanAmount, [required(), min(50000)]);
+});
+
+const applicantRules = defineValidation<Form>(({ model }) => {
+  validate(model.$.personalData.firstName, [required()]);
+  validate(model.$.personalData.lastName, [required()]);
+});
+
+const STEP_RULES: readonly ValidationDefinition<Form>[] = [loanRules, applicantRules];
+const fullRules = defineValidation<Form>(() => apply(...STEP_RULES));
+
+// true = нет блокирующих замечаний (severity:'warning' не блокирует); замечания уже в нодах
+const stepOk = await validateModel(model, STEP_RULES[index], { touch: true });
+const allOk = await validateModel(model, fullRules, { touch: true });
+```
+
+Поток без сборки собирает `createFormFlow({ steps, validateStep })` — см. `38-form-flow.md`.
+
+### Удалено
+
+| Прежний контракт                                         | Сейчас                                                    |
+| -------------------------------------------------------- | --------------------------------------------------------- |
+| `validation: { steps: { loan: rules } }`                 | `flow: { steps: [{ id: 'loan', rules }] }`                |
+| `bundle.validation.validateStep(n)` / `.validateAll()` / `.runStep()` / `.runAll()` | `bundle.validateStep(id)` / `bundle.validate()` |
+| `<FormWizard config={…} ref={…}>`, `FormWizardConfig`, `FormWizardHandle` | `<FormWizard flow={bundle.flow}>`, навигация — `bundle.flow` |
+| `defineSteps`, `useWizardStepValidation`                 | `flow` сборки; живая проверка — `validation.strategy`     |

package/docs/llms/14-extended-mistakes.md

@@ -58,41 +58,44 @@ compute(model.$.b, () => model.a + 1); // расходится → Cycle detecte
 compute(model.$.total, () => model.price * model.qty); // одно направление
 ```
 
-### Cross-field валидация — через `cross(sig, fn)`
+### Cross-field валидация — через `cross` области схемы
 
-Cross-field живёт в схеме валидации (`@reformer/core/validation`), а не в layout: правило вешается на
-ПОЛЕ-НОСИТЕЛЬ ошибки оператором `cross(sig, fn)`, а `fn` читает снапшот текущего scope (`model.get()`).
+Cross-field живёт в схеме валидации (`@reformer/core/validation`), а не в схеме формы: правило
+вешается на ПОЛЕ-НОСИТЕЛЬ ошибки оператором `cross(sig, check)` из аргумента схемы, а `check`
+получает снимок модели области.
 
 ```typescript
-import { defineValidationSchema, validate, cross, validateModel } from '@reformer/core/validation';
+import { defineValidation, validate, validateModel } from '@reformer/core/validation';
 import { required } from '@reformer/core/validators';
-import { revalidateWhen, type ValidationError } from '@reformer/core';
+import { type ValidationIssue } from '@reformer/core';
+import { revalidateWhen } from '@reformer/core/model';
 
 // ❌ старое (УДАЛЕНО): дерево { value, validators }, ModelValidator (value, scope, root), validateFormModel
 const legacyRule: ModelValidator<number, unknown, Form> = (_value, _scope, root) =>
-  root.field1 > root.field2 ? { code: 'error', message: 'Invalid' } : null;
+  root.field1 > root.field2 ? { code: 'error' } : null;
 const legacySchema = { field1: { value: model.$.field1, component: Input, validators: [legacyRule] } };
 validateFormModel(model, legacySchema);
 
-// ✅ новое: cross-правило — обычная функция над снапшотом (model.get()), не читает scope/root
-const field1LessThanField2 = (f: Form): ValidationError | null =>
-  f.field1 > f.field2 ? { code: 'error', message: 'Invalid' } : null;
+// ✅ новое: cross-правило — обычная функция над снимком модели
+const field1LessThanField2 = (form: Form): ValidationIssue | null =>
+  form.field1 > form.field2 ? { code: 'field1.notLess' } : null;
 
-const schema = defineValidationSchema<Form>(({ model }) => {
+const schema = defineValidation<Form>(({ model, cross }) => {
   validate(model.$.field1, [required()]);
-  cross(model.$.field1, field1LessThanField2); // правило на поле-носителе ошибки
+  cross(model.$.field1, field1LessThanField2); // правило на поле-носителе замечания
 });
 
-// Прогон — ТОЛЬКО внешним раннером; ошибки сами доезжают до нод формы.
-// ⚠️ form.validate()/submit() схему валидации больше НЕ прогоняют.
+// Прогон — уровнем формы (createForm({ …, validation: schema })): bundle.validate() /
+// bundle.submission.submit(handler); без сборки — раннер. Замечания сами доезжают до нод формы.
 await validateModel(model, schema);
 
 // Перезапуск правила при изменении соседнего поля — мост «поведение → валидация»:
 revalidateWhen([model.$.field2], () => void validateModel(model, schema));
 ```
 
-> **Актуальный vs удалённый API.** Операторы валидации `validate`/`validateAsync`/`validateWhen`/`cross`/`each`/`apply`
-> ТЕПЕРЬ существуют — в `@reformer/core/validation` с новыми сигнатурами (ambient, активны только внутри прогона
-> `validateModel`). УДАЛЕНЫ: `applyWhen`, `validateGroup`/`validateTree`/`validateForm`/`validateFormModel`,
+> **Актуальный vs удалённый API.** Операторы валидации `validate`/`validateAsync`/`validateWhen`/`apply`/`applyEach`
+> существуют — в `@reformer/core/validation` (активны только внутри прогона схемы); `cross` — в аргументе
+> схемы. УДАЛЕНЫ: `applyWhen`, `validateGroup`/`validateTree`/`validateForm`/`validateFormModel`,
 > типы `FieldPath`/`ValidationSchemaFn`/`BehaviorSchemaFn` и `ctx.form.*`/`ctx.setFieldValue` (наследие
-> path-based архитектуры). См. `17-nonexistent-api.md`.
+> path-based архитектуры), а также текст в правиле (`message`), методы проверки на нодах
+> (`form.validate()` / `form.submit()`) и `validation.steps` сборки. См. `17-nonexistent-api.md`.