@reformer/core 10.2.0 → 11.0.0-beta.2

package/docs/llms/27-revalidate-when.md

@@ -0,0 +1,132 @@
+# revalidateWhen — Перевалидация по триггерам
+
+## Purpose
+
+`revalidateWhen` вызывает переданный колбэк ревалидации, когда изменяется любая из
+зависимостей. Применяется, когда правило зависит от значений других полей
+(`amount <= maxAmount`, `confirmPassword === password`, `initialPayment >= propertyValue * 0.2`).
+Валидация — отдельная функция-схема (`@reformer/core/validation`), прогоняемая по требованию через
+`validateModel(model, schema)`. Поэтому ревалидация выражается явным колбэком, а не автоматической
+привязкой к полю: поведение (`revalidateWhen`) лишь _инициирует_ прогон схемы валидации при изменении зависимости.
+
+## API
+
+`revalidateWhen` — оператор поведения (`@reformer/core/behaviors`, либо примитив `@reformer/core`).
+Его сигнатура НЕ зависит от контракта валидации:
+
+```typescript
+// примитив: возвращает cleanup
+function revalidateWhen(deps: ReadonlySignal<unknown>[], revalidate: () => void): () => void;
+
+// DSL: cleanup управляется формой
+function revalidateWhen(deps: ReadonlySignal<unknown>[], revalidate: () => void): void;
+```
+
+`deps` — массив сигналов-триггеров (`model.$.field`). `revalidate` — колбэк (обычно
+`() => void validateModel(model, schema)`, где `schema` — `defineValidationSchema<T>(({ model }) => …)`).
+Вызывается при изменении любой зависимости (НЕ на инициализации), вне effect-контекста.
+
+## Examples
+
+### Базовый сценарий — перевалидация amount при смене maxAmount
+
+```typescript
+import { defineFormBehavior, revalidateWhen } from '@reformer/core/behaviors';
+import { validateModel } from '@reformer/core/validation';
+
+export const paymentBehavior = defineFormBehavior<PaymentForm>(({ model }) => {
+  revalidateWhen([model.$.maxAmount], () => {
+    void validateModel(model, paymentSchema);
+  });
+});
+```
+
+Пример: `revalidateWhen([model.$.maxAmount], () => void validateModel(model, paymentSchema))`.
+Схема `paymentSchema` — стабильный module-level `const` (важно для отмены устаревших прогонов
+в `validateModel`), где правило amount навешано через `cross(model.$.amount, amountVsMax)`.
+
+### Несколько триггеров
+
+```typescript
+import { defineFormBehavior, revalidateWhen } from '@reformer/core/behaviors';
+import { validateModel } from '@reformer/core/validation';
+
+export const mortgageBehavior = defineFormBehavior<MortgageForm>(({ model }) => {
+  // initialPayment зависит и от propertyValue, и от loanAmount
+  revalidateWhen([model.$.propertyValue, model.$.loanAmount], () => {
+    void validateModel(model, mortgageSchema);
+  });
+});
+```
+
+### Парная перевалидация — confirmPassword
+
+```typescript
+import { defineFormBehavior, revalidateWhen } from '@reformer/core/behaviors';
+import { validateModel } from '@reformer/core/validation';
+
+// правило совпадения — cross-field в схеме: cross(model.$.confirmPassword, passwordsMatch),
+// где passwordsMatch читает снапшот формы (см. 03-api-signatures.md)
+export const registrationBehavior = defineFormBehavior<RegistrationForm>(({ model }) => {
+  // при смене password перевалидируем схему (confirm перепроверится)
+  revalidateWhen([model.$.password], () => {
+    void validateModel(model, registrationSchema);
+  });
+});
+```
+
+### Как примитив (вне defineFormBehavior)
+
+```typescript
+import { revalidateWhen } from '@reformer/core';
+import { validateModel } from '@reformer/core/validation';
+
+const stop = revalidateWhen([model.$.maxAmount], () => void validateModel(model, schema));
+```
+
+## Anti-patterns
+
+```typescript
+// ❌ Триггер == поле, которое и так меняется само
+revalidateWhen([model.$.amount], () => validateModel(model, schema));
+// amount и так валидируется при собственном изменении в общем прогоне
+
+// ✅ Триггеры — ДРУГИЕ поля, от которых зависит правило amount
+revalidateWhen([model.$.maxAmount, model.$.discount], () => validateModel(model, schema));
+```
+
+```typescript
+// ❌ Правило только через revalidateWhen, но в схеме нет зависимости от триггера
+revalidateWhen([model.$.maxAmount], () => validateModel(model, schema));
+// а валидатор amount — статичный max(1000), не читает maxAmount
+
+// ✅ Сначала cross-field правило (читает снапшот формы) в схеме валидации, потом revalidateWhen
+const amountVsMax = (f: Form): ValidationError | null =>
+  f.amount != null && f.maxAmount != null && f.amount > f.maxAmount
+    ? { code: 'tooBig', message: '...' }
+    : null;
+
+const schema = defineValidationSchema<Form>(({ model }) => {
+  cross(model.$.amount, amountVsMax); // навешиваем правило на поле amount
+});
+revalidateWhen([model.$.maxAmount], () => void validateModel(model, schema));
+```
+
+## Troubleshooting
+
+**Q: Ошибка target не пропадает после изменения триггера.**
+A: Проверьте, что (1) правило реально читает значение триггера — cross-field `cross(sig, fn)`,
+где `fn` берёт снапшот формы (`model.get()` / `f`); (2) в `deps` передан именно сигнал (`model.$.trigger`);
+(3) колбэк вызывает `validateModel` (роутит ошибки в ноды через `getNodeForSignal(sig).setErrors`).
+
+**Q: Как перевалидировать только одно поле, а не всю схему?**
+A: Схема — обычная функция, поэтому опиши стабильную под-схему только для этого поля и прогони её:
+`validateModel(model, oneFieldSchema)`, где
+`const oneFieldSchema = defineValidationSchema<Form>(({ model }) => cross(model.$.amount, amountVsMax))`.
+Раннер выставит/погасит ошибки только затронутых полей (гашение накапливается на пару `(model, schema)`).
+
+## See also
+
+- [03-api-signatures.md](./03-api-signatures.md) — cross-field `cross(sig, fn)` и раннер `validateModel`
+- [28-submit-and-reset.md](./28-submit-and-reset.md) — полная валидация формы
+- [20-compute-vs-watch.md](./20-compute-vs-watch.md) — реактивные производные значения

