GrSparkline

charts
Графики
API · 7 props
⌨ клавиши

Берут, когда тренд в ячейке таблицы.

import { GrSparkline } from '@feugene/granularity-charts/components/GrSparkline'

Обзор

Когда брать

тренд в ячейке таблицы — колонка «динамика» рядом с числом: направление видно, точные значения читаются из соседней колонки;
тренд в карточке показателя — под крупным числом GrStatistic, чтобы «1 240» получило историю;
много графиков на одной странице — компонент ничего не замеряет и не держит слушателей, поэтому сотня штук на экране ничего не стоит;
нужен только силуэт — summary добавляет минимум, максимум и последнее значение словами для скринридера, не занимая места на экране.

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

Нужно	Берите
Читать значения по осям, а не силуэт	`GrChartLine`
Показать объём, а не ход	`GrChartArea`
Сравнить категории между собой	`GrChartBar`
Показать долю от целого	`GrProgressBar`

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

История под каждым числом
Спарклайн даёт крупному числу историю: вверх или вниз, ровно или рывками. Осей у него нет намеренно, поэтому две карточки нельзя сравнить по высоте линий — каждая нормирована по своему ряду, а «насколько» говорит число сверху. variant="area" подходит карточке, color красит отток красным, потому что его рост — плохо, изменение под числом — GrDelta, который знает, что падение оттока — хорошая новость, а summary проговаривает диктору минимум, максимум и последнее значение.
MRR
€205 640
+3,1%this week
Active customers
1 284
+18this week
Churn
2,4%
+0,6 ppthis week
Overdue invoices
€6 940
-18,2%this week
Колонка динамики в таблице
Линия говорит «растёт или падает», соседняя колонка — насколько. Каждая строка получает 365 суточных точек, и компонент сам прореживает их (LTTB) до того, что умещается в ячейке шириной 8rem, сохраняя форму и выбросы. null — разрыв: линия прерывается на месяц паузы аккаунта, а не ныряет в ноль.
API usage by accountCalls per day · last 12 months
Account Trend Now
Northwind TradersBusiness
48.2k/day
Contoso LtdTeam
12.9k/day
Fabrikam InteriorsTeamPaused in August
6.4k/day
Adventure WorksStarter
1.1k/day
Задержка на странице статуса
Силуэт, а не график для чтения: ни курсора, ни остановки Tab в каждой строке — так задумано. Сбой — разрыв из точек null, и линия не выдумывает падение в ноль. aria-label называет строку предложением там, где автоматическая сводка сказала бы меньше.
Northwind Billing · statusp95 latency · last 24 hours
- Invoices APIp95 182 ms
  Operational
- PaymentsNo data 14:30–16:00 — provider outage
  Recovered
- WebhooksSpike at 17:30 — a retry storm, 30 minutes
  Operational
- Exportsp95 1.4 s
  Operational

Account	Trend	Now
Northwind TradersBusiness		48.2k/day
Contoso LtdTeam		12.9k/day
Fabrikam InteriorsTeamPaused in August		6.4k/day
Adventure WorksStarter		1.1k/day

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

Props

Prop	Type	по умолчанию	Описание
`valueFormat`	`GrChartNumberFormat \| undefined`	`undefined`	Формат чисел в текстовой сводке для скринридера: знаки после запятой и разделители.
`locale`	`string \| undefined`	`undefined`	BCP-47 локаль чисел сводки. Не задана — язык переводов приложения, иначе `en`.
`ariaLabel`	`string \| undefined`	`undefined`	Своё имя вместо сводки.
`color`	`string \| undefined`	`undefined`	Цвет линии. Не задан — токен `--gr-sparkline-color`.
`variant`	`"line" \| "area" \| undefined`	`undefined`	Вид: `line` (по умолчанию) или `area` — линия с заливкой под ней.
`summary`	`boolean \| undefined`	`undefined`	Автоматическая текстовая сводка для скринридера.
`data`обязательный	`readonly (number \| null)[] \| readonly GrChartPoint[]`	—	Голый ряд чисел либо точки. `null` — пропуск, линия рвётся.

Типы

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

Импорт

import type { GrSparklineConfigurableProps, GrSparklineProps } from '@feugene/granularity-charts/components/GrSparkline'

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

grSparklineConfigconst

Зависимостей нет: спарклайн не рендерит ни одного чужого компонента.

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

Файлdist/types/components/GrSparkline/defaults.d.ts

GrSparklineConfigurablePropsinterface

Пропы GrSparkline, настраиваемые глобально через <GrConfigProvider :component-defaults="{ GrSparkline: { … } }">. Шкалы размеров у спарклайна нет: его размер — это его высота, а она задаётся токеном --gr-sparkline-height либо контейнером.

interface GrSparklineConfigurableProps {
    variant: 'line' | 'area';
    summary: boolean;
}

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

grSparklineSafelistconst

const grSparklineSafelist: string[];

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

GrSparklinePropsinterface

Линия без рамы: в ячейку таблицы, в карточку показателя, рядом с числом. Ни осей, ни легенды, ни тултипа, ни замера контейнера — поэтому его не страшно поставить сотней штук в GrDataTable. Рисунок живёт в фиксированной системе координат и растягивается по контейнеру. Он **неинтерактивен**, и это меняет доступность: role="img" с осмысленным именем здесь честнее оверлея с клавиатурой — точек не разглядеть, а число рядом уже написано.

interface GrSparklineProps {
    /** Голый ряд чисел либо точки. `null` — пропуск, линия рвётся. */
    data: readonly (number | null)[] | readonly GrChartPoint[];
    /** Вид: `line` (по умолчанию) или `area` — линия с заливкой под ней. */
    variant?: 'line' | 'area';
    /** Цвет линии. Не задан — токен `--gr-sparkline-color`. */
    color?: string;
    /** Автоматическая текстовая сводка для скринридера. */
    summary?: boolean;
    /** Формат чисел в текстовой сводке для скринридера: знаки после запятой и разделители. */
    valueFormat?: GrChartNumberFormat;
    /** BCP-47 локаль чисел сводки. Не задана — язык переводов приложения, иначе `en`. */
    locale?: string;
    /** Своё имя вместо сводки. */
    ariaLabel?: string;
}

Доступность

Паттерн APG

Клавиатуры нет вовсе: компонент неинтерактивен и объявляет себя role="img" со сводкой

Клавиша	Действие
—	—

Полный контракт пакета: docs/keyboard.md ↗

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

Осей нет намеренно

Без осей у линии нет масштаба, и сравнивать две спарклайны между собой нельзя: каждая нормируется по своему ряду, поэтому одинаковый на вид подъём в двух строках таблицы может означать плюс два процента и плюс двести. Спарклайн отвечает «росло или падало» — на «насколько» отвечает соседняя колонка с числом.

Длинный ряд сокращается сам

Холст спарклайна фиксирован (viewBox шириной сто единиц), поэтому бюджет вершин известен заранее и замерять нечего: ряд длиннее бюджета прореживается по LTTB без единого пропа. Сотня спарклайнов в колонке таблицы перестаёт складывать сотню тысяч вершин ради рисунка шириной в пару сантиметров, а форма и одиночные выбросы остаются на месте — ../model.md, раздел «Прореживание — проекция, а не данные».

Ни курсора, ни клавиатуры

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