npm - @central-design-system/components - Versions diffs - 4.0.0-alpha.3 → 4.0.0-alpha.5 - Mend

@central-design-system/components 4.0.0-alpha.3 → 4.0.0-alpha.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1190) hide show

package/llms/llms-guides.txt CHANGED Viewed

@@ -1,21 +1,20 @@
-# Central Design System (CDS 4) — гайды
+# Central Design System (CDS 4) — guides
-> Версия: 4.0.0-alpha.3
-> Подключение, конвенции, формы, тематизация, Tailwind CSS, tree-shaking и адаптив.
-> Сгенерировано автоматически (`bun run generate:meta` → `bun run generate:llms`). Не редактировать вручную.
+> Version: 4.0.0-alpha.5
+> Setup, conventions, forms, theming, Tailwind CSS, tree-shaking, and responsiveness.
+> Generated automatically (`bun run generate:meta` → `bun run generate:llms`). Do not edit manually.
 ---
-# Подключение и темы
+# Setup and themes
-## Установка
+## Installation
 ```bash
-bun add @central-design-system/components
-# или npm i / yarn add / pnpm add
+npm install @central-design-system/components
 ```
-## Подключение к приложению
+## Wiring it into the app
 ```ts
 import { createApp } from 'vue';
@@ -27,31 +26,32 @@ const cds = createCds({ components, directives });
 createApp(App).use(cds).mount('#app');
 ```
-После этого все компоненты доступны глобально: `<CdsButton appearance="primary">Нажми меня</CdsButton>`.
+After that every component is available globally: `<CdsButton appearance="primary">Click me</CdsButton>`.
-Это полная регистрация — она подключает всю библиотеку. Для продуктовых приложений
-регистрируй компоненты точечно, см. гайд Tree-shaking.
+This is the full registration — it pulls in the entire library. For production
+apps register components individually, see the Tree-shaking guide.
-## Точки входа стилей
+## Style entry points
-| Импорт | Что подключает |
+| Import | What it provides |
 | --- | --- |
-| `@central-design-system/components/styles` | Агрегат: CSS всех компонентов (~556 KB). Быстрый старт, tree-shaking отключён |
-| `@central-design-system/components/styles/common.css` | Базовый слой (~9 KB): слои, reset, шрифты, типографика, grid |
-| `@central-design-system/components/styles/core` | Только слои, шрифты и reset — без типографики |
-| `@central-design-system/components/styles/utilities` | Утилитарные классы |
-| `@central-design-system/components/styles/tailwind` | Слой интеграции с Tailwind CSS |
-| `@central-design-system/components/styles/legacy` | Legacy-утилиты для миграции с CDS 3 |
+| `@central-design-system/components/styles` | Aggregate: CSS of every component (~556 KB). Quick start, tree-shaking disabled |
+| `@central-design-system/components/styles/common.css` | Base layer (~9 KB): layers, reset, fonts, typography, grid |
+| `@central-design-system/components/styles/core` | Only layers, fonts and reset — no typography |
+| `@central-design-system/components/styles/utilities` | Utility classes |
+| `@central-design-system/components/styles/tailwind` | Tailwind CSS integration layer |
+| `@central-design-system/components/styles/legacy` | Legacy utilities for migrating from CDS 3 |
-При точечной регистрации подключается только базовый слой `styles/common.css` —
-CSS каждого компонента приезжает вместе с самим компонентом.
+With per-component registration you only include the base layer
+`styles/common.css` — each component ships its own CSS alongside the
+component itself.
-Интеграция с Tailwind CSS v4 (установка, слои, утилиты на CDS-токенах) —
-в гайде Tailwind CSS + CDS.
+Tailwind CSS v4 integration (installation, layers, utilities built on CDS
+tokens) is covered in the Tailwind CSS + CDS guide.
-## Темы
+## Themes
-Тема задаётся при инициализации через `createCds`:
+The theme is set at initialization via `createCds`:
 ```ts
 const cds = createCds({
@@ -61,17 +61,17 @@ const cds = createCds({
 });
 ```
-Встроенные темы: `cdsLight` (по умолчанию), `cdsDark`, `b2bLight`, `b2bDark`,
-`promoLight`, `promoDark`. Значения всех цветовых токенов каждой темы —
-в ../tokens/themes.md.
+Built-in themes: `cdsLight` (default), `cdsDark`, `b2bLight`, `b2bDark`,
+`promoLight`, `promoDark`. The values of every color token in each theme
+are listed in ../tokens/themes.md.
-Своя тема, смена темы в рантайме и отключение темизации — в гайде
-Тематизация.
+Custom themes, runtime theme switching and disabling theming are covered in
+the Theming guide.
-## Иконки
+## Icons
-По умолчанию активен встроенный iconpack `cds`. Доступны и другие наборы
-(`carbon`, `lucide`, `phosphor`, `remix`):
+The built-in `cds` iconpack is active by default. Other packs are available
+too (`carbon`, `lucide`, `phosphor`, `remix`):
 ```ts
 import { createCds, iconsets } from '@central-design-system/components';
@@ -85,95 +85,96 @@ createCds({
 });
 ```
-Пакет `@central-design-system/icons` (CDS 3) — deprecated, см.
-миграцию.
+The `@central-design-system/icons` package (CDS 3) is deprecated, see the
+migration guide.
 ---
-# Конвенции CDS 4
+# CDS 4 conventions
-Главное правило: **источник истины — `api.md` компонента**
-(`references/components/<имя>/api.md`). Не выдумывай пропсы, события и слоты —
-если их нет в api.md, их нет в компоненте.
+The golden rule: **the source of truth is the component's `api.md`**
+(`references/components/<name>/api.md`). Do not invent props, events or
+slots — if they are not in api.md, they do not exist on the component.
-## Единые пропсы
+## Shared props
-Пропсы ниже приходят из общих composable-фабрик и ведут себя одинаково во всех
-компонентах, где присутствуют:
+The props below come from shared composable factories and behave identically
+in every component that has them:
-| Проп | Семантика |
+| Prop | Semantics |
 | --- | --- |
-| `size` | Размер: `xs` / `sm` / `md` / `lg` / `xl` или число |
-| `appearance` | Внешний вид (вариант оформления), набор значений у каждого компонента свой — смотри тип в api.md |
-| `color` / `bgColor` | Цвет контента / фона **токеном темы**, не CSS-значением |
-| `disabled` | Заблокированное состояние |
-| `loading` | Состояние загрузки |
-| `width` / `height` | Габариты (число → px или CSS-значение строкой) |
+| `size` | Size: `xs` / `sm` / `md` / `lg` / `xl` or a number |
+| `appearance` | Appearance (visual variant); the set of values is component-specific — check the type in api.md |
+| `color` / `bgColor` | Content / background color as a **theme token**, not a CSS value |
+| `disabled` | Disabled state |
+| `loading` | Loading state |
+| `width` / `height` | Dimensions (number → px, or a CSS value as a string) |
-## Токены, не raw-значения
+## Tokens, not raw values
-- Цвета задаются через проп `color` / токены темы (`--cds-color-*`), а не
-  произвольным CSS (`#fff`, `red`). Токены тем — в ../tokens/themes.md.
-- Отступы, радиусы и прочие величины в кастомном SCSS — через глобальные
-  `--cds-*` переменные, а не хардкод.
+- Set colors via the `color` prop / theme tokens (`--cds-color-*`), never
+  arbitrary CSS (`#fff`, `red`). Theme tokens are listed in ../tokens/themes.md.
+- Spacing, radii and other values in custom SCSS go through the global
+  `--cds-*` variables, never hardcoded.
 ## Atomic Design
-Сложный UI собирается композицией из атомов. Пример — форма: готовая «молекула»
-`CdsTextInput` внутри устроена как `CdsField` + `CdsLabel` + `CdsDescription` +
-`CdsMessages` + `CdsInput`, и те же атомы доступны для сборки собственных полей.
-Подробнее — в гайде «Формы».
+Complex UI is composed from atoms. Example — a form: the ready-made
+`CdsTextInput` "molecule" is internally built as `CdsField` + `CdsLabel` +
+`CdsDescription` + `CdsMessages` + `CdsInput`, and the same atoms are
+available for building your own fields. See the Forms guide
+for details.
-## Значения по умолчанию (Defaults)
+## Defaults
-Дефолты пропсов можно задать централизованно:
+Prop defaults can be set centrally:
-- глобально — через опцию `defaults` в `createCds({ defaults: { CdsButton: { size: 'lg' } } })`;
-- для поддерева — компонентом `CdsDefaultsProvider`
+- globally — via the `defaults` option in `createCds({ defaults: { CdsButton: { size: 'lg' } } })`;
+- for a subtree — with the `CdsDefaultsProvider` component
   (api).
-## Устаревшие API
+## Deprecated APIs
-Пропсы/компоненты, помеченные `_(deprecated)_` в api.md, работают, но будут
-удалены. В dev-консоли они дают предупреждение с префиксом `[CDS UPGRADE]`.
-При миграции со старого кода смотри гайд миграции.
+Props/components marked `_(deprecated)_` in api.md still work but will be
+removed. In the dev console they emit a warning prefixed `[CDS UPGRADE]`.
+When migrating legacy code, see the migration guide.
 ---
-# Формы на CDS 4
+# Forms with CDS 4
-## Готовые контролы
+## Ready-made controls
-Для типовых форм используй готовые «молекулы» (у каждой — свой `api.md` и
-`examples.md` в `references/components/`):
+For typical forms use the ready-made "molecules" (each has its own `api.md`
+and `examples.md` in `references/components/`):
-| Контрол | Назначение |
+| Control | Purpose |
 | --- | --- |
-| CdsTextInput | Текстовое поле с label / description / messages |
-| CdsSelect | Выпадающий список (single / multiple) |
-| CdsAutocomplete | Выбор с поиском по списку |
-| CdsCombobox | Выбор с возможностью ввода произвольного значения |
-| CdsCheckbox | Чекбокс |
-| CdsRadioGroup | Группа радиокнопок |
-| CdsToggle | Переключатель |
-| CdsDatePicker / CdsTimePicker | Дата / время |
+| CdsTextInput | Text field with label / description / messages |
+| CdsSelect | Dropdown (single / multiple) |
+| CdsAutocomplete | Selection with search over the list |
+| CdsCombobox | Selection that also accepts free-form input |
+| CdsCheckbox | Checkbox |
+| CdsRadioGroup | Radio button group |
+| CdsToggle | Toggle |
+| CdsDatePicker / CdsTimePicker | Date / time |
-## CdsForm: агрегация и валидация
+## CdsForm: aggregation and validation
-`CdsForm` объединяет поля, агрегирует их валидацию (`v-model` — валидность
-формы) и даёт методы `validate` / `reset` / `resetValidation` через слот-пропсы
-и exposed API. Правила валидации задаются на полях пропом `rules`
-(массив функций `значение → true | 'текст ошибки'`).
+`CdsForm` groups fields, aggregates their validation (`v-model` — form
+validity) and exposes `validate` / `reset` / `resetValidation` methods via
+slot props and the exposed API. Validation rules are set on the fields with
+the `rules` prop (an array of functions `value → true | 'error text'`).
-Проверенный пример (из Storybook):
+A verified example (from Storybook):
 ```html
 <CdsForm v-model="valid" @submit.prevent>
   <template #default="{ reset }">
-    <CdsTextInput v-model="name" :rules="rules.name" label="Имя" placeholder="Введите имя" />
-    <CdsTextInput v-model="email" :rules="rules.email" label="Email" placeholder="Введите Email" />
-    <CdsButton appearance="secondary" @click="reset">Очистить</CdsButton>
-    <CdsButton type="submit">Отправить</CdsButton>
+    <CdsTextInput v-model="name" :rules="rules.name" label="Name" placeholder="Enter name" />
+    <CdsTextInput v-model="email" :rules="rules.email" label="Email" placeholder="Enter Email" />
+    <CdsButton appearance="secondary" @click="reset">Clear</CdsButton>
+    <CdsButton type="submit">Submit</CdsButton>
   </template>
 </CdsForm>
 ```
