tgui-dashboard

Data-компоненты для Telegram Mini Apps UI — desktop / admin-компаньон к мобильному киту.

English · Русский

Зачем

@telegram-apps/telegram-ui отлично делает нативный мобильный «хром» — списки, ячейки, секции, кнопки — но в нём нет таблиц, графиков, воронок и KPI-карточек. Как только начинаешь делать админку, экран аналитики или десктоп-дашборд, упираешься в эту стену.

tgui-dashboard закрывает пробел. Каждый компонент читает CSS-переменные telegram-ui --tgui--*, поэтому автоматически наследует реальную тему пользователя, светлый/тёмный режим и платформу — выглядит как часть кита, а не чужеродная вставка.

• 🎨 Нативный вид — на токенах --tgui--, следует за живой темой
• 📊 Те самые тяжёлые компоненты — таблица, area-график, спарклайн, воронка, KPI, master-detail, badge, skeleton
• 🪶 Headless-мощь — DataTable на TanStack Table, графики на Recharts
• 🧩 Маленький и tree-shakeable — ESM + CJS, полные типы TypeScript, MIT
• 🌗 Светлая и тёмная тема из коробки (превью выше)

Соответствие: цвета, радиусы и типографика взяты из токенов @telegram-apps/telegram-ui v2.1.13 — Card 20px, Section 12px, hint #707579, green #31D158, а каждый компонент читает живые переменные --tgui--, поэтому внутри реального Telegram точно следует теме пользователя.

Установка

npm i tgui-dashboard @tanstack/react-table recharts
# peers: react, react-dom и @telegram-apps/telegram-ui (для переменных темы)

Оберни приложение в AppRoot из telegram-ui, чтобы переменные --tgui-- были определены:

import { AppRoot } from '@telegram-apps/telegram-ui';
import '@telegram-apps/telegram-ui/dist/styles.css';

export default function App() {
  return (
    <AppRoot>
      <Dashboard />
    </AppRoot>
  );
}

Компоненты

StatCard

Компактная KPI-карточка. Разложи несколько в CSS-грид — получишь шапку дашборда.

import { StatCard } from 'tgui-dashboard';

<StatCard label="Новые лиды" value={128} delta={12} hint="за 7 дней" />
<StatCard label="КЭВ назначено" value={34} delta={-4} hint="за 7 дней" />
<StatCard label="Ср. ответ" value="1:40" />

label · value · delta (%, +зелёная ▲ / −красная ▼) · hint · icon

DataTable

Таблица с сортировкой и пагинацией на headless-движке TanStack Table.

import { DataTable } from 'tgui-dashboard';
import type { ColumnDef } from '@tanstack/react-table';

const columns: ColumnDef<Lead>[] = [
  { accessorKey: 'name', header: 'Клиент' },
  { accessorKey: 'stage', header: 'Стадия' },
];

<DataTable columns={columns} data={leads} pageSize={20} onRowClick={openLead} />

columns · data · pageSize=10 · enableSorting=true · enablePagination=true · emptyText · onRowClick

AreaChart

Area-график на Recharts, темизированный под палитру токенов.

import { AreaChart } from 'tgui-dashboard';

<AreaChart
  data={daily}
  xKey="day"
  series={[{ key: 'leads', label: 'Лиды' }, { key: 'booked', label: 'КЭВ' }]}
  height={240}
/>

data · xKey · series[{ key, label?, color? }] · height=240

Sparkline

Крошечный трендовый график без зависимостей — для инлайна (например, внутри StatCard).

import { Sparkline } from 'tgui-dashboard';

<Sparkline data={[4, 6, 5, 8, 7, 11, 14]} />

data · width=120 · height=36 · color · area=true · strokeWidth=2

Funnel

Горизонтальная воронка конверсии — по бару на стадию, с процентом конверсии.

import { Funnel } from 'tgui-dashboard';

<Funnel steps={[
  { label: 'Квалификация', value: 128 },
  { label: 'Прогрев', value: 86 },
  { label: 'Запись (КЭВ)', value: 41 },
  { label: 'BOOKED', value: 27 },
]} />

steps[{ label, value, color? }] · showPercent=true

MasterDetail

Двухпанельный лейаут «список + деталь» (например, список лидов рядом с выбранным диалогом). Заточен под десктоп/админку.

import { MasterDetail } from 'tgui-dashboard';

<MasterDetail
  list={<LeadsList onSelect={setLead} />}
  detail={lead ? <Conversation lead={lead} /> : null}
  listWidth={340}
/>

list · detail · listWidth=340 · minHeight=480 · emptyDetail

Badge

Небольшой пилл для статусов / категорий / стадий воронки.

import { Badge } from 'tgui-dashboard';

<Badge tone="green">ААА</Badge>
<Badge tone="accent">ВВВ</Badge>
<Badge tone="gray">ССС</Badge>
<Badge tone="accent" variant="solid">Новый</Badge>

tone: 'accent' | 'green' | 'red' | 'gray' · variant: 'soft' | 'solid'

Skeleton

Пульсирующий плейсхолдер для состояний загрузки.

import { Skeleton } from 'tgui-dashboard';

<Skeleton width={180} height={20} />
<Skeleton width={40} height={40} radius="50%" />

width · height · radius

Темизация

Экспорт tokens отдаёт CSS-переменные telegram-ui как готовые строки var(...), чтобы твои компоненты попадали в стиль кита:

import { tokens } from 'tgui-dashboard';

<div style={{ background: tokens.cardBg, color: tokens.text, borderRadius: 20 }} />

bg · secondaryBg · tertiaryBg · sectionBg · cardBg · headerBg · text · hint · subtitle · sectionHeader · link · accent · divider · outline · skeleton · green · destructive · fontFamily · series[]

Роадмап

• [x] AreaChart / Sparkline
• [x] Funnel
• [x] MasterDetail
• [x] Badge, Skeleton
• [ ] Фильтры колонок и фасетный поиск для DataTable
• [ ] BarChart / Donut
• [ ] Виртуализация строк для очень больших таблиц

Контрибьютинг

Issues и PR приветствуются. Держите компоненты на токенах (без хардкод-цветов), чтобы они оставались theme-aware.

npm i && npm run build

Лицензия

MIT © skiddgoddamn

Превью — иллюстративные SVG-макеты на реальной палитре telegram-ui v2.1.13.