@reformer/core 10.1.0 → 11.0.0-beta.1

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

@@ -0,0 +1,98 @@
+## 13. EXTENDED COMMON MISTAKES
+
+### Reuse via apply / applyEach — не дублируй код
+
+```typescript
+import { defineFormBehavior, apply, applyEach, compute } from '@reformer/core/behaviors';
+
+// ✅ apply — одна под-схема на несколько групп
+const addressBehavior = defineFormBehavior<Address>(({ model }) => {
+  compute(model.$.full, () => `${model.city}, ${model.street}`);
+});
+
+const behavior = defineFormBehavior<Form>(({ model }) => {
+  apply([model.$.homeAddress, model.$.workAddress], addressBehavior);
+
+  // ✅ applyEach — под-схема на КАЖДЫЙ элемент массива (реагирует на add/remove)
+  applyEach(
+    model.$.items,
+    defineFormBehavior<Item>(({ model: row }) => {
+      compute(row.$.lineTotal, () => row.qty * row.price);
+    })
+  );
+});
+```
+
+### Идемпотентность transformValue
+
+```typescript
+// ❌ неидемпотентный transformer — бесконечный цикл setValue → callback → setValue
+transformValue(model.$.field, (v) => `prefix-${v}`); // f(f(x)) ≠ f(x)
+
+// ✅ guard «уже преобразовано»
+transformValue(model.$.field, (v) => (v?.startsWith('prefix-') ? v : `prefix-${v}`));
+```
+
+### compute для производных полей вместо ручной синхронизации
+
+```typescript
+// ❌ ручной onChange + запись — легко зациклить/забыть кейс
+onChange(model.$.firstName, () => { model.fullName = `${model.firstName} ${model.lastName}`; });
+
+// ✅ compute: цель не входит в источники → цикла нет, запись идемпотентна (peek-guard)
+compute(model.$.fullName, () => [model.firstName, model.lastName].filter(Boolean).join(' '));
+```
+
+### Расходящийся цикл compute (Cycle detected)
+
+Взаимные `compute`/`computeFrom` без стабилизации preact обрывает как «Cycle detected».
+DSL перехватывает это и бросает понятную ошибку с именем поля. Решение — разорвать цикл
+условием `when` или читать одну сторону через `peek()`:
+
+```typescript
+// ❌ взаимный пересчёт без стабилизации
+compute(model.$.a, () => model.b + 1);
+compute(model.$.b, () => model.a + 1); // расходится → Cycle detected
+
+// ✅ добавь стабилизирующее условие или однонаправленную зависимость
+compute(model.$.total, () => model.price * model.qty); // одно направление
+```
+
+### Cross-field валидация — через `cross(sig, fn)`
+
+Cross-field живёт в схеме валидации (`@reformer/core/validation`), а не в layout: правило вешается на
+ПОЛЕ-НОСИТЕЛЬ ошибки оператором `cross(sig, fn)`, а `fn` читает снапшот текущего scope (`model.get()`).
+
+```typescript
+import { defineValidationSchema, validate, cross, validateModel } from '@reformer/core/validation';
+import { required } from '@reformer/core/validators';
+import { revalidateWhen, type ValidationError } from '@reformer/core';
+
+// ❌ старое (УДАЛЕНО): дерево { 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;
+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;
+
+const schema = defineValidationSchema<Form>(({ model }) => {
+  validate(model.$.field1, [required()]);
+  cross(model.$.field1, field1LessThanField2); // правило на поле-носителе ошибки
+});
+
+// Прогон — ТОЛЬКО внешним раннером; ошибки сами доезжают до нод формы.
+// ⚠️ form.validate()/submit() схему валидации больше НЕ прогоняют.
+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`,
+> типы `FieldPath`/`ValidationSchemaFn`/`BehaviorSchemaFn` и `ctx.form.*`/`ctx.setFieldValue` (наследие
+> path-based архитектуры). См. `17-nonexistent-api.md`.

package/docs/llms/15-project-structure.md

