@reformer/core 11.0.0-beta.5 → 11.0.0-beta.7

package/docs/llms/16-ui-components.md

@@ -2,12 +2,13 @@
 
 > **Default rule (read first)**: для UI используй `FormField` из
 > [`@reformer/ui-kit`](../../reformer-ui-kit/) — он покрывает 95% случаев одной
-> строкой `<FormField control={form.x} />`. Свои field-обёртки пиши ТОЛЬКО если
+> строкой `<FormField control={form.x} />`. Свои обёртки поля пиши ТОЛЬКО если
 > ui-kit не подходит (другая design system, особый low-level input).
 >
 > Канонический schema-driven подход:
 >
-> - **компонент** объявляется в схеме как `component: InputField` (или `Select`, `Checkbox`, etc.)
+> - **компонент** объявляется в схеме как `component: Input` (или `SelectAsync`, `CheckboxWithLabel`, …) —
+>   сам компонент кита, отдельных «field-версий» нет: связывает его с полем обёртка (`FormField`)
 > - **пропсы** компонента — в `componentProps: { label, placeholder, options, type, ... }`
 > - **JSX рендерит**: `<FormField control={form.x} />` БЕЗ дополнительных props
 >
@@ -19,7 +20,7 @@
 ```tsx
 import { useMemo } from 'react';
 import { createModel, createForm } from '@reformer/core';
-import { FormField, InputField, SelectField, CheckboxField, Button } from '@reformer/ui-kit';
+import { FormField, Input, SelectAsync, CheckboxWithLabel, Button } from '@reformer/ui-kit';
 
 type RegistrationForm = {
   email: string;
@@ -33,12 +34,12 @@ function RegistrationPage() {
     const schema = {
       email: {
         value: model.$.email,
-        component: InputField,
+        component: Input,
         componentProps: { label: 'Email', type: 'email', placeholder: 'you@example.com' },
       },
       country: {
         value: model.$.country,
-        component: SelectField,
+        component: SelectAsync,
         componentProps: {
           label: 'Country',
           options: [
@@ -49,7 +50,7 @@ function RegistrationPage() {
       },
       agree: {
         value: model.$.agree,
-        component: CheckboxField,
+        component: CheckboxWithLabel,
         componentProps: { label: 'I agree to terms' },
       },
     };
@@ -92,7 +93,7 @@ function RegistrationPage() {
 ✅ Всё это в схеме:
 
 ```ts
-{ email: { component: InputField, componentProps: { label: 'Email' } } }
+{ email: { component: Input, componentProps: { label: 'Email' } } }
 ```
 
 ```tsx
@@ -113,7 +114,8 @@ import { InputMask } from 'react-input-mask';
 ```
 
 `children` оборачивается в `CdkFormField.Control asChild` и получает все нужные
-props (`value`, `onChange`, `onBlur`, `aria-invalid`).
+props (`value`, `onChange`, `onBlur`, `aria-invalid`) — в диалекте ребёнка, если тот объявил
+статику `reformerAdapter` (`defineFieldControl` из `@reformer/ui-kit/fields`), иначе value-based.
 
 ### Advanced — write your own from scratch (rare)
 
@@ -155,12 +157,37 @@ function MyFormField<T>({ control }: MyFormFieldProps<T>) {
 <MyFormField control={form.email} /> // ← без label-prop
 ```
 
