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

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

@@ -2,42 +2,59 @@
 
 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.
+`index.tsx`. Naming rule: **`form.<role>` is a form artefact, the suffix names its role** —
+`form.schema.*` (layout), `form.behavior.ts` (form behavior: model operators AND schema-node rules
+such as `hideWhen` / `onComponentEvent`), `form.validation.ts` (validation rules), and the optional
+`form.flow.ts` (the steps of a wizard) and `form.messages.ts` (the issue-message dictionary); every
+other file has no prefix. There is one behavior per form:
+the former render-layer file `form.render.ts` (and `renderer.behavior.ts`) is retired — its node
+rules move into `form.behavior.ts`. The old `renderer.schema.*` / `validation.ts` names, and the
+retired `form.render.ts` / `wizard.tsx` / `renderer.wizard.tsx`, are accepted with a warning. No
+folders until the form grows (see "Scaling up" below). Arrays are declared in `form.schema.ts` and
+rendered with `FieldArray` / `FieldArraySection` — no per-step component files.
 
 ```
 src/
-├── components/ui/                # App-wide reusable UI (FormField, FormArraySection, ...)
+├── components/ui/                # App-wide reusable UI (FormField, FieldArraySection, ...)
 │
 ├── 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 }
+│       ├── index.tsx             # entry + whole form: ONE createForm call → <FormWizard flow={bundle.flow}> with all steps inline
+│       ├── types.ts              # form type (interface or type) + enums + { value, label } option type + constant dictionaries
+│       ├── model.ts              # createModel + initial values + arrayOf(blank) templates of array rows
+│       ├── form.schema.ts        # schema builder (model) => node tree: { model: model.$.x, component, componentProps }
+│       ├── form.behavior.ts      # defineFormBehavior: compute / enableWhen / copyFrom / onChange + hideWhen / onComponentEvent
+│       ├── form.validation.ts    # rules of each step (exported) + extras
+│       ├── form.flow.ts          # optional, wizard: flow { steps: [{ id, rules }] }
+│       ├── form.messages.ts      # optional: defineIssueMessages dictionary (issue texts by code)
 │       ├── data-sources.ts       # options + async loaders (dataSources)
 │       └── api.ts                # submit + prefill/load
 ```
 
+Optionally a wizard may keep its steps in folders: `steps/index.ts` (step order) and one
+`steps/<slug>/` folder per step (`<slug>` — kebab-case of the step title, no number) with the same
+file names — `form.schema.ts`, `form.validation.ts`, `form.behavior.ts` — for the step only;
+everything that crosses steps stays in the root files.
+
 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