@@ -0,0 +1,125 @@
+## 14. PROJECT STRUCTURE (COLOCATION)
+
+One form is one module folder. **Default layout — flat minimalist:** every concern is a single
+file at the module root, and the whole form (entry + all wizard steps inline) lives in one
+`index.tsx`. Filenames are flat with no prefix — **the dot-prefix (`form.` / `renderer.`) is
+carried only by `schema` and `behavior`**, the two concerns that have both a model-layer and a
+render-layer version (`form.schema.ts` / `form.behavior.ts` here; renderer slices add
+`renderer.schema.*` / `renderer.behavior.ts`). No `lib/` / `schema/` / `components/steps/`
+nesting until the form grows (see "Scaling up" below). Arrays are declared in `form.schema.ts`
+and rendered with `FormArraySection` — no per-step component files.
+
+```
+src/
+├── components/ui/                # App-wide reusable UI (FormField, FormArraySection, ...)
+│
+├── forms/
+│   └── [form-name]/              # Form module — flat, one file per concern
+│       ├── index.tsx             # entry + whole form: createModel→createForm→<FormWizard> with all steps inline; arrays via FormArraySection
+│       ├── types.ts              # form type + enums + { value, label } option type + constant dictionaries
+│       ├── model.ts              # createModel + initial values + empty-array-element factories
+│       ├── form.schema.ts        # FormSchema: { value: model.$.x, component, componentProps }
+│       ├── form.behavior.ts      # defineFormBehavior: compute / enableWhen / hideWhen / copyFrom / onChange
+│       ├── validation.ts         # ALL validation → { validateStep, validateAll }
+│       ├── data-sources.ts       # options + async loaders (dataSources)
+│       └── api.ts                # submit + prefill/load
+```
+
+Rule of thumb: **one concern → one file at the module root; the whole component tree (all steps) →
+`index.tsx`; validation is a single `validation.ts`.** This is the working default for
+almost every form — reach for folders only when a file stops fitting on a screen.
+
+### Key Files
+
+```typescript
+// forms/credit-application/types.ts
+export type CreditApplicationForm = {
+  loanType: LoanType;
+  loanAmount: number | null;
+  // ...
+};
+
+// forms/credit-application/model.ts
+import { createModel, type FormModel } from '@reformer/core';
+export const createCreditApplicationModel = (): FormModel<CreditApplicationForm> =>
+  createModel<CreditApplicationForm>(createInitialCreditApplication());
+
+// forms/credit-application/form.schema.ts
+import type { FormModel } from '@reformer/core';
+export const creditApplicationSchema = (model: FormModel<CreditApplicationForm>) => ({
+  loanType: { value: model.$.loanType, component: Select, componentProps: { /* ... */ } },
+  personalData: personalDataNodes(model.$.personalData),
+  properties: { array: model.properties, item: propertyItem },
+});
+
+// forms/credit-application/form.behavior.ts
+import { defineFormBehavior, compute, enableWhen } from '@reformer/core/behaviors';
+export const creditApplicationBehavior = defineFormBehavior<CreditApplicationForm>(({ model }) => {
+  compute(model.$.monthlyPayment, () => computeMonthlyPayment(model));
+  enableWhen([model.$.propertyValue], () => model.loanType === 'mortgage', { resetOnDisable: true });
+});
+
+// forms/credit-application/index.tsx — entry: assembles the form, renders <FormWizard> with all steps inline
+import { createForm } from '@reformer/core';
+export const createCreditApplicationForm = () => {
+  const model = createCreditApplicationModel();
+  return createForm({ model, schema: creditApplicationSchema(model), behavior: creditApplicationBehavior });
+};
+```
+
+### Scaling up: folders (large forms)
+
+When the flat module gets unwieldy — steps you want in their own files, sub-forms reused across
+steps, calc/validators that outgrow one file — promote it to a three-folder module: `lib/`
+(domain raw material), `schema/` (the form definition), `components/` (React layout), plus the
+entry component and `index.ts`. Keep the module root to just the entry + `index.ts`; everything
+else lives in a folder.
+
+```
+forms/
+└── [form-name]/                  # Form module — folders (scale-up)
+    ├── [FormName]Form.tsx        # Entry: builds model+form, renders FormWizard + step components
+    ├── index.ts                  # Public re-exports of the module
+    │
+    ├── lib/                      # Domain helpers (target-agnostic)
+    │   ├── types.ts             # Form interface + field enums + { value, label } option type
+    │   ├── constants.ts         # Option dictionaries (LOAN_TYPES, GENDERS, ...)
+    │   ├── calc.ts              # Pure fns for derived fields (age, monthlyPayment, ...)
+    │   ├── custom-validators.ts # Reusable validator factories
+    │   └── api.ts               # Data sources + submit
+    │
+    ├── schema/                   # The form definition
+    │   ├── model.ts             # createModel factory + initial values + array-element factories
+    │   ├── schema.ts            # createForm schema tree ({ value: model.$.x, component })
+    │   ├── validation.ts        # defineValidationSchema + validateModel config ({ validateStep, validateAll })
+    │   ├── behavior.ts          # defineFormBehavior(...)
+    │   └── create-form.ts       # Assembly: createForm({ model, schema, behavior })
+    │
+    └── components/
+        ├── steps/               # One component per wizard step
+        ├── nested-forms/        # Reusable sub-forms (Address, PersonalData, ...)
+        └── ui/                  # Form-specific helper blocks (summary, warnings, sections)
+```
+
+Rule of thumb for this layout: **domain raw material → `lib/`; anything describing the form →
+`schema/`; React layout → `components/`; root = entry + `index.ts`.** In very large forms you
+may co-locate each step's `schema.ts` / `validation.ts` / `behavior.ts` inside its
+`steps/[Step]/` folder, keeping only the shared `model` and cross-step rules in `schema/` — see
+the guide below.
+
+### Scaling
+
+| Complexity | Structure |
+| ---------- | --------------------------------------------------------------------------------------- |
+| Simple | Single file: `index.tsx` (model + schema + behavior + component) |
+| **Minimalist (flat)** | **Default.** One file per concern at the module root (`types` / `model` / `form.schema` / `form.behavior` / `validation` / `data-sources` / `api`) + `index.tsx` with all steps inline |
+| Folders (`lib/` + `schema/` + `components/`) | Large forms: split concerns into folders, one component per step, reusable `nested-forms/` |
+
+> The leading layout is configurable: set `REFORMER_FORM_LAYOUT` (`minimalist` | `folders`)
+> when registering the MCP server to choose which structure the generators lead with. Default
+> is `minimalist`.
+
+> Cross-target variants (renderer-react `renderer.schema.ts` + `renderer.behavior.ts` /
+> renderer-json `renderer.schema.json` + `renderer.behavior.ts` + `registry.ts`), the
+> centralized-vs-co-located choice, and the full reuse map live in the
+> **form-directory-layout** guide (`@reformer/mcp`).

