@particle-academy/fancy-echarts 1.2.0

package/docs/registration.md

@@ -0,0 +1,152 @@
+# Registration
+
+ECharts uses a modular architecture. You must register chart types and components before using them. This package provides helpers for both quick-start and tree-shaking-optimized approaches.
+
+## Import
+
+```tsx
+import {
+  registerAll,
+  registerCharts,
+  registerComponents,
+  // Individual charts
+  LineChart, BarChart, PieChart, ScatterChart, RadarChart,
+  HeatmapChart, GaugeChart, FunnelChart, TreemapChart, SunburstChart,
+  SankeyChart, GraphChart, CandlestickChart, BoxplotChart, ParallelChart,
+  ThemeRiverChart, MapChart, CustomChart, EffectScatterChart, PictorialBarChart,
+  // Components
+  GridComponent, TooltipComponent, TitleComponent, LegendComponent,
+  DataZoomComponent, ToolboxComponent, VisualMapComponent, GeoComponent,
+  CalendarComponent, GraphicComponent, PolarComponent, DatasetComponent,
+  // Renderers
+  CanvasRenderer, SVGRenderer,
+} from "@particle-academy/fancy-echarts";
+```
+
+## Quick Start: registerAll
+
+Registers all chart types, all components, and both renderers. Convenient but not tree-shakeable.
+
+```tsx
+// Call once at app entry (e.g., main.tsx)
+import { registerAll } from "@particle-academy/fancy-echarts";
+registerAll();
+```
+
+Calling `registerAll()` multiple times is safe -- it no-ops after the first call.
+
+## Selective Registration
+
+### registerCharts
+
+Register only the chart types you need.
+
+```tsx
+import {
+  registerCharts,
+  LineChart,
+  BarChart,
+  PieChart,
+} from "@particle-academy/fancy-echarts";
+
+registerCharts(LineChart, BarChart, PieChart);
+```
+
+### registerComponents
+
+Register only the UI components you need.
+
+```tsx
+import {
+  registerComponents,
+  GridComponent,
+  TooltipComponent,
+  TitleComponent,
+  LegendComponent,
+} from "@particle-academy/fancy-echarts";
+
+registerComponents(GridComponent, TooltipComponent, TitleComponent, LegendComponent);
+```
+
+### Manual Registration
+
+For full control, import and register directly via `echarts/core`:
+
+```tsx
+import { use } from "echarts/core";
+import { LineChart } from "@particle-academy/fancy-echarts";
+import { GridComponent, TooltipComponent } from "@particle-academy/fancy-echarts";
+import { CanvasRenderer } from "@particle-academy/fancy-echarts";
+
+use([LineChart, GridComponent, TooltipComponent, CanvasRenderer]);
+```
+
+## Available Charts
+
+| Export | ECharts Type |
+|--------|-------------|
+| `LineChart` | `line` |
+| `BarChart` | `bar` |
+| `PieChart` | `pie` |
+| `ScatterChart` | `scatter` |
+| `RadarChart` | `radar` |
+| `HeatmapChart` | `heatmap` |
+| `GaugeChart` | `gauge` |
+| `FunnelChart` | `funnel` |
+| `TreemapChart` | `treemap` |
+| `SunburstChart` | `sunburst` |
+| `SankeyChart` | `sankey` |
+| `GraphChart` | `graph` |
+| `CandlestickChart` | `candlestick` |
+| `BoxplotChart` | `boxplot` |
+| `ParallelChart` | `parallel` |
+| `ThemeRiverChart` | `themeRiver` |
+| `MapChart` | `map` |
+| `CustomChart` | `custom` |
+| `EffectScatterChart` | `effectScatter` |
+| `PictorialBarChart` | `pictorialBar` |
+
+## Available Components
+
+| Export | Purpose |
+|--------|---------|
+| `GridComponent` | Cartesian grid layout |
+| `TooltipComponent` | Hover tooltips |
+| `TitleComponent` | Chart title |
+| `LegendComponent` | Series legend |
+| `DataZoomComponent` | Zoom/pan controls |
+| `ToolboxComponent` | Save, restore, data view tools |
+| `VisualMapComponent` | Color/size mapping |
+| `GeoComponent` | Geographic coordinate system |
+| `CalendarComponent` | Calendar heatmap layout |
+| `GraphicComponent` | Custom graphic elements |
+| `PolarComponent` | Polar coordinate system |
+| `DatasetComponent` | Dataset-driven charts |
+
+## Renderers
+
+| Export | Description |
+|--------|-------------|
+| `CanvasRenderer` | Canvas-based rendering (default, better performance) |
+| `SVGRenderer` | SVG-based rendering (better for small charts, CSS styling) |
+
+## Recommended Setup
+
+For production apps, register only what you use:
+
+```tsx
+// chart-setup.ts
+import { registerCharts, registerComponents, CanvasRenderer } from "@particle-academy/fancy-echarts";
+import { LineChart, BarChart, PieChart } from "@particle-academy/fancy-echarts";
+import { GridComponent, TooltipComponent, TitleComponent, LegendComponent } from "@particle-academy/fancy-echarts";
+import { use } from "echarts/core";
+
+registerCharts(LineChart, BarChart, PieChart);
+registerComponents(GridComponent, TooltipComponent, TitleComponent, LegendComponent);
+use([CanvasRenderer]);
+```
+
+```tsx
+// main.tsx
+import "./chart-setup";
+```