+`index.tsx`; validation rules are a single `form.validation.ts`, the steps — `form.flow.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 = {
+// forms/credit-application/types.ts — `interface` and `type` both work
+export interface CreditApplication {
   loanType: LoanType;
-  loanAmount: number | null;
+  loanAmount: number | null; // an empty number input is `null`
   // ...
-};
+}
+// computed fields (targets of `compute`) — a separate type; the form is the intersection
+export interface CreditApplicationDerived {
+  monthlyPayment: number;
+  // ...
+}
+export type CreditApplicationForm = CreditApplication & CreditApplicationDerived;
 
 // forms/credit-application/model.ts
 import { createModel, type FormModel } from '@reformer/core';
@@ -45,81 +62,218 @@ 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 },
+import type { FormModel, FormSchemaNode } from '@reformer/core';
+export const creditApplicationSchema = (
+  model: FormModel<CreditApplicationForm>
+): FormSchemaNode => ({
+  // Nested nodes live in `children` only — not in componentProps, not under arbitrary keys.
+  children: [
+    { model: model.$.loanType, component: SelectAsync, componentProps: { /* ... */ } }, // field
+    { model: model.$.registrationAddress, part: address }, // sub-form: group + part
+    { model: model.$.properties, component: FieldArray, item: propertyRow }, // array of sub-forms
+  ],
 });
 
-// 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/form.behavior.ts — ONE behavior: model operators and node rules
+import { defineFormBehavior, compute, enableWhen, hideWhen } from '@reformer/core/behaviors';
+export const creditApplicationBehavior = defineFormBehavior<CreditApplicationForm>(
+  ({ model, schema }) => {
+    compute(model.$.monthlyPayment, () => computeMonthlyPayment(model));
+    enableWhen([model.$.propertyValue], () => model.loanType === 'mortgage', { resetOnDisable: true });
+    hideWhen(schema.node('mortgage'), () => model.loanType !== 'mortgage'); // executed by the renderer
+  }
+);
+
+// forms/credit-application/form.validation.ts — step rules (exported) and the extras
+import type { FormValidation } from '@reformer/core';
+import { defineValidation } from '@reformer/core/validation';
+export const loanRules = defineValidation<CreditApplicationForm>(({ model }) => { /* ... */ });
+export const contactsRules = defineValidation<CreditApplicationForm>(({ model }) => { /* ... */ });
+export const creditApplicationValidation: FormValidation<CreditApplicationForm> = {
+  extras: crossStepRules, // checked only as a whole (submit)
+};
+
+// forms/credit-application/form.flow.ts — the steps of the wizard
+import type { FormFlowConfig } from '@reformer/core';
+import { loanRules, contactsRules } from './form.validation';
+export const creditApplicationFlow: FormFlowConfig<CreditApplicationForm> = {
+  steps: [
+    { id: 'loan', rules: loanRules }, // id = selector of the step node in form.schema.ts
+    { id: 'contacts', rules: contactsRules },
+  ],
+};
+
+// forms/credit-application/form.messages.ts — the issue texts by code
+import { defineIssueMessages } from '@reformer/core/i18n';
+export const creditApplicationMessages = defineIssueMessages({
+  'loanAmount.required': 'Укажите сумму кредита',
 });
 
 // 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 });
-};
+// ONE call: model + form + behavior + validation + flow. In the page: useFormBundle(createCreditApplicationForm).
+export const createCreditApplicationForm = () =>
+  createForm<CreditApplicationForm>({
+    model: createCreditApplicationModel(),
+    schema: creditApplicationSchema,          // builder (model) => tree
+    behavior: creditApplicationBehavior,
+    validation: creditApplicationValidation,  // { extras } — rules outside the steps
+    flow: creditApplicationFlow,              // steps → bundle.flow, bundle.validateStep(id)
+  });
+// The page: <ValidationMessagesProvider messages={creditApplicationMessages}> around the form,
+// <FormWizard form={bundle.form} flow={bundle.flow} … onSubmit={() => bundle.submission.submit(api.send)} />.
 ```
 
 ### 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.