+### Связывание поля с контролом — `FieldAdapter` (`@reformer/core`)
+
+Контролы говорят на разных диалектах (`checked` + `onCheckedChange`, `onValueChange`, DOM-событие
+в `onChange`), форма — на value-based seam (`value` + `onChange(value)` + `onBlur`). Перевод
+описывает `FieldAdapter` (`valueProp`, `changeProp`, `fromEmit`, `toValue`, `bindBlur`, `strip`,
+`passControl` — все необязательны). Компонент объявляет его статикой `reformerAdapter`, а обёртка
+поля (`FormField.Control` из `@reformer/cdk`, рендерер `@reformer/renderer-react`) читает статику
+и связывает поле сама — отдельные «field-версии» компонентов не нужны.
+
+| Символ                        | Назначение                                                                  |
+| ----------------------------- | --------------------------------------------------------------------------- |
+| `FieldAdapter`                | Тип адаптера: диалект контрола                                              |
+| `getFieldAdapter(component)`  | Статика `component.reformerAdapter` либо `undefined`                        |
+| `bindFieldProps(adapter, seam, props)` | Props контрола под адаптер (без адаптера — seam как есть)          |
+| `FieldHandle`                 | Императивный handle поля: `focus` / `blur` / `scrollIntoView` / `getElement` |
+| `makeElementFieldHandle(ref)` | Базовый `FieldHandle` из DOM-узла                                           |
+| `useFieldHandleRef(outerRef)` | Ref для контрола + публикация handle потребителю (строит ОБЁРТКА поля)     |
+
+В приложении обычно достаточно `defineFieldControl(MyControl, { adapter })` из
+`@reformer/ui-kit/fields` (плюс готовые пресеты `checkedAdapter`, `valueChangeAdapter`, …); для
+компонентов чужой библиотеки без статики — `RendererSettings.resolveFieldAdapter`.
+
 ### Integration with UI libraries (shadcn etc.)
 
 > **Через рендерер — без обёртки.** Если ты рендеришь форму через `@reformer/renderer-react` /
 > `@reformer/renderer-json`, вместо ручной обёртки на каждый контрол можно зарегистрировать сырой
 > компонент и передать `settings.resolveFieldAdapter` — рендерер сам сведёт value-seam к диалекту
-> контрола. Ручная обёртка на `useFormControl` (ниже) нужна для прямого JSX без рендерера.
+> контрола. Свой компонент можно подготовить и один раз — статикой
+> `defineFieldControl(MyInput, { adapter })` из `@reformer/ui-kit/fields`: его поймут и рендерер,
+> и `FormField.Control` из `@reformer/cdk`. Ручная обёртка на `useFormControl` (ниже) нужна для
+> прямого JSX без `FormField` и рендерера.
 
 Если есть существующая design system — оборачивай её компоненты в один
 `MyFormField` (как выше) и используй один прop `control`. Не множь обёртки на

package/docs/llms/17-nonexistent-api.md

@@ -26,6 +26,20 @@
 | `FormProvider`, `control` prop, `register()` | `<Component form={form} />`, `useFormControl(form.field)` | Форма передаётся через props |
 | `getFieldValue()`                | `model.field` / `useFormControlValue(form.field)`| Не существует                                   |
 
+### UI: удалённые field-версии компонентов (`@reformer/ui-kit`)
+
+Отдельных «field-версий» у компонентов кита больше нет: в `component` поля кладётся сам
+компонент, диалект он объявляет статикой `reformerAdapter`, связывает поле обёртка
+(`FormField.Control` / рендерер).
+
+| Wrong                                          | Correct                                                   |
+| ---------------------------------------------- | --------------------------------------------------------- |
+| `InputField`, `SelectField`, `CheckboxField`, … (любой `*Field`) | `Input`, `SelectAsync`, `CheckboxWithLabel`, … — таблица в ui-kit `01-overview.md` |
+| `InputField` + `type: 'number'`                | `InputNumber`                                             |
+| `InputField` + `suggestions`                   | `InputSuggest`                                            |
+| `FileUploadField` + `variant: 'dropzone' \| 'input'` | `FileUploadDropzone` / `FileUploadInput` (без `variant`) |
+| `withFormControl(MyControl, adapter)`          | `defineFieldControl(MyControl, { adapter })` из `@reformer/ui-kit/fields` |
+
 ### Common Import Errors
 
 ```typescript
@@ -64,8 +78,8 @@ const schema = {
 
 // CORRECT - layout только связывает поле с сигналом модели...
 const layout = {
-  name:  { value: model.$.name,  component: InputField, componentProps: { label: 'Name' } },
-  email: { value: model.$.email, component: InputField, componentProps: { label: 'Email' } },
+  name:  { value: model.$.name,  component: Input, componentProps: { label: 'Name' } },
+  email: { value: model.$.email, component: Input, componentProps: { label: 'Email' } },
 };
 
 // ...а правила — отдельная ambient-схема (прогоняется раннером validateModel):

package/docs/llms/29-async-preload.md

@@ -31,16 +31,16 @@ Initial values задаются в `createModel(initial)`; `reset()` возвр
 
 ```typescript
 import { createModel, createForm } from '@reformer/core';
