@reformer/core 10.2.0 → 11.0.0-beta.10

package/dist/{form → platforms/react}/hooks/useFormControlValue.d.ts

@@ -1,11 +1,10 @@
-import { FieldNode } from '../nodes/field-node';
-import { FormValue } from '../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 '../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 '../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 '../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 '../types/index';
  * @example Preview значения
  * ```tsx
  * interface MarkdownEditorProps {
- *   control: FieldNode<string>;
+ *   control: FormControl<string>;
  * }
  *
  * function MarkdownPreview({ control }: MarkdownEditorProps) {
@@ -133,7 +132,8 @@ import { FormValue } from '../types/index';
  *
  * // Основной редактор использует useFormControl для полного состояния
  * function MarkdownEditor({ control }: MarkdownEditorProps) {
- *   const { value, shouldShowError, errors } = useFormControl(control);
+ *   const { value, shouldShowIssues, issues } = useFormControl(control);
+ *   const message = useIssueMessage(); // из '@reformer/core/react'
  *
  *   return (
  *     <div className="editor-container">
@@ -141,7 +141,7 @@ import { FormValue } from '../types/index';
  *         value={value}
  *         onChange={e => control.setValue(e.target.value)}
  *       />
- *       {shouldShowError && <span className="error">{errors[0]?.message}</span>}
+ *       {shouldShowIssues && <span className="error">{message(issues[0])}</span>}
  *
  *       {/* Preview обновляется только при изменении value *}
  *       <MarkdownPreview control={control} />
@@ -152,7 +152,7 @@ import { FormValue } from '../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;
  *
@@ -165,8 +165,8 @@ import { FormValue } from '../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/{form → 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

@@ -0,0 +1,18 @@
+import { I18nHandle } from '../../../i18n/translator';
+/** Имя контекста и одновременно маркер, по которому страж ищет его копии в сборках. */
+export declare const I18N_CONTEXT_MARKER = "ReformerI18nContext";
+/** Что видит компонент: ручка активной локали и состояние её загрузки. */
+export interface I18nContextValue extends I18nHandle {
+    /** Идёт загрузка другого языка; на экране пока прежний. Без загрузчика всегда `false`. */
+    readonly pending: boolean;
+    /** Ошибка последней загрузки языка. */
+    readonly error: unknown;
+    /**
+     * Повторить загрузку языка, которая упала (`error` задан). Без загрузчика и без ошибки ничего
+     * не делает.
+     */
+    readonly retry: () => void;
+}
+/** Значение контекста для локали: ручка плюс состояние загрузки. */
+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

@@ -0,0 +1,65 @@
+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';
+/**
+ * Активная локаль: перевод ключей приложения, форматирование чисел, дат и размеров, состояние
+ * загрузки языка. Без провайдера — английский с пустым словарём.
+ *
+ * @example
+ * ```tsx
+ * function LangBadge() {
+ *   const { code, pending, t } = useI18n();
+ *   return <span aria-busy={pending}>{t('app.language')}: {code}</span>;
+ * }
+ * ```
+ */
+export declare function useI18n(): I18nContextValue;
+/**
+ * Переводчик пакета: ищет ключ в локали провайдера, а при промахе берёт встроенную английскую
+ * таблицу этого пакета. Так пакет говорит по-английски без провайдера и не зависит от того, знает
+ * ли локаль его ключи. Тип ключа выводится из таблицы — опечатка в ключе не скомпилируется.
+ *
+ * `defaults` должен быть стабильной ссылкой (импорт JSON-модуля), иначе переводчик будет
+ * пересоздаваться на каждый рендер.
+ *
+ * @param defaults - Встроенная английская таблица пакета.
+ * @returns Функция `(ключ, значения?) => строка`; её идентичность меняется вместе с локалью.
+ *
+ * @example
+ * ```tsx
+ * import en from './locale/en.json';
+ *
+ * const useKitMessages = () => useMessages(en);
+ *
+ * function ClearButton() {
+ *   const t = useKitMessages();
+ *   return <button aria-label={t('kit.select.clear')} />;
+ * }
+ * ```
+ */
+export declare function useMessages<D extends Messages>(defaults: D): (key: keyof D & string, values?: MessageValues) => string;
+/**
+ * Резолвер текста замечания валидации: словарь формы → словарь активной локали по коду →
+ * встроенный английский → код. Идентичность функции меняется вместе с локалью и словарём,
+ * поэтому показанные замечания переводятся при смене языка без повторной валидации.
+ *
+ * `FormField` из `@reformer/cdk` использует его сам; вызывайте напрямую, если рисуете замечания
+ * своим компонентом.
+ *
+ * @param messages - Словарь формы (`defineIssueMessages`). Стабильная ссылка — константа
+ *   модуля, иначе резолвер будет пересоздаваться на каждый рендер.
+ *
+ * @example
+ * ```tsx
+ * 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 useIssueMessage(messages?: IssueMessages): (issue: ValidationIssue) => string;

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

