@reformer/renderer-json 8.0.0 → 9.0.0-beta.2

package/dist/locale/i18n.d.ts

@@ -0,0 +1,21 @@
+import { ReactNode } from 'react';
+import { LocaleParams } from './locale-service';
+/** Props {@link I18n}. */
+export interface I18nProps {
+    /** Ключ сообщения в сервисе локализации. */
+    id: string;
+    /**
+     * Параметры интерполяции/склонения. Значения могут быть сигналами (`$model(...)`) — тогда текст
+     * обновляется при их изменении — или литералами.
+     */
+    values?: LocaleParams;
+}
+/**
+ * Реактивный локализованный текст. Читает {@link LocaleService} из {@link LocaleProvider} (live-смена
+ * языка) и разворачивает `values`-сигналы (live-обновление параметров). Если сервис умеет `render` —
+ * рендерит rich-контент (markdown/JSX), иначе строку через `resolve`.
+ *
+ * @param props - {@link I18nProps} (`id` + опциональные `values`).
+ * @returns Локализованный `ReactNode`.
+ */
+export declare function I18n({ id, values }: I18nProps): ReactNode;

package/dist/locale/locale-context.d.ts

@@ -0,0 +1,36 @@
+import { ReactNode } from 'react';
+import { LocaleService } from './locale-service';
+/** Props {@link LocaleProvider}. */
+export interface LocaleProviderProps {
+    /** Текущий сервис локализации. Смена ссылки (напр. при переключении языка) перерендеривает все `I18n`. */
+    service: LocaleService;
+    /** Поддерево, в котором `I18n`/`useLocale` видят этот сервис. */
+    children: ReactNode;
+}
+/**
+ * Провайдер сервиса локализации для реактивного пути. Оберни форму (или её часть) и передавай
+ * новый `service` при смене языка — вложенные `I18n` перерисуются без пересборки схемы.
+ *
+ * @example Переключение языка
+ * ```tsx
+ * import { LocaleProvider, createLocaleService, JsonFormRenderer } from '@reformer/renderer-json';
+ *
+ * const services = { ru: createLocaleService(ruTable), en: createLocaleService(enTable) };
+ * function App() {
+ *   const [lang, setLang] = useState<'ru' | 'en'>('ru');
+ *   return (
+ *     <LocaleProvider service={services[lang]}>
+ *       <JsonFormRenderer schema={schema} />
+ *     </LocaleProvider>
+ *   );
+ * }
+ * ```
+ */
+export declare function LocaleProvider({ service, children }: LocaleProviderProps): ReactNode;
+/**
+ * Текущий сервис локализации из {@link LocaleProvider}. Без провайдера — fallback-to-key.
+ * Используется внутри {@link I18n}; вызывай напрямую для собственного localized-компонента.
+ *
+ * @returns Активный {@link LocaleService}.
+ */
+export declare function useLocale(): LocaleService;

package/dist/locale/locale-service.d.ts

