@reformer/core 11.0.0-beta.8 → 11.0.0-beta.9

package/dist/platforms/react/hooks/use-form-bundle.d.ts

@@ -1,26 +1,41 @@
 import { FormValidationController } from '../../../form/validation/strategy';
-/** Минимум, который хук ожидает от бандла: опциональный контроллер живой валидации. */
+/** Минимум, который хук ожидает от бандла: контроллер живой валидации и снятие — оба опционально. */
 export interface FormBundleLike {
     validation?: {
         controller: FormValidationController;
     };
+    /** Снять сборку: поведение, подписки нод, живую проверку. Есть у всех фабрик семейства. */
+    dispose?(): void;
 }
 /**
  * Собрать форму один раз и держать её стабильной; живую стратегию валидации армировать в эффекте
- * (не при SSR — там эффекты не выполняются).
+ * (не при SSR — там эффекты не выполняются); при размонтировании снять сборку.
  *
  * @typeParam B - Тип бандла конкретной фабрики.
- * @param factory - Фабрика бандла, обычно `() => createCoreForm({…})`.
+ * @param factory - Фабрика бандла, обычно `() => createForm({…})`. Сборкой владеет хук: при
+ *   размонтировании он вызывает её `dispose()`, поэтому фабрика должна собирать НОВУЮ форму, а не
+ *   возвращать чужую, живущую дольше компонента.
  * @returns Стабильный бандл.
  *
  * @example
  * ```tsx
- * const credit = useFormBundle(() => createCoreForm<CreditForm>({ model: createCreditModel() }));
+ * const credit = useFormBundle(() => createForm<CreditForm>({ model: createCreditModel() }));
  * ```
  *
  * @remarks
  * Передавайте именно фабрику: `useState` трактует функцию как ленивый инициализатор, а некоторые
  * части бандла сами являются функциями (`RenderSchemaProxy`), поэтому `useFormBundle(bundle.render)`
  * вызвал бы её вместо сохранения.
+ *
+ * Сборка снимается микрозадачей после размонтирования, а не в самой очистке эффекта (см. шапку
+ * модуля): код, который сразу после размонтирования пишет в модель, ещё видит живое поведение.
+ *
+ * **Ограничение StrictMode (только разработка).** StrictMode вызывает ленивый инициализатор
+ * `useState` дважды, и фабрика на монтирование срабатывает два раза. Второй бандл React
+ * выбрасывает до коммита: хук его не видит, поэтому не армирует и не снимает. Живая проверка у
+ * него не запущена, но поведение (`compute`, `onChange`, …) работает, пока бандл не соберёт
+ * сборщик мусора. В production инициализатор вызывается один раз и утечки нет. Побочные эффекты
+ * на создание (запрос данных в фабрике или в `setup`) в разработке поэтому тоже срабатывают
+ * дважды — запускайте их из поведения формы или из эффекта компонента.
  */
 export declare function useFormBundle<B extends FormBundleLike>(factory: () => B): B;

package/dist/platforms/react/hooks/use-form-flow.d.ts

@@ -0,0 +1,40 @@
+import { FormFlow } from '../../../form/flow/flow';
+/**
+ * Состояние потока на момент рендера.
+ *
+ * @group React
+ */
+export interface FormFlowSnapshot {
+    /** Текущий шаг. */
+    readonly current: string;
+    /** Номер текущего шага с нуля. */
+    readonly index: number;
+    /** Пройденные шаги. */
+    readonly completed: ReadonlySet<string>;
+    readonly isFirst: boolean;
+    readonly isLast: boolean;
+    /** Идёт ли проверка шага. */
+    readonly validating: boolean;
+}
+/**
+ * Подписаться на поток шагов: компонент перерисовывается при смене шага, пройденных шагов и
+ * состояния проверки. Переходы — методами самого потока (`flow.next()`, `flow.goTo(id)`).
+ *
+ * @param flow - Поток шагов (`bundle.flow`).
+ * @returns {@link FormFlowSnapshot}.
+ *
+ * @example
+ * ```tsx
+ * function Steps({ flow }: { flow: FormFlow }) {
+ *   const { current, isLast, validating } = useFormFlow(flow);
+ *   return (
+ *     <button disabled={isLast || validating} onClick={() => void flow.next()}>
+ *       Далее ({current})
+ *     </button>
+ *   );
+ * }
+ * ```
+ *
+ * @group React
+ */
+export declare function useFormFlow(flow: FormFlow): FormFlowSnapshot;

