Версии компонента: что описываем, а что нет

Источник: ds-docs/component-contracts/foundations/versions.md

В Astra DS отменённое живёт двумя способами, и путать их нельзя: от того, какой именно перед вами, зависит, попадает компонент в базу или нет.

Два вида отмены


Отменён компонент целиком	крест стоит в имени: `❌ Carousel (Используйте Carousel)`, `❌ List item / Switch`, весь раздел `Deprication Version`	контракта не пишем вовсе — описываем то, на что переходят
Отменена версия внутри компонента	у набора есть ось `Version` со значениями `🟢 Stable` и `❌ Deprecated`	описываем только `🟢 Stable` — точно и целиком; отменённые мастера в контракт не попадают

Зачем внутри компонента держат обе версии

Чтобы продукт мог перейти на новую версию сменой значения свойства, а не заменой компонента. Свап на другой компонент рвёт содержимое: тексты, значки и настройки слетают, и экран приходится собирать заново. Смена Version с ❌ Deprecated на 🟢 Stable оставляет содержимое на месте — поэтому старая ветка и живёт рядом с новой.

Из этого следует и правило описания: старая ветка — не документация, а путь отхода. Разработчику она не нужна: он реализует живую версию, а старую видит только в макетах, которые ещё не перевели.

Как это записано в контракте

в axes у оси версии остаётся одно значение — живое;
masters.count, fullGrid и counts считают только живых мастеров;
правила variants и masters.rules про отменённую ветку не пишутся;
в gaps стоит строка о том, сколько мастеров отменённой версии осталось за кадром.

axes:
  - {name: Version, in: variant, values: ["🟢 Stable"], default: "🟢 Stable"}

gaps:
  - {kind: GAP, text: "у набора есть отменённая версия — 4 мастеров с ❌ в имени.
     По решению они не описываются: переход на новую версию делают сменой значения оси,
     а не заменой компонента"}

Чего это правило не касается

Ось или свойство, названные с крестом, но стоящие у всех мастеров. Такие в контракте остаются: без них живого мастера не собрать. Валидатор о них предупреждает, чтобы долг был виден:

❌ Progress у circular-indeterminate — ось отменена, но стоит у каждого мастера и множит решётку;
❌ Show Badge Indicator у segmented-control-item — крест в имени публичного свойства.

Живой компонент, внутри которого стоит отменённая версия ребёнка. Это не ошибка контракта, а долг макета, и он записывается предупреждением: «вставлена отменённая версия circular-indeterminate». Так видно, где переход на новую версию ещё не сделан.

Что проверяет валидатор


значение оси начинается с ❌	«описана отменённая версия — описываем только 🟢 Stable»
имя оси начинается с ❌	«описана отменённая ось — описываем только живые свойства»
в `props` инстанса стоит ❌-значение	«вставлена отменённая версия ребёнка — она не описана»
сухая сверка	мастеров с ❌ в имени не сверяет и считает их отдельно: «пропущено мастеров отменённой версии: N»

Разнобой в написании

Одно и то же названо в файле по-разному, и контракт повторяет имя как есть:


`🟢 Stable`	`❌ Deprecated`
`🟢 Stabled`	`❌ Depricated`
—	`❌ Description` (у диалогов и календарей: то же место в оси `Version`)

Ось зовётся то Version, то Vesrion. Всё это — дефекты источника, они записаны дырами в контрактах соответствующих компонентов.

См. также: фундаменты, системные элементы.