@reformer/core 10.2.0 → 11.0.0-beta.10

package/docs/llms/32-async-options-loading.md

@@ -0,0 +1,108 @@
+## 32. ASYNC OPTIONS LOADING
+
+Для динамической подгрузки опций dropdown'а по значению другого поля (`region` → `city options`,
+`carBrand` → `carModel options`) — используй `onChange` из `@reformer/core/behaviors` +
+`form.field.updateComponentProps({ options })`. `onChange` даёт debounce и AbortSignal из коробки.
+
+```ts
+import { defineFormBehavior, onChange } from '@reformer/core/behaviors';
+
+type CityOption = { value: string; label: string };
+
+async function fetchCitiesByRegion(region: string, opts?: { signal?: AbortSignal }): Promise<CityOption[]> {
+  const res = await fetch(`/api/cities?region=${encodeURIComponent(region)}`, { signal: opts?.signal });
+  return res.json();
+}
+
+export const behavior = defineFormBehavior<MyForm>(({ model, form }) => {
+  onChange(
+    model.$.registrationAddress.region,
+    async (region, { signal }) => {
+      // сбросить зависимое поле при смене source
+      model.registrationAddress.city = '';
+
+      if (!region) {
+        form.registrationAddress.city.updateComponentProps({ options: [] });
+        return;
+      }
+
+      // (опционально) loading-состояние
+      form.registrationAddress.city.updateComponentProps({ loading: true, options: [] });
+
+      try {
+        const options = await fetchCitiesByRegion(region, { signal }); // отмена устаревших
+        form.registrationAddress.city.updateComponentProps({ loading: false, options });
+      } catch (e) {
+        if ((e as Error).name === 'AbortError') return; // устаревший запрос — молча выходим
+        form.registrationAddress.city.updateComponentProps({ loading: false, options: [] });
+      }
+    },
+    { debounce: 300 }
+  );
+});
+```
+
+### Lifecycle
+
+1. `onChange` подписан на изменения `model.$.region`.
+2. Debounce 300 мс (не fetch на каждое нажатие клавиши).
+3. Async `fetchCitiesByRegion(region, { signal })` — `signal` отменяет устаревший запрос при
+   следующей смене значения (защита от race).
+4. Результат — `updateComponentProps({ options })` на target-поле.
+5. UI (Select / Combobox) обновляется через сигнал `componentProps`.
+
+### Переиспользуемый оператор
+
+Как в монорепо — собираешь свой оператор поверх `onChange`:
+
+```ts
+import { onChange } from '@reformer/core/behaviors';
+import type { ReadonlySignal } from '@reformer/core/behaviors';
+
+function loadOptionsOn<TValue, TOption>(
+  source: ReadonlySignal<TValue>,
+  target: { updateComponentProps(p: Record<string, unknown>): void; reset?: () => void },
+  fetcher: (value: TValue, opts?: { signal?: AbortSignal }) => Promise<TOption[]>,
+  options: { debounce?: number; resetTarget?: boolean } = {}
+): void {
+  const { debounce = 300, resetTarget = false } = options;
+  onChange(
+    source,
+    async (value, { signal }) => {
+      if (resetTarget) target.reset?.();
+      if (!value) { target.updateComponentProps({ options: [] }); return; }
+      try {
+        const data = await fetcher(value, { signal });
+        target.updateComponentProps({ options: data });
+      } catch {
+        target.updateComponentProps({ options: [] });
+      }
+    },
+    { debounce }
+  );
+}
+
+// Usage:
+loadOptionsOn(model.$.carBrand, form.carModel, fetchCarModels, { resetTarget: true });
+```
+
+### Common patterns
+
+- **Debounce 300–500 мс** — баланс UX и rate-limit.
+- **Reset target value** — при смене source очисти зависимое поле (`model.city = ''`), чтобы не
+  остался устаревший выбор.
+- **Loading state** — `updateComponentProps({ loading: true })` пока идёт fetch (компонент должен поддержать).
+- **Cancellation** — `onChange` даёт `{ signal }` (AbortSignal); передавай его в `fetch` и
+  игнорируй `AbortError`.
+
+### Initial load (preload at form mount)
+
+Для загрузки опций при инициализации формы — external hook + `model.set` + `updateComponentProps`
+(см. [29-async-preload.md](29-async-preload.md)). `onChange` не срабатывает на init (по умолчанию
+`immediate: false`); для запуска сразу передай `{ immediate: true }`.
+
+### See also
+
+- [11-async-watchfield.md](11-async-watchfield.md) — общий паттерн `onChange`
+- [29-async-preload.md](29-async-preload.md) — preload данных при инициализации
+- [31-async-validator-debounce.md](31-async-validator-debounce.md) — async **валидация** (не options)

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

