@reformer/core 10.0.0-beta.2 → 10.0.0-beta.4

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` для динамических опций

package/docs/llms/30-type-safety-recipes.md

@@ -0,0 +1,159 @@
+## 30. TYPE-SAFETY RECIPES
+
+Идиоматичные паттерны, которые держат сгенерированный код без `any` и `as`-кастов под M1.
+
+### Recipe 1 — Imports (root cause prevention)
+
+- Модель/форма/хуки/типы/**примитивы behaviors** — из `@reformer/core`.
+- Схема валидации (операторы + раннер `validateModel`) — из `@reformer/core/validation`.
+- Чистые фабрики валидаторов — из `@reformer/core/validators`.
+- Декларативный DSL (`defineFormBehavior` + операторы) — из `@reformer/core/behaviors`.
+
+```typescript
+import {
+  createModel,
+  createForm,
+  type FormModel,
+  type FormProxy,
+  type ModelSignals,
+} from '@reformer/core';
+import {
+  defineValidationSchema,
+  validate,
+  cross,
+  validateModel,
+  type Rule,
+} from '@reformer/core/validation';
+import { required, min, max, email } from '@reformer/core/validators';
+import { defineFormBehavior, compute, enableWhen, onChange } from '@reformer/core/behaviors';
+```
+
+> **watchField — из `@reformer/core`** (примитив), НЕ из `@reformer/core/behaviors` (там `onChange`).
+
+### Recipe 2 — Form-shape types as `type`, not `interface`
+
+`Record<string, FormValue>` требует index signature. У `interface` её нет неявно; у `type` —
+структурно. Объявляй через `type`-alias всё, что попадает в `FormProxy<T>`/`ArrayNode<T>`:
+корневую форму, вложенные группы, типы элементов массива.
+
+```typescript
+export type PropertyItem = {
+  type: 'apartment' | 'house' | 'car';
+  description: string;
+  estimatedValue: number;
+};
+
+export type CreditApplicationForm = {
+  loanAmount: number | null;
+  properties: PropertyItem[];
+  // ...
+};
+```
+
+### Recipe 3 — Схема привязана к сигналам модели
+
+`value` поля — это сигнал модели (`model.$.field`), а не литерал. Тип поля выводится из сигнала.
+Layout-схема БЕЗ валидаторов — правила живут в отдельной validation-схеме.
+
+```typescript
+const model = createModel<CreditApplicationForm>(initial);
+
+const schema = {
+  loanAmount: { value: model.$.loanAmount, component: Input },
+  // вложенная группа — builder, принимающий ModelSignals<Sub>
+  personalData: personalDataNodes(model.$.personalData),
+  // массив — { array, item }
+  properties: { array: model.properties, item: propertyItem },
+};
+
+// правила — отдельно; типы полей выводятся из сигналов
+const validation = defineValidationSchema<CreditApplicationForm>(({ model }) => {
+  validate(model.$.loanAmount, [required(), min(50000)]);
+});
+```
+
+### Recipe 4 — Cross-field валидаторы: `cross` над типизированным снапшотом
+
+Правило — обычная функция `(f: Root) => ValidationError | null` над снапшотом `model.get()`.
+Соседние поля читаются без `as`; ошибка вешается на поле-носитель `sig`:
+
+```typescript
+import type { ValidationError } from '@reformer/core';
+
+const initialPaymentVsProperty = (f: CreditApplicationForm): ValidationError | null =>
+  f.initialPayment && f.propertyValue && f.initialPayment > f.propertyValue
+    ? { code: 'tooHigh', message: 'Взнос не может превышать стоимость' }
+    : null;
+
+// внутри defineValidationSchema<CreditApplicationForm>(({ model }) => { ... }):
+cross(model.$.initialPayment, initialPaymentVsProperty);
+```
+
+### Recipe 5 — `compute` читает модель напрямую (без аннотаций)
+
+`compute(target, () => …)` читает value-модель (`model.field`) — типы полей выводятся из типа
+модели, `as`-касты не нужны:
+
+```typescript
+compute(model.$.monthlyPayment, () =>
+  annuityMonthly(model.loanAmount ?? 0, model.loanTerm ?? 0, model.interestRate ?? 0)
+);
+
+// nested reads — тоже напрямую
+compute(model.$.fullName, () =>
+  [model.personalData.firstName, model.personalData.lastName].filter(Boolean).join(' ')
+);
+```
+
+### Recipe 6 — `null` vs `undefined` для опциональных полей
+
+Оба работают. `null` — конвенция «пользователь очистил поле». Встроенные валидаторы
+(`min`, `max`, `minLength`, `maxLength`, `minDate`, `maxDate`, `minAge`, `maxAge`) пропускают
+пустые значения — guard `if (value != null)` не нужен.
+
+```typescript
+export type CreditForm = {
+  loanAmount: number | null;   // min(model.$.loanAmount, 50000) — ок
+  loanPurpose: string | null;  // minLength — ок
+  birthDate: string | null;    // minAge — ок
+};
+```
+
+### Recipe 7 — Нода поля для кастомных компонентов
+
+`useFormControl(control)` типизируется по `FieldNode<T>`. В props компонента используй `FieldNode<T>`:
+
+```typescript
+import type { FieldNode } from '@reformer/core';
+
+type MyFieldProps<T> = { control: FieldNode<T> };
+function MyField<T>({ control }: MyFieldProps<T>) {
+  const { value, errors, disabled } = useFormControl(control);
+  // ...
+}
+```
+
+### Recipe 8 — Вынос правил в именованные функции
+
+Field-правила — именованные `Rule<T>`, validation-схема остаётся плоской:
+
+```typescript
+import type { Rule } from '@reformer/core/validation';
+
+const validateAdultAge: Rule<string | null> = (value) => {
+  if (!value) return null;
+  const age = new Date().getFullYear() - new Date(value).getFullYear();
+  return age < 18 ? { code: 'tooYoung', message: 'Минимум 18 лет' } : null;
+};
+
+// внутри defineValidationSchema<MyForm>(({ model }) => { ... }):
+validate(model.$.birthDate, [validateAdultAge]);
+```
+
+### Anti-patterns to avoid
+
+- `import { computeFrom } from '@reformer/core/behaviors'` для примитива, вызываемого вне
+  `defineFormBehavior` → примитив живёт в `@reformer/core` (возвращает cleanup).
+- `interface MyForm { ... }` для form-shape → см. Recipe 2.
+- `as`-касты значений полей внутри `compute` → читай `model.field` напрямую (Recipe 5).
+- строковые пути / `(form) => ...` в behaviors → это удалённый API, используй сигналы (`model.$.x`).