@@ -0,0 +1,76 @@
+import { ReactNode } from 'react';
+/** Параметры для интерполяции/склонения (ICU-values, i18next-values и т.п.). */
+export type LocaleParams = Record<string, unknown>;
+/** Резолвер ключа (+опциональные параметры) в строку. */
+export type LocaleResolver = (key: string, params?: LocaleParams) => string;
+/**
+ * Сервис локализации в реестре / контексте. `resolve` обязателен (строковый путь); `render`
+ * опционален (rich/markdown-путь через `Trans`/`RichText`); `keys` (если задан — напр., из каталога)
+ * включает проверку опечаток ключей на этапе `validateFormSchema`.
+ */
+export interface LocaleService {
+    /** Ключ (+params) → локализованная строка (при промахе — сам ключ). Для label/placeholder и fallback `Trans`. */
+    resolve: LocaleResolver;
+    /**
+     * Ключ (+params) → rich-контент (markdown/JSX). Опционален. Используется `Trans`/`RichText`, когда
+     * нужен не голый текст, а разметка. Реализуется потребителем (напр. через `react-markdown`).
+     */
+    render?(key: string, params?: LocaleParams): ReactNode;
+    /** Множество известных ключей. Есть → `validate` ловит `unknown locale key`; нет → проверка мягко пропускается (как для `$model`). */
+    keys?: readonly string[];
+}
+/** Дефолтный резолвер: отдаёт сам ключ (fallback-to-key). Применяется, когда сервис не зарегистрирован. */
+export declare const defaultLocaleResolver: LocaleResolver;
+/**
+ * Строит {@link LocaleService} из каталога `ключ → строка`. Промах ключа → сам ключ (fallback-to-key,
+ * зеркало `createMessageResolver` из `@reformer/cdk`). `keys` каталога включает validate-time проверку
+ * опечаток. Смена языка — пересобрать сервис на другом каталоге и передать новый ref в `reg.locale`.
+ *
+ * @param catalog - Таблица `ключ → локализованная строка`.
+ * @returns {@link LocaleService} для `reg.locale(...)`.
+ *
+ * @example
+ * ```ts
+ * import { defineRegistry } from '@reformer/renderer-json';
+ * import { createLocaleResolver } from '@reformer/renderer-json';
+ *
+ * const registry = defineRegistry((reg) => {
+ *   reg.locale(createLocaleResolver({
+ *     'fields.email.label': 'Email',
+ *     'fields.email.placeholder': 'you@example.com',
+ *   }));
+ * });
+ * // В схеме: componentProps: { label: '$locale(fields.email.label)' }
+ * // '$locale(fields.unknown)' при наличии каталога → ошибка на validateFormSchema.
+ * ```
+ */
+export declare function createLocaleResolver(catalog: Record<string, string>): LocaleService;
+/**
+ * Строит {@link LocaleService} из таблицы `ключ → (params) => строка` — 0-dependency вариант для
+ * параметров и склонения без ICU (стиль `createMessageResolver` из `@reformer/cdk`). Промах ключа →
+ * сам ключ. `keys` таблицы включает validate-time проверку опечаток.
+ *
+ * Для ICU-склонения по CLDR-правилам подключи `intl-messageformat` в СВОЁМ сервисе:
+ * `reg.locale({ resolve: (k, p) => new IntlMessageFormat(catalog[k], lng).format(p) as string, keys })`.
+ * Для markdown добавь `render` (напр. через `react-markdown`).
+ *
+ * @param table - Таблица `ключ → (params) => локализованная строка`.
+ * @returns {@link LocaleService} для `reg.locale(...)` / `LocaleProvider`.
+ *
+ * @example
+ * ```ts
+ * import { createLocaleService } from '@reformer/renderer-json';
+ *
+ * const ru = createLocaleService({
+ *   'fields.min': (p) => `Минимум ${p?.count} символов`,
+ *   'users.count': (p) => {
+ *     const n = Number(p?.count);
+ *     const forms = ['пользователь', 'пользователя', 'пользователей'];
+ *     const idx = n % 10 === 1 && n % 100 !== 11 ? 0 : n % 10 >= 2 && n % 10 <= 4 && (n % 100 < 10 || n % 100 >= 20) ? 1 : 2;
+ *     return `${n} ${forms[idx]}`;
+ *   },
+ * });
+ * ru.resolve('fields.min', { count: 3 }); // 'Минимум 3 символов'
+ * ```
+ */
+export declare function createLocaleService(table: Record<string, (params?: LocaleParams) => string>): LocaleService;

package/dist/locale/locale-service.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/locale/use-signal-value.d.ts

@@ -0,0 +1,15 @@
+import { LocaleParams } from './locale-service';
+/**
+ * Разворачивает значения-сигналы в обычные (читает `.value`), литералы отдаёт как есть. Если сигналов
+ * не было — возвращает исходный объект (стабильная ссылка). Pure — тестируется без DOM.
+ */
+export declare function unwrapSignalValues(values?: LocaleParams): LocaleParams | undefined;
+/**
+ * Реактивно разворачивает `values`-сигналы. Перерендер компонента при изменении любого сигнала;
+ * литералы проходят как есть. Снапшот кэшируется (стабильная ссылка при неизменных значениях) —
+ * иначе `useSyncExternalStore` зациклится.
+ *
+ * @param values - Параметры сообщения (сигналы и/или литералы).
+ * @returns Развёрнутые значения для передачи в `LocaleService.resolve/render`.
+ */
+export declare function useSignalValues(values?: LocaleParams): LocaleParams | undefined;

