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

package/docs/llms/33-validation-strategy.md

@@ -4,29 +4,52 @@
 
 Одна декларативная точка выбора «когда прогонять схему валидации» вместо ручной разводки
 `markAsTouched` + `validateModel` + `revalidateWhen` + `useState(pending)`. Аддитивный слой над
-функциональной схемой (`@reformer/core/validation`): переиспользует `validateModel` как
-ЕДИНСТВЕННЫЙ движок (роутинг ошибок в ноды, отмена устаревших прогонов, дедуп по `(model, schema)`),
-второго движка не заводит. Node-level `updateOn` / `debounce` на самой ноде поля (legacy-триггеры)
-этот API НЕ трогает.
+функциональной схемой (`@reformer/core/validation`): переиспользует раннер схемы как
+ЕДИНСТВЕННЫЙ движок (разнос ошибок по нодам, отмена устаревших прогонов, дедуп по `(model, schema)`),
+второго движка не заводит. Других триггеров валидации нет: у ноды поля собственных валидаторов,
+`updateOn` и `debounce` не бывает — когда запускать проверку, решает только стратегия.
 
 Стратегия определяет только момент запуска и раскрытие ошибок — сами правила остаются в отдельной
-`defineValidationSchema<T>(({ model }) => …)`.
+`defineValidation<T>(({ model }) => …)`.
 
 ## API
 
-Основной способ — React-хук `useFormValidation` из `@reformer/core` (рядом с `useFormControl`).
-Под ним — headless-фабрика `createFormValidation` из `@reformer/core/validation` (для SSR / тестов /
-не-React потребителей).
+Три точки входа к одному контроллеру:
+
+- **сборка `createForm`** — `validation: { rules?, extras?, strategy, debounce, liveAfterSubmit }`.
+  Контроллер собирает уровень формы, армирует `useFormBundle` (в эффекте, не при SSR);
+  `bundle.validate()` и `bundle.submission.submit(handler)` — полный прогон с раскрытием замечаний.
+  Это путь по умолчанию для формы со сборкой;
+- **React-хук `useFormValidation`** из `@reformer/core/react` — для формы без сборки
+  (`createFormFromModel` + своя схема);
+- **headless-фабрика `createFormValidation`** из `@reformer/core/validation` — для SSR / тестов /
+  не-React потребителей.
 
 ```typescript
-// React (@reformer/core)
+// Сборка (@reformer/core)
+createForm<T>({
+  …,
+  validation: {
+    rules?: ValidationDefinition<T>;       // полный набор; без него — правила шагов flow + extras
+    extras?: ValidationDefinition<T>;
+    strategy?: ValidationStrategyKind;     // default 'submit'
+    debounce?: number;
+    liveAfterSubmit?: 'change' | 'blur';
+  },
+});
+
+// React (@reformer/core/react)
 function useFormValidation<T>(args: {
   model: FormModel<T>;
-  schema: ValidationSchema<T>;         // СТАБИЛЬНАЯ ссылка (module-level const / useMemo)
+  schema: ValidationDefinition<T>;         // СТАБИЛЬНАЯ ссылка (module-level const / useMemo)
   strategy?: ValidationStrategyKind;   // default 'submit'
   debounce?: number;                   // мс, для live-фаз (change / live-часть afterFirstSubmit)
   liveAfterSubmit?: 'change' | 'blur'; // default 'change'
-}): { submit: () => Promise<boolean>; validate: () => Promise<boolean>; isValidating: boolean };
+}): {
+  submit: () => Promise<boolean>;   // попытка отправки: при отказе раскрыта вся форма, afterFirstSubmit → живая фаза
+  validate: () => Promise<boolean>; // проверка без отправки: раскрыты проверенные поля, фаза не меняется
+  isValidating: boolean;
+};
 
 // headless (@reformer/core/validation)
 type ValidationStrategyKind = 'submit' | 'blur' | 'change' | 'afterFirstSubmit';
@@ -35,51 +58,101 @@ interface ValidationStrategyOptions {
   debounce?: number;
   liveAfterSubmit?: 'change' | 'blur';
 }
+interface FormValidationRunOptions {
+  touch?: true | 'all'; // true (default) — проверенные поля; 'all' — при отказе ещё и вся форма
+  submit?: boolean;     // прогон — попытка отправки: afterFirstSubmit → живая фаза
+}
 interface FormValidationController {
-  validate(): Promise<boolean>;        // полный прогон, touch:true (раскрыть ВСЕ ошибки); переводит afterFirstSubmit в live-фазу
+  validate(): Promise<boolean>;        // нейтральная проверка: touch:true, фазу afterFirstSubmit не трогает; true — только valid
+  run(options?: FormValidationRunOptions): Promise<ValidationResult>; // valid | invalid | error | cancelled
   start(): () => void;                 // армит реактивные подписки (ТОЛЬКО на клиенте) → dispose
-  dispose(): void;
+  dispose(): void;                     // снять подписки и таймеры, отменить идущий прогон (он получит cancelled)
   readonly isValidating: boolean;
   readonly validating: ReadonlySignal<boolean>;
 }
 function createFormValidation<T>(
   model: FormModel<T>,
-  schema: ValidationSchema<T>,
+  schema: ValidationDefinition<T>,
   options?: ValidationStrategyOptions,
 ): FormValidationController;
 ```
 
