@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 +33 -2
- package/build/docs/INDEX.md +111 -0
- package/build/docs/guides/testing.md +136 -0
- package/build/plugins/yagr/types.d.ts +1 -1
- package/package.json +4 -2
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](#
|
|
19
|
+
- [Get started](#getting-started)
|
|
20
20
|
- [Updating charting packages](#updating-charting-packages)
|
|
21
21
|
- [Development](#development)
|
|
22
22
|
|
|
23
|
-
##
|
|
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 '
|
|
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.
|
|
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.
|
|
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'",
|