@reformer/ui-kit 7.0.0-beta.1 → 7.0.0-beta.3

package/llms.txt

@@ -84,34 +84,53 @@ import { Button } from '@reformer/ui-kit/button';
 
 ## 3. Quick Start
 
-Минимальная форма из двух полей с валидацией и сабмитом. `FormField`
-самостоятельно подцепляет `value`/`error`/`pending` через `@reformer/cdk`:
+Минимальная форма из двух полей с валидацией и сабмитом (архитектура M1:
+`createModel` → схема → `createForm({ model, schema })` → `validateFormModel`).
+`FormField` самостоятельно подцепляет `value`/`error`/`pending` через `@reformer/cdk`:
 
 ```tsx
 import { useMemo } from 'react';
-import { createForm, type FormSchema } from '@reformer/core';
-import { Button, FormField, Input } from '@reformer/ui-kit';
-import { object, string, email, minLength } from 'valibot';
+import { createModel, createForm, validateFormModel } from '@reformer/core';
+import { required, email, minLength } from '@reformer/core/validators';
+import { Button, FormField, Input, InputPassword } from '@reformer/ui-kit';
 
-interface RegistrationForm {
+type RegistrationForm = {
   email: string;
   password: string;
-}
+};
 
 function RegistrationPage() {
-  const form = useMemo(
-    () =>
-      createForm<FormSchema<RegistrationForm>>({
-        email: { component: Input, validations: [string(), email()] },
-        password: { component: Input, validations: [string(), minLength(8)] },
-      }),
-    []
-  );
+  const { model, form, schema } = useMemo(() => {
+    // 1) Модель — источник истины значений.
+    const model = createModel<RegistrationForm>({ email: '', password: '' });
+    // 2) Схема: лист = { value: сигнал модели, component, componentProps?, validators }.
+    const schema = {
+      children: [
+        {
+          value: model.$.email,
+          component: Input,
+          componentProps: { label: 'Email', type: 'email', testId: 'email' },
+          validators: [required({ message: 'Email обязателен' }), email()],
+        },
+        {
+          value: model.$.password,
+          component: InputPassword,
+          componentProps: { label: 'Пароль', testId: 'password' },
+          validators: [required({ message: 'Пароль обязателен' }), minLength(8)],
+        },
+      ],
+    };
+    // 3) createForm привязывает ноды к сигналам модели → FormProxy.
+    const form = createForm<RegistrationForm>({ model, schema });
+    return { model, form, schema };
+  }, []);
 
   const onSubmit = async () => {
     form.markAsTouched();
-    if (!(await form.validate())) return;
-    console.log('values', form.getValue());
+    // 4) Валидация всей модели по схеме.
+    const res = await validateFormModel(model, schema);
+    if (!res.valid) return;
+    console.log('values', model.get());
   };
 
   return (
@@ -122,8 +141,8 @@ function RegistrationPage() {
       }}
       className="space-y-4 max-w-md"
     >
-      <FormField control={form.email} testId="email" />
-      <FormField control={form.password} testId="password" />
+      <FormField control={form.email} />
+      <FormField control={form.password} />
       <Button type="submit">Зарегистрироваться</Button>
     </form>
   );
@@ -217,18 +236,29 @@ import { Input } from '@reformer/ui-kit';
 > прокидывается — `onChange` просто не вызывается. Поэтому в форме поле должно
 > иметь тип `number | null`, а не `number`.
 
-Email-валидация на уровне формы:
+Email-валидация на уровне формы (M1: `createModel` → схема с листом
+`{ value: model.$.email, component, validators }` → `createForm({ model, schema })`):
 
 ```tsx
-import { createForm, type FormSchema } from '@reformer/core';
-import { Input } from '@reformer/ui-kit';
-import { string, email, pipe } from 'valibot';
-
-const form = createForm<FormSchema<{ email: string }>>({
-  email: { component: Input, validations: [pipe(string(), email())] },
-});
+import { createModel, createForm } from '@reformer/core';
+import { required, email } from '@reformer/core/validators';
+import { Input, FormField } from '@reformer/ui-kit';
+
+const model = createModel<{ email: string }>({ email: '' });
+const schema = {
+  children: [
+    {
+      value: model.$.email,
+      component: Input,
+      componentProps: { type: 'email', label: 'Email', testId: 'email' },
+      validators: [required(), email()],
+    },
+  ],
+};
+const form = createForm<{ email: string }>({ model, schema });
 
-<Input value={form.email.value} onChange={form.email.setValue} type="email" />;
+// Через FormField значение/ошибки подцепляются автоматически:
+<FormField control={form.email} testId="email" />;
 ```
 
 ### Anti-patterns
@@ -291,7 +321,7 @@ import { InputMask } from '@reformer/ui-kit';
   нужно делать в behavior `transformValue` или при сабмите.
 - Использовать `mask` для сложных правил (валидация диапазонов, контрольные
   суммы) — `InputMask` только направляет ввод, не валидирует. Валидацию вешать
-  через `validations` в schema поля.
+  через массив `validators` листа схемы (`validateFormModel`).
 
 ## 9. InputPassword
 
@@ -398,14 +428,13 @@ import { Textarea } from '@reformer/ui-kit';
   имеет логики авто-роста.
 - Полагаться на `maxLength` как валидатор: это soft-лимит на ввод; для бизнес-
   правил (например, `длина <= 500 на русском, <= 1000 на английском`) ставить
-  `validations` в `createForm`.
+  `validators` в лист схемы (`{ value: model.$.field, component, validators }`).
 
 ## 11. See also
 
 - [03-choice-fields.md](03-choice-fields.md) — Select, Checkbox, RadioGroup.
 - [05-form-field-integration.md](05-form-field-integration.md) — как все эти поля автоматически подключаются через `FormField`.
 - [06-troubleshooting.md](06-troubleshooting.md) — «number возвращает строку», «mask пропускает символы», «password toggle не появляется».
-- Эталон: `RegistrationForm.tsx`, `credit-application-schema.ts` (monorepo examples).
 
 ## 12. Checkbox
 
@@ -453,12 +482,16 @@ import { Checkbox } from '@reformer/ui-kit';
 label сверху):
 
 ```tsx
-import { createForm, type FormSchema } from '@reformer/core';
+import { createModel, createForm } from '@reformer/core';
 import { Checkbox, FormField } from '@reformer/ui-kit';
 
-const form = createForm<FormSchema<{ accept: boolean }>>({
-  accept: { component: Checkbox, value: false, componentProps: { label: 'Принять' } },
-});
+const model = createModel<{ accept: boolean }>({ accept: false });
+const schema = {
+  children: [
+    { value: model.$.accept, component: Checkbox, componentProps: { label: 'Принять' } },
+  ],
+};
+const form = createForm<{ accept: boolean }>({ model, schema });
 
 <FormField control={form.accept} testId="accept" />;
 ```
@@ -534,13 +567,19 @@ const LOAN_TYPES = [
 В составе формы:
 
 ```tsx
