@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 CHANGED
@@ -19,3 +19,4 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
19
  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
20
  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
21
21
  THE SOFTWARE.
22
+
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Gravity UI ChartKit · [![npm package](https://img.shields.io/npm/v/@gravity-ui/chartkit)](https://www.npmjs.com/package/@gravity-ui/chartkit) [![License](https://img.shields.io/github/license/gravity-ui/ChartKit)](LICENSE) [![CI](https://img.shields.io/github/actions/workflow/status/gravity-ui/ChartKit/.github/workflows/ci.yml?label=CI&logo=github)](https://github.com/gravity-ui/ChartKit/actions/workflows/ci.yml?query=branch:main) [![storybook](https://img.shields.io/badge/Storybook-deployed-ff4685)](https://preview.gravity-ui.com/chartkit/)
2
2
 
3
- Plugin-based React component that provides a unified rendering interface for multiple charting libraries. You register one or more plugins and render charts via `<ChartKit type="..." data={...} />` — ChartKit dispatches to the correct renderer automatically.
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're building in the Gravity UI ecosystem
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
- - `[@gravity-ui/uikit](https://github.com/gravity-ui/uikit)` — required peer dependency (provides theming and UI primitives)
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-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.
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 (e.g. `gravity-charts` + `yagr`) behind one consistent component.
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
- - Bundling charts into a Gravity UI app that wants mobile-friendly tooltips and unified theming out of the box.
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
- if ((_a = widgetRef.current) === null || _a === void 0 ? void 0 : _a.reflow) {
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
- return Math.max(0, containerHeight - SPLIT_TOOLTIP_RESIZER_SIZE - tooltipHeight);
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 maxSize = getSplitTooltipMainPaneSize({
20
- containerHeight,
21
- containerWidth: 0,
22
- layout: SplitLayout.HORIZONTAL,
23
- tooltipHeight,
24
- });
25
- return {
26
- minSize: Math.min(containerHeight / 3, maxSize),
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 [size, setSize] = React.useState(() => getSplitTooltipMainPaneSize({
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
- const nextTooltipHeight = (_b = (_a = tooltipRef.current) === null || _a === void 0 ? void 0 : _a.getBoundingClientRect().height) !== null && _b !== void 0 ? _b : 0;
68
- setTooltipHeight(nextTooltipHeight);
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
- const effectiveSize = getNextMainPaneSize({
75
- currentSize: size,
76
- nextDimensions: dimensions,
77
- previousDimensions: previousDimensionsRef.current,
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
- previousDimensionsRef.current = dimensions;
81
- if (effectiveSize !== size) {
82
- setSize(effectiveSize);
79
+ if (enabled) {
80
+ previousSizingRef.current = { layout, maxSize };
81
+ if (effectiveSize !== size) {
82
+ setSize(effectiveSize);
83
+ }
83
84
  }
84
- }, [dimensions, effectiveSize, size]);
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
- return callback(effectiveSize, layout);
97
+ callback(effectiveSize, layout);
98
+ return undefined;
97
99
  });
98
- const allowResize = layout === SplitLayout.HORIZONTAL;
99
- const sizeLimits = getSplitTooltipSizeLimits(containerHeight, tooltipHeight);
100
- const maxSize = allowResize ? sizeLimits.maxSize : undefined;
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), tooltipPaneStyle) }));
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
- setDimensions({
112
- height: (_b = rect === null || rect === void 0 ? void 0 : rect.height) !== null && _b !== void 0 ? _b : 0,
113
- width: (_c = rect === null || rect === void 0 ? void 0 : rect.width) !== null && _c !== void 0 ? _c : 0,
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.height > 0 && dimensions.width > 0 ? (React.createElement(SplitTooltipContent, Object.assign({}, props, { containerHeight: dimensions.height, containerWidth: dimensions.width }))) : null));
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
  }
@@ -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-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.
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 (e.g. `gravity-charts` + `yagr`) behind one consistent component.
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
- - Bundling charts into a Gravity UI app that wants mobile-friendly tooltips and unified theming out of the box.
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
- - `[@gravity-ui/uikit](https://github.com/gravity-ui/uikit)` — required peer dependency (provides theming and UI primitives)
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
- (_a = chartRef.current) === null || _a === void 0 ? void 0 : _a.reflow();
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
- return React.createElement(ChartComponent, { ref: chartRef, data: data, lang: lang, onReady: handleChartReady });
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
- export declare function withSplitPane(ChartComponent: typeof Chart): React.ForwardRefExoticComponent<ChartProps<import("@gravity-ui/charts").ChartInteractionItem<object, string>> & React.RefAttributes<ChartRef>>;
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: () => { var _a; return (_a = chartRef.current) === null || _a === void 0 ? void 0 : _a.reflow(); }, 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 })) }));
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, _ref) {
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;
@@ -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
- reflow: (details?: unknown) => void;
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.11.0",
4
- "description": "React component used to render charts based on any sources you need",
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.71.0",
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",