package/dist/locale/use-signal-value.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/operators.d.ts

@@ -6,6 +6,8 @@
  * - `"$model(path)"`        — путь к полю/массиву модели: лист → `model.signalAt(path)`, массив → `model.<path>`.
  * - `"$component(Name)"`    — имя компонента в реестре (`reg.component`).
  * - `"$dataSource(NAME)"`   — имя registry-source (`reg.dataSource`): options/itemLabel/константы/loading-компоненты.
+ * - `"$fn(name)"`           — имя функции в реестре (`reg.fn`): форматтеры/компараторы/itemLabel/обработчики.
+ * - `"$locale(key)"`        — ключ строки для сервиса локализации (`reg.locale`): резолвится в строку.
  *
  * Схема остаётся чистым JSON (копируется в `.json`, приходит строкой с сервера). Типобезопасность
  * на этапе компиляции даётся template-literal типами ({@link ModelOp} и т.д.) — литерал
@@ -19,11 +21,15 @@ export type ModelOp = `$model(${string})`;
 export type ComponentOp = `$component(${string})`;
 /** Строка-оператор ссылки на registry-source: `` `$dataSource(${name})` ``. */
 export type DataSourceOp = `$dataSource(${string})`;
+/** Строка-оператор ссылки на функцию реестра: `` `$fn(${name})` ``. */
+export type FnOp = `$fn(${string})`;
+/** Строка-оператор ссылки на ключ локализации: `` `$locale(${key})` ``. */
+export type LocaleOp = `$locale(${string})`;
 /** Любой строковый оператор JSON-схемы. */
-export type JsonOperator = ModelOp | ComponentOp | DataSourceOp;
-/** Разобранный оператор: тип + аргумент (путь/имя). */
+export type JsonOperator = ModelOp | ComponentOp | DataSourceOp | FnOp | LocaleOp;
+/** Разобранный оператор: тип + аргумент (путь/имя/ключ). */
 export interface ParsedOperator {
-    op: 'model' | 'component' | 'dataSource';
+    op: 'model' | 'component' | 'dataSource' | 'fn' | 'locale';
     arg: string;
 }
 /**
@@ -83,3 +89,31 @@ export declare const isComponentOp: (v: unknown) => v is ComponentOp;
  * ```
  */
 export declare const isDataSourceOp: (v: unknown) => v is DataSourceOp;
+/**
+ * Type-guard: строка — оператор `"$fn(...)"` (ссылка на функцию реестра).
+ *
+ * @param v - Проверяемое значение.
+ * @returns `true`, если `v` — {@link FnOp}.
+ *
+ * @example
+ * ```ts
+ * if (isFnOp(props.itemLabel)) {
+ *   const name = parseOperator(props.itemLabel)!.arg; // 'propertyItemLabel'
+ * }
+ * ```
+ */
+export declare const isFnOp: (v: unknown) => v is FnOp;
+/**
+ * Type-guard: строка — оператор `"$locale(...)"` (ключ строки для сервиса локализации).
+ *
+ * @param v - Проверяемое значение.
+ * @returns `true`, если `v` — {@link LocaleOp}.
+ *
+ * @example
+ * ```ts
+ * if (isLocaleOp(props.label)) {
+ *   const key = parseOperator(props.label)!.arg; // 'fields.email.label'
+ * }
+ * ```
+ */
+export declare const isLocaleOp: (v: unknown) => v is LocaleOp;

package/dist/operators.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/registry/component-registry.d.ts

@@ -1,9 +1,11 @@
 import { ComponentRegistry, ComponentMetadata, RegistryBuilder } from './types';