package/docs/themes.md

@@ -0,0 +1,152 @@
+# Themes
+
+Built-in theme presets and utilities for registering custom themes with ECharts.
+
+## Import
+
+```tsx
+import {
+  darkTheme,
+  vintageTheme,
+  pastelTheme,
+  registerTheme,
+  registerBuiltinThemes,
+} from "@particle-academy/fancy-echarts";
+```
+
+## Quick Start
+
+Register all built-in themes at app entry:
+
+```tsx
+import { registerBuiltinThemes } from "@particle-academy/fancy-echarts";
+registerBuiltinThemes();
+```
+
+Then use by name:
+
+```tsx
+<EChart option={myOption} theme="vintage" />
+<EChart option={myOption} theme="pastel" />
+<EChart option={myOption} theme="dark-preset" />
+```
+
+## Built-in Themes
+
+### darkTheme
+
+Registered as `"dark-preset"`. Dark background (`#1a1a2e`) with light text and muted axis lines.
+
+| Property | Value |
+|----------|-------|
+| Background | `#1a1a2e` |
+| Text color | `#e0e0e0` |
+| Title color | `#ffffff` |
+| Axis lines | `#444` |
+| Palette | `#5470c6`, `#91cc75`, `#fac858`, `#ee6666`, `#73c0de`, `#3ba272`, `#fc8452`, `#9a60b4`, `#ea7ccc` |
+
+### vintageTheme
+
+Registered as `"vintage"`. Warm parchment background (`#fef8ef`) with earthy tones.
+
+| Property | Value |
+|----------|-------|
+| Background | `#fef8ef` |
+| Title color | `#333333` |
+| Axis lines | `#ccc` |
+| Palette | `#d87c7c`, `#919e8b`, `#d7ab82`, `#6e7074`, `#61a0a8`, `#efa18d`, `#787464`, `#cc7e63`, `#724e58`, `#4b565b` |
+
+### pastelTheme
+
+Registered as `"pastel"`. Light background (`#fafafa`) with soft pastel colors.
+
+| Property | Value |
+|----------|-------|
+| Background | `#fafafa` |
+| Text color | `#555` |
+| Title color | `#333` |
+| Palette | `#c4b5fd`, `#a5f3fc`, `#fca5a5`, `#fde68a`, `#a7f3d0`, `#fbcfe8`, `#c7d2fe`, `#fed7aa` |
+
+## API
+
+### registerTheme
+
+Register a custom theme by name. Wraps `echarts.registerTheme()`.
+
+```ts
+function registerTheme(name: string, theme: object): void
+```
+
+```tsx
+registerTheme("corporate", {
+  color: ["#003f5c", "#58508d", "#bc5090", "#ff6361", "#ffa600"],
+  backgroundColor: "#ffffff",
+  textStyle: { color: "#333" },
+  title: { textStyle: { color: "#003f5c" } },
+});
+```
+
+### registerBuiltinThemes
+
+Registers all three built-in themes (`"dark-preset"`, `"vintage"`, `"pastel"`). Call once at app startup.
+
+```ts
+function registerBuiltinThemes(): void
+```
+
+## Using Themes
+
+### By registered name
+
+```tsx
+<EChart option={option} theme="vintage" />
+```
+
+### By object (inline, no registration needed)
+
+```tsx
+<EChart option={option} theme={darkTheme} />
+<EChart option={option} theme={{ color: ["#e63946", "#457b9d", "#1d3557"] }} />
+```
+
+### Auto Dark Mode
+
+When `theme` is omitted, `useECharts` auto-detects the system `prefers-color-scheme: dark` preference and applies ECharts' built-in `"dark"` theme (not `darkTheme` from this package). The background is set to `transparent` so the chart inherits the page background.
+
+```tsx
+{/* Automatically switches between light and dark based on OS setting */}
+<EChart option={option} />
+```
+
+To opt out, pass any explicit theme (including `undefined` as a string or object):
+
+```tsx
+<EChart option={option} theme="" />
+```
+
+## Custom Theme Example
+
+```tsx
+import { registerTheme } from "@particle-academy/fancy-echarts";
+
+const neonTheme = {
+  backgroundColor: "#0a0a0a",
+  textStyle: { color: "#00ff88" },
+  title: { textStyle: { color: "#00ff88" } },
+  color: ["#00ff88", "#ff0080", "#00ccff", "#ffcc00", "#ff4400"],
+  categoryAxis: {
+    axisLine: { lineStyle: { color: "#333" } },
+    axisLabel: { color: "#888" },
+  },
+  valueAxis: {
+    axisLine: { lineStyle: { color: "#333" } },
+    splitLine: { lineStyle: { color: "#222" } },
+    axisLabel: { color: "#888" },
+  },
+};
+
+registerTheme("neon", neonTheme);
+
+// Then use it
+<EChart option={option} theme="neon" />
+```

