# Подготовка к CDS 4, не дожидаясь апгрейда

> **Требуется CDS 3.11.0 или выше.** Всё описанное ниже и API 4-ки, поддержанное в 3-ке, — появилось в
> `@central-design-system/components@3.11.0`. На более ранних версиях ничего
> этого нет, поэтому начните с обновления пакета.

CDS 4 — крупное мажорное обновление дизайн-системы. Чтобы переход не
превратился в один большой PR, часть изменений можно внести уже сейчас. 
CDS v3.11.0 делает две вещи:

1. **Предупреждает.** В dev-сборке компоненты пишут в консоль
   `[CDS UPGRADE] …` там, где код придётся править при переходе на 4-ку.
   Каждое сообщение выводится один раз за сессию и содержит ссылку на
   [migration guide](https://cds.b2b-center.ru/migration/) (_Он пока не опубликован, следите за обновлениями_). Предупреждение
   появляется, только если проп реально задан и меняет значение по умолчанию:
   `:persistent-messages="false"` или `v-bind` со всем набором пропсов
   (как в Storybook) ни на что не влияют и остаются без сообщения.
   Отдельный вид сообщения — `behaves differently in v4.0.0`: проп остаётся,
   но начинает работать иначе, и менять его имя не нужно.
2. **Даёт API 4-ки уже сейчас.** Бо́льшую часть переименований можно применить
   на 3-ке: старое и новое имена работают одновременно, поведение не меняется.
   После апгрейда такой код трогать не нужно.

Ниже — что можно переписать сегодня.

## Точка входа стилей

```diff
- import '@central-design-system/components/dist/cds.css';
+ import '@central-design-system/components/styles';
```

## Компоненты

| Было (CDS 3) | Стало (CDS 4) | Доступно в CDS 3                         |
| --- | --- |------------------------------------------|
| `CdsProgress` | `CdsProgressBar` | ✅ полный алиас                           |
| `CdsRadioButton` | `CdsRadioGroup` | ✅ полный алиас                           |
| `CdsSidebar` | `CdsDrawer` | ✅ `CdsDrawer` уже есть                   |
| `CdsContentSwitcher` | `CdsTabs` (в 3-ке — `CdsTabsV2` + проп `grow`) | ✅                                        |
| `CdsContainer` | `CdsCard` или обычный `<div>` | ✅                                        |
| `CdsCheckboxGroup` | `CdsLabel` + `CdsDescription` + `CdsCheckbox` с общим массивом в `v-model` | ✅ |
| `CdsListGroup` с `title` / `#title` (статичная подпись группы, без `subgroup`) | `CdsListSubheader` | ✅ `CdsListSubheader` есть с 3.12.0 |
| `CdsTabs` / `CdsTab` (старые) | их в CDS 4 нет | ✅ переходите на `CdsTabsV2` / `CdsTabV2` |
| `CdsTabsV2` / `CdsTabV2` | `CdsTabs` / `CdsTab` | ❌ имена заняты старыми табами            |
| `CdsSelect` (нативный) | `CdsSelect` с пропом `native-select` | ✅ CdsDropdown с пропом  `native-select`    |
| `CdsDropdown` | `CdsSelect` | ❌ имя занято нативным `CdsSelect`        |

Компоненты помеченные ❌ — единственные переименования, которые придётся делать
в момент апгрейда: их имена в CDS 3 уже заняты другими компонентами. Поэтому
предупреждение у них другое — не «проп устарел», а
`becomes '…' in v4.0.0. Rename it during the upgrade, not before`.

### Табы: переезд в два шага

В CDS 3 живут две пары табов, и в CDS 4 имена достаются новой:

| Сейчас в коде | Что делать в CDS 3 | Что станет в CDS 4 |
| --- | --- | --- |
| `CdsTabs` / `CdsTab` (старые) | перейти на `CdsTabsV2` / `CdsTabV2` | этих компонентов нет |
| `CdsTabsV2` / `CdsTabV2` | ничего, это актуальная пара | переименовать в `CdsTabs` / `CdsTab` |

То есть `CdsTabsV2` — не «устаревший», а наоборот целевой компонент: суффикс
`V2` уйдёт из имени при апгрейде, когда старые табы будут удалены.

### Группа чекбоксов без `CdsCheckboxGroup`

`CdsCheckboxGroup` в CDS 4 удалён, а то, что он давал — общий `v-model`, `label`
и `description`, — разошлось по трём частям. Все три доступны в CDS 3:

```html
<CdsLabel text="Заголовок группы" />
<CdsDescription text="Вспомогательное описание" />

<CdsCheckbox v-model="selected" value="first" label="Первый" hide-messages />
<CdsCheckbox v-model="selected" value="second" label="Второй" hide-messages />
```

`selected` — массив; каждый чекбокс добавляет и убирает из него своё `value`.

`CdsLabel` и `CdsDescription` — имена из CDS 4; в CDS 3 это алиасы
`CdsInputLabel` и `CdsInputDescription`, поэтому писать можно уже сегодня.
Что учесть:

- вёрстка группы (отступы, колонка) в CDS 4 — на плечах разработчика: обёртка
  `CdsCheckboxGroup` больше ничего не выравнивает, в примере миграции это
  flex-контейнер;
- пропсы `for`, `size` и `readonly` у `CdsLabel` появились в CDS 4. В 3-ке
  `for` долетит нативным атрибутом на `<label>` и сработает, а `size`
  и `readonly` просто осядут в атрибутах и ни на что не повлияют;
- строку сообщений под каждым чекбоксом убирает `hide-messages` — проп есть
  и в CDS 3, и в CDS 4, так что пишется сразу в целевом виде. Раньше это делала
  сама обёртка `CdsCheckboxGroup`, поэтому без неё проп нужно проставить руками.
  В примере миграции стоит `hide-details` — в CDS 4 это более широкий проп
  (принимает ещё `'auto'`: блок скрыт, пока сообщений нет, и появляется вместе
  с ними), в CDS 3 его нет. Для группы разницы нет — берите `hide-messages`.

## Пропсы, значения, события

| Компонент | Было | Стало | Доступно в CDS 3 |
| --- | --- | --- | --- |
| `CdsBadge` | `count`, `limited` | `content`, `max` | ✅ |
| `CdsBreadcrumbsItem` | `text` | `title` | ✅ |
| `CdsCard` | `interactive` | `link` | ✅ |
| `CdsCard` | `selected` | `CdsCardGroup` + `value` | ✅ |
| `CdsListItem` | `isClickable` | `link` | ✅ |
| `CdsNotification` | `customIcon="bookmark"` | `icon="bookmark"` | ✅ |
| `CdsNotification`, `CdsStatus` | `status="error"` | `status="danger"` | ✅ |
| `CdsStatus` | `icon` | `variant="text"` | ✅ |
| `CdsSlideGroup`, `CdsTabsV2` | `prependIcon`, `appendIcon` | `prevIcon`, `nextIcon` | ✅ |
| `CdsTag` | `@remove` | `@click:close` | ✅ |
| `CdsTag` | слот `#text` | проп `text` или слот по умолчанию | ✅ |
| `CdsTextInput`, `CdsTextArea` | `:limit="60"` | `maxlength="60"` + `:counter="60"` | ✅ |
| `CdsTextInput`, `CdsTextArea` | `persistent-messages` | `messages` — они и так всегда видны (см. ниже) | ✅ |
| `CdsTooltip` | — | `interactive` для кликабельного контента | ✅ проп принимается (в 3-ке контент интерактивен всегда) |
| `CdsModal` | `loading`, `dismiss-btn` | `CdsLoader` и `CdsFunctionalButton` в контенте | ✅ |
| `CdsListGroup` | слот `#title` | `CdsListSubheader` | ✅ с 3.12.0 |
| `CdsListGroup` без `subgroup` | проп `title` — статичный заголовок над группой | `title` — текст активатора, а он рисуется только со слотом `#activator`; статичная подпись — `CdsListSubheader` | ⚠️ `CdsListSubheader` есть с 3.12.0, смена смысла `title` — только в CDS 4 |
| `CdsListGroup` с `subgroup` | проп `title` | ничего не меняется: CDS 4 сам рисует `CdsListSubheader` внутри группы | ✅ менять не нужно |
| `CdsBadge`, `CdsIcon`, `CdsList` и др. | `invertColor` | `color` / `textColor` | ❌ |
| `CdsSlideView` | `chevron-left` / `chevron-right` | `prev` / `next` | ❌ другой набор иконок |

### Подсказки под полем: `messages` → `messages` или `hint`

Проп `messages` в CDS 4 остался, но роли разошлись. В CDS 3 сообщения видны
только в фокусе, а `persistent-messages` их закрепляет. В CDS 4 `messages`
видны **всегда**, а «только в фокусе» — это отдельный проп `hint`
(с `persistent-hint`, если нужно закрепить).

| CDS 3 | CDS 4 |
| --- | --- |
| `:messages="x" persistent-messages` — видно всегда | `:messages="x"` — просто убрать `persistent-messages` |
| `:messages="x"` — видно только в фокусе | `:hint="x"` |

`hint` и `persistent-hint` уже работают в CDS 3 и ведут себя как в 4-ке, так
что второй случай можно переписать сегодня. Первый — тоже: `persistent-messages`
и `messages` продолжают работать, а убрать проп нужно будет в момент апгрейда.

Сам `messages` из CDS 4 никуда не делся и переименования не требует — поэтому
на него приходит не deprecation, а сообщение о смене поведения.

## Что предупреждения не покрывают

Эти изменения нельзя поймать в рантайме — сверьтесь с migration guide вручную при обновлении на CDS v4:

- изменения exposed-API (`ref.validationRef`, `ref.inputRef`, `ref.overlay`,
  `ref.form` и т. д.) — в CDS 4 это единый validation-API и `controlRef`;
- CSS-архитектура, слои, токены и новая система иконок.