@@ -185,111 +186,116 @@ const email = ref('');
 const rules = {
   name: [
-    (value: string) => !!value || 'Не может быть пустым',
-    (value: string) => value.length <= 10 || 'Не более 10 символов'
+    (value: string) => !!value || 'Must not be empty',
+    (value: string) => value.length <= 10 || 'No more than 10 characters'
   ],
   email: [
-    (value: string) => !!value || 'Не может быть пустым',
-    (value: string) => /.+@.+\..+/.test(value) || 'Неверный формат'
+    (value: string) => !!value || 'Must not be empty',
+    (value: string) => /.+@.+\..+/.test(value) || 'Invalid format'
   ]
 };
 ```
-Полезные режимы (полный список — в api.md):
+Useful modes (full list in api.md):
-- `first-fail` — валидация останавливается на первом невалидном поле;
-- `disabled` / `readonly` на форме прокидываются во все вложенные поля.
+- `first-fail` — validation stops at the first invalid field;
+- `disabled` / `readonly` on the form propagate to every nested field.
-CdsForm совместим и с внешними валидаторами (vuelidate, vee-validate) — см.
+CdsForm also works with external validators (vuelidate, vee-validate) — see
 examples.md.
-## Атомарная сборка собственного поля
+## Building your own field from atoms
-Когда готовой молекулы не хватает, поле собирается из атомов:
+When no ready-made molecule fits, assemble the field from atoms:
-| Атом | Роль |
+| Atom | Role |
 | --- | --- |
-| CdsField | Обёртка поля: связывает label/контрол/сообщения, состояния |
-| CdsLabel | Подпись поля |
-| CdsDescription | Вспомогательное описание |
-| CdsMessages | Сообщения об ошибках / подсказки |
-| CdsInput | Голый контрол ввода |
+| CdsField | Field wrapper: wires up label/control/messages, states |
+| CdsLabel | Field label |
+| CdsDescription | Supporting description |
+| CdsMessages | Error messages / hints |
+| CdsInput | Bare input control |
-Перед сборкой открой `api.md` каждого атома — состав пропсов и слотов бери
-только оттуда.
+Before assembling, open the `api.md` of every atom — take the set of props
+and slots only from there.
 ---
-# Миграция CDS 3 → CDS 4 (дайджест)
+# CDS 3 → CDS 4 migration (digest)
-Это краткий дайджест. **Полная версия с Before/After по каждому изменению —
-`MIGRATION.md` в корне npm-пакета `@central-design-system/components`.**
+This is a short digest. **The full version with Before/After for every
+change is `MIGRATION.md` at the root of the
+`@central-design-system/components` npm package.**
-## Легенда severity
+## Severity legend
-| Маркер | Что значит |
+| Marker | Meaning |
 | --- | --- |
-| ⚠️ **BREAKING** | Ломает существующий код — обязательное действие |
-| 🔁 **RENAMED** | Переименование — механический поиск/замена |
-| 🟠 **DEPRECATED** | Работает в 4.x, будет удалено в 5.x |
-| ✨ **NEW** | Новая возможность без ломки |
+| ⚠️ **BREAKING** | Breaks existing code — action required |
+| 🔁 **RENAMED** | Rename — mechanical search & replace |
+| 🟠 **DEPRECATED** | Works in 4.x, will be removed in 5.x |
+| ✨ **NEW** | New capability, nothing breaks |
-## Быстрый чек-лист
+## Quick checklist
-- [ ] Заменить импорт CSS: `@central-design-system/components/dist/cds.css` →
+- [ ] Replace the CSS import: `@central-design-system/components/dist/cds.css` →
       `@central-design-system/components/styles` (⚠️ breaking).
-- [ ] Если используете `@central-design-system/icons` — пакет 🟠 deprecated;
-      перейти на iconpacks через `createCds({ icons })` (см. setup.md).
-- [ ] Пройтись по индексу переименований компонентов ниже.
-- [ ] Прогнать сборку и проверить dev-консоль: предупреждения `[CDS UPGRADE]`
-      указывают на устаревшие пропсы.
+- [ ] If you use `@central-design-system/icons` — the package is 🟠 deprecated;
+      switch to iconpacks via `createCds({ icons })` (see setup.md).
+- [ ] Go through the component rename index below.
+- [ ] Run the build and check the dev console: `[CDS UPGRADE]` warnings
+      point at deprecated props.
-## Ключевые breaking-изменения
+## Key breaking changes
-- ⚠️ **Путь импорта CSS** — `dist/cds.css` больше не публичная точка входа,
-  подключать `@central-design-system/components/styles`.
-- ⚠️ **Legacy reset выключен по умолчанию** — глобальный reset из CDS 3 теперь
+- ⚠️ **CSS import path** — `dist/cds.css` is no longer a public entry point;
+  import `@central-design-system/components/styles` instead.
+- ⚠️ **Legacy reset is off by default** — the global reset from CDS 3 is now
   opt-in: `@use '@central-design-system/components/styles' with ($legacy-reset: true);`.
-- ⚠️ **CSS-архитектура на ITCSS + CSS Layers** — каскад определяется нативными
-  `@layer`; глобальные переопределения стилей CDS без `!important` могут
-  сработать иначе.
+- ⚠️ **CSS architecture on ITCSS + CSS Layers** — the cascade is driven by
+  native `@layer`; global overrides of CDS styles without `!important` may
+  now resolve differently.
-## Индекс переименований и удалений компонентов
+## Component rename and removal index
 | CDS 3 | CDS 4 |
 | --- | --- |
-| `CdsDropdown` | 🔁 `CdsSelect` (нативный `<select>` из CDS 3 — через проп `native-select`) |
+| `CdsDropdown` | 🔁 `CdsSelect` (the native `<select>` from CDS 3 — via the `native-select` prop) |
 | `CdsRadioButton` | 🔁 `CdsRadioGroup` |
 | `CdsProgress` | 🔁 `CdsProgressBar` |
 | `CdsTabsV2` | 🔁 `CdsTabs` |
-| `CdsCheckboxGroup` | ⚠️ удалён (использовать `CdsCheckbox` самостоятельно) |
-| `CdsContainer` | ⚠️ удалён |
-| `CdsBadge` | 🔁 пропсы: `count`→`content`, `limited`→`:max`; ⚠️ удалён `invertColor` |
+| `CdsCheckboxGroup` | ⚠️ removed (use `CdsCheckbox` on its own) |
+| `CdsContainer` | ⚠️ removed |
+| `CdsBadge` | 🔁 props: `count`→`content`, `limited`→`:max`; ⚠️ `invertColor` removed |
-После переименования сверься с `api.md` нового компонента в
-`../components/` — контракты пропсов могли измениться.
+After renaming, double-check the `api.md` of the new component in
+`../components/` — prop contracts may have changed.
 ---
+---
+sourceHash: abc11a2cdeb9c401a04b865e6fd89a2c3f36d3a5
+---
 # Tailwind CSS v4 + CDS 4
-Для проектов на Vite подключайте Tailwind CSS v4 по официальной инструкции Tailwind:
-[Installing Tailwind CSS with Vite](https://tailwindcss.com/docs/installation/using-vite).
+For Vite projects, install Tailwind CSS v4 by following the official Tailwind
+guide: [Installing Tailwind CSS with Vite](https://tailwindcss.com/docs/installation/using-vite).
-Ниже показана рекомендуемая интеграция CDS 4 с Tailwind CSS v4.
+Below is the recommended way to integrate CDS 4 with Tailwind CSS v4.
-- Vite-плагин подключается в `vite.config.ts`
-- CSS-слой Tailwind подключается в `main.ts`
+- The Vite plugin goes into `vite.config.ts`
+- Tailwind's CSS layer goes into `main.ts`
-## 1. Установите Tailwind CSS
+## 1. Install Tailwind CSS
 ```bash
 npm install -D tailwindcss @tailwindcss/vite
 ```
-## 2. Подключите Vite-плагин
+## 2. Add the Vite plugin
-Добавьте `@tailwindcss/vite` в `vite.config.ts`:
+Add `@tailwindcss/vite` to `vite.config.ts`:
 ```ts
 import { defineConfig } from 'vite';
@@ -300,9 +306,9 @@ export default defineConfig({
 });
 ```
-## 3. Создайте файл `tailwind.css`
+## 3. Create a `tailwind.css` file
-Например, `src/tailwind.css`:
+For example, `src/tailwind.css`:
 ```css
 @import "@central-design-system/components/styles/tailwind";
