@central-design-system/components 4.0.0-alpha.2 → 4.0.0-alpha.4

package/llms/llms-guides.txt

@@ -1,6 +1,6 @@
 # Central Design System (CDS 4) — гайды
 
-> Версия: 4.0.0-alpha.2
+> Версия: 4.0.0-alpha.4
 > Подключение, конвенции, формы, тематизация, Tailwind CSS, tree-shaking и адаптив.
 > Сгенерировано автоматически (`bun run generate:meta` → `bun run generate:llms`). Не редактировать вручную.
 
@@ -390,16 +390,18 @@ ThemeDefinition (TS)  →  --cds-color-* / --cds-* (CSS-переменные)
 
 ## Подключение темы
 
-CDS 4 поставляет шесть готовых тем:
+CDS 4 поставляет восемь готовых тем:
 
-| Тема          | Описание                                    |
-| ------------- | ------------------------------------------- |
-| `cdsLight`    | светлая тема, используется по умолчанию      |
-| `cdsDark`     | тёмная тема                                  |
-| `b2bLight`    | светлая тема для приложений B2B-Center       |
-| `b2bDark`     | тёмная тема для приложений B2B-Center        |
-| `promoLight`  | светлая промо-тема                           |
-| `promoDark`   | тёмная промо-тема                            |
+| Тема          | Описание                                |
+| ------------- |-----------------------------------------|
+| `cdsLight`    | светлая тема, используется по умолчанию |
+| `cdsDark`     | тёмная тема                             |
+| `b2bLight`    | светлая тема для приложений B2B-Center  |
+| `b2bDark`     | тёмная тема для приложений B2B-Center   |
+| `lumaLight`   | светлая тема Luma                       |
+| `lumaDark`    | тёмная тема Luma                        |
+| `promoLight`  | светлая промо-тема                      |
+| `promoDark`   | тёмная промо-тема                       |
 
 > По умолчанию используется `cdsLight` — подключать её не нужно.
 