@@ -0,0 +1,59 @@
+import { ReactElement, ReactNode } from 'react';
+import { FormLocale } from '../../../i18n/locale';
+import { LocaleLoad } from '../../../i18n/locale-store';
+/** Режим «готовая локаль». */
+export interface I18nStaticProviderProps {
+    /** Локаль. Смена объекта переключает язык сразу. */
+    locale: FormLocale;
+    children?: ReactNode;
+}
+/** Режим «провайдер грузит сам». */
+export interface I18nLoadingProviderProps {
+    /** Код языка. Смена кода запускает загрузку; до её конца на экране прежний язык. */
+    lang: string;
+    /**
+     * Загрузчик локалей — обычно результат `createLocaleLoader`. Нужна СТАБИЛЬНАЯ ссылка (модульная
+     * константа, `useMemo`): новый загрузчик — новое хранилище, и язык запрашивается у него заново.
+     * На экране тем временем остаётся прежняя локаль, но инлайн-стрелка гоняла бы запрос на каждый
+     * рендер родителя.
+     */
+    load: LocaleLoad;
+    /**
+     * Что показать, пока не загружена самая первая локаль. По умолчанию — ничего: иначе на кадр
+     * мелькнул бы встроенный английский. Если локаль уже в кэше загрузчика (`load.preload(lang)`
+     * до монтирования), первый рендер синхронный и `fallback` не показывается. Упала первая
+     * загрузка — дети показываются на встроенном английском, ошибка — в `useI18n().error`,
+     * повторить — `useI18n().retry()`.
+     */
+    fallback?: ReactNode;
+    /** Отказ загрузки. Язык на экране при этом не меняется. */
+    onError?: (error: unknown, lang: string) => void;
+    children?: ReactNode;
+}
+export type I18nProviderProps = I18nStaticProviderProps | I18nLoadingProviderProps;
+/**
+ * Провайдер локализации для подписей компонентов, ошибок валидации и авторских подписей формы.
+ * Без провайдера компоненты говорят встроенным английским.
+ *
+ * При смене `lang` на экране остаётся прежний язык, пока новый не загрузится (`useI18n().pending`
+ * — для индикатора). При быстром переключении применяется только последний запрос. Вложенный
+ * провайдер заменяет локаль для своего поддерева целиком.
+ *
+ * @example Провайдер грузит локаль сам
+ * ```tsx
+ * const [lang, setLang] = useState('ru');
+ *
+ * <I18nProvider lang={lang} load={loadLocale}>
+ *   <LangSwitch value={lang} onChange={setLang} />
+ *   <CreditForm />
+ * </I18nProvider>
+ * ```
+ *
+ * @example Готовая локаль — SSR и тесты
+ * ```tsx
+ * import { ru } from '@reformer/ui-kit/locale/ru';
+ *
+ * <I18nProvider locale={ru}><CreditForm /></I18nProvider>
+ * ```
+ */
+export declare function I18nProvider(props: I18nProviderProps): ReactElement | null;

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

@@ -0,0 +1,30 @@
+/**
+ * Модуль `platforms/react` — биндинги ядра к React.
+ *
+ * Единственное место в пакете, где есть runtime-зависимость от `react` и
+ * `use-sync-external-store`: слои `model` и `form` от React свободны и в рантайме, и в типах
+ * (компонент узла схемы для них — непрозрачная ссылка `ComponentRef`). Хуки читают
+ * сигналы нод формы через `useSyncExternalStore` и отдают плоские снапшоты
+ * ({@link FieldControlState}/{@link ArrayControlState}) в рендер.
+ *
+ * Состав barrel'а отдаёт вход `@reformer/core/react` (`src/react.ts`); корень `@reformer/core` его
+ * не реэкспортирует.
+ *
+ * @group Platforms
+ * @module platforms/react
+ */
+export { useFormControl } from './hooks/useFormControl';
+export { useFormControlValue } from './hooks/useFormControlValue';
+export { useArrayLength } from './hooks/useArrayLength';
+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';
+export type { FieldAdapter, FieldAdapterCarrier, FieldSeam } from './field-binding/field-adapter';
+export { makeElementFieldHandle, useFieldHandleRef } from './field-binding/field-handle';
+export type { FieldHandle } from './field-binding/field-handle';

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';