§Gravity UI ChartKit · npm package License CI storybook

React-компонент с плагинизированной архитектурой и единым интерфейсом рендеринга для нескольких библиотек графиков. Зарегистрируйте плагины и рендерите графики через <ChartKit type="..." data={...} /> — ChartKit сам направляет вызов нужному рендереру.

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

Когда подходит:

• Нужны современные декларативные графики (gravity-charts) или временные ряды / мониторинг (yagr)
• Нужны разные типы графиков под одним согласованным API
• Вы строите продукт в экосистеме Gravity UI

Когда лучше не использовать:

• Нужна только одна конкретная библиотека графиков — лучше подключить @gravity-ui/charts напрямую

§Содержание

• С чего начать
• Разработка

§С чего начать

§Требования

• React 16, 17 или 18
• @gravity-ui/uikit — обязательная peer-зависимость (темизация и UI-примитивы)

§Установка

npm install @gravity-ui/chartkit @gravity-ui/uikit

§Стили

Подключите стили @gravity-ui/uikit в точке входа приложения:

import '@gravity-ui/uikit/styles/fonts.css';
import '@gravity-ui/uikit/styles/styles.css';

Подробнее о настройке стилей — в руководстве по стилям uikit.

§Базовое использование

ChartKit использует глобальный реестр плагинов. Один раз при запуске приложения вызовите settings.set и передайте нужные плагины. При рендере <ChartKit type="..." /> ChartKit ищет подходящий плагин — если плагин не найден, выбрасывается ошибка. Рендерер каждого плагина — компонент React.lazy, поэтому его код загружается только при появлении ChartKit в UI.

Можно зарегистрировать несколько плагинов за раз:

settings.set({plugins: [GravityChartsPlugin, YagrPlugin]});

Или вызывать settings.set несколько раз — список плагинов объединяется, а не заменяется целиком.

Простой пример:

import {ThemeProvider} from '@gravity-ui/uikit';
import ChartKit, {settings} from '@gravity-ui/chartkit';
import {GravityChartsPlugin} from '@gravity-ui/chartkit/gravity-charts';

import '@gravity-ui/uikit/styles/fonts.css';
import '@gravity-ui/uikit/styles/styles.css';

settings.set({plugins: [GravityChartsPlugin]});

const data = {
  series: {
    data: [
      {
        type: 'line',
        name: 'Series',
        data: [
          {x: 0, y: 10},
          {x: 1, y: 25},
          {x: 2, y: 18},
          {x: 3, y: 30},
        ],
      },
    ],
  },
};

export default function App() {
  return (
    <ThemeProvider theme="light">
      <div style={{height: 300}}>
        <ChartKit type="gravity-charts" data={data} />
      </div>
    </ThemeProvider>
  );
}

ChartKit подстраивается под размер родителя — задайте контейнеру явную высоту.

§Разработка

§Предварительные требования

• Node.js 22 (см. .nvmrc)
• npm 10 или новее

§Настройка

Клонируйте репозиторий и установите зависимости:

git clone https://github.com/gravity-ui/ChartKit.git
cd ChartKit
npm ci

§Запуск Storybook

npm run start

Storybook будет доступен по адресу http://localhost:7007.

§Разработка с локальной зависимостью

Чтобы править зависимость (например, @gravity-ui/charts) и сразу видеть изменения в Storybook без публикации в npm:

1. Локальная ссылка на пакет

# В локальной копии @gravity-ui/charts:
git clone https://github.com/gravity-ui/charts.git
cd charts
npm ci
# внесите изменения
npm run build
npm link

# В ChartKit:
npm link @gravity-ui/charts

2. Настройка отслеживания локального пакета

Создайте в корне ChartKit файл .env.local (он в .gitignore):

LOCAL_PKG=@gravity-ui/charts

Так Vite будет следить за этим пакетом в node_modules и не пребандлить его. После пересборки @gravity-ui/charts Storybook подхватит изменения с горячей перезагрузкой.

Для нескольких пакетов через запятую:

LOCAL_PKG=@gravity-ui/charts,@gravity-ui/uikit

3. Запуск Storybook

npm run start

4. Вернуть обычный пакет

Когда закончите:

1. Закомментируйте LOCAL_PKG в .env.local
2. Выполните в ChartKit npm install — симлинк заменится версией из реестра

# В ChartKit:
npm ci

§Запуск тестов

npm test

Визуальные регрессионные тесты запускаются в Docker для стабильных скриншотов в разных окружениях:

npm run test:docker

Чтобы обновить эталонные скриншоты после намеренных изменений UI:

npm run test:docker:update

§Участие в проекте

Перед отправкой pull request ознакомьтесь с руководством для контрибьюторов.