package/docs/llms/28-submit-and-reset.md

@@ -0,0 +1,259 @@
+# Submit и Reset — Жизненный цикл отправки формы
+
+## Purpose
+
+Канонический submit-флоу под M1: «запустить полную валидацию данных (`validateModel`) →
+проверить `boolean`-результат → достать снимок (`model.get()`) → сделать запрос → `model.reset()`».
+Валидация — **отдельный слой** (`@reformer/core/validation`, схема через `defineValidationSchema`), она
+НЕ входит в layout-дерево, которое получает `createForm`. Раннер `validateModel(model, schema)` сам роутит
+ошибки в ноды формы, поэтому UI подсветит проблемные поля, а наружу вернёт лишь `boolean`
+(false = есть блокирующая ошибка; `severity:'warning'` показывается, но submit не блокирует).
+`model.reset()` возвращает значения к initial-снимку.
+
+## API
+
+```typescript
+// Модель (источник истины значений):
+interface ModelApi<T> {
+  get(): T;                         // снимок значений — для submit
+  set(value: T): void;              // полная установка (все ключи T)
+  patch(value: Partial<T>): void;   // частичное слияние
+  isDirty(): boolean;               // отличаются ли значения от initial-снимка
+  reset(): void;                    // вернуть к initial-снимку
+  captureInitial(): void;           // зафиксировать текущие как новый initial
+}
+
+// Валидация данных — headless-раннер: находит ноды по сигналам модели, роутит в них ошибки,
+// отменяет устаревшие прогоны той же (model, schema). Возвращает ТОЛЬКО boolean:
+validateModel<T>(model: FormModel<T>, schema: ValidationSchema<T>): Promise<boolean>
+// true  = нет блокирующих ошибок (severity:'warning' не блокирует, но показывается).
+// false = есть блокирующая ошибка; она уже проставлена в ноду → UI подсветит поле.
+
+// Схема валидации — отдельный слой над моделью (не смешивается с layout):
+defineValidationSchema<T>(({ model }) => {
+  validate(model.$.field, [rules]);          // синхронные правила поля
+  // validateAsync / validateWhen / cross / each / apply — см. contract-spec
+}): ValidationSchema<T>
+
+// Нода поля/формы (для точечной работы с UI-состоянием):
+form.markAsTouched();                         // тронуть все поля (показать ошибки)
+form.clearErrors();                           // снять ошибки со всех нод
+form.<field>.setErrors([{ code, message }]);  // серверная/бизнес-ошибка в конкретное поле
+form.<field>.clearErrors();
+```
+
+## Examples
+
+### Базовый submit-handler
+
+```tsx
+import { useMemo } from 'react';
+import { createModel, createForm } from '@reformer/core';
+import { defineValidationSchema, validate, validateModel } from '@reformer/core/validation';
+import { required, email, minLength } from '@reformer/core/validators';
+
+type RegistrationFormData = { username: string; email: string; password: string };
+
+// Валидация — отдельная схема над моделью. НЕ входит в layout, который получает createForm.
+// Стабильная module-level `const`-ссылка — чтобы validateModel мог отменять устаревшие прогоны.
+const registrationSchema = defineValidationSchema<RegistrationFormData>(({ model }) => {
+  validate(model.$.username, [required({ message: 'Имя обязательно' }), minLength(3)]);
+  validate(model.$.email, [required({ message: 'Email обязателен' }), email()]);
+  validate(model.$.password, [required({ message: 'Пароль обязателен' }), minLength(8)]);
+});
+
+function RegistrationForm() {
+  const { model, form } = useMemo(() => {
+    const m = createModel<RegistrationFormData>({ username: '', email: '', password: '' });
+    // schema здесь — layout-дерево нод (компоненты/раскладка), без валидаторов.
+    return { model: m, form: createForm({ model: m, schema: buildLayout(m) }) };
+  }, []);
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    form.markAsTouched(); // показать ошибки на всех полях
+
+    // Шаг 1: прогон валидации данных. Ошибки автоматически проставятся в ноды → UI подсветит.
+    const valid = await validateModel(model, registrationSchema);
+    if (!valid) return;
+
+    // Шаг 2: достать чистые данные и отправить
+    const payload = model.get();
+    const response = await fetch('/api/v1/auth/register', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(payload),
+    });
+
+    // Шаг 3: чистый старт после успеха
+    if (response.ok) model.reset();
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <FormField control={form.username} testId="username" />
+      <FormField control={form.email} testId="email" />
+      <FormField control={form.password} testId="password" />
+      <button type="submit">Отправить</button>
+    </form>
+  );
+}
+```
+
+### Submit с error-handling и серверными ошибками
+
+```tsx
+async function handleSubmit(e: React.FormEvent) {
+  e.preventDefault();
+  form.markAsTouched();
+
+  const valid = await validateModel(model, registrationSchema);
+  if (!valid) return;
+
+  try {
+    const response = await api.register(model.get());
+    if (response.success) {
+      model.reset();
+      navigate('/welcome');
+    } else {
+      // Серверная бизнес-ошибка — НЕ сбрасываем форму, кладём ошибку в поле
+      form.username.setErrors([{ code: 'taken', message: response.message }]);
+    }
+  } catch (error) {
+    // Сеть/неожиданная ошибка — оставляем значения
+    showToast(`Ошибка сети: ${(error as Error).message}`);
+  }
+}
+```
+
+### Reset с подтверждением
+
+```tsx
+function ActionButtons({ model }: { model: FormModel<RegistrationFormData> }) {
+  const handleReset = () => {
+    if (!model.isDirty()) return; // нечего сбрасывать
+    if (confirm('Очистить форму? Несохранённые изменения будут потеряны.')) {
+      model.reset();
+    }
+  };
+
+  const clearJustPassword = () => {
+    model.password = ''; // сброс одного поля — прямая запись в модель
+  };
+
+  return (
+    <>
+      <button type="button" onClick={handleReset}>Очистить</button>
+      <button type="button" onClick={clearJustPassword}>Очистить только пароль</button>
+    </>
+  );
+}
+```
+
+### Использование вне React (server action / Node)
+
+Раннер headless — работает без UI-компонентов, только с моделью и схемой:
+
+```typescript
+import { createModel } from '@reformer/core';
+import { validateModel } from '@reformer/core/validation';
+
+async function processFormPayload(rawData: Partial<MyForm>) {
+  const model = createModel<MyForm>(initialValues);
+  model.patch(rawData); // частичный load данных
+
+  // validateModel находит ноды по сигналам модели и роутит в них ошибки, возвращая boolean.
+  const valid = await validateModel(model, myFormSchema);
+  if (!valid) return { ok: false as const };
+  return { ok: true as const, data: model.get() };
+}
+```
+
+## Anti-patterns
+
+```typescript
+// ❌ Обращение к .valid: раннер возвращает boolean, а не { valid, errors }
+const result = await validateModel(model, schema);
+if (!result.valid) return; // result — boolean, .valid === undefined → guard никогда не сработает
+
+// ✅ Результат — сам boolean
+const valid = await validateModel(model, schema);
+if (!valid) return;
+```
+
+```typescript
+// ❌ Чтение результата валидации без await — сабмитим по неполному вердикту
+const handleSubmit = (e) => {
+  e.preventDefault();
+  validateModel(model, schema); // Promise проигнорирован, async-валидаторы не дождались
+  submit(model.get());
+};
+
+// ✅ Дождаться и проверить boolean
+const handleSubmit = async (e) => {
+  e.preventDefault();
+  if (await validateModel(model, schema)) submit(model.get());
+};
+```
+
+```typescript
+// ❌ Валидаторы в layout-дереве, отдаваемом в createForm — layout не несёт правил
+createForm({ model, schema: { username: { value: '', validators: [required()] } } });
+
+// ✅ Валидация — отдельная схема, прогоняется раннером
+const schema = defineValidationSchema<T>(({ model }) => {
+  validate(model.$.username, [required()]);
+});
+await validateModel(model, schema);
+```
+
+```typescript
+// ❌ model.reset() до ответа сервера — потеря данных при ошибке
+await api.send(model.get());
+model.reset();
+
+// ✅ Reset только после успеха
+try {
+  await api.send(model.get());
+  model.reset();
+} catch (err) { showError(err); }
+```
+
+```typescript
+// ❌ Сброс полей по очереди — многословно
+model.username = '';
+model.email = '';
+model.password = '';
+
+// ✅ model.reset() — к initial-снимку одним вызовом
+model.reset();
+```
+
+## Troubleshooting
+
+**Q: После `reset()` в UI остались старые ошибки.**
+A: `model.reset()` меняет значения; ошибки в нодах чистит валидация. Перезапусти
+`validateModel(model, schema)` после reset (валидные поля погаснут сами), либо очисти напрямую —
+`form.clearErrors()` / `form.<field>.clearErrors()`.
+
+**Q: `validateModel` вернул `true`, но в поле висит ошибка.**
+A: Это правило с `severity: 'warning'` — оно показывается, но submit не блокирует, поэтому раннер
+и вернул `true`. Блокируют только ошибки без `severity` (default). Чтобы не пускать submit при
+warning — проверяй его отдельно, вне `validateModel`.
+
+**Q: `reset()` не возвращает данные, загруженные с сервера.**
+A: `reset()` возвращает к initial-снимку (значения на момент `createModel`). `set/patch` НЕ
+меняют initial. Чтобы сделать загруженные данные новой «точкой отсчёта» — вызови
+`model.captureInitial()` после загрузки.
+
+**Q: Disabled-поля участвуют в submit-данных?**
+A: `model.get()` возвращает значения всех полей. Фильтруй вручную после `get()` или используй
+`enableWhen({ resetOnDisable: true })`, чтобы при disable поле возвращалось к initial.
+
+## See also
+
+- [29-async-preload.md](./29-async-preload.md) — initial values и preload через `set`/`patch`
+- [13-multi-step.md](./13-multi-step.md) — пошаговая валидация через `validateModel` (`validateStep`/`validateAll`)
+- [27-revalidate-when.md](./27-revalidate-when.md) — мост «поведение → валидация»: `revalidateWhen([deps], () => void validateModel(model, schema))`
+- [03-api-signatures.md](./03-api-signatures.md) — сигнатуры модели и `validateModel`
+- [05-common-mistakes.md](./05-common-mistakes.md) — типичные ошибки