-- `useFormValidation` мемоизирует контроллер по `[model, schema, strategy, debounce, liveAfterSubmit]`,
-  армит стратегию в `useEffect` (SSR-safe), а `submit()` = `controller.validate()`.
+- `useFormValidation` мемоизирует контроллер по
+  `[model, schema, strategy, debounce, liveAfterSubmit]` и армит стратегию в `useEffect`
+  (SSR-safe). `submit()` = `controller.run({ touch: 'all', submit: true })`, `validate()` =
+  `controller.validate()`; обе — стабильные ссылки, отвечают `true` только при `valid`.
 - `createFormValidation` ЧИСТА до `start()` (никаких подписок) → SSR-safe; `start()` возвращает
   `dispose` и арминует триггеры только на клиенте.
 
+### Живая фаза `afterFirstSubmit` — одно правило
+
+Живую фазу включает **только попытка отправки**:
+
+| Вызов                                                           | Попытка отправки | Касание при отказе |
+| --------------------------------------------------------------- | ---------------- | ------------------ |
+| `bundle.submission.submit(handler)`                             | да               | вся форма          |
+| `submit()` хука `useFormValidation`                             | да               | вся форма          |
+| `controller.run({ touch: 'all', submit: true })`                | да               | вся форма          |
+| `bundle.validate()`, `validate()` хука, `controller.validate()` | нет              | проверенные поля   |
+| `bundle.validateStep(id)`, `flow.next()`                        | нет              | поля шага          |
+
+Кнопка «Проверить» — `validate()`: показывает замечания, но форма остаётся в тихой фазе. Отменённая
+отправка (`cancelled`) форму тронутой не помечает.
+
 ### Стратегии
 
-| strategy | когда прогон | touch | раскрытие ошибок |
-| --- | --- | --- | --- |
-| `submit` (default) | только `validate()` / `submit()` | `true` | всё на submit |
-| `blur` | смена `touched` поля (потеря фокуса) | `false` | только сблюренные (по `touched`) |
-| `change` | на каждый ввод (+ `debounce`) | `false` | только редактированные (по `dirty`) |
-| `afterFirstSubmit` | тихо до 1-го submit, затем live (`liveAfterSubmit: 'change'` \| `'blur'`, default `'change'`) | `true` один раз на 1-м submit, дальше `false` | тихо → раскрыть всё на submit → далее live |
+| strategy           | когда прогон                                                                                                                                | touch                                                        | раскрытие замечаний                          |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | -------------------------------------------- |
+| `submit` (default) | только `validate()` / `submit()` (в сборке — `bundle.validate()` / `bundle.submission.submit()`)                                            | `true`                                                       | всё на submit                                |
+| `blur`             | каждый уход из поля (потеря фокуса), и повторный тоже                                                                                       | `false`                                                      | только сблюренные (по `touched`)             |
+| `change`           | на каждый ввод (+ `debounce`)                                                                                                               | `false`                                                      | только редактированные (по `dirty`)          |
+| `afterFirstSubmit` | тихо до первой попытки отправки, затем live (`liveAfterSubmit: 'change'` \| `'blur'`, default `'change'`); `validate()` фазу не переключает | при отправке — вся форма (при отказе), дальше live — `false` | тихо → раскрыть всё на отправке → далее live |
 
 ## Examples
 