package/docs/llms/16-ui-components.md

@@ -0,0 +1,189 @@
+## 14.5 UI COMPONENT PATTERNS
+
+> **Default rule (read first)**: для UI используй `FormField` из
+> [`@reformer/ui-kit`](../../reformer-ui-kit/) — он покрывает 95% случаев одной
+> строкой `<FormField control={form.x} />`. Свои field-обёртки пиши ТОЛЬКО если
+> ui-kit не подходит (другая design system, особый low-level input).
+>
+> Канонический schema-driven подход:
+>
+> - **компонент** объявляется в схеме как `component: Input` (или `Select`, `Checkbox`, etc.)
+> - **пропсы** компонента — в `componentProps: { label, placeholder, options, type, ... }`
+> - **JSX рендерит**: `<FormField control={form.x} />` БЕЗ дополнительных props
+>
+> См. `find_recipe(package="@reformer/ui-kit", topic="form-field-integration")`
+> для полного руководства.
+
+### Default — FormField из ui-kit (canonical)
+
+```tsx
+import { useMemo } from 'react';
+import { createModel, createForm } from '@reformer/core';
+import { FormField, Input, Select, Checkbox, Button } from '@reformer/ui-kit';
+
+type RegistrationForm = {
+  email: string;
+  country: string;
+  agree: boolean;
+};
+
+function RegistrationPage() {
+  const form = useMemo(() => {
+    const model = createModel<RegistrationForm>({ email: '', country: 'ru', agree: false });
+    const schema = {
+      email: {
+        value: model.$.email,
+        component: Input,
+        componentProps: { label: 'Email', type: 'email', placeholder: 'you@example.com' },
+      },
+      country: {
+        value: model.$.country,
+        component: Select,
+        componentProps: {
+          label: 'Country',
+          options: [
+            { value: 'ru', label: 'Россия' },
+            { value: 'by', label: 'Беларусь' },
+          ],
+        },
+      },
+      agree: {
+        value: model.$.agree,
+        component: Checkbox,
+        componentProps: { label: 'I agree to terms' },
+      },
+    };
+    return createForm<RegistrationForm>({ model, schema });
+  }, []);
+
+  return (
+    <form>
+      <FormField control={form.email} testId="email" />
+      <FormField control={form.country} testId="country" />
+      <FormField control={form.agree} testId="agree" />
+      <Button type="submit">Register</Button>
+    </form>
+  );
+}
+```
+
+`FormField` сам читает `componentProps.label`, `componentProps.placeholder`,
+`componentProps.options` через `useFormControl(...).componentProps` и применяет
+их к нужному `<input>`/`<select>`/etc. Error rendering, `pending` для async-валидаций,
+`data-testid` для e2e — всё из коробки.
+
+### Anti-patterns (не делай так)
+
+❌ **Свои field-компоненты с label-prop'ами в JSX**:
+
+```tsx
+// WRONG — дублирует логику FormField, ломает schema-driven архитектуру
+<Input control={form.email} label="Email" placeholder="..." />
+<Select control={form.country} options={[...]} />
+```
+
+❌ **Передача компонент-пропсов через JSX вместо схемы**:
+
+```tsx
+// WRONG — нарушает single source of truth (схема)
+<FormField control={form.email} label="Email" />
+```
+
+✅ Всё это в схеме:
+
+```ts
+{ email: { component: Input, componentProps: { label: 'Email' } } }
+```
+
+```tsx
+<FormField control={form.email} />
+```
+
+### Advanced — кастомный input через `children` slot
+
+Когда нужен низкоуровневый input, которого нет в ui-kit (маска, особый combobox):
+
+```tsx
+import { FormField } from '@reformer/ui-kit';
+import { InputMask } from 'react-input-mask';
+
+<FormField control={form.phone} testId="phone">
+  <InputMask mask="+7 (999) 999-99-99" />
+</FormField>;
+```
+
+`children` оборачивается в `CdkFormField.Control asChild` и получает все нужные
+props (`value`, `onChange`, `onBlur`, `aria-invalid`).
+
+### Advanced — write your own from scratch (rare)
+
+Если ты не хочешь подключать `@reformer/ui-kit`, пиши свои компоненты на основе
+`useFormControl` — но **сохраняй schema-driven подход**: читай label/placeholder
+из `componentProps`, не из JSX-props.
+
+```tsx
+import type { FieldNode } from '@reformer/core';
+import { useFormControl } from '@reformer/core';
+
+type MyFormFieldProps<T> = { control: FieldNode<T> }; // ← ОДИН prop
+
+function MyFormField<T>({ control }: MyFormFieldProps<T>) {
+  const { value, errors, disabled, shouldShowError, componentProps } = useFormControl(control);
+  // componentProps = { label, placeholder, type, options, ... } — из СХЕМЫ
+  const cp = (componentProps ?? {}) as Record<string, unknown>;
+
+  return (
+    <label>
+      {cp.label && <span>{cp.label as string}</span>}
+      <input
+        type={(cp.type as string) ?? 'text'}
+        value={(value ?? '') as string}
+        placeholder={cp.placeholder as string | undefined}
+        disabled={disabled}
+        onChange={(e) => (control.setValue as (v: unknown) => void)(e.target.value)}
+        onBlur={() => control.markAsTouched()}
+      />
+      {shouldShowError && errors[0] && <span>{errors[0].message}</span>}
+    </label>
+  );
+}
+```
+
+Использование — как у `FormField`:
+
+```tsx
+<MyFormField control={form.email} /> // ← без label-prop
+```
+
+### Integration with UI libraries (shadcn etc.)
+
+> **Через рендерер — без обёртки.** Если ты рендеришь форму через `@reformer/renderer-react` /
+> `@reformer/renderer-json`, вместо ручной обёртки на каждый контрол можно зарегистрировать сырой
+> компонент и передать `settings.resolveFieldAdapter` — рендерер сам сведёт value-seam к диалекту
+> контрола. Ручная обёртка на `useFormControl` (ниже) нужна для прямого JSX без рендерера.
+
+Если есть существующая design system — оборачивай её компоненты в один
+`MyFormField` (как выше) и используй один прop `control`. Не множь обёртки на
+тип input'а — пусть `componentProps.type` диспатчит внутри.
+
+```tsx
+import { Input } from '@/components/ui/input';
+import { Label } from '@/components/ui/label';
+
+function ShadcnFormField({ control }: { control: FieldNode<string> }) {
+  const { value, errors, disabled, componentProps } = useFormControl(control);
+  const cp = (componentProps ?? {}) as Record<string, unknown>;
+
+  return (
+    <div className="space-y-2">
+      {cp.label && <Label>{cp.label as string}</Label>}
+      <Input
+        value={(value ?? '') as string}
+        onChange={(e) => control.setValue(e.target.value)}
+        disabled={disabled}
+      />
+      {errors[0] && <p className="text-red-500">{errors[0].message}</p>}
+    </div>
+  );
+}
+```

