Skip to content

Commit 0aa603c

Browse files
yikenmanyikenman
committed
docs(changeset): first release
1 parent 4c78ae6 commit 0aa603c

23 files changed

+3672
-386
lines changed

‎.changeset/chilly-eels-grab.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"use-echarts-react": major
3+
---
4+
5+
first release

‎.syncpackrc.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,15 @@
11
{
22
"$schema": "./node_modules/syncpack/dist/schema.json",
33
"lintFormatting": false,
4+
"lintSemverRanges": false,
45
"sortPackages": true,
56
"sortFirst": [
67
"name",
78
"private",
89
"description",
910
"version",
11+
"homepage",
12+
"repository",
1013
"author",
1114
"license",
1215
"exports",

‎README.md‎

Lines changed: 264 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,264 @@
1+
# use-echarts-react
2+
3+
[![NPM Version](https://img.shields.io/npm/v/use-echarts-react)
4+
](https://www.npmjs.com/package/use-echarts-react)
5+
![NPM License](https://img.shields.io/npm/l/use-echarts-react)
6+
[![codecov](https://codecov.io/gh/yikenman/use-echarts-react/graph/badge.svg?token=43EG2T8LKS)](https://codecov.io/gh/yikenman/use-echarts-react)
7+
8+
A modernized React hook for integrating ECharts.
9+
10+
---
11+
12+
## Features
13+
14+
- **Hook** based modern APIs.
15+
- Supports **tree-shakeable** ECharts usages by default.
16+
- Supports **declarative**/**imperative** mode for different scenarios.
17+
- Supports **deep comparison**.
18+
- Supports all **ECharts** APIs.
19+
- Works with **SSR**.
20+
- Written in **Typescript**.
21+
- 100% test coverage.
22+
23+
24+
## Install
25+
26+
```bash
27+
$ npm install --save use-echarts-react echarts
28+
```
29+
30+
## Basic Usage
31+
32+
```tsx
33+
import { LineChart } from 'echarts/charts';
34+
import { GridComponent, LegendComponent, TitleComponent, TooltipComponent } from 'echarts/components';
35+
import { use } from 'echarts/core';
36+
import { CanvasRenderer } from 'echarts/renderers';
37+
import { useECharts, useEChartsEvent } from "use-echarts-react";
38+
39+
// Tree-shakeable ECharts usage, see https://echarts.apache.org/handbook/en/basics/import/#shrinking-bundle-size.
40+
use([
41+
CanvasRenderer,
42+
GridComponent,
43+
LineChart,
44+
TooltipComponent,
45+
TitleComponent,
46+
LegendComponent
47+
]);
48+
49+
const App = () => {
50+
const ref = useECharts<HTMLDivElement>({
51+
// echarts instance option
52+
xAxis: {
53+
type: 'category',
54+
data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
55+
},
56+
yAxis: {
57+
type: 'value'
58+
},
59+
series: [
60+
{
61+
data: [150, 230, 224, 218, 135, 147, 260],
62+
type: 'line'
63+
}
64+
]
65+
}, {
66+
width: 100,
67+
height: 100
68+
});
69+
70+
// binding event
71+
useEChartsEvent(ref, 'click', () => {
72+
console.log('triggered');
73+
});
74+
75+
return (
76+
<div ref={ref}></div>
77+
);
78+
};
79+
```
80+
81+
## APIs
82+
83+
### useECharts(option, initOpts)
84+
85+
Configures the ECharts instance with the provided options.
86+
87+
#### `option` (Optional)
88+
89+
This parameter is used for configuring the ECharts instance with the options that would be passed to the `setOption` method. It can include the following:
90+
91+
|Property|Description|
92+
|--|--|
93+
| **... ECharts Options** | Accepts all options from `setOption` method. Refers [ECharts Configuration Items Manual](https://echarts.apache.org/en/option.html#title) for all available options. |
94+
| **`group`** | Specifies the `group` of the ECharts instance and automatically connects the chart group. See [echartsInstance.group](https://echarts.apache.org/zh/api.html#echartsInstance.group). |
95+
| **`loading`** | Controls the loading state of the ECharts instance. See [showLoading method](https://echarts.apache.org/zh/api.html#echartsInstance.showLoading). |
96+
97+
98+
#### `initOpts` (Optional)
99+
100+
This is used to initialize the ECharts instance. It can only be set once during the initialization and includes the following options:
101+
102+
|Property|Description|
103+
|--|--|
104+
| **`theme`**| The theme for the ECharts instance, see [echarts.init - theme](https://echarts.apache.org/en/api.html#echarts.init). |
105+
| **`locale`**| The locale for the ECharts instance, see [echarts.init - locale](https://echarts.apache.org/en/api.html#echarts.init). |
106+
| **`renderer`**| The renderer for ECharts (canvas or SVG), see [echarts.init - renderer](https://echarts.apache.org/en/api.html#echarts.init). |
107+
| **`devicePixelRatio`**| The pixel ratio for the instance, see [echarts.init - devicePixelRatio](https://echarts.apache.org/en/api.html#echarts.init). |
108+
| **`useDirtyRect`**| Whether to use the dirty rectangle technique to optimize performance, see [echarts.init - useDirtyRect](https://echarts.apache.org/en/api.html#echarts.init). |
109+
| **`useCoarsePointer`**| Whether to use a coarse pointer for event handling, see [echarts.init - useCoarsePointer](https://echarts.apache.org/en/api.html#echarts.init). |
110+
| **`pointerSize`**| The size of the pointer for interactions, see [echarts.init - pointerSize](https://echarts.apache.org/en/api.html#echarts.init). |
111+
| **`ssr`**| Enable server-side rendering for the instance, see [echarts.init - ssr](https://echarts.apache.org/en/api.html#echarts.init). |
112+
| **`width`**| The width of the chart, see [echarts.init - width](https://echarts.apache.org/en/api.html#echarts.init). |
113+
| **`height`**| The height of the chart, see [echarts.init - height](https://echarts.apache.org/en/api.html#echarts.init). |
114+
| **`resize`**| Automatically resizes the chart when the bound element’s size changes. Defaults to `false`. |
115+
| **`imperativeMode`**| Enables direct control of the ECharts instance. When enabled, the `option` parameter is ignored. Defaults to `false`. |
116+
| **`deepCompare`**| Enables deep comparison for `option` before updating the instance. Defaults to `false`. |
117+
118+
#### Returns
119+
120+
The hook returns a **React ref** object used to bind the DOM element. This ref contains two properties:
121+
122+
- **`current`**: The current DOM element that the ref is bound to.
123+
- **`chart`**: The current created ECharts instance with restricted APIs. If `imperativeMode` is enabled, this will return the complete ECharts instance, allowing direct interaction with all methods of ECharts.
124+
125+
126+
### useEChartsEvent(ref, event, handler) / useEChartsEvent(ref, event, query, handler)
127+
128+
Automatically handling event binding to ECharts instance.
129+
130+
#### `ref` (Required)
131+
The return value of the `useECharts` hook.
132+
133+
#### `event` (Required)
134+
The event to listen for. This is the same as the `eventName` parameter in the [ECharts `echartsInstance.on` method](https://echarts.apache.org/en/api.html#echartsInstance.on).
135+
136+
#### `query` (Optional)
137+
This is the query parameter for the event listener. It is the same as the `query` parameter in the [ECharts `echartsInstance.on` method](https://echarts.apache.org/en/api.html#echartsInstance.on).
138+
139+
#### `handler` (Required)
140+
Same as the `handler` parameter in the [ECharts `echartsInstance.on` method](https://echarts.apache.org/en/api.html#echartsInstance.on).
141+
142+
## Declarative / Imperative Mode
143+
144+
By default, `useECharts` will return an ECharts instance with restricted APIs like `setOption`, `on`... and user should update ECharts instance by updating the hook parameters. Also user can get a complete ECharts instance via enabling `imperativeMode`.
145+
146+
### Declarative Mode
147+
148+
```tsx
149+
import { useECharts } from "use-echarts-react";
150+
151+
const App = () => {
152+
const ref = useECharts<HTMLDivElement>({
153+
// can only use hook parameters to update ECharts instance.
154+
xAxis: {
155+
type: 'category',
156+
data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
157+
},
158+
yAxis: {
159+
type: 'value'
160+
},
161+
series: [
162+
{
163+
data: [150, 230, 224, 218, 135, 147, 260],
164+
type: 'line'
165+
}
166+
]
167+
}, {
168+
width: 100,
169+
height: 100
170+
});
171+
172+
return (
173+
<div ref={ref}></div>
174+
);
175+
};
176+
```
177+
178+
### Imperative Mode
179+
180+
```tsx
181+
import { useECharts } from "use-echarts-react";
182+
183+
const App = () => {
184+
const ref = useECharts<HTMLDivElement>({
185+
// option will be ignored under imperative mode.
186+
}, {
187+
imperativeMode: true,
188+
width: 100,
189+
height: 100
190+
});
191+
192+
return (
193+
<div>
194+
<button
195+
onClick={() => {
196+
// `setOption` is available to call now.
197+
ref.chart?.setOption({
198+
xAxis: {
199+
type: 'category',
200+
data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
201+
},
202+
yAxis: {
203+
type: 'value'
204+
},
205+
series: [
206+
{
207+
data: [150, 230, 224, 218, 135, 147, 260],
208+
type: 'line',
209+
}
210+
]
211+
});
212+
}}
213+
>
214+
update
215+
</button>
216+
<div ref={ref}></div>
217+
</div>
218+
);
219+
};
220+
```
221+
222+
223+
## About SSR
224+
225+
`useEcharts` supports using [`ECharts SSR`](https://echarts.apache.org/handbook/en/how-to/cross-platform/server/) option. But this is not as the same as `React SSR`. `ECharts SSR` is used for returning SVG string instead of manipulating a dom element.
226+
227+
```tsx
228+
import { useECharts } from "use-echarts-react";
229+
230+
const App = () => {
231+
const ref = useECharts<HTMLDivElement>({
232+
xAxis: {
233+
type: 'category',
234+
data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
235+
},
236+
yAxis: {
237+
type: 'value'
238+
},
239+
series: [
240+
{
241+
data: [150, 230, 224, 218, 135, 147, 260],
242+
type: 'line'
243+
}
244+
]
245+
}, {
246+
renderer: 'svg',
247+
ssr: true,
248+
width: 100,
249+
height: 100
250+
});
251+
252+
return (
253+
<div
254+
dangerouslySetInnerHTML={{
255+
__html: ref.chart?.renderToSVGString() ?? ''
256+
}}
257+
></div>
258+
);
259+
};
260+
```
261+
262+
## License
263+
264+
MIT License

‎package.json‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,16 @@
11
{
22
"name": "use-echarts-react",
33
"private": true,
4-
"version": "0.0.0",
54
"description": "A modernized React hook for integrating ECharts.",
5+
"version": "0.0.0",
66
"homepage": "https://github.com/yikenman/use-echarts-react",
77
"repository": "https://github.com/yikenman/use-echarts-react",
88
"author": "yikenman",
99
"license": "MIT",
1010
"scripts": {
1111
"build": "turbo run build",
12-
"check": "syncpack format && syncpack lint",
13-
"ci:publish": "changeset publish",
12+
"check": "syncpack format && echo ''",
13+
"ci:publish": "cp ./README.md ./packages/use-echarts-react/README.md && changeset publish",
1414
"ci:version": "changeset version && pnpm install --frozen-lockfile=false",
1515
"dev": "turbo run dev",
1616
"format": "biome check .",
@@ -23,9 +23,9 @@
2323
"@changesets/cli": "^2.27.11",
2424
"@changesets/config": "^3.0.5",
2525
"husky": "^9.1.7",
26-
"lint-staged": "^15.3.0",
26+
"lint-staged": "^15.4.3",
2727
"syncpack": "^13.0.0",
28-
"turbo": "^2.3.3"
28+
"turbo": "^2.4.4"
2929
},
3030
"engines": {
3131
"node": ">=20.13.0"

‎packages/use-echarts-react/jest.config.json‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
{
2+
"moduleFileExtensions": [
3+
"js",
4+
"json",
5+
"ts"
6+
],
7+
"rootDir": "src",
8+
"testRegex": ".*\\.spec\\.ts$",
9+
"transform": {
10+
"^.+\\.(t|j)s$": "ts-jest"
11+
},
12+
"collectCoverage": true,
13+
"collectCoverageFrom": [
14+
"**/*.(t|j)s"
15+
],
16+
"coverageDirectory": "../coverage",
17+
"testEnvironment": "jsdom"
18+
}

0 commit comments

Comments
 (0)