@@ -0,0 +1,305 @@
+# useFormValidation — Единый выбор стратегии валидации
+
+## Purpose
+
+Одна декларативная точка выбора «когда прогонять схему валидации» вместо ручной разводки
+`markAsTouched` + `validateModel` + `revalidateWhen` + `useState(pending)`. Аддитивный слой над
+функциональной схемой (`@reformer/core/validation`): переиспользует раннер схемы как
+ЕДИНСТВЕННЫЙ движок (разнос ошибок по нодам, отмена устаревших прогонов, дедуп по `(model, schema)`),
+второго движка не заводит. Других триггеров валидации нет: у ноды поля собственных валидаторов,
+`updateOn` и `debounce` не бывает — когда запускать проверку, решает только стратегия.
+
+Стратегия определяет только момент запуска и раскрытие ошибок — сами правила остаются в отдельной
+`defineValidation<T>(({ model }) => …)`.
+
+## API
+
+Три точки входа к одному контроллеру:
+
+- **сборка `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
+// Сборка (@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: ValidationDefinition<T>;         // СТАБИЛЬНАЯ ссылка (module-level const / useMemo)
+  strategy?: ValidationStrategyKind;   // default 'submit'
+  debounce?: number;                   // мс, для live-фаз (change / live-часть afterFirstSubmit)
+  liveAfterSubmit?: 'change' | 'blur'; // default 'change'
+}): {
+  submit: () => Promise<boolean>;   // попытка отправки: при отказе раскрыта вся форма, afterFirstSubmit → живая фаза
+  validate: () => Promise<boolean>; // проверка без отправки: раскрыты проверенные поля, фаза не меняется
+  isValidating: boolean;
+};
+
+// headless (@reformer/core/validation)
+type ValidationStrategyKind = 'submit' | 'blur' | 'change' | 'afterFirstSubmit';
+interface ValidationStrategyOptions {
+  strategy?: ValidationStrategyKind;
+  debounce?: number;
+  liveAfterSubmit?: 'change' | 'blur';
+}
+interface FormValidationRunOptions {
+  touch?: true | 'all'; // true (default) — проверенные поля; 'all' — при отказе ещё и вся форма
+  submit?: boolean;     // прогон — попытка отправки: afterFirstSubmit → живая фаза
+}
+interface FormValidationController {
+  validate(): Promise<boolean>;        // нейтральная проверка: touch:true, фазу afterFirstSubmit не трогает; true — только valid
+  run(options?: FormValidationRunOptions): Promise<ValidationResult>; // valid | invalid | error | cancelled
+  start(): () => void;                 // армит реактивные подписки (ТОЛЬКО на клиенте) → dispose
+  dispose(): void;                     // снять подписки и таймеры, отменить идущий прогон (он получит cancelled)
+  readonly isValidating: boolean;
+  readonly validating: ReadonlySignal<boolean>;
+}
+function createFormValidation<T>(
+  model: FormModel<T>,
+  schema: ValidationDefinition<T>,
+  options?: ValidationStrategyOptions,
+): FormValidationController;
+```
+
+- `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()` (в сборке — `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
+
+### Сборка — стратегия полем `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` не нужен. `validate()` — кнопка «Проверить»: раскрывает замечания
+проверенных полей, а форма остаётся в тихой фазе.
+
+```tsx
+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 = defineValidation<RegistrationData>(({ model }) => {
+  validate(model.$.username, [required(), minLength(3)]);
+  validate(model.$.email, [required(), email()]);
+  validate(model.$.password, [required(), minLength(8)]);
+});
+
+function RegistrationForm() {
+  const model = useMemo(() => createModel<RegistrationData>({ username: '', email: '', password: '' }), []);
+  const form = useMemo(() => createFormFromModel({ model }), [model]);
+
+  const { submit, validate, isValidating } = useFormValidation({
+    model,
+    schema: registrationValidation,
+    strategy: 'afterFirstSubmit',
+    debounce: 400,
+  });
+
+  const onSubmit = async (event: React.FormEvent) => {
+    event.preventDefault();
+    if (await submit()) await api.save(model.get()); // true = нет блокирующих ошибок
+  };
+
+  return (
+    <form onSubmit={onSubmit}>
+      <FormField control={form.username} />
+      <FormField control={form.email} />
+      <FormField control={form.password} />
+      <button type="button" onClick={() => void validate()}>
+        Проверить
+      </button>
+      <button type="submit" disabled={isValidating}>
+        Отправить
+      </button>
+    </form>
+  );
+}
+```
+
+### Визард — стратегия формы и проверка шага потоком
+
+Живая стратегия — свойство формы, а не шага: она задаётся полем `validation` сборки и армируется
+`useFormBundle`. Проверку шага делает поток: «Далее» визарда — `flow.next()`, он прогоняет правила
+текущего шага и не пускает дальше при замечаниях. Отправка — `bundle.submission.submit` (все
+шаги + `extras`). Живую фазу `afterFirstSubmit` включает только она: `flow.next()` и
+`validateStep` фазу не переключают.
+
+```tsx
+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 CreditWizard() {
+  const credit = useFormBundle(createCredit);
+  return (
+    <FormWizard
+      form={credit.form}
+      flow={credit.flow}
+      steps={STEPS}
+      onSubmit={() => void credit.submission.submit(api.save)}
+    />
+  );
+}
+```
+
+Живая фаза прогоняет **полный** набор правил (все шаги + `extras`), а показ замечаний гейтится
+`touched` / `dirty` полей: поля следующих шагов пользователь ещё не трогал — их замечания не видны.
+Прежний per-step механизм (`defineSteps(…, { strategy })` + `useWizardStepValidation`) удалён.
+
+### Headless / SSR / тесты — createFormValidation
+
+```typescript
+import { createFormValidation } from '@reformer/core/validation';
+
+const controller = createFormValidation(model, registrationValidation, {
+  strategy: 'afterFirstSubmit',
+  debounce: 300,
+});
+const dispose = controller.start(); // ТОЛЬКО на клиенте (в React — из useEffect)
+const checked = await controller.validate(); // проверка: замечания проверенных полей, фаза тихая
+const sent = await controller.run({ touch: 'all', submit: true }); // попытка отправки → живая фаза
+dispose();
+```
+
+## Anti-patterns
+
+```typescript
+// ❌ schema пересоздаётся каждый рендер → контроллер и дедуп раннера ломаются
+function MyForm() {
+  const schema = defineValidation<Form>(({ model }) => { … }); // новая ссылка на каждый рендер
+  useFormValidation({ model, schema, strategy: 'change' });
+}
+
+// ✅ Стабильная ссылка: module-level const (или useMemo с пустыми deps)
+const formValidation = defineValidation<Form>(({ model }) => { … });
+function MyForm() {
+  useFormValidation({ model, schema: formValidation, strategy: 'change' });
+}
+```
+
+```typescript
+// ❌ updateOn / debounce / validators в узле схемы — таких ключей у узла нет, сборка их не читает
+// { model: model.$.email, component: Input, updateOn: 'blur', validators: [required()] }
+
+// ✅ Момент запуска — стратегия формы; правила — схема валидации
+// 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 controller = createFormValidation(model, schema, { strategy: 'change' });
+controller.start(); // на сервере подписок быть не должно
+
+// ✅ Фабрика чиста до start(); армить только на клиенте (useFormValidation делает это в useEffect)
+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
+
+- [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) — многошаговая форма: поток `flow`, `bundle.validateStep(id)`
+- [38-form-flow.md](./38-form-flow.md) — уровень формы: `validate`, `submission`, поток шагов