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

package/dist/components/form-array/form-array-section.d.ts

@@ -1,6 +1,11 @@
 import { ComponentType, ReactNode } from 'react';
 import { ArrayNode, FormArrayProxy, FormProxy } from '@reformer/core';
 import { FieldWrapperProps } from '@reformer/renderer-react';
+/**
+ * Пропсы {@link FormArraySection}.
+ *
+ * @typeParam T - Тип одного элемента массива (object).
+ */
 export interface FormArraySectionProps<T extends object> {
     /** Уже-резолвленный ArrayNode/ModelArrayNode/FormArrayProxy. */
     control: FormArrayProxy<T> | ArrayNode<T> | undefined;
@@ -59,4 +64,43 @@ export interface FormArraySectionProps<T extends object> {
      */
     fieldWrapper?: ComponentType<FieldWrapperProps>;
 }
+/**
+ * Готовая 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` секция скрывается целиком.
+ *
+ * @typeParam T - Тип одного элемента массива (object).
+ *
+ * @example Массив «Имущество» под чекбоксом-переключателем
+ * ```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
+ *     />
+ *   );
+ * }
+ * ```
+ */
 export declare function FormArraySection<T extends object>({ control, itemComponent: ItemComponent, title, itemLabel, addButtonLabel, removeButtonLabel, emptyMessage, emptyMessageHint, hasItems, initialValue, showRemoveOnSingle, reorderable, maxItems, className, cardClassName, }: FormArraySectionProps<T>): ReactNode;

package/dist/components/form-wizard/form-wizard-actions.d.ts

@@ -1,11 +1,47 @@
 import { FC } from 'react';
 import { FormWizardActionsRenderProps } from '@reformer/cdk/form-wizard';
+/**
+ * Пропсы {@link FormWizardActions}: render-props навигации из headless-слота
+ * `<FormWizard.Actions>` (`prev`, `next`, `submit`, `isFirstStep`, `isLastStep`,
+ * `isValidating`, `isSubmitting`) плюс переопределяемые подписи кнопок.
+ *
+ * Все `*Label`-пропсы опциональны и имеют русские дефолты.
+ */
 export interface FormWizardActionsProps extends FormWizardActionsRenderProps {
+    /** Внешний CSS-класс контейнера кнопок. */
     className?: string;
+    /** Подпись кнопки «Назад». По умолчанию `'← Назад'`. */
     prevLabel?: string;
+    /** Подпись кнопки «Далее». По умолчанию `'Далее →'`. */
     nextLabel?: string;
+    /** Подпись кнопки отправки на последнем шаге. По умолчанию `'Отправить заявку'`. */
     submitLabel?: string;
+    /** Подпись кнопки «Далее» во время валидации шага. По умолчанию `'Проверка...'`. */
     validatingLabel?: string;
+    /** Подпись кнопки отправки во время submit. По умолчанию `'Отправка...'`. */
     submittingLabel?: string;
 }
+/**
+ * Кнопки навигации wizard'а: «Назад» / «Далее →» / «Отправить». На первом шаге
+ * скрывает «Назад», на последнем показывает «Отправить» вместо «Далее». Во время
+ * валидации/отправки показывает промежуточные подписи и блокирует кнопку.
+ *
+ * Рендерится из headless-слота `<FormWizard.Actions>` через render-prop, поэтому
+ * `prev`/`next`/`submit`/флаги приходят автоматически. Готовый {@link FormWizard}
+ * уже подключает этот компонент — использовать напрямую нужно только для кастомной
+ * раскладки.
+ *
+ * @example Кастомные подписи в слоте Actions
+ * ```tsx
+ * <FormWizard.Actions onSubmit={onSubmit}>
+ *   {(actions) => (
+ *     <FormWizardActions
+ *       {...actions}
+ *       submitLabel="Оформить заявку"
+ *       className="mt-8"
+ *     />
+ *   )}
+ * </FormWizard.Actions>
+ * ```
+ */
 export declare const FormWizardActions: FC<FormWizardActionsProps>;

package/dist/components/form-wizard/form-wizard-progress.d.ts

@@ -1,7 +1,37 @@
 import { FC, ReactNode } from 'react';
 import { FormWizardProgressRenderProps } from '@reformer/cdk/form-wizard';
+/**
+ * Пропсы {@link FormWizardProgress}: render-props прогресса из слота
+ * `<FormWizard.Progress>` (`current`, `total`, `percent`) плюс `className` и
+ * переопределяемый `format`.
+ */
 export interface FormWizardProgressProps extends FormWizardProgressRenderProps {
+    /** Внешний CSS-класс контейнера. */
     className?: string;
+    /**
+     * Кастомный форматтер строки прогресса. Получает `{ current, total, percent }`.
+     * По умолчанию — `'Шаг N из M • X% завершено'`.
+     */
     format?: (props: FormWizardProgressRenderProps) => ReactNode;
 }
+/**
+ * Текстовый индикатор прогресса wizard'а — по умолчанию рендерит
+ * «Шаг N из M • X% завершено». Формат строки переопределяется пропом `format`.
+ *
+ * Рендерится из headless-слота `<FormWizard.Progress>` через render-prop
+ * (`current`/`total`/`percent` приходят автоматически). Готовый {@link FormWizard}
+ * уже подключает этот компонент; напрямую нужен только для кастомной раскладки.
+ *
+ * @example Свой формат строки прогресса
+ * ```tsx
+ * <FormWizard.Progress>
+ *   {(progress) => (
+ *     <FormWizardProgress
+ *       {...progress}
+ *       format={({ current, total }) => `${current} / ${total}`}
+ *     />
+ *   )}
+ * </FormWizard.Progress>
+ * ```
+ */
 export declare const FormWizardProgress: FC<FormWizardProgressProps>;

package/dist/components/form-wizard/form-wizard.d.ts

@@ -3,28 +3,75 @@ import { FormWizard as FormWizardHeadless, FormWizardActionsProps as HeadlessFor
 import { FormProxy } from '@reformer/core';
 import { RenderNode } from '@reformer/renderer-react';
 /**
- * Полиморфное тело шага.
+ * Полиморфное тело шага {@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`.
+ *
+ * @typeParam T - Тип значения корневой формы (`FormProxy<T>`).
+ *
+ * @example Компонент шага получает control
+ * ```tsx
+ * function BasicInfoForm({ control }: { control: FormProxy<CreditApplication> }) {
+ *   return <FormField control={control.loanAmount} testId="loanAmount" />;
+ * }
+ * const body: FormWizardStepBody<CreditApplication> = BasicInfoForm;
+ * ```
  */
 export type FormWizardStepBody<T> = ComponentType<{
     control: FormProxy<T>;
 }> | ReactNode | RenderNode<T>;
+/**
+ * Описание одного шага {@link FormWizard}: порядковый номер, заголовок и иконка
+ * для индикатора, плюс полиморфное тело {@link FormWizardStepBody}.
+ *
+ * Массив `FormWizardStep<T>[]` передаётся в проп `steps`. Порядок и `number`
+ * задают последовательность навигации; `number` должен быть 1-based и уникальным.
+ *
+ * @typeParam T - Тип значения корневой формы (`FormProxy<T>`).
+ *
+ * @example Массив шагов кредитной заявки
+ * ```tsx
+ * const STEPS: FormWizardStep<CreditApplication>[] = [
+ *   { number: 1, title: 'Кредит', icon: '💰', body: BasicInfoForm },
+ *   { number: 2, title: 'Данные', icon: '👤', body: PersonalInfoForm },
+ *   { number: 3, title: 'Подтверждение', icon: '✓', body: ConfirmationForm },
+ * ];
+ * ```
+ */
 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>;
 }
+/**
+ * Пропсы {@link FormWizard}. Расширяют headless-пропсы из
+ * `@reformer/cdk/form-wizard` (`form`, `config`, `onStepChange`, …), добавляя
+ * декларативный `steps` и колбэк `onSubmit`.
+ *
+ * @typeParam T - Тип значения корневой формы. Ограничение `Record<string, any>`
+ *   синхронизировано с headless-cdk и нужно только как bound для инференции
+ *   generic'а T в JSX (в т.ч. при nullable-числах вида `number | null`).
+ *
+ * @see {@link FormWizardStep} — форма элемента `steps`.
+ * @see FormWizardHandle — императивный handle через `ref` (submit/навигация).
+ */
 export interface FormWizardProps<T extends Record<string, any>> extends FormWizardHeadlessProps<T> {
+    /** Внешний CSS-класс корневого контейнера. */
     className?: string;
+    /** Декларативный список шагов (см. {@link FormWizardStep}). Порядок = порядок навигации. */
     steps: FormWizardStep<T>[];
+    /** Колбэк отправки формы на последнем шаге; вызывается после успешной валидации. */
     onSubmit: HeadlessFormWizardActionsProps['onSubmit'];
 }
 declare const FormWizardForwarded: <T extends Record<string, any>>(props: FormWizardProps<T> & {
@@ -36,5 +83,57 @@ type FormWizardCompound = typeof FormWizardForwarded & {
     Actions: typeof FormWizardHeadless.Actions;
     Progress: typeof FormWizardHeadless.Progress;
 };
+/**
+ * Готовая многошаговая форма (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` для кастомной раскладки.
+ *
+ * @typeParam T - Тип значения корневой формы (`FormProxy<T>`).
+ *
+ * @example Кредитная заявка с 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 {@link FormWizardStep} — форма элемента `steps`.
+ * @see {@link StepIndicator}, {@link FormWizardActions}, {@link FormWizardProgress} — слоты layout'а.
+ */
 declare const FormWizard: FormWizardCompound;
 export { FormWizard };

package/dist/components/form-wizard/step-indicator.d.ts

@@ -1,10 +1,37 @@
 import { FC } from 'react';
 import { FormWizardIndicatorStepWithState, FormWizardIndicatorRenderProps } from '@reformer/cdk/form-wizard';
+/**
+ * Пропсы {@link StepIndicator}: render-props индикатора из слота
+ * `<FormWizard.Indicator>` (`steps` со статусами, `goToStep`) плюс `className`
+ * и настройка aria-меток.
+ */
 export interface StepIndicatorProps extends FormWizardIndicatorRenderProps {
+    /** Внешний CSS-класс контейнера. */
     className?: string;
     /** Aria-label контейнера навигации. По умолчанию «Шаги формы». */
     navAriaLabel?: string;
     /** Кастомный шаблон aria-label для шага. Получает {step}. */
     stepAriaLabel?: (step: FormWizardIndicatorStepWithState) => string;
 }
+/**
+ * Визуальная цепочка шагов wizard'а — иконки, заголовки и соединительные линии
+ * с подсветкой текущего / завершённого шага. Клик (и Enter) по доступному шагу
+ * вызывает `goToStep`; недоступные шаги приглушены и не кликабельны. Разметка
+ * доступна для скринридеров (`role="navigation"`, `aria-current="step"`,
+ * настраиваемые aria-метки).
+ *
+ * Рендерится из headless-слота `<FormWizard.Indicator>` через render-prop
+ * (`steps` со статусами и `goToStep` приходят автоматически). Готовый
+ * {@link FormWizard} уже подключает этот компонент; напрямую нужен только для
+ * кастомной раскладки.
+ *
+ * @example Индикатор с кастомной aria-меткой контейнера
+ * ```tsx
+ * <FormWizard.Indicator steps={steps}>
+ *   {(indicator) => (
+ *     <StepIndicator {...indicator} navAriaLabel="Этапы заявки" className="mb-8" />
+ *   )}
+ * </FormWizard.Indicator>
+ * ```
+ */
 export declare const StepIndicator: FC<StepIndicatorProps>;

package/dist/components/state/error-state.d.ts

@@ -1,10 +1,31 @@
 import { ReactNode } from 'react';
 interface ErrorStateProps {
+    /** Текст ошибки, показывается под заголовком. */
     error: string;
+    /** Заголовок блока ошибки. По умолчанию `'Ошибка загрузки'`. */
     title?: string;
+    /** Колбэк повторной попытки. Если задан — рендерится кнопка «Повторить». */
     onRetry?: () => void;
+    /** Подпись кнопки повтора. По умолчанию `'Повторить'`. */
     retryLabel?: string;
+    /** Внешний CSS-класс контейнера. По умолчанию `'w-full'`. */
     className?: string;
 }
+/**
+ * Состояние ошибки — карточка с иконкой, заголовком, текстом ошибки и
+ * опциональной кнопкой повтора. Типовое применение — показать вместо формы,
+ * когда не удалось загрузить данные заявки.
+ *
+ * @param props - Пропсы: `error` (обязателен), `title`, `onRetry`, `retryLabel`, `className`.
+ * @returns Разметку блока ошибки.
+ *
+ * @example Ошибка загрузки с повтором
+ * ```tsx
+ * const { error } = useLoadCreditApplication(form, '1');
+ * if (error) {
+ *   return <ErrorState error={error} onRetry={() => window.location.reload()} />;
+ * }
+ * ```
+ */
 export declare function ErrorState({ error, title, onRetry, retryLabel, className, }: ErrorStateProps): ReactNode;
 export {};

package/dist/components/state/loading-state.d.ts

@@ -1,8 +1,26 @@
 import { ReactNode } from 'react';
 interface LoadingStateProps {
+    /** Основной текст. По умолчанию `'Загрузка данных...'`. */
     title?: string;
+    /** Вспомогательный текст под спиннером. По умолчанию `'Пожалуйста, подождите'`. */
     subtitle?: string;
+    /** Внешний CSS-класс контейнера. По умолчанию центрирует спиннер с отступами. */
     className?: string;
 }
+/**
+ * Состояние загрузки — центрированный спиннер с заголовком и подзаголовком.
+ * Типовое применение — показать вместо формы, пока грузятся данные заявки.
+ *
+ * @param props - Пропсы: `title`, `subtitle`, `className` (все опциональны).
+ * @returns Разметку блока загрузки.
+ *
+ * @example Загрузка перед рендером формы
+ * ```tsx
+ * const { isLoading } = useLoadCreditApplication(form, '1');
+ * if (isLoading) {
+ *   return <LoadingState />;
+ * }
+ * ```
+ */
 export declare function LoadingState({ title, subtitle, className, }: LoadingStateProps): ReactNode;
 export {};

package/dist/components/ui/async-boundary.d.ts

@@ -49,13 +49,15 @@ export interface AsyncBoundaryProps {
  *
  * @example Внутри 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' });
  * ```

package/dist/components/ui/box.d.ts

@@ -14,26 +14,30 @@ export interface BoxProps {
  * Простой `<div>` для группировки элементов в `RenderSchema`. Используйте
  * `className` для настройки layout через atomic CSS (Tailwind).
  *
- * @example Вертикальный список полей в RenderSchema
+ * @example Вертикальный список полей в 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 },
  *   ],
  * }
  * ```
  *
  * @example Двухколоночная сетка
  * ```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 },
  *   ],
  * }
  * ```

package/dist/components/ui/collapsible.d.ts

@@ -21,11 +21,13 @@ export interface CollapsibleProps {
  *
  * Заголовок-кнопка переключает видимость `children`. Состояние локальное
  * (`useState`), внешний control пока не поддерживается — для управляемого
- * варианта используй `RenderSchema.node('selector').setHidden(true)` поверх
- * обычного `Box`.
+ * извне варианта используй `createRenderSchema(...).node('selector').setHidden(true)`
+ * поверх обычного `Box`/`Section`.
  *
- * @example Свёрнута по умолчанию
+ * @example Свёрнута по умолчанию (M1: лист = `value` + `component`)
  * ```typescript
+ * import { Collapsible, Textarea, Input } from '@reformer/ui-kit';
+ *
  * {
  *   component: Collapsible,
  *   componentProps: {
@@ -35,14 +37,16 @@ export interface CollapsibleProps {
  *     titleClassName: 'font-semibold w-full text-left',
  *   },
  *   children: [
- *     { component: path.notes },
- *     { component: path.tags },
+ *     { value: model.$.notes, component: Textarea },
+ *     { value: model.$.tags, component: Input },
  *   ],
  * }
  * ```
  *
  * @example Развёрнута, со специальным фоном контента
  * ```typescript
+ * import { Collapsible, Textarea } from '@reformer/ui-kit';
+ *
  * {
  *   component: Collapsible,
  *   componentProps: {
@@ -51,7 +55,7 @@ export interface CollapsibleProps {
  *     contentClassName: 'mt-2 bg-gray-50 p-3 rounded',
  *   },
  *   children: [
- *     { component: path.deliveryAddress },
+ *     { value: model.$.deliveryAddress, component: Textarea },
  *   ],
  * }
  * ```

package/dist/components/ui/form-field.d.ts

@@ -34,22 +34,31 @@ export interface FormFieldProps {
  * - Обёрнут в `React.memo` со сравнением по ссылке `control` — критично для
  *   производительности больших форм.
  *
- * @example Standalone в обычной форме
+ * @example 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>
  *   );
@@ -59,11 +68,15 @@ export interface FormFieldProps {
  * @example В качестве `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 }} />

package/dist/components/ui/input.d.ts

@@ -49,6 +49,27 @@ export interface InputProps extends Omit<React.InputHTMLAttributes<HTMLInputElem
  *   placeholder="Возраст"
  * />
  * ```
+ *
+ * @example Привязка к полю формы через `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'}
+ *     />
+ *   );
+ * }
+ * ```
  */
 declare const Input: React.ForwardRefExoticComponent<InputProps & React.RefAttributes<HTMLInputElement>>;
 export { Input };

package/dist/components/ui/section.d.ts

@@ -20,8 +20,10 @@ export interface SectionProps {
  * Семантический `<section>`-контейнер для группировки связанных полей
  * с опциональным заголовком (`titleAs` управляет уровнем `h1`-`h6`).
  *
- * @example Заголовок h2 + сетка из двух колонок
+ * @example Заголовок h2 + сетка из двух колонок (M1: лист = `value` + `component`)
  * ```typescript
+ * import { Section, Input } from '@reformer/ui-kit';
+ *
  * {
  *   component: Section,
  *   componentProps: {
@@ -31,20 +33,22 @@ export interface SectionProps {
  *     className: 'grid grid-cols-2 gap-4',
  *   },
  *   children: [
- *     { component: path.firstName },
- *     { component: path.lastName },
+ *     { value: model.$.firstName, component: Input },
+ *     { value: model.$.lastName, component: Input },
  *   ],
  * }
  * ```
  *
  * @example 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 },
  *   ],
  * }
  * ```