-### Простая форма — afterFirstSubmit + debounce
+### Сборка — стратегия полем `validation`
+
+```tsx
+import { createForm } from '@reformer/core';
+import { useFormBundle } from '@reformer/core/react';
+
+const createRegistration = () =>
+  createForm<RegistrationData>({
+    initial: { username: '', email: '', password: '' },
+    schema: registrationSchema,
+    validation: { rules: registrationValidation, strategy: 'afterFirstSubmit', debounce: 400 },
+  });
+
+function RegistrationForm() {
+  const registration = useFormBundle(createRegistration); // армирует живую стратегию в эффекте
+  const onSubmit = async (event: React.FormEvent) => {
+    event.preventDefault();
+    // первая отправка раскрывает все замечания и переводит форму в живую фазу;
+    // registration.validate() фазу не переключает
+    await registration.submission.submit(api.save);
+  };
+  /* … */
+}
+```
+
+### Без сборки — useFormValidation, afterFirstSubmit + debounce
 
-Тихо до первой отправки, `submit()` раскрывает все ошибки и переводит форму в живую фазу
-(дальше проверка на ввод с задержкой 400 мс). `submit()` сам метит `touched` — ручной
-`markAsTouched` не нужен.
+Тихо до первой отправки, `submit()` раскрывает все замечания и переводит форму в живую фазу
+(дальше проверка на ввод с задержкой 400 мс). `submit()` сам метит `touched` (при отказе — всю
+форму) — ручной `markAsTouched` не нужен. `validate()` — кнопка «Проверить»: раскрывает замечания
+проверенных полей, а форма остаётся в тихой фазе.
 
 ```tsx
-import { createModel, createForm, useFormValidation } from '@reformer/core';
-import { defineValidationSchema, validate } from '@reformer/core/validation';
+import { useMemo } from 'react';
+import { createModel, createFormFromModel } from '@reformer/core';
+import { useFormValidation } from '@reformer/core/react';
+import { defineValidation, validate } from '@reformer/core/validation';
 import { required, email, minLength } from '@reformer/core/validators';
 
 type RegistrationData = { username: string; email: string; password: string };
 
 // Схема — стабильный module-level const (иначе ломается дедуп раннера).
-const registrationValidation = defineValidationSchema<RegistrationData>(({ model }) => {
+const registrationValidation = defineValidation<RegistrationData>(({ model }) => {
   validate(model.$.username, [required(), minLength(3)]);
   validate(model.$.email, [required(), email()]);
   validate(model.$.password, [required(), minLength(8)]);
@@ -87,17 +160,17 @@ const registrationValidation = defineValidationSchema<RegistrationData>(({ model
 
 function RegistrationForm() {
   const model = useMemo(() => createModel<RegistrationData>({ username: '', email: '', password: '' }), []);
-  const form = useMemo(() => createForm({ model }), [model]);
+  const form = useMemo(() => createFormFromModel({ model }), [model]);
 
-  const { submit, isValidating } = useFormValidation({
+  const { submit, validate, isValidating } = useFormValidation({
     model,
     schema: registrationValidation,
     strategy: 'afterFirstSubmit',
     debounce: 400,
   });
 
-  const onSubmit = async (e: React.FormEvent) => {
-    e.preventDefault();
+  const onSubmit = async (event: React.FormEvent) => {
+    event.preventDefault();
     if (await submit()) await api.save(model.get()); // true = нет блокирующих ошибок
   };
 
@@ -106,49 +179,69 @@ function RegistrationForm() {
       <FormField control={form.username} />
       <FormField control={form.email} />
       <FormField control={form.password} />
-      <button type="submit" disabled={isValidating}>Отправить</button>
+      <button type="button" onClick={() => void validate()}>
+        Проверить
+      </button>
+      <button type="submit" disabled={isValidating}>
+        Отправить
+      </button>
     </form>
   );
 }
 ```
 
