@gravity-ui/chartkit 7.60.5 → 7.61.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -16,11 +16,11 @@ Each plugin renderer is lazy-loaded, so the underlying library code is only down
16
16
 
17
17
  ## Table of contents
18
18
 
19
- - [Get started](#get-started)
19
+ - [Get started](#getting-started)
20
20
  - [Updating charting packages](#updating-charting-packages)
21
21
  - [Development](#development)
22
22
 
23
- ## Get started
23
+ ## Getting started
24
24
 
25
25
  ### Requirements
26
26
 
@@ -206,3 +206,34 @@ npm run test:docker:update
206
206
  ### Contributing
207
207
 
208
208
  Please refer to the [contributing guide](CONTRIBUTING.md) before submitting a pull request.
209
+
210
+ ## License
211
+
212
+ Distributed under the MIT License. See [LICENSE](LICENSE) for details.
213
+
214
+ ## For AI agents
215
+
216
+ A plugin-dispatching React component that renders charts from multiple Gravity UI charting libraries through one `<ChartKit type="..." data={...} />` API — reach for it when you need a single lazy-loading entry point for mixed chart types, instead of importing each chart library directly.
217
+
218
+ ### When to use
219
+
220
+ - Rendering more than one charting engine (e.g. `gravity-charts` + `yagr`) behind one consistent component.
221
+ - Lazy-loading chart bundles — each plugin's renderer is `React.lazy`, so a library's code is only fetched when its chart type is actually shown.
222
+ - Bundling charts into a Gravity UI app that wants mobile-friendly tooltips and unified theming out of the box.
223
+
224
+ ### When not to use
225
+
226
+ - For a single chart type only, import [`@gravity-ui/charts`](https://github.com/gravity-ui/charts) (general) or [`@gravity-ui/yagr`](https://github.com/gravity-ui/yagr) (high-performance time-series) directly — the plugin registry is overhead for one engine.
227
+ - To compose a dashboard grid of widgets, use [`@gravity-ui/dashkit`](https://github.com/gravity-ui/dashkit) — ChartKit renders a chart; DashKit arranges many widgets.
228
+
229
+ ### Common pitfalls
230
+
231
+ - **Rendering `<ChartKit>` before `settings.set({plugins: [...]})`** — the global plugin registry must be populated at app entry; an unregistered `type` throws at render time.
232
+ - **Hallucinated prop `chartType` / `library`** — the dispatch prop is `type` (e.g. `type="gravity-charts"`), and the data is `data`.
233
+ - **Forgetting a container height** — `ChartKit` fills its parent; without an explicit height on the wrapper, the chart collapses to zero.
234
+ - **Expecting plugins to be bundled** — plugin renderers (`@gravity-ui/chartkit/gravity-charts`, `.../yagr`) are lazy; the first render of a type fetches its bundle.
235
+ - **Missing the uikit styles import** — theming depends on `@gravity-ui/uikit/styles/styles.css`; without it, charts render unstyled.
236
+
237
+ ## Documentation for AI agents
238
+
239
+ Agent-readable documentation for the installed version is located in `node_modules/@gravity-ui/chartkit/build/docs/INDEX.md`.
@@ -0,0 +1,111 @@
1
+ # @gravity-ui/chartkit documentation
2
+
3
+ Documentation for the **installed** version of `@gravity-ui/chartkit`.
4
+ Your training data may be outdated — these files are the source of truth.
5
+
6
+ Paths are relative to this file (`node_modules/@gravity-ui/chartkit/build/docs/`).
7
+
8
+ ## For AI agents
9
+
10
+ A plugin-dispatching React component that renders charts from multiple Gravity UI charting libraries through one `<ChartKit type="..." data={...} />` API — reach for it when you need a single lazy-loading entry point for mixed chart types, instead of importing each chart library directly.
11
+
12
+ ### When to use
13
+
14
+ - Rendering more than one charting engine (e.g. `gravity-charts` + `yagr`) behind one consistent component.
15
+ - Lazy-loading chart bundles — each plugin's renderer is `React.lazy`, so a library's code is only fetched when its chart type is actually shown.
16
+ - Bundling charts into a Gravity UI app that wants mobile-friendly tooltips and unified theming out of the box.
17
+
18
+ ### When not to use
19
+
20
+ - For a single chart type only, import [`@gravity-ui/charts`](https://github.com/gravity-ui/charts) (general) or [`@gravity-ui/yagr`](https://github.com/gravity-ui/yagr) (high-performance time-series) directly — the plugin registry is overhead for one engine.
21
+ - To compose a dashboard grid of widgets, use [`@gravity-ui/dashkit`](https://github.com/gravity-ui/dashkit) — ChartKit renders a chart; DashKit arranges many widgets.
22
+
23
+ ### Common pitfalls
24
+
25
+ - **Rendering `<ChartKit>` before `settings.set({plugins: [...]})`** — the global plugin registry must be populated at app entry; an unregistered `type` throws at render time.
26
+ - **Hallucinated prop `chartType` / `library`** — the dispatch prop is `type` (e.g. `type="gravity-charts"`), and the data is `data`.
27
+ - **Forgetting a container height** — `ChartKit` fills its parent; without an explicit height on the wrapper, the chart collapses to zero.
28
+ - **Expecting plugins to be bundled** — plugin renderers (`@gravity-ui/chartkit/gravity-charts`, `.../yagr`) are lazy; the first render of a type fetches its bundle.
29
+ - **Missing the uikit styles import** — theming depends on `@gravity-ui/uikit/styles/styles.css`; without it, charts render unstyled.
30
+
31
+ ## Install
32
+
33
+ ```shell
34
+ npm install @gravity-ui/chartkit @gravity-ui/uikit
35
+ ```
36
+
37
+ ## Usage
38
+
39
+ ### Requirements
40
+
41
+ - React 16, 17, or 18
42
+ - `[@gravity-ui/uikit](https://github.com/gravity-ui/uikit)` — required peer dependency (provides theming and UI primitives)
43
+
44
+ ### Styles
45
+
46
+ Import the styles from `@gravity-ui/uikit` in your entry point:
47
+
48
+ ```tsx
49
+ import '@gravity-ui/uikit/styles/fonts.css';
50
+ import '@gravity-ui/uikit/styles/styles.css';
51
+ ```
52
+
53
+ For full setup details see the [uikit styles guide](https://github.com/gravity-ui/uikit?tab=readme-ov-file#styles).
54
+
55
+ ### Basic usage
56
+
57
+ ChartKit uses a global plugin registry. Call `settings.set` once at your app entry point to register the plugins you need. When `<ChartKit type="..." />` renders, it looks up the matching plugin — if none is found, an error is thrown. Each plugin's renderer is a `React.lazy` component, so its code is fetched only when ChartKit first appears in the UI.
58
+
59
+ You can register multiple plugins at once:
60
+
61
+ ```ts
62
+ settings.set({plugins: [GravityChartsPlugin, YagrPlugin]});
63
+ ```
64
+
65
+ Or call `settings.set` multiple times — it merges the plugin list rather than replacing it.
66
+
67
+ **Basic example:**
68
+
69
+ ```tsx
70
+ import {ThemeProvider} from '@gravity-ui/uikit';
71
+ import ChartKit, {settings} from '@gravity-ui/chartkit';
72
+ import {GravityChartsPlugin} from '@gravity-ui/chartkit/gravity-charts';
73
+
74
+ import '@gravity-ui/uikit/styles/fonts.css';
75
+ import '@gravity-ui/uikit/styles/styles.css';
76
+
77
+ settings.set({plugins: [GravityChartsPlugin]});
78
+
79
+ const data = {
80
+ series: {
81
+ data: [
82
+ {
83
+ type: 'line',
84
+ name: 'Series',
85
+ data: [
86
+ {x: 0, y: 10},
87
+ {x: 1, y: 25},
88
+ {x: 2, y: 18},
89
+ {x: 3, y: 30},
90
+ ],
91
+ },
92
+ ],
93
+ },
94
+ };
95
+
96
+ export default function App() {
97
+ return (
98
+ <ThemeProvider theme="light">
99
+ <div style={{height: 300}}>
100
+ <ChartKit type="gravity-charts" data={data} />
101
+ </div>
102
+ </ThemeProvider>
103
+ );
104
+ }
105
+ ```
106
+
107
+ `ChartKit` adapts to its parent's size — make sure the container has an explicit height.
108
+
109
+ ## Guides
110
+
111
+ - [Testing Guide](./guides/testing.md)
@@ -0,0 +1,136 @@
1
+ # Testing Guide
2
+
3
+ ## Scripts
4
+
5
+ | Script | Description |
6
+ | --------------------------------- | ----------------------------------------------------------------------------------------- |
7
+ | `npm test` | Run unit tests once |
8
+ | `npm run test:watch` | Run unit tests in watch mode |
9
+ | `npm run test:unit` | Alias for `npm test` |
10
+ | `npm run test:coverage` | Unit tests with coverage report (saved to `reports/coverage/`) |
11
+ | `npm run test:storybook` | Run all Storybook stories as tests |
12
+ | `npm run test:docker` | Run visual tests in Docker (Linux) — use this for visual testing |
13
+ | `npm run test:docker:update` | Update baseline screenshots via Docker |
14
+ | `npm run test:docker:clear-cache` | Clear Docker image cache |
15
+ | `npm run test:visual` | Run visual tests locally (macOS) — used internally by Docker scripts, not for regular use |
16
+
17
+ ## Test Projects
18
+
19
+ The project uses [Vitest](https://vitest.dev/) with three test projects:
20
+
21
+ | Project | Environment | Pattern |
22
+ | ----------- | ------------------ | ----------------------------- |
23
+ | `unit` | Node | `src/**/*.test.ts?(x)` |
24
+ | `storybook` | Browser (Chromium) | Storybook stories |
25
+ | `visual` | Browser (Chromium) | `src/**/*.visual.test.ts?(x)` |
26
+
27
+ ## Unit Tests
28
+
29
+ Standard Vitest tests running in Node. No browser, no screenshots.
30
+
31
+ Coverage report is saved to `reports/coverage/`.
32
+
33
+ ## Visual (Screenshot) Tests
34
+
35
+ Visual tests use Playwright via `vitest-browser-react` and capture screenshots to compare against baselines.
36
+
37
+ ### Running visual tests
38
+
39
+ **Always run visual tests via Docker** to ensure consistent Linux-based screenshots:
40
+
41
+ ```bash
42
+ npm run test:docker # run visual tests in Docker
43
+ npm run test:docker:update # update baseline screenshots
44
+ ```
45
+
46
+ Running `npm run test:visual` directly produces macOS screenshots (darwin) which are not committed and not used as baselines. This command is used internally by the Docker scripts.
47
+
48
+ ### How screenshots work
49
+
50
+ Screenshots are stored next to the test file in a `__screenshots__/` directory. The filename is generated automatically.
51
+
52
+ Only Linux screenshots (generated via Docker) are committed to the repository — they serve as the CI baseline.
53
+
54
+ ### Adding a new visual test
55
+
56
+ 1. Create `src/plugins/<plugin>/__tests__/<Name>.visual.test.tsx`
57
+ 2. Use `toMatchScreenshot()` for screenshot assertions:
58
+
59
+ ```tsx
60
+ import React from 'react';
61
+ import {render} from '../../../../test-utils/utils.js';
62
+ import {ChartKit} from '../../../components/ChartKit.js';
63
+ import {settings} from '../../../libs/index.js';
64
+ import {MyPlugin} from '../index.js';
65
+
66
+ describe('MyPlugin visual tests', () => {
67
+ const options = {providers: {theme: 'light'}};
68
+
69
+ test('default state', async () => {
70
+ settings.set({plugins: [MyPlugin]});
71
+ const screen = await render(
72
+ <div style={{height: 300, width: '100%'}}>
73
+ <ChartKit id="my-chart" type="my-type" data={data} />
74
+ </div>,
75
+ options,
76
+ );
77
+ await expect(screen.getByRole('img')).toMatchScreenshot();
78
+ });
79
+ });
80
+ ```
81
+
82
+ 3. Generate the baseline screenshot:
83
+
84
+ ```bash
85
+ npm run test:docker:update
86
+ ```
87
+
88
+ 4. Commit the generated `*-linux.png` file.
89
+
90
+ ### Behavior-only visual tests
91
+
92
+ Not every visual test needs a screenshot. Use `expect.element().toBeVisible()` for asserting rendered state without capturing a screenshot:
93
+
94
+ ```tsx
95
+ test('no data state', async () => {
96
+ const screen = await render(<ChartKit id="empty" type="my-type" data={emptyData} />, options);
97
+ await expect.element(screen.getByText('No data')).toBeVisible();
98
+ });
99
+ ```
100
+
101
+ ### Updating screenshots
102
+
103
+ If a visual change is intentional, update the baselines:
104
+
105
+ **Locally (via Docker):**
106
+
107
+ ```bash
108
+ npm run test:docker:update
109
+ ```
110
+
111
+ **On a pull request** — comment `/update-screenshots` on the PR. The bot will run the update workflow and push the new screenshots to the branch.
112
+
113
+ ## Storybook Tests
114
+
115
+ Story-based tests run all stories through `@storybook/addon-vitest`. They verify stories render without errors and can include story-level play functions.
116
+
117
+ ```bash
118
+ npm run test:storybook
119
+ ```
120
+
121
+ ## CI
122
+
123
+ The CI pipeline (`.github/workflows/ci.yml`) runs:
124
+
125
+ - Lint + typecheck (`verify_files` job)
126
+ - Unit tests with coverage (`tests` job — runs `npm run test:unit -- --coverage`)
127
+ - Visual tests (`visual_tests` job — runs `npm run test:visual` on Ubuntu, matching the committed Linux baselines)
128
+
129
+ To update baselines after an intentional visual change, comment `/update-screenshots` on the PR.
130
+
131
+ ### Test reports
132
+
133
+ After CI completes, test and coverage reports are uploaded to S3 and linked in a PR comment:
134
+
135
+ - Tests report: HTML Vitest report
136
+ - Coverage report: LCOV coverage report
@@ -1,6 +1,6 @@
1
1
  import type { MinimalValidConfig, RawSerieData, YagrConfig } from '@gravity-ui/yagr';
2
2
  import type Yagr from '@gravity-ui/yagr';
3
- import { ChartKitProps } from 'src/types';
3
+ import type { ChartKitProps } from '../../types';
4
4
  export type { default as Yagr } from '@gravity-ui/yagr';
5
5
  export type { YagrReactRef } from '@gravity-ui/yagr/react';
6
6
  export * from '@gravity-ui/yagr/dist/types';
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@gravity-ui/chartkit",
3
- "version": "7.60.5",
3
+ "version": "7.61.0",
4
4
  "description": "React component used to render charts based on any sources you need",
5
5
  "license": "MIT",
6
6
  "repository": "git@github.com:gravity-ui/ChartKit.git",
@@ -47,7 +47,7 @@
47
47
  ],
48
48
  "dependencies": {
49
49
  "@bem-react/classname": "^1.6.0",
50
- "@gravity-ui/charts": "^1.56.1",
50
+ "@gravity-ui/charts": "^1.57.1",
51
51
  "@gravity-ui/date-utils": "^2.1.0",
52
52
  "@gravity-ui/i18n": "^1.0.0",
53
53
  "@gravity-ui/yagr": "^4.13.8",
@@ -58,6 +58,7 @@
58
58
  "devDependencies": {
59
59
  "@gravity-ui/eslint-config": "^4.2.1",
60
60
  "@gravity-ui/prettier-config": "^1.1.0",
61
+ "@gravity-ui/readme-validator": "^1.3.0",
61
62
  "@gravity-ui/stylelint-config": "^4.0.1",
62
63
  "@gravity-ui/tsconfig": "^1.0.0",
63
64
  "@gravity-ui/uikit": "^7.4.0",
@@ -121,6 +122,7 @@
121
122
  "clean": "gulp clean",
122
123
  "start": "storybook dev -p 7007",
123
124
  "build": "gulp",
125
+ "build:docs": "gulp copy-docs",
124
126
  "lint:js": "eslint .",
125
127
  "lint:js:fix": "eslint . --fix",
126
128
  "lint:styles": "cross-env stylelint '{styles,src}/**/*.scss'",