@gravity-ui/chartkit 8.11.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/components/ChartKit.js +2 -4
- package/build/components/SplitPane/SplitPane.d.ts +1 -0
- package/build/components/SplitPane/SplitPane.js +8 -0
- package/build/components/SplitTooltip/SplitTooltip.d.ts +16 -2
- package/build/components/SplitTooltip/SplitTooltip.js +71 -64
- package/build/docs/INDEX.md +30 -5
- package/build/plugins/gravity-charts/renderer/GravityChartsWidget.js +29 -4
- package/build/plugins/gravity-charts/renderer/withSplitPane/withSplitPane.d.ts +5 -1
- package/build/plugins/gravity-charts/renderer/withSplitPane/withSplitPane.js +17 -4
- package/build/types/index.d.ts +9 -1
- 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
|
|
@@ -25,10 +25,8 @@ const ChartKitComponent = (props) => {
|
|
|
25
25
|
const ChartComponent = plugin.renderer;
|
|
26
26
|
React.useImperativeHandle(instanceRef, () => ({
|
|
27
27
|
reflow(details) {
|
|
28
|
-
var _a;
|
|
29
|
-
|
|
30
|
-
widgetRef.current.reflow(details);
|
|
31
|
-
}
|
|
28
|
+
var _a, _b;
|
|
29
|
+
return (_b = (_a = widgetRef.current) === null || _a === void 0 ? void 0 : _a.reflow) === null || _b === void 0 ? void 0 : _b.call(_a, details);
|
|
32
30
|
},
|
|
33
31
|
}), []);
|
|
34
32
|
return (React.createElement(React.Suspense, { fallback: React.createElement(Loader, { renderPluginLoader: renderPluginLoader }) },
|
|
@@ -48,6 +48,7 @@ export declare class SplitPane extends React.Component<Props, State> {
|
|
|
48
48
|
private pane2;
|
|
49
49
|
constructor(props: Props);
|
|
50
50
|
componentDidMount(): void;
|
|
51
|
+
componentDidUpdate(previousProps: Props, previousState: State): void;
|
|
51
52
|
componentWillUnmount(): void;
|
|
52
53
|
render(): React.JSX.Element;
|
|
53
54
|
private onMouseDown;
|
|
@@ -177,6 +177,14 @@ export class SplitPane extends React.Component {
|
|
|
177
177
|
document.addEventListener('touchmove', this.onTouchMove);
|
|
178
178
|
this.setState(SplitPane.getSizeUpdate(this.props, this.state));
|
|
179
179
|
}
|
|
180
|
+
componentDidUpdate(previousProps, previousState) {
|
|
181
|
+
var _a, _b;
|
|
182
|
+
if (this.state.active &&
|
|
183
|
+
(!this.props.allowResize || previousProps.split !== this.props.split)) {
|
|
184
|
+
(_b = (_a = this.props).onDragFinished) === null || _b === void 0 ? void 0 : _b.call(_a, previousState.draggedSize);
|
|
185
|
+
this.setState({ active: false });
|
|
186
|
+
}
|
|
187
|
+
}
|
|
180
188
|
componentWillUnmount() {
|
|
181
189
|
document.removeEventListener('mouseup', this.onMouseUp);
|
|
182
190
|
document.removeEventListener('mousemove', this.onMouseMove);
|
|
@@ -12,6 +12,8 @@ export interface SplitTooltipRenderProps {
|
|
|
12
12
|
size: number;
|
|
13
13
|
}
|
|
14
14
|
export interface SplitTooltipProps {
|
|
15
|
+
/** Whether to show the tooltip pane. Defaults to `true`. Disabling preserves the mounted main pane. */
|
|
16
|
+
enabled?: boolean;
|
|
15
17
|
/**
|
|
16
18
|
* The controlled pane layout. When omitted, the layout is derived from the container size:
|
|
17
19
|
* vertical when width is greater than height, horizontal otherwise.
|
|
@@ -19,10 +21,21 @@ export interface SplitTooltipProps {
|
|
|
19
21
|
layout?: SplitTooltipLayout;
|
|
20
22
|
/** The share of the container width occupied by the main pane in vertical layout. Defaults to `0.6`. */
|
|
21
23
|
mainPaneRatio?: number;
|
|
24
|
+
/**
|
|
25
|
+
* Minimum main pane height in pixels in horizontal layout. Does not apply in vertical layout.
|
|
26
|
+
* Capped at half the height available after the resizer. When omitted, automatic sizing has no minimum.
|
|
27
|
+
*/
|
|
28
|
+
minMainPaneSize?: number;
|
|
22
29
|
/** Additional styles for the main pane. */
|
|
23
30
|
mainPaneStyle?: React.CSSProperties;
|
|
24
31
|
/** Called after initialization and whenever the main pane size or layout changes. */
|
|
25
32
|
onMainPaneSizeChange?: (size: number, layout: SplitTooltipLayout) => void;
|
|
33
|
+
/**
|
|
34
|
+
* Preserves the manually selected horizontal main pane size across content, container and layout
|
|
35
|
+
* changes, allowing the tooltip to shrink and scroll. Defaults to `false`.
|
|
36
|
+
* Before the first drag, sizing follows the tooltip content in either mode.
|
|
37
|
+
*/
|
|
38
|
+
preserveManualSize?: boolean;
|
|
26
39
|
/** Renders the main pane with its current layout and size. */
|
|
27
40
|
renderMainPane: (props: SplitTooltipRenderProps) => React.ReactNode;
|
|
28
41
|
/** Renders the tooltip pane with the current main pane layout and size. */
|
|
@@ -35,14 +48,15 @@ export interface SplitTooltipProps {
|
|
|
35
48
|
tooltipPaneStyle?: React.CSSProperties;
|
|
36
49
|
}
|
|
37
50
|
export declare function getSplitTooltipLayout(width: number, height: number, layout?: SplitTooltipLayout): SplitTooltipLayout;
|
|
38
|
-
export declare function getSplitTooltipMainPaneSize({ containerHeight, containerWidth, layout, mainPaneRatio, tooltipHeight, }: {
|
|
51
|
+
export declare function getSplitTooltipMainPaneSize({ containerHeight, containerWidth, layout, mainPaneRatio, minMainPaneSize, tooltipHeight, }: {
|
|
39
52
|
containerHeight: number;
|
|
40
53
|
containerWidth: number;
|
|
41
54
|
layout: SplitTooltipLayout;
|
|
42
55
|
mainPaneRatio?: number;
|
|
56
|
+
minMainPaneSize?: number;
|
|
43
57
|
tooltipHeight: number;
|
|
44
58
|
}): number;
|
|
45
|
-
export declare function getSplitTooltipSizeLimits(containerHeight: number, tooltipHeight: number): {
|
|
59
|
+
export declare function getSplitTooltipSizeLimits(containerHeight: number, tooltipHeight: number, minMainPaneSize?: number, preserveManualSize?: boolean): {
|
|
46
60
|
minSize: number;
|
|
47
61
|
maxSize: number;
|
|
48
62
|
};
|
|
@@ -9,79 +9,80 @@ const defaultTooltipPaneStyle = { overflow: 'auto' };
|
|
|
9
9
|
export function getSplitTooltipLayout(width, height, layout) {
|
|
10
10
|
return layout !== null && layout !== void 0 ? layout : (width > height ? SplitLayout.VERTICAL : SplitLayout.HORIZONTAL);
|
|
11
11
|
}
|
|
12
|
-
export function getSplitTooltipMainPaneSize({ containerHeight, containerWidth, layout, mainPaneRatio = SPLIT_TOOLTIP_MAIN_PANE_RATIO, tooltipHeight, }) {
|
|
12
|
+
export function getSplitTooltipMainPaneSize({ containerHeight, containerWidth, layout, mainPaneRatio = SPLIT_TOOLTIP_MAIN_PANE_RATIO, minMainPaneSize, tooltipHeight, }) {
|
|
13
13
|
if (layout === SplitLayout.VERTICAL) {
|
|
14
14
|
return containerWidth * mainPaneRatio;
|
|
15
15
|
}
|
|
16
|
-
|
|
16
|
+
const { minSize } = getSplitTooltipSizeLimits(containerHeight, tooltipHeight, minMainPaneSize);
|
|
17
|
+
return Math.max(minMainPaneSize === undefined ? 0 : minSize, containerHeight - SPLIT_TOOLTIP_RESIZER_SIZE - tooltipHeight);
|
|
17
18
|
}
|
|
18
|
-
export function getSplitTooltipSizeLimits(containerHeight, tooltipHeight) {
|
|
19
|
-
const
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
maxSize,
|
|
28
|
-
};
|
|
29
|
-
}
|
|
30
|
-
function getNextMainPaneSize({ currentSize, nextDimensions, previousDimensions, }) {
|
|
31
|
-
if (nextDimensions.layout !== previousDimensions.layout ||
|
|
32
|
-
nextDimensions.layout === SplitLayout.VERTICAL) {
|
|
33
|
-
return getSplitTooltipMainPaneSize(nextDimensions);
|
|
34
|
-
}
|
|
35
|
-
const { maxSize: previousMaxSize } = getSplitTooltipSizeLimits(previousDimensions.containerHeight, previousDimensions.tooltipHeight);
|
|
36
|
-
const { minSize: nextMinSize, maxSize: nextMaxSize } = getSplitTooltipSizeLimits(nextDimensions.containerHeight, nextDimensions.tooltipHeight);
|
|
37
|
-
if (currentSize === previousMaxSize) {
|
|
38
|
-
return nextMaxSize;
|
|
39
|
-
}
|
|
40
|
-
return Math.max(nextMinSize, Math.min(nextMaxSize, currentSize));
|
|
19
|
+
export function getSplitTooltipSizeLimits(containerHeight, tooltipHeight, minMainPaneSize, preserveManualSize = false) {
|
|
20
|
+
const availableSize = Math.max(0, containerHeight - SPLIT_TOOLTIP_RESIZER_SIZE);
|
|
21
|
+
const contentSize = Math.max(0, availableSize - tooltipHeight);
|
|
22
|
+
const defaultMinSize = preserveManualSize ? 0 : Math.min(containerHeight / 3, contentSize);
|
|
23
|
+
const minSize = minMainPaneSize === undefined
|
|
24
|
+
? defaultMinSize
|
|
25
|
+
: Math.min(Math.max(0, minMainPaneSize), availableSize / 2);
|
|
26
|
+
const maxSize = preserveManualSize ? availableSize : Math.max(minSize, contentSize);
|
|
27
|
+
return { minSize, maxSize };
|
|
41
28
|
}
|
|
42
29
|
function SplitTooltipContent(props) {
|
|
43
|
-
const { containerHeight, containerWidth, renderMainPane, renderTooltip, layout: layoutProp, mainPaneRatio = SPLIT_TOOLTIP_MAIN_PANE_RATIO, resizerVisible, onMainPaneSizeChange, style, mainPaneStyle, tooltipPaneStyle, } = props;
|
|
30
|
+
const { containerHeight, containerWidth, enabled = true, renderMainPane, renderTooltip, layout: layoutProp, mainPaneRatio = SPLIT_TOOLTIP_MAIN_PANE_RATIO, minMainPaneSize, preserveManualSize = false, resizerVisible, onMainPaneSizeChange, style, mainPaneStyle, tooltipPaneStyle, } = props;
|
|
44
31
|
const tooltipRef = React.useRef(null);
|
|
45
32
|
const layout = getSplitTooltipLayout(containerWidth, containerHeight, layoutProp);
|
|
46
33
|
const [tooltipHeight, setTooltipHeight] = React.useState(0);
|
|
47
|
-
const [
|
|
48
|
-
containerHeight,
|
|
49
|
-
containerWidth,
|
|
50
|
-
layout,
|
|
51
|
-
mainPaneRatio,
|
|
52
|
-
tooltipHeight: 0,
|
|
53
|
-
}));
|
|
54
|
-
const dimensions = React.useMemo(() => ({
|
|
55
|
-
containerHeight,
|
|
56
|
-
containerWidth,
|
|
57
|
-
layout,
|
|
58
|
-
mainPaneRatio,
|
|
59
|
-
tooltipHeight,
|
|
60
|
-
}), [containerHeight, containerWidth, layout, mainPaneRatio, tooltipHeight]);
|
|
61
|
-
const previousDimensionsRef = React.useRef(dimensions);
|
|
34
|
+
const [userSize, setUserSize] = React.useState();
|
|
62
35
|
const lastNotificationRef = React.useRef(null);
|
|
63
36
|
const onMainPaneSizeChangeRef = React.useRef(onMainPaneSizeChange);
|
|
64
37
|
onMainPaneSizeChangeRef.current = onMainPaneSizeChange;
|
|
65
38
|
const handleTooltipResize = React.useCallback(() => {
|
|
66
39
|
var _a, _b;
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
40
|
+
if (enabled) {
|
|
41
|
+
const nextTooltipHeight = (_b = (_a = tooltipRef.current) === null || _a === void 0 ? void 0 : _a.getBoundingClientRect().height) !== null && _b !== void 0 ? _b : 0;
|
|
42
|
+
setTooltipHeight(nextTooltipHeight);
|
|
43
|
+
}
|
|
44
|
+
}, [enabled]);
|
|
70
45
|
useResizeObserver({
|
|
71
46
|
ref: tooltipRef,
|
|
72
47
|
onResize: handleTooltipResize,
|
|
73
48
|
});
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
49
|
+
React.useLayoutEffect(handleTooltipResize, [handleTooltipResize, layout, containerWidth]);
|
|
50
|
+
const { minSize, maxSize } = getSplitTooltipSizeLimits(containerHeight, tooltipHeight, minMainPaneSize, preserveManualSize);
|
|
51
|
+
const automaticSize = getSplitTooltipMainPaneSize({
|
|
52
|
+
containerHeight,
|
|
53
|
+
containerWidth,
|
|
54
|
+
layout,
|
|
55
|
+
mainPaneRatio,
|
|
56
|
+
minMainPaneSize,
|
|
57
|
+
tooltipHeight,
|
|
78
58
|
});
|
|
59
|
+
const [size, setSize] = React.useState(automaticSize);
|
|
60
|
+
const previousSizingRef = React.useRef({ layout, maxSize });
|
|
61
|
+
let effectiveSize = automaticSize;
|
|
62
|
+
if (!enabled) {
|
|
63
|
+
effectiveSize = layout === SplitLayout.HORIZONTAL ? containerHeight : containerWidth;
|
|
64
|
+
}
|
|
65
|
+
else if (layout === SplitLayout.HORIZONTAL) {
|
|
66
|
+
if (preserveManualSize) {
|
|
67
|
+
if (userSize !== undefined) {
|
|
68
|
+
effectiveSize = Math.max(minSize, Math.min(maxSize, userSize));
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
else if (previousSizingRef.current.layout === layout) {
|
|
72
|
+
effectiveSize =
|
|
73
|
+
size === previousSizingRef.current.maxSize
|
|
74
|
+
? maxSize
|
|
75
|
+
: Math.max(minSize, Math.min(maxSize, size));
|
|
76
|
+
}
|
|
77
|
+
}
|
|
79
78
|
React.useLayoutEffect(() => {
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
79
|
+
if (enabled) {
|
|
80
|
+
previousSizingRef.current = { layout, maxSize };
|
|
81
|
+
if (effectiveSize !== size) {
|
|
82
|
+
setSize(effectiveSize);
|
|
83
|
+
}
|
|
83
84
|
}
|
|
84
|
-
}, [
|
|
85
|
+
}, [effectiveSize, enabled, layout, maxSize, size]);
|
|
85
86
|
React.useLayoutEffect(() => {
|
|
86
87
|
const previousNotification = lastNotificationRef.current;
|
|
87
88
|
if ((previousNotification === null || previousNotification === void 0 ? void 0 : previousNotification.size) === effectiveSize &&
|
|
@@ -93,30 +94,36 @@ function SplitTooltipContent(props) {
|
|
|
93
94
|
return undefined;
|
|
94
95
|
}
|
|
95
96
|
lastNotificationRef.current = { layout, size: effectiveSize };
|
|
96
|
-
|
|
97
|
+
callback(effectiveSize, layout);
|
|
98
|
+
return undefined;
|
|
97
99
|
});
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
const
|
|
101
|
-
const minSize = allowResize ? sizeLimits.minSize : undefined;
|
|
100
|
+
// SplitPane treats maxSize=0 as an offset from the container size, so disable dragging
|
|
101
|
+
// when no space remains after the resizer.
|
|
102
|
+
const allowResize = enabled && layout === SplitLayout.HORIZONTAL && containerWidth > 0 && maxSize > 0;
|
|
102
103
|
const renderProps = { layout, size: effectiveSize };
|
|
103
|
-
return (React.createElement(StyledSplitPane, { allowResize: allowResize, maxSize: maxSize, minSize: minSize, size: effectiveSize, split: layout, style: style, onChange: setSize, resizerStyle: resizerVisible ? undefined : hiddenResizerStyle, paneOneRender: () => renderMainPane(renderProps), paneTwoRender: () => React.createElement("div", { ref: tooltipRef }, renderTooltip(renderProps)), pane1Style: mainPaneStyle, pane2Style: Object.assign(Object.assign({}, defaultTooltipPaneStyle),
|
|
104
|
+
return (React.createElement(StyledSplitPane, { allowResize: allowResize, maxSize: maxSize, minSize: minSize, size: effectiveSize, split: layout, style: style, onChange: preserveManualSize ? setUserSize : setSize, resizerStyle: enabled && resizerVisible ? undefined : hiddenResizerStyle, paneOneRender: () => renderMainPane(renderProps), paneTwoRender: () => React.createElement("div", { ref: tooltipRef }, renderTooltip(renderProps)), pane1Style: mainPaneStyle, pane2Style: Object.assign(Object.assign(Object.assign(Object.assign({}, defaultTooltipPaneStyle), ((preserveManualSize || minMainPaneSize !== undefined) && {
|
|
105
|
+
minHeight: 0,
|
|
106
|
+
minWidth: 0,
|
|
107
|
+
})), tooltipPaneStyle), (!enabled && { display: 'none' })) }));
|
|
104
108
|
}
|
|
105
109
|
export function SplitTooltip(props) {
|
|
106
110
|
const containerRef = React.useRef(null);
|
|
107
|
-
const [dimensions, setDimensions] = React.useState({ height: 0, width: 0 });
|
|
111
|
+
const [dimensions, setDimensions] = React.useState({ height: 0, width: 0, initialized: false });
|
|
108
112
|
const updateDimensions = React.useCallback(() => {
|
|
109
113
|
var _a, _b, _c;
|
|
110
114
|
const rect = (_a = containerRef.current) === null || _a === void 0 ? void 0 : _a.getBoundingClientRect();
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
+
const height = (_b = rect === null || rect === void 0 ? void 0 : rect.height) !== null && _b !== void 0 ? _b : 0;
|
|
116
|
+
const width = (_c = rect === null || rect === void 0 ? void 0 : rect.width) !== null && _c !== void 0 ? _c : 0;
|
|
117
|
+
setDimensions((previous) => ({
|
|
118
|
+
height,
|
|
119
|
+
width,
|
|
120
|
+
initialized: previous.initialized || (height > 0 && width > 0),
|
|
121
|
+
}));
|
|
115
122
|
}, []);
|
|
116
123
|
useResizeObserver({
|
|
117
124
|
ref: containerRef,
|
|
118
125
|
onResize: updateDimensions,
|
|
119
126
|
});
|
|
120
127
|
React.useLayoutEffect(updateDimensions, [updateDimensions]);
|
|
121
|
-
return (React.createElement("div", { ref: containerRef, style: { position: 'relative', height: '100%' } }, dimensions.
|
|
128
|
+
return (React.createElement("div", { ref: containerRef, style: { position: 'relative', height: '100%' } }, dimensions.initialized ? (React.createElement(SplitTooltipContent, Object.assign({}, props, { containerHeight: dimensions.height, containerWidth: dimensions.width }))) : null));
|
|
122
129
|
}
|
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)
|
|
@@ -12,7 +12,21 @@ export const GravityChartsWidget = React.forwardRef(function GravityChartsWidget
|
|
|
12
12
|
const lang = settings.get('lang');
|
|
13
13
|
const performanceMeasure = React.useRef(measurePerformance());
|
|
14
14
|
const chartRef = React.useRef(null);
|
|
15
|
+
const [reflowFailure, setReflowFailure] = React.useState();
|
|
15
16
|
const ChartComponent = (tooltip === null || tooltip === void 0 ? void 0 : tooltip.splitted) ? ChartWithSplitPane : Chart;
|
|
17
|
+
const handleReflowError = React.useCallback((error) => {
|
|
18
|
+
// shortcut: Match lifecycle messages until charts exposes a cancellation error type.
|
|
19
|
+
if (error instanceof Error &&
|
|
20
|
+
[
|
|
21
|
+
'Chart host is unavailable',
|
|
22
|
+
'Chart host has zero size',
|
|
23
|
+
'Chart is unmounted',
|
|
24
|
+
'Chart unmounted before reflow completed',
|
|
25
|
+
].includes(error.message)) {
|
|
26
|
+
return;
|
|
27
|
+
}
|
|
28
|
+
setReflowFailure({ error });
|
|
29
|
+
}, []);
|
|
16
30
|
const handleChartReady = React.useCallback(() => {
|
|
17
31
|
if (!performanceMeasure.current) {
|
|
18
32
|
performanceMeasure.current = measurePerformance();
|
|
@@ -30,16 +44,27 @@ export const GravityChartsWidget = React.forwardRef(function GravityChartsWidget
|
|
|
30
44
|
});
|
|
31
45
|
}, [onRender, onLoad]);
|
|
32
46
|
React.useImperativeHandle(forwardedRef, () => ({
|
|
33
|
-
reflow() {
|
|
47
|
+
reflow(details) {
|
|
34
48
|
var _a;
|
|
35
|
-
|
|
49
|
+
const options = details &&
|
|
50
|
+
typeof details === 'object' &&
|
|
51
|
+
'immediate' in details &&
|
|
52
|
+
typeof details.immediate === 'boolean'
|
|
53
|
+
? { immediate: details.immediate }
|
|
54
|
+
: undefined;
|
|
55
|
+
const completion = (_a = chartRef.current) === null || _a === void 0 ? void 0 : _a.reflow(options);
|
|
56
|
+
completion === null || completion === void 0 ? void 0 : completion.catch(handleReflowError);
|
|
57
|
+
return completion;
|
|
36
58
|
},
|
|
37
|
-
}), []);
|
|
59
|
+
}), [handleReflowError]);
|
|
38
60
|
React.useLayoutEffect(() => {
|
|
39
61
|
if (onChartLoad) {
|
|
40
62
|
onChartLoad({});
|
|
41
63
|
}
|
|
42
64
|
}, [onChartLoad]);
|
|
43
|
-
|
|
65
|
+
if (reflowFailure) {
|
|
66
|
+
throw reflowFailure.error;
|
|
67
|
+
}
|
|
68
|
+
return (React.createElement(ChartComponent, { ref: chartRef, data: data, lang: lang, onReady: handleChartReady, onReflowError: handleReflowError }));
|
|
44
69
|
});
|
|
45
70
|
export default GravityChartsWidget;
|
|
@@ -1,4 +1,8 @@
|
|
|
1
1
|
import React from 'react';
|
|
2
2
|
import { Chart } from '@gravity-ui/charts';
|
|
3
3
|
import type { ChartProps, ChartRef } from '@gravity-ui/charts';
|
|
4
|
-
|
|
4
|
+
type WithSplitPaneProps = {
|
|
5
|
+
onReflowError: (error: unknown) => void;
|
|
6
|
+
};
|
|
7
|
+
export declare function withSplitPane(ChartComponent: typeof Chart): React.ForwardRefExoticComponent<ChartProps<import("@gravity-ui/charts").ChartInteractionItem<object, string>> & WithSplitPaneProps & React.RefAttributes<ChartRef>>;
|
|
8
|
+
export {};
|
|
@@ -8,8 +8,18 @@ import { TooltipContent } from './TooltipContent';
|
|
|
8
8
|
import { useViewportSplitTooltipLayout } from './useViewportSplitTooltipLayout';
|
|
9
9
|
const SplitPaneContent = (props) => {
|
|
10
10
|
var _a;
|
|
11
|
-
const { data, ChartComponent } = props, restProps = __rest(props, ["data", "ChartComponent"]);
|
|
11
|
+
const { data, ChartComponent, forwardedRef, onReflowError } = props, restProps = __rest(props, ["data", "ChartComponent", "forwardedRef", "onReflowError"]);
|
|
12
12
|
const chartRef = React.useRef(null);
|
|
13
|
+
React.useImperativeHandle(forwardedRef, () => ({
|
|
14
|
+
reflow: (options) => {
|
|
15
|
+
if (chartRef.current) {
|
|
16
|
+
return chartRef.current.reflow(options);
|
|
17
|
+
}
|
|
18
|
+
const unavailable = Promise.reject(new Error('Chart host is unavailable'));
|
|
19
|
+
unavailable.catch(() => undefined);
|
|
20
|
+
return unavailable;
|
|
21
|
+
},
|
|
22
|
+
}), []);
|
|
13
23
|
const tooltipRef = React.useRef(null);
|
|
14
24
|
const [tooltipVisible, setTooltipVisible] = React.useState(false);
|
|
15
25
|
const layout = useViewportSplitTooltipLayout();
|
|
@@ -36,12 +46,15 @@ const SplitPaneContent = (props) => {
|
|
|
36
46
|
hoveredPosition: { x: 0, y: 0 },
|
|
37
47
|
} }, data), { chart: Object.assign(Object.assign({}, data.chart), { events: Object.assign(Object.assign({}, (_c = data.chart) === null || _c === void 0 ? void 0 : _c.events), { pointermove: pointerMoveHandler }) }), tooltip: Object.assign(Object.assign({}, data.tooltip), { enabled: false }) });
|
|
38
48
|
}, [data]);
|
|
39
|
-
return (React.createElement(SplitTooltip, { layout: layout, resizerVisible: tooltipVisible, onMainPaneSizeChange: () => {
|
|
49
|
+
return (React.createElement(SplitTooltip, { layout: layout, resizerVisible: tooltipVisible, onMainPaneSizeChange: () => {
|
|
50
|
+
var _a;
|
|
51
|
+
(_a = chartRef.current) === null || _a === void 0 ? void 0 : _a.reflow().catch(onReflowError);
|
|
52
|
+
}, renderMainPane: () => (React.createElement(ChartComponent, Object.assign({}, restProps, { ref: chartRef, data: resultData }))), renderTooltip: () => (React.createElement(TooltipContent, { ref: tooltipRef, renderer: resultData.tooltip.renderer, headerFormat: headerFormat, valueFormat: resultData.tooltip.valueFormat, rowRenderer: resultData.tooltip.rowRenderer, totals: resultData.tooltip.totals, rows: resultData.tooltip.rows })) }));
|
|
40
53
|
};
|
|
41
54
|
export function withSplitPane(ChartComponent) {
|
|
42
55
|
const componentName = getComponentName(ChartComponent);
|
|
43
|
-
const component = React.forwardRef(function WithSplitPaneComponent(props,
|
|
44
|
-
return React.createElement(SplitPaneContent, Object.assign({ ChartComponent: ChartComponent }, props));
|
|
56
|
+
const component = React.forwardRef(function WithSplitPaneComponent(props, ref) {
|
|
57
|
+
return (React.createElement(SplitPaneContent, Object.assign({ ChartComponent: ChartComponent, forwardedRef: ref }, props)));
|
|
45
58
|
});
|
|
46
59
|
component.displayName = `withSplitPane(${componentName})`;
|
|
47
60
|
return component;
|
package/build/types/index.d.ts
CHANGED
|
@@ -5,7 +5,15 @@ export type { ChartKitHolidays } from './misc';
|
|
|
5
5
|
export type ChartKitLang = 'ru' | 'en';
|
|
6
6
|
export type ChartKitType = keyof ChartKitWidget;
|
|
7
7
|
export type ChartKitRef = {
|
|
8
|
-
|
|
8
|
+
/**
|
|
9
|
+
* Renderers may return a promise that completes when the resized chart is ready.
|
|
10
|
+
* `undefined` means no completion signal is available, including while the widget is loading.
|
|
11
|
+
* It does not guarantee that the chart is ready. Awaiting callers must handle rejection.
|
|
12
|
+
* Gravity Charts also reports preparation failures through onError/renderError;
|
|
13
|
+
* unavailable-host, zero-size and unmount cancellations only reject the promise.
|
|
14
|
+
* For Gravity Charts, pass `{immediate: true}` to skip the resize debounce.
|
|
15
|
+
*/
|
|
16
|
+
reflow: (details?: unknown) => void | Promise<void>;
|
|
9
17
|
};
|
|
10
18
|
export type ChartKitWidgetRef = {
|
|
11
19
|
reflow?: ChartKitRef['reflow'];
|
package/package.json
CHANGED
|
@@ -1,7 +1,21 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@gravity-ui/chartkit",
|
|
3
|
-
"version": "8.
|
|
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.
|
|
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",
|