-### Wizard — live-стратегия внутри активного шага
+### Визард — стратегия формы и проверка шага потоком
 
-`defineSteps(..., { strategy })` задаёт ЖИВУЮ стратегию ВНУТРИ шага; `useWizardStepValidation`
-арминует её под текущий шаг (`currentStep` из `FormWizardContext`) и снимает при смене шага / unmount.
-Per-step gate (`validateStep` на «Далее») и `validateAll` (submit) при этом НЕ меняются — стратегия
-добавляет живой слой ПОВЕРХ них. No-op, если `strategy` не задана / `'submit'` / у шага нет правил.
+Живая стратегия — свойство формы, а не шага: она задаётся полем `validation` сборки и армируется
+`useFormBundle`. Проверку шага делает поток: «Далее» визарда — `flow.next()`, он прогоняет правила
+текущего шага и не пускает дальше при замечаниях. Отправка — `bundle.submission.submit` (все
+шаги + `extras`). Живую фазу `afterFirstSubmit` включает только она: `flow.next()` и
+`validateStep` фазу не переключают.
 
 ```tsx
-import { defineSteps, useWizardStepValidation, FormWizard } from '@reformer/cdk/form-wizard';
-
-const config = defineSteps<'loan' | 'applicant' | 'confirm', CreditForm>(model, {
-  steps: { loan: loanStep, applicant: applicantStep, confirm: null }, // confirm — без правил, ЯВНО
-  extras: crossFieldRules,   // применяются только в validateAll (submit)
-  strategy: 'blur',          // живая валидация полей текущего шага при потере фокуса
-});
+const createCredit = () =>
+  createForm<CreditForm>({
+    model: createCreditModel(),
+    schema: creditSchema,
+    validation: { extras: crossFieldRules, strategy: 'blur' }, // живая проверка при потере фокуса
+    flow: {
+      steps: [
+        { id: 'loan', rules: loanStep },
+        { id: 'applicant', rules: applicantStep },
+        { id: 'confirm' }, // без правил
+      ],
+    },
+  });
 
-function LoanStepBody() {
-  useWizardStepValidation(config); // армит 'blur' под активный шаг, снимает при переходе
-  return <>{/* поля шага */}</>;
+function CreditWizard() {
+  const credit = useFormBundle(createCredit);
+  return (
+    <FormWizard
+      form={credit.form}
+      flow={credit.flow}
+      steps={STEPS}
+      onSubmit={() => void credit.submission.submit(api.save)}
+    />
+  );
 }
-
-<FormWizard form={form} config={config}>
-  <LoanStepBody />
-</FormWizard>;
 ```
 
+Живая фаза прогоняет **полный** набор правил (все шаги + `extras`), а показ замечаний гейтится
+`touched` / `dirty` полей: поля следующих шагов пользователь ещё не трогал — их замечания не видны.
+Прежний per-step механизм (`defineSteps(…, { strategy })` + `useWizardStepValidation`) удалён.
+
 ### Headless / SSR / тесты — createFormValidation
 
 ```typescript
 import { createFormValidation } from '@reformer/core/validation';
 
-const ctrl = createFormValidation(model, registrationValidation, {
+const controller = createFormValidation(model, registrationValidation, {
   strategy: 'afterFirstSubmit',
   debounce: 300,
 });
-const dispose = ctrl.start();        // ТОЛЬКО на клиенте (в React — из useEffect)
-const ok = await ctrl.validate();    // submit → раскрыть все ошибки
+const dispose = controller.start(); // ТОЛЬКО на клиенте (в React — из useEffect)
+const checked = await controller.validate(); // проверка: замечания проверенных полей, фаза тихая
+const sent = await controller.run({ touch: 'all', submit: true }); // попытка отправки → живая фаза
 dispose();
 ```
 