package/dist/platforms/react/hooks/use-form-validation.d.ts

@@ -1,11 +1,11 @@
-import { FormModel } from '../../../index';
-import { ValidationSchema } from '../../../form/validation';
+import { FormModel } from '../../../model/types';
+import { ValidationDefinition } from '../../../form/validation';
 import { ValidationStrategyKind } from '../../../form/validation/strategy';
 export interface UseFormValidationArgs<T> {
     /** Модель данных формы. */
     model: FormModel<T>;
     /** Схема валидации. **Стабильная ссылка** (module-level `const` / `useMemo`) — иначе ломается дедуп раннера. */
-    schema: ValidationSchema<T>;
+    schema: ValidationDefinition<T>;
     /** Стратегия запуска. Default `'submit'`. */
     strategy?: ValidationStrategyKind;
     /** Debounce (мс) для live-фаз (`change` / live-часть `afterFirstSubmit`). */
@@ -14,9 +14,15 @@ export interface UseFormValidationArgs<T> {
     liveAfterSubmit?: 'change' | 'blur';
 }
 export interface UseFormValidationResult {
-    /** Полный прогон + раскрытие ошибок (`touch:true`); для `onSubmit`. Стабильная ссылка. */
+    /**
+     * Попытка отправки: полный прогон; при замечаниях раскрыта вся форма, `afterFirstSubmit`
+     * переходит в живую фазу. `true` — только статус `valid`. Для `onSubmit`. Стабильная ссылка.
+     */
     submit: () => Promise<boolean>;
-    /** Алиас `submit` для не-submit сценариев. */
+    /**
+     * Проверка без отправки: полный прогон, раскрыты замечания проверенных полей, фаза
+     * `afterFirstSubmit` не меняется. Для кнопки «Проверить». Стабильная ссылка.
+     */
     validate: () => Promise<boolean>;
     /** Идёт ли прогон (submit или live) — для блокировки кнопки. */
     isValidating: boolean;
@@ -31,7 +37,7 @@ export interface UseFormValidationResult {
  *
  * @example
  * ```tsx
- * const validation = defineValidationSchema<Form>(({ model }) => { ... }); // module-level
+ * const validation = defineValidation<Form>(({ model }) => { ... }); // module-level
  *
  * function MyForm() {
  *   const { submit, isValidating } = useFormValidation({

package/dist/platforms/react/hooks/useArrayLength.d.ts

@@ -1,13 +1,13 @@
-import { ArrayNode } from '../../../form/nodes/array-node';
+import { FormArray } from '../../../form/types/index';
 /**
  * React-хук для подписки только на длину массива.
  *
- * Оптимизированная версия {@link useFormControl} для ArrayNode, которая
- * подписывается только на сигнал `length`. Компонент не будет ре-рендериться
+ * Оптимизированная версия {@link useFormControl} для FormArray, которая
+ * подписывается только на длину массива. Компонент не будет ре-рендериться
  * при изменении значений вложенных полей.
  *
  * @typeParam T - Тип элемента массива
- * @param control - ArrayNode для подписки
+ * @param control - FormArray для подписки
  * @returns Текущая длина массива
  *
  * @example
@@ -18,7 +18,7 @@ import { ArrayNode } from '../../../form/nodes/array-node';
  *   return (
  *     <div>
  *       {arrayNode.map((item, index) => (
- *         <ItemRenderer key={item.id} item={item} />
+ *         <ItemRenderer key={arrayNode.keyAt(index)} item={item} />
  *       ))}
  *     </div>
  *   );
@@ -27,4 +27,4 @@ import { ArrayNode } from '../../../form/nodes/array-node';
  *
  * @group React Hooks
  */
-export declare function useArrayLength<T extends object>(control: ArrayNode<T>): number;
+export declare function useArrayLength<T extends object>(control: FormArray<T>): number;

package/dist/platforms/react/hooks/useFormControl.d.ts

@@ -1,24 +1,22 @@
-import { FieldNode } from '../../../form/nodes/field-node';
-import { ArrayNode } from '../../../form/nodes/array-node';
-import { FormValue } from '../../../form/types/index';
+import { FormArray, FormControl } from '../../../form/types/index';
 import { FieldControlState, ArrayControlState } from './types';
 /**
- * React-хук для подписки на состояние {@link ArrayNode}.
+ * React-хук для подписки на состояние {@link FormArray}.
  *
  * @typeParam T - Тип элемента массива
- * @param control - ArrayNode или undefined
+ * @param control - FormArray или undefined
  * @returns Состояние массива {@link ArrayControlState}
  *
  * @group React Hooks
  */
-export declare function useFormControl<T extends object>(control: ArrayNode<T> | undefined): ArrayControlState<T>;
+export declare function useFormControl<T extends object>(control: FormArray<T> | undefined): ArrayControlState<T>;
 /**
- * React-хук для подписки на состояние {@link FieldNode}.
+ * React-хук для подписки на состояние {@link FormControl}.
  *
  * @typeParam T - Тип значения поля
- * @param control - FieldNode для подписки
+ * @param control - FormControl для подписки
  * @returns Состояние поля {@link FieldControlState}
  *
  * @group React Hooks
  */
-export declare function useFormControl<T extends FormValue>(control: FieldNode<T>): FieldControlState<T>;
+export declare function useFormControl<T>(control: FormControl<T>): FieldControlState<T>;

package/dist/platforms/react/hooks/useFormControlValue.d.ts

@@ -1,11 +1,10 @@
-import { FieldNode } from '../../../form/nodes/field-node';
-import { FormValue } from '../../../form/types/index';
+import { FormControl } from '../../../form/types/index';
 /**
  * React-хук для подписки только на значение поля.
  *
  * Оптимизированная версия {@link useFormControl}, которая подписывается
  * только на сигнал `value`. Компонент не будет ре-рендериться при изменении
- * `errors`, `touched`, `valid` и других свойств состояния.
+ * `issues`, `touched`, `valid` и других свойств состояния.
  *
  * ## Когда использовать
  *
@@ -16,21 +15,21 @@ import { FormValue } from '../../../form/types/index';
  *
  * ## Когда НЕ использовать
  *
- * Если компоненту нужны `errors`, `touched`, `disabled` или другие свойства -
+ * Если компоненту нужны `issues`, `touched`, `disabled` или другие свойства -
  * используйте {@link useFormControl}. Множественные подписки на один контрол
  * через разные хуки менее эффективны, чем одна подписка через `useFormControl`.
  *
  * @typeParam T - Тип значения поля
- * @param control - FieldNode для подписки на значение
+ * @param control - FormControl для подписки на значение
  * @returns Текущее значение поля
  *
  * @example Условный рендеринг секции
  * ```tsx
- * import { useFormControlValue } from '@reformer/core';
+ * import { useFormControlValue } from '@reformer/core/react';
  *
  * interface FormFields {
- *   hasShipping: FieldNode<boolean>;
- *   shippingAddress: GroupNode<AddressFields>;
+ *   hasShipping: FormControl<boolean>;
+ *   shippingAddress: FormGroup<AddressFields>;
  * }
  *
  * function ShippingSection({ form }: { form: FormFields }) {
@@ -53,8 +52,8 @@ import { FormValue } from '../../../form/types/index';
  * @example Динамические опции на основе другого поля
  * ```tsx
  * interface FormFields {
- *   country: FieldNode<string>;
- *   city: FieldNode<string>;
+ *   country: FormControl<string>;
+ *   city: FormControl<string>;
  * }
  *
  * function CitySelect({ form }: { form: FormFields }) {
@@ -93,14 +92,14 @@ import { FormValue } from '../../../form/types/index';
  *
  * // Хук вызывается на уровне компонента-строки (не в цикле — Rules of Hooks).
  * // Доступ к полям элемента — через Proxy: item.quantity, item.price.
- * function OrderRow({ item }: { item: FormProxy<OrderItem> }) {
+ * function OrderRow({ item }: { item: FormGroup<OrderItem> }) {
  *   const quantity = useFormControlValue(item.quantity);
  *   const price = useFormControlValue(item.price);
  *
  *   return <span>Итого: ${(quantity * price).toFixed(2)}</span>;
  * }
  *
- * function OrderList({ items }: { items: ArrayNode<OrderItem> }) {
+ * function OrderList({ items }: { items: FormArray<OrderItem> }) {
  *   return (
  *     <div>
  *       {items.map((item, index) => (
@@ -114,7 +113,7 @@ import { FormValue } from '../../../form/types/index';
  * @example Preview значения
  * ```tsx
  * interface MarkdownEditorProps {
- *   control: FieldNode<string>;
+ *   control: FormControl<string>;
  * }
  *
  * function MarkdownPreview({ control }: MarkdownEditorProps) {
@@ -133,8 +132,8 @@ import { FormValue } from '../../../form/types/index';
  *
  * // Основной редактор использует useFormControl для полного состояния
  * function MarkdownEditor({ control }: MarkdownEditorProps) {
- *   const { value, shouldShowError, errors } = useFormControl(control);
- *   const message = useValidationMessage(); // из '@reformer/core/i18n'
+ *   const { value, shouldShowIssues, issues } = useFormControl(control);
+ *   const message = useIssueMessage(); // из '@reformer/core/react'
  *
  *   return (
  *     <div className="editor-container">
@@ -142,7 +141,7 @@ import { FormValue } from '../../../form/types/index';
  *         value={value}
  *         onChange={e => control.setValue(e.target.value)}
  *       />
- *       {shouldShowError && <span className="error">{message(errors[0])}</span>}
+ *       {shouldShowIssues && <span className="error">{message(issues[0])}</span>}
  *
  *       {/* Preview обновляется только при изменении value *}
  *       <MarkdownPreview control={control} />
@@ -153,7 +152,7 @@ import { FormValue } from '../../../form/types/index';
  *
  * @example Счётчик символов
  * ```tsx
- * function CharacterCounter({ control, max }: { control: FieldNode<string>; max: number }) {
+ * function CharacterCounter({ control, max }: { control: FormControl<string>; max: number }) {
  *   const value = useFormControlValue(control);
  *   const remaining = max - value.length;
  *
@@ -166,8 +165,8 @@ import { FormValue } from '../../../form/types/index';
  * ```
  *
  * @see {@link useFormControl} - для полного состояния поля
- * @see {@link FieldNode} - тип контрола поля
+ * @see {@link FormControl} - тип контрола поля
  *
  * @group React Hooks
  */
-export declare function useFormControlValue<T extends FormValue>(control: FieldNode<T>): T;
+export declare function useFormControlValue<T>(control: FormControl<T>): T;

package/dist/platforms/react/hooks/useSignalSubscription.d.ts

@@ -9,9 +9,17 @@ export type ExtractSignalValues<T extends SignalMap> = {
 export interface SignalConfig<K extends string> {
     key: K;
     useShallowArrayEqual?: boolean;
+    /**
+     * Сравнивать объект поверхностно: новый объект с теми же значениями (`updateComponentProps`
+     * теми же пропсами) снапшот не меняет.
+     */
+    useShallowObjectEqual?: boolean;
 }
 /**
- * Хук для подписки на набор сигналов с кешированием
+ * Хук для подписки на набор сигналов с кешированием.
+ *
+ * Подписка — только на сигналы из `configs`: их смена пересобирает снапшот. Остальные сигналы
+ * `signals` в снапшот попадают значением на момент сборки и сами компонент не будят.
  * @internal
  */
 export declare function useSignalSubscription<TSignals extends SignalMap, TSnapshot extends ExtractSignalValues<TSignals>>(signals: TSignals, configs: SignalConfig<Extract<keyof TSignals, string>>[], buildSnapshot: (values: ExtractSignalValues<TSignals>) => TSnapshot, 

package/dist/platforms/react/i18n/context.d.ts

@@ -7,7 +7,12 @@ export interface I18nContextValue extends I18nHandle {
     readonly pending: boolean;
     /** Ошибка последней загрузки языка. */
     readonly error: unknown;
+    /**
+     * Повторить загрузку языка, которая упала (`error` задан). Без загрузчика и без ошибки ничего
+     * не делает.
+     */
+    readonly retry: () => void;
 }
 /** Значение контекста для локали: ручка плюс состояние загрузки. */
-export declare function contextValue(handle: I18nHandle, pending: boolean, error: unknown): I18nContextValue;
+export declare function contextValue(handle: I18nHandle, pending: boolean, error: unknown, retry?: () => void): I18nContextValue;
 export declare const I18nContext: import('react').Context<I18nContextValue>;

package/dist/platforms/react/i18n/hooks.d.ts

@@ -1,6 +1,7 @@
-import { ValidationError } from '../../../form/types/contracts';
+import { ValidationIssue } from '../../../form/types/contracts';
 import { Messages } from '../../../i18n/locale';
 import { MessageValues } from '../../../i18n/message-format';
+import { IssueMessages } from '../../../i18n/validation-message';
 import { I18nContextValue } from './context';
 /**
  * Активная локаль: перевод ключей приложения, форматирование чисел, дат и размеров, состояние
@@ -40,20 +41,25 @@ export declare function useI18n(): I18nContextValue;
  */
 export declare function useMessages<D extends Messages>(defaults: D): (key: keyof D & string, values?: MessageValues) => string;
 /**
- * Резолвер текста ошибки валидации по активной локали: `messageKey` автора → явное `message` →
- * словарь локали по коду → встроенный английский → код. Идентичность функции меняется вместе с
- * локалью, поэтому показанные ошибки переводятся при смене языка без повторной валидации.
+ * Резолвер текста замечания валидации: словарь формы → словарь активной локали по коду →
+ * встроенный английский → код. Идентичность функции меняется вместе с локалью и словарём,
+ * поэтому показанные замечания переводятся при смене языка без повторной валидации.
  *
- * `FormField` из `@reformer/cdk` использует его сам; вызывайте напрямую, если рисуете ошибки
+ * `FormField` из `@reformer/cdk` использует его сам; вызывайте напрямую, если рисуете замечания
  * своим компонентом.
  *
+ * @param messages - Словарь формы (`defineIssueMessages`). Стабильная ссылка — константа
+ *   модуля, иначе резолвер будет пересоздаваться на каждый рендер.
+ *
  * @example
  * ```tsx
- * function FieldErrors({ control }: { control: FieldNode<string> }) {
- *   const message = useValidationMessage();
- *   const { errors } = useFormControl(control);
- *   return <>{errors.map((error) => <span key={error.code}>{message(error)}</span>)}</>;
+ * const messages = defineIssueMessages({ 'phone.required': 'Укажите телефон' });
+ *
+ * function FieldIssues({ control }: { control: FormControl<string> }) {
+ *   const message = useIssueMessage(messages);
+ *   const { issues } = useFormControl(control);
+ *   return <>{issues.map((issue) => <span key={issue.code}>{message(issue)}</span>)}</>;
  * }
  * ```
  */
-export declare function useValidationMessage(): (error: ValidationError) => string;
+export declare function useIssueMessage(messages?: IssueMessages): (issue: ValidationIssue) => string;

package/dist/platforms/react/i18n/provider.d.ts

@@ -11,12 +11,19 @@ export interface I18nStaticProviderProps {
 export interface I18nLoadingProviderProps {
     /** Код языка. Смена кода запускает загрузку; до её конца на экране прежний язык. */
     lang: string;
-    /** Загрузчик локалей — обычно результат `createLocaleLoader`. */
+    /**
+     * Загрузчик локалей — обычно результат `createLocaleLoader`. Нужна СТАБИЛЬНАЯ ссылка (модульная
+     * константа, `useMemo`): новый загрузчик — новое хранилище, и язык запрашивается у него заново.
+     * На экране тем временем остаётся прежняя локаль, но инлайн-стрелка гоняла бы запрос на каждый
+     * рендер родителя.
+     */
     load: LocaleLoad;
     /**
      * Что показать, пока не загружена самая первая локаль. По умолчанию — ничего: иначе на кадр
      * мелькнул бы встроенный английский. Если локаль уже в кэше загрузчика (`load.preload(lang)`
-     * до монтирования), первый рендер синхронный и `fallback` не показывается.
+     * до монтирования), первый рендер синхронный и `fallback` не показывается. Упала первая
+     * загрузка — дети показываются на встроенном английском, ошибка — в `useI18n().error`,
+     * повторить — `useI18n().retry()`.
      */
     fallback?: ReactNode;
     /** Отказ загрузки. Язык на экране при этом не меняется. */

package/dist/platforms/react/index.d.ts

@@ -2,13 +2,13 @@
  * Модуль `platforms/react` — биндинги ядра к React.
  *
  * Единственное место в пакете, где есть runtime-зависимость от `react` и
- * `use-sync-external-store`: слои `model` и `form` от React свободны (в `form/types/` остаются
- * только type-only `ComponentType`/`ElementType` — они стираются при компиляции). Хуки читают
+ * `use-sync-external-store`: слои `model` и `form` от React свободны и в рантайме, и в типах
+ * (компонент узла схемы для них — непрозрачная ссылка `ComponentRef`). Хуки читают
  * сигналы нод формы через `useSyncExternalStore` и отдают плоские снапшоты
  * ({@link FieldControlState}/{@link ArrayControlState}) в рендер.
  *
- * Barrel заведён как точка для будущего сабпата `@reformer/core/react`; сейчас его состав
- * реэкспортируется зонтиком `@reformer/core` — ровно теми же именами, что и до выноса.
+ * Состав barrel'а отдаёт вход `@reformer/core/react` (`src/react.ts`); корень `@reformer/core` его
+ * не реэкспортирует.
  *
  * @group Platforms
  * @module platforms/react
@@ -20,6 +20,8 @@ export { useFormValidation } from './hooks/use-form-validation';
 export type { UseFormValidationArgs, UseFormValidationResult } from './hooks/use-form-validation';
 export { useFormBundle } from './hooks/use-form-bundle';
 export type { FormBundleLike } from './hooks/use-form-bundle';
+export { useFormFlow } from './hooks/use-form-flow';
+export type { FormFlowSnapshot } from './hooks/use-form-flow';
 export { FormBundleContext, useFormBundleContext } from './form-bundle-context';
 export type { FieldControlState, ArrayControlState } from './hooks/types';
 export { getFieldAdapter, bindFieldProps, FIELD_WRAPPER_ONLY_PROPS, } from './field-binding/field-adapter';

package/dist/react.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Подпуть `@reformer/core/react` — привязка ядра к React: хуки нод формы, связка поля с контролом,
+ * контекст сборки и React-часть локализации.
+ *
+ * Единственный вход пакета с зависимостью от `react`. Корень `@reformer/core` и остальные сабпаты
+ * от React свободны, поэтому `react` и `react-dom` — необязательные peer-зависимости: они нужны
+ * только тому, кто импортирует этот вход.
+ *
+ * Контекст локализации обязан существовать в одном экземпляре на все пакеты `@reformer/*`:
+ * пакеты получают его отсюда как внешнюю зависимость и не включают в свою сборку
+ * (страж — `scripts/check-i18n-singleton.mjs`).
+ *
+ * @group Platforms
+ * @module react
+ * @mergeModuleWith <project>
+ */
+export * from './platforms/react/index';
+export { I18nProvider } from './platforms/react/i18n/provider';
+export type { I18nProviderProps, I18nStaticProviderProps, I18nLoadingProviderProps, } from './platforms/react/i18n/provider';
+export { useI18n, useMessages, useIssueMessage } from './platforms/react/i18n/hooks';
+export { I18N_CONTEXT_MARKER } from './platforms/react/i18n/context';
+export type { I18nContextValue } from './platforms/react/i18n/context';