-import { InputField, SelectField } from '@reformer/ui-kit';
+import { Input, SelectAsync, CheckboxWithLabel } from '@reformer/ui-kit';
 
 type ProfileForm = { username: string; language: 'ru' | 'en'; marketing: boolean };
 
 const model = createModel<ProfileForm>({ username: '', language: 'ru', marketing: true });
 const schema = {
-  username: { value: model.$.username, component: InputField, componentProps: { label: 'Username' } },
+  username: { value: model.$.username, component: Input, componentProps: { label: 'Username' } },
   language: {
     value: model.$.language,
-    component: SelectField,
+    component: SelectAsync,
     componentProps: {
       label: 'Язык',
       options: [
@@ -49,7 +49,7 @@ const schema = {
       ],
     },
   },
-  marketing: { value: model.$.marketing, component: InputField, componentProps: { type: 'checkbox' } },
+  marketing: { value: model.$.marketing, component: CheckboxWithLabel, componentProps: { label: 'Рассылка' } },
 };
 const form = createForm({ model, schema });
 // model.get() === { username: '', language: 'ru', marketing: true }

package/docs/llms/30-type-safety-recipes.md

@@ -59,7 +59,7 @@ Layout-схема БЕЗ валидаторов — правила живут в
 const model = createModel<CreditApplicationForm>(initial);
 
 const schema = {
-  loanAmount: { value: model.$.loanAmount, component: InputField },
+  loanAmount: { value: model.$.loanAmount, component: InputNumber },
   // вложенная группа — builder, принимающий ModelSignals<Sub>
   personalData: personalDataNodes(model.$.personalData),
   // массив — { array, item }

package/docs/llms/34-i18n.md

@@ -0,0 +1,272 @@
+# i18n — локаль, загрузка словарей и провайдер
+
+## Purpose
+
+Подпуть `@reformer/core/i18n` — общий рантайм локализации для всех пакетов `@reformer/*`: объект
+локали, загрузка словарей, React-провайдер, перевод и форматирование. Язык задаётся провайдером,
+подгружается динамически и переключается на лету; узлы формы при этом не пересоздаются.
+
+Без провайдера всё работает на английском: у каждого пакета есть встроенная английская таблица.
+
+> Импорт всегда из `@reformer/core/i18n`. Из главной бочки `@reformer/core` этот модуль не
+> реэкспортируется: React-контекст локализации обязан существовать в одном экземпляре.
+
+## Локаль — это данные
+
+```typescript
+interface FormLocale {
+  code: string; // BCP 47: 'en', 'ru', 'pt-BR' — по нему работают Intl и plural
+  messages: Record<string, string>; // плоский словарь: ключ → сообщение ICU
+  weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+  dateLocale?: unknown; // необязательно: объект локали react-day-picker / date-fns
+  dateFormat?: string; // необязательно: токены date-fns для DatePicker
+}
+```
+
+Функций в локали нет, поэтому её можно положить JSON-файлом на сервер и получить по сети:
+
+```json
+{ "code": "ru", "weekStartsOn": 1, "messages": { "profile.title": "Профиль" } }
+```
+
+`extendLocale(base, patch)` возвращает новую локаль: словари сливаются (ключи из `patch` важнее),
+остальные поля заменяются.
+
+## Формат сообщений — подмножество ICU
+
+| Конструкция         | Пример                                                                    |
+| ------------------- | ------------------------------------------------------------------------- |
+| подстановка         | `Открыт файл {name}`                                                      |
+| множественные формы | `{count, plural, one{# файл} few{# файла} many{# файлов} other{# файла}}` |
+| точное значение     | `{count, plural, =0{файлов нет} other{# файлов}}`                         |
+| выбор               | `{gender, select, male{он} female{она} other{оно}}`                       |
+| экранирование       | `'{'` → `{`, `'}'` → `}`, `''` → `'`                                      |
+
+- Ветка `other` обязательна. `#` внутри `plural` — число, отформатированное по языку.
+- Типы `number`, `date`, `time`, `selectordinal` не поддерживаются: числа и даты форматируйте
+  отдельно (`useI18n().number`, `.date`) и передавайте готовой строкой.
+- Категории (`one`/`few`/`many`) берутся из `Intl.PluralRules` языка локали.
+
+## Загрузка локалей
+
+Откуда брать словарь, решает приложение: источник — функция `(code) => локаль | словарь`.
+
+```typescript
+import { createLocaleLoader, fetchMessages } from '@reformer/core/i18n';
+import { loadCoreLocale } from '@reformer/core/locale';
+
+export const loadLocale = createLocaleLoader([
+  loadCoreLocale, // встроенные словари ядра — чанк нужного языка
+  fetchMessages((code) => `/locales/${code}.json`), // ключи приложения и правки — с сервера
+]);
+```
+
+- Источники опрашиваются параллельно, сливаются по порядку: поздний перекрывает ранний.
+- Источник отдаёт локаль целиком (`{ code, messages, … }`) или голый словарь (`{ "a.b": "…" }`);
+  `null` означает «для этого языка у меня ничего нет» и ошибкой не считается.
+- Результат кэшируется по коду языка, идущий запрос не дублируется.
+- Отказ любого источника — отказ загрузки. Источник, которому можно промахнуться, оборачивайте:
+  `(code) => source(code).catch(() => null)`.
+- `loadLocale.peek(code)` — уже загруженная локаль или `undefined`; `loadLocale.preload(code)` — то
+  же, что вызов загрузчика.
+
+Ядро отдаёт свои локали в трёх видах:
+
+| Вид               | Импорт                                      | Для чего                                        |
+| ----------------- | ------------------------------------------- | ----------------------------------------------- |
+| загрузчик         | `loadCoreLocale` из `@reformer/core/locale` | основной путь: чанк языка по запросу            |
+| JSON-файл         | `@reformer/core/locale/ru.json`             | выложить на свой сервер, править без пересборки |
+| синхронный модуль | `ru` из `@reformer/core/locale/ru`          | SSR и тесты                                     |
+
+Встроенные языки ядра — `en` и `ru`. Словарь ядра несёт тексты ошибок валидации
+(`validation.<code>`) и единицы размера файла (`format.fileSize.b|kb|mb|gb|tb`).
+
+Пакеты выше отдают локаль накопительно и в тех же трёх видах, поэтому источник встроенных словарей
+в загрузчике всегда один — самого верхнего из используемых пакетов:
+
+| Пакеты приложения               | Источник                                     | Что в локали                      |
+| ------------------------------- | -------------------------------------------- | --------------------------------- |
+| только ядро                     | `loadCoreLocale` из `@reformer/core/locale`  | ошибки валидации, размер файла    |
+| ядро + `@reformer/cdk`          | `loadCdkLocale` из `@reformer/cdk/locale`    | то же плюс строки cdk (`cdk.*`)   |
+| ядро + cdk + `@reformer/ui-kit` | `loadKitLocale` из `@reformer/ui-kit/locale` | то же плюс подписи кита (`kit.*`) |
+
+## Провайдер
+
+```tsx
+import { I18nProvider } from '@reformer/core/i18n';
+
+function App() {
+  const [lang, setLang] = useState('ru');
+  return (
+    <I18nProvider lang={lang} load={loadLocale}>
+      <LangSwitch value={lang} onChange={setLang} />
+      <CreditForm />
+    </I18nProvider>
+  );
+}
+```
+
+| Проп            | Назначение                                                               |
+| --------------- | ------------------------------------------------------------------------ |
+| `lang` + `load` | провайдер грузит локаль сам                                              |
+| `fallback`      | что показать, пока не загружена самая первая локаль; по умолчанию ничего |
+| `onError`       | отказ загрузки `(error, lang)`                                           |
+| `locale`        | готовый объект вместо `lang` + `load` — SSR, тесты                       |
+
+Поведение при `lang` + `load`:
+
+- при смене `lang` на экране остаётся прежний язык, пока новый не загрузится;
+  `useI18n().pending` — для индикатора;
+- при быстром переключении применяется только последний запрос;
+- ошибка загрузки язык не меняет и попадает в `useI18n().error` и `onError`;
+- если локаль уже в кэше (`await loadLocale.preload(lang)` до монтирования), первый рендер
+  синхронный и `fallback` не показывается.
+
+SSR: эффекты на сервере не выполняются, поэтому там передавайте готовый объект —
+`<I18nProvider locale={ru}>` — либо заранее вызовите `preload`.
+
+Вложенный провайдер заменяет локаль для своего поддерева целиком.
+
+## Хуки
+
+```typescript
+const { code, locale, pending, error, t, has, number, date, fileSize } = useI18n();
+
+t('profile.title'); // ключ приложения
+t('cart.items', { count: 3 }); // с подстановками
+t('cart.empty', undefined, 'Your cart is empty'); // английский текст на случай промаха
+number(1234.5); // '1 234,5' в ru
+date(new Date(), { dateStyle: 'long' }); // '15 января 2024 г.' в ru
+fileSize(1536); // '1,5 КБ' в ru, '1.5 KB' без провайдера
+```
+
+`useMessages(builtinEn)` — для авторов пакетов и китов: ищет ключ в локали провайдера, а при
+промахе берёт встроенную английскую таблицу пакета. Тип ключа выводится из таблицы.
+
+```tsx
+import en from './locale/en.json';
+
+function ClearButton() {
+  const t = useMessages(en);
+  return <button aria-label={t('kit.select.clear')} />;
+}
+```
+
+## Тексты ошибок валидации
+
+Правила из `@reformer/core/validators` несут только `code` и `params`; готового текста у них нет
+(`message` по умолчанию — пустая строка). Строку даёт резолвер при отображении ошибки:
+
+1. `messageKey` автора правила — если такой ключ есть в активной локали;
+2. явное `message` автора правила;
+3. `validation.<code>` из словаря локали;
+4. `validation.<code>` из встроенной английской таблицы ядра;
+5. сам код — для своих кодов, которых нет ни в одном словаре.
+
+```typescript
+validate(model.$.email, [
+  required(), // «Обязательное поле» в ru, английская фраза без провайдера
+  minLength(5, { message: 'Слишком коротко' }), // явный текст: важнее словаря, но языком не переключается
+  email({ messageKey: 'profile.email.invalid' }), // ключ словаря приложения: переключается вместе с языком
+]);
+```
+
+- Текст получается при отображении, а не при проверке: смена языка переводит уже показанные
+  ошибки без повторной валидации.
+- `FormField` (`@reformer/cdk`, `@reformer/ui-kit`) резолвит ошибку сам. В своём компоненте —
+  `useValidationMessage()`; вне React — `resolveValidationError(error, createI18n(locale))`.
+- Свой код ошибки локализуется ключом `validation.<свой_код>` в словаре приложения либо
+  `messageKey` в самом правиле.
+- Встроенный текст меняется тем же ключом в словаре приложения:
+  `extendLocale(ru, { messages: { 'validation.required': 'Заполните поле' } })`.
+- Параметры готовятся до подстановки: `Date` — по языку (`15 янв. 2030 г.`), массив — перечнем,
+  размеры в байтах (`maxFileSize`, `minFileSize`, `actualSize`, `maxTotalFileSize`, `actualTotal`) —
+  строкой с единицей (`5 МБ`). Числа остаются числами, поэтому в сообщении работает `plural`.
+
+```tsx
+function FieldErrors({ control }: { control: FieldNode<string> }) {
+  const message = useValidationMessage();
+  const { errors, shouldShowError } = useFormControl(control);
+  return shouldShowError ? <span role="alert">{message(errors[0])}</span> : null;
+}
+```
+
+Смонтированный `ValidationMessagesProvider` из `@reformer/cdk` заменяет этот резолвер целиком:
+локаль для ошибок в его поддереве не участвует.
+
+## Что показывается, когда ключа нет
+
+| Ключ                       | Нет в локали                                                    | Сообщение не разбирается                              |
+| -------------------------- | --------------------------------------------------------------- | ----------------------------------------------------- |
+| пакета (`useMessages`)     | встроенный английский пакета                                    | встроенный английский, `console.error` вне production |
+| приложения (`useI18n().t`) | `defaultMessage`, затем сам ключ; `console.warn` вне production | то же, `console.error`                                |
+
+Пропущенная подстановка выводится как `{name}`. Форма не падает ни в одном из случаев: неполный
+словарь, пришедший по сети, — законный сценарий.
+
+## Проверка словаря в тестах
+
+```typescript
+import { validateLocale } from '@reformer/core/i18n';
+
+expect(validateLocale(ruJson, enJson)).toEqual([]);
+// находит: syntax (не разбирается), missing / extra (ключи), arguments (потерянная подстановка)
+```
+
+## Описатели сообщений (низкий уровень)
+
+`msg(key, values?, defaultMessage?)` создаёт описатель сообщения, `defineMessages(appEn)` — `msg` с
+типизированными ключами, `resolveLocalized(value, i18n)` раскрывает описатели в объекте пропсов.
+
+> ⚠️ Рендереры и `FormField` описатели сами пока НЕ раскрывают. Не кладите `msg(...)` в
+> `componentProps` схемы: компонент получит объект вместо строки. До появления раскрытия в
+> рендерерах вызывайте `resolveLocalized` вручную или используйте `useI18n().t`.
+
+## Anti-patterns
+
+```typescript
+// ❌ Импорт из главной бочки — i18n там нет, а второй путь импорта дал бы вторую копию контекста
+import { I18nProvider } from '@reformer/core';
+
+// ✅ Единственный путь импорта — подпуть i18n
+import { I18nProvider } from '@reformer/core/i18n';
+```
+
+```tsx
+// ❌ Новый загрузчик на каждый рендер: кэш теряется, локаль грузится заново, первый кадр — fallback
+<I18nProvider lang={lang} load={createLocaleLoader([loadCoreLocale])}>
+
+// ✅ Загрузчик — константа модуля: один кэш на приложение
+const loadLocale = createLocaleLoader([loadCoreLocale]);
+<I18nProvider lang={lang} load={loadLocale}>
+```
+
+```typescript
+// ❌ Число или дата типами ICU внутри сообщения — не поддерживается, сообщение не разберётся
+const message = 'Итого: {total, number}';
+
+// ✅ Отформатировать отдельно и передать готовой строкой
+t('cart.total', { total: number(total, { style: 'currency', currency: 'RUB' }) });
+```
+
+```tsx
+// ❌ Ошибка выводится полем message: у правил без своего текста оно пустое — на экране ничего
+<span>{errors[0].message}</span>;
+
+// ✅ Текст ошибки — через резолвер: он знает словарь локали, messageKey и явное сообщение
+const message = useValidationMessage();
+<span>{message(errors[0])}</span>;
+```
+
+```typescript
+// ❌ Настройки локали без словаря: объект без поля messages принимается за словарь сообщений
+const source = () => ({ weekStartsOn: 1 });
+
+// ✅ Часть локали узнаётся по полю messages — отдавайте его хотя бы пустым
+const source = () => ({ weekStartsOn: 1, messages: {} });
+```
+
+## See also
+
+- [28-submit-and-reset.md](./28-submit-and-reset.md) — жизненный цикл формы; смена языка его не затрагивает
+- [33-validation-strategy.md](./33-validation-strategy.md) — когда запускается валидация