GrValue — Компоненты

Обзор

Когда брать

пишете свой компонент с величиной — плитку, ячейку, строку отчёта: приписки оформятся так же, как в остальном пакете, без копирования классов;
валюта стоит справа — 100 ₽, а не $100: сторона задаётся тем, в какую приписку положить символ;
величина не число — «2 ч 15 мин», «—», «н/д» выводятся как есть;
нужна своя вёрстка вокруг значения — знак, стрелка, скрытая подпись ложатся в слоты между частями записи.

Когда взять другое

Нужно	Берите
Знак и тон по знаку внутри строки текста	`GrDelta`
Крупный показатель плиткой, с подписью и динамикой	`GrStatistic`
Значение как статус или метка	`GrBadge`
Пара «характеристика → значение»	`GrDescriptionList`
Форматирование числа по локали	`formatStatisticValue` из `GrStatistic`

Playground контролы выводятся из API, а не пишутся руками

Сцена

Загружается…

0 изменено· состояние — в адресе

Примеры 4 у каждого — живое демо и его код

Готовая величина и её приписки
Величина приходит отформатированной — Intl на стороне вызова, «2 days 6 h» или «—» как есть, — а компонент только расставляет приписки: префикс берёт цвет и кегль числа, суффикс приглушён, мельче и отбит.
Team plan · 9 seats
€432.00
Extra storage · 180 GB
€36.00
Automation runs over quota
€12.40
Discount
—
VAT
20%
Total due€576.48
Next charge in 2 days 6 h
Валюта справа
Сторону символа выбирает приписка, а не локаль. Валюта после числа — всё равно часть суммы, поэтому --gr-value-suffix-color: currentColor и --gr-value-suffix-size: 1em снимают приглушение, которое подходит единице вроде ms.
- Germany€1,284.50
- Poland5 480,00zł
- Sweden14 990kr
- United States$1,399.00
Median response 182ms
Тон и кегль приходят от родителя
Своей шкалы и тона у величины нет: заголовок набирает её крупно, ячейка таблицы — мелко и красным, и валюта идёт за числом в обоих случаях. Знак ложится в слот lead, перед префиксом, а колонка выравнивается по моноширинным цифрам.
Net revenue, September€55,963.80
Subscriptions +€48,920.00 72.4%
Services +€12,850.00 19.0%
Refunds −€4,320.00 6.4%
Payment fees −€1,486.20 2.2%
Цена, набранная вручную
У каждой части записи свой слот: lead держит «from», prefix — приподнятую валюту, слот по умолчанию — число с мелкими копейками, suffix — период, а trail — фразу, которую слышит только скринридер.
Starter
€ 0euros per seat a month/ seat · month
free for up to 3 members
Team
from€ 48.00euros per seat a month/ seat · month
billed yearly
Business
from€ 96.50euros per seat a month/ seat · month
billed yearly

API порождается из пакета · разойтись не может

Props

Prop	Type	по умолчанию	Описание
`value`	`string \| number \| null \| undefined`	—	Готовое к показу значение. Не форматируется: «2 ч 15 мин» и «—» тоже величины.
`prefix`	`string \| undefined`	—	Приписка перед значением: валюта, знак приближения.
`suffix`	`string \| undefined`	—	Приписка после значения: единица измерения, валюта справа.

Слоты

Slot	Type	Описание
`default`	`any`	Значение вместо пропа.
`prefix`	`any`	Приписка перед значением.
`suffix`	`any`	Приписка после значения.
`lead`	`any`	Перед префиксом: знак величины у `GrDelta`, стрелка направления. Слотом, а не пропом, — разметка там принадлежит потребителю.
`trail`	`any`	После значения: скрытый узел для диктора у `GrStatistic`.

Типы

Все экспортируемые типы подпути, по файлам, где они объявлены. Имена, дженерики и тела читаются из файлов деклараций пакета и разойтись не могут.

Импорт

import type { GrValueProps } from '@feugene/granularity/components/GrValue'

Файлdist/types/components/GrValue/config.d.ts

grValueConfigconst

