@central-design-system/components 4.0.0-alpha.0 → 4.0.0-alpha.10

package/llms/llms-migration.txt

@@ -1,8 +1,8 @@
-# Central Design System — миграция CDS 3 → CDS 4
+# Central Design System — CDS 3 → CDS 4 migration
 
-> Версия: 4.0.0-alpha.0
-> Полный гайд перехода: breaking-изменения, переименования, deprecations и шаги миграции.
-> Сгенерировано автоматически (`bun run generate:meta` → `bun run generate:llms`). Не редактировать вручную.
+> Version: 4.0.0-alpha.10
+> The full migration guide (currently in Russian): breaking changes, renames, deprecations, and migration steps.
+> Generated automatically (`bun run generate:meta` → `bun run generate:llms`). Do not edit manually.
 
 ---
 
@@ -12,7 +12,7 @@
 Этот документ — **живой** migration guide: записи добавляются по мере появления
 breaking-изменений в alpha/beta релизах CDS 4.
 
-> Версии: CDS 3 — `3.10.1` (стабильная), CDS 4 — `4.0.0-alpha.0` (в разработке).
+> Версии: CDS 3 — `3.10.1` (стабильная), CDS 4 — `4.0.0-alpha.4` (в разработке).
 
 ## Как читать этот документ
 
@@ -408,7 +408,7 @@ import '@central-design-system/components/styles';
 
 ```ts
 // CDS 3
-import '@central-design-system/components/css';
+import '@central-design-system/components/dist/cds.css';
 import { createCds } from '@central-design-system/components';
 
 app.use(createCds());
@@ -423,7 +423,7 @@ app.use(createCds());
 
 ```ts
 // CDS 4 — временно включить легаси-утилиты на период миграции
-import '@central-design-system/components/css';
+import '@central-design-system/components/styles';
 import '@central-design-system/components/styles/legacy';
 import { createCds } from '@central-design-system/components';
 