+import { LocaleService } from '../locale/locale-service';
 export declare class ComponentRegistryImpl implements ComponentRegistry {
     private own;
     private parent;
     get(name: string): ComponentMetadata | undefined;
     getDataSource<T = unknown>(name: string): T | undefined;
+    getLocale(): LocaleService | undefined;
     has(name: string): boolean;
     names(): string[];
     _set(name: string, metadata: ComponentMetadata): void;

package/dist/registry/component-registry.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/registry/constants.d.ts

@@ -15,3 +15,20 @@
  * ```
  */
 export declare const FIELD_WRAPPER = "$fieldWrapper";
+/**
+ * Зарезервированный ключ реестра для единственного сервиса локализации.
+ *
+ * `reg.locale(...)` кладёт сервис под этот ключ; оператор `"$locale(key)"` резолвится через него
+ * (`registry.getLocale()`). Ключ намеренно отличается от имени оператора, чтобы `$dataSource`/`$fn`
+ * не могли достать сервис локализации по имени.
+ *
+ * @example
+ * ```typescript
+ * import { defineRegistry, createLocaleResolver } from '@reformer/renderer-json';
+ *
+ * const registry = defineRegistry((reg) => {
+ *   reg.locale(createLocaleResolver({ 'fields.email.label': 'Email' }));
+ * });
+ * ```
+ */
+export declare const LOCALE_SERVICE = "$localeService";

package/dist/registry/types.d.ts

@@ -1,8 +1,9 @@
 import { ComponentType } from 'react';
+import { LocaleResolver, LocaleService } from '../locale/locale-service';
 /**
- * Запись реестра. Хранит сам компонент (или dataSource-значение) и его роль.
+ * Запись реестра. Хранит значение (компонент / dataSource / функцию / сервис локализации) и его роль.
  *
- * @typeParam P - Пропсы компонента (для `field`/`container`).
+ * @typeParam P - Пропсы компонента (для `component`).
  *
  * @example
  * ```typescript
@@ -12,7 +13,7 @@ import { ComponentType } from 'react';
  */
 export interface ComponentMetadata<P = any> {
     component: ComponentType<P> | unknown;
-    type: 'component' | 'dataSource';
+    type: 'component' | 'dataSource' | 'fn' | 'locale';
     description?: string;
 }
 /**
@@ -32,6 +33,12 @@ export interface ComponentMetadata<P = any> {
 export interface ComponentRegistry {
     get(name: string): ComponentMetadata | undefined;
     getDataSource<T = unknown>(name: string): T | undefined;
+    /**
+     * Единственный сервис локализации (для оператора `$locale(key)`), если зарегистрирован через
+     * `reg.locale(...)`. Опционален — сторонние реализации `ComponentRegistry` без него продолжают
+     * компилироваться; при его отсутствии `$locale` мягко деградирует до самого ключа.
+     */
+    getLocale?(): LocaleService | undefined;
     has(name: string): boolean;
     names(): string[];
 }
