@particle-academy/fancy-echarts 1.2.0 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (10) hide show
  1. package/README.md +217 -213
  2. package/dist/index.cjs.map +1 -1
  3. package/dist/index.js.map +1 -1
  4. package/docs/EChart.md +207 -207
  5. package/docs/EChart3D.md +178 -178
  6. package/docs/EChartGraphic.md +149 -149
  7. package/docs/registration.md +152 -152
  8. package/docs/themes.md +152 -152
  9. package/docs/useECharts.md +129 -129
  10. package/package.json +71 -66
package/docs/useECharts.md CHANGED
@@ -1,129 +1,129 @@
1
- # useECharts
2
-
3
- Low-level hook that initializes an ECharts instance on a div ref, manages option updates, event binding, loading state, and auto-resize. Used internally by `EChart`, `EChart3D`, and `EChartGraphic`.
4
-
5
- ## Import
6
-
7
- ```tsx
8
- import { useECharts } from "@particle-academy/fancy-echarts";
9
- import type { UseEChartsOptions, UseEChartsReturn } from "@particle-academy/fancy-echarts";
10
- ```
11
-
12
- ## Signature
13
-
14
- ```ts
15
- function useECharts(options: UseEChartsOptions): UseEChartsReturn
16
- ```
17
-
18
- ## Options
19
-
20
- | Option | Type | Default | Description |
21
- |--------|------|---------|-------------|
22
- | `option` | `EChartsOption` | **required** | ECharts option object |
23
- | `theme` | `string \| object` | `undefined` | Theme name or object. When omitted, auto-detects dark mode |
24
- | `renderer` | `"canvas" \| "svg"` | `"canvas"` | Rendering engine |
25
- | `notMerge` | `boolean` | `false` | Replace option instead of merging |
26
- | `lazyUpdate` | `boolean` | `false` | Delay chart update |
27
- | `showLoading` | `boolean` | `false` | Show loading animation |
28
- | `loadingOption` | `object` | `undefined` | Customize loading spinner |
29
- | `onEvents` | `Record<string, (params) => void>` | `undefined` | Event handlers keyed by event name |
30
- | `autoResize` | `boolean` | `true` | Auto-resize via `ResizeObserver` |
31
-
32
- ## Return Value
33
-
34
- | Property | Type | Description |
35
- |----------|------|-------------|
36
- | `chartRef` | `RefObject<HTMLDivElement \| null>` | Ref to attach to a container div |
37
- | `instance` | `ECharts \| null` | The ECharts instance (null before init) |
38
-
39
- ## Behavior
40
-
41
- - **Dark mode auto-detection:** When `theme` is omitted, the hook listens to `prefers-color-scheme: dark` and applies ECharts' built-in `"dark"` theme reactively. In auto-dark mode, `backgroundColor` is set to `"transparent"` so the chart blends with the page background.
42
- - **Re-initialization:** The chart instance is disposed and re-created when `theme` or `renderer` changes.
43
- - **StrictMode safe:** Handles React 18 StrictMode double-mount by disposing any existing instance on the same DOM element.
44
- - **Event cleanup:** Event listeners are bound/unbound cleanly via `useEffect` cleanup.
45
- - **Resize:** Uses `useResizeObserver` internally to call `chart.resize()` on container size changes.
46
-
47
- ## Basic Usage
48
-
49
- ```tsx
50
- function MyChart({ data }) {
51
- const option = useMemo(() => ({
52
- xAxis: { type: "category", data: ["A", "B", "C"] },
53
- yAxis: { type: "value" },
54
- series: [{ type: "bar", data }],
55
- }), [data]);
56
-
57
- const { chartRef } = useECharts({ option });
58
-
59
- return <div ref={chartRef} style={{ width: "100%", height: 400 }} />;
60
- }
61
- ```
62
-
63
- ## Accessing the Instance
64
-
65
- ```tsx
66
- function ExportableChart() {
67
- const { chartRef, instance } = useECharts({
68
- option: { /* ... */ },
69
- });
70
-
71
- const handleExport = () => {
72
- if (instance) {
73
- const dataUrl = instance.getDataURL({ type: "png" });
74
- // download or display dataUrl
75
- }
76
- };
77
-
78
- return (
79
- <div>
80
- <div ref={chartRef} style={{ width: "100%", height: 400 }} />
81
- <button onClick={handleExport}>Export PNG</button>
82
- </div>
83
- );
84
- }
85
- ```
86
-
87
- ## Event Handling
88
-
89
- ```tsx
90
- const { chartRef } = useECharts({
91
- option: myOption,
92
- onEvents: {
93
- click: (params) => console.log("Clicked:", params.name),
94
- mouseover: (params) => console.log("Hover:", params.data),
95
- legendselectchanged: (params) => console.log("Legend:", params.selected),
96
- },
97
- });
98
- ```
99
-
100
- ## Custom Theme
101
-
102
- ```tsx
103
- const { chartRef } = useECharts({
104
- option: myOption,
105
- theme: "vintage", // registered theme name
106
- renderer: "svg", // SVG instead of canvas
107
- autoResize: false, // manual resize control
108
- });
109
- ```
110
-
111
- ## useResizeObserver
112
-
113
- A utility hook used internally. Calls a callback whenever the referenced element's size changes.
114
-
115
- ```ts
116
- import { useResizeObserver } from "@particle-academy/fancy-echarts";
117
-
118
- function useResizeObserver(
119
- ref: RefObject<HTMLElement | null>,
120
- callback: () => void
121
- ): void
122
- ```
123
-
124
- ```tsx
125
- const divRef = useRef<HTMLDivElement>(null);
126
- useResizeObserver(divRef, () => {
127
- console.log("Container resized");
128
- });
129
- ```
1
+ # useECharts
2
+
3
+ Low-level hook that initializes an ECharts instance on a div ref, manages option updates, event binding, loading state, and auto-resize. Used internally by `EChart`, `EChart3D`, and `EChartGraphic`.
4
+
5
+ ## Import
6
+
7
+ ```tsx
8
+ import { useECharts } from "@particle-academy/fancy-echarts";
9
+ import type { UseEChartsOptions, UseEChartsReturn } from "@particle-academy/fancy-echarts";
10
+ ```
11
+
12
+ ## Signature
13
+
14
+ ```ts
15
+ function useECharts(options: UseEChartsOptions): UseEChartsReturn
16
+ ```
17
+
18
+ ## Options
19
+
20
+ | Option | Type | Default | Description |
21
+ |--------|------|---------|-------------|
22
+ | `option` | `EChartsOption` | **required** | ECharts option object |
23
+ | `theme` | `string \| object` | `undefined` | Theme name or object. When omitted, auto-detects dark mode |
24
+ | `renderer` | `"canvas" \| "svg"` | `"canvas"` | Rendering engine |
25
+ | `notMerge` | `boolean` | `false` | Replace option instead of merging |
26
+ | `lazyUpdate` | `boolean` | `false` | Delay chart update |
27
+ | `showLoading` | `boolean` | `false` | Show loading animation |
28
+ | `loadingOption` | `object` | `undefined` | Customize loading spinner |
29
+ | `onEvents` | `Record<string, (params) => void>` | `undefined` | Event handlers keyed by event name |
30
+ | `autoResize` | `boolean` | `true` | Auto-resize via `ResizeObserver` |
31
+
32
+ ## Return Value
33
+
34
+ | Property | Type | Description |
35
+ |----------|------|-------------|
36
+ | `chartRef` | `RefObject<HTMLDivElement \| null>` | Ref to attach to a container div |
37
+ | `instance` | `ECharts \| null` | The ECharts instance (null before init) |
38
+
39
+ ## Behavior
40
+
41
+ - **Dark mode auto-detection:** When `theme` is omitted, the hook listens to `prefers-color-scheme: dark` and applies ECharts' built-in `"dark"` theme reactively. In auto-dark mode, `backgroundColor` is set to `"transparent"` so the chart blends with the page background.
42
+ - **Re-initialization:** The chart instance is disposed and re-created when `theme` or `renderer` changes.
43
+ - **StrictMode safe:** Handles React 18 StrictMode double-mount by disposing any existing instance on the same DOM element.
44
+ - **Event cleanup:** Event listeners are bound/unbound cleanly via `useEffect` cleanup.
45
+ - **Resize:** Uses `useResizeObserver` internally to call `chart.resize()` on container size changes.
46
+
47
+ ## Basic Usage
48
+
49
+ ```tsx
50
+ function MyChart({ data }) {
51
+ const option = useMemo(() => ({
52
+ xAxis: { type: "category", data: ["A", "B", "C"] },
53
+ yAxis: { type: "value" },
54
+ series: [{ type: "bar", data }],
55
+ }), [data]);
56
+
57
+ const { chartRef } = useECharts({ option });
58
+
59
+ return <div ref={chartRef} style={{ width: "100%", height: 400 }} />;
60
+ }
61
+ ```
62
+
63
+ ## Accessing the Instance
64
+
65
+ ```tsx
66
+ function ExportableChart() {
67
+ const { chartRef, instance } = useECharts({
68
+ option: { /* ... */ },
69
+ });
70
+
71
+ const handleExport = () => {
72
+ if (instance) {
73
+ const dataUrl = instance.getDataURL({ type: "png" });
74
+ // download or display dataUrl
75
+ }
76
+ };
77
+
78
+ return (
79
+ <div>
80
+ <div ref={chartRef} style={{ width: "100%", height: 400 }} />
81
+ <button onClick={handleExport}>Export PNG</button>
82
+ </div>
83
+ );
84
+ }
85
+ ```
86
+
87
+ ## Event Handling
88
+
89
+ ```tsx
90
+ const { chartRef } = useECharts({
91
+ option: myOption,
92
+ onEvents: {
93
+ click: (params) => console.log("Clicked:", params.name),
94
+ mouseover: (params) => console.log("Hover:", params.data),
95
+ legendselectchanged: (params) => console.log("Legend:", params.selected),
96
+ },
97
+ });
98
+ ```
99
+
100
+ ## Custom Theme
101
+
102
+ ```tsx
103
+ const { chartRef } = useECharts({
104
+ option: myOption,
105
+ theme: "vintage", // registered theme name
106
+ renderer: "svg", // SVG instead of canvas
107
+ autoResize: false, // manual resize control
108
+ });
109
+ ```
110
+
111
+ ## useResizeObserver
112
+
113
+ A utility hook used internally. Calls a callback whenever the referenced element's size changes.
114
+
115
+ ```ts
116
+ import { useResizeObserver } from "@particle-academy/fancy-echarts";
117
+
118
+ function useResizeObserver(
119
+ ref: RefObject<HTMLElement | null>,
120
+ callback: () => void
121
+ ): void
122
+ ```
123
+
124
+ ```tsx
125
+ const divRef = useRef<HTMLDivElement>(null);
126
+ useResizeObserver(divRef, () => {
127
+ console.log("Container resized");
128
+ });
129
+ ```
package/package.json CHANGED
@@ -1,66 +1,71 @@
1
- {
2
- "name": "@particle-academy/fancy-echarts",
3
- "version": "1.2.0",
4
- "description": "React component library wrapping Apache ECharts with typed components for every chart type",
5
- "repository": {
6
- "type": "git",
7
- "url": "git+https://github.com/Particle-Academy/fancy-echarts.git"
8
- },
9
- "homepage": "https://github.com/Particle-Academy/fancy-echarts#readme",
10
- "bugs": "https://github.com/Particle-Academy/fancy-echarts/issues",
11
- "type": "module",
12
- "main": "./dist/index.cjs",
13
- "module": "./dist/index.js",
14
- "types": "./dist/index.d.ts",
15
- "exports": {
16
- ".": {
17
- "import": {
18
- "types": "./dist/index.d.ts",
19
- "default": "./dist/index.js"
20
- },
21
- "require": {
22
- "types": "./dist/index.d.cts",
23
- "default": "./dist/index.cjs"
24
- }
25
- }
26
- },
27
- "files": [
28
- "dist",
29
- "docs",
30
- "README.md"
31
- ],
32
- "scripts": {
33
- "build": "tsup",
34
- "dev": "tsup --watch",
35
- "lint": "tsc --noEmit",
36
- "clean": "rm -rf dist",
37
- "prepublishOnly": "tsup"
38
- },
39
- "keywords": [
40
- "react",
41
- "echarts",
42
- "charts",
43
- "visualization",
44
- "components"
45
- ],
46
- "peerDependencies": {
47
- "react": "^18.0.0 || ^19.0.0",
48
- "react-dom": "^18.0.0 || ^19.0.0"
49
- },
50
- "dependencies": {
51
- "echarts": "^5.6.0",
52
- "echarts-gl": "^2.0.9"
53
- },
54
- "devDependencies": {
55
- "@types/react": "^19.0.0",
56
- "@types/react-dom": "^19.0.0",
57
- "react": "^19.0.0",
58
- "react-dom": "^19.0.0",
59
- "tsup": "^8.5.0",
60
- "typescript": "^5.8.0"
61
- },
62
- "publishConfig": {
63
- "access": "public"
64
- },
65
- "license": "MIT"
66
- }
1
+ {
2
+ "name": "@particle-academy/fancy-echarts",
3
+ "version": "2.0.0",
4
+ "description": "React component library wrapping Apache ECharts with typed components for every chart type",
5
+ "repository": {
6
+ "type": "git",
7
+ "url": "git+https://github.com/Particle-Academy/fancy-echarts.git"
8
+ },
9
+ "homepage": "https://github.com/Particle-Academy/fancy-echarts#readme",
10
+ "bugs": "https://github.com/Particle-Academy/fancy-echarts/issues",
11
+ "type": "module",
12
+ "main": "./dist/index.cjs",
13
+ "module": "./dist/index.js",
14
+ "types": "./dist/index.d.ts",
15
+ "exports": {
16
+ ".": {
17
+ "import": {
18
+ "types": "./dist/index.d.ts",
19
+ "default": "./dist/index.js"
20
+ },
21
+ "require": {
22
+ "types": "./dist/index.d.cts",
23
+ "default": "./dist/index.cjs"
24
+ }
25
+ }
26
+ },
27
+ "files": [
28
+ "dist",
29
+ "docs",
30
+ "README.md"
31
+ ],
32
+ "scripts": {
33
+ "build": "tsup",
34
+ "dev": "tsup --watch",
35
+ "lint": "tsc --noEmit",
36
+ "clean": "rm -rf dist",
37
+ "prepublishOnly": "tsup"
38
+ },
39
+ "keywords": [
40
+ "react",
41
+ "echarts",
42
+ "charts",
43
+ "visualization",
44
+ "components"
45
+ ],
46
+ "peerDependencies": {
47
+ "react": "^18.0.0 || ^19.0.0",
48
+ "react-dom": "^18.0.0 || ^19.0.0",
49
+ "echarts": "^5.5.0",
50
+ "echarts-gl": "^2.0.0"
51
+ },
52
+ "peerDependenciesMeta": {
53
+ "echarts-gl": {
54
+ "optional": true
55
+ }
56
+ },
57
+ "devDependencies": {
58
+ "@types/react": "^19.0.0",
59
+ "@types/react-dom": "^19.0.0",
60
+ "echarts": "^5.6.0",
61
+ "echarts-gl": "^2.0.9",
62
+ "react": "^19.0.0",
63
+ "react-dom": "^19.0.0",
64
+ "tsup": "^8.5.0",
65
+ "typescript": "^5.8.0"
66
+ },
67
+ "publishConfig": {
68
+ "access": "public"
69
+ },
70
+ "license": "MIT"
71
+ }