@@ -1305,3 +1307,798 @@ defineRender(() => (
 остальные флаги — `false`. После гидрации значения можно пересчитать вызовом
 `display.update()` (пересчитывает и размеры, и платформу). Начальные размеры для SSR
 задаются вторым аргументом `createDisplay(options, ssr)` / опцией `ssr` в `createCds`.
+
+---
+
+# Глобальная конфигурация
+
+CDS 4 позволяет задать значения пропсов по умолчанию — глобально, для конкретного компонента
+или только внутри определённого поддерева. Так вы один раз описываете «как выглядят кнопки
+в нашем продукте» и перестаёте дублировать одни и те же пропсы в каждом шаблоне.
+
+## Настройка
+
+Значения по умолчанию задаются опцией `defaults` в `createCds`. Ключ `global` действует на все
+компоненты, ключ с именем компонента — только на него.
+
+```ts
+import { createApp } from 'vue';
+import '@central-design-system/components/styles';
+import { createCds, components, directives } from '@central-design-system/components';
+
+import App from './App.vue';
+
+const cds = createCds({
+  components,
+  directives,
+  defaults: {
+    global: {
+      size: 'sm'
+    },
+    CdsButton: {
+      appearance: 'secondary'
+    },
+    CdsTextInput: {
+      hideDetails: 'auto'
+    }
+  }
+});
+
+createApp(App).use(cds);
+```
+
+**Важно.** Пропсы в `defaults` пишутся в camelCase: `hideDetails`, а не `hide-details`.
+
+Ключ компонента — это его имя из `defineOptions({ name })`, то есть `CdsButton`, `CdsTextInput`,
+`CdsCardActions` и так далее. Имена подкомпонентов (`CdsCardTitle`, `CdsListItem`) работают так же,
+как имена корневых.
+
+### Порядок разрешения значения
+
+Для каждого пропса CDS берёт первое подходящее значение:
+
+1. проп, явно переданный в шаблоне;
+2. `defaults.<ИмяКомпонента>.<проп>` из ближайшего контекста дефолтов;
+3. `defaults.global.<проп>`;
+4. значение по умолчанию, объявленное в самом компоненте.
+
+Явно переданный проп всегда выигрывает — дефолты не могут «перебить» шаблон.
+
+### Изменение дефолтов в рантайме
+
+`createCds` возвращает инстанс, у которого дефолты лежат в реактивной ссылке. Их можно менять
+на лету — все смонтированные компоненты пересчитаются:
+
+```ts
+const cds = createCds({ components, directives });
+
+// например, включить компактный режим по настройке пользователя
+cds.defaults.value = {
+  ...cds.defaults.value,
+  global: { size: 'sm' }
+};
+```
+
+## Контекстные дефолты
+
+Дефолты можно задать для компонентов, вложенных в другой компонент. Например, чтобы все кнопки
+внутри карточки по умолчанию были вторичными:
+
+```ts
+createCds({
+  defaults: {
+    CdsCard: {
+      CdsButton: { appearance: 'secondary' }
+    }
+  }
+});
+```
+
+Правило простое: ключ с заглавной буквы — это имя вложенного компонента, ключ со строчной —
+проп текущего компонента. Вложенность не ограничена одним уровнем:
+
+```ts
+createCds({
+  defaults: {
+    CdsCard: {
+      CdsCardActions: {
+        CdsButton: { appearance: 'tertiary', size: 'sm' }
+      }
+    }
+  }
+});
+```
+
+Тот же механизм библиотека использует внутри себя, чтобы группирующие компоненты раздавали
+свои настройки детям:
+
+- `CdsButtonGroup` задаёт вложенным `CdsButton` пропсы `appearance`, `color`, `baseColor`, `size`;
+- `CdsTagGroup` задаёт `CdsTag` пропсы `color`, `activeColor`, `disabled`, `filter`;
+- `CdsSelectionControlGroup` раздаёт настройки контролам, имя целевого компонента задаётся
+  пропом `defaultsTarget` (`CdsCheckbox`, `CdsRadio` и т. д.);
+- так же работают `CdsTabs`, `CdsSteps`, `CdsList`, `CdsBreadcrumbs`, `CdsButtonToggle`,
+  `CdsExpandablePanels`, `CdsOtpInput`.
+
+Поэтому `<CdsButtonGroup size="sm">` делает маленькими все кнопки внутри — вам не нужно
+проставлять `size` каждой.
+
+## Глобальные класс и стиль
+
+В дефолтах компонента, помимо пропсов, можно задать `class` и `style`. Это удобный способ
+навесить продуктовые правила на все экземпляры компонента, не трогая шаблоны:
+
+```ts
+createCds({
+  defaults: {
+    CdsButton: {
+      class: 'my-button'
+    }
+  }
+});
+```
+
+Работает любое значение, которое принимает Vue, — строка, объект, массив:
+
+```ts
+createCds({
+  defaults: {
+    CdsButton: {
+      style: [{ textTransform: 'none' }]
+    }
+  }
+});
+```
+
+В отличие от обычных пропсов, `class` и `style` не перезаписываются шаблоном, а **объединяются**
+с ним. То есть `<CdsButton class="mt-200">` получит и `my-button`, и `mt-200`.
+
+**Важно.** `class` и `style` работают только в ключе конкретного компонента. В `global` они
+игнорируются.
+
+## Алиасы
+
+Алиас — это тот же компонент, зарегистрированный под другим именем и со своими дефолтами.
+Из алиасов удобно собирать «продуктовые» варианты компонентов.
+
+```ts
+import { createCds, components, directives, CdsButton } from '@central-design-system/components';
+
+const cds = createCds({
+  components,
+  directives,
+  aliases: {
+    CdsButtonPrimary: CdsButton,
+    CdsButtonDanger: CdsButton
+  },
+  defaults: {
+    CdsButtonPrimary: {
+      appearance: 'primary',
+      class: 'my-button--primary'
+    },
+    CdsButtonDanger: {
+      appearance: 'primary',
+      color: 'red',
+      class: 'my-button--danger'
+    }
+  }
+});
+```
+
+Алиасы регистрируются глобально, поэтому в шаблоне их можно использовать сразу:
+
+```vue
+<template>
+  <CdsButtonPrimary>Сохранить</CdsButtonPrimary>
+  <CdsButtonDanger class="ml-200">Удалить</CdsButtonDanger>
+</template>
+```
+
+**Важно.** Алиас не наследует дефолты базового компонента. Если в конфигурации есть
+`defaults.CdsButton`, к `<CdsButtonPrimary>` они не применятся — дефолты ищутся по имени алиаса.
+Общие настройки для обоих выносите в `global` или дублируйте в ключе алиаса.
+
+## Дефолты для части приложения
+
+Чтобы задать дефолты не глобально, а в поддереве, используйте компонент `CdsDefaultsProvider`.
+На нём же построена панель Controls в Storybook: значения из панели применяются
+к компонентам примера как дефолты.
+
+```vue
+<script setup lang="ts">
+import { CdsButton, CdsDefaultsProvider } from '@central-design-system/components';
+</script>
+
+<template>
+  <CdsDefaultsProvider :defaults="{ CdsButton: { appearance: 'tertiary', size: 'sm' } }">
+    <CdsButton>Второстепенная маленькая кнопка</CdsButton>
+  </CdsDefaultsProvider>
+</template>
+```
+
+| Проп       | Тип                 | Назначение                                                                                   |
+| ---------- | ------------------- | -------------------------------------------------------------------------------------------- |
+| `defaults` | `DefaultsOptions`   | Дефолты для поддерева; по умолчанию мержатся с унаследованными                                 |
+| `scoped`   | `boolean`           | Не смешивать с родительскими дефолтами — действуют только заданные здесь                        |
+| `reset`    | `number \| string`  | Подняться на N уровней вверх по цепочке дефолтов                                                |
+| `root`     | `boolean \| string` | Вернуться к корневым дефолтам из `createCds`; строкой — к именованной группе внутри них          |
+| `disabled` | `boolean`           | Ничего не провайдить — поддерево получает дефолты родителя как есть                              |
+
+Типичный сценарий `scoped` — «островок» в чужом окружении: вложенные группы (например,
+`CdsButtonGroup`) не должны навязывать свои настройки вашему блоку.
+
+## Свои компоненты
+
+Собственные компоненты приложения тоже могут участвовать в системе дефолтов. Для этого
+пропустите пропсы через `useDefaults`:
+
+```vue
+<script setup lang="ts">
+import { useDefaults } from '@central-design-system/components';
+
+const _props = defineProps<{ foo?: string }>();
+const props = useDefaults(_props, 'MyComponent');
+</script>
+
+<template>
+  <div>Я {{ props.foo }}</div>
+</template>
+```
+
+У `useDefaults` два аргумента, оба опциональные:
+
+- `props` — объект пропсов, возвращённый `defineProps`;
+- `name` — имя компонента, по которому ищется ключ в `defaults`. Если не передать, берётся имя
+  из `defineOptions({ name })`, а при его отсутствии — имя файла.
+
+Теперь компонент настраивается из общей конфигурации:
+
+```ts
+createCds({
+  defaults: {
+    MyComponent: { foo: 'бар' }
+  }
+});
+```
+
+**Важно.** В шаблоне обращайтесь к `props.foo`, а не к `foo`. `useDefaults` возвращает прокси
+над пропсами, и распакованные `defineProps` переменные его минуют:
+
+```diff
+-<div>Я {{ foo }}</div>
++<div>Я {{ props.foo }}</div>
+```
+
+### Вложенные дефолты в своих компонентах
+
+Чтобы ваш компонент раздавал дефолты детям (как это делает `CdsButtonGroup`), достаточно
+вызвать `useDefaults()` без аргументов — вложенные ключи из его секции `defaults` уйдут в
+дочерний контекст:
+
+```vue
+<script setup lang="ts">
+import { useDefaults } from '@central-design-system/components';
+
+useDefaults();
+</script>
+
+<template>
+  <div class="my-panel">
+    <slot />
+  </div>
+</template>
+```
+
+```ts
+createCds({
+  defaults: {
+    MyPanel: {
+      CdsButton: { appearance: 'tertiary' }
+    }
+  }
+});
+```
+
+Если дефолты детей зависят от пропсов компонента, используйте `provideDefaults` напрямую:
+
+```vue
+<script setup lang="ts">
+import { provideDefaults } from '@central-design-system/components';
+import { toRef } from 'vue';
+
+const props = defineProps<{ size?: 'sm' | 'md' }>();
+
+provideDefaults({
+  CdsButton: {
+    size: toRef(() => props.size)
+  }
+});
+</script>
+
+<template>
+  <div class="my-toolbar">
+    <slot />
+  </div>
+</template>
+```
+
+## Blueprint — пресет конфигурации
+
+Если один и тот же набор опций нужен нескольким приложениям, вынесите его в `blueprint`:
+это обычный объект опций `createCds`, на который сверху накладывается остальная конфигурация.
+
+```ts
+import { createCds, components, directives } from '@central-design-system/components';
+import type { Blueprint } from '@central-design-system/components';
+
+const productBlueprint: Blueprint = {
+  theme: { defaultTheme: 'b2bLight' },
+  defaults: {
+    CdsButton: { appearance: 'secondary' }
+  }
+};
+
+const cds = createCds({
+  blueprint: productBlueprint,
+  components,
+  directives,
+  // перекрывает значение из blueprint
+  defaults: {
+    CdsButton: { size: 'sm' }
+  }
+});
+```
+
+Опции сливаются глубоко (`mergeDeep`), поэтому в примере выше у кнопок останется
+`appearance: 'secondary'` из пресета и добавится `size: 'sm'`.
+
+---
+
+# Интернационализация (i18n)
+
+У компонентов CDS есть собственные тексты: «Отсутствуют данные» в селекте, подписи фильтров
+таблицы, `aria-label` кнопки закрытия, счётчик файлов. Все они идут через встроенный слой
+локализации, поэтому вы можете перевести их на другой язык, переопределить отдельную строку под
+свой продукт или переключать язык на лету — не переписывая компоненты.
+
+В библиотеку встроены два словаря — русский и английский. По умолчанию активен `ru`, поэтому без
+настройки всё уже на русском.
+
+## Настройка
+
+Локаль настраивается опцией `locale` в `createCds`. Переключиться на встроенный английский —
+одна строка, словари для этого передавать не нужно:
+
+```ts
+import { createApp } from 'vue';
+import '@central-design-system/components/styles';
+import { createCds, components, directives } from '@central-design-system/components';
+
+import App from './App.vue';
+
+const cds = createCds({
+  components,
+  directives,
+  locale: {
+    locale: 'en'
+  }
+});
+
+createApp(App).use(cds);
+```
+
+Языки, которых в библиотеке нет, добавляются словарём в `messages`:
+
+```ts
+import de from './locales/cds-de';
+
+createCds({
+  components,
+  directives,
+  locale: {
+    locale: 'de',
+    fallback: 'en',
+    messages: { de }
+  }
+});
+```
+
+| Опция              | Тип                       | Назначение                                                                    |
+| ------------------ | ------------------------- | ----------------------------------------------------------------------------- |
+| `locale`           | `string`                  | Активный язык; из коробки доступны `ru` (по умолчанию) и `en`                  |
+| `fallback`         | `string`                  | Язык, из которого берётся строка, если в активном её нет; по умолчанию `ru`    |
+| `messages`         | `LocaleMessages`          | Словари дополнительных языков; словарь одноимённого встроенного заменяется целиком |
+| `decimalSeparator` | `string`                  | Разделитель дробной части; по умолчанию выводится из активной локали           |
+| `rtl`              | `Record<string, boolean>` | Карта языков с письмом справа налево (см. [RTL](#rtl))                        |
+| `adapter`          | `LocaleInstance`          | Свой движок переводов вместо встроенного (см. [Свой адаптер](#свои-адаптер))   |
+
+Встроенные словари доступны и вам — они лежат в экспорте `locales`. Берите их за основу для
+своего языка или чтобы поправить пару строк:
+
+```ts
+import { locales } from '@central-design-system/components';
+
+locales.ru; // русский словарь
+locales.en; // английский словарь
+```
+
+Полный набор ключей — в разделе [Ключи сообщений](#ключи-сообщении).
+
+## Как компоненты берут текст
+
+Строки компонентов — это ключи с префиксом `$cds.`, которые библиотека прогоняет через функцию
+перевода. Часть ключей объявлена значениями пропсов по умолчанию, поэтому их видно в API:
+`text` у `CdsFileUpload` — `$cds.fileUpload.browse`, `closeLabel` у `CdsNotification` — `$cds.close`,
+`noDataText` у `CdsSelect` — `$cds.noDataText`.
+
+Отсюда три способа поменять текст.
+
+**Сменить язык целиком** — опцией `locale`:
+
+```ts
+createCds({ locale: { locale: 'en' } });
+```
+
+**Поменять надписи во всём продукте** — словарём поверх встроенного:
+
+```ts
+import { createCds, locales } from '@central-design-system/components';
+
+createCds({
+  locale: {
+    messages: {
+      ru: { ...locales.ru, noDataText: 'Ничего не нашлось' }
+    }
+  }
+});
+```
+
+**Важно.** Словарь языка заменяется целиком, а не сливается по ключам. Без спреда
+`...locales.ru` в русской локали останется один ключ, а остальные строки превратятся
+в свои же ключи (`$cds.close` вместо «Закрыть»). Вложенные секции спредьте отдельно:
+`table: { ...locales.ru.table, emptyText: '…' }`.
+
+**Поменять одну надпись в одном месте** — пропсом:
+
+```vue
+<CdsSelect :items="items" no-data-text="Подходящих поставщиков нет" />
+```
+
+Тот же проп можно задать значением по умолчанию для всех экземпляров компонента —
+см. глобальную конфигурацию:
+
+```ts
+createCds({
+  defaults: {
+    CdsSelect: { noDataText: 'Ничего не нашлось' }
+  }
+});
+```
+
+Функция перевода принимает и обычный текст: строка без префикса `$cds.` возвращается как есть,
+подставляя параметры. Так пропсы с локализуемым значением работают одинаково и с ключом,
+и с готовой фразой.
+
+Если ключа нет ни в активной локали, ни в `fallback`, компонент покажет сам ключ, а в dev-режиме
+в консоли появится предупреждение `[CDS: useLocale] Translation key … not found`.
+
+## Смена языка в рантайме
+
+`createCds` возвращает инстанс, у которого локаль лежит в реактивных ссылках — переключение
+языка достаточно записать в `current`:
+
+```ts
+const cds = createCds({ components, directives });
+
+// например, по выбору пользователя в настройках профиля
+cds.locale.current.value = 'en';
+```
+
+Внутри компонентов то же делает композабл `useLocale`:
+
+```vue
+<script setup lang="ts">
+import { CdsButton, CdsButtonToggle, useLocale } from '@central-design-system/components';
+
+const { current } = useLocale();
+</script>
+
+<template>
+  <CdsButtonToggle v-model="current" appearance="tertiary">
+    <CdsButton value="ru" text="Русский" />
+    <CdsButton value="en" text="English" />
+  </CdsButtonToggle>
+</template>
+```
+
+Все смонтированные компоненты пересчитают свои строки сами — перезагрузка страницы не нужна.
+
+## Локаль для части приложения
+
+Отдельному поддереву можно задать свой язык — например, показать англоязычный виджет внутри
+русского интерфейса. Для этого в компоненте-обёртке вызовите `provideLocale`: он берёт локаль
+из контекста, накладывает переданные пропсы и провайдит результат детям.
+
+```vue
+<script setup lang="ts">
+import { provideLocale } from '@central-design-system/components';
+
+const props = defineProps<{ locale?: string; fallback?: string }>();
+
+provideLocale(props);
+</script>
+
+<template>
+  <div>
+    <slot />
+  </div>
+</template>
+```
+
+```vue
+<template>
+  <LocaleProvider locale="en">
+    <CdsSelect :items="items" />
+  </LocaleProvider>
+</template>
+```
+
+Не переданные пропсы наследуются от родительской локали, поэтому обёртка с одним `locale`
+не теряет ни `fallback`, ни словари.
+
+## useLocale
+
+Композабл отдаёт текущую локаль и её функции — используйте его в своих компонентах, чтобы их
+тексты жили в тех же словарях, что и тексты CDS.
+
+```vue
+<script setup lang="ts">
+import { useLocale } from '@central-design-system/components';
+
+const { t, n } = useLocale();
+</script>
+
+<template>
+  <p>{{ t('$cds.table.emptyText') }}</p>
+  <p>{{ n(1234.56) }}</p>
+</template>
+```
+
+| Свойство           | Тип                                            | Назначение                                                    |
+| ------------------ | ---------------------------------------------- | ------------------------------------------------------------- |
+| `t`                | `(key: string, ...params: unknown[]) => string` | Перевод ключа `$cds.…` с подстановкой параметров               |
+| `n`                | `(value: number) => string`                    | Форматирование числа по активной локали                        |
+| `current`          | `Ref<string>`                                  | Активный язык; запись меняет язык                              |
+| `fallback`         | `Ref<string>`                                  | Язык-подстраховка                                              |
+| `messages`         | `Ref<LocaleMessages>`                          | Словари; можно дописывать в рантайме                           |
+| `decimalSeparator` | `ShallowRef<string>`                           | Разделитель дробной части активной локали                      |
+
+Параметры в строках нумерованные — `{0}`, `{1}`:
+
+```ts
+const { t } = useLocale();
+
+t('$cds.carousel.delimiter', 3, 8); // «Слайд 3 из 8»
+t('Осталось дней: {0}', 5); // «Осталось дней: 5»
+```
+
+`n` под капотом — `Intl.NumberFormat` с активной локалью и `fallback`, так что разделители групп
+и дробной части приходят из браузера. `decimalSeparator` библиотека выводит из той же локали
+(`,` для `ru`, `.` для `en`); если в продукте принят другой — задайте его явно в `createCds`.
+
+## Даты
+
+Названия месяцев и дней недели живут в отдельных date-локалях: их везут `ru` и `en`. Компоненты
+даты и времени берут date-локаль по активному языку, поэтому после `current.value = 'en'` календарь
+переключится сам.
+
+Одному компоненту язык задаётся пропом `locale` — он есть у `CdsDatePicker`, `CdsDateInput`
+и `CdsTimePicker`:
+
+```vue
+<CdsDatePicker v-model="value" locale="en" :first-day-of-week="0" header />
+```
+
+Проп принимает не только имя языка, но и свой объект date-локали (тип `TDateLocale`) — так
+подключается язык, которого в библиотеке нет. Встроенные date-локали для сверки и переиспользования
+лежат в том же экспорте `locales`: `locales.ruDate`, `locales.enDate` и карта `locales.dateLocales`.
+
+```ts
+const de = {
+  days: 'Sonntag_Montag_Dienstag_Mittwoch_Donnerstag_Freitag_Samstag'.split('_'),
+  daysShort: 'So_Mo_Di_Mi_Do_Fr_Sa'.split('_'),
+  months: 'Januar_Februar_März_April_Mai_Juni_Juli_August_September_Oktober_November_Dezember'.split('_'),
+  monthsLong: 'Januar_Februar_März_April_Mai_Juni_Juli_August_September_Oktober_November_Dezember'.split('_'),
+  monthsShort: 'Jan_Feb_Mär_Apr_Mai_Jun_Jul_Aug_Sep_Okt_Nov_Dez'.split('_'),
+  today: 'Heute',
+  now: 'Jetzt',
+  firstDayOfWeek: 1,
+  format24h: true,
+  pluralDay: (day = 0) => (day === 1 ? 'Tag' : 'Tage')
+};
+```
+
+```vue
+<CdsDatePicker v-model="value" :locale="de" />
+```
+
+## Таблица
+
+`CdsTable` собирает свои подписи из ключей `$cds.table.*`, но принимает и точечное
+переопределение пропом `locale` — он перекрывает только переданные строки:
+
+```vue
+<CdsTable :columns="columns" :data="data" :locale="{ emptyText: 'Заявок пока нет' }" />
+```
+
+## RTL
+
+Языки с письмом справа налево описываются картой `rtl`: ключ — язык, значение — направление.
+
+```ts
+createCds({
+  locale: {
+    locale: 'ar',
+    messages: { ar },
+    rtl: { ar: true }
+  }
+});
+```
+
+Компоненты читают направление через `useRtl` и разворачивают то, что зависит от оси: сторону
+раскрытия меню и тултипов, стрелки пагинации, порядок ячеек `CdsOtpInput`, заливку
+`CdsProgressBar`. Отступы и границы в стилях в основном описаны логическими свойствами
+(`margin-inline`, `inset-inline`) и зеркалятся браузером сами — но полноценной поддержки RTL
+дизайн-система пока не заявляет, отдельные места потребуют доводки на вашей стороне.
+
+Атрибут направления библиотека за вас не проставляет — повесьте его на корень приложения сами:
+
+```vue
+<script setup lang="ts">
+import { useRtl } from '@central-design-system/components';
+
+const { isRtl } = useRtl();
+</script>
+
+<template>
+  <div :dir="isRtl ? 'rtl' : 'ltr'">
+    <slot />
+  </div>
+</template>
+```
+
+`useRtl` отдаёт `isRtl` и `rtlClasses` — готовый класс `cds-locale--is-rtl` / `cds-locale--is-ltr`
+для ваших собственных стилей.
+
+## Свой адаптер
+
+Если в приложении уже есть i18n-библиотека, отдайте переводы ей: опция `adapter` принимает любой
+объект, реализующий интерфейс `LocaleInstance`. Тогда `messages`, `locale` и `fallback` из
+`createCds` не используются — источником истины становится ваш движок, а строки CDS живут
+в общих словарях приложения под ключом `$cds`.
+
+```ts
+import type { LocaleInstance, LocaleOptions } from '@central-design-system/components';
+import { toRef } from 'vue';
+import type { I18n } from 'vue-i18n';
+
+export function createVueI18nAdapter(i18n: I18n<any, any, any, string, false>): LocaleInstance {
+  const format = (value: number) => i18n.global.n(value);
+
+  return {
+    name: 'vue-i18n',
+    current: i18n.global.locale,
+    fallback: i18n.global.fallbackLocale as never,
+    messages: i18n.global.messages as never,
+    decimalSeparator: toRef(() => (format(0.1).includes(',') ? ',' : '.')),
+    t: (key, ...params) => i18n.global.t(key, params as never),
+    n: format,
+    provide: () => createVueI18nAdapter(i18n)
+  };
+}
+```
+
+```ts
+import { createI18n } from 'vue-i18n';
+
+const i18n = createI18n({
+  legacy: false,
+  locale: 'ru',
+  messages: {
+    ru: {
+      $cds: { noDataText: 'Отсутствуют данные' },
+      profile: { title: 'Профиль' }
+    }
+  }
+});
+
+const cds = createCds({
+  components,
+  directives,
+  locale: {
+    adapter: createVueI18nAdapter(i18n)
+  }
+});
+```
+
+Обязательные члены `LocaleInstance`: `name` (по нему адаптер и распознаётся), `current`,
+`fallback`, `messages`, `decimalSeparator`, `t`, `n` и `provide` — фабрика вложенной локали
+для `provideLocale`. Если поддержка «локали в поддереве» вам не нужна, `provide` может возвращать
+тот же инстанс, как в примере выше.
+
+## Ключи сообщений
+
+Встроенный русский словарь — шаблон для перевода на новый язык. Скопируйте его, переведите
+значения и передайте в `messages` под ключом своего языка; его английская версия доступна как
+`locales.en`.
+
+```ts
+export default {
+  badge: 'Бейдж',
+  noDataText: 'Отсутствуют данные',
+  selectAll: 'Выбрать все',
+  close: 'Закрыть',
+  open: 'Открыть',
+  dismiss: 'Отклонить',
+  confirmEdit: {
+    ok: 'ОК',
+    cancel: 'Отмена'
+  },
+  carousel: {
+    prev: 'Предыдущий слайд',
+    next: 'Следующий слайд',
+    delimiter: 'Слайд {0} из {1}'
+  },
+  input: {
+    clear: 'Очистить {0}',
+    otp: 'Введите одноразовый код',
+    prependAction: '{0} предварительных действий',
+    appendAction: '{0} добавочных действий'
+  },
+  fileInput: {
+    counter: 'Файлов: {0}',
+    counterSize: 'Файлов: {0} ({1} всего)'
+  },
+  fileUpload: {
+    title: 'Перетащите файлы сюда',
+    divider: 'или',
+    browse: 'Выберите файлы'
+  },
+  steps: {
+    prev: 'Назад',
+    next: 'Далее'
+  },
+  table: {
+    filterTitle: 'Фильтр меню',
+    filterConfirm: 'Выбрать',
+    filterReset: 'Сброс',
+    filterEmptyText: 'Нет фильтров',
+    filterCheckAll: 'Выбрать все элементы',
+    filterSearchPlaceholder: 'Поиск фильтров',
+    emptyText: 'Нет данных',
+    selectAll: 'Выбрать текущую страницу',
+    selectInvert: 'Инвертировать текущую страницу',
+    selectNone: 'Очистить все данные',
+    selectionAll: 'Выбрать все данные',
+    sortTitle: 'Сортировка',
+    expand: 'Раскрыть строку',
+    collapse: 'Свернуть строку',
+    triggerDesc: 'Отсортировать по убыванию',
+    triggerAsc: 'Отсортировать по возрастанию',
+    cancelSort: 'Отменить сортировку',
+    showed: 'Отображено',
+    from: 'из',
+    rowOnPage: 'Строк на странице'
+  },
+  uploader: {
+    uploading: 'Загрузка...',
+    uploadFile: 'Загрузить файл',
+    downloadFile: 'Скачать файл',
+    removeFile: 'Удалить файл',
+    uploadError: 'Ошибка загрузки',
+    previewFile: 'Предпросмотр файла'
+  }
+};
+```
+
+Словарь можно оставить неполным: недостающие ключи возьмутся из `fallback`, то есть по умолчанию
+из русского.