@@ -458,10 +458,10 @@ app.use(createCds({
 
 ```vue
 <!-- CDS 4 — Tailwind v4 + CDS-токены как утилиты -->
-<div class="flex flex-col p-400 text-surface-primary">…</div>
+<div class="flex flex-col p-4 text-surface-primary">…</div>
 ```
 
-**Действие:** установить Tailwind CSS v4 по [официальной документации](https://tailwindcss.com/) и подключить конфигурацию `@central-design-system/components/styles/tailwind` — она расширяет тему Tailwind токенами CDS (`bg-surface-*`, `text-content-*`, `p-400`, `rounded-200`, …) и автоматически реагирует на смену темы. Стандартные Tailwind-утилиты (`p-4`, `text-blue-500`) остаются доступны параллельно.
+**Действие:** установить Tailwind CSS v4 по [официальной документации](https://tailwindcss.com/) и подключить конфигурацию `@central-design-system/components/styles/tailwind` — она расширяет тему Tailwind токенами CDS (`bg-surface-*`, `text-content-*`, `rounded-200`, …) и автоматически реагирует на смену темы. Отступы пишутся стандартной числовой шкалой Tailwind (`p-4`, `gap-2`) — шкала отступов CDS с ней совпадает.
 
 <!-- entry-meta: id=styles-tailwind-v4-integration; severity=new; component= -->
 
@@ -584,9 +584,10 @@ _Пока изменений нет. Записи будут добавлять
 | `CdsCard`        | ⚠️ удалены `interactive` / `selected`                                                      | [CdsCard](#cdscard)               |
 | `CdsCheckbox`    | ⚠️ удалён `CdsCheckboxGroup`; ⚠️ изменён exposed-API                                       | [CdsCheckbox](#cdscheckbox)       |
 | `CdsContentSwitcher` | ⚠️ Компонент удалён → `CdsTabs` / `CdsTab`                                             | [CdsContentSwitcher](#cdscontentswitcher) |
+| `CdsDrawer`      | ⚠️ `v-model` управляет видимостью и на широком экране; синхронизация с шириной экрана     | [CdsDrawer](#cdsdrawer)           |
 | `CdsForm`        | ⚠️ изменён exposed-API — убраны обёртки `form` / `formRef`                                 | [CdsForm](#cdsform)               |
 | `CdsIcon`        | ⚠️ удалён deprecated `invertColor` → цветовые пропсы `color` / `baseColor` / `textColor`   | [CdsIcon](#cdsicon)               |
-| `CdsList`        | ⚠️ удалён `invertColor`; `CdsListItem` — удалён `isClickable` (→ `link`) и изменён exposed-API; `CdsListGroup` — удалён слот `title` и изменён exposed-API; payload `click:open`/`click:select` без `event` | [CdsList](#cdslist)               |
+| `CdsList`        | ⚠️ удалён `invertColor`; `CdsListItem` — удалён `isClickable` (→ `link`) и изменён exposed-API; `CdsListGroup` — удалён слот `title`, проп `title` стал текстом активатора (статичная подпись → `CdsListSubheader`), изменён exposed-API; payload `click:open`/`click:select` без `event` | [CdsList](#cdslist)               |
 | `CdsModal`       | ⚠️ удалены `loading` и `dismissBtn`; ⚠️ изменён exposed-API                                | [CdsModal](#cdsmodal)             |
 | `CdsNotification` | 🔁 `status="error"`→`"danger"`; ⚠️ удалён `customIcon`; ✨ `variant="flat"`, тень у `important`, `bgColor`/`textColor` | [CdsNotification](#cdsnotification) |
 | `CdsNotificationAlert` | 🟠 Мост миграции на `CdsToast`; внутри `CdsNotification` (`variant="important"`); будет удалён | [CdsNotificationAlert](#cdsnotificationalert) |
@@ -595,13 +596,14 @@ _Пока изменений нет. Записи будут добавлять
 | `CdsProgress`    | 🔁 Переименован в `CdsProgressBar`; ✨ новые пропсы стилизации                              | [CdsProgress](#cdsprogress)       |
 | `CdsSlideGroup`  | 🔁 `prependIcon`/`appendIcon`→`prevIcon`/`nextIcon` (новая система иконок)                  | [CdsSlideGroup](#cdsslidegroup)   |
 | `CdsSlideView`   | ⚠️ дефолты иконок стрелок `chevron-left`/`chevron-right`→`prev`/`next` (новая система иконок) | [CdsSlideView](#cdsslideview)     |
+| `CdsStages`      | 🟠 Помечен deprecated → `CdsSteps` без `interactive`; будет удалён в 5.0                    | [CdsStages](#cdsstages)           |
 | `CdsStatus`      | 🔁 значение `status="error"`→`"danger"`; ⚠️ булев `icon`→`variant="text"`                   | [CdsStatus](#cdsstatus)           |
 | `CdsSteps`       | ⚠️ дефолт `interactive` изменён `true`→`false`; ✨ проп `items`, контентная часть и кнопки навигации | [CdsSteps](#cdssteps)             |
 | `CdsTabsV2`      | 🔁 Переименован в `CdsTabs`; 🔁 `prependIcon`/`appendIcon`→`prevIcon`/`nextIcon`; ✨ новые пропсы | [CdsTabsV2](#cdstabsv2)           |
 | `CdsTag`         | 🔁 `remove`→`click:close`; ⚠️ удалён слот `text`; иконки → `IconValue`; ✨ новые пропсы | [CdsTag](#cdstag)                 |
 | `CdsTextArea`    | ⚠️ удалён `limit`; ⚠️ изменён exposed-API; | [CdsTextArea](#cdstextarea)       |
-| `CdsTextInput`   | ⚠️ удалён `limit`; ⚠️ удалён `persistentMessages`; ⚠️ изменён exposed-API; иконки → `IconValue` | [CdsTextInput](#cdstextinput)     |
-| `CdsTooltip`     | ⚠️ hover на контент закрывает подсказку; интерактивный контент — через новый проп `interactive`; ⚠️ удалён `hideArrow`/«хвостик»; изменён exposed-API | [CdsTooltip](#cdstooltip)         |
+| `CdsTextInput`   | ⚠️ удалён `limit`; ⚠️ удалён `persistentMessages`, `messages` теперь видны всегда; ⚠️ изменён exposed-API; иконки → `IconValue` | [CdsTextInput](#cdstextinput)     |
+| `CdsTooltip`     | ⚠️ hover на контент закрывает подсказку; интерактивный контент — через новый проп `interactive`; изменён exposed-API | [CdsTooltip](#cdstooltip)         |
 | `CdsContainer`   | ⚠️ Компонент удален;                                                                       | [CdsContainer](#cdscontainer)     |
 
 ### CdsNotification
@@ -942,9 +944,9 @@ const selected = ref(['first']);
 
 <template>
   <div class="w-full">
-    <CdsLabel class="mb-100">Заголовок группы чекбоксов</CdsLabel>
-    <CdsDescription class="mb-100">Вспомогательное описание</CdsDescription>
-    <div class="flex flex-col gap-200">
+    <CdsLabel class="mb-1">Заголовок группы чекбоксов</CdsLabel>
+    <CdsDescription class="mb-1">Вспомогательное описание</CdsDescription>
+    <div class="flex flex-col gap-2">
       <CdsCheckbox v-model="selected" label="Значение чекбокса 1" hide-details value="first" />
       <CdsCheckbox v-model="selected" label="Значение чекбокса 2" hide-details value="second" />
       <CdsCheckbox v-model="selected" label="Значение чекбокса 3" hide-details value="third" />
@@ -1036,6 +1038,45 @@ const model = ref('ru');
 
 <!-- entry-meta: id=cdscontentswitcher-removed; severity=breaking; component=CdsContentSwitcher -->
 
+### CdsDrawer
+
+#### `v-model` управляет видимостью панели и на широком экране
+
+> ⚠️ **BREAKING** — `false` больше не игнорируется на экранах от 1056 px.
+
+**Было (CDS 3):**
+
+```vue
+<!-- CDS 3 -->
+<script setup>
+const drawer = ref(false); // для мобильной кнопки-бургера
+</script>
+
+<template>
+  <!-- на широком экране панель видна при любом значении drawer -->
+  <CdsDrawer v-model="drawer">…</CdsDrawer>
+</template>
+```
+
+**Стало (CDS 4):**
+
+```vue
+<!-- CDS 4 -->
+<script setup>
+// null — панель сама открыта на широком экране и закрыта на узком
+const drawer = ref<boolean | null>(null);
+</script>
+
+<template>
+  <!-- false скрывает панель на любой ширине и освобождает место в макете -->
+  <CdsDrawer v-model="drawer">…</CdsDrawer>
+</template>
+```
+
+**Действие:** если `v-model` обычной панели (без `permanent` / `temporary`) стартует с `false` в расчёте на то, что на десктопе панель всё равно видна, — заменить начальное значение на `null` (или убрать `v-model`) или на `true`. При переходе через 1056 px панель теперь сама меняет `v-model` (закрывается при сужении, открывается при расширении) — если это мешает, добавить `disable-resize-watcher`. `permanent` на узком экране теперь занимает место в макете, а не накрывает контент. Поиск: `grep -rnE "<CdsDrawer[^>]*(v-model|:model-value)" src/`.
+
+<!-- entry-meta: id=cdsdrawer-v-model-controls-visibility; severity=breaking; component=CdsDrawer -->
+
 ### CdsForm
 
 #### Изменён exposed-API — убраны обёртки `form` / `formRef`
@@ -1633,6 +1674,32 @@ const value = ref(35);
 
 <!-- entry-meta: id=cdsslideview-arrow-icons-iconvalue; severity=breaking; component=CdsSlideView -->
 
+### CdsStages
+
+#### Компонент `CdsStages` помечен deprecated — переходите на `CdsSteps`
+
+> 🟠 **DEPRECATED** — публичный API компонента не изменился (`items`, `current`, `finished`, exposed `isCurrent` / `isFinished` работают как в CDS 3), но сценарий полностью закрывает `CdsSteps`, поэтому новый код на `CdsStages` писать не нужно. Компонент остаётся рабочим во всей ветке 4.x и будет удалён в 5.0.
+
+**Было (CDS 3):**
+
+```html
+<!-- CDS 3 -->
+<CdsStages :items="stages" :current="current" :finished="finished" />
+```
+
+**Стало (CDS 4):**
+
+```html
+<!-- CDS 4 — шапка степпера без items работает как трекер статуса -->
+<CdsSteps :model-value="current">
+  <CdsStepsItem v-for="stage in stages" :key="stage.value" :value="stage.value" :title="stage.title" :error="stage.error" />
+</CdsSteps>
+```
+
+**Действие:** `CdsStages` продолжает работать в 4.x, но в dev-консоли выводит `[CDS UPGRADE] 'CdsStages' is deprecated, use 'CdsSteps' instead.` (см. `deprecate()` в `src/utils/dom/console.ts`). Переходите на `CdsSteps`: без пропа `interactive` шаги некликабельны (дефолт `false`), `readonly` отключает переходы принудительно, а шапка без `items` рендерится без контентной части и кнопок навигации. Учтите, что вид отличается: `CdsStages` — стрелочная лента, `CdsSteps` — индикаторы с линией прогресса; для вертикального трекера есть проп `vertical`. Поиск: `grep -rnE "CdsStages|cds-stages" src/`.
+
+<!-- entry-meta: id=cdsstages-deprecated-use-cdssteps; severity=deprecation; component=CdsStages -->
+
 ### CdsStatus
 
 #### Значение `status="error"` переименовано в `status="danger"`
@@ -1994,25 +2061,27 @@ area.value.controlRef;        // DOM-элемент контрола (<textarea>
 
 <!-- entry-meta: id=cdstextinput-limit-removed; severity=breaking; component=CdsTextInput -->
 
-#### Удалён пропс `persistentMessages`
+#### Удалён пропс `persistentMessages`, а `messages` видны всегда
 
-> ⚠️ **BREAKING** — в CDS 3 `persistentMessages` держал блок сообщений/подсказки под полем всегда видимым. В CDS 4 пропс удалён: для постоянного показа подсказки используйте `hint` + `persistentHint`.
+> ⚠️ **BREAKING** — роли разошлись. В CDS 3 `messages` показывались только в фокусе, а `persistentMessages` их закреплял. В CDS 4 `messages` видны **всегда**, поэтому `persistentMessages` удалён за ненадобностью, а «только в фокусе» — это отдельный пропс `hint` (с `persistentHint`, если подсказку нужно закрепить).
 
 **Было (CDS 3):**
 
 ```html
 <!-- CDS 3 -->
 <cds-text-input v-model="text" :messages="hint" persistent-messages />
+<cds-text-input v-model="text" :messages="hint" />
 ```
 
 **Стало (CDS 4):**
 
 ```html
-<!-- CDS 4 -->
-<CdsTextInput v-model="text" :hint="hint" persistent-hint />
+<!-- CDS 4 — messages видны всегда; показ по фокусу даёт hint -->
+<CdsTextInput v-model="text" :messages="hint" />
+<CdsTextInput v-model="text" :hint="hint" />
 ```
 
-**Действие:** убрать `persistent-messages`; для постоянной подсказки под полем задать `hint` и `persistent-hint`. Поиск: `grep -rnE "persistent-messages|persistentMessages" src/`.
+**Действие:** там, где стоял `persistent-messages`, достаточно удалить пропс — `messages` и так видны всегда, переносить текст в `hint` не нужно. Там, где `messages` использовались **без** него, перенести текст в `hint`: иначе подсказка, которая раньше появлялась по фокусу, после апгрейда будет висеть постоянно — код не сломается, но поле станет выглядеть иначе. Поиск: `grep -rnE "persistent-messages|persistentMessages|:messages|messages=" src/`. Начиная с CDS 3.11.0 оба случая предупреждают в консоли (`[CDS UPGRADE]`), а `hint` / `persistent-hint` там уже работают — переписать можно до апгрейда.
 
 <!-- entry-meta: id=cdstextinput-persistentmessages-removed; severity=breaking; component=CdsTextInput -->
 
@@ -2082,36 +2151,6 @@ input.value.controlRef;        // DOM-элемент контрола (<input>)
 
 <!-- entry-meta: id=cdstooltip-interactive-prop-required; severity=breaking; component=CdsTooltip -->
 
-#### Удалён пропс `hideArrow` и направляющий «хвостик»
-
-> ⚠️ **BREAKING** — у подсказки больше нет указателя-«хвостика», а вместе с ним удалён пропс `hideArrow`.
-
-**Было (CDS 3):**
-
-```html
-<!-- CDS 3 — «хвостик» можно было скрыть через hide-arrow -->
-<cds-tooltip text="Подсказка" hide-arrow>
-  <template #activator="{ props }">
-    <cds-button v-bind="props" text="Наведи" />
-  </template>
-</cds-tooltip>
-```
-
-**Стало (CDS 4):**
-
-```html
-<!-- CDS 4 — «хвостик» удалён из вёрстки, пропса hideArrow нет -->
-<CdsTooltip text="Подсказка">
-  <template #activator="{ props }">
-    <CdsButton v-bind="props" text="Наведи" />
-  </template>
-</CdsTooltip>
-```
-
-**Действие:** удалить `hide-arrow` / `hideArrow` из использований `CdsTooltip`. Поиск: `grep -rnE "cds-tooltip[^>]*hide-arrow|CdsTooltip[^>]*hideArrow" src/`.
-
-<!-- entry-meta: id=cdstooltip-hidearrow-removed; severity=breaking; component=CdsTooltip -->
-
 #### Изменён exposed-API
 
 > ⚠️ **BREAKING** — вместо `id` / `overlay` компонент отдаёт элементы и методы оверлея напрямую.
@@ -2161,13 +2200,13 @@ tip.value.updateLocation?.(e);   // пересчёт позиции
 
 ```html
 <!-- CDS 4 — обычный div + утилиты Tailwind и токены CDS -->
-<div class="rounded-200 bg-surface-primary p-400">
-  <div class="h6 mb-100">Заголовок контейнера</div>
+<div class="rounded-200 bg-surface-primary p-4">
+  <div class="h6 mb-1">Заголовок контейнера</div>
   <p>Используется в качестве элемента, где вся область контейнера — это интерактивное состояние.</p>
 </div>
 ```
 
-**Действие:** заменить `CdsContainer` / `<div class="cds-container-default …">` обычным `<div>` с утилитарными классами. В CDS 3 этот же совет давался прямо в сторибуке (`CdsContainer/stories/features.stories.ts`, story «Обычный контейнер»/«Вложенные контейнеры»), а в CDS 4 он тем более уместен — доступны Tailwind v4 и design-токены как утилиты (`bg-surface-*`, `p-400`, `rounded-200`, см. раздел «Интеграция с Tailwind CSS v4»). Поиск: `grep -rnE "CdsContainer|cds-container|cds-container-default" src/`.
+**Действие:** заменить `CdsContainer` / `<div class="cds-container-default …">` обычным `<div>` с утилитарными классами. В CDS 3 этот же совет давался прямо в сторибуке (`CdsContainer/stories/features.stories.ts`, story «Обычный контейнер»/«Вложенные контейнеры»), а в CDS 4 он тем более уместен — доступны Tailwind v4 и design-токены как утилиты (`bg-surface-*`, `rounded-200`, см. раздел «Интеграция с Tailwind CSS v4»). Поиск: `grep -rnE "CdsContainer|cds-container|cds-container-default" src/`.
 
 #### Выбираемый и множественный контейнер → `CdsCard` + `CdsCardGroup`
 
@@ -2207,7 +2246,7 @@ const items = [1, 2, 3];
 </script>
 
 <template>
-  <CdsCardGroup v-model="selected" required class="gap-400">
+  <CdsCardGroup v-model="selected" required class="gap-4">
     <CdsCard
       v-for="item in items"
       :key="item"