@reformer/core 10.2.0 → 11.0.0-beta.10

package/dist/form/{validation/validators → validators}/phone.d.ts

@@ -1,4 +1,5 @@
-import { Validator, ValidateOptions } from '../../types/validation-schema';
+import { RuleOptions } from '../types/validation-schema';
+import { Rule } from '../validation/types';
 /**
  * Формат проверки номера телефона для валидатора {@link phone}.
  *
@@ -9,10 +10,10 @@ import { Validator, ValidateOptions } from '../../types/validation-schema';
  */
 export type PhoneFormat = 'international' | 'ru' | 'us' | 'any';
 /**
- * Опции валидатора {@link phone}. Расширяют {@link ValidateOptions} (`message`, `params`)
+ * Опции валидатора {@link phone}. Расширяют {@link RuleOptions} (`code`, `params`)
  * выбором формата номера.
  */
-export interface PhoneValidatorOptions extends ValidateOptions {
+export interface PhoneValidatorOptions extends RuleOptions {
     /** Формат проверки {@link PhoneFormat}. По умолчанию `'any'`. */
     format?: PhoneFormat;
 }
@@ -24,18 +25,17 @@ export interface PhoneValidatorOptions extends ValidateOptions {
  *
  * @param options - Опции валидатора {@link PhoneValidatorOptions}. В `params` ошибки
  *   автоматически попадает выбранный `format`.
- * @returns Чистый валидатор {@link Validator} для строкового поля
+ * @returns Правило {@link Rule} для строкового поля
  *
  * @example Проверка номера телефона
  * ```typescript
+ * import { defineValidation, validate } from '@reformer/core/validation';
  * import { required, phone } from '@reformer/core/validators';
  *
- * // Внутри FieldConfig схемы формы:
- * phone: {
- *   value: model.$.phone,
- *   component: Input,
- *   validators: [required(), phone({ format: 'ru' })],
- * },
+ * // Правила живут в отдельной схеме над МОДЕЛЬЮ — layout-схема валидаторов не несёт.
+ * const validation = defineValidation<MyForm>(({ model }) => {
+ *   validate(model.$.phone, [required(), phone({ format: 'ru' })]);
+ * });
  * ```
  */
-export declare function phone<TForm = unknown, TField extends string | null | undefined = string>(options?: PhoneValidatorOptions): Validator<TForm, TField>;
+export declare function phone(options?: PhoneValidatorOptions): Rule<string | null | undefined>;

package/dist/form/validators/required.d.ts

@@ -0,0 +1,29 @@
+import { RuleOptions } from '../types/validation-schema';
+import { Rule } from '../validation/types';
+/**
+ * Фабрика валидатора обязательного поля.
+ *
+ * Возвращает чистую функцию-валидатор `(value, control, root)`. Передаётся в `validate()`.
+ *
+ * Пустыми считаются: `null`, `undefined`, `''` (пустая строка), `[]` (пустой массив —
+ * обязательный multi-select / FieldArray без выбранных элементов), `NaN` (так выглядит очищенный
+ * числовой ввод).
+ * Для boolean полей требуется значение `true`.
+ *
+ * @param options - Опции валидатора ({@link RuleOptions}): `code`, `params`
+ * @returns Правило {@link Rule} для поля схемы
+ *
+ * @example Обязательные поля в схеме формы
+ * ```typescript
+ * import { defineValidation, validate } from '@reformer/core/validation';
+ * import { required } from '@reformer/core/validators';
+ *
+ * // Правила живут в отдельной схеме над МОДЕЛЬЮ — layout-схема валидаторов не несёт.
+ * const validation = defineValidation<MyForm>(({ model }) => {
+ *   validate(model.$.email, [required()]);
+ *   validate(model.$.phone, [required({ code: 'phone.required' })]);
+ *   validate(model.$.agreeToTerms, [required({ code: 'agreeToTerms.required' })]);
+ * });
+ * ```
+ */
+export declare function required(options?: RuleOptions): Rule<unknown>;

package/dist/form/validators/url.d.ts

@@ -0,0 +1,45 @@
+import { RuleOptions } from '../types/validation-schema';
+import { Rule } from '../validation/types';
+/**
+ * Опции валидатора {@link url}. Расширяют {@link RuleOptions} (`code`, `params`)
+ * настройками проверки протокола.
+ */
+export interface UrlValidatorOptions extends RuleOptions {
+    /** Требовать протокол (`схема://`). По умолчанию `false`: `example.com` допустим. */
+    requireProtocol?: boolean;
+    /**
+     * Разрешённые протоколы (без `://`), сравнение без учёта регистра, например `['https']`. Не
+     * задан или пуст — `http` и `https`. Значение с иным протоколом даёт замечание `url_protocol`;
+     * при заданном списке — и значение без протокола.
+     */
+    allowedProtocols?: string[];
+}
+/**
+ * Фабрика валидатора URL.
+ *
+ * Пустые значения (`''`/`null`/`undefined`) пропускаются (используйте {@link required}
+ * для обязательности).
+ *
+ * Контракт адреса: разбор — `new URL`; хост — `localhost`, домен с буквенной зоной (в том числе
+ * кириллический и punycode), IPv4 или `[IPv6]`; порт допустим. Запрещены пробелы и userinfo
+ * (`user:pass@`). Протокол необязателен (`example.com`), пока не задан `requireProtocol`; по
+ * умолчанию разрешены `http` и `https`, чужой протокол — замечание `url_protocol` с
+ * `params.allowedProtocols`. Свой `code` из опций заменяет оба встроенных кода.
+ *
+ * @param options - Опции валидатора {@link UrlValidatorOptions}
+ * @returns Правило {@link Rule} для строкового поля
+ *
+ * @example Проверка URL
+ * ```typescript
+ * import { defineValidation, validate } from '@reformer/core/validation';
+ * import { required, url } from '@reformer/core/validators';
+ *
+ * // Правила живут в отдельной схеме над МОДЕЛЬЮ — layout-схема валидаторов не несёт.
+ * const validation = defineValidation<MyForm>(({ model }) => {
+ *   validate(model.$.website, [required(), url({ code: 'website.url' })]);
+ *   // Требовать протокол и ограничить схему только https:
+ *   validate(model.$.homepage, [url({ requireProtocol: true, allowedProtocols: ['https'] })]);
+ * });
+ * ```
+ */
+export declare function url(options?: UrlValidatorOptions): Rule<string | null | undefined>;

package/dist/form/validators/validation-issue.d.ts

@@ -0,0 +1,8 @@
+import { ValidationIssue } from '../types/contracts';
+import { RuleOptions } from '../types/validation-schema';
+/**
+ * @param code - Встроенный код правила; по нему ищется текст в словаре локали (`validation.<code>`).
+ * @param options - Опции правила: свой код и дополнительные параметры.
+ * @param params - Параметры, которые правило заполняет само; параметры из `options` важнее.
+ */
+export declare function validationIssue(code: string, options: RuleOptions | undefined, params?: Record<string, unknown>): ValidationIssue;

package/dist/i18n/descriptor.d.ts

@@ -0,0 +1,54 @@
+import { Messages } from './locale';
+/**
+ * Бренд описателя. `Symbol.for` — чтобы описатель узнавался и через границу двух копий модуля
+ * (разные чанки, разные версии пакета на странице).
+ */
+export declare const MESSAGE_DESCRIPTOR: unique symbol;
+/**
+ * Описатель сообщения. Намеренно без ключей `value`, `array`, `item`, `component`: обход схемы в
+ * `createForm` узнаёт по ним узел, а описатель узлом не является.
+ */
+export interface MessageDescriptor {
+    readonly [MESSAGE_DESCRIPTOR]: true;
+    /** Ключ сообщения в словаре приложения. */
+    readonly key: string;
+    /** Значения подстановок. */
+    readonly values?: Readonly<Record<string, unknown>>;
+    /** Английский текст на случай, если ключа в локали нет. */
+    readonly defaultMessage?: string;
+}
+/** Текст, который можно задать строкой или описателем. */
+export type LocalizableText = string | MessageDescriptor;
+/**
+ * Создаёт описатель сообщения.
+ *
+ * @param key - Ключ в словаре приложения.
+ * @param values - Значения подстановок.
+ * @param defaultMessage - Английский текст на случай, если ключа в локали нет.
+ *
+ * @example
+ * ```ts
+ * { model: model.$.email, component: Input, componentProps: { label: msg('profile.email.label') } }
+ * ```
+ */
+export declare function msg(key: string, values?: Readonly<Record<string, unknown>>, defaultMessage?: string): MessageDescriptor;
+/** Является ли значение описателем сообщения. */
+export declare function isMessageDescriptor(value: unknown): value is MessageDescriptor;
+/**
+ * `msg` с типизированными ключами: принимает английский словарь приложения, проверяет ключ при
+ * компиляции и подставляет английский текст как `defaultMessage` — без провайдера и при промахе
+ * по локали форма покажет его, а не ключ.
+ *
+ * @param defaults - Английский словарь приложения.
+ *
+ * @example
+ * ```ts
+ * import appEn from './locales/en.json';
+ *
+ * export const { msg } = defineMessages(appEn);
+ * msg('profile.email.label'); // опечатка в ключе — ошибка компиляции
+ * ```
+ */
+export declare function defineMessages<D extends Messages>(defaults: D): {
+    msg(key: keyof D & string, values?: Readonly<Record<string, unknown>>): MessageDescriptor;
+};

package/dist/i18n/en.json.d.ts

@@ -0,0 +1,49 @@
+declare const _default: {
+  "format.fileSize.b": "{value} B",
+  "format.fileSize.kb": "{value} KB",
+  "format.fileSize.mb": "{value} MB",
+  "format.fileSize.gb": "{value} GB",
+  "format.fileSize.tb": "{value} TB",
+
+  "validation.required": "This field is required",
+  "validation.pattern": "Invalid format",
+  "validation.email": "Enter a valid email address",
+  "validation.url": "Enter a valid URL",
+  "validation.url_protocol": "The URL must use one of these protocols: {allowedProtocols}",
+  "validation.phone": "Enter a valid phone number",
+
+  "validation.min": "Must be at least {min}",
+  "validation.max": "Must be at most {max}",
+  "validation.minLength": "Enter at least {minLength, plural, one{# character} other{# characters}}",
+  "validation.maxLength": "Enter no more than {maxLength, plural, one{# character} other{# characters}}",
+  "validation.minItems": "At least {minLength, plural, one{# item} other{# items}}",
+  "validation.maxItems": "No more than {maxLength, plural, one{# item} other{# items}}",
+  "validation.isNumber": "Enter a number",
+  "validation.integer": "Enter a whole number",
+  "validation.multipleOf": "Must be a multiple of {multipleOf}",
+  "validation.nonNegative": "Must not be negative",
+  "validation.nonZero": "Must not be zero",
+
+  "validation.date_invalid": "Enter a valid date",
+  "validation.date_min": "The date must not be earlier than {minDate}",
+  "validation.date_max": "The date must not be later than {maxDate}",
+  "validation.date_past": "The date must not be in the past",
+  "validation.date_future": "The date must not be in the future",
+  "validation.date_min_age": "Age must be at least {minAge}",
+  "validation.date_max_age": "Age must be at most {maxAge}",
+
+  "validation.fileType": "File {fileName} has a type that is not allowed. Allowed: {accept}",
+  "validation.maxFileSize": "File {fileName} is larger than {maxFileSize}",
+  "validation.minFileSize": "File {fileName} is smaller than {minFileSize}",
+  "validation.maxFiles": "No more than {maxFiles, plural, one{# file} other{# files}}",
+  "validation.minFiles": "At least {minFiles, plural, one{# file} other{# files}}",
+  "validation.maxTotalFileSize": "The total size of the files exceeds {maxTotalFileSize}",
+  "validation.fileExists": "File {fileName} has already been added",
+  "validation.uploadAborted": "Upload cancelled",
+  "validation.uploadFailed": "Failed to upload {fileName}",
+
+  "validation.ruleFailed": "Could not check this field. Try again"
+}
+;
+
+export default _default;

package/dist/i18n/loader.d.ts

@@ -0,0 +1,71 @@
+import { FormLocale, Messages } from './locale';
+/** Что может вернуть источник: локаль целиком, её часть, голый словарь или ничего. */
+export type LocaleSourceResult = Partial<FormLocale> | Messages | null | undefined;
+/**
+ * Источник локали. Получает код языка, отдаёт локаль или словарь — сразу или промисом.
+ * `null`/`undefined` означает «для этого языка у меня ничего нет» и ошибкой не считается.
+ */
+export type LocaleSource = (code: string) => LocaleSourceResult | Promise<LocaleSourceResult>;
+/** Загрузчик локалей с кэшем. */
+export interface LocaleLoader {
+    /** Загрузить локаль языка. Повторный вызов возвращает тот же промис и ту же локаль. */
+    (code: string): Promise<FormLocale>;
+    /** Уже загруженная локаль или `undefined`. Позволяет провайдеру отрисоваться синхронно. */
+    peek(code: string): FormLocale | undefined;
+    /** То же, что вызов загрузчика; имя для чтения в коде старта приложения. */
+    preload(code: string): Promise<FormLocale>;
+}
+/**
+ * Собирает загрузчик из источников. Источники опрашиваются параллельно, а сливаются по порядку:
+ * поздний перекрывает ранний. Результат кэшируется по коду языка, идущий запрос не дублируется.
+ * Отказ любого источника — отказ загрузки; из кэша такой запрос удаляется, и следующая попытка
+ * пойдёт заново. Источник, которому можно промахнуться, приложение оборачивает само:
+ * `(code) => source(code).catch(() => null)`.
+ *
+ * Код языка у результата — всегда запрошенный: по нему работает `Intl`, и он не должен зависеть
+ * от того, что написано внутри файла.
+ *
+ * @param sources - Источники в порядке возрастания приоритета.
+ *
+ * @example
+ * ```ts
+ * import { createLocaleLoader, fetchMessages } from '@reformer/core/i18n';
+ * import { loadKitLocale } from '@reformer/ui-kit/locale';
+ *
+ * export const loadLocale = createLocaleLoader([
+ *   loadKitLocale,                                    // подписи кита — чанк нужного языка
+ *   fetchMessages((code) => `/locales/${code}.json`), // ключи приложения и правки — с сервера
+ * ]);
+ * ```
+ */
+export declare function createLocaleLoader(sources: readonly LocaleSource[]): LocaleLoader;
+/**
+ * Источник локали по сети: забирает JSON по адресу, построенному из кода языка. Файл может быть
+ * словарём (`{ "profile.title": "Профиль" }`) или локалью целиком (`{ "code": "ru", "messages": … }`).
+ * Ответ не `2xx` — ошибка загрузки.
+ *
+ * @param url - Адрес файла для языка.
+ * @param init - Параметры запроса, передаются в `fetch` как есть.
+ *
+ * @example
+ * ```ts
+ * fetchMessages((code) => `/locales/${code}.json`);
+ * ```
+ */
+export declare function fetchMessages(url: (code: string) => string, init?: RequestInit): LocaleSource;
+/**
+ * Источник встроенных локалей пакета: по чанку на язык. Язык ищется точно, затем по основной части
+ * кода (`ru-RU` → `ru`). Языка нет — источник отдаёт `null`: подписи пакета останутся английскими,
+ * пока приложение не даст их своим источником.
+ *
+ * @param loaders - Код языка → ленивый импорт его локали.
+ *
+ * @example
+ * ```ts
+ * export const loadKitLocale = bundledLocaleSource({
+ *   en: () => import('./en').then((m) => m.en),
+ *   ru: () => import('./ru').then((m) => m.ru),
+ * });
+ * ```
+ */
+export declare function bundledLocaleSource(loaders: Readonly<Record<string, () => Promise<FormLocale>>>): LocaleSource;

package/dist/i18n/locale-store.d.ts

@@ -0,0 +1,46 @@
+import { FormLocale } from './locale';
+/** Функция загрузки локали. `peek` — необязательный синхронный кэш (есть у `createLocaleLoader`). */
+export interface LocaleLoad {
+    (code: string): Promise<FormLocale>;
+    peek?(code: string): FormLocale | undefined;
+}
+/** Состояние хранилища. Объект неизменяемый: новая ссылка — новое состояние. */
+export interface LocaleStoreState {
+    /** Запрошенный язык. Пока `pending`, может отличаться от языка `locale`. */
+    readonly lang: string;
+    /** Локаль, которая сейчас на экране; `null` — ни одна ещё не загружена. */
+    readonly locale: FormLocale | null;
+    /** Идёт загрузка запрошенного языка. */
+    readonly pending: boolean;
+    /** Ошибка последней загрузки; сбрасывается следующей удачной. */
+    readonly error: unknown;
+}
+/** Хранилище активной локали. */
+export interface LocaleStore {
+    getState(): LocaleStoreState;
+    subscribe(listener: () => void): () => void;
+    /** Запросить язык. Повторный запрос того же языка, пока он грузится или уже показан, — no-op. */
+    setLang(lang: string): void;
+    /** Повторить запрос языка, загрузка которого упала. Без ошибки — no-op. */
+    retry(): void;
+}
+/** Настройки хранилища. */
+export interface LocaleStoreOptions {
+    /** Вызывается при отказе загрузки языка, который всё ещё запрошен. */
+    readonly onError?: (error: unknown, lang: string) => void;
+    /**
+     * Локаль, которая уже на экране (прежнее хранилище провайдера с другим загрузчиком). Пока новый
+     * загрузчик не отдал язык, на экране остаётся она, а не «ничего не загружено».
+     */
+    readonly previous?: FormLocale;
+}
+/**
+ * Создаёт хранилище. Загрузка при создании НЕ начинается: начальное состояние считается чисто —
+ * из кэша загрузчика, если локаль там уже есть, — а запрос уходит на первый {@link LocaleStore.setLang}.
+ * Это позволяет создавать хранилище прямо в рендере.
+ *
+ * @param load - Загрузчик локалей.
+ * @param lang - Начальный язык.
+ * @param options - См. {@link LocaleStoreOptions}.
+ */
+export declare function createLocaleStore(load: LocaleLoad, lang: string, options?: LocaleStoreOptions): LocaleStore;

package/dist/i18n/locale.d.ts

@@ -0,0 +1,90 @@
+import { MessagePattern } from './message-format';
+/** Плоский словарь: ключ → сообщение в формате ICU (см. `message-format.ts`). */
+export type Messages = Readonly<Record<string, string>>;
+/** День недели, с которого начинается календарь: `0` — воскресенье, `1` — понедельник. */
+export type WeekStart = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+/**
+ * Локаль формы.
+ *
+ * @example
+ * ```ts
+ * const ru: FormLocale = {
+ *   code: 'ru',
+ *   weekStartsOn: 1,
+ *   messages: { 'kit.select.selected': 'Выбрано: {count}' },
+ * };
+ * ```
+ */
+export interface FormLocale {
+    /** Код языка BCP 47 (`en`, `ru`, `pt-BR`): по нему работают `Intl` и множественные формы. */
+    readonly code: string;
+    /** Словарь сообщений. Ключа нет — пакет подставит встроенный английский. */
+    readonly messages: Messages;
+    /** Первый день недели календаря. По умолчанию — воскресенье. */
+    readonly weekStartsOn?: WeekStart;
+    /**
+     * Необязательное переопределение: объект локали `react-day-picker` / `date-fns`. Для ядра
+     * непрозрачен. Без него даты форматируются через `Intl` по {@link FormLocale.code}.
+     */
+    readonly dateLocale?: unknown;
+    /** Необязательное переопределение: формат даты в токенах `date-fns` для DatePicker. */
+    readonly dateFormat?: string;
+}
+/**
+ * Локаль «провайдера нет»: английский, пустой словарь. Каждый пакет при промахе по словарю берёт
+ * свою встроенную английскую таблицу, поэтому пустой словарь означает «всё по-английски».
+ */
+export declare const DEFAULT_LOCALE: FormLocale;
+/**
+ * Новая локаль на основе существующей: словари сливаются (ключи из `patch` важнее), остальные
+ * поля заменяются. Исходный объект не меняется.
+ *
+ * @param base - Локаль-основа, например поставляемая китом.
+ * @param patch - Свои ключи, переопределения китовых подписей и поля локали.
+ *
+ * @example
+ * ```ts
+ * import { ru } from '@reformer/ui-kit/locale/ru';
+ *
+ * const appRu = extendLocale(ru, {
+ *   messages: { 'profile.title': 'Профиль', 'kit.formWizard.submit': 'Отправить' },
+ * });
+ * ```
+ */
+export declare function extendLocale(base: FormLocale, patch: Partial<FormLocale>): FormLocale;
+/** `Object.hasOwn` без требования ES2022 к рантайму потребителя. */
+export declare function hasOwn(target: object, key: string): boolean;
+/** Что не так со словарём. */
+export interface LocaleIssue {
+    readonly key: string;
+    /**
+     * - `syntax` — сообщение не разбирается;
+     * - `missing` — ключ есть в образце, но его нет в словаре;
+     * - `extra` — ключа нет в образце;
+     * - `arguments` — набор подстановок не совпадает с образцом.
+     */
+    readonly kind: 'syntax' | 'missing' | 'extra' | 'arguments';
+    readonly message: string;
+}
+/**
+ * Имена аргументов сообщения, включая те, что встречаются только внутри веток `plural`/`select`.
+ *
+ * @param pattern - Результат `parseMessage`.
+ */
+export declare function messageArguments(pattern: MessagePattern, out?: Set<string>): Set<string>;
+/**
+ * Проверяет словарь: каждое сообщение разбирается, а при заданном образце — набор ключей и имена
+ * подстановок совпадают с ним. Нужна там, где компилятор не поможет: словарь пришёл по сети или
+ * написан вне репозитория. В рантайме вызывать не обязательно — битое или пропущенное сообщение
+ * и так откатится на встроенный английский; проверка нужна тестам и CI.
+ *
+ * @param messages - Проверяемый словарь.
+ * @param reference - Образец, обычно английский словарь того же пакета.
+ * @returns Список расхождений; пустой — словарь в порядке.
+ *
+ * @example
+ * ```ts
+ * expect(validateLocale(ruJson, enJson)).toEqual([]);
+ * ```
+ */
+export declare function validateLocale(messages: Messages, reference?: Messages): LocaleIssue[];

package/dist/i18n/message-format.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Формат сообщений интерфейса — подмножество ICU MessageFormat без зависимостей.
+ *
+ * Один на подписи форм (`@reformer/core/i18n`) и на интерфейс билдера. Поддерживает ровно то, что
+ * им нужно, и ничего сверх:
+ * - **подстановка** — `Открыт файл {name}`;
+ * - **множественные формы** — `{count, plural, one{# файл} few{# файла} many{# файлов} other{# файла}}`,
+ *   категории берутся из {@link Intl.PluralRules} активной локали, `#` подставляет само число через
+ *   {@link Intl.NumberFormat};
+ * - **выбор по значению** — `{gender, select, male{он} female{она} other{оно}}`;
+ * - **экранирование** — апострофом, как в ICU: `'{'` → `{`, `'}'` → `}`, `''` → `'`; как в
+ *   `intl-messageformat`, литерал открывает и апостроф перед `<` и `>`.
+ *
+ * Три свойства, ради которых формат устроен именно так:
+ *
+ * 1. **Сообщение разбирается в дерево, а не форматируется заменами по строке.** Значение аргумента
+ *    попадает в результат как текст и повторно не разбирается: `{name}` со значением
+ *    `{count, plural, ...}` выведет эти символы, а не выполнит их. Замена регулярным выражением
+ *    такой гарантии не даёт.
+ * 2. **Синтаксис — честное подмножество ICU.** Любое сообщение, которое понимает этот модуль,
+ *    `intl-messageformat` (в режиме `ignoreTag`, со строковыми значениями и конечными числами;
+ *    значение `plural` — число) понимает так же и выводит посимвольно то же самое; это проверено
+ *    дифференциальным и property-тестами (`tests/i18n/message-format.differential.test.ts`,
+ *    `message-format.property.test.ts`). Чего не понимает эталон — повтор ключа ветки, `=N` с не
+ *    целым числом или в `select`, символы синтаксиса ICU в имени, — не понимает и этот модуль.
+ *    Отсюда страховка из контракта:
+ *    если подмножества перестанет хватать, библиотека подставляется под тот же вызов, и словари
+ *    переписывать не придётся.
+ * 3. **Ошибка синтаксиса и отсутствие ветки `other` — отказ на разборе**, а не молчаливая
+ *    неправильная строка в интерфейсе. Разбор словаря на старте и в CI ловит их до пользователя.
+ *
+ * Отличий от `intl-messageformat` в выводе нет; отличий два, и оба — сужение, а не расхождение:
+ * - **Грамматика уже.** Типы аргументов `number`, `date`, `time`, `selectordinal` не поддержаны и
+ *   отвергаются на разборе. Сообщение с ними не пройдёт в словарь, а не отформатируется молча
+ *   неправильно. Заметь: голое `{n}` форматируется как `String(n)` и здесь, и в `intl-messageformat`
+ *   (`{year}` → `2026`, а не `2 026`); по локали форматируется только `#` внутри `plural`.
+ *   Вложенность аргументов — не глубже 100 уровней: глубже рекурсивный разбор исчерпал бы стек
+ *   (`RangeError`) вместо внятного отказа.
+ * - **Пропущенный аргумент не бросает исключение**, а подставляет заметный маркер `⟦name⟧`: строка
+ *   интерфейса не должна ронять панель. Поведение настраивается через `onMissingArgument`.
+ *
+ * @module i18n/message-format
+ */
+/** Узел разобранного сообщения. */
+export type MessageNode = {
+    readonly kind: 'text';
+    readonly value: string;
+} | {
+    readonly kind: 'arg';
+    readonly name: string;
+} | {
+    readonly kind: 'number';
+    readonly name: string;
+} | {
+    readonly kind: 'plural';
+    readonly name: string;
+    readonly branches: MessageBranches;
+} | {
+    readonly kind: 'select';
+    readonly name: string;
+    readonly branches: MessageBranches;
+};
+/** Разобранное сообщение — плоская последовательность узлов. */
+export type MessagePattern = readonly MessageNode[];
+/** Ветки `plural`/`select`: категория CLDR (`one`, `few`, …), точное совпадение (`=0`) или значение `select`. */
+export type MessageBranches = ReadonlyMap<string, MessagePattern>;
+/** Значения аргументов сообщения. */
+export type MessageValues = Readonly<Record<string, unknown>>;
+/** Настройки форматирования. */
+export interface MessageFormatOptions {
+    /**
+     * Что подставить вместо аргумента, которого нет в значениях (или чьё значение не число там, где
+     * ожидалось число). По умолчанию — заметный маркер `⟦name⟧`, тот же приём, что и для пропущенного
+     * ключа: пропуск должен попадаться разработчику, а не пользователю.
+     */
+    readonly onMissingArgument?: (name: string) => string;
+}
+/** Отказ разбора сообщения: синтаксис или отсутствие обязательной ветки `other`. */
+export declare class MessageSyntaxError extends Error {
+    readonly name = "MessageSyntaxError";
+}
+/**
+ * Код языка, пригодный для `Intl`. Некорректный (не BCP 47) заменяется на `en` — с предупреждением
+ * в dev, один раз на код. Код может прийти извне (язык из адресной строки), и `RangeError` из
+ * `Intl` ронял бы рендер на первом же `plural`, числе или дате.
+ *
+ * @param code - Код языка локали.
+ * @returns Тот же код либо `en`.
+ */
+export declare function intlLocale(code: string): string;
+/**
+ * Значение как текст. Значение, которое нельзя привести к строке (`Object.create(null)`, объект
+ * с бросающим `toString`), — пустая строка: одно такое значение не роняет всё сообщение.
+ */
+export declare function toText(value: unknown): string;
+/**
+ * Разбирает сообщение в дерево. Бросает {@link MessageSyntaxError} на ошибке синтаксиса и на
+ * `plural`/`select` без ветки `other`.
+ *
+ * @param source - Текст сообщения из словаря.
+ * @returns Разобранное сообщение для {@link formatPattern}.
+ *
+ * @example
+ * ```ts
+ * parseMessage('{count, plural, one{# файл} few{# файла} many{# файлов} other{# файла}}');
+ * ```
+ */
+export declare function parseMessage(source: string): MessagePattern;
+/**
+ * Собирает строку из разобранного сообщения. Значения подставляются как текст и повторно
+ * не разбираются.
+ *
+ * @param pattern - Результат {@link parseMessage}.
+ * @param values - Значения аргументов.
+ * @param locale - Локаль для {@link Intl.PluralRules} и {@link Intl.NumberFormat} (`ru`, `en`, …).
+ * @param options - Настройки; см. {@link MessageFormatOptions}.
+ * @returns Готовая строка интерфейса.
+ */
+export declare function formatPattern(pattern: MessagePattern, values: MessageValues, locale: string, options?: MessageFormatOptions): string;
+/**
+ * Форматтер одной локали с кэшем разбора: сообщение разбирается один раз, на первый вызов.
+ * Это внутренность `I18nService.t()` — сам `t()` добавляет сверху поиск ключа в словаре, маркер
+ * пропущенного ключа и откат на резервную локаль.
+ *
+ * @param locale - Локаль форматтера.
+ * @param options - Настройки; см. {@link MessageFormatOptions}.
+ * @returns Функция `(сообщение, значения) => строка`.
+ *
+ * @example
+ * ```ts
+ * const format = createMessageFormatter('ru');
+ * format('{count, plural, one{# файл} few{# файла} many{# файлов} other{# файла}}', { count: 5 });
+ * // '5 файлов'
+ * ```
+ */
+export declare function createMessageFormatter(locale: string, options?: MessageFormatOptions): (source: string, values?: MessageValues) => string;

package/dist/i18n/resolve-localized.d.ts

@@ -0,0 +1,17 @@
+import { I18nHandle } from './translator';
+/**
+ * Заменяет описатели сообщений на строки по активной локали. Обходит массивы и простые
+ * объекты-литералы — подписи опций, заголовки шагов; сигналы, React-элементы, функции и
+ * экземпляры классов (узлы формы) возвращает как есть. Поддерево без описателей сохраняет ссылку:
+ * если раскрывать было нечего, возвращается тот же объект.
+ *
+ * @param value - Пропсы, массив или одиночное значение.
+ * @param i18n - Ручка активной локали (`createI18n` / `useI18n`).
+ *
+ * @example
+ * ```ts
+ * resolveLocalized({ label: msg('profile.email.label'), options: [{ value: 'a', label: msg('opt.a') }] }, i18n);
+ * // { label: 'Почта', options: [{ value: 'a', label: 'Вариант А' }] }
+ * ```
+ */
+export declare function resolveLocalized<T>(value: T, i18n: I18nHandle): T;