@central-design-system/components 3.10.6 → 3.11.0

package/UPGRADE.md

@@ -0,0 +1,146 @@
+# Подготовка к 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` | ✅ |
+| `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` | ❌ только в CDS 4 |
+| `CdsListGroup` | проп `title` — статичный заголовок над группой | тот же `title`, но это текст кликабельного активатора; статичный заголовок — `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-архитектура, слои, токены и новая система иконок.

package/dist/cds.d.ts

@@ -22,6 +22,8 @@ declare module '@vue/runtime-core' {
         CdsCardTitle: typeof components.CdsCardTitle;
         CdsCheckbox: typeof components.CdsCheckbox;
         CdsCheckboxGroup: typeof components.CdsCheckboxGroup;
+        CdsLabel: typeof components.CdsLabel;
+        CdsDescription: typeof components.CdsDescription;
         CdsCombobox: typeof components.CdsCombobox;
         CdsContainer: typeof components.CdsContainer;
         CdsContainerItem: typeof components.CdsContainerItem;
@@ -64,8 +66,10 @@ declare module '@vue/runtime-core' {
         CdsPage: typeof components.CdsPage;
         CdsPagination: typeof components.CdsPagination;
         CdsProgress: typeof components.CdsProgress;
+        CdsProgressBar: typeof components.CdsProgressBar;
         CdsRadio: typeof components.CdsRadio;
         CdsRadioButton: typeof components.CdsRadioButton;
+        CdsRadioGroup: typeof components.CdsRadioGroup;
         CdsSelect: typeof components.CdsSelect;
         CdsSidebar: typeof components.CdsSidebar;
         CdsSkeletonLoader: typeof components.CdsSkeletonLoader;