# StatCard

Плитка ключової метрики зі зміною за період і власним напрямом «краще».


Одна метрика на дашборді: назва, число, зміна за період. Компонент нічого
не рахує й не форматує — він показує те, що йому дали, і відповідає за
єдину нетривіальну річ: як пофарбувати зміну.


Example (app/demos/stat-card/StatCardBasic.vue):

```vue
<script setup lang="ts">
import UiStatCard from '~/components/ui/UiStatCard.vue'
</script>

<template>
  <div class="grid w-full gap-4 sm:grid-cols-2 lg:grid-cols-3">
    <UiStatCard label="Виторг за місяць" value="₴1 284 300" :delta="12.4" hint="проти липня">
      <template #icon>
        <svg class="h-5 w-5" viewBox="0 0 24 24" fill="none" aria-hidden="true">
          <path d="M4 18V9m6 9V5m6 13v-6" stroke="currentColor" stroke-width="2" stroke-linecap="round" />
        </svg>
      </template>
    </UiStatCard>

    <UiStatCard label="Нових угод" value="87" :delta="-4" delta-format="absolute" hint="проти липня" />

    <UiStatCard label="Середній чек" value="₴14 762" :delta="0" hint="без змін" />
  </div>
</template>

```


## Зростання не завжди добре

Найпоширеніша помилка такої плитки — фарбувати все зростання зеленим.
Для виторгу це правильно, для відтоку клієнтів — навпаки: `+0,4 %` відтоку
це погана новина, пофарбована в зелене.

Тому знак і колір розведені. Знак `delta` дає стрілку, `deltaGood` каже,
який напрям вважати добрим:

- `deltaGood="up"` — більше краще (виторг, конверсія);
- `deltaGood="down"` — менше краще (відтік, час відповіді, відмови);
- `deltaGood="none"` — «краще» не визначено: стрілка лишається, кольору немає.


Example (app/demos/stat-card/StatCardDeltas.vue):

```vue
<script setup lang="ts">
import UiStatCard from '~/components/ui/UiStatCard.vue'
</script>

<template>
  <div class="grid w-full gap-4 sm:grid-cols-3">
    <!-- Зростання доброго — зелене. -->
    <UiStatCard label="Конверсія" value="4,8 %" :delta="0.6" delta-good="up" hint="більше — краще" />

    <!-- Зростання поганого — червоне. Той самий знак, інший колір. -->
    <UiStatCard label="Відтік клієнтів" value="2,1 %" :delta="0.4" delta-good="down" hint="менше — краще" />

    <!-- Метрика без «кращого» напряму: стрілка є, кольору немає. -->
    <UiStatCard label="Частка мобільних" value="63 %" :delta="5" delta-good="none" hint="просто зміна" />

    <UiStatCard label="Завантаження" loading />
  </div>
</template>

```


## API

[Props, events, slots, exposed API (JSON)](https://ui.tatet.net/api/component-meta/UiStatCard)

## Коли використовувати

- Рядок KPI над дашбордом або звітом.
- Підсумок над таблицею: скільки записів, на яку суму, як змінилось.
- Будь-де, де число важливіше за графік.

## Коли НЕ використовувати

- Для показника без контексту порівняння: без `delta` і `hint` це просто
  число, і звичайний абзац упорається дешевше.
- Як кнопку дії. Плитка з `to` — це посилання на звіт, а не спосіб щось
  запустити.
- Для рядів даних: п'ять плиток поспіль з тією самою метрикою за різні
  місяці — це таблиця або графік.

## Доступність

Стрілка `▲`/`▼` має `aria-hidden`, а поруч стоїть словесний еквівалент:
«зростання на 12 відсотків». Без цього скрінрідер зачитує назву символа —
«чорний трикутник вгору 12».

Число зміни форматується українською — `12.4` друкується як «+12,4 %», з
десятковою комою, а не сирим рядком JS «+12.4 %». Словесний еквівалент
бере те саме число й узгоджує слово: «на 1 відсоток», «на 3 відсотки»,
«на 25 відсотків», «на 12,4 відсотка».

Коли видиме значення скорочене («1,2 млн»), передайте повне в `valueLabel`:
воно піде в `sr-only`, а видиме отримає `aria-hidden`, щоб число не
прозвучало двічі.

Стан `loading` показує скелетони, зберігаючи висоту плитки — сітка
дашборда не перебудовується в момент приходу даних. Плитка тоді має
`aria-busy`: скелетони приховані від скрінрідера, і без нього підпис
метрики звучав би так, ніби значення немає зовсім.


[Source files, dependencies and ZIP](https://ui.tatet.net/registry/components/stat-card.json)