@@ -44,6 +51,8 @@ export interface ComponentRegistry {
  *   reg.component('Input', Input);
  *   reg.component('Box', Box);
  *   reg.dataSource('LOAN_TYPES', LOAN_TYPES);
+ *   reg.fn('formatCurrency', formatCurrency);
+ *   reg.locale(createLocaleResolver({ 'fields.email.label': 'Email' }));
  * });
  * ```
  */
@@ -57,4 +66,16 @@ export interface RegistryBuilder {
      */
     component<P>(name: string, component: ComponentType<P>, description?: string): void;
     dataSource<T>(name: string, value: T, description?: string): void;
+    /**
+     * Зарегистрировать функцию под именем — доступна в схеме как `$fn(name)` (форматтеры,
+     * компараторы, `itemLabel`, обработчики). Отдельный от `dataSource` вид: бросает при регистрации,
+     * если передана не функция, и `validateFormSchema` отклоняет перепутанные `$fn`/`$dataSource`.
+     */
+    fn<F extends (...args: any[]) => any>(name: string, fn: F, description?: string): void;
+    /**
+     * Зарегистрировать единственный сервис локализации для оператора `$locale(key)`. Принимает
+     * {@link LocaleService} (каталог через `createLocaleResolver` — включает validate-time проверку
+     * ключей) либо голый резолвер `(key) => string`. Кладётся под зарезервированный ключ `LOCALE_SERVICE`.
+     */
+    locale(service: LocaleService | LocaleResolver, description?: string): void;
 }

package/dist/schema/form-schema.schema.json.d.ts

@@ -23,11 +23,14 @@ declare const _default: {
       "description": "Registry component: \"$component(Name)\". Name is tightened to a registry enum by buildFormSchemaMetaSchema."
     },
     "node": {
-      "oneOf": [
-        { "$ref": "#/definitions/fieldNode" },
-        { "$ref": "#/definitions/arrayNode" },
-        { "$ref": "#/definitions/containerNode" }
-      ]
+      "$comment": "Discriminated by which operator key is present (array→value→component), mirroring the isArrayNode/isFieldNode/isContainerNode runtime guards. Using oneOf here made ajv (allErrors) report failures against all three branches for any single mistake, burying the real cause; if/then/else surfaces only the relevant branch's errors.",
+      "if": { "type": "object", "required": ["array"] },
+      "then": { "$ref": "#/definitions/arrayNode" },
+      "else": {
+        "if": { "type": "object", "required": ["value"] },
+        "then": { "$ref": "#/definitions/fieldNode" },
+        "else": { "$ref": "#/definitions/containerNode" }
+      }
     },
     "fieldNode": {
       "type": "object",

package/dist/schema/index.d.ts

@@ -38,9 +38,31 @@ export declare function getComponentNames(registry: ComponentRegistry): string[]
  */
 export declare function getDataSourceNames(registry: ComponentRegistry): string[];
 /**
- * Конкретная мета-схема: базовая + (если заданы `componentNames`) сужение паттерна `$component(...)`
- * до enum имён (`^\$component\((Input|Select|…)\)$`). `$dataSource`-имена JSON Schema'й не покрыть
- * (вложены в произвольный componentProps) — их проверяет рекурсивный обход в `validateFormSchema`.
+ * Имена функций реестра (`reg.fn`) — то, что валидно в `$fn(...)`: форматтеры/компараторы/itemLabel/
+ * обработчики. Отдельно от {@link getDataSourceNames}, поэтому `validateFormSchema` ловит перепутанные
+ * `$fn`/`$dataSource`.
+ *
+ * @param registry - Реестр (см. {@link defineRegistry}).
+ * @returns Массив имён функций.
+ */
+export declare function getFnNames(registry: ComponentRegistry): string[];
+/**
+ * Известные ключи локализации сервиса реестра (`reg.locale` с каталогом) — то, что валидно в
+ * `$locale(...)`. `undefined`, если сервис не зарегистрирован или задан голым резолвером без `keys`
+ * (тогда `validateFormSchema` мягко пропускает проверку ключей, как для `$model`-путей).
+ *
+ * @param registry - Реестр (см. {@link defineRegistry}).
+ * @returns Массив ключей либо `undefined`.
+ */
+export declare function getLocaleKeys(registry: ComponentRegistry): readonly string[] | undefined;
+/**
+ * Конкретная мета-схема: базовая + (если заданы `componentNames`) сужение `$component(...)` до
+ * enum допустимых значений (`["$component(Input)", "$component(Select)", …]`). `$dataSource`-имена
+ * JSON Schema'й не покрыть (вложены в произвольный componentProps) — их проверяет рекурсивный обход
+ * в `validateFormSchema`.
+ *
+ * enum, а не regex-`pattern`: ajv перечисляет допустимые имена в тексте ошибки, IDE даёт
+ * автодополнение по значениям, а имена не нужно экранировать под regex (напр. `$fieldWrapper`).
  *
  * @example
  * ```ts

package/dist/validate.d.ts

@@ -5,11 +5,15 @@ export interface FormSchemaValidationResult {
     /** Человекочитаемые ошибки (путь + сообщение). Пусто, если валидно. */
     errors: string[];
 }
-/** Опции: реестр (имена извлекаются автоматически) либо явные списки имён. */
+/** Опции: реестр (имена извлекаются автоматически) либо явные списки имён/ключей. */
 export interface ValidateFormSchemaOptions {
     registry?: ComponentRegistry;
     componentNames?: string[];
     dataSourceNames?: string[];
+    /** Имена функций `reg.fn` для проверки `$fn(...)`. Не заданы → проверка `$fn`-имён пропускается. */
+    fnNames?: string[];
+    /** Ключи каталога локализации для проверки `$locale(...)`. Не заданы → проверка ключей пропускается. */
+    localeKeys?: readonly string[];
 }
 /**
  * Валидирует form-DSL JSON-схему. Если передан `registry`, имена компонентов/source берутся из него