-const form = createForm<FormSchema<{ loanType: string }>>({
-  loanType: {
-    component: RadioGroup,
-    value: 'consumer',
-    componentProps: { options: LOAN_TYPES },
-  },
-});
+import { createModel, createForm } from '@reformer/core';
+
+const model = createModel<{ loanType: string }>({ loanType: 'consumer' });
+const schema = {
+  children: [
+    {
+      value: model.$.loanType,
+      component: RadioGroup,
+      componentProps: { options: LOAN_TYPES },
+    },
+  ],
+};
+const form = createForm<{ loanType: string }>({ model, schema });
 
 <FormField control={form.loanType} testId="loan-type" />;
 ```
@@ -562,17 +601,29 @@ const form = createForm<FormSchema<{ loanType: string }>>({
 данных:
 
 - **Inline**: `options={[…]}` — массив `{ value, label, group? }`.
-- **Resource**: `resource={{ type, load }}` — асинхронная загрузка (см. ниже).
+- **Resource**: `resource={{ type, load }}` — асинхронная загрузка со стратегией `type`:
+  - `static` — один `load({})` при маунте, без поиска (снимок);
+  - `preload` — грузит всё сразу, поиск фильтрует опции **на клиенте**;
+  - `partial` — **серверные** поиск (`load({ search })` с debounce ~300 мс) и
+    пагинация (`load({ page })` по мере прокрутки списка до `totalCount`).
+
+  Для `preload`/`partial` в дропдауне появляется поле поиска.
 
 ### API
 
 ```typescript
 interface ResourceConfig<T> {
+  /** Стратегия загрузки. Если не задана — трактуется как `static`. */
   type: 'static' | 'preload' | 'partial';
-  load: (params?: ResourceLoadParams) => Promise<{
+  load: (params?: {
+    search?: string; // серверная фильтрация (partial)
+    page?: number; // 1-based, пагинация (partial)
+    pageSize?: number;
+  }) => Promise<{
     items: Array<{ id: string | number; label: string; value: T; group?: string }>;
-    totalCount: number;
+    totalCount: number; // общее число опций — для пагинации (partial)
   }>;
+  pageSize?: number; // размер страницы для partial (по умолчанию 20)
 }
 
 interface SelectProps<T> {
@@ -593,7 +644,7 @@ interface SelectProps<T> {
 | Prop          | Тип                               | Default                 | Описание                                                                                                                                        |
 | ------------- | --------------------------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
 | `options`     | `Array<{value,label,group?}>`     | —                       | Inline-варианты. `value` приводится к строке. `group` опционально — варианты с одинаковым `group` объединяются в `SelectGroup` с `SelectLabel`. |
-| `resource`    | `ResourceConfig<T>`               | —                       | Асинхронный источник. На маунт вызывается `resource.load({})`. На время загрузки `Select` показывает `Loading...` и блокируется.                |
+| `resource`    | `ResourceConfig<T>`               | —                       | Асинхронный источник со стратегией `type` (`static`/`preload`/`partial`). Во время первичной загрузки `Select` показывает `Loading...` и блокируется; при пагинации (`partial`) внизу списка — `Loading more...`.                |
 | `value`       | `string \| null`                  | `null`                  | Выбранное значение (всегда строка из `option.value`).                                                                                           |
 | `onChange`    | `(value: string \| null) => void` | —                       | Срабатывает при выборе. При нажатии на крестик (`clearable`) приходит `null`.                                                                   |
 | `placeholder` | `string`                          | `'Select an option...'` | Подсказка в триггере.                                                                                                                           |
@@ -634,10 +685,10 @@ import { Select } from '@reformer/ui-kit';
 />;
 ```
 
-Async `resource` (пример: список банков):
+Async `resource`, стратегия `preload` (грузим всё, поиск на клиенте):
 
 ```tsx
-import { Select, type ResourceConfig } from '@reformer/ui-kit/select';
+import { Select, type ResourceConfig } from '@reformer/ui-kit';
 
 const banksResource: ResourceConfig<string> = {
   type: 'preload',
@@ -654,6 +705,26 @@ const banksResource: ResourceConfig<string> = {
 <Select value={bankId} onChange={setBankId} resource={banksResource} />;
 ```
 
+Стратегия `partial` (серверные поиск + пагинация больших списков):
+
+```tsx
+const usersResource: ResourceConfig<string> = {
+  type: 'partial',
+  pageSize: 20,
+  load: async ({ search = '', page = 1, pageSize = 20 } = {}) => {
+    const res = await fetch(`/api/users?q=${search}&page=${page}&size=${pageSize}`);
+    const { rows, total }: { rows: Array<{ id: number; name: string }>; total: number } =
+      await res.json();
+    return {
+      items: rows.map((u) => ({ id: u.id, value: String(u.id), label: u.name })),
+      totalCount: total, // Select догружает страницы, пока items.length < totalCount
+    };
+  },
+};
+
+<Select value={userId} onChange={setUserId} resource={usersResource} clearable />;
+```
+
 Grouped options:
 
 ```tsx
@@ -687,18 +758,25 @@ Grouped options:
 В составе формы:
 
 ```tsx
-const form = createForm<FormSchema<{ city: string }>>({
-  city: {
-    component: Select,
-    componentProps: {
-      placeholder: 'Город',
-      options: [
-        { value: 'msk', label: 'Москва' },
-        { value: 'spb', label: 'Санкт-Петербург' },
-      ],
+import { createModel, createForm } from '@reformer/core';
+
+const model = createModel<{ city: string }>({ city: '' });
+const schema = {
+  children: [
+    {
+      value: model.$.city,
+      component: Select,
+      componentProps: {
+        placeholder: 'Город',
+        options: [
+          { value: 'msk', label: 'Москва' },
+          { value: 'spb', label: 'Санкт-Петербург' },
+        ],
+      },
     },
-  },
-});
+  ],
+};
+const form = createForm<{ city: string }>({ model, schema });
 
 <FormField control={form.city} testId="city" />;
 ```
@@ -722,7 +800,6 @@ const form = createForm<FormSchema<{ city: string }>>({
 - [02-text-fields.md](02-text-fields.md) — `Input`, `InputMask`, `InputPassword`, `Textarea`.
 - [05-form-field-integration.md](05-form-field-integration.md) — `FormField` распознаёт `Checkbox` и не дублирует label.
 - [06-troubleshooting.md](06-troubleshooting.md) — «Select не показывает options», «options vs resource», «onBlur не срабатывает на Select/RadioGroup».
-- Эталон: `credit-application-schema.ts` (monorepo example) — большой пример с `Select` и `Checkbox` в реальной форме.
 
 ## 16. Button
 
@@ -1043,35 +1120,40 @@ interface FormFieldProps {
 
 ```tsx
 import { useMemo } from 'react';
-import { createForm, type FormSchema } from '@reformer/core';
+import { createModel, createForm } from '@reformer/core';
 import { Button, FormField, Input, Select } from '@reformer/ui-kit';
 
-interface RegistrationForm {
+type RegistrationForm = {
   email: string;
   country: string;
-}
+};
 
 function RegistrationPage() {
-  const form = useMemo(
-    () =>
-      createForm<FormSchema<RegistrationForm>>({
-        email: {
+  const form = useMemo(() => {
+    const model = createModel<RegistrationForm>({ email: '', country: '' });
+    const schema = {
+      children: [
+        {
+          value: model.$.email,
           component: Input,
-          componentProps: { label: 'Email', placeholder: 'you@example.com' },
+          componentProps: { label: 'Email', placeholder: 'you@example.com', testId: 'email' },
         },
-        country: {
+        {
+          value: model.$.country,
           component: Select,
           componentProps: {
             label: 'Страна',
+            testId: 'country',
             options: [
               { value: 'ru', label: 'Россия' },
               { value: 'by', label: 'Беларусь' },
             ],
           },
         },
-      }),
-    []
-  );
+      ],
+    };
+    return createForm<RegistrationForm>({ model, schema });
+  }, []);
 
   return (
     <form className="space-y-4">
@@ -1094,37 +1176,37 @@ function RegistrationPage() {
 
 ```tsx
 import { useMemo } from 'react';
+import { createForm } from '@reformer/core';
 import { FormRenderer, createRenderSchema } from '@reformer/renderer-react';
-import { FormField, Box, Section } from '@reformer/ui-kit';
-import { createCreditApplicationForm } from './schemas/create-credit-application-form';
+import { FormField, Input, Section } from '@reformer/ui-kit';
+import { createCreditApplicationModel } from './schemas/model';
 
 function CreditApplicationPage() {
-  const form = useMemo(() => createCreditApplicationForm(), []);
-  const schema = useMemo(
-    () =>
-      createRenderSchema((path) => ({
-        component: Section,
-        componentProps: { title: 'Заявка', className: 'space-y-4' },
-        children: [
-          { component: path.email },
-          { component: path.phone },
-          { component: path.amount },
-        ],
-      })),
-    []
-  );
+  const { form, schema } = useMemo(() => {
+    // M1: модель — источник истины; листья схемы ссылаются на её сигналы.
+    const model = createCreditApplicationModel();
+    const schema = createRenderSchema<CreditApplication>(() => ({
+      component: Section,
+      componentProps: { title: 'Заявка', className: 'space-y-4' },
+      children: [
+        { value: model.$.email, component: Input, componentProps: { testId: 'email' } },
+        { value: model.$.phone, component: Input, componentProps: { testId: 'phone' } },
+        { value: model.$.amount, component: Input, componentProps: { testId: 'amount' } },
+      ],
+    }));
+    const form = createForm<CreditApplication>({ model, schema });
+    return { form, schema };
+  }, []);
 
   // settings.fieldWrapper применяется к каждому field-узлу автоматически.
   return <FormRenderer render={schema} settings={{ fieldWrapper: FormField }} />;
 }
 ```
 
-Эталон: `CreditApplicationFormRenderer.tsx` (monorepo example).
-
-`testId` рендерер берёт из `componentProps.testId` поля schema:
+`testId` рендерер берёт из `componentProps.testId` листа schema:
 
 ```tsx
-{ component: itemPath.bank, componentProps: { testId: 'existingLoan-bank' } }
+{ value: itemModel.$.bank, component: Input, componentProps: { testId: 'existingLoan-bank' } }
 // → <FormField control={...} testId="existingLoan-bank" />
 // → data-testid="field-existingLoan-bank", "input-existingLoan-bank", ...
 ```
@@ -1164,15 +1246,20 @@ import { InputMask } from '@reformer/ui-kit/input-mask';
 верхний `Label`:
 
 ```tsx
+import { createModel, createForm } from '@reformer/core';
 import { Checkbox, FormField } from '@reformer/ui-kit';
 
-const form = createForm<FormSchema<{ accept: boolean }>>({
-  accept: {
-    component: Checkbox,
-    value: false,
-    componentProps: { label: 'Принимаю условия' },
-  },
-});
+const model = createModel<{ accept: boolean }>({ accept: false });
+const schema = {
+  children: [
+    {
+      value: model.$.accept,
+      component: Checkbox,
+      componentProps: { label: 'Принимаю условия' },
+    },
+  ],
+};
+const form = createForm<{ accept: boolean }>({ model, schema });
 
 <FormField control={form.accept} testId="accept" />;
 // рендерится только Checkbox с label справа + error снизу.
@@ -1207,7 +1294,6 @@ const form = createForm<FormSchema<{ accept: boolean }>>({
 - [04-layout-and-buttons.md](04-layout-and-buttons.md) — `Button` для submit/prev/next.
 - [06-troubleshooting.md](06-troubleshooting.md) — «label дублируется», «error не появляется», «FormField не подцепляет ошибки».
 - CDK-хуки: [@reformer/cdk/form-field](../../../reformer-cdk/docs/llms/) (`FormField.Root`, `useFormFieldContext`).
-- Эталон: `CreditApplicationFormRenderer.tsx` (monorepo example) — `FormField` как `fieldWrapper` целой multi-step формы.
 
 ## 25. 1. `Input type="number"` возвращает строку, а не число (или `null`)
 
@@ -1323,14 +1409,17 @@ const MyLink = React.forwardRef<HTMLAnchorElement, { href: string; children: Rea
 
 - Передан `checked` вместо `value` (`<Checkbox checked={...}>`) — пропа
   `checked` нет, нужно `value`.
-- В schema поле имеет тип `boolean`, но `value: undefined` — компонент
-  отрендерится как `false`, и при `setValue(true)` без вмешательства React
-  re-render не произойдёт. Указывай `value: false` явно в schema.
+- В модели поле имеет тип `boolean`, но начальное значение `undefined` —
+  компонент отрендерится как `false`, и при `setValue(true)` без вмешательства
+  React re-render не произойдёт. Указывай `accept: false` явно в initial-значениях
+  модели.
 
 ```typescript
-const form = createForm<FormSchema<{ accept: boolean }>>({
-  accept: { component: Checkbox, value: false }, // не undefined!
-});
+const model = createModel<{ accept: boolean }>({ accept: false }); // false, не undefined!
+const schema = {
+  children: [{ value: model.$.accept, component: Checkbox }],
+};
+const form = createForm<{ accept: boolean }>({ model, schema });
 ```
 
 ## 30. 6. `FormField` не подцепляет ошибки (`<error>` не появляется)
@@ -1347,13 +1436,18 @@ const form = createForm<FormSchema<{ accept: boolean }>>({
   после `blur` или `markAsTouched`. Если submit-кнопка не вызывает
   `form.markAsTouched()` — пользователь вообще не увидит ошибку.
 
-**Решение.** На submit обязательно:
+**Решение.** На submit обязательно помечаем touched и валидируем модель по схеме
+(M1: `validateFormModel(model, schema)` — именно он прогоняет `validators` листьев
+и роутит ошибки в ноды):
 
 ```tsx
+import { validateFormModel } from '@reformer/core';
+
 const onSubmit = async () => {
   form.markAsTouched();
-  if (!(await form.validate())) return;
-  // ... отправка
+  const res = await validateFormModel(model, schema);
+  if (!res.valid) return;
+  // ... отправка (значения — из model.get())
 };
 ```
 
@@ -1465,14 +1559,14 @@ const hasValue = Boolean(value);
 
 ## 35. 11. JSON-renderer: `Select`-`options` хранятся в реестре, но в дропдауне пусто
 
-**Симптом.** Регистрируется source `LOAN_TYPES` через `reg.source('LOAN_TYPES', list)`,
+**Симптом.** Регистрируется dataSource `LOAN_TYPES` через `reg.dataSource('LOAN_TYPES', list)`,
 в JSON-схеме `componentProps: { options: '$LOAN_TYPES' }`, но опции пустые.
 
 **Причина.** `Select` ждёт `options: Array<{value, label, group?}>`, а из
 реестра приходит уже обработанная строкой ссылка `'$LOAN_TYPES'`. Нужен
-правильный синтаксис source-ссылки в реестре.
+правильный синтаксис dataSource-ссылки в реестре.
 
-**Решение.** Проверь convention для source-ссылок в
+**Решение.** Проверь convention для dataSource-ссылок в
 [`renderer-json/03-registry.md`](../../../reformer-renderer-json/docs/llms/03-registry.md).
 Внутри `Select` дальнейших магий нет — он просто читает `directOptions`
 один в один.
@@ -1486,19 +1580,47 @@ const hasValue = Boolean(value);
 ## 37. Базовое использование
 
 ```tsx
-import { useRef } from 'react';
+import { useMemo, useRef, type FC } from 'react';
 import { FormWizard, type FormWizardStep } from '@reformer/ui-kit/form-wizard';
-import type { FormWizardHandle } from '@reformer/cdk/form-wizard';
-import type { FormProxy, ValidationSchemaFn } from '@reformer/core';
+import { FormField, Input, Checkbox } from '@reformer/ui-kit';
+import type { FormWizardHandle, FormWizardConfig } from '@reformer/cdk/form-wizard';
+import { createModel, createForm, validateFormModel, type FormProxy } from '@reformer/core';
+import { required, email, minLength } from '@reformer/core/validators';
 
 // Используйте `type`, не `interface`, для structural-совместимости с
-// FormFields constraint внутри FormWizard generic'а.
+// constraint `T extends Record<string, any>` внутри FormWizard generic'а.
 type MyForm = {
   email: string;
   password: string;
   confirmation: boolean;
 };
 
+// M1: модель — источник истины значений; листья схемы ссылаются на её сигналы.
+const model = createModel<MyForm>({ email: '', password: '', confirmation: false });
+const schema = {
+  children: [
+    {
+      value: model.$.email,
+      component: Input,
+      componentProps: { label: 'Email', testId: 'email' },
+      validators: [required(), email()],
+    },
+    {
+      value: model.$.password,
+      component: Input,
+      componentProps: { label: 'Пароль', testId: 'password' },
+      validators: [required(), minLength(8)],
+    },
+    {
+      value: model.$.confirmation,
+      component: Checkbox,
+      componentProps: { label: 'Подтверждаю' },
+      validators: [required()],
+    },
+  ],
+};
+const form = createForm<MyForm>({ model, schema });
+
 const Step1: FC<{ control: FormProxy<MyForm> }> = ({ control }) => (
   <FormField control={control.email} />
 );
@@ -1513,25 +1635,20 @@ const steps: FormWizardStep<MyForm>[] = [
   { number: 3, title: 'Готово', icon: '✓', body: <ConfirmationView /> },
 ];
 
-// ⚠️ КРИТИЧНО: `stepValidations` это **Record<number, ValidationSchemaFn<T>>**,
-// НЕ array. Если объявить как array `[step1Fn, step2Fn]` — FormWizard молча
-// пропустит валидацию, "Далее" сработает без проверок. Silent no-op, без
-// runtime warning.
-const STEP_VALIDATIONS: Record<number, ValidationSchemaFn<MyForm>> = {
-  1: (path) => {
-    required(path.email);
-    email(path.email);
-  },
-  2: (path) => {
-    required(path.password);
-    minLength(path.password, 8);
+// ⚠️ КРИТИЧНО: `config` это **FormWizardConfig** — объект с ДВУМЯ колбэками
+// (`validateStep`, `validateAll`), НЕ схемы/массивы валидаторов. Каждый колбэк
+// возвращает `boolean | Promise<boolean>`: `true` = валидно, идём дальше.
+// Если колбэк не задан — соответствующий шаг/submit считается валидным (no-op).
+// Канон M1 — валидировать per-step/полностью через validateFormModel(model, ...).
+const config: FormWizardConfig = {
+  // step 1-based. Провалидируй нужный шаг (собери под-схему шага и прогони
+  // validateFormModel), верни boolean.
+  validateStep: async (step) => {
+    const stepSchema = { children: [schema.children[step - 1]] };
+    const res = await validateFormModel(model, stepSchema);
+    return res.valid;
   },
-};
-
-const fullValidation: ValidationSchemaFn<MyForm> = (path) => {
-  STEP_VALIDATIONS[1](path);
-  STEP_VALIDATIONS[2](path);
-  required(path.confirmation);
+  validateAll: async () => (await validateFormModel(model, schema)).valid,
 };
 
 // ref типизируется явно типом формы; constraint `T extends Record<string, any>`
@@ -1540,21 +1657,26 @@ const navRef = useRef<FormWizardHandle<MyForm>>(null);
 
 // ВАЖНО: prop-level `onSubmit` имеет signature `() => void | Promise<void>` —
 // БЕЗ аргумента values. Это by-design (см. FormWizardActionsProps в @reformer/cdk).
-// Чтобы получить values — читай их из form внутри handler:
+// Чтобы получить values — читай их из модели внутри handler:
 const handleSubmit = async () => {
-  const values = form.getValue();
+  const values = model.get();
   await api.submit(values);
 };
 
 <FormWizard
   ref={navRef}
   form={form}
-  config={{ stepValidations: STEP_VALIDATIONS, fullValidation }}
+  config={config}
   steps={steps}
   onSubmit={handleSubmit}
 />;
 ```
 
+> **`config` не привязан к типу формы.** `FormWizardConfig` — это `{ validateStep?, validateAll? }`,
+> оба колбэка возвращают `boolean | Promise<boolean>`. Канон M1 — прогонять
+> `validateFormModel(model, schema)` (именно он исполняет `validators` листьев;
+> `form.validate()` по нодам схемные правила НЕ запустит).
+
 ### Альтернатива — imperative submit с values
 
 `navRef.current?.submit(callback)` — отдельный API, ПРИНИМАЕТ `(values: T) =>` callback.
@@ -1585,8 +1707,14 @@ const handleSaveAndExit = async () => {
 
 ## 39. RenderNode body (renderer-react / renderer-json)
 
+M1: схема без аргумента `path` — листья ссылаются на сигналы модели
+(`value: model.$.x`), а не на `path.x`:
+
 ```tsx
-const renderSchema = (path) => ({
+import { createRenderSchema } from '@reformer/renderer-react';
+import { Box, Input } from '@reformer/ui-kit';
+
+const renderSchema = createRenderSchema<CreditApplication>(() => ({
   selector: 'wizard',
   component: FormWizard,
   componentProps: {
@@ -1601,12 +1729,15 @@ const renderSchema = (path) => ({
         body: {
           component: Box,
           componentProps: { className: 'space-y-4' },
-          children: [{ component: path.loanAmount }, { component: path.loanTerm }],
+          children: [
+            { value: model.$.loanAmount, component: Input },
+            { value: model.$.loanTerm, component: Input },
+          ],
         },
       },
     ],
   },
-});
+}));
 ```
 
 ui-kit FormWizard детектирует RenderNode (объект с `.component` без React-element-маркера) и оборачивает в `RenderNodeComponent` с `form={form}`.
@@ -1685,11 +1816,22 @@ const wizardRef = useRef<FormWizardHandle<MyForm>>(null);
 
 <FormWizard ref={wizardRef} ... />
 
-// Программная навигация:
-wizardRef.current?.goToStep(2);
-wizardRef.current?.submit(handleSubmit);
+// Программная навигация и submit (см. FormWizardHandle<T> в @reformer/cdk):
+wizardRef.current?.goToStep(2); // boolean: false, если предыдущий шаг не завершён
+await wizardRef.current?.goToNextStep(); // валидирует текущий шаг, затем переходит
+wizardRef.current?.goToPreviousStep();
+await wizardRef.current?.validateCurrentStep(); // Promise<boolean>
+
+// submit принимает callback (values: T) => R | Promise<R>; возвращает R | null
+// (null — не прошла validateAll):
+const result = await wizardRef.current?.submit((values) => api.submit(values));
 ```
 
+Доступные поля/методы `FormWizardHandle<T>`: `form`, `currentStep`,
+`completedSteps`, `isFirstStep`, `isLastStep`, `isValidating`,
+`validateCurrentStep()`, `goToNextStep()`, `goToPreviousStep()`,
+`goToStep(step)`, `submit(cb)`.
+
 ## 43. Базовое использование (TS-flow)
 
 ```tsx
@@ -1737,34 +1879,42 @@ const PropertyForm: FC<{ control: FormProxy<Property> }> = ({ control }) => (
 
 ## 44. Renderer-react RenderSchema
 
-`control` принимает `FieldPathNode` (`path.<arrayField>`) — резолвится автоматически через `FieldPathNavigator`.
+M1: схема без аргумента `path` (`createRenderSchema<T>(() => ...)`). `control`
+ссылается на массив модели (`model.<arrayField>` — `ModelArray<T>`); `FormArraySection`
+резолвит его в `ArrayNode` внутри.
 
 ```tsx
-const renderSchema = (path) => ({
+import { createRenderSchema } from '@reformer/renderer-react';
+import { FormArraySection } from '@reformer/ui-kit/form-array';
+
+const renderSchema = createRenderSchema<CreditApplication>(() => ({
   selector: 'properties-section',
   component: FormArraySection,
   componentProps: {
-    control: path.properties, // FieldPath → ArrayNode
+    control: model.properties, // ModelArray → резолвится в ArrayNode
     itemComponent: PropertyForm, // FC напрямую
     title: 'Имущество',
     addButtonLabel: '+ Добавить имущество',
+    initialValue: createBlankProperty(),
   },
-});
+}));
 ```
 
-ui-kit FormArraySection маркирован `__selfManagedChildren = true` — родитель-renderer пробрасывает `form` без рекурсии. Резолв `FieldPathNode → ArrayNode` происходит внутри.
+ui-kit FormArraySection маркирован `__selfManagedChildren = true` — родитель-renderer пробрасывает `form` без рекурсии.
+
+> Альтернатива — нативный array-узел движка `{ array: model.properties, initialValue, item: (im) => ({ children: [ { value: im.$.field, component } ] }) }`.
 
 ## 45. JSON (renderer-json)
 
 Два варианта `itemComponent`:
 
-### Вариант 1: registry-name (FC зарегистрирован как container)
+### Вариант 1: registry-name (FC зарегистрирован через reg.component)
 
 ```ts
 // registry.ts
 defineRegistry((reg) => {
-  reg.container('FormArraySection', FormArraySection);
-  reg.container('PropertyForm', PropertyForm);
+  reg.component('FormArraySection', FormArraySection);
+  reg.component('PropertyForm', PropertyForm);
 });
 ```
 
@@ -1817,20 +1967,25 @@ defineRegistry((reg) => {
 
 ## 46. Props (полный список)
 
-| Prop                 | Type                                                 | Default        | Описание                               |
-| -------------------- | ---------------------------------------------------- | -------------- | -------------------------------------- |
-| `control`            | `FormArrayProxy<T> \| ArrayNode<T> \| FieldPathNode` | required       | Массив для управления                  |
-| `itemComponent`      | `ComponentType<{ control: FormProxy<T> }>`           | required       | FC для рендера каждого item            |
-| `title`              | `string`                                             | —              | Заголовок секции (h3)                  |
-| `itemLabel`          | `string \| (control, index) => string`               | —              | Метка над каждым item                  |
-| `addButtonLabel`     | `string`                                             | `'+ Добавить'` | Текст кнопки добавления                |
-| `removeButtonLabel`  | `string`                                             | `'Удалить'`    | Текст кнопки удаления                  |
-| `emptyMessage`       | `string`                                             | —              | Сообщение при пустом массиве           |
-| `emptyMessageHint`   | `string`                                             | —              | Подсказка под emptyMessage             |
-| `hasItems`           | `boolean`                                            | —              | `false` → секция полностью скрыта      |
-| `initialValue`       | `Partial<FormFields>`                                | —              | Plain-leaf значения для новых items    |
-| `maxItems`           | `number`                                             | —              | Максимум items (AddButton отключается) |
-| `showRemoveOnSingle` | `boolean`                                            | `false`        | Показывать «Удалить» при одном item    |
+| Prop                 | Type                                                         | Default                          | Описание                                                  |
+| -------------------- | ------------------------------------------------------------ | -------------------------------- | --------------------------------------------------------- |
+| `control`            | `FormArrayProxy<T> \| ArrayNode<T> \| undefined`             | required                         | Массив для управления (в RenderSchema — `FieldPathNode`)  |
+| `itemComponent`      | `ComponentType<{ control: FormProxy<T> }>`                   | required                         | FC для рендера каждого item                               |
+| `title`              | `string`                                                     | —                                | Заголовок секции (h3)                                     |
+| `itemLabel`          | `string \| (control: FormProxy<T>, index: number) => string` | —                                | Метка над каждым item                                    |
+| `addButtonLabel`     | `string`                                                     | `'+ Добавить'`                   | Текст кнопки добавления                                   |
+| `removeButtonLabel`  | `string`                                                     | `'Удалить'`                      | Текст кнопки удаления                                     |
+| `emptyMessage`       | `string`                                                     | —                                | Сообщение при пустом массиве                             |
+| `emptyMessageHint`   | `string`                                                     | —                                | Подсказка под emptyMessage                               |
+| `hasItems`           | `boolean`                                                    | —                                | `false` → секция полностью скрыта                        |
+| `initialValue`       | `Partial<T>`                                                 | —                                | Plain-leaf значения для новых items                      |
+| `showRemoveOnSingle` | `boolean`                                                    | `false`                          | Показывать «Удалить» при одном item                      |
+| `reorderable`        | `boolean`                                                    | `false`                          | Показывать кнопки ↑/↓ для перестановки элементов          |
+| `maxItems`           | `number`                                                     | —                                | Максимум items (AddButton скрывается при достижении)     |
+| `className`          | `string`                                                     | `'space-y-3 mt-2'`               | Класс `<section>`-обёртки                                |
+| `cardClassName`      | `string`                                                     | `'mb-4 p-4 bg-white rounded border'` | Класс card-обёртки каждого item                     |
+| `form`               | `FormProxy<unknown>`                                         | авто-инъекция                    | Проброс `form` (RenderNodeComponent через `__selfManagedChildren`) |
+| `fieldWrapper`       | `ComponentType<FieldWrapperProps>`                          | авто-инъекция                    | Field wrapper для дочерних полей (по умолчанию — от родителя) |
 
 ## 47. Critical: `initialValue` — PLAIN LEAVES ONLY
 
@@ -1846,10 +2001,13 @@ FieldConfig попадает в значение поля → Textarea ренд
 
 ## 48. Schema-driven (canonical pattern)
 
-Объяви InputMask как `component` поля; передай `mask` в `componentProps`:
+Канон M1: `createModel` → схема, где лист = `{ value: model.$.field, component,
+componentProps, validators }` → `createForm({ model, schema })`. Объяви InputMask
+как `component` листа; передай `mask` в `componentProps`:
 
 ```ts
-import { createForm, type FormSchema } from '@reformer/core';
+import { createModel, createForm } from '@reformer/core';
+import { required, pattern } from '@reformer/core/validators';
 import { InputMask } from '@reformer/ui-kit';
 
 type ContactForm = {
@@ -1859,30 +2017,41 @@ type ContactForm = {
   snils: string;
 };
 
-const form = createForm<ContactForm>({
-  form: {
-    phone: {
-      value: '',
+const model = createModel<ContactForm>({ phone: '', passport: '', inn: '', snils: '' });
+
+const schema = {
+  children: [
+    {
+      value: model.$.phone,
       component: InputMask,
-      componentProps: { label: 'Телефон', mask: '+7 (999) 999-99-99' },
+      componentProps: { label: 'Телефон', mask: '+7 (999) 999-99-99', testId: 'phone' },
+      validators: [
+        required({ message: 'Телефон обязателен' }),
+        pattern(/^\+7 \(\d{3}\) \d{3}-\d{2}-\d{2}$/, { message: 'Неверный формат телефона' }),
+      ],
     },
-    passport: {
-      value: '',
+    {
+      value: model.$.passport,
       component: InputMask,
-      componentProps: { label: 'Серия и номер паспорта', mask: '9999 999999' },
+      componentProps: { label: 'Серия и номер паспорта', mask: '9999 999999', testId: 'passport' },
+      validators: [required()],
     },
-    inn: {
-      value: '',
+    {
+      value: model.$.inn,
       component: InputMask,
-      componentProps: { label: 'ИНН', mask: '999999999999' },
+      componentProps: { label: 'ИНН', mask: '999999999999', testId: 'inn' },
+      validators: [required(), pattern(/^\d{12}$/, { message: 'ИНН должен содержать 12 цифр' })],
     },
-    snils: {
-      value: '',
+    {
+      value: model.$.snils,
       component: InputMask,
-      componentProps: { label: 'СНИЛС', mask: '999-999-999 99' },
+      componentProps: { label: 'СНИЛС', mask: '999-999-999 99', testId: 'snils' },
+      validators: [required()],
     },
-  } satisfies FormSchema<ContactForm>,
-});
+  ],
+};
+
+const form = createForm<ContactForm>({ model, schema });
 ```
 
 Render как обычно через `FormField`:
@@ -1915,24 +2084,30 @@ import { FormField } from '@reformer/ui-kit';
 ## 50. Validation
 
 `InputMask` пишет в значение **то, что ввёл пользователь** (с literal-символами маски).
-Для validation используй:
+Валидаторы — фабрики из `@reformer/core/validators` — кладутся в массив `validators`
+листа схемы (см. схему выше), а не в отдельную path-функцию. Прогоняются через
+`validateFormModel(model, schema)`:
 
-- `required(path.phone)` — на пустоту
-- `minLength(path.phone, 18)` — для проверки длины с literal-символами (телефон ровно 18 символов)
-- `pattern(path.phone, /^\+7 \(\d{3}\) \d{3}-\d{2}-\d{2}$/)` — точный pattern если нужно
+- `required({ message })` — на пустоту;
+- `minLength(18)` — для проверки длины с literal-символами (телефон ровно 18 символов);
+- `pattern(/^\+7 \(\d{3}\) \d{3}-\d{2}-\d{2}$/, { message })` — точный формат.
 
 ```ts
-const validation: ValidationSchemaFn<ContactForm> = (path) => {
-  required(path.phone, { message: 'Телефон обязателен' });
-  pattern(path.phone, /^\+7 \(\d{3}\) \d{3}-\d{2}-\d{2}$/, {
-    message: 'Неверный формат телефона',
-  });
-
-  required(path.inn);
-  pattern(path.inn, /^\d{12}$/, { message: 'ИНН должен содержать 12 цифр' });
+import { validateFormModel } from '@reformer/core';
+
+// schema — из блока Schema-driven выше (валидаторы уже на листьях phone/inn/…).
+const onSubmit = async () => {
+  form.markAsTouched();
+  const res = await validateFormModel(model, schema);
+  if (!res.valid) return;
+  await api.submit(model.get());
 };
 ```
 
+Cross-field правила (например, «доп. телефон отличается от основного») — это
+именованные `ModelValidator<value, scope, root>` в том же массиве `validators`
+(читают корень формы через третий аргумент).
+
 ## 51. Advanced — strict mask через FormField + children slot
 
 Если нужна автоматическая вставка literal-символов (true input-mask), используй
@@ -2013,13 +2188,15 @@ ErrorComponent={() => <p>Ошибка загрузки</p>}
 
 Внутри RenderSchema (статус подставляется через `patchProps`)
 ```tsx
+import { createRenderSchema } from '@reformer/renderer-react';
 import { AsyncBoundary } from '@reformer/ui-kit';
 
-createRenderSchema((path) => ({
+// M1: функция схемы не принимает аргументов — привязка к данным идёт через сигналы модели.
+const schema = createRenderSchema(() => ({
 selector: 'data-boundary',
 component: AsyncBoundary,
 componentProps: { status: 'loading', LoadingComponent: Spinner },
-children: [...],
+children: [{ value: model.$.email, component: Input }],
 }));
 // позже: schema.node('data-boundary').patchProps({ status: 'ready' });
 ```
@@ -2077,26 +2254,30 @@ export function Box({ className, children }: BoxProps): ReactNode
 
 **Examples:**
 
-Вертикальный список полей в RenderSchema
+Вертикальный список полей в RenderSchema (M1: лист = `value` + `component`)
 ```typescript
+import { Box, Input, InputPassword } from '@reformer/ui-kit';
+
 {
 component: Box,
 componentProps: { className: 'flex flex-col gap-4' },
 children: [
-{ component: path.email },
-{ component: path.password },
+{ value: model.$.email, component: Input },
+{ value: model.$.password, component: InputPassword },
 ],
 }
 ```
 
 Двухколоночная сетка
 ```typescript
+import { Box, Input } from '@reformer/ui-kit';
+
 {
 component: Box,
 componentProps: { className: 'grid grid-cols-2 gap-4' },
 children: [
-{ component: path.firstName },
-{ component: path.lastName },
+{ value: model.$.firstName, component: Input },
+{ value: model.$.lastName, component: Input },
 ],
 }
 ```
@@ -2285,8 +2466,8 @@ Collapsible - сворачиваемая секция формы.
 
 Заголовок-кнопка переключает видимость `children`. Состояние локальное
 (`useState`), внешний control пока не поддерживается — для управляемого
-варианта используй `RenderSchema.node('selector').setHidden(true)` поверх
-обычного `Box`.
+извне варианта используй `createRenderSchema(...).node('selector').setHidden(true)`
+поверх обычного `Box`/`Section`.
 
 **Signature:**
 ```typescript
@@ -2302,8 +2483,10 @@ export function Collapsible({
 
 **Examples:**
 
-Свёрнута по умолчанию
+Свёрнута по умолчанию (M1: лист = `value` + `component`)
 ```typescript
+import { Collapsible, Textarea, Input } from '@reformer/ui-kit';
+
 {
 component: Collapsible,
 componentProps: {
@@ -2313,14 +2496,16 @@ className: 'border rounded p-4',
 titleClassName: 'font-semibold w-full text-left',
 },
 children: [
-{ component: path.notes },
-{ component: path.tags },
+{ value: model.$.notes, component: Textarea },
+{ value: model.$.tags, component: Input },
 ],
 }
 ```
 
 Развёрнута, со специальным фоном контента
 ```typescript
+import { Collapsible, Textarea } from '@reformer/ui-kit';
+
 {
 component: Collapsible,
 componentProps: {
@@ -2329,7 +2514,7 @@ defaultOpen: true,
 contentClassName: 'mt-2 bg-gray-50 p-3 rounded',
 },
 children: [
-{ component: path.deliveryAddress },
+{ value: model.$.deliveryAddress, component: Textarea },
 ],
 }
 ```
@@ -2366,6 +2551,10 @@ _Source: src/components/ui/collapsible.tsx_
 
 **Kind:** `function`
 
+Состояние ошибки — карточка с иконкой, заголовком, текстом ошибки и
+опциональной кнопкой повтора. Типовое применение — показать вместо формы,
+когда не удалось загрузить данные заявки.
+
 **Signature:**
 ```typescript
 export function ErrorState({
@@ -2377,6 +2566,21 @@ export function ErrorState({
 }: ErrorStateProps): ReactNode
 ```
 
+**Parameters:**
+- `props` — - Пропсы: `error` (обязателен), `title`, `onRetry`, `retryLabel`, `className`.
+
+**Returns:** Разметку блока ошибки.
+
+**Examples:**
+
+Ошибка загрузки с повтором
+```tsx
+const { error } = useLoadCreditApplication(form, '1');
+if (error) {
+return <ErrorState error={error} onRetry={() => window.location.reload()} />;
+}
+```
+
 _Source: src/components/state/error-state.tsx_
 
 ### ExampleCard
@@ -2468,6 +2672,20 @@ _Source: src/components/ui/example-card.tsx_
 
 **Kind:** `function`
 
+Готовая UI-секция для динамического массива форм — стилизованная обёртка поверх
+headless-compound `@reformer/cdk/form-array`. Рендерит заголовок, кнопку
+«Добавить», карточку с меткой на каждый элемент (плюс опциональные кнопки
+удаления и перестановки ↑/↓) и сообщение пустого состояния.
+
+`control` принимает `FormArrayProxy<T>` или уже-резолвленный
+`ArrayNode<T>`/`ModelArrayNode<T>`. `itemComponent` — единственная форма
+рендера элемента: `ComponentType<{ control: FormProxy<T> }>` (тот же контракт,
+что у шага {@link FormWizardStep}). Внутри `RenderNodeComponent` проп `form`
+инъектится автоматически (маркер `__selfManagedChildren`).
+
+Проп `hasItems` удобен для toggle-чекбоксов («У меня есть имущество»): при
+`false` секция скрывается целиком.
+
 **Signature:**
 ```typescript
 export function FormArraySection<T extends object>({
@@ -2489,12 +2707,38 @@ export function FormArraySection<T extends object>({
 }: FormArraySectionProps<T>): ReactNode
 ```
 
+**Examples:**
+
+Массив «Имущество» под чекбоксом-переключателем
+```tsx
+import { FormArraySection } from '@reformer/ui-kit/form-array';
+
+function AdditionalInfo({ control }: { control: FormProxy<CreditApplication> }) {
+const hasProperty = useFormControlValue(control.hasProperty) as boolean;
+return (
+<FormArraySection
+title="Имущество"
+control={control.properties}
+itemComponent={PropertyForm}
+itemLabel="Имущество"
+addButtonLabel="+ Добавить имущество"
+emptyMessage='Нажмите "Добавить имущество" для добавления информации'
+hasItems={hasProperty}
+initialValue={createBlankProperty()}
+reorderable
+/>
+);
+}
+```
+
 _Source: src/components/form-array/form-array-section.tsx_
 
 ### FormArraySectionProps
 
 **Kind:** `interface`
 
+Пропсы {@link FormArraySection}.
+
 **Signature:**
 ```typescript
 export interface FormArraySectionProps<T extends object> {
@@ -2594,22 +2838,31 @@ export const FormField
 
 **Examples:**
 
-Standalone в обычной форме
+Standalone в обычной форме (M1: `createModel` + `createForm({ model, schema })`)
 ```tsx
 import { useMemo } from 'react';
-import { createForm, type FormSchema } from '@reformer/core';
+import { createModel, createForm } from '@reformer/core';
+import { required } from '@reformer/core/validators';
 import { Button, FormField, Input } from '@reformer/ui-kit';
 
 function RegistrationPage() {
-const form = useMemo(
-() => createForm<FormSchema<{ email: string }>>({
-email: { component: Input, componentProps: { label: 'Email' } },
-}),
-[]
-);
+const { form } = useMemo(() => {
+const model = createModel<{ email: string }>({ email: '' });
+const schema = {
+children: [
+{
+ value: model.$.email,
+ component: Input,
+ componentProps: { label: 'Email', type: 'email', testId: 'email' },
+ validators: [required({ message: 'Email обязателен' })],
+},
+],
+};
+return { form: createForm<{ email: string }>({ model, schema }) };
+}, []);
 return (
 <form>
-<FormField control={form.email} testId="email" />
+<FormField control={form.email} />
 <Button type="submit">OK</Button>
 </form>
 );
@@ -2619,11 +2872,15 @@ return (
 В качестве `fieldWrapper` для FormRenderer
 ```tsx
 import { FormRenderer, createRenderSchema } from '@reformer/renderer-react';
-import { FormField } from '@reformer/ui-kit';
+import { Box, FormField, Input } from '@reformer/ui-kit';
 
-const schema = createRenderSchema<MyForm>((path) => ({
-component: 'Box',
-children: [{ component: path.email }, { component: path.phone }],
+// M1: узлы ссылаются на компоненты-значения, листья — на сигналы модели.
+const schema = createRenderSchema<MyForm>(() => ({
+component: Box,
+children: [
+{ value: model.$.email, component: Input },
+{ value: model.$.phone, component: Input },
+],
 }));
 
 <FormRenderer render={schema} settings={{ fieldWrapper: FormField }} />
@@ -2670,39 +2927,140 @@ _Source: src/components/ui/form-field.tsx_
 
 **Kind:** `const`
 
+Готовая многошаговая форма (multi-step wizard) — стилизованная обёртка поверх
+headless-compound `@reformer/cdk/form-wizard`. Собирает Indicator, тело шагов,
+Actions (Назад / Далее / Отправить) и Progress в единый layout, работает с
+одной {@link FormProxy} и декларативным списком {@link FormWizardStep}.
+
+Один компонент покрывает TS-flow, renderer-react и renderer-json за счёт
+полиморфного {@link FormWizardStepBody}. Валидация по шагам и submit-валидация
+задаются через `config` (`{ validateStep, validateAll }`, обычно из
+`validateFormModel`). Императивный доступ (submit/навигация снаружи дерева) —
+через `ref` типа `FormWizardHandle<T>`.
+
+Экспонирует compound-слоты `FormWizard.Indicator` / `.Step` / `.Actions` /
+`.Progress` для кастомной раскладки.
+
 **Signature:**
 ```typescript
 const FormWizard
 ```
 
+**Examples:**
+
+Кредитная заявка с 3 шагами и внешним submit
+```tsx
+import { useMemo, useRef } from 'react';
+import { FormWizard, type FormWizardStep } from '@reformer/ui-kit/form-wizard';
+import type { FormWizardHandle } from '@reformer/cdk/form-wizard';
+
+const STEPS: FormWizardStep<CreditApplication>[] = [
+{ number: 1, title: 'Кредит', icon: '💰', body: BasicInfoForm },
+{ number: 2, title: 'Данные', icon: '👤', body: PersonalInfoForm },
+{ number: 3, title: 'Подтверждение', icon: '✓', body: ConfirmationForm },
+];
+
+function CreditForm() {
+const navRef = useRef<FormWizardHandle<CreditApplication>>(null);
+const { form, model } = useMemo(() => createCreditForm(), []);
+const config = useMemo(() => makeValidationConfig(model), [model]);
+
+const onSubmit = () =>
+navRef.current?.submit((values) => api.submit(values));
+
+return (
+<FormWizard
+ref={navRef}
+form={form}
+config={config}
+steps={STEPS}
+onSubmit={onSubmit}
+/>
+);
+}
+```
+
+**See also:**
+- {@link FormWizardStep} — форма элемента `steps`.
+- {@link StepIndicator}, {@link FormWizardActions}, {@link FormWizardProgress} — слоты layout'а.
+
 _Source: src/components/form-wizard/form-wizard.tsx_
 
 ### FormWizardActions
 
 **Kind:** `const`
 
+Кнопки навигации wizard'а: «Назад» / «Далее →» / «Отправить». На первом шаге
+скрывает «Назад», на последнем показывает «Отправить» вместо «Далее». Во время
+валидации/отправки показывает промежуточные подписи и блокирует кнопку.
+
+Рендерится из headless-слота `<FormWizard.Actions>` через render-prop, поэтому
+`prev`/`next`/`submit`/флаги приходят автоматически. Готовый {@link FormWizard}
+уже подключает этот компонент — использовать напрямую нужно только для кастомной
+раскладки.
+
 **Signature:**
 ```typescript
 export const FormWizardActions: FC<FormWizardActionsProps>
 ```
 
+**Examples:**
+
+Кастомные подписи в слоте Actions
+```tsx
+<FormWizard.Actions onSubmit={onSubmit}>
+{(actions) => (
+<FormWizardActions
+{...actions}
+submitLabel="Оформить заявку"
+className="mt-8"
+/>
+)}
+</FormWizard.Actions>
+```
+
 _Source: src/components/form-wizard/form-wizard-actions.tsx_
 
 ### FormWizardProgress
 
 **Kind:** `const`
 
+Текстовый индикатор прогресса wizard'а — по умолчанию рендерит
+«Шаг N из M • X% завершено». Формат строки переопределяется пропом `format`.
+
+Рендерится из headless-слота `<FormWizard.Progress>` через render-prop
+(`current`/`total`/`percent` приходят автоматически). Готовый {@link FormWizard}
+уже подключает этот компонент; напрямую нужен только для кастомной раскладки.
+
 **Signature:**
 ```typescript
 export const FormWizardProgress: FC<FormWizardProgressProps>
 ```
 
+**Examples:**
+
+Свой формат строки прогресса
+```tsx
+<FormWizard.Progress>
+{(progress) => (
+<FormWizardProgress
+{...progress}
+format={({ current, total }) => `${current} / ${total}`}
+/>
+)}
+</FormWizard.Progress>
+```
+
 _Source: src/components/form-wizard/form-wizard-progress.tsx_
 
 ### FormWizardProps
 
 **Kind:** `interface`
 
+Пропсы {@link FormWizard}. Расширяют headless-пропсы из
+`@reformer/cdk/form-wizard` (`form`, `config`, `onStepChange`, …), добавляя
+декларативный `steps` и колбэк `onSubmit`.
+
 **Signature:**
 ```typescript
 export interface FormWizardProps<
@@ -2713,43 +3071,71 @@ export interface FormWizardProps<
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   T extends Record<string, any>,
 > extends FormWizardHeadlessProps<T> {
+  /** Внешний CSS-класс корневого контейнера. */
   className?: string;
+  /** Декларативный список шагов (см. {@link FormWizardStep}). Порядок = порядок навигации. */
   steps: FormWizardStep<T>[];
+  /** Колбэк отправки формы на последнем шаге; вызывается после успешной валидации. */
   onSubmit: HeadlessFormWizardActionsProps['onSubmit'];
 }
 ```
 
+**See also:**
+- {@link FormWizardStep} — форма элемента `steps`.
+- — императивный handle через `ref` (submit/навигация).
+
 _Source: src/components/form-wizard/form-wizard.tsx_
 
 ### FormWizardStep
 
 **Kind:** `interface`
 
+Описание одного шага {@link FormWizard}: порядковый номер, заголовок и иконка
+для индикатора, плюс полиморфное тело {@link FormWizardStepBody}.
+
+Массив `FormWizardStep<T>[]` передаётся в проп `steps`. Порядок и `number`
+задают последовательность навигации; `number` должен быть 1-based и уникальным.
+
 **Signature:**
 ```typescript
 export interface FormWizardStep<T> {
-  /** Step number (1-based). */
+  /** Порядковый номер шага (1-based). Уникальный, задаёт порядок навигации. */
   number: number;
-  /** Step title shown in indicator. */
+  /** Заголовок шага, показывается в {@link StepIndicator}. */
   title: string;
-  /** Optional icon (string или ReactNode). Передаётся в headless Indicator. */
+  /** Иконка шага (эмодзи или строка). Передаётся в headless Indicator. */
   icon?: string;
-  /** Body — FC | ReactNode | RenderNode<T>. */
+  /** Тело шага — FC | ReactNode | RenderNode<T> (см. {@link FormWizardStepBody}). */
   body: FormWizardStepBody<T>;
 }
 ```
 
+**Examples:**
+
+Массив шагов кредитной заявки
+```tsx
+const STEPS: FormWizardStep<CreditApplication>[] = [
+{ number: 1, title: 'Кредит', icon: '💰', body: BasicInfoForm },
+{ number: 2, title: 'Данные', icon: '👤', body: PersonalInfoForm },
+{ number: 3, title: 'Подтверждение', icon: '✓', body: ConfirmationForm },
+];
+```
+
 _Source: src/components/form-wizard/form-wizard.tsx_
 
 ### FormWizardStepBody
 
 **Kind:** `type`
 
-Полиморфное тело шага.
+Полиморфное тело шага {@link FormWizardStep}. Один и тот же {@link FormWizard}
+покрывает TS-flow, renderer-react и renderer-json за счёт трёх допустимых форм
+`body`, дискриминация которых выполняется в рантайме по типу значения:
 
-- FC получает `control={form}`.
-- ReactNode рендерится напрямую (статический JSX).
-- RenderNode<T> рендерится через `<RenderNodeComponent>`.
+- `ComponentType<{ control: FormProxy<T> }>` — React-компонент; получает
+  `control={form}` (корневой {@link FormProxy}) и сам обращается к нужным полям.
+- `ReactNode` — готовый JSX или статический контент шага (текст, число и т.п.).
+- `RenderNode<T>` — RenderSchema-поддерево; рендерится через `RenderNodeComponent`
+  для интеграции с `@reformer/renderer-react`.
 
 **Signature:**
 ```typescript
@@ -2759,6 +3145,16 @@ export type FormWizardStepBody<T> =
   | RenderNode<T>;
 ```
 
+**Examples:**
+
+Компонент шага получает control
+```tsx
+function BasicInfoForm({ control }: { control: FormProxy<CreditApplication> }) {
+return <FormField control={control.loanAmount} testId="loanAmount" />;
+}
+const body: FormWizardStepBody<CreditApplication> = BasicInfoForm;
+```
+
 _Source: src/components/form-wizard/form-wizard.tsx_
 
 ### Input
@@ -2797,6 +3193,27 @@ placeholder="Возраст"
 />
 ```
 
+Привязка к полю формы через `useFormControl`
+```tsx
+import { useFormControl, type FieldNode } from '@reformer/core';
+import { Input } from '@reformer/ui-kit';
+
+function EmailField({ control }: { control: FieldNode<string> }) {
+const { value, disabled, errors, shouldShowError } = useFormControl(control);
+return (
+<Input
+type="email"
+value={value}
+disabled={disabled}
+onChange={(v) => control.setValue((v ?? '') as string)}
+onBlur={() => control.markAsTouched()}
+aria-invalid={shouldShowError}
+placeholder={shouldShowError ? errors[0]?.message : 'you@example.com'}
+/>
+);
+}
+```
+
 _Source: src/components/ui/input.tsx_
 
 ### InputMask
@@ -2991,6 +3408,9 @@ _Source: src/components/ui/input.tsx_
 
 **Kind:** `function`
 
+Состояние загрузки — центрированный спиннер с заголовком и подзаголовком.
+Типовое применение — показать вместо формы, пока грузятся данные заявки.
+
 **Signature:**
 ```typescript
 export function LoadingState({
@@ -3000,6 +3420,21 @@ export function LoadingState({
 }: LoadingStateProps): ReactNode
 ```
 
+**Parameters:**
+- `props` — - Пропсы: `title`, `subtitle`, `className` (все опциональны).
+
+**Returns:** Разметку блока загрузки.
+
+**Examples:**
+
+Загрузка перед рендером формы
+```tsx
+const { isLoading } = useLoadCreditApplication(form, '1');
+if (isLoading) {
+return <LoadingState />;
+}
+```
+
 _Source: src/components/state/loading-state.tsx_
 
 ### RadioGroup
@@ -3093,6 +3528,26 @@ export interface RadioOption {
 
 _Source: src/components/ui/radio-group.tsx_
 
+### ResourceConfig
+
+**Kind:** `interface`
+
+Конфигурация асинхронного источника опций для {@link Select}.
+
+**Signature:**
+```typescript
+export interface ResourceConfig<T> {
+  /** Стратегия загрузки. По умолчанию (если не задана) трактуется как `'static'`. */
+  type: ResourceStrategy;
+  /** Функция загрузки опций. Должна вернуть `{ items, totalCount }`. */
+  load: (params?: ResourceLoadParams) => Promise<ResourceResult<T>>;
+  /** Размер страницы для стратегии `partial`. По умолчанию 20. */
+  pageSize?: number;
+}
+```
+
+_Source: src/components/ui/select-resource.ts_
+
 ### Section
 
 **Kind:** `function`
@@ -3115,8 +3570,10 @@ export function Section({
 
 **Examples:**
 
-Заголовок h2 + сетка из двух колонок
+Заголовок h2 + сетка из двух колонок (M1: лист = `value` + `component`)
 ```typescript
+import { Section, Input } from '@reformer/ui-kit';
+
 {
 component: Section,
 componentProps: {
@@ -3126,20 +3583,22 @@ titleClassName: 'text-xl font-bold',
 className: 'grid grid-cols-2 gap-4',
 },
 children: [
-{ component: path.firstName },
-{ component: path.lastName },
+{ value: model.$.firstName, component: Input },
+{ value: model.$.lastName, component: Input },
 ],
 }
 ```
 
 Section без заголовка (только обёртка)
 ```typescript
+import { Section, Input } from '@reformer/ui-kit';
+
 {
 component: Section,
 componentProps: { className: 'space-y-4 mt-4' },
 children: [
-{ component: path.address },
-{ component: path.city },
+{ value: model.$.address, component: Input },
+{ value: model.$.city, component: Input },
 ],
 }
 ```
@@ -3174,9 +3633,17 @@ _Source: src/components/ui/section.tsx_
 
 **Kind:** `const`
 
-Выпадающий список на `@radix-ui/react-select`. Поддерживает два режима
-источника данных: inline `options` и async `resource`. При `clearable=true`
-показывает крестик для сброса значения в `null`.
+Выпадающий список на `@radix-ui/react-select`. Два источника данных: inline
+`options` и асинхронный `resource` со стратегией загрузки
+({@link ResourceConfig.type}):
+
+- `static` — один `load({})` при маунте, без поиска;
+- `preload` — грузит всё сразу, поиск фильтрует опции на клиенте;
+- `partial` — серверные поиск (`load({ search })` с debounce) и пагинация
+  (`load({ page })` по мере скролла до `totalCount`).
+
+Для `preload`/`partial` в дропдауне показывается поле поиска. При
+`clearable=true` рядом со значением есть крестик сброса в `null`.
 
 **Signature:**
 ```typescript
@@ -3196,24 +3663,47 @@ placeholder="Тип кредита"
 options={[
 { value: 'consumer', label: 'Потребительский' },
 { value: 'mortgage', label: 'Ипотека' },
-{ value: 'auto', label: 'Авто' },
 ]}
 />
 ```
 
-Grouped options
+Серверные поиск и пагинация (resource type='partial')
 ```tsx
-import { Select } from '@reformer/ui-kit';
+import { Select, type ResourceConfig } from '@reformer/ui-kit';
+
+const users: ResourceConfig<string> = {
+type: 'partial',
+pageSize: 20,
+load: async ({ search = '', page = 1, pageSize = 20 }) => {
+const res = await fetch(`/api/users?q=${search}&page=${page}&size=${pageSize}`);
+const { rows, total } = await res.json();
+return {
+items: rows.map((u) => ({ id: u.id, label: u.name, value: u.id })),
+totalCount: total,
+};
+},
+};
 
-<Select
-value={city}
-onChange={setCity}
-options={[
-{ value: 'msk', label: 'Москва', group: 'Россия' },
-{ value: 'spb', label: 'Санкт-Петербург', group: 'Россия' },
-{ value: 'minsk', label: 'Минск', group: 'Беларусь' },
-]}
-/>
+<Select value={userId} onChange={setUserId} resource={users} clearable />
+```
+
+Предзагрузка с клиентским поиском (resource type='preload')
+```tsx
+import { Select, type ResourceConfig } from '@reformer/ui-kit';
+
+const countries: ResourceConfig<string> = {
+type: 'preload',
+load: async () => {
+const res = await fetch('/api/countries');
+const items = await res.json();
+return {
+items: items.map((c) => ({ id: c.id, label: c.name, value: c.code })),
+totalCount: items.length,
+};
+},
+};
+
+<Select value={country} onChange={setCountry} resource={countries} />
 ```
 
 _Source: src/components/ui/select.tsx_
@@ -3222,18 +3712,29 @@ _Source: src/components/ui/select.tsx_
 
 **Kind:** `function`
 
-Дропдаун-контент {@link Select} (попап со списком). Обёртка над
+Дропдаун-контent {@link Select} (попап со списком). Обёртка над
 `Radix.Select.Content` с порталом, скролл-кнопками сверху/снизу и
 `position='popper'` по умолчанию (растягивается под ширину триггера).
 
+Опционально принимает `header` (нескроллящаяся шапка, например поле поиска)
+и `onViewportScroll` (для infinite-scroll — вешается на скроллящийся
+viewport со списком опций).
+
 **Signature:**
 ```typescript
 function SelectContent({
   className,
   children,
   position = 'popper',
+  header,
+  onViewportScroll,
   ...props
-}: React.ComponentProps<typeof SelectPrimitive.Content>)
+}: React.ComponentProps<typeof SelectPrimitive.Content> & {
+  /** Нескроллящаяся шапка над списком (например, поле поиска). */
+  header?: React.ReactNode;
+  /** Обработчик прокрутки viewport-а со списком (для infinite-scroll). */
+  onViewportScroll?: React.UIEventHandler<HTMLDivElement>;
+})
 ```
 
 **Examples:**
@@ -3571,11 +4072,33 @@ _Source: src/components/ui/select.tsx_
 
 **Kind:** `const`
 
+Визуальная цепочка шагов wizard'а — иконки, заголовки и соединительные линии
+с подсветкой текущего / завершённого шага. Клик (и Enter) по доступному шагу
+вызывает `goToStep`; недоступные шаги приглушены и не кликабельны. Разметка
+доступна для скринридеров (`role="navigation"`, `aria-current="step"`,
+настраиваемые aria-метки).
+
+Рендерится из headless-слота `<FormWizard.Indicator>` через render-prop
+(`steps` со статусами и `goToStep` приходят автоматически). Готовый
+{@link FormWizard} уже подключает этот компонент; напрямую нужен только для
+кастомной раскладки.
+
 **Signature:**
 ```typescript
 export const StepIndicator: FC<StepIndicatorProps>
 ```
 
+**Examples:**
+
+Индикатор с кастомной aria-меткой контейнера
+```tsx
+<FormWizard.Indicator steps={steps}>
+{(indicator) => (
+<StepIndicator {...indicator} navAriaLabel="Этапы заявки" className="mb-8" />
+)}
+</FormWizard.Indicator>
+```
+
 _Source: src/components/form-wizard/step-indicator.tsx_
 
 ### Textarea