@gravity-ui/chartkit 8.12.0 → 8.12.1
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/LICENSE +1 -0
- package/README.md +32 -7
- package/build/docs/INDEX.md +30 -5
- package/package.json +17 -3
package/LICENSE
CHANGED
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Gravity UI ChartKit · [](https://www.npmjs.com/package/@gravity-ui/chartkit) [](LICENSE) [](https://github.com/gravity-ui/ChartKit/actions/workflows/ci.yml?query=branch:main) [](https://preview.gravity-ui.com/chartkit/)
|
|
2
2
|
|
|
3
|
-
Plugin-based React component that
|
|
3
|
+
Plugin-based React component that renders charts from multiple charting libraries, such as Gravity Charts and Yagr, through a single ChartKit API, with mobile-friendly tooltips and custom plugin support. You register one or more plugins and render charts via `<ChartKit type="..." data={...} />` — ChartKit dispatches to the correct renderer automatically.
|
|
4
4
|
|
|
5
5
|
Each plugin renderer is lazy-loaded, so the underlying library code is only downloaded when ChartKit is actually rendered in the UI. ChartKit also handles mobile-friendly tooltip display out of the box. You can use the built-in plugins or implement your own.
|
|
6
6
|
|
|
@@ -8,7 +8,7 @@ Each plugin renderer is lazy-loaded, so the underlying library code is only down
|
|
|
8
8
|
|
|
9
9
|
- You need modern declarative charts (`gravity-charts`) or time-series / monitoring charts (`yagr`)
|
|
10
10
|
- You need multiple chart types under a single consistent API
|
|
11
|
-
- You
|
|
11
|
+
- You want charts that follow the same light/dark theme as the rest of your UI out of the box
|
|
12
12
|
|
|
13
13
|
**When not to use:**
|
|
14
14
|
|
|
@@ -25,7 +25,7 @@ Each plugin renderer is lazy-loaded, so the underlying library code is only down
|
|
|
25
25
|
### Requirements
|
|
26
26
|
|
|
27
27
|
- React 16, 17, or 18
|
|
28
|
-
-
|
|
28
|
+
- [`@gravity-ui/uikit`](https://github.com/gravity-ui/uikit) — required peer dependency (provides theming and UI primitives)
|
|
29
29
|
|
|
30
30
|
### Install
|
|
31
31
|
|
|
@@ -98,6 +98,27 @@ export default function App() {
|
|
|
98
98
|
|
|
99
99
|
`ChartKit` adapts to its parent's size — make sure the container has an explicit height.
|
|
100
100
|
|
|
101
|
+
### SplitTooltip
|
|
102
|
+
|
|
103
|
+
The split-pane tooltip layout that `gravity-charts` uses on touch devices (`tooltip={{splitted: true}}`) is also available as a standalone component. It works with any content: it renders the main pane and the tooltip pane side by side (or stacked, depending on the container size) with a draggable resizer between them.
|
|
104
|
+
|
|
105
|
+
```tsx
|
|
106
|
+
import {SplitTooltip} from '@gravity-ui/chartkit';
|
|
107
|
+
|
|
108
|
+
export function Panel() {
|
|
109
|
+
return (
|
|
110
|
+
<div style={{height: 400}}>
|
|
111
|
+
<SplitTooltip
|
|
112
|
+
renderMainPane={() => <MyVisualization />}
|
|
113
|
+
renderTooltip={() => <MyTooltipContent />}
|
|
114
|
+
/>
|
|
115
|
+
</div>
|
|
116
|
+
);
|
|
117
|
+
}
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
See the `SplitTooltipProps` type for layout control, pane sizing and resizer options.
|
|
121
|
+
|
|
101
122
|
## Updating charting packages
|
|
102
123
|
|
|
103
124
|
ChartKit bundles two Gravity UI charting libraries as dependencies:
|
|
@@ -213,13 +234,16 @@ Distributed under the MIT License. See [LICENSE](LICENSE) for details.
|
|
|
213
234
|
|
|
214
235
|
## For AI agents
|
|
215
236
|
|
|
216
|
-
A plugin-
|
|
237
|
+
A plugin-based React component that renders charts from multiple charting libraries, such as Gravity Charts and Yagr, through a single `<ChartKit type="..." data={...} />` API, lazy-loading each library only when its chart type is rendered.
|
|
217
238
|
|
|
218
239
|
### When to use
|
|
219
240
|
|
|
220
|
-
- Rendering more than one charting engine
|
|
241
|
+
- Rendering more than one charting engine behind one consistent component: `gravity-charts` (declarative SVG charts via [`@gravity-ui/charts`](https://github.com/gravity-ui/charts)) and `yagr` (uPlot-based time-series via [`@gravity-ui/yagr`](https://github.com/gravity-ui/yagr)).
|
|
221
242
|
- 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
|
-
-
|
|
243
|
+
- Mobile-friendly tooltips out of the box — the chart and its tooltip are shown in resizable split panes instead of a hover popup; for `gravity-charts` turn it on with `<ChartKit type="gravity-charts" tooltip={{splitted: true}} />`.
|
|
244
|
+
- Using the split-pane tooltip layout on its own — `SplitTooltip` is a standalone component exported from the root entry: pass `renderMainPane` and `renderTooltip`, and it lays them out as resizable panes (vertical or horizontal, picked from the container size) for any content, not only ChartKit charts.
|
|
245
|
+
- Writing your own plugin — register `{type, renderer}` via `settings.set({plugins: [...]})`, where `renderer` is a `React.lazy` component; ChartKit dispatches to it by `type` exactly like to the built-in plugins.
|
|
246
|
+
- Consistent light/dark theming across every chart engine out of the box — the charts follow the `@gravity-ui/uikit` theme of the surrounding app.
|
|
223
247
|
|
|
224
248
|
### When not to use
|
|
225
249
|
|
|
@@ -230,8 +254,9 @@ A plugin-dispatching React component that renders charts from multiple Gravity U
|
|
|
230
254
|
|
|
231
255
|
- **Rendering `<ChartKit>` before `settings.set({plugins: [...]})`** — the global plugin registry must be populated at app entry; an unregistered `type` throws at render time.
|
|
232
256
|
- **Hallucinated prop `chartType` / `library`** — the dispatch prop is `type` (e.g. `type="gravity-charts"`), and the data is `data`.
|
|
257
|
+
- **Importing plugins from the root entry** — plugins live in subpath exports (e.g. `@gravity-ui/chartkit/gravity-charts`, `@gravity-ui/chartkit/yagr`); the root `@gravity-ui/chartkit` entry does not re-export them.
|
|
258
|
+
- **Assuming one `data` shape for every `type`** — the shape depends on the plugin, e.g. `gravity-charts` takes `ChartData` from `@gravity-ui/charts` (`{series: {data: [...]}}`), while `yagr` takes `{data: {graphs, timeline}, libraryConfig}` with `libraryConfig` required.
|
|
233
259
|
- **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
260
|
- **Missing the uikit styles import** — theming depends on `@gravity-ui/uikit/styles/styles.css`; without it, charts render unstyled.
|
|
236
261
|
|
|
237
262
|
## Documentation for AI agents
|
package/build/docs/INDEX.md
CHANGED
|
@@ -7,13 +7,16 @@ Paths are relative to this file (`node_modules/@gravity-ui/chartkit/build/docs/`
|
|
|
7
7
|
|
|
8
8
|
## For AI agents
|
|
9
9
|
|
|
10
|
-
A plugin-
|
|
10
|
+
A plugin-based React component that renders charts from multiple charting libraries, such as Gravity Charts and Yagr, through a single `<ChartKit type="..." data={...} />` API, lazy-loading each library only when its chart type is rendered.
|
|
11
11
|
|
|
12
12
|
### When to use
|
|
13
13
|
|
|
14
|
-
- Rendering more than one charting engine
|
|
14
|
+
- Rendering more than one charting engine behind one consistent component: `gravity-charts` (declarative SVG charts via [`@gravity-ui/charts`](https://github.com/gravity-ui/charts)) and `yagr` (uPlot-based time-series via [`@gravity-ui/yagr`](https://github.com/gravity-ui/yagr)).
|
|
15
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
|
-
-
|
|
16
|
+
- Mobile-friendly tooltips out of the box — the chart and its tooltip are shown in resizable split panes instead of a hover popup; for `gravity-charts` turn it on with `<ChartKit type="gravity-charts" tooltip={{splitted: true}} />`.
|
|
17
|
+
- Using the split-pane tooltip layout on its own — `SplitTooltip` is a standalone component exported from the root entry: pass `renderMainPane` and `renderTooltip`, and it lays them out as resizable panes (vertical or horizontal, picked from the container size) for any content, not only ChartKit charts.
|
|
18
|
+
- Writing your own plugin — register `{type, renderer}` via `settings.set({plugins: [...]})`, where `renderer` is a `React.lazy` component; ChartKit dispatches to it by `type` exactly like to the built-in plugins.
|
|
19
|
+
- Consistent light/dark theming across every chart engine out of the box — the charts follow the `@gravity-ui/uikit` theme of the surrounding app.
|
|
17
20
|
|
|
18
21
|
### When not to use
|
|
19
22
|
|
|
@@ -24,8 +27,9 @@ A plugin-dispatching React component that renders charts from multiple Gravity U
|
|
|
24
27
|
|
|
25
28
|
- **Rendering `<ChartKit>` before `settings.set({plugins: [...]})`** — the global plugin registry must be populated at app entry; an unregistered `type` throws at render time.
|
|
26
29
|
- **Hallucinated prop `chartType` / `library`** — the dispatch prop is `type` (e.g. `type="gravity-charts"`), and the data is `data`.
|
|
30
|
+
- **Importing plugins from the root entry** — plugins live in subpath exports (e.g. `@gravity-ui/chartkit/gravity-charts`, `@gravity-ui/chartkit/yagr`); the root `@gravity-ui/chartkit` entry does not re-export them.
|
|
31
|
+
- **Assuming one `data` shape for every `type`** — the shape depends on the plugin, e.g. `gravity-charts` takes `ChartData` from `@gravity-ui/charts` (`{series: {data: [...]}}`), while `yagr` takes `{data: {graphs, timeline}, libraryConfig}` with `libraryConfig` required.
|
|
27
32
|
- **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
33
|
- **Missing the uikit styles import** — theming depends on `@gravity-ui/uikit/styles/styles.css`; without it, charts render unstyled.
|
|
30
34
|
|
|
31
35
|
## Install
|
|
@@ -39,7 +43,7 @@ npm install @gravity-ui/chartkit @gravity-ui/uikit
|
|
|
39
43
|
### Requirements
|
|
40
44
|
|
|
41
45
|
- React 16, 17, or 18
|
|
42
|
-
-
|
|
46
|
+
- [`@gravity-ui/uikit`](https://github.com/gravity-ui/uikit) — required peer dependency (provides theming and UI primitives)
|
|
43
47
|
|
|
44
48
|
### Styles
|
|
45
49
|
|
|
@@ -106,6 +110,27 @@ export default function App() {
|
|
|
106
110
|
|
|
107
111
|
`ChartKit` adapts to its parent's size — make sure the container has an explicit height.
|
|
108
112
|
|
|
113
|
+
### SplitTooltip
|
|
114
|
+
|
|
115
|
+
The split-pane tooltip layout that `gravity-charts` uses on touch devices (`tooltip={{splitted: true}}`) is also available as a standalone component. It works with any content: it renders the main pane and the tooltip pane side by side (or stacked, depending on the container size) with a draggable resizer between them.
|
|
116
|
+
|
|
117
|
+
```tsx
|
|
118
|
+
import {SplitTooltip} from '@gravity-ui/chartkit';
|
|
119
|
+
|
|
120
|
+
export function Panel() {
|
|
121
|
+
return (
|
|
122
|
+
<div style={{height: 400}}>
|
|
123
|
+
<SplitTooltip
|
|
124
|
+
renderMainPane={() => <MyVisualization />}
|
|
125
|
+
renderTooltip={() => <MyTooltipContent />}
|
|
126
|
+
/>
|
|
127
|
+
</div>
|
|
128
|
+
);
|
|
129
|
+
}
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
See the `SplitTooltipProps` type for layout control, pane sizing and resizer options.
|
|
133
|
+
|
|
109
134
|
## Guides
|
|
110
135
|
|
|
111
136
|
- [Testing Guide](./guides/testing.md)
|
package/package.json
CHANGED
|
@@ -1,7 +1,21 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@gravity-ui/chartkit",
|
|
3
|
-
"version": "8.12.
|
|
4
|
-
"description": "React component
|
|
3
|
+
"version": "8.12.1",
|
|
4
|
+
"description": "Plugin-based React component that renders charts from multiple charting libraries, such as Gravity Charts and Yagr, through a single ChartKit API, with mobile-friendly tooltips and custom plugin support",
|
|
5
|
+
"keywords": [
|
|
6
|
+
"charts",
|
|
7
|
+
"chart",
|
|
8
|
+
"charting",
|
|
9
|
+
"data-visualization",
|
|
10
|
+
"dataviz",
|
|
11
|
+
"react",
|
|
12
|
+
"react-component",
|
|
13
|
+
"typescript",
|
|
14
|
+
"gravity-ui",
|
|
15
|
+
"chartkit",
|
|
16
|
+
"yagr"
|
|
17
|
+
],
|
|
18
|
+
"homepage": "https://github.com/gravity-ui/ChartKit#readme",
|
|
5
19
|
"license": "MIT",
|
|
6
20
|
"repository": "git@github.com:gravity-ui/ChartKit.git",
|
|
7
21
|
"main": "build/index.js",
|
|
@@ -47,7 +61,7 @@
|
|
|
47
61
|
],
|
|
48
62
|
"dependencies": {
|
|
49
63
|
"@bem-react/classname": "^1.6.0",
|
|
50
|
-
"@gravity-ui/charts": "^1.73.
|
|
64
|
+
"@gravity-ui/charts": "^1.73.1",
|
|
51
65
|
"@gravity-ui/date-utils": "^2.1.0",
|
|
52
66
|
"@gravity-ui/i18n": "^1.0.0",
|
|
53
67
|
"@gravity-ui/yagr": "^5.0.0",
|