const grValueConfig: import("@feugene/granum/contract").GranumComponentDescriptor<"GrValue">;

Файлdist/types/components/GrValue/GrValue.vue.d.ts

GrValuePropsinterface

Величина с приписками: префикс, значение, суффикс — и ничего больше. Примитив, на котором стоят GrDelta (величина со знаком и тоном) и GrStatistic (величина плиткой с подписью). Сам он не форматирует число, не знает про тон и не имеет своей шкалы размеров: значение приходит готовым, а кегль и цвет наследуются от места, где величина стоит. Чем является приписка — валютой, единицей измерения или пометкой — компонент не решает: оформление обеих задаётся токенами --gr-value-*.

interface GrValueProps {
    /** Готовое к показу значение. Не форматируется: «2 ч 15 мин» и «—» тоже величины. */
    value?: string | number | null;
    /** Приписка перед значением: валюта, знак приближения. */
    prefix?: string;
    /** Приписка после значения: единица измерения, валюта справа. */
    suffix?: string;
}

Файлdist/types/components/GrValue/safelist.d.ts

grValueSafelistconst

const grValueSafelist: string[];

Использование из прозы библиотеки

Величина приходит готовой

Примитив ничего не форматирует: разряды, точность и разделители — забота того, кто передаёт значение. Это не экономия, а граница ответственности: «2 ч 15 мин» и «—» такие же величины, как 1 284 500, и компонент, который попытался бы их разобрать, испортил бы обе.

Форматирование по локали в пакете есть — formatStatisticValue; оно доступно отдельно и складывается с примитивом как угодно.

Приписка — не обязательно единица измерения

Компонент не решает, чем является приписка. Это и есть его смысл: $, ₽, %, мс, «за заказ» — разные вещи, и одно правило на всех однажды соврёт.

Дефолты выбраны по частоте, а не по истине:

	Префикс	Суффикс
цвет	как у величины	приглушённый
кегль	как у величины	мельче
отбивка	нет	есть

За ними стоит наблюдение: слева чаще пишут валюту, и она часть суммы; справа чаще единицу, и она величине не принадлежит. $14,99 и 42 % получаются сами.

Валюта справа — снимите приглушение

Рубль пишут после числа, но он такая же часть суммы, как $ перед ней. Поэтому дефолт суффикса ему не подходит, и его меняют токенами:

vue

<GrValue
  :value="formatted"
  suffix="₽"
  style="--gr-value-suffix-color: currentColor; --gr-value-suffix-size: 1em"
/>

Приложению, где так всегда, удобнее объявить это классом один раз:

css

.amount { --gr-value-suffix-color: currentColor; --gr-value-suffix-size: 1em; }

Именно currentColor и 1em, а не inherit. У пользовательского свойства inherit — ключевое слово наследования самой переменной: оно означает «возьми её значение у родителя», а у родителя её нет, и токен остаётся неопределённым. Фолбэк тогда срабатывает как обычно, и приписка выглядит нетронутой — правка молча не даёт ничего. currentColor и 1em — настоящие значения, и они означают ровно то, что нужно: цвет и кегль величины.

Сторону символа компонент не выбирает. Соблазн вывести её из локали есть, но Intl расставляет валюту по локали, а не по валюте: в ru-RU справа оказываются все, включая доллар (1 284 500,50 $), в en-US слева все, включая рубль (RUB 1,284,500.50). Привычное «₽ справа, $ и € слева» — правило смешанное и продуктовое, вывести его неоткуда. Решает потребитель, выбирая приписку.

Тон доезжает до приписки сам

Цвет префикса по умолчанию — inherit, а не копия роли тона. Разница видна на отрицательной сумме: краснеет вся запись, а не число без символа валюты. Поэтому тон задаётся один раз на родителе — так делает GrStatistic, — и примитиву о нём знать не нужно.

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

Границы

Позиции приписок фиксированы: префикс слева, суффикс справа. Порядок не меняется ни пропом, ни локалью — величина, у которой приписки переставляются местами, это две разные записи, и выбрать между ними может только автор экрана.