package/docs/llms/17-nonexistent-api.md

@@ -0,0 +1,93 @@
+## 15. NON-EXISTENT API (DO NOT USE)
+
+**Следующего API НЕТ в @reformer/core** (наследие старой path-based архитектуры,
+удалено при переходе на M1 и при разделении валидации/поведения):
+
+> ⚠️ Операторы валидации `validate`/`validateAsync`/`validateWhen`/`cross`/`each`/`apply`
+> **существуют** — но живут в сабпути `@reformer/core/validation` (ambient-схема
+> `defineValidationSchema(({ model }) => …)`, раннер `validateModel`), а НЕ в корне и НЕ
+> в `@reformer/core/validators`. Ниже перечислено то, чего действительно нет.
+
+| Wrong                            | Correct                                          | Notes                                          |
+| -------------------------------- | ------------------------------------------------ | ---------------------------------------------- |
+| `useForm`                        | `createModel` + `createForm`                     | Хука useForm нет                               |
+| `validateForm`, `validateFormModel` | `validateModel(model, schema)` из `@reformer/core/validation` | Legacy-движок дерева `{ value, validators }` удалён; внешний раннер — `validateModel` |
+| `validateModelSync`              | `await validateModel(model, schema)`             | Синхронного раннера нет — прогон асинхронный (`Promise<boolean>`) |
+| `applyWhen`                      | `validateWhen(() => cond, () => { … })`          | Условная валидация — оператором `validateWhen`, не узлом `{ when, children }` |
+| `validateItems`, `validateGroup`, `validateTree` | `each(model.arr, (im) => { … })` | Per-item — оператором `each`; под-схема — прямой вызов `sub({ model: model.child })` |
+| `ValidationSchemaFn`, `BehaviorSchemaFn` | `ValidationSchema<T>` (`defineValidationSchema`) / `defineFormBehavior` | Типы path-схем удалены |
+| `equalTo`, `custom`, `notEmpty` (validators) | inline `Rule<T>` `(value) => err \| null` в `validate(sig, [...])`; сравнение полей — `cross(sig, fn)` | Таких фабрик нет; кастомное правило — обычная функция значения, cross-field — `cross` |
+| `form.submit()` / `form.validate()` прогоняют схему | `await validateModel(model, schema)` перед submit/шагом | submit/validate НЕ запускают ambient-схему валидации |
+| `FieldPath`, `FieldPathNode`     | `model.$.field` (`PathAwareSignal`)              | Пути заменены сигналами                         |
+| `ctx.form.x.value.value`         | `model.x` / `model.$.x.value`                    | В behaviors читаем модель напрямую              |
+| `ctx.setFieldValue(name, value)` | `model.x = value` / `compute(...)`               | Не существует                                   |
+| `transformers`, `createTransformer` | `transformValue(signal, fn)`                  | Готового набора трансформеров нет               |
+| `useHiddenCondition`             | `useFormControlValue` + условный рендер в JSX    | Хука нет                                        |
+| `FormProvider`, `control` prop, `register()` | `<Component form={form} />`, `useFormControl(form.field)` | Форма передаётся через props |
+| `getFieldValue()`                | `model.field` / `useFormControlValue(form.field)`| Не существует                                   |
+
+### Common Import Errors
+
+```typescript
+// WRONG - этих символов / путей НЕ существует
+import { useForm, validateForm, validateFormModel } from '@reformer/core';        // NO!
+import { validate, applyWhen, equalTo } from '@reformer/core/validators';         // NO! операторов тут нет
+import { transformers } from '@reformer/core/behaviors';                          // NO!
+import type { FieldPath, ValidationSchemaFn } from '@reformer/core';              // NO!
+
+// CORRECT
+import { createModel, createForm, useFormControl } from '@reformer/core';
+import type { FormModel, ValidationError, FieldConfig } from '@reformer/core';
+// Операторы валидации + раннер + defineValidationSchema — отдельный сабпуть:
+import {
+  validate, validateAsync, validateWhen, cross, each, apply,
+  defineValidationSchema, validateModel,
+  type Rule, type AsyncRule, type ValidationSchema,
+} from '@reformer/core/validation';
+// Фабрики-валидаторы (value-only, принимают nullable):
+import { required, email, min, minLength, pattern } from '@reformer/core/validators';
+// Поведение (отдельный слой, контракт не менялся):
+import { defineFormBehavior, compute, onChange, revalidateWhen } from '@reformer/core/behaviors';
+```
+
+### Schema Common Mistakes
+
+Валидация и layout — **разные** контракты. Layout-узел привязывает поле к сигналу и
+НЕ несёт `validators`; правила живут в отдельной `defineValidationSchema`.
+
+```typescript
+// WRONG - примитив/литерал вместо сигнала, и validators прямо в layout-узле
+const schema = {
+  name:  '',                                       // нет привязки к сигналу
+  email: { value: '', validators: [required()] },  // value — литерал, а validators в layout больше нет
+};
+
+// CORRECT - layout только связывает поле с сигналом модели...
+const layout = {
+  name:  { value: model.$.name,  component: Input, componentProps: { label: 'Name' } },
+  email: { value: model.$.email, component: Input, componentProps: { label: 'Email' } },
+};
+
+// ...а правила — отдельная ambient-схема (прогоняется раннером validateModel):
+const validation = defineValidationSchema<Form>(({ model }) => {
+  validate(model.$.email, [required({ message: 'Email обязателен' }), email()]);
+});
+```
+
+### Behaviors Common Mistakes
+
+```typescript
+// WRONG - строковые пути и (form) => ... — старый API
+enableWhen(path.city, (form) => Boolean(form.country));
+
+// CORRECT - сигналы модели, условие читает model
+enableWhen(model.$.city, () => Boolean(model.country), { resetOnDisable: true });
+```
+
+Поведение **не владеет** валидацией. Чтобы поведение инициировало прогон схемы — мост
+`revalidateWhen` (validate/submit сами схему не запускают):
+
+```typescript
+// CORRECT - поведение дёргает внешний раннер валидации при изменении зависимости
+revalidateWhen([model.$.password], () => void validateModel(model, validation));
+```