package/docs/llms/29-async-preload.md

@@ -0,0 +1,193 @@
+# Async Preload — Загрузка начальных значений и справочников
+
+## Purpose
+
+Загрузка формы данными с сервера под M1: (1) **initial values** в `createModel(...)`; (2)
+**`model.set` / `model.patch`** для загрузки/обновления значений; (3) **external React-hook**
+для full-blown async preload (параллельный fetch заявки + справочников, обработка ошибок,
+race-guard через deps). Динамические `componentProps` (опции селектов) обновляются через
+`form.field.updateComponentProps({ options })` в `queueMicrotask`, чтобы не пересечься с
+реактивными эффектами от `set`/`patch`.
+
+## API
+
+```typescript
+// Модель:
+model.set(value: T): void;            // полная установка значений (load полного DTO). Не меняет initial.
+model.patch(value: Partial<T>): void; // частичное слияние (только переданные ключи). Не меняет initial.
+model.reset(): void;                  // вернуть к initial-снимку
+model.captureInitial(): void;         // сделать текущие значения новым initial-снимком
+
+// Нода поля/группы:
+form.field.updateComponentProps(props: Record<string, unknown>): void; // динамические опции и т.п.
+```
+
+Initial values задаются в `createModel(initial)`; `reset()` возвращает к ним. Чтобы загруженные
+данные стали новой «точкой отсчёта» для `reset()` — вызови `model.captureInitial()` после load.
+
+## Examples
+
+### Initial values в модели
+
+```typescript
+import { createModel, createForm } from '@reformer/core';
+import { Input, Select } from '@reformer/ui-kit';
+
+type ProfileForm = { username: string; language: 'ru' | 'en'; marketing: boolean };
+
+const model = createModel<ProfileForm>({ username: '', language: 'ru', marketing: true });
+const schema = {
+  username: { value: model.$.username, component: Input, componentProps: { label: 'Username' } },
+  language: {
+    value: model.$.language,
+    component: Select,
+    componentProps: {
+      label: 'Язык',
+      options: [
+        { value: 'ru', label: 'Русский' },
+        { value: 'en', label: 'English' },
+      ],
+    },
+  },
+  marketing: { value: model.$.marketing, component: Input, componentProps: { type: 'checkbox' } },
+};
+const form = createForm({ model, schema });
+// model.get() === { username: '', language: 'ru', marketing: true }
+// после правок: model.reset() возвращает к этим значениям
+```
+
+### Async preload через external hook + model.set
+
+```tsx
+import { useEffect, useState } from 'react';
+import type { FormModel, FormProxy } from '@reformer/core';
+
+interface LoadingState { isLoading: boolean; error: string | null }
+
+export function useLoadCreditApplication(
+  model: FormModel<CreditApplicationForm>,
+  form: FormProxy<CreditApplicationForm>,
+  applicationId: string | null
+): LoadingState {
+  const [state, setState] = useState<LoadingState>({ isLoading: !!applicationId, error: null });
+
+  useEffect(() => {
+    if (!applicationId) { setState({ isLoading: false, error: null }); return; }
+    let cancelled = false;
+
+    (async () => {
+      setState({ isLoading: true, error: null });
+      try {
+        const [appResp, dictsResp] = await Promise.all([
+          fetchCreditApplication(applicationId),
+          fetchDictionaries(),
+        ]);
+        if (cancelled) return; // race-guard: сменили applicationId / unmount
+        if (appResp.status !== 200 || dictsResp.status !== 200) throw new Error('Сервер вернул ошибку');
+
+        // Загрузка значений в модель
+        model.set(appResp.data);
+
+        // Динамические componentProps — через queueMicrotask (после реактивных эффектов от set)
+        queueMicrotask(() => {
+          if (cancelled) return;
+          form.registrationAddress.city.updateComponentProps({ options: dictsResp.data.cities });
+        });
+
+        setState({ isLoading: false, error: null });
+      } catch (err) {
+        if (cancelled) return;
+        setState({ isLoading: false, error: err instanceof Error ? err.message : 'Ошибка' });
+      }
+    })();
+
+    return () => { cancelled = true; };
+  }, [applicationId]); // model/form стабильны (создан через useMemo)
+
+  return state;
+}
+```
+
+### Preload через behavior — onChange на поле
+
+Загрузка справочника при выборе другого поля (после preload) — через `onChange`:
+
+```typescript
+import { defineFormBehavior, onChange } from '@reformer/core/behaviors';
+
+export const addressBehavior = defineFormBehavior<AddressForm>(({ model, form }) => {
+  onChange(
+    model.$.region,
+    async (region, { signal }) => {
+      if (!region) { form.city.updateComponentProps({ options: [] }); return; }
+      try {
+        const cities = await fetchCities(region, { signal });
+        form.city.updateComponentProps({ options: cities });
+      } catch {
+        form.city.updateComponentProps({ options: [] });
+      }
+    },
+    { debounce: 300 }
+  );
+});
+```
+
+## Anti-patterns
+
+```typescript
+// ❌ model/form пересоздаются на каждый рендер → preload запускается каждый раз
+function MyForm() {
+  const model = createModel<T>(initial);   // КАЖДЫЙ рендер!
+  const form = createForm({ model, schema });
+}
+
+// ✅ Стабильные ссылки через useMemo
+function MyForm() {
+  const { model, form } = useMemo(() => {
+    const m = createModel<T>(initial);
+    return { model: m, form: createForm({ model: m, schema: buildSchema(m) }) };
+  }, []);
+}
+```
+
+```typescript
+// ❌ updateComponentProps синхронно после set → возможный конфликт с реактивными эффектами
+model.set(data);
+form.region.updateComponentProps({ options: [...] });
+
+// ✅ queueMicrotask, чтобы реактивные эффекты от set завершились
+model.set(data);
+queueMicrotask(() => form.region.updateComponentProps({ options: [...] }));
+```
+
+```typescript
+// ❌ Нет race-guard в async useEffect
+useEffect(() => { fetchData(id).then((d) => model.set(d)); }, [id]);
+
+// ✅ Cleanup-флаг
+useEffect(() => {
+  let cancelled = false;
+  fetchData(id).then((d) => { if (!cancelled) model.set(d); });
+  return () => { cancelled = true; };
+}, [id]);
+```
+
+## Troubleshooting
+
+**Q: После `set`/`patch` не показываются ошибки.**
+A: `set`/`patch` не запускают валидацию. После загрузки вызови `await validateModel(model, schema)` (внешний раннер из `@reformer/core/validation`).
+
+**Q: Опции в `<Select>` не появляются после `updateComponentProps`.**
+A: (1) Оберни вызов в `queueMicrotask`; (2) убедись, что компонент подписан через `useFormControl`;
+(3) для массивов — пройдись по элементам (`form.items.map`) и обнови каждый.
+
+**Q: При `reset()` теряются данные с сервера.**
+A: `reset()` возвращает к initial-снимку из `createModel`, не к последнему `set`. Чтобы «сбросить
+к данным с сервера» — после `set` вызови `model.captureInitial()` (новая точка отсчёта).
+
+## See also
+
+- [28-submit-and-reset.md](./28-submit-and-reset.md) — обратная сторона жизненного цикла
+- [11-async-watchfield.md](./11-async-watchfield.md) — `onChange` для динамики после preload
+- [22-cycle-detection.md](./22-cycle-detection.md) — почему `queueMicrotask` нужен
+- [16-ui-components.md](./16-ui-components.md) — `updateComponentProps` для динамических опций