@@ -310,9 +316,10 @@ export default defineConfig({
 @import "tailwindcss/utilities" layer(cds-utilities.tailwind);
 ```
-Такой вариант подключает CDS-токены в Tailwind. `preflight` отдельно не нужен, потому что базовые reset-стили уже приходят из `@central-design-system/components/styles`.
+This wires CDS tokens into Tailwind. You don't need `preflight` separately —
+the base reset styles already come from `@central-design-system/components/styles`.
-## 4. Импортируйте стили в точке входа приложения
+## 4. Import the styles in your app entry point
 ```ts
 import { createApp } from 'vue';
@@ -332,45 +339,57 @@ const cds = createCds({
 createApp(App).use(cds).mount('#app');
 ```
-## 5. Используйте Tailwind-утилиты и CDS-токены вместе
+## 5. Use Tailwind utilities and CDS tokens together
 ```html
 <template>
-  <div class="flex flex-col gap-300 rounded-200 bg-surface-primary p-400 text-content-primary">
+  <div class="flex flex-col gap-3 rounded-200 bg-surface-primary p-4 text-content-primary">
     <h1 class="text-900 font-bold text-brand-primary">Hello CDS + Tailwind</h1>
-    <CdsButton>Нажми меня</CdsButton>
+    <CdsButton>Click me</CdsButton>
   </div>
 </template>
 ```
-После подключения доступны одновременно:
+Once this is set up, you get both at the same time:
+- standard Tailwind utilities: `flex`, `font-bold`, `gap-3`, `p-4`
+- utility classes built from CDS tokens: `bg-surface-primary`, `text-content-primary`, `rounded-200`
-- стандартные Tailwind-утилиты: `flex`, `font-bold`
-- utility-классы на основе CDS-токенов: `bg-surface-primary`, `text-content-primary`, `p-400`, `rounded-200`
+Write spacing with the standard Tailwind numeric scale (`gap-2`, `p-4`,
+`mt-2`): the CDS spacing scale matches it, so there is no need for
+`gap-200`/`p-400`-style spacing classes. Token-based classes remain for
+color, radius, and typography.
-CDS-конфигурация автоматически синхронизируется с активной темой CDS, поэтому
-цветовые utility-классы будут переключаться вместе с темой.
+The CDS configuration stays in sync with the active CDS theme automatically, so
+color utility classes switch along with the theme.
 ---
-# Тематизация
+---
+sourceHash: 41872192eda1479740145bb7f4bcb9dbb28f0462
+---
-Дизайн-система поддерживает смену темы или настройку своей собственной темы программно, в том числе прямо в рантайме.
+# Theming
-## Как это устроено
+The design system lets you switch themes or configure your own theme
+programmatically, including at runtime.
-Тема в CDS 4 — это набор **семантических токенов**, из которых при старте приложения генерируются CSS-переменные:
+## How it works
+A theme in CDS 4 is a set of **semantic tokens** that are turned into CSS
+variables when the application starts:
 ```
-ThemeDefinition (TS)  →  --cds-color-* / --cds-* (CSS-переменные)  →  стили компонентов
+ThemeDefinition (TS)  →  --cds-color-* / --cds-* (CSS variables)  →  component styles
                                      ↓
-                          @theme (Tailwind CSS v4)  →  bg-surface-primary, p-400, …
+                          @theme (Tailwind CSS v4)  →  bg-surface-primary, rounded-200, …
 ```
-Цвета пишутся в переменные **каналами RGB**, а не готовым цветом — это позволяет управлять прозрачностью:
+Colors are written into the variables as **RGB channels** rather than finished
+colors — that's what makes opacity control possible:
 ```css
-/* сгенерировано CDS */
+/* generated by CDS */
 :root {
   --cds-color-brand-primary: 0,90,178;
   --cds-color-surface-primary: 255,255,255;
@@ -378,7 +397,7 @@ ThemeDefinition (TS)  →  --cds-color-* / --cds-* (CSS-переменные)
   --cds-border-radius-200: 0.25rem;
 }
-/* использование */
+/* usage */
 .my-block {
   background: rgb(var(--cds-color-surface-primary));
   border: var(--cds-border-100) solid rgb(var(--cds-color-brand-primary) / 0.4);
@@ -386,24 +405,27 @@ ThemeDefinition (TS)  →  --cds-color-* / --cds-* (CSS-переменные)
 }
 ```
-Стили тем инжектятся в `<style id="cds-theme-stylesheet">` и пересчитываются реактивно при смене темы.
+Theme styles are injected into `<style id="cds-theme-stylesheet">` and are
+recalculated reactively when the theme changes.
-## Подключение темы
+## Enabling a theme
-CDS 4 поставляет шесть готовых тем:
+CDS 4 ships eight ready-made themes:
-| Тема          | Описание                                    |
-| ------------- | ------------------------------------------- |
-| `cdsLight`    | светлая тема, используется по умолчанию      |
-| `cdsDark`     | тёмная тема                                  |
-| `b2bLight`    | светлая тема для приложений B2B-Center       |
-| `b2bDark`     | тёмная тема для приложений B2B-Center        |
-| `promoLight`  | светлая промо-тема                           |
-| `promoDark`   | тёмная промо-тема                            |
+| Theme         | Description                             |
+| ------------- |-----------------------------------------|
+| `cdsLight`    | light theme, used by default            |
+| `cdsDark`     | dark theme                              |
+| `b2bLight`    | light theme for B2B-Center applications |
+| `b2bDark`     | dark theme for B2B-Center applications  |
+| `lumaLight`   | light Luma theme                        |
+| `lumaDark`    | dark Luma theme                         |
+| `promoLight`  | light promo theme                       |
+| `promoDark`   | dark promo theme                        |
-> По умолчанию используется `cdsLight` — подключать её не нужно.
+> `cdsLight` is used by default — you don't need to enable it.
-Чтобы включить другую тему, передайте её название в опции `createCds`:
+To switch to another theme, pass its name in the `createCds` options:
 ```ts
 import { createApp } from 'vue';
@@ -423,7 +445,7 @@ const cds = createCds({
 createApp(App).use(cds);
 ```
-## Опции темизации
+## Theming options
 ```ts
 createCds({
@@ -442,22 +464,24 @@ createCds({
 });
 ```
-| Опция           | Тип                                                        | По умолчанию            | Назначение                                                                 |
+| Option          | Type                                                        | Default                 | Purpose                                                                    |
 | --------------- | ---------------------------------------------------------- | ----------------------- | -------------------------------------------------------------------------- |
-| `defaultTheme`  | `ThemeName \| string`                                       | `'cdsLight'`            | Активная тема при старте                                                    |
-| `prefix`        | `string`                                                    | `'cds'`                 | Префикс генерируемых CSS-переменных (`--cds-color-*`)                       |
-| `themes`        | `Record<string, ThemeDefinition>`                           | штатные темы            | Свои темы; мержатся со штатными                                             |
-| `variations`    | `false \| { colors: string[]; lighten: number; darken: number }` | `false`             | Автогенерация светлых/тёмных вариаций цветов                                |
-| `utilities`     | `boolean`                                                   | `true`                  | Генерация утилитарных классов фона/текста по токенам темы                   |
-| `legacyClasses` | `boolean`                                                   | `false`                 | Легаси-классы CDS 3 (`cds-bg-*`, `cds-text-*`, `cds-border-*`)              |
-| `scoped`        | `boolean`                                                   | `false`                 | Не писать переменные в `:root`                                              |
-| `scope`         | `string`                                                    | —                       | Ограничить селекторы темы поддеревом (`:where(<scope>)`)                    |
-| `stylesheetId`  | `string`                                                    | `'cds-theme-stylesheet'`| `id` тега `<style>` с темой                                                 |
-| `cspNonce`      | `string`                                                    | —                       | `nonce` для Content Security Policy                                         |
-## Создание своей темы
-Своя тема — это объект `ThemeDefinition` с полями `dark`, `colors` и `variables`. Указывать нужно **только переопределения**: недостающие токены наследуются из `cdsLight` / `cdsDark`.
+| `defaultTheme`  | `ThemeName \| string`                                       | `'cdsLight'`            | Theme active at startup                                                     |
+| `prefix`        | `string`                                                    | `'cds'`                 | Prefix of the generated CSS variables (`--cds-color-*`)                     |
+| `themes`        | `Record<string, ThemeDefinition>`                           | built-in themes         | Your own themes; merged with the built-in ones                              |
+| `variations`    | `false \| { colors: string[]; lighten: number; darken: number }` | `false`             | Auto-generation of lighter/darker color variations                          |
+| `utilities`     | `boolean`                                                   | `true`                  | Generation of background/text utility classes from theme tokens             |
+| `legacyClasses` | `boolean`                                                   | `false`                 | CDS 3 legacy classes (`cds-bg-*`, `cds-text-*`, `cds-border-*`)             |
+| `scoped`        | `boolean`                                                   | `false`                 | Don't write the variables into `:root`                                      |
+| `scope`         | `string`                                                    | —                       | Limit theme selectors to a subtree (`:where(<scope>)`)                      |
+| `stylesheetId`  | `string`                                                    | `'cds-theme-stylesheet'`| `id` of the `<style>` tag holding the theme                                 |
+| `cspNonce`      | `string`                                                    | —                       | `nonce` for Content Security Policy                                         |
+## Creating your own theme
+A custom theme is a `ThemeDefinition` object with the fields `dark`, `colors` and
+`variables`. You only need to specify the **overrides**: missing tokens are
+inherited from `cdsLight` / `cdsDark`.
 ```ts
 import { createApp } from 'vue';
@@ -470,7 +494,7 @@ import App from './App.vue';
 const myCustomGreenTheme: ThemeDefinition = {
   dark: false,
   colors: {
-    // Основные цвета бренда новой темы
+    // Main brand colors of the new theme
     'brand-primary': '#2C8926',
     'brand-primary-hover': '#3C9C2C',
     'brand-primary-active': '#50A946',
@@ -480,11 +504,11 @@ const myCustomGreenTheme: ThemeDefinition = {
     'brand-secondary-hover': '#A5DD98',
     'brand-secondary-active': '#97D283',
     'brand-secondary-border': '#BCE8AB',
-    // Поверхности
+    // Surfaces
     'page-primary': '#F2F8F0',
     'surface-secondary': '#E8F3E4'
   },
-  // Переменные: типографика, отступы, скругления, тени
+  // Variables: typography, spacing, radii, shadows
   variables: {
     'font-family': 'Roboto, sans-serif',
     'border-radius-200': '0.625rem'
@@ -505,26 +529,30 @@ const cds = createCds({
 createApp(App).use(cds);
 ```
-Для каждой зарегистрированной темы дополнительно генерируется класс `.cds-theme--<name>` — им можно включить тему на произвольном участке разметки.
+Every registered theme also gets a `.cds-theme--<name>` class — use it to enable
+the theme on an arbitrary part of the markup.
-### Группы токенов
+### Token groups
-`colors` — семантические цвета:
+`colors` — semantic colors:
-- `brand-*` — бренд (`primary`, `secondary` и их `hover` / `active` / `border` / `content`)
-- `surface-*`, `page-*`, `fill-*` — поверхности и заливки
-- `content-*` — текст, иконки, ссылки
-- `line-*` — границы, разделители, фокус и выделение
-- `status-{success,warning,progress,info,danger,indication}-*` — статусы
-- `other-*` — дополнительные акцентные палитры
+- `brand-*` — brand (`primary`, `secondary` and their `hover` / `active` / `border` / `content`)
+- `surface-*`, `page-*`, `fill-*` — surfaces and fills
+- `content-*` — text, icons, links
+- `line-*` — borders, dividers, focus and selection
+- `status-{success,warning,progress,info,danger,indication}-*` — statuses
+- `other-*` — additional accent palettes
-`variables` — размерности: `spacing-*`, `font-size-*`, `font-line-height-*`, `font-weight-*`, `border-*`, `border-radius-*`, `shadow-{x,y,blur}-*`, `font-family`, `base-unit`.
+`variables` — dimensions: `spacing-*`, `font-size-*`, `font-line-height-*`,
+`font-weight-*`, `border-*`, `border-radius-*`, `shadow-{x,y,blur}-*`,
+`font-family`, `base-unit`.
-Полный список токенов конкретной темы смотрите в исходниках пакета: `@central-design-system/components/src/themes/cdsLight.ts`.
+For the full token list of a specific theme, see the package sources:
+`@central-design-system/components/src/themes/cdsLight.ts`.
-## Смена темы
+## Switching the theme
-Тему можно менять прямо в рантайме через composable `useTheme`:
+You can change the theme at runtime through the `useTheme` composable:
 ```vue
 <script setup lang="ts">
@@ -538,34 +566,39 @@ function toggleTheme(): void {
 </script>
 <template>
-  <cds-button @click="toggleTheme">Переключить тему</cds-button>
+  <cds-button @click="toggleTheme">Toggle theme</cds-button>
 </template>
 ```
-Также можно изменить тему конкретного компонента, передав в него проп `theme`. Учитывайте, что тема применится не только к самому компоненту, но и ко всем вложенным в него компонентам:
+You can also change the theme of a single component by passing it the `theme`
+prop. Keep in mind that the theme applies not only to the component itself but to
+everything nested inside it:
 ```vue
 <template>
   <cds-notification theme="b2bLight">
-    <!-- кнопка будет использовать тему b2bLight -->
+    <!-- the button will use the b2bLight theme -->
     <cds-button>Button</cds-button>
   </cds-notification>
 </template>
 ```
-Проп `theme` поддерживают компоненты-контейнеры и большинство визуальных компонентов: `CdsApp`, `CdsLayout`, `CdsPage`, `CdsSurface`, `CdsCard`, `CdsDrawer`, `CdsModal`, `CdsOverlay`, `CdsButton`, `CdsField`, `CdsTable` и другие.
+The `theme` prop is supported by container components and most visual components:
+`CdsApp`, `CdsLayout`, `CdsPage`, `CdsSurface`, `CdsCard`, `CdsDrawer`,
+`CdsModal`, `CdsOverlay`, `CdsButton`, `CdsField`, `CdsTable` and others.
-## Использование токенов темы в своём коде
+## Using theme tokens in your own code
 ### Tailwind CSS v4
-Токены темы замаплены в `@theme` Tailwind, поэтому утилиты переключаются вместе с темой автоматически:
+Theme tokens are mapped into Tailwind's `@theme`, so utilities switch along with
+the theme automatically:
 ```html
-<div class="bg-surface-primary text-content-primary p-400 rounded-200">…</div>
+<div class="bg-surface-primary text-content-primary p-4 rounded-200">…</div>
 ```
-Подключение описано в Tailwind CSS v4 + CDS 4.
+Setup is described in Tailwind CSS v4 + CDS 4.
 ### CSS / SCSS
@@ -578,7 +611,8 @@ function toggleTheme(): void {
 }
 ```
-Переопределяя стили компонентов CDS, пишите их в слой `cds-overrides` — так они гарантированно выиграют у стилей библиотеки:
+When you override CDS component styles, put them into the `cds-overrides` layer —
+that way they are guaranteed to win over the library's styles:
 ```scss
 @layer cds-overrides {
@@ -588,9 +622,10 @@ function toggleTheme(): void {
 }
 ```
-### Легаси-классы CDS 3
+### CDS 3 legacy classes
-Утилитарные классы CDS 3 (`cds-bg-*`, `cds-text-*`, `cds-border-*`) в CDS 4 **выключены по умолчанию**. Чтобы их вернуть на время миграции:
+The CDS 3 utility classes (`cds-bg-*`, `cds-text-*`, `cds-border-*`) are **off by
+default** in CDS 4. To bring them back for the duration of a migration:
 ```ts
 import '@central-design-system/components/styles/legacy';
@@ -600,9 +635,11 @@ const cds = createCds({
 });
 ```
-## Отключение темизации
+## Disabling theming
-Передайте в опцию `theme` значение `false`. Это предотвратит генерацию CSS-переменных и классов тем и отключит возможность смены темы в рантайме — тег `<style>` вообще не будет создан.
+Pass `false` to the `theme` option. This prevents the generation of CSS variables
+and theme classes and disables runtime theme switching — the `<style>` tag is not
+created at all.
 ```ts
 import { createCds } from '@central-design-system/components';
@@ -612,56 +649,59 @@ const cds = createCds({
 });
 ```
-При отключённой темизации `theme.isDisabled === true`, а `themeClasses` возвращает `undefined`.
+With theming disabled, `theme.isDisabled === true` and `themeClasses` returns
+`undefined`.
-## Интерфейс инстанса темы
+## Theme instance interface
-`useTheme()` возвращает `ThemeInstance` — доступ к текущей теме и её настройкам.
+`useTheme()` returns a `ThemeInstance` — access to the current theme and its
+settings.
 ```ts
 interface ThemeInstance {
-  /** Включена ли темизация (`false` при `theme: false`) */
+  /** Whether theming is enabled (`false` with `theme: false`) */
   readonly isDisabled: boolean;
   /**
-   * Raw-объект установленных тем
-   * Можно добавлять и изменять темы
+   * Raw object of the installed themes
+   * Themes can be added and modified
    */
   readonly themes: Ref<Record<string, InternalThemeDefinition>>;
   /**
-   * Название текущей темы
-   * Наследуется от родительского компонента
+   * Name of the current theme
+   * Inherited from the parent component
    */
   readonly name: Readonly<Ref<string>>;
   /**
-   * Обработанный объект текущей темы
-   * Включает уже автоматически сгенерированные цвета
+   * Processed object of the current theme
+   * Includes the automatically generated colors
    */
   readonly current: DeepReadonly<Ref<InternalThemeDefinition>>;
   readonly computedThemes: DeepReadonly<Ref<Record<string, InternalThemeDefinition>>>;
-  /** Класс текущей темы — `cds-theme--<name>` */
+  /** Class of the current theme — `cds-theme--<name>` */
   readonly themeClasses: Readonly<ComputedRef<string | undefined>>;
-  /** Сгенерированный CSS текущей темы */
+  /** Generated CSS of the current theme */
   readonly styles: Readonly<ComputedRef<string>>;
   readonly global: {
-    /** Название текущей глобальной темы в приложении (writable) */
+    /** Name of the current global theme in the application (writable) */
     readonly name: Ref<string>;
     /**
-     * Обработанный объект текущей глобальной темы в приложении
-     * Также можно получить из `theme.computedThemes.value[theme.global.name.value]`
+     * Processed object of the current global theme in the application
+     * Also available from `theme.computedThemes.value[theme.global.name.value]`
      */
     readonly current: DeepReadonly<Ref<InternalThemeDefinition>>;
   };
 }
 ```
-Инстанс темы также доступен из объекта, возвращённого `createCds()` — это удобно вне контекста компонента:
+The theme instance is also available on the object returned by `createCds()` —
+handy outside of a component context:
 ```ts
 const cds = createCds({ theme: { defaultTheme: 'cdsLight' } });
@@ -671,33 +711,39 @@ cds.theme.global.name.value = 'cdsDark';
 ---
+---
+sourceHash: b1ba0f5864509842881b42ebf6cfb46aadcba96f
+---
 # Tree-shaking
-CDS 4 публикуется как ESM-бандл с сохранённой модульной структурой: каждый компонент —
-отдельный чанк, рядом с ним лежит его собственный CSS. Благодаря этому сборщик
-(Vite, webpack, Rollup) может выбросить из приложения всё, что вы не используете.
+CDS 4 is published as an ESM bundle with its module structure preserved: every
+component is a separate chunk with its own CSS next to it. That lets the bundler
+(Vite, webpack, Rollup) drop everything your application doesn't use.
-Чтобы это работало, нужно соблюсти два правила:
+For this to work, follow two rules:
-1. **Регистрировать в `createCds` только те компоненты, которые реально нужны.**
-2. **Подключать базовые стили точечно**, а не весь `styles.css`.
+1. **Register only the components you actually need in `createCds`.**
+2. **Include the base styles selectively** rather than the whole `styles.css`.
-Ниже — как это сделать и сколько это даёт.
+Below is how to do that and how much it saves.
-## Как это устроено
+## How it works
-- ESM-бандл собирается с `chunkSplitPlugin({ strategy: 'unbundle' })` — модульная структура
-  библиотеки сохраняется, компоненты не склеиваются в один файл.
-- В `package.json` объявлен `sideEffects` — сборщик знает, что JS-модули библиотеки чистые
-  и их можно безопасно удалять.
-- При сборке в чанк каждого компонента дописывается импорт его CSS. Поэтому
-  `import { CdsButton }` тянет за собой ровно `CdsButton.css`, а не стили всей библиотеки.
+- The ESM bundle is built with `chunkSplitPlugin({ strategy: 'unbundle' })` — the
+  library's module structure is preserved and components are not glued into a
+  single file.
+- `package.json` declares `sideEffects`, so the bundler knows the library's JS
+  modules are pure and safe to remove.
+- During the build, each component's chunk gets an import of its own CSS
+  appended. That's why `import { CdsButton }` pulls in exactly `CdsButton.css`,
+  not the styles of the entire library.
-Отдельная сборка или плагин для этого не нужны — достаточно обычных именованных импортов.
+No special build or plugin is required — ordinary named imports are enough.
-## Точечная регистрация компонентов
+## Selective component registration
-Передавайте в `createCds` только используемые компоненты:
+Pass only the components you use to `createCds`:
 ```ts
 import { createApp } from 'vue';
@@ -714,25 +760,25 @@ const cds = createCds({
 createApp(App).use(cds).mount('#app');
 ```
-Компоненты, зарегистрированные таким образом, доступны в шаблонах глобально —
-как и при полной регистрации:
+Components registered this way are available in templates globally — just as with
+full registration:
 ```html
 <template>
   <CdsCard>
-    <CdsButton>Нажми меня</CdsButton>
+    <CdsButton>Click me</CdsButton>
   </CdsCard>
 </template>
 ```
-> **Важно:** `createCds` не регистрирует компоненты сам. Набор всегда задаёт вызывающая
-> сторона. Это сделано намеренно: если бы фабрика ссылалась на полный список компонентов,
-> сборщик не смог бы удалить ни один из них.
+> **Important:** `createCds` does not register components on its own. The set is
+> always defined by the caller. That's deliberate: if the factory referenced the
+> full component list, the bundler could not remove a single one of them.
-### Альтернатива: локальный импорт в SFC
+### Alternative: a local import in an SFC
-Если компонент нужен в одном-двух местах, глобальная регистрация не обязательна —
-импортируйте его прямо в компоненте:
+If you need a component in one or two places, global registration is optional —
+import it right inside the component:
 ```html
 <script setup lang="ts">
@@ -740,17 +786,18 @@ import { CdsButton } from '@central-design-system/components';
 </script>
 <template>
-  <CdsButton>Нажми меня</CdsButton>
+  <CdsButton>Click me</CdsButton>
 </template>
 ```
-`createCds` всё равно нужен в точке входа — он поставляет темы, локали, иконки
-и брейкпоинты через `provide`. Но в `components` его можно не передавать вовсе.
+You still need `createCds` in the entry point — it supplies themes, locales,
+icons and breakpoints through `provide`. But you don't have to pass `components`
+to it at all.
-## Полная регистрация
+## Full registration
-Когда набор компонентов заранее неизвестен (внутренние админки, песочницы,
-документация), проще зарегистрировать всё:
+When the set of components is not known in advance (internal admin panels,
+sandboxes, documentation), it's easier to register everything:
 ```ts
 import { createCds, components, directives } from '@central-design-system/components';
@@ -758,46 +805,47 @@ import { createCds, components, directives } from '@central-design-system/compon
 const cds = createCds({ components, directives });
 ```
-Такой вызов отключает tree-shaking компонентов: namespace-импорт `components`
-удерживает в бандле всю библиотеку.
+Such a call disables component tree-shaking: the `components` namespace import
+keeps the whole library in the bundle.
-## Стили
+## Styles
-Стили компонентов подключаются автоматически вместе с самими компонентами.
-Вручную нужно подключить только **базовый слой** — reset, шрифты, порядок CSS-слоёв
-и глобальные стили элементов:
+Component styles are included automatically along with the components themselves.
+The only thing you have to include manually is the **base layer** — reset, fonts,
+CSS layer order and global element styles:
 ```ts
 import '@central-design-system/components/styles/common.css';
 ```
-Базовый слой обязателен: именно в нём объявляется порядок `@layer`, от которого
-зависит корректный каскад стилей компонентов.
+The base layer is mandatory: it's where the `@layer` order is declared, and the
+correct cascade of component styles depends on it.
-Берите `common.css`, а не `core.css`: в `core.css` нет типографики, поэтому заголовки
-(`h1`–`h6`) останутся с браузерными размерами вместо шкалы CDS.
+Take `common.css`, not `core.css`: `core.css` has no typography, so headings
+(`h1`–`h6`) keep browser sizes instead of the CDS scale.
-Доступные варианты:
+Available options:
-| Импорт | Размер | Что внутри |
+| Import | Size | What's inside |
 | --- | --- | --- |
-| `styles/common.css` | ~9 KB | Рекомендуемая база: `core` + типографика + grid-утилиты |
-| `styles/core.css` | ~2 KB | Только слои, шрифты и reset — **без типографики** |
-| `styles/tailwind.css` | ~12 KB | CDS-токены для Tailwind CSS v4 |
-| `styles/legacy.css` | ~253 KB | Совместимость с легаси-разметкой CDS 3 |
+| `styles/common.css` | ~9 KB | The recommended base: `core` + typography + grid utilities |
+| `styles/core.css` | ~2 KB | Layers, fonts and reset only — **no typography** |
+| `styles/tailwind.css` | ~12 KB | CDS tokens for Tailwind CSS v4 |
+| `styles/legacy.css` | ~253 KB | Compatibility with legacy CDS 3 markup |
-> **Не используйте `@central-design-system/components/styles` в tree-shaking-сценарии.**
-> Это агрегат на ~556 KB, содержащий CSS всех компонентов библиотеки. Он удобен для
-> быстрого старта, но полностью обесценивает точечную регистрацию.
+> **Don't use `@central-design-system/components/styles` in a tree-shaking
+> scenario.** It's a ~556 KB aggregate containing the CSS of every component in
+> the library. It's convenient for a quick start, but it completely defeats
+> selective registration.
-Цветовые токены (`--cds-color-*` и остальные) в CSS-файлах не лежат — их генерирует
-и вставляет в документ `createCds` в рантайме, исходя из активной темы. Дополнительно
-подключать ничего не нужно.
+Color tokens (`--cds-color-*` and the rest) are not in the CSS files — they are
+generated and injected into the document by `createCds` at runtime, based on the
+active theme. There is nothing extra to include.
-## Директивы
+## Directives
-Директивы (`ClickOutside`, `Intersect`, `Touch`) экспортируются именованно и
-регистрируются так же точечно:
+Directives (`ClickOutside`, `Intersect`, `Touch`) are named exports and are
+registered just as selectively:
 ```ts
 import { createCds, ClickOutside } from '@central-design-system/components';
@@ -808,107 +856,355 @@ const cds = createCds({
 });
 ```
-Компонентам библиотеки регистрировать директивы не нужно — те, что используют
-`ClickOutside`, `Intersect` и `Touch` внутри (`CdsOverlay` и построенные на нём
-`CdsSelect`, `CdsMenu`, `CdsTooltip`, `CdsSlideView`, поля ввода), тянут их
-собственным импортом и регистрируют локально. Передавайте `directives` в
-`createCds` только ради своей разметки — `v-click-outside`, `v-intersect`,
-`v-touch` в шаблонах приложения.
+The library's own components don't need you to register directives — the ones
+that use `ClickOutside`, `Intersect` and `Touch` internally (`CdsOverlay` and
+everything built on it: `CdsSelect`, `CdsMenu`, `CdsTooltip`, `CdsSlideView`,
+input fields) import them themselves and register them locally. Pass `directives`
+to `createCds` only for your own markup — `v-click-outside`, `v-intersect`,
+`v-touch` in the application's templates.
-> **В `4.0.0-alpha.0`:** локальная регистрация внутри
-> компонентов не срабатывала, и меню `CdsSelect` / `CdsMenu` не закрывалось по
-> клику вне, если в `createCds` не передали `directives`. Если обновиться нельзя —
-> добавьте в регистрацию `directives: { ClickOutside, Touch }`.
+> **In `4.0.0-alpha.0`:** local registration inside components didn't work, and
+> the `CdsSelect` / `CdsMenu` menus wouldn't close on an outside click unless
+> `directives` was passed to `createCds`. If you can't upgrade, add
+> `directives: { ClickOutside, Touch }` to the registration.
-## Сколько это даёт
+## How much it saves
-Замеры на Vite 5 (production, minify, стили в отдельном файле, Vue включён в бандл,
-базовый `common.css` не учтён):
+Measurements on Vite 5 (production, minified, styles in a separate file, Vue
+included in the bundle, the base `common.css` not counted):
-| Сценарий | JS | JS (gzip) | CSS | CSS (gzip) |
+| Scenario | JS | JS (gzip) | CSS | CSS (gzip) |
 | --- | --- | --- | --- | --- |
-| Полная регистрация (`components`, `directives`) | 625 KB | 203 KB | 208 KB | 24.6 KB |
-| `createCds` + 3 компонента | 196 KB | 62.6 KB | 27.6 KB | 4.1 KB |
-| `createCds` + 1 компонент | 162 KB | 51.4 KB | 12.6 KB | 1.9 KB |
-| 1 компонент без `createCds` | 63 KB | 23.4 KB | 12.6 KB | 1.9 KB |
+| Full registration (`components`, `directives`) | 625 KB | 203 KB | 208 KB | 24.6 KB |
+| `createCds` + 3 components | 196 KB | 62.6 KB | 27.6 KB | 4.1 KB |
+| `createCds` + 1 component | 162 KB | 51.4 KB | 12.6 KB | 1.9 KB |
+| 1 component without `createCds` | 63 KB | 23.4 KB | 12.6 KB | 1.9 KB |
-Цифры зависят от того, какие именно компоненты подключены: составные компоненты
-(`CdsTable`, `CdsAutocomplete`, `CdsDatePicker`) тянут больше зависимостей, чем атомы.
+The numbers depend on which components exactly you include: composite components
+(`CdsTable`, `CdsAutocomplete`, `CdsDatePicker`) pull in more dependencies than
+atoms do.
-### Что не тришейкается
+### What isn't tree-shaken
-Около 99 KB приходится на ядро, которое `createCds` подключает всегда:
-темы, локали, иконки, брейкпоинты (`useDisplay`), `goTo` и система `defaults`.
-Этот объём не зависит от числа компонентов — он и составляет разницу между
-строками «1 компонент без `createCds`» (63 KB) и «`createCds` + 1 компонент» (162 KB).
+About 99 KB is the core that `createCds` always includes: themes, locales, icons,
+breakpoints (`useDisplay`), `goTo` and the `defaults` system. That volume doesn't
+depend on the number of components — it is exactly the difference between the
+"1 component without `createCds`" (63 KB) and "`createCds` + 1 component"
+(162 KB) rows.
-Если CDS используется в паре мест и глобальные подсистемы не нужны, можно вообще
-не вызывать `createCds`. Но тогда не будет ни тем, ни локалей, ни настроек
-по умолчанию, поэтому такой режим подходит только для точечных встроек.
+If CDS is used in a couple of places and you don't need the global subsystems,
+you can skip `createCds` entirely. But then there are no themes, no locales and
+no defaults, so that mode only suits pinpoint embeds.
-## Как проверить результат
+## How to verify the result
 ```bash
 npx vite-bundle-visualizer
 ```
-На что смотреть:
+What to look for:
-- в бандле не должно быть чанков компонентов, которых нет в вашем `createCds`;
-- если попал «лишний» компонент — скорее всего, он импортируется транзитивно
-  (например, `CdsSelect` тянет `CdsMenu` и `CdsList`), это нормально;
-- если в бандле оказалась вся библиотека — ищите `components` или `import * as`
-  среди своих импортов.
+- the bundle should contain no chunks of components missing from your `createCds`;
+- if an "extra" component shows up, it is most likely imported transitively
+  (`CdsSelect` pulls in `CdsMenu` and `CdsList`, for instance) — that's normal;
+- if the whole library ended up in the bundle, look for `components` or
+  `import * as` among your imports.
-## Частые ошибки
+## Common mistakes
-**Namespace-импорт вместо именованного.** Любой `import * as` из библиотеки
-удерживает её целиком:
+**A namespace import instead of a named one.** Any `import * as` from the library
+keeps all of it:
 ```ts
-// ❌ тянет все компоненты
+// ❌ pulls in every component
 import * as cdsComponents from '@central-design-system/components';
 // ✅
 import { CdsButton } from '@central-design-system/components';
 ```
-**Импорт наборов иконок через `iconsets`.** Объект `iconsets` ссылается сразу на все
-наборы, поэтому не тришейкается: в бандл попадёт JS всех паков (включая `cds` — 46 KB)
-и, поскольку UnoCSS сканирует их сам, CSS всех пяти наборов (≈370 KB вместо ≈70 KB).
-Импортируйте набор подпутём:
+**Importing icon packs through `iconsets`.** The `iconsets` object references all
+packs at once, so it is not tree-shaken: the bundle gets the JS of every pack
+(including `cds` — 46 KB) and, since UnoCSS scans them itself, the CSS of all five
+packs (≈370 KB instead of ≈70 KB). Import the pack through its subpath:
 ```ts
-// ❌ тянет все наборы
+// ❌ pulls in every pack
 import { iconsets } from '@central-design-system/components';
 const aliases = iconsets.remix.aliases;
-// ✅ только remix
+// ✅ remix only
 import { remix } from '@central-design-system/components/iconsets/remix';
 const aliases = remix.aliases;
 ```
-**Подключение агрегата стилей.** `@central-design-system/components/styles` содержит CSS
-всех компонентов — используйте `styles/common.css`.
+**Including the style aggregate.** `@central-design-system/components/styles`
+contains the CSS of every component — use `styles/common.css`.
+**Your own barrel re-export.** A `src/ui/index.ts` file that re-exports dozens of
+CDS components kills tree-shaking if you import everything from it. Import
+components directly from the library.
+**A bundler without ESM support.** The CJS bundle (`dist/cjs`) and the IIFE build
+are not tree-shakable by design. Make sure your bundler resolves the `import`
+export condition — Vite, webpack 5 and Rollup do it by default.
+---
+---
+sourceHash: 5d3ad246b66c58c6ecd39eb645d52dd6a026eaf2
+---
+# SASS variables
+CDS 4 styles are written in SASS/SCSS, and part of the internal setup — the base
+reset, global typography, font, grid and breakpoints — is extracted into SASS
+variables flagged with `!default`. You can override them when building your
+application through the standard
+[module configuration](https://sass-lang.com/documentation/at-rules/use/#configuration)
+mechanism: `@use '…' with (…)`.
+> SASS variables are the **compile-time** configuration layer. Colors, spacing
+> and the rest of the component design tokens live in CSS variables (`--cds-*`)
+> and are configured by themes at runtime — see Theming. Start
+> with the theme; drop down to SASS variables when you need to change the base
+> layer itself: reset, typography, grid.
+## Setup
+Vite compiles SCSS out of the box — you only need the preprocessor itself:
+```bash
+npm install -D sass-embedded
+```
+The classic `sass` works too, but `sass-embedded` is noticeably faster. To speed
+up large builds, opt into the modern compiler API:
+```ts
+// vite.config.ts
+export default defineConfig({
+  css: {
+    preprocessorOptions: {
+      scss: { api: 'modern-compiler' }
+    }
+  }
+});
+```
+## Plugging in with a configuration
+Normally the base styles are plugged in as ready-made CSS —
+`import '@central-design-system/components/styles'`. To override SASS variables,
+replace that import with your own SCSS file: in SCSS the
+`@central-design-system/components/styles` entry point resolves to the **sources**
+of the base layer (the `sass` export condition in `package.json`), and your
+configuration is applied at compile time.
+```diff
+// main.ts
+import { createApp } from 'vue';
+- import '@central-design-system/components/styles';
++ import './styles/main.scss';
+```
+```scss
+// src/styles/main.scss
+@use '@central-design-system/components/styles' with (
+  $reset: false,
+  $body-font-family: ('Inter', sans-serif)
+);
+```
+The component styles themselves need nothing extra: they are precompiled and ship
+with the components' JS chunks — both with selective and with full registration
+(see Tree-shaking).
+> Wrap a value containing commas — `$body-font-family` with several fonts, for
+> instance — in parentheses, otherwise SASS reads it as several arguments.
+## A settings file
+Module configuration is applied once, on the first load. If you need the values
+not only in the entry point but also in your application's component styles,
+extract them into a separate settings file and use that everywhere:
+```scss
+// src/styles/settings.scss
+@forward '@central-design-system/components/styles/settings' with (
+  $body-font-family: ('Inter', sans-serif),
+  $grid-gutter: 24px
+);
+```
+```scss
+// src/styles/main.scss
+@use './settings'; // configures the CDS variables
+@use '@central-design-system/components/styles'; // the base is built with them
+```
+```html
+<!-- Component.vue -->
+<style lang="scss">
+@use '@/styles/settings' as s;
+.card {
+  gap: s.$grid-gutter;
+  font-family: s.$body-font-family;
+}
+</style>
+```
+Every `<style>` block is compiled separately, so "configure it in `main.scss` and
+read it straight from the package" won't work — a direct
+`@use '@central-design-system/components/styles/settings'` in a component would
+return the default values. A shared settings file guarantees identical values at
+every compilation point.
+The `styles/settings` entry contains variables only and emits not a single byte
+of CSS — it's safe to include in any number of files.
+## Global variables
+| Variable | Default | What it does |
+| --- | --- | --- |
+| `$reset` | `true` | Emit the base layer's CSS reset |
+| `$legacy-reset` | `false` | Reset for compatibility with CDS 3 markup |
+| `$enable-typography` | `true` | Global typography (`h1`–`h6`, `.h1`–`.h6` and so on) |
+| `$body-font-family` | `var(--cds-font-family), 'PT Root UI VF', …` | `body` font |
+| `$font-size-root` | `var(--cds-base-unit)` (16px) | Root font size |
+| `$line-height-root` | `1.5` | Root line height |
+| `$border-color-root` | `transparent` | Default border color |
+| `$border-style-root` | `solid` | Default border style |
+| `$border-radius-root` | `var(--cds-border-radius-200)` | Base corner radius |
+| `$size-scale` | `4px` | Step of the size scale |
+| `$sizes` | `('xs', 'sm', 'md', 'lg', 'xl')` | Size names |
+| `$standard-easing` | `cubic-bezier(0.4, 0, 0.2, 1)` | Base animation curve |
+| `$decelerated-easing` | `cubic-bezier(0, 0, 0.2, 1)` | Enter curve |
+| `$accelerated-easing` | `cubic-bezier(0.4, 0, 1, 1)` | Leave curve |
+| `$rounded` | map | Radius scale (`sm`, `md`, `lg`, `xl`, `pill`, `circle`, …) |
+## Grid and breakpoints
+| Variable | Default | What it does |
+| --- | --- | --- |
+| `$prefix` | `'cds'` | Prefix of the grid CSS classes |
+| `$flex-grid-columns` | `16` | Number of flex grid columns (`12` is supported too) |
+| `$grid-gutter` | `32px` | Grid gutter |
+| `$grid-gutter-condensed` | `1px` | Gutter of the condensed grid |
+| `$grid-breakpoints` | map | Breakpoints: width, columns and spacing for `xs`–`xl` |
+The grid variables belong to the same settings module, while the breakpoint and
+grid mixins live in a separate `styles/breakpoints` entry — which emits no CSS
+either:
+```scss
+@use '@/styles/settings' as s;
+@use '@central-design-system/components/styles/breakpoints' as bp;
+.sidebar {
+  gap: s.$grid-gutter;
+  @include bp.cds-breakpoint-up('md') {
+    width: 320px;
+  }
+}
+```
+> SASS breakpoints affect your styles and the grid mixins. The runtime
+> breakpoints of `useDisplay` are configured separately, through the `display`
+> option of `createCds` (see Display & Platform).
+> The two sets match by default; when you change one, don't forget the other.
+## Component variables and vite-plugin
+Without the plugin, `@use … with` configures the base layer only: component CSS
+is precompiled. The `@central-design-system/vite-plugin` plugin lifts that
+limitation — it recompiles the styles of every component you use with your
+settings file:
+```ts
+// vite.config.ts
+import cds from '@central-design-system/vite-plugin';
+export default defineConfig({
+  plugins: [
+    vue(),
+    cds({ styles: { configFile: 'src/styles/settings.scss' } })
+  ]
+});
+```
+The settings file is the same, but you have to forward
+`styles/component-settings` — the aggregate that includes both global and
+component variables:
+```scss
+// src/styles/settings.scss
+@forward '@central-design-system/components/styles/component-settings' with (
+  $border-radius-root: 0,          // global
+  $button-border-radius: 9999px    // component-level
+);
+```
-**Собственный barrel-реэкспорт.** Файл вида `src/ui/index.ts`, который реэкспортирует
-десятки компонентов CDS, сводит tree-shaking на нет, если импортировать из него всё подряд.
-Импортируйте компоненты напрямую из библиотеки.
+With the plugin you don't need to change the
+`@central-design-system/components/styles` import in `main.ts` — it starts
+meaning "the configured base layer" on its own, and component styles are rebuilt
+on the fly. The plugin can also auto-import components from templates
+(`autoImport: true` by default), which makes registration in
+`createCds({ components })` optional.
+## What SASS can't configure
+- **Component-local variables** (`$button-border-radius` and friends from
+  `styles/_CdsX.variables.scss`). Unavailable without the plugin: component CSS
+  is published precompiled, so its local variables are frozen at the moment the
+  library was built. With `@central-design-system/vite-plugin` they are
+  configured through `styles/component-settings` — the plugin recompiles the
+  published SCSS sources of the components with your settings file (see above).
+- **Turning off individual utility classes.** Instead of a toggle map, pick an
+  entry point by content: `styles/core` — layers, fonts and reset only;
+  `styles/common` — plus typography and helpers.
+- **CSS layers.** `@layer cds-*` is always on: the layer order is declared in the
+  base style layer, and ordinary application CSS (outside `@layer`) always beats
+  the design system's styles — there is nothing to turn off here.
+## Pitfalls
+- **Variables only in the settings file.** Any styles or imports of regular style
+  files inside `settings.scss` get duplicated into every file that includes it.
+  Styles belong in `main.scss`; the settings file holds variables, mixins and
+  functions.
+- **Configure before the module's first load.** `@use … with` fails with a
+  `module was already loaded` error if the settings module has already been
+  loaded without a configuration higher up the chain. Include the settings file
+  first.
+- **Build speed.** With ready-made CSS there is nothing to compile; with a
+  configuration the base layer is built together with the application. The volume
+  is small, but the difference shows on cold builds — `sass-embedded` and
+  `api: 'modern-compiler'` keep it to a minimum.
+- **Resolution assumes a bundler.** Bare imports such as
+  `@use '@central-design-system/components/styles'` are resolved by Vite and
+  webpack (`sass-loader`) through the `sass` export condition. In plain `sass`
+  CLI without a bundler you'll have to point the paths at the files inside
+  `node_modules` by hand.
-**Сборщик без поддержки ESM.** CJS-бандл (`dist/cjs`) и IIFE-сборка не тришейкаются
-by design. Убедитесь, что сборщик резолвит `import`-условие экспорта, — Vite, webpack 5
-и Rollup делают это по умолчанию.
+---
+---
+sourceHash: 5822739245a9c6095f09064c0b58dc326ac5c188
 ---
-# Иконки
+# Icons
-Дизайн-система CDS v4 «из коробки» поддерживает множество популярных наборов иконок (iconpack).
+CDS v4 supports many popular icon packs out of the box.
-## Использование
+## Usage
-Вы можете выбрать один из готовых наборов иконок или подключить собственный.
-По умолчанию CDS использует набор `cds` — он включает все иконки, необходимые компонентам дизайн-системы.
+You can pick one of the ready-made icon packs or plug in your own.
+By default CDS uses the `cds` pack — it contains every icon the design system
+components need.
 ```ts
 import { createCds } from '@central-design-system/components';
@@ -922,7 +1218,7 @@ const cds = createCds({
 app.use(cds);
 ```
-После этого иконку можно использовать в шаблонах:
+After that, use the icon in templates:
 ```html
 <template>
@@ -930,19 +1226,25 @@ app.use(cds);
 </template>
 ```
-## Установка наборов иконок через UnoCSS
+## Installing icon packs through UnoCSS
-Дизайн-система CDS интегрируется с [UnoCSS Preset Icons](https://unocss.dev/presets/icons), который поддерживает все наборы иконок, доступные на [Iconify](https://icon-sets.iconify.design/).
+CDS integrates with [UnoCSS Preset Icons](https://unocss.dev/presets/icons), which
+supports every icon pack available on [Iconify](https://icon-sets.iconify.design/).
-Иконки подключаются с tree-shaking, поэтому в итоговый CSS-бандл попадают только те иконки, которые вы действительно используете. Вы можете зарегистрировать сразу несколько наборов и свободно комбинировать иконки из любого из них в своих компонентах.
+Icons are tree-shaken, so only the icons you actually use end up in the final CSS
+bundle. You can register several packs at once and freely mix icons from any of
+them in your components.
-### Наборы иконок
+### Icon packs
-Для перечисленных ниже наборов в CDS подготовлены iconset'ы с alias mappings — псевдонимами для иконок, которые используют компоненты CDS (например, чекбоксы, выпадающие списки, радио-кнопки и т. д.).
-В качестве набора по умолчанию (`defaultSet`) нужно выбрать один из них; при необходимости alias mappings можно переопределить.
-Дополнительные наборы — уже без алиасов — можно подключить параллельно и свободно использовать в своих шаблонах.
+For the packs listed below, CDS ships iconsets with alias mappings — aliases for
+the icons CDS components use (checkboxes, dropdowns, radio buttons and so on).
+Pick one of them as the default pack (`defaultSet`); the alias mappings can be
+overridden if needed.
+Additional packs — without aliases — can be plugged in alongside and used freely
+in your own templates.
-| Библиотека иконок                                                | Iconify package        | Импорт iconset'а                                          | Set name   |
+| Icon library                                                     | Iconify package        | Iconset import                                            | Set name   |
 |------------------------------------------------------------------|------------------------|-----------------------------------------------------------|------------|
 | [Remix Icon](https://remixicon.com/)                             | `@iconify-json/ri`     | `@central-design-system/components/iconsets/remix`        | `ri`       |
 | [Phosphor Icons](https://phosphoricons.com/)                     | `@iconify-json/ph`     | `@central-design-system/components/iconsets/phosphor`     | `phosphor` |
@@ -950,26 +1252,28 @@ app.use(cds);
 | [Carbon](https://carbondesignsystem.com/elements/icons/library/) | `@iconify-json/carbon` | `@central-design-system/components/iconsets/carbon`       | `carbon`   |
 | [Material Design Icons](https://pictogrammers.com/library/mdi/)  | `@iconify-json/mdi`    | `@central-design-system/components/iconsets/mdi`          | `mdi`      |
-Каждый модуль экспортирует объект с именем набора: `icons` (сам набор для `sets`) и `aliases` (псевдонимы для `aliases`).
+Each module exports an object named after the pack: `icons` (the pack itself, for
+`sets`) and `aliases` (the aliases, for `aliases`).
-Установите нужный набор из таблицы выше:
+Install the pack you need from the table above:
 ```bash
 npm install @iconify-json/ri
 ```
-> Иконки из таблицы работают через UnoCSS, поэтому сначала нужно установить и настроить сам UnoCSS.
-> Подробнее об этом — в [официальной документации](https://unocss.dev/integrations/).
+> Icons from the table run through UnoCSS, so you have to install and configure
+> UnoCSS first. See the [official documentation](https://unocss.dev/integrations/)
+> for details.
-Ниже — пример интеграции в проект на Vite.
+Here is an example integration in a Vite project.
-1. Установите UnoCSS в dev-зависимости (см. [интеграцию с Vite](https://unocss.dev/integrations/vite)):
+1. Install UnoCSS as a dev dependency (see the [Vite integration](https://unocss.dev/integrations/vite)):
 ```bash
 npm install -D unocss
 ```
-2. Подключите плагин UnoCSS в конфигурации Vite:
+2. Add the UnoCSS plugin to your Vite config:
 ```ts
 // vite.config.ts
@@ -983,7 +1287,7 @@ export default defineConfig({
 })
 ```
-3. Создайте в корне проекта файл **unocss.config.ts**:
+3. Create an **unocss.config.ts** file in the project root:
 ```ts
 // unocss.config.ts
@@ -1000,12 +1304,14 @@ export default defineConfig({
 })
 ```
-> Больше ничего в `unocss.config.ts` дописывать не нужно: iconset'ы CDS помечены маркером `@unocss-include`,
-> поэтому UnoCSS сканирует их сам — несмотря на то, что они лежат в `node_modules` и это `.js`-файлы,
-> которые по умолчанию не попадают в `content.pipeline.include`.
+> Nothing else needs to go into `unocss.config.ts`: CDS iconsets carry the
+> `@unocss-include` marker, so UnoCSS scans them on its own — even though they
+> live in `node_modules` as `.js` files, which are not part of
+> `content.pipeline.include` by default.
-4. Передайте набор иконок в функцию `createCds()`.
-В примере используется набор **[Remix](https://remixicon.com/)**, но его можно заменить любым другим из таблицы выше:
+4. Pass the icon pack to `createCds()`.
+The example uses the **[Remix](https://remixicon.com/)** pack, but you can swap it
+for any other pack from the table above:
 ```ts
 import { createCds } from '@central-design-system/components';
@@ -1024,21 +1330,26 @@ const cds = createCds({
 app.use(cds);
 ```
-> Импортируйте набор подпутём `@central-design-system/components/iconsets/<набор>`, а не из общего
-> объекта `iconsets`. Общий объект ссылается сразу на все наборы и не тришейкается — в бандл попадут
-> лишний JS и CSS всех пяти наборов (≈370 КБ против ≈70 КБ у одного).
+> Import the pack through the `@central-design-system/components/iconsets/<pack>`
+> subpath, not from the shared `iconsets` object. The shared object references all
+> packs at once and is not tree-shaken — you would ship the JS and CSS of all five
+> packs (≈370 KB instead of ≈70 KB for a single one).
-После этого можно выбрать любую иконку из набора — например, [ri:settings-3-line](https://icon-sets.iconify.design/ri/?icon-filter=settings-3-line) — и использовать её в шаблонах:
+After that, pick any icon from the pack — for example
+[ri:settings-3-line](https://icon-sets.iconify.design/ri/?icon-filter=settings-3-line) —
+and use it in templates:
 ```html
 <CdsButton icon="i-ri:settings-3-line" />
 ```
-> UnoCSS использует для иконок префикс `i-`. CDS использует тот же префикс и уже настраивает с ним свои алиасы — не меняйте его, иначе алиасы из CDS перестанут работать.
+> UnoCSS uses the `i-` prefix for icons. CDS uses the same prefix and already
+> configures its aliases with it — don't change it, or the CDS aliases will stop
+> working.
-## Legacy-набор иконок из CDS v3
+## Legacy icon pack from CDS v3
-Если нужен полный набор иконок из CDS v3, подключите его так:
+If you need the full icon pack from CDS v3, plug it in like this:
 ```bash
 npm install @central-design-system/icons
@@ -1056,16 +1367,21 @@ app.use(cds);
 ---
+---
+sourceHash: 2d02d03da0e4d6f0fcb171775b7b88784a216ac0
+---
 # Display & Platform
-Central Design System предоставляет реактивную информацию об **экране** (брейкпоинты,
-размеры вьюпорта, мобильный режим) и о **платформе** (браузер, ОС, тип устройства) через
-один composable — `useDisplay`. Брейкпоинты используются одинаково в JavaScript и в стилях
-(SCSS-миксины `cds-breakpoint-*`), поэтому адаптивная логика в скрипте и CSS совпадает.
+Central Design System exposes reactive information about the **screen**
+(breakpoints, viewport size, mobile mode) and the **platform** (browser, OS,
+device type) through a single composable — `useDisplay`. Breakpoints are the same
+in JavaScript and in styles (the `cds-breakpoint-*` SCSS mixins), so responsive
+logic in script and CSS always agrees.
-## Точки преломления (breakpoints)
+## Breakpoints
-| Брейкпоинт | Диапазон ширины (px) | Стартовая ширина | Колонки сетки |
+| Breakpoint | Width range (px) | Start width | Grid columns |
 | --- | --- | --- | --- |
 | `xs` | `0 … 671` | `0` | 4 |
 | `sm` | `672 … 1055` | `672` | 8 |
@@ -1073,45 +1389,46 @@ Central Design System предоставляет реактивную инфор
 | `lg` | `1312 … 1583` | `1312` | 16 |
 | `xl` | `1584 … ∞` | `1584` | 16 |
-Источник значений один:
+The values have a single source:
 - JS — `defaultDisplayOptions.thresholds` (`src/composables/useDisplay/internal/useDisplay.constants.ts`);
 - SCSS — `$grid-breakpoints` (`src/styles/utilities/grid/_config.scss`).
-## В JavaScript — `useDisplay`
+## In JavaScript — `useDisplay`
-Composable `useDisplay` возвращает реактивное состояние экрана и платформы. Он работает
-«из коробки», если приложение инициализировано через `createCds` (он провайдит `cds:display`).
+The `useDisplay` composable returns the reactive state of the screen and the
+platform. It works out of the box as long as the application is initialized
+through `createCds` (which provides `cds:display`).
 ```ts
 import { useDisplay } from '@central-design-system/components';
 const display = useDisplay();
-display.width.value; // текущая ширина вьюпорта, px
+display.width.value; // current viewport width, px
 display.name.value; // 'xs' | 'sm' | 'md' | 'lg' | 'xl'
-display.mobile.value; // true, если width < mobileBreakpoint (по умолчанию 'sm')
+display.mobile.value; // true when width < mobileBreakpoint ('sm' by default)
 ```
-### Доступные флаги
+### Available flags
-| Флаг | Значение |
+| Flag | Meaning |
 | --- | --- |
-| `xs` / `sm` / `md` / `lg` / `xl` | активен ровно один — текущий брейкпоинт |
-| `smUp` / `mdUp` / `lgUp` / `xlUp` | ширина ≥ стартовой ширины брейкпоинта («и выше») |
-| `smDown` / `mdDown` / `lgDown` / `xlDown` | брейкпоинт и всё, что ниже («и ниже») |
-| `name` | имя текущего брейкпоинта |
-| `mobile` | мобильный режим (по `mobileBreakpoint`) |
-| `mobileBreakpoint` | текущий порог мобильного режима |
-| `width` / `height` | размеры вьюпорта, px |
-| `thresholds` | текущая карта порогов |
-| `platform` | флаги платформы/браузера (см. [Платформа](#платформа-platform)) |
-| `update()` | принудительно пересчитать размеры и платформу |
-Например, `mdUp` истинно при `width ≥ 1056`, а `smDown` — при `width < 1056`
-(то есть охватывает диапазоны `xs` и `sm`).
-### Пример в компоненте
+| `xs` / `sm` / `md` / `lg` / `xl` | exactly one is active — the current breakpoint |
+| `smUp` / `mdUp` / `lgUp` / `xlUp` | width ≥ the breakpoint's start width ("and up") |
+| `smDown` / `mdDown` / `lgDown` / `xlDown` | the breakpoint and everything below it ("and down") |
+| `name` | name of the current breakpoint |
+| `mobile` | mobile mode (based on `mobileBreakpoint`) |
+| `mobileBreakpoint` | current mobile mode threshold |
+| `width` / `height` | viewport size, px |
+| `thresholds` | current threshold map |
+| `platform` | platform/browser flags (see [Platform](#platform)) |
+| `update()` | force a recalculation of size and platform |
+For example, `mdUp` is true when `width ≥ 1056`, and `smDown` when `width < 1056`
+(that is, it covers the `xs` and `sm` ranges).
+### Example in a component
 ```tsx
 import { useDisplay } from '@central-design-system/components';
@@ -1125,19 +1442,20 @@ defineRender(() => (
 ));
 ```
-### Мобильный режим на уровне пропсов
+### Mobile mode at the prop level
-Компоненты, подмешивающие `defineDisplayProps()`, принимают пропсы `mobile` и
-`mobileBreakpoint` — ими можно переопределить порог мобильного режима локально:
+Components that mix in `defineDisplayProps()` accept the `mobile` and
+`mobileBreakpoint` props — use them to override the mobile mode threshold
+locally:
 ```html
-<!-- Мобильный режим включится при ширине < 1056px (md), а не по глобальному 'sm' -->
+<!-- Mobile mode kicks in below 1056px (md) instead of the global 'sm' -->
 <CdsSlideGroup mobile-breakpoint="md" />
 ```
-### Переопределение порогов глобально
+### Overriding the thresholds globally
-Пороги и `mobileBreakpoint` настраиваются при инициализации:
+Thresholds and `mobileBreakpoint` are configured at initialization:
 ```ts
 import { createCds } from '@central-design-system/components';
@@ -1150,75 +1468,79 @@ app.use(createCds({
 }));
 ```
-> Если вы меняете пороги в JS — синхронизируйте их и в SCSS (`$grid-breakpoints`),
-> иначе адаптивность в скрипте и стилях разойдётся.
+> If you change the thresholds in JS, keep them in sync in SCSS
+> (`$grid-breakpoints`) — otherwise responsiveness in script and styles will
+> drift apart.
-## В SCSS — миксины `cds-breakpoint-*`
+## In SCSS — the `cds-breakpoint-*` mixins
-Миксины подключаются из публичной точки входа:
+The mixins come from a public entry point:
 ```scss
 @use '@central-design-system/components/styles/breakpoints' as breakpoint;
 ```
-> В чистом Dart Sass (без бандлера) используйте pkg-схему и Node-импортер:
+> In plain Dart Sass (without a bundler), use the pkg scheme and the Node
+> importer:
 > `@use 'pkg:@central-design-system/components/styles/breakpoints' as breakpoint;`.
-### `cds-breakpoint-up($name)` — «и выше»
+### `cds-breakpoint-up($name)` — "and up"
 ```scss
 .card {
   display: none;
-  // применится при min-width: 1056px (md и выше)
+  // applies at min-width: 1056px (md and up)
   @include breakpoint.cds-breakpoint-up(md) {
     display: block;
   }
 }
 ```
-### `cds-breakpoint-down($name)` — «и ниже»
+### `cds-breakpoint-down($name)` — "and down"
 ```scss
 .sidebar {
-  // применится при max-width: 1055.98px — то есть на sm и xs
+  // applies at max-width: 1055.98px — that is, on sm and xs
   @include breakpoint.cds-breakpoint-down(sm) {
     display: none;
   }
 }
 ```
-`cds-breakpoint-down('<name>')` покрывает сам брейкпоинт **и все, что ниже**
-(верхняя граница — старт следующего брейкпоинта минус `0.02px`). Для крупнейшего
-брейкпоинта (`xl`) media query не генерируется — «xl и ниже» это все ширины.
+`cds-breakpoint-down('<name>')` covers the breakpoint itself **and everything
+below it** (the upper bound is the start of the next breakpoint minus `0.02px`).
+No media query is generated for the largest breakpoint (`xl`) — "xl and down" is
+every width.
-### `cds-breakpoint-between($lower, $upper)` — диапазон
+### `cds-breakpoint-between($lower, $upper)` — a range
 ```scss
 .banner {
-  // min-width: 672px и max-width: 1056px
+  // min-width: 672px and max-width: 1056px
   @include breakpoint.cds-breakpoint-between(sm, md) {
     padding: 16px;
   }
 }
 ```
-Оба миксина также принимают число вместо имени: `cds-breakpoint-up(900px)`.
+Both mixins also accept a number instead of a name: `cds-breakpoint-up(900px)`.
-### Прочие миксины и функции
+### Other mixins and functions
-- `cds-breakpoint($name)` — алиас `cds-breakpoint-up`.
-- `cds-largest-breakpoint` — media query для самого крупного брейкпоинта.
-- `breakpoint-next($name)` / `breakpoint-prev($name)` — соседний брейкпоинт.
-- `is-smallest-breakpoint($name)` — является ли `$name` наименьшим.
-- `largest-breakpoint-name()` — имя самого крупного брейкпоинта.
+- `cds-breakpoint($name)` — an alias for `cds-breakpoint-up`.
+- `cds-largest-breakpoint` — media query for the largest breakpoint.
+- `breakpoint-next($name)` / `breakpoint-prev($name)` — the neighboring breakpoint.
+- `is-smallest-breakpoint($name)` — whether `$name` is the smallest one.
+- `largest-breakpoint-name()` — name of the largest breakpoint.
-## Соответствие JS ↔ CSS
+## JS ↔ CSS correspondence
-Флаги `useDisplay` и media query миксинов покрывают одинаковые диапазоны ширины —
-это позволяет писать согласованную адаптивную логику в скрипте и стилях.
+The `useDisplay` flags and the mixins' media queries cover identical width
+ranges — that's what lets you write consistent responsive logic in script and
+styles.
-| JS (`useDisplay`) | SCSS-миксин | Диапазон ширины |
+| JS (`useDisplay`) | SCSS mixin | Width range |
 | --- | --- | --- |
 | `smUp` | `cds-breakpoint-up(sm)` | `≥ 672` |
 | `mdUp` | `cds-breakpoint-up(md)` | `≥ 1056` |
@@ -1227,19 +1549,20 @@ app.use(createCds({
 | `smDown` | `cds-breakpoint-down(sm)` | `< 1056` |
 | `mdDown` | `cds-breakpoint-down(md)` | `< 1312` |
 | `lgDown` | `cds-breakpoint-down(lg)` | `< 1584` |
-| `xlDown` | `cds-breakpoint-down(xl)` | все ширины |
+| `xlDown` | `cds-breakpoint-down(xl)` | every width |
-> **Важно (миграция с CDS 3).** В CDS 3 семантика `cds-breakpoint-down` в SCSS
-> отличалась от JS: `down('sm')` означало «строго ниже `sm`» (только `xs`), тогда как
-> `smDown` в JS — «`sm` и ниже». В CDS 4 CSS выровнен под JS: `down('<name>')` теперь
-> всегда «`<name>` и ниже». Если вы переносите стили из CDS 3 — сдвиньте аргумент
-> `down()` на один вниз (старый `down('md')` ⇒ новый `down('sm')`).
-> См. Migration Guide.
+> **Important (migrating from CDS 3).** In CDS 3 the semantics of
+> `cds-breakpoint-down` in SCSS differed from JS: `down('sm')` meant "strictly
+> below `sm`" (only `xs`), whereas `smDown` in JS means "`sm` and down". In CDS 4
+> the CSS is aligned with JS: `down('<name>')` now always means "`<name>` and
+> down". If you are porting styles from CDS 3, shift the `down()` argument one
+> step down (old `down('md')` ⇒ new `down('sm')`).
+> See the Migration Guide.
-## Платформа (platform)
+## Platform
-`useDisplay().platform` — реактивный объект с флагами устройства, ОС и браузера.
-Определение основано на `navigator.userAgent` и поддержке касаний.
+`useDisplay().platform` is a reactive object with device, OS and browser flags.
+Detection is based on `navigator.userAgent` and touch support.
 ```ts
 import { useDisplay } from '@central-design-system/components';
@@ -1247,33 +1570,33 @@ import { useDisplay } from '@central-design-system/components';
 const { platform } = useDisplay();
 if (platform.value.ios) {
-  // особое поведение для iOS
+  // special behavior for iOS
 }
 const isTouchDevice = platform.value.touch;
 ```
-### Поля объекта `platform`
+### Fields of the `platform` object
-Все поля — `boolean`.
+Every field is a `boolean`.
-| Поле | Значение |
+| Field | Meaning |
 | --- | --- |
-| `android` | устройство на Android |
-| `ios` | устройство на iOS (iPhone / iPad / iPod) |
-| `cordova` | приложение работает в Cordova |
-| `electron` | приложение работает в Electron |
-| `chrome` | браузер Chrome |
-| `edge` | браузер Edge |
-| `firefox` | браузер Firefox |
-| `opera` | браузер Opera |
-| `win` | ОС Windows |
-| `mac` | ОС macOS |
-| `linux` | ОС Linux |
-| `touch` | устройство поддерживает касания |
-| `ssr` | значение вычислено на сервере (SSR) |
-### Пример: класс на корне приложения
+| `android` | an Android device |
+| `ios` | an iOS device (iPhone / iPad / iPod) |
+| `cordova` | the app runs in Cordova |
+| `electron` | the app runs in Electron |
+| `chrome` | Chrome browser |
+| `edge` | Edge browser |
+| `firefox` | Firefox browser |
+| `opera` | Opera browser |
+| `win` | Windows OS |
+| `mac` | macOS |
+| `linux` | Linux OS |
+| `touch` | the device supports touch |
+| `ssr` | the value was computed on the server (SSR) |
+### Example: a class on the app root
 ```tsx
 import { useDisplay } from '@central-design-system/components';
@@ -1293,15 +1616,1151 @@ defineRender(() => (
 ));
 ```
-> **Осторожно с user-agent sniffing.** Определение браузера/ОС по `userAgent`
-> ненадёжно (строку можно подменить, а новые браузеры — не распознаться). Используйте
-> `platform` для прогрессивных улучшений (например, специфичные фиксы под iOS Safari),
-> а не как единственное условие доступа к функциональности. Для фич-детекта
-> предпочитайте проверку возможностей (`'ontouchstart' in window` и т. п.).
+> **Careful with user-agent sniffing.** Detecting the browser or OS from
+> `userAgent` is unreliable (the string can be spoofed, and new browsers may not
+> be recognized). Use `platform` for progressive enhancement — say, a fix
+> specific to iOS Safari — not as the only gate in front of a feature. For
+> feature detection, prefer capability checks (`'ontouchstart' in window` and the
+> like).
 ### SSR
-При серверном рендеринге `userAgent` недоступен, поэтому `platform.ssr === true`, а
-остальные флаги — `false`. После гидрации значения можно пересчитать вызовом
-`display.update()` (пересчитывает и размеры, и платформу). Начальные размеры для SSR
-задаются вторым аргументом `createDisplay(options, ssr)` / опцией `ssr` в `createCds`.
+During server-side rendering `userAgent` is unavailable, so `platform.ssr === true`
+and the rest of the flags are `false`. After hydration the values can be
+recalculated by calling `display.update()` (which recalculates both size and
+platform). Initial sizes for SSR are set through the second argument of
+`createDisplay(options, ssr)` or the `ssr` option in `createCds`.
+---
+---
+sourceHash: 49864e870f2f989420a5ebf7ffc7eb1a3458124a
+---
+# Global configuration
+CDS 4 lets you set default prop values — globally, for a specific component, or
+only inside a given subtree. You describe "what buttons look like in our product"
+once and stop repeating the same props in every template.
+## Setup
+Default values are set through the `defaults` option of `createCds`. The `global`
+key affects every component; a key named after a component affects only that one.
+```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);
+```
+**Important.** Props in `defaults` are written in camelCase: `hideDetails`, not
+`hide-details`.
+A component key is its name from `defineOptions({ name })` — `CdsButton`,
+`CdsTextInput`, `CdsCardActions` and so on. Subcomponent names (`CdsCardTitle`,
+`CdsListItem`) work exactly like root component names.
+### Resolution order
+For every prop, CDS takes the first value that applies:
+1. the prop explicitly passed in the template;
+2. `defaults.<ComponentName>.<prop>` from the nearest defaults context;
+3. `defaults.global.<prop>`;
+4. the default value declared in the component itself.
+An explicitly passed prop always wins — defaults can never override the template.
+### Changing defaults at runtime
+`createCds` returns an instance whose defaults live in a reactive ref. You can
+change them on the fly — every mounted component recalculates:
+```ts
+const cds = createCds({ components, directives });
+// for example, turn on compact mode based on a user setting
+cds.defaults.value = {
+  ...cds.defaults.value,
+  global: { size: 'sm' }
+};
+```
+## Contextual defaults
+Defaults can be set for components nested inside another component. For example,
+to make every button inside a card secondary by default:
+```ts
+createCds({
+  defaults: {
+    CdsCard: {
+      CdsButton: { appearance: 'secondary' }
+    }
+  }
+});
+```
+The rule is simple: a capitalized key is the name of a nested component, a
+lowercase key is a prop of the current component. Nesting is not limited to one
+level:
+```ts
+createCds({
+  defaults: {
+    CdsCard: {
+      CdsCardActions: {
+        CdsButton: { appearance: 'tertiary', size: 'sm' }
+      }
+    }
+  }
+});
+```
+The library uses the same mechanism internally so that grouping components can
+hand their settings down to their children:
+- `CdsButtonGroup` sets the `appearance`, `color`, `baseColor`, `size` props on nested `CdsButton`s;
+- `CdsTagGroup` sets the `color`, `activeColor`, `disabled`, `filter` props on `CdsTag`;
+- `CdsSelectionControlGroup` passes settings to the controls, with the target component name
+  set by the `defaultsTarget` prop (`CdsCheckbox`, `CdsRadio` and so on);
+- `CdsTabs`, `CdsSteps`, `CdsList`, `CdsBreadcrumbs`, `CdsButtonToggle`,
+  `CdsExpandablePanels`, `CdsOtpInput` work the same way.
+That's why `<CdsButtonGroup size="sm">` makes every button inside small — you
+don't have to set `size` on each of them.
+## Global class and style
+Besides props, a component's defaults can carry `class` and `style`. It's a
+convenient way to apply product-specific rules to every instance of a component
+without touching the templates:
+```ts
+createCds({
+  defaults: {
+    CdsButton: {
+      class: 'my-button'
+    }
+  }
+});
+```
+Any value Vue accepts works — a string, an object, an array:
+```ts
+createCds({
+  defaults: {
+    CdsButton: {
+      style: [{ textTransform: 'none' }]
+    }
+  }
+});
+```
+Unlike ordinary props, `class` and `style` are not overwritten by the template
+but **merged** with it. So `<CdsButton class="mt-2">` gets both `my-button` and
+`mt-2`.
+**Important.** `class` and `style` only work under a specific component's key. In
+`global` they are ignored.
+## Aliases
+An alias is the same component registered under a different name with its own
+defaults. Aliases are a handy way to assemble "product" variants of components.
+```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'
+    }
+  }
+});
+```
+Aliases are registered globally, so you can use them in templates right away:
+```vue
+<template>
+  <CdsButtonPrimary>Save</CdsButtonPrimary>
+  <CdsButtonDanger class="ml-2">Delete</CdsButtonDanger>
+</template>
+```
+**Important.** An alias does not inherit the base component's defaults. If the
+configuration has `defaults.CdsButton`, it will not apply to `<CdsButtonPrimary>`
+— defaults are looked up by the alias name. Move shared settings into `global` or
+duplicate them under the alias key.
+## Defaults for part of the application
+To set defaults for a subtree rather than globally, use the
+`CdsDefaultsProvider` component. The Controls panel in Storybook is built on it
+too: the values from the panel are applied to the example's components as
+defaults.
+```vue
+<script setup lang="ts">
+import { CdsButton, CdsDefaultsProvider } from '@central-design-system/components';
+</script>
+<template>
+  <CdsDefaultsProvider :defaults="{ CdsButton: { appearance: 'tertiary', size: 'sm' } }">
+    <CdsButton>Small tertiary button</CdsButton>
+  </CdsDefaultsProvider>
+</template>
+```
+| Prop       | Type                | Purpose                                                                                      |
+| ---------- | ------------------- | -------------------------------------------------------------------------------------------- |
+| `defaults` | `DefaultsOptions`   | Defaults for the subtree; merged with the inherited ones by default                            |
+| `scoped`   | `boolean`           | Don't mix with the parent defaults — only the ones set here apply                              |
+| `reset`    | `number \| string`  | Go N levels up the defaults chain                                                              |
+| `root`     | `boolean \| string` | Fall back to the root defaults from `createCds`; with a string — to a named group inside them  |
+| `disabled` | `boolean`           | Provide nothing — the subtree gets the parent defaults as they are                             |
+The typical use for `scoped` is an "island" inside someone else's environment:
+enclosing groups (`CdsButtonGroup`, say) should not impose their settings on your
+block.
+## Your own components
+Your application's own components can take part in the defaults system too. Pass
+their props through `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>I am {{ props.foo }}</div>
+</template>
+```
+`useDefaults` takes two arguments, both optional:
+- `props` — the props object returned by `defineProps`;
+- `name` — the component name used to look up the key in `defaults`. If omitted,
+  the name from `defineOptions({ name })` is used, and failing that, the file name.
+Now the component is configurable from the shared configuration:
+```ts
+createCds({
+  defaults: {
+    MyComponent: { foo: 'bar' }
+  }
+});
+```
+**Important.** In the template, refer to `props.foo`, not `foo`. `useDefaults`
+returns a proxy over the props, and destructured `defineProps` variables bypass
+it:
+```diff
+-<div>I am {{ foo }}</div>
++<div>I am {{ props.foo }}</div>
+```
+### Nested defaults in your own components
+To make your component hand defaults down to its children (the way
+`CdsButtonGroup` does), just call `useDefaults()` with no arguments — the nested
+keys from its `defaults` section go into the child context:
+```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' }
+    }
+  }
+});
+```
+If the children's defaults depend on the component's props, use `provideDefaults`
+directly:
+```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 — a configuration preset
+If several applications need the same set of options, extract it into a
+`blueprint`: a plain `createCds` options object that the rest of the
+configuration is layered on top of.
+```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,
+  // overrides the value from the blueprint
+  defaults: {
+    CdsButton: { size: 'sm' }
+  }
+});
+```
+Options are merged deeply (`mergeDeep`), so in the example above the buttons keep
+`appearance: 'secondary'` from the preset and gain `size: 'sm'`.
+---
+---
+sourceHash: 26c790bd53cd55729b9902cf5d1032b5c6457f6b
+---
+# Internationalization (i18n)
+CDS components carry texts of their own: "No data available" in a select, the
+table filter labels, the `aria-label` of a close button, the file counter. They
+all go through the built-in localization layer, so you can translate them into
+another language, override a single string for your product, or switch languages
+on the fly — without rewriting components.
+The library ships two dictionaries — Russian and English. `ru` is active by
+default, so out of the box everything is in Russian.
+## Setup
+The locale is configured through the `locale` option of `createCds`. Switching to
+the built-in English is a one-liner — you don't need to pass any dictionaries:
+```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);
+```
+Languages the library doesn't have are added as a dictionary in `messages`:
+```ts
+import de from './locales/cds-de';
+createCds({
+  components,
+  directives,
+  locale: {
+    locale: 'de',
+    fallback: 'en',
+    messages: { de }
+  }
+});
+```
+| Option             | Type                      | Purpose                                                                       |
+| ------------------ | ------------------------- | ----------------------------------------------------------------------------- |
+| `locale`           | `string`                  | Active language; `ru` (default) and `en` are available out of the box          |
+| `fallback`         | `string`                  | Language a string is taken from when the active one lacks it; `ru` by default  |
+| `messages`         | `LocaleMessages`          | Dictionaries of extra languages; a same-named built-in dictionary is replaced entirely |
+| `decimalSeparator` | `string`                  | Decimal separator; derived from the active locale by default                   |
+| `rtl`              | `Record<string, boolean>` | Map of right-to-left languages (see [RTL](#rtl))                               |
+| `adapter`          | `LocaleInstance`          | Your own translation engine instead of the built-in one (see [Custom adapter](#custom-adapter)) |
+The built-in dictionaries are available to you as well — they live in the
+`locales` export. Use them as a base for your own language or to fix a couple of
+strings:
+```ts
+import { locales } from '@central-design-system/components';
+locales.ru; // Russian dictionary
+locales.en; // English dictionary
+```
+For the full set of keys, see [Message keys](#message-keys).
+## How components get their text
+Component strings are keys prefixed with `$cds.` that the library runs through a
+translation function. Some of the keys are declared as default prop values, so
+you can see them in the API: `text` on `CdsFileUpload` is `$cds.fileUpload.browse`,
+`closeLabel` on `CdsNotification` is `$cds.close`, `noDataText` on `CdsSelect` is
+`$cds.noDataText`.
+That gives you three ways to change a text.
+**Switch the whole language** — with the `locale` option:
+```ts
+createCds({ locale: { locale: 'en' } });
+```
+**Change wording across the product** — with a dictionary on top of the built-in
+one:
+```ts
+import { createCds, locales } from '@central-design-system/components';
+createCds({
+  locale: {
+    messages: {
+      en: { ...locales.en, noDataText: 'Nothing found' }
+    }
+  }
+});
+```
+**Important.** A language dictionary is replaced entirely, not merged key by key.
+Without the `...locales.en` spread, the English locale is left with a single key
+and the rest of the strings turn into their own keys (`$cds.close` instead of
+"Close"). Spread nested sections separately:
+`table: { ...locales.en.table, emptyText: '…' }`.
+**Change one label in one place** — with a prop:
+```vue
+<CdsSelect :items="items" no-data-text="No matching suppliers" />
+```
+The same prop can be set as the default for every instance of the component — see
+global configuration:
+```ts
+createCds({
+  defaults: {
+    CdsSelect: { noDataText: 'Nothing found' }
+  }
+});
+```
+The translation function also accepts plain text: a string without the `$cds.`
+prefix is returned as is, with the parameters substituted. That's how props with
+a localizable value work the same way with a key and with a ready-made phrase.
+If a key is missing from both the active locale and the `fallback`, the component
+shows the key itself, and in dev mode a
+`[CDS: useLocale] Translation key … not found` warning appears in the console.
+## Switching the language at runtime
+`createCds` returns an instance whose locale lives in reactive refs — to switch
+languages, just write to `current`:
+```ts
+const cds = createCds({ components, directives });
+// for example, following the user's choice in profile settings
+cds.locale.current.value = 'en';
+```
+Inside components, the `useLocale` composable does the same:
+```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>
+```
+Every mounted component recalculates its strings on its own — no page reload
+needed.
+## A locale for part of the application
+A single subtree can get its own language — for example, an English-language
+widget inside a Russian interface. Call `provideLocale` in a wrapper component:
+it takes the locale from the context, applies the props you passed and provides
+the result to the children.
+```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>
+```
+Props you don't pass are inherited from the parent locale, so a wrapper with just
+a `locale` loses neither the `fallback` nor the dictionaries.
+## useLocale
+The composable hands you the current locale and its functions — use it in your
+own components so their texts live in the same dictionaries as the CDS ones.
+```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>
+```
+| Property           | Type                                           | Purpose                                                       |
+| ------------------ | ---------------------------------------------- | ------------------------------------------------------------- |
+| `t`                | `(key: string, ...params: unknown[]) => string` | Translation of a `$cds.…` key with parameter substitution      |
+| `n`                | `(value: number) => string`                    | Number formatting for the active locale                        |
+| `current`          | `Ref<string>`                                  | Active language; writing to it switches the language           |
+| `fallback`         | `Ref<string>`                                  | Fallback language                                              |
+| `messages`         | `Ref<LocaleMessages>`                          | Dictionaries; can be extended at runtime                       |
+| `decimalSeparator` | `ShallowRef<string>`                           | Decimal separator of the active locale                         |
+Parameters in strings are numbered — `{0}`, `{1}`:
+```ts
+const { t } = useLocale();
+t('$cds.carousel.delimiter', 3, 8); // "Slide 3 of 8"
+t('Days left: {0}', 5); // "Days left: 5"
+```
+Under the hood `n` is `Intl.NumberFormat` with the active locale and the
+`fallback`, so group and decimal separators come from the browser. The library
+derives `decimalSeparator` from the same locale (`,` for `ru`, `.` for `en`); if
+your product uses a different one, set it explicitly in `createCds`.
+## Dates
+Month and weekday names live in separate date locales, shipped by `ru` and `en`.
+Date and time components pick the date locale by the active language, so after
+`current.value = 'en'` the calendar switches by itself.
+A single component gets its language from the `locale` prop — `CdsDatePicker`,
+`CdsDateInput` and `CdsTimePicker` all have it:
+```vue
+<CdsDatePicker v-model="value" locale="en" :first-day-of-week="0" header />
+```
+The prop accepts not only a language name but also your own date locale object
+(type `TDateLocale`) — that's how you plug in a language the library doesn't
+have. The built-in date locales, for reference and reuse, live in the same
+`locales` export: `locales.ruDate`, `locales.enDate` and the `locales.dateLocales`
+map.
+```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" />
+```
+## Table
+`CdsTable` builds its labels from the `$cds.table.*` keys, but it also accepts a
+pinpoint override through the `locale` prop — which replaces only the strings you
+pass:
+```vue
+<CdsTable :columns="columns" :data="data" :locale="{ emptyText: 'No requests yet' }" />
+```
+## RTL
+Right-to-left languages are described by the `rtl` map: the key is the language,
+the value is the direction.
+```ts
+createCds({
+  locale: {
+    locale: 'ar',
+    messages: { ar },
+    rtl: { ar: true }
+  }
+});
+```
+Components read the direction through `useRtl` and flip whatever depends on the
+axis: the side menus and tooltips open to, the pagination arrows, the cell order
+in `CdsOtpInput`, the fill of `CdsProgressBar`. Spacing and borders in the styles
+are mostly written with logical properties (`margin-inline`, `inset-inline`) and
+are mirrored by the browser itself — but the design system does not claim full
+RTL support yet, and some places will need polishing on your side.
+The library does not set the direction attribute for you — put it on the
+application root yourself:
+```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` gives you `isRtl` and `rtlClasses` — a ready `cds-locale--is-rtl` /
+`cds-locale--is-ltr` class for your own styles.
+## Custom adapter
+If your application already has an i18n library, hand the translations over to
+it: the `adapter` option accepts any object implementing the `LocaleInstance`
+interface. In that case `messages`, `locale` and `fallback` from `createCds` are
+unused — your engine becomes the source of truth, and the CDS strings live in the
+application's shared dictionaries under the `$cds` key.
+```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: 'en',
+  messages: {
+    en: {
+      $cds: { noDataText: 'No data available' },
+      profile: { title: 'Profile' }
+    }
+  }
+});
+const cds = createCds({
+  components,
+  directives,
+  locale: {
+    adapter: createVueI18nAdapter(i18n)
+  }
+});
+```
+Required members of `LocaleInstance`: `name` (that's how the adapter is
+recognized), `current`, `fallback`, `messages`, `decimalSeparator`, `t`, `n` and
+`provide` — a factory for a nested locale, used by `provideLocale`. If you don't
+need "a locale in a subtree", `provide` can return the same instance, as in the
+example above.
+## Message keys
+The built-in English dictionary is a template for translating into a new
+language. Copy it, translate the values and pass it to `messages` under your
+language's key; the Russian version is available as `locales.ru`.
+```ts
+export default {
+  badge: 'Badge',
+  noDataText: 'No data available',
+  selectAll: 'Select all',
+  close: 'Close',
+  open: 'Open',
+  dismiss: 'Dismiss',
+  confirmEdit: {
+    ok: 'OK',
+    cancel: 'Cancel'
+  },
+  carousel: {
+    prev: 'Previous slide',
+    next: 'Next slide',
+    delimiter: 'Slide {0} of {1}'
+  },
+  input: {
+    clear: 'Clear {0}',
+    otp: 'Please enter OTP character',
+    prependAction: '{0} prepended action',
+    appendAction: '{0} appended action'
+  },
+  fileInput: {
+    counter: '{0} files',
+    counterSize: '{0} files ({1} in total)'
+  },
+  fileUpload: {
+    title: 'Drag and drop files here',
+    divider: 'or',
+    browse: 'Browse files'
+  },
+  steps: {
+    prev: 'Back',
+    next: 'Next'
+  },
+  table: {
+    filterTitle: 'Filter menu',
+    filterConfirm: 'OK',
+    filterReset: 'Reset',
+    filterEmptyText: 'No filters',
+    filterCheckAll: 'Select all items',
+    filterSearchPlaceholder: 'Search in filters',
+    emptyText: 'No data',
+    selectAll: 'Select current page',
+    selectInvert: 'Invert current page',
+    selectNone: 'Clear all data',
+    selectionAll: 'Select all data',
+    sortTitle: 'Sort',
+    expand: 'Expand row',
+    collapse: 'Collapse row',
+    triggerDesc: 'Click to sort descending',
+    triggerAsc: 'Click to sort ascending',
+    cancelSort: 'Click to cancel sorting',
+    showed: 'Showed',
+    from: 'from',
+    rowOnPage: 'Row on page'
+  },
+  uploader: {
+    uploading: 'Uploading...',
+    uploadFile: 'Upload file',
+    downloadFile: 'Download file',
+    removeFile: 'Remove file',
+    uploadError: 'Upload error',
+    previewFile: 'Preview file'
+  }
+};
+```
+The dictionary may stay incomplete: missing keys are taken from the `fallback` —
+that is, from Russian by default.
+---
+---
+sourceHash: 16f5caa5227fd7ac98a4d370070985a7094a8a2b
+---
+# Date Utils
+Central Design System includes a set of functions for working with the native JS
+`Date`: mask-based formatting, string parsing, arithmetic, comparison and
+calendar math. You don't need a separate date library (dayjs, date-fns) for
+everyday tasks. The date and time components use the very same functions —
+CdsDateInput, CdsDatePicker,
+CdsTimePicker — so format masks are identical in
+the utilities and in the components.
+The functions accept a `Date`, a timestamp (milliseconds) or a date string,
+return a native `Date` and **never mutate** the arguments you pass — the result
+is always a new object.
+## Setup
+The utilities are exported from the package under the `utils` namespace:
+```ts
+import { utils } from '@central-design-system/components';
+const { formatDate, addToDate } = utils;
+formatDate(new Date(2026, 7, 18), 'DD.MM.YYYY'); // '18.08.2026'
+```
+## Formatting — `formatDate`
+`formatDate(value, mask, dateLocale?)` turns a date into a string using a mask:
+```ts
+const { formatDate } = utils;
+formatDate(new Date(2026, 7, 18, 14, 30), 'DD.MM.YYYY HH:mm'); // '18.08.2026 14:30'
+formatDate(Date.now(), 'D MMM YYYY'); // '18 Авг 2026'
+formatDate(new Date(2026, 7, 18), 'dddd'); // 'Вторник'
+```
+Without a mask, an ISO-like format is used: `YYYY-MM-DDTHH:mm:ss.SSSZ`.
+For an invalid value the function returns `undefined`.
+Month and weekday names come from the Russian date locale by default. To print
+them in another language, pass a date locale as the third argument — the
+built-in ones live in the `locales` export:
+```ts
+import { locales, utils } from '@central-design-system/components';
+utils.formatDate(new Date(2026, 7, 18), 'dddd, D MMMM', locales.enDate);
+// 'Tuesday, 18 August'
+```
+Your own language is plugged in as a `TDateLocale` object — the same fields as
+`locales.ruDate`. See the Internationalization
+guide for more on date locales.
+### Format tokens
+| Unit | Token | Result |
+| --- | --- | --- |
+| Year | `YY` / `YYYY` | `26` / `2026` |
+| Month | `M` / `MM` | `8` / `08` |
+| Month (name) | `MMM` / `MMMM` | `Авг` / `Август` |
+| Quarter | `Q` / `Qo` | `3` / `3rd` |
+| Day of month | `D` / `Do` / `DD` | `18` / `18th` / `18` |
+| Day of year | `DDD` / `DDDD` | `230` / `230` (zero-padded to 3 digits) |
+| Day of week | `d` | `2` (0 — Sunday) |
+| Day of week (name) | `dd` / `ddd` / `dddd` | `Вт` / `Вт` / `Вторник` |
+| Day of week (ISO) | `E` | `2` (1 — Monday, 7 — Sunday) |
+| Week of year | `w` / `ww` | `34` / `34` |
+| Hour (0–23) | `H` / `HH` | `14` / `14` |
+| Hour (1–12) | `h` / `hh` | `2` / `02` |
+| Minute | `m` / `mm` | `30` / `30` |
+| Second | `s` / `ss` | `5` / `05` |
+| Fractions of a second | `S` / `SS` / `SSS` | `1` / `12` / `123` |
+| Time zone | `Z` / `ZZ` | `+03:00` / `+0300` |
+| Meridiem | `A` / `a` / `aa` | `PM` / `pm` / `p.m.` |
+| Unix time | `X` / `x` | seconds / milliseconds |
+Ordinal suffixes (`Do`, `Qo`) are English (`1st`, `2nd`…) regardless of the
+locale.
+Arbitrary text inside a mask is escaped with square brackets:
+```ts
+formatDate(new Date(2026, 7, 18), '[Сегодня] DD.MM'); // 'Сегодня 18.08'
+```
+## Parsing — `extractDate` and `splitDate`
+`extractDate(str, mask, dateLocale?)` parses a string with a mask and returns a
+`Date`:
+```ts
+const { extractDate } = utils;
+extractDate('21.03.1985', 'DD.MM.YYYY'); // Date: 21 March 1985
+extractDate('2019-10-29 23:12', 'YYYY-MM-DD HH:mm'); // Date: 29 October 2019, 23:12
+```
+Month and day names inside the string are recognized through the date locale —
+Russian by default, just like in `formatDate`.
+A non-existent day overflows following the rules of the native `Date`:
+`extractDate('30.02.2024', 'DD.MM.YYYY')` gives 1 March 2024. When you need
+strict input validation, format the result back and compare it with the string:
+```ts
+const strict = (str: string, mask: string) => formatDate(extractDate(str, mask), mask) === str;
+strict('18.08.2026', 'DD.MM.YYYY'); // true
+strict('30.02.2024', 'DD.MM.YYYY'); // false — overflowed into 01.03.2024
+```
+If you don't need a `Date`, `splitDate(str, mask, dateLocale?)` splits the string
+into its parts — an `IRawDate` object with the fields `year`, `month`, `day`,
+`hour`, `minute`, `second`, `millisecond` (anything not found is `null`):
+```ts
+const { splitDate } = utils;
+splitDate('18.08.2026', 'DD.MM.YYYY');
+// { year: 2026, month: 8, day: 18, hour: null, … }
+```
+## Creating and changing
+### `buildDate`
+`buildDate(modified, utc?)` — the current moment with individual parts replaced.
+Handy when you need "now, but at 15:00" or "today, but in 2010":
+```ts
+const { buildDate } = utils;
+buildDate({ year: 2010, day: 5, hour: 15 });
+// current month, minutes and seconds; year 2010, day 5, hour 15
+```
+Supported object fields: `year`, `month` (1–12), `day` (or `date`), `hour`,
+`minute`, `second`, `millisecond`.
+### `adjustDate`
+`adjustDate(date, modified, utc?)` — the same thing, but for an arbitrary date:
+```ts
+const { adjustDate } = utils;
+adjustDate(new Date(2026, 10, 2), { year: 2010, month: 2 });
+// Date: 2 February 2010
+```
+Note that `month` here is 1-based (February is `2`), unlike in the `Date`
+constructor.
+### `addToDate` / `subtractFromDate`
+Add and subtract intervals. The object fields are the same, but they mean "how
+much to add" rather than "what to set":
+```ts
+const { addToDate, subtractFromDate } = utils;
+addToDate(new Date(2026, 2, 7), { day: 7, month: 1 }); // Date: 14 April 2026
+subtractFromDate(new Date(2026, 2, 7), { hour: 24 }); // Date: 6 March 2026
+```
+### `startOfDate` / `endOfDate`
+The start and the end of a period — year, month, day, hour, minute or second:
+```ts
+const { startOfDate, endOfDate } = utils;
+startOfDate(new Date(2026, 7, 18, 14, 30), 'year'); // Date: 1 January 2026, 00:00:00.000
+endOfDate(new Date(2026, 7, 18, 14, 30), 'month'); // Date: 31 August 2026, 23:59:59.999
+```
+Period unit: `'year'`, `'month'`, `'day'`, `'hour'`, `'minute'`, `'second'`
+(the plural form is accepted too).
+## Comparison and ranges
+### `isSameDate`
+Compares dates down to a unit: `'year'` — the year only, `'month'` — month and
+year, `'day'` — the calendar day, and so on. Without a unit, the timestamps are
+compared in full.
+```ts
+const { isSameDate } = utils;
+isSameDate(new Date(2026, 7, 1), new Date(2026, 7, 30), 'month'); // true
+isSameDate(new Date(2026, 7, 1), new Date(2026, 7, 30), 'day'); // false
+```
+### `getDateDiff`
+The difference between two dates in the chosen unit (days by default):
+```ts
+const { getDateDiff } = utils;
+getDateDiff(new Date(2026, 4, 12), new Date(2026, 3, 8)); // 34 (days)
+getDateDiff(new Date(2026, 4, 12), new Date(2026, 3, 8), 'months'); // 1
+```
+### `isBetweenDates` / `getDateBetween`
+`isBetweenDates(date, from, to, opts?)` checks whether a date falls inside a
+range. The bounds are excluded by default; the `inclusiveFrom` and `inclusiveTo`
+options include them, and `onlyDate: true` compares calendar days only, ignoring
+the time:
+```ts
+const { isBetweenDates } = utils;
+isBetweenDates(date, from, to); // strict range
+isBetweenDates(date, from, to, { inclusiveFrom: true, inclusiveTo: true, onlyDate: true });
+```
+`getDateBetween(date, min, max)` clamps a date to a range: it returns the date
+itself if it is inside, otherwise the nearest bound:
+```ts
+const { getDateBetween } = utils;
+getDateBetween(new Date(2025, 0, 1), new Date(2026, 0, 1), new Date(2026, 11, 31));
+// Date: 1 January 2026 — the date is below the minimum, so the min bound came back
+```
+### `getMinDate` / `getMaxDate`
+The smallest and the largest of a set of dates. They return a timestamp (number) —
+wrap it in `new Date()` if you need a date object:
+```ts
+const { getMinDate, getMaxDate } = utils;
+const min = getMinDate(new Date(2026, 6, 24), new Date(2026, 5, 20), new Date(2026, 6, 26));
+new Date(min); // Date: 20 June 2026
+const dates = [/* Date[] */];
+const max = getMaxDate(dates[0], ...dates.slice(1));
+```
+## Calendar
+```ts
+const { getDayOfWeek, getWeekOfYear, getDayOfYear, daysInMonth } = utils;
+getDayOfWeek(new Date(2026, 7, 16)); // 7 — Sunday (ISO: 1 — Monday)
+getWeekOfYear(new Date(2026, 0, 4)); // 1 — ISO week number in the year
+getDayOfYear(new Date(2026, 1, 4)); // 35 — ordinal day in the year
+daysInMonth(new Date(2024, 1, 15)); // 29 — February of a leap year
+```
+## Other
+### `isValidDate`
+Checks whether a value parses into a date:
+```ts
+const { isValidDate } = utils;
+isValidDate('2026-08-18'); // true
+isValidDate('не дата'); // false
+```
+The check is syntactic — it does not catch non-existent calendar days
+(see `splitDate` above).
+### `cloneDate`
+A copy of a date. Useful before handing it to third-party code that might mutate
+the object (CDS utilities themselves never modify their arguments):
+```ts
+const { cloneDate } = utils;
+const copy = cloneDate(original);
+```
+### `inferDateFormat`
+Detects the shape of a value — handy for returning the result in the same form
+the value came in:
+```ts
+const { inferDateFormat } = utils;
+inferDateFormat(new Date()); // 'date'
+inferDateFormat(1787059805000); // 'number'
+inferDateFormat('18.08.2026'); // 'string'
+```