@@ -157,32 +250,50 @@ dispose();
 ```typescript
 // ❌ schema пересоздаётся каждый рендер → контроллер и дедуп раннера ломаются
 function MyForm() {
-  const schema = defineValidationSchema<Form>(({ model }) => { … }); // новая ссылка на каждый рендер
+  const schema = defineValidation<Form>(({ model }) => { … }); // новая ссылка на каждый рендер
   useFormValidation({ model, schema, strategy: 'change' });
 }
 
 // ✅ Стабильная ссылка: module-level const (или useMemo с пустыми deps)
-const formValidation = defineValidationSchema<Form>(({ model }) => { … });
+const formValidation = defineValidation<Form>(({ model }) => { … });
 function MyForm() {
   useFormValidation({ model, schema: formValidation, strategy: 'change' });
 }
 ```
 
 ```typescript
-// ❌ Node-level updateOn (Слой B) И активная schema-стратегия на ОДНОМ поле → оба пишут ошибки в ноду → мерцание
-// узел поля: { updateOn: 'blur', … } + useFormValidation({ strategy: 'blur', schema: включает это же поле })
+// ❌ updateOn / debounce / validators в узле схемы — таких ключей у узла нет, сборка их не читает
+// { model: model.$.email, component: Input, updateOn: 'blur', validators: [required()] }
 
-// ✅ Одно поле обслуживает ОДИН слой: либо node-level updateOn, либо schema-стратегия — не оба сразу
+// ✅ Момент запуска — стратегия формы; правила — схема валидации
+// createForm({ …, validation: { rules: formValidation, strategy: 'blur', debounce: 300 } })
+```
+
+```typescript
+// ❌ Своя стратегия поверх сборки: второй контроллер на ту же модель и правила
+const bundle = useFormBundle(() => createForm({ …, validation: rules }));
+useFormValidation({ model: bundle.model, schema: rules, strategy: 'change' });
+
+// ✅ Стратегия — полем validation сборки; армирует useFormBundle
+const bundle = useFormBundle(() => createForm({ …, validation: { rules, strategy: 'change' } }));
 ```
 
 ```typescript
 // ❌ start() на сервере — арминует реактивные подписки при SSR
-const ctrl = createFormValidation(model, schema, { strategy: 'change' });
-ctrl.start(); // на сервере подписок быть не должно
+const controller = createFormValidation(model, schema, { strategy: 'change' });
+controller.start(); // на сервере подписок быть не должно
 
 // ✅ Фабрика чиста до start(); армить только на клиенте (useFormValidation делает это в useEffect)
-const ctrl = createFormValidation(model, schema, { strategy: 'change' });
-if (typeof window !== 'undefined') ctrl.start();
+const controller = createFormValidation(model, schema, { strategy: 'change' });
+if (typeof window !== 'undefined') controller.start();
+```
+
+```typescript
+// ❌ afterFirstSubmit: ждать живой фазы после проверки — validate() фазу не переключает
+await bundle.validate(); // форма в тихой фазе, ввод не перепроверяется
+
+// ✅ Живую фазу включает попытка отправки
+await bundle.submission.submit(api.save); // без сборки — submit() хука useFormValidation
 ```
 
 ## See also
@@ -190,4 +301,5 @@ if (typeof window !== 'undefined') ctrl.start();
 - [28-submit-and-reset.md](./28-submit-and-reset.md) — submit-флоу и `validateModel` (движок под стратегией)
 - [27-revalidate-when.md](./27-revalidate-when.md) — ручные триггеры перевалидации (низкоуровневый примитив)
 - [31-async-validator-debounce.md](./31-async-validator-debounce.md) — async-правила и отмена устаревших прогонов
-- [13-multi-step.md](./13-multi-step.md) — per-step / полная валидация wizard (`validateStep` / `validateAll`)
+- [13-multi-step.md](./13-multi-step.md) — многошаговая форма: поток `flow`, `bundle.validateStep(id)`
+- [38-form-flow.md](./38-form-flow.md) — уровень формы: `validate`, `submission`, поток шагов