+When the flat module gets unwieldy — a multi-step wizard, sub-forms reused across steps, rules
+that outgrow one file — split it by **concern**, one folder per layer. Each layer answers one
+question about the form:
+
+| Folder         | Question it answers                                     |
+| -------------- | ------------------------------------------------------- |
+| `model/`       | What data does the form hold, and what does it start as |
+| `schema/`      | How is the form laid out                                |
+| `validation/`  | What is a valid value                                   |
+| `behavior/`    | How do values and field state react to each other       |
+| `flow/`        | Which steps does the user walk through, in what order   |
+| `application/` | How is the form assembled, loaded and submitted         |
 
 ```
 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
+└── [form-name]/
+    ├── [FormName]Form.tsx           # Entry: builds the form, renders FormWizard + step components
+    │
+    ├── model/
+    │   ├── model.ts                 # create[FormName]Model — the reactive model
+    │   ├── initial-value.ts         # initial values; arrays via arrayOf(blank)
+    │   ├── predicates.ts            # conditions shared by behavior, validation and JSX
+    │   └── factories/               # blank values of sub-forms and array rows
+    │       ├── address.ts
+    │       └── property.ts
+    │
+    ├── schema/
+    │   ├── form.ts                  # the tree: loading → wizard → steps taken from the flow
+    │   ├── steps/                   # content of each step (an array of nodes)
+    │   │   ├── loan.ts
+    │   │   └── contacts.ts
+    │   └── sections/                # sections, sub-forms (part) and array rows (item)
+    │       ├── address.ts
+    │       └── property.ts
     │
-    ├── 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
+    ├── validation/
+    │   ├── form.ts                  # FormValidation: { extras } — rules outside the steps
+    │   ├── messages.ts              # defineIssueMessages: issue code → text
+    │   ├── common/                  # shared rule sets, rules of sub-forms and array rows
+    │   │   ├── rules.ts
+    │   │   └── address.ts
+    │   ├── loan.ts                  # rules of one step — one file per step
+    │   ├── contacts.ts
+    │   └── cross-step.ts            # rules of the whole form (checked on 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 })
+    ├── behavior/
+    │   ├── index.ts                 # the form behavior, composed of the parts below
+    │   ├── derived.ts               # computed fields
+    │   ├── conditions.ts            # enabling fields and hiding sections
+    │   ├── synchronization.ts       # copies, clearing lists
+    │   ├── dynamic-options.ts       # options and limits that depend on values
+    │   └── operators.ts             # custom operators built on the built-in ones
     │
-    └── components/
-        ├── steps/               # One component per wizard step
-        ├── nested-forms/        # Reusable sub-forms (Address, PersonalData, ...)
-        └── ui/                  # Form-specific helper blocks (summary, warnings, sections)
+    ├── flow/
+    │   └── [form-name]-flow.ts      # the list of steps: selector, title, icon, content, rules
+    │                                #   + FormFlowConfig { steps: [{ id, rules }] } for createForm
+    │
+    ├── application/
+    │   ├── create.ts                # ONE createForm call shared by every way of rendering
+    │   ├── load.ts                  # network: fetch the entity and dictionaries
+    │   ├── mapping.ts               # server response → model (model.patch + captureInitial)
+    │   ├── payload.ts               # form values → request body: drops the computed fields
+    │   ├── submit.ts                # sending and reporting the outcome (handler of bundle.submission.submit)
+    │   └── renderer.ts              # node rules for the renderer: loading, submit, navigation (setup)
+    │
+    ├── components/                  # React layout: steps/, nested-forms/, ui/
+    ├── api/                         # HTTP calls
+    └── types/  constants/  utils/   # form type, option dictionaries, pure calculations
 ```
 
-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.
+Dependencies point one way: `application → flow → schema/steps, validation/<step>`;
+`application → behavior → model`. Nothing below `application/` knows the entity id, the network or
+the wizard — the behavior is static and reusable.
+
+**The flow is the single place a step is declared.** One entry carries the step's `selector`,
+title, icon, content and rules, so the step nodes of the schema, the `flow` of the assembly and
+the wizard steps of a hand-written React page are all derived from the same list — there is
+nowhere to pair the layout of one step with the rules of another:
+
+```typescript
+// flow/credit-application-flow.ts
+export const creditApplicationFlow = [
+  { selector: 'loan', title: 'Loan', icon: '💰', content: loanStep, rules: loanRules },
+  { selector: 'contacts', title: 'Contacts', icon: '📞', content: contactsStep, rules: contactsRules },
+] as const satisfies readonly FlowStep[];
+
+// the same list → the flow of createForm; the step id is the step selector
+export const creditApplicationFlowSteps: FormFlowConfig<CreditApplicationForm> = {
+  steps: creditApplicationFlow.map((step) => ({ id: step.selector, rules: step.rules })),
+};
+
+// schema/form.ts — step nodes come from the flow
+children: creditApplicationFlow.map((step) => ({
+  selector: step.selector,
+  component: Step,
+  componentProps: { title: step.title, icon: step.icon },
+  children: step.content(model),
+})),
+
+// validation/form.ts — only the rules outside the steps
+export const creditApplicationValidation: FormValidation<CreditApplicationForm> = {
+  extras: crossStepRules,
+};
+
+// application/create.ts
+createForm<CreditApplicationForm>({
+  model: createCreditApplicationModel(),
+  schema: creditApplicationSchema,
+  behavior: creditApplicationBehavior,
+  validation: creditApplicationValidation,
+  flow: creditApplicationFlowSteps,
+});
+```
+
+**Texts of the issues live in `validation/messages.ts`.** Rules carry codes
+(`required({ code: 'loanAmount.required' })`), the dictionary maps a code to its text, and every
+way of rendering wraps the form in `<ValidationMessagesProvider messages={…}>` from
+`@reformer/cdk` — the texts are the same in hand-written React, renderer-react and renderer-json.
+
+**Conditions live in `model/predicates.ts`** as pure functions over values
+(`isMortgage(loanType)`). Behavior (`enableWhen`, `hideWhen`), validation (`validateWhen`) and the
+JSX of a step call the same function — a condition is written once.
+
+**Loading and submitting are not behavior.** They belong to `application/`: the page (or, for the
+renderer, `application/renderer.ts` passed as `setup`) calls `load`, hands the response to
+`mapping`, and sends through `bundle.submission.submit(handler)` — one run of all the rules, the
+handler is called only when the form is valid. Written into the model with `model.patch` followed
+by `model.captureInitial()`, the loaded values become the form's starting point: the form is not
+dirty, and `model.reset()` returns to them. The handler receives `model.get()` — the whole model,
+disabled fields included; `application/payload.ts` drops the fields the server does not expect
+(computed ones) before the request.
+
+Rule of thumb for this layout: **one folder per question; a step is declared once, in the flow;
+the root holds only the entry component.**
 
 ### 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/` |
