Обёртки текста

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

В макете почти всякая надпись внутри компонента вставлена не текстовым слоем, а инстансом из семейства «Text / …». Это приём Figma, а не устройство компонента: обёртка даёт дизайнеру выбрать в одном месте стиль, цвет, число строк и то, как обрезается хвост. В коде ей соответствует не компонент, а свойства самого текста.

Как это попадает в контракт. Инстанс обёртки сворачивается в текстовый узел, а её внутреннее дерево не переносится:

- path: Text State/Label
  kind: text
  foundation: typography
  size: {width: fill, height: hug}
  text: {style: Body/H4, color: text-secondary, align: start, lines: 1, truncate: ellipsis}

foundation: typography — метка «текст пришёл из обёртки»: в макете здесь инстанс, а в коде обычная надпись. Всё, что разработчику нужно знать, стоит рядом в text.

Что настраивается

truncate: blur — тот самый случай, ради которого настройку и нужно фиксировать. Текст, не поместившийся в отведённое число строк, не обрывается многоточием, а гаснет градиентом: поверх хвоста ложится полоска ⚒︎ Text Overflow Blur с переходом в цвет слоя. Читать это надо так: «строка ограничена числом строк, а край размыт». Многоточия при этом нет — если в коде поставить text-overflow: ellipsis, вид разойдётся с макетом.

Чем обёртка устроена внутри

Три приёма, которые в код не переносятся:

• цвет задаётся прямоугольником поверх надписи. Внутри обёртки лежит инстанс ⚒︎ Text Color, положенный абсолютно поверх текста; красит он на просвет. Сама надпись в обычном виде залита литеральным чёрным rgb(0,0,0) — это не дефект вёрстки, а часть приёма: видимый цвет берётся с прямоугольника. Поэтому и читать цвет надо с него, а не с текстового слоя;
• размытие хвоста — отдельная обойма с градиентом. При Text Overflow=Blur в дерево добавляется ⚒︎ Blur с полоской ⚒︎ Text Overflow Blur/Layer-01…03 (по одной на слой фона), а раскладка корня разворачивается с колонки на строку;
• у обжимающих обёрток есть вид со счётчиком. Ось Type со значением Text + Quentity добавляет вторую надпись. Такой инстанс в текстовый узел не сворачивается: надписи две, и обе значащие — он остаётся в контракте инстансом.

Отдельно стоит Typography (61392:97040) — обёртка без стиля вовсе: начертание набрано переменными напрямую, а цвет можно взять как из токена, так и своим прямоугольником Custom Color. Это заготовка для случаев, которых нет среди стилей.

Наборы семейства

Тянущиеся по ширине: оси Max Lines (1…5, Max) × Text Overflow (Elipse, Blur), 12 мастеров.

Обжимающие по содержимому: ось Type (Text, Text + Quentity), 2 мастера.

Служебные части семейства: ⚒︎ Text Color (61721:589, 23 мастера — по одному на токен), ⚒︎ Text Overflow Blur/Layer-01…03 (36069:38763, 36069:38765, 36069:38866), ⚒︎ Text Overflow Blur (40001352:18483) и ⚒︎ Text Overflow Blur Left (40018207:38312). Своих контрактов у них нет — но в чужих деревьях они встречаются, и тогда записываются по правилу ниже.

Костыли, которые лежат отдельно от обёртки

Два компонента страницы Text живут своей жизнью: их кладут прямо в дерево компонента, без обёртки вокруг. Контрактов им не пишут — как и слою состояния, и SYSTEM-слоям: это приём макета, а не часть системы.

Полоска размытия — ⚒︎ Text Overflow Blur/Layer-01…03

Прямоугольник 12×14 с горизонтальным градиентом: он ложится на хвост строки и гасит его в цвет фона. Мастеров три — по одному на слой фона, и различаются они только цветом градиента:

Внутри обёртки полоску добавляет ось Text Overflow=Blur, и тогда она в контракт не попадает: обёртка сворачивается в текстовый узел с text.truncate: blur. Но полоску кладут и вручную, рядом с надписью — так сделаны подписи Action Button и значение Card Input. Тогда узел остаётся в дереве и пишется как костыль:

- path: "Action Button/Text/Text 1 Fill/Blur Fill/⚒︎ Text Overflow Blur"
  kind: instance
  layerName: "⚒︎ Text Overflow Blur/Layer-02"
  of: null
  local: true
  foundation: typography
  fill: GRADIENT_LINEAR

of: null и local: true — контракта у костыля нет и не будет; foundation: typography отсылает сюда. Разработчику это читается так же, как truncate: blur у надписи: хвост не обрывается, а гаснет в фон, и отдельного слоя в разметке для этого не нужно.

Точки загрузки — ⚒︎ Elilpses Loading/1…4

Четыре кадра анимации: рамка 7×2 и три точки 2×2 цветом fg-tertiary. Кадры отличаются только тем, какие точки погашены прозрачностью:

В базе контрактов этот костыль не встретился ни разу: точки ставят на макетах экранов, а не внутри компонентов. Если встретится — писать так же, как полоску размытия: of: null, local: true, foundation: typography, а рядом дыра о том, что это анимация ожидания, а не содержимое.

Дыры

• градиент костыля теряет токены. У полоски размытия каждый стоп привязан к переменной (layer-0N-blur-gradient-0M, девять штук, со значениями для тёмной темы), но контракт пишет заливку одним словом GRADIENT_LINEAR: имён стопов в формате нет. По базе у всех девяти переменных счётчик применений — ноль, хотя применяются они трижды.

• значение оси написано Elipse — с одной «л» и без «i»: ни Ellipse, ни Ellipsis.

• Max Lines доходит только до пяти строк. Дальше — сразу Max, то есть без ограничения вовсе; шести или семи строк выбрать нельзя.

• имя стиля у статейных заголовков — Articles/Titile/H1…H6: опечатка в самом стиле, и она попадает в контракты как есть.

• имя набора Text / Articles /Title / H6 написано без пробела перед слешем, в отличие от пяти соседей.

• обёртка Typography не привязана ни к одному стилю: её текст держится на переменных напрямую и при перенастройке стилей за ними не пойдёт.

• у надписи внутри обёртки стоят и стиль, и переменные типографики — и это норма. Текстовые стили Astra DS сами собраны из переменных (font-family, font-size, line-height, letter-spacing, font-weight), поэтому привязки видны и на узле. Дефектом было бы обратное: своя переменная поверх стиля, отличная от стиля, — такое ловит плагин проверки правилом TXT-002.