package/docs/useECharts.md

@@ -0,0 +1,129 @@
+# useECharts
+
+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`.
+
+## Import
+
+```tsx
+import { useECharts } from "@particle-academy/fancy-echarts";
+import type { UseEChartsOptions, UseEChartsReturn } from "@particle-academy/fancy-echarts";
+```
+
+## Signature
+
+```ts
+function useECharts(options: UseEChartsOptions): UseEChartsReturn
+```
+
+## Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `option` | `EChartsOption` | **required** | ECharts option object |
+| `theme` | `string \| object` | `undefined` | Theme name or object. When omitted, auto-detects dark mode |
+| `renderer` | `"canvas" \| "svg"` | `"canvas"` | Rendering engine |
+| `notMerge` | `boolean` | `false` | Replace option instead of merging |
+| `lazyUpdate` | `boolean` | `false` | Delay chart update |
+| `showLoading` | `boolean` | `false` | Show loading animation |
+| `loadingOption` | `object` | `undefined` | Customize loading spinner |
+| `onEvents` | `Record<string, (params) => void>` | `undefined` | Event handlers keyed by event name |
+| `autoResize` | `boolean` | `true` | Auto-resize via `ResizeObserver` |
+
+## Return Value
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `chartRef` | `RefObject<HTMLDivElement \| null>` | Ref to attach to a container div |
+| `instance` | `ECharts \| null` | The ECharts instance (null before init) |
+
+## Behavior
+
+- **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.
+- **Re-initialization:** The chart instance is disposed and re-created when `theme` or `renderer` changes.
+- **StrictMode safe:** Handles React 18 StrictMode double-mount by disposing any existing instance on the same DOM element.
+- **Event cleanup:** Event listeners are bound/unbound cleanly via `useEffect` cleanup.
+- **Resize:** Uses `useResizeObserver` internally to call `chart.resize()` on container size changes.
+
+## Basic Usage
+
+```tsx
+function MyChart({ data }) {
+  const option = useMemo(() => ({
+    xAxis: { type: "category", data: ["A", "B", "C"] },
+    yAxis: { type: "value" },
+    series: [{ type: "bar", data }],
+  }), [data]);
+
+  const { chartRef } = useECharts({ option });
+
+  return <div ref={chartRef} style={{ width: "100%", height: 400 }} />;
+}
+```
+
+## Accessing the Instance
+
+```tsx
+function ExportableChart() {
+  const { chartRef, instance } = useECharts({
+    option: { /* ... */ },
+  });
+
+  const handleExport = () => {
+    if (instance) {
+      const dataUrl = instance.getDataURL({ type: "png" });
+      // download or display dataUrl
+    }
+  };
+
+  return (
+    <div>
+      <div ref={chartRef} style={{ width: "100%", height: 400 }} />
+      <button onClick={handleExport}>Export PNG</button>
+    </div>
+  );
+}
+```
+
+## Event Handling
+
+```tsx
+const { chartRef } = useECharts({
+  option: myOption,
+  onEvents: {
+    click: (params) => console.log("Clicked:", params.name),
+    mouseover: (params) => console.log("Hover:", params.data),
+    legendselectchanged: (params) => console.log("Legend:", params.selected),
+  },
+});
+```
+
+## Custom Theme
+
+```tsx
+const { chartRef } = useECharts({
+  option: myOption,
+  theme: "vintage",       // registered theme name
+  renderer: "svg",        // SVG instead of canvas
+  autoResize: false,      // manual resize control
+});
+```
+
+## useResizeObserver
+
+A utility hook used internally. Calls a callback whenever the referenced element's size changes.
+
+```ts
+import { useResizeObserver } from "@particle-academy/fancy-echarts";
+
+function useResizeObserver(
+  ref: RefObject<HTMLElement | null>,
+  callback: () => void
+): void
+```
+
+```tsx
+const divRef = useRef<HTMLDivElement>(null);
+useResizeObserver(divRef, () => {
+  console.log("Container resized");
+});
+```

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@particle-academy/fancy-echarts",
+  "version": "1.2.0",
+  "description": "React component library wrapping Apache ECharts with typed components for every chart type",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Particle-Academy/fancy-echarts.git"
+  },
+  "homepage": "https://github.com/Particle-Academy/fancy-echarts#readme",
+  "bugs": "https://github.com/Particle-Academy/fancy-echarts/issues",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "docs",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "tsup"
+  },
+  "keywords": [
+    "react",
+    "echarts",
+    "charts",
+    "visualization",
+    "components"
+  ],
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "dependencies": {
+    "echarts": "^5.6.0",
+    "echarts-gl": "^2.0.9"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tsup": "^8.5.0",
+    "typescript": "^5.8.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT"
+}