+| **Minimalist (flat)** | **Default.** One file per concern at the module root (`types` / `model` / `form.schema` / `form.behavior` / `form.validation` / `data-sources` / `api`) + `index.tsx` with all steps inline |
+| Folders (`model/` + `schema/` + `validation/` + `behavior/` + `flow/` + `application/`) | Large forms: one folder per layer, a step declared once in the flow, reusable sections and rules |
 
-> 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`.
+> The leading layout of the MCP generators is configurable: set `REFORMER_FORM_LAYOUT`
+> (`minimalist` | `folders`) when registering the MCP server. 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`).
+> The MCP layout check (`validate_form` with `kind: "layout"`) verifies the flat layout file names
+> (and the optional `steps/<slug>/` folders); the folders layout is recognized by its top-level
+> folders only. Cross-target variants (renderer-react: the same files; renderer-json: plus
+> `registry.ts`, and `form.schema.ts` holds the JSON-DSL document) are described in the
+> **form-directory-layout** guide (`find_recipe directory-layout`).

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

@@ -2,12 +2,13 @@
 
 > **Default rule (read first)**: для UI используй `FormField` из
 > [`@reformer/ui-kit`](../../reformer-ui-kit/) — он покрывает 95% случаев одной
-> строкой `<FormField control={form.x} />`. Свои field-обёртки пиши ТОЛЬКО если
+> строкой `<FormField control={form.x} />`. Свои обёртки поля пиши ТОЛЬКО если
 > ui-kit не подходит (другая design system, особый low-level input).
 >
 > Канонический schema-driven подход:
 >
-> - **компонент** объявляется в схеме как `component: Input` (или `Select`, `Checkbox`, etc.)
+> - **компонент** объявляется в схеме как `component: Input` (или `SelectAsync`, `CheckboxWithLabel`, …) —
+>   сам компонент кита, отдельных «field-версий» нет: связывает его с полем обёртка (`FormField`)
 > - **пропсы** компонента — в `componentProps: { label, placeholder, options, type, ... }`
 > - **JSX рендерит**: `<FormField control={form.x} />` БЕЗ дополнительных props
 >
@@ -17,44 +18,48 @@
 ### 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';
+import { createForm, type FormModel, type FormSchemaNode } from '@reformer/core';
+import { useFormBundle } from '@reformer/core/react';
+import { FormField, Input, SelectAsync, CheckboxWithLabel, Button } from '@reformer/ui-kit';
 
-type RegistrationForm = {
+interface 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 });
-  }, []);
+  // useFormBundle вызывает фабрику ровно один раз и держит сборку стабильной между рендерами
+  const { form } = useFormBundle(() =>
+    createForm<RegistrationForm>({
+      initial: { email: '', country: 'ru', agree: false },
+      schema: (model: FormModel<RegistrationForm>): FormSchemaNode => ({
+        children: [
+          {
+            model: model.$.email,
+            component: Input,
+            componentProps: { label: 'Email', type: 'email', placeholder: 'you@example.com' },
+          },
+          {
+            model: model.$.country,
+            component: SelectAsync,
+            componentProps: {
+              label: 'Country',
+              options: [
+                { value: 'ru', label: 'Россия' },
+                { value: 'by', label: 'Беларусь' },
+              ],
+            },
+          },
+          {
+            model: model.$.agree,
+            component: CheckboxWithLabel,
+            componentProps: { label: 'I agree to terms' },
+          },
+        ],
+      }),
+    })
+  );
 
   return (
     <form>
@@ -69,7 +74,8 @@ function RegistrationPage() {
 
 `FormField` сам читает `componentProps.label`, `componentProps.placeholder`,
 `componentProps.options` через `useFormControl(...).componentProps` и применяет
-их к нужному `<input>`/`<select>`/etc. Error rendering, `pending` для async-валидаций,
+их к нужному `<input>`/`<select>`/etc. Текст замечания (по коду — словарь формы из
+`ValidationMessagesProvider messages`, затем локаль), `pending` для async-валидаций,
 `data-testid` для e2e — всё из коробки.
 
 ### Anti-patterns (не делай так)
@@ -92,7 +98,7 @@ function RegistrationPage() {
 ✅ Всё это в схеме:
 
 ```ts
-{ email: { component: Input, componentProps: { label: 'Email' } } }
+{ model: model.$.email, component: Input, componentProps: { label: 'Email' } }
 ```
 
 ```tsx
@@ -113,7 +119,8 @@ import { InputMask } from 'react-input-mask';
 ```
 
 `children` оборачивается в `CdkFormField.Control asChild` и получает все нужные
-props (`value`, `onChange`, `onBlur`, `aria-invalid`).
+props (`value`, `onChange`, `onBlur`, `aria-invalid`) — в диалекте ребёнка, если тот объявил
+статику `reformerAdapter` (`defineFieldControl` из `@reformer/ui-kit/fields`), иначе value-based.
 
 ### Advanced — write your own from scratch (rare)
 
@@ -122,13 +129,15 @@ props (`value`, `onChange`, `onBlur`, `aria-invalid`).
 из `componentProps`, не из JSX-props.
 
 ```tsx
-import type { FieldNode } from '@reformer/core';
-import { useFormControl } from '@reformer/core';
+import type { FormControl } from '@reformer/core';
+import { useFormControl, useIssueMessage } from '@reformer/core/react';
+import { formMessages } from './form.validation'; // defineIssueMessages — константа модуля
 
-type MyFormFieldProps<T> = { control: FieldNode<T> }; // ← ОДИН prop
+type MyFormFieldProps<T> = { control: FormControl<T> }; // ← ОДИН prop
 
 function MyFormField<T>({ control }: MyFormFieldProps<T>) {
-  const { value, errors, disabled, shouldShowError, componentProps } = useFormControl(control);
+  const { value, issues, disabled, shouldShowIssues, componentProps } = useFormControl(control);
+  const message = useIssueMessage(formMessages); // текст замечания по коду
   // componentProps = { label, placeholder, type, options, ... } — из СХЕМЫ
   const cp = (componentProps ?? {}) as Record<string, unknown>;
 
@@ -143,24 +152,54 @@ function MyFormField<T>({ control }: MyFormFieldProps<T>) {
         onChange={(e) => (control.setValue as (v: unknown) => void)(e.target.value)}
         onBlur={() => control.markAsTouched()}
       />
-      {shouldShowError && errors[0] && <span>{errors[0].message}</span>}
+      {/* shouldShowIssues — ошибки и предупреждения; shouldShowError — для aria-invalid */}
+      {shouldShowIssues && issues[0] && <span>{message(issues[0])}</span>}
     </label>
   );
 }
 ```
 
+Внутри дерева с `ValidationMessagesProvider` (cdk) вместо `useIssueMessage(formMessages)` берут
+`useIssueMessageResolver()` из `@reformer/cdk` — он учитывает словари всех провайдеров выше. См.
+`36-issue-messages.md`.
+
 Использование — как у `FormField`:
 
 ```tsx
 <MyFormField control={form.email} /> // ← без label-prop
 ```
 
+### Связывание поля с контролом — `FieldAdapter` (`@reformer/core/react`)
+
+Контролы говорят на разных диалектах (`checked` + `onCheckedChange`, `onValueChange`, DOM-событие
+в `onChange`), форма — на value-based seam (`value` + `onChange(value)` + `onBlur`). Перевод
+описывает `FieldAdapter` (`valueProp`, `changeProp`, `fromEmit`, `toValue`, `bindBlur`, `strip`,
+`passControl` — все необязательны). Компонент объявляет его статикой `reformerAdapter`, а обёртка
+поля (`FormField.Control` из `@reformer/cdk`, рендерер `@reformer/renderer-react`) читает статику
+и связывает поле сама — отдельные «field-версии» компонентов не нужны.
+
+| Символ                        | Назначение                                                                  |
+| ----------------------------- | --------------------------------------------------------------------------- |
+| `FieldAdapter`                | Тип адаптера: диалект контрола                                              |
+| `getFieldAdapter(component)`  | Статика `component.reformerAdapter` либо `undefined`                        |
+| `bindFieldProps(adapter, seam, props)` | Props контрола под адаптер (без адаптера — seam как есть)          |
+| `FieldHandle`                 | Императивный handle поля: `focus` / `blur` / `scrollIntoView` / `getElement` |
+| `makeElementFieldHandle(ref)` | Базовый `FieldHandle` из DOM-узла                                           |
+| `useFieldHandleRef(outerRef)` | Ref для контрола + публикация handle потребителю (строит ОБЁРТКА поля)     |
+
+В приложении обычно достаточно `defineFieldControl(MyControl, { adapter })` из
+`@reformer/ui-kit/fields` (плюс готовые пресеты `checkedAdapter`, `valueChangeAdapter`, …); для
+компонентов чужой библиотеки без статики — `RendererSettings.resolveFieldAdapter`.
+
 ### Integration with UI libraries (shadcn etc.)
 
 > **Через рендерер — без обёртки.** Если ты рендеришь форму через `@reformer/renderer-react` /
 > `@reformer/renderer-json`, вместо ручной обёртки на каждый контрол можно зарегистрировать сырой
 > компонент и передать `settings.resolveFieldAdapter` — рендерер сам сведёт value-seam к диалекту
-> контрола. Ручная обёртка на `useFormControl` (ниже) нужна для прямого JSX без рендерера.
+> контрола. Свой компонент можно подготовить и один раз — статикой
+> `defineFieldControl(MyInput, { adapter })` из `@reformer/ui-kit/fields`: его поймут и рендерер,
+> и `FormField.Control` из `@reformer/cdk`. Ручная обёртка на `useFormControl` (ниже) нужна для
+> прямого JSX без `FormField` и рендерера.
 
 Если есть существующая design system — оборачивай её компоненты в один
 `MyFormField` (как выше) и используй один прop `control`. Не множь обёртки на
@@ -170,8 +209,9 @@ function MyFormField<T>({ control }: MyFormFieldProps<T>) {
 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);
+function ShadcnFormField({ control }: { control: FormControl<string> }) {
+  const { value, issues, disabled, shouldShowIssues, componentProps } = useFormControl(control);
+  const message = useIssueMessage(formMessages);
   const cp = (componentProps ?? {}) as Record<string, unknown>;
 
   return (
@@ -182,7 +222,7 @@ function ShadcnFormField({ control }: { control: FieldNode<string> }) {
         onChange={(e) => control.setValue(e.target.value)}
         disabled={disabled}
       />
-      {errors[0] && <p className="text-red-500">{errors[0].message}</p>}
+      {shouldShowIssues && issues[0] && <p className="text-red-500">{message(issues[0])}</p>}
     </div>
   );
 }