vue-echarts 8.1.0 → 8.3.0

package/README.md

@@ -102,6 +102,14 @@ But if you really want to import the whole ECharts bundle without having to impo
 import "echarts";
 ```
 
+#### Styles
+
+When Vue ECharts is imported in a browser, it injects its base styles into the global document, so no CSS import is normally required. For a shadow root or another document, include `vue-echarts/style.css` in that styling scope; see [CSP](#csp-style-src-or-style-src-elem) for the fallback required by older browsers.
+
+### Server-side rendering
+
+`VChart` can be rendered and hydrated by Vue SSR frameworks. The server renders only the chart container; ECharts initializes after the component mounts in the browser. The low-level ECharts `ssr` field in `init-options` does not enable server-side chart rendering in `VChart`.
+
 ### CDN
 
 Drop `<script>` inside your HTML file and access the component via `window.VueECharts`.
@@ -113,8 +121,8 @@ Drop `<script>` inside your HTML file and access the component via `window.VueEC
 
 ```html
 <script src="https://cdn.jsdelivr.net/npm/echarts@6.1.0"></script>
-<script src="https://cdn.jsdelivr.net/npm/vue@3.5.40"></script>
-<script src="https://cdn.jsdelivr.net/npm/vue-echarts@8.1.0"></script>
+<script src="https://cdn.jsdelivr.net/npm/vue@3.5.41"></script>
+<script src="https://cdn.jsdelivr.net/npm/vue-echarts@8.3.0"></script>
 ```
 
 <!-- scripts:end -->
@@ -142,16 +150,27 @@ See more examples [here](https://github.com/ecomfe/vue-echarts/tree/main/demo).
 
   Theme to be applied. See `echarts.init`'s `theme` parameter [here →](https://echarts.apache.org/en/api.html#echarts.init)
 
+  Pass an empty string to use ECharts' default theme while overriding an injected theme.
+
+  ECharts recreates its model when changing themes. Vue ECharts reapplies the latest automatic option, but uncontrolled interaction state (such as legend selection or data zoom) may reset. Keep state that must survive a rebuild in `option`.
+
   Injection key: `THEME_KEY`.
 
 - `option: object`
 
   ECharts' universal interface. Modifying this prop triggers Vue ECharts to compute an update plan and call `setOption`. Read more [here →](https://echarts.apache.org/en/option.html)
+  Temporarily removing the prop pauses automatic updates without letting a later theme change roll the chart back to its initial option.
 
   #### Smart update
-  - If you supply `update-options` (via prop or injection), Vue ECharts forwards it directly to `setOption` and skips the planner.
+
+  Reactive updates describe the complete configuration. Vue ECharts preserves existing models where merging can apply that configuration, and rebuilds when necessary to remove stale settings. A rebuild can reset interaction state such as legend selections and data zoom.
+
+  - If you supply `update-options` (via prop or injection), Vue ECharts forwards it directly to `setOption` and skips the planner. After you remove it, the first smart source-option update rebuilds once to establish a safe structural baseline.
+  - A failed option or theme submission invalidates that baseline. The next smart update rebuilds instead of trusting a potentially partial update.
+  - Automatic option, theme, and slot changes are batched after Vue updates. `clear()` takes effect immediately and cancels already queued automatic work; later changes can populate the chart again.
   - Manual `setOption` calls (only available when `manual-update` is `true`) behave like native ECharts, honouring only the per-call override you pass in and are not carried across re-initializations.
-  - Otherwise, Vue ECharts analyses the change: removed objects become `null`, removed arrays become `[]` with `replaceMerge`, ID/anonymous deletions trigger `replaceMerge`, and risky changes fall back to `notMerge: true`.
+  - Updates containing a graphic element `$action` keep normal merge for `graphic` so the command can target the existing element tree; safe removals of unrelated components still use `replaceMerge`. Changes requiring a full rebuild cannot be applied together with these commands. For complete snapshot semantics, describe the resulting graphic tree without `$action` commands.
+  - Otherwise, Vue ECharts analyses the change: component removals, reordering, and deletions inside anonymous components use `replaceMerge` when it can reproduce the requested order; deletions inside ID-matched components, identity ordering that `replaceMerge` cannot reproduce, newly introduced or shrinking non-component arrays, first-time ARIA configuration, and other risky changes fall back to `notMerge: true`.
 
 - `update-options: object`
 
@@ -165,21 +184,44 @@ See more examples [here](https://github.com/ecomfe/vue-echarts/tree/main/demo).
 
 - `autoresize: boolean | { throttle?: number, onResize?: () => void }` (default: `false`)
 
-  Whether the chart should be resized automatically whenever its root is resized. Use the options object to specify a custom throttle delay (in milliseconds) and/or an extra resize callback function.
+  Whether to resize the chart automatically when its rendering container changes size. Use the options object to specify a custom throttle delay (in milliseconds) and/or an extra resize callback function. Zero-sized containers are not resized; the configured throttle also applies when they recover.
 
 - `loading: boolean` (default: `false`)
 
   Whether the chart is in loading state.
 
+- `loading-type: string`
+
+  Name of the registered loading effect. It is passed as the first argument to `echartsInstance.showLoading`; omit it to use the default effect.
+
 - `loading-options: object`
 
-  Configuration item of loading animation. See `echartsInstance.showLoading`'s `opts` parameter [here →](https://echarts.apache.org/en/api.html#echartsInstance.showLoading)
+  Configuration item of loading animation. Default-effect fields are typed explicitly, and additional fields for custom effects are forwarded to `echartsInstance.showLoading`. See its `opts` parameter [here →](https://echarts.apache.org/en/api.html#echartsInstance.showLoading)
 
   Injection key: `LOADING_OPTIONS_KEY`.
 
 - `manual-update: boolean` (default: `false`)
 
-  Handy for performance-sensitive charts (large or high-frequency updates). When set to `true`, Vue only uses the `option` prop for the initial render; later prop changes do nothing and you must drive updates via `setOption` on a template ref. If the chart re-initializes (for example due to `init-options` changes, flipping `manual-update`, or a remount), the manual state is discarded and the chart is rendered again from the current `option` value.
+  Handy for performance-sensitive charts (large or high-frequency updates). When set to `true`, Vue uses the `option` prop for the initial render but does not deeply observe it afterwards; later prop changes do nothing and you must drive updates via `setOption` on a template ref. The component-managed initial render still honors `update-options`, while later manual calls use only their per-call arguments. If `autoresize` defers that first render and you successfully call `setOption` first, the manual call takes precedence. If the chart re-initializes (for example due to `init-options` changes, flipping `manual-update`, or a remount), the manual state is discarded and the chart is rendered again from the current `option` value.
+
+#### TypeScript
+
+Component-specific prop types are available from the package root:
+
+```ts
+import type { AutoResize, LoadingOptions } from "vue-echarts";
+```
+
+For a typed template ref:
+
+```ts
+import VChart from "vue-echarts";
+import { ref } from "vue";
+
+const chart = ref<InstanceType<typeof VChart> | null>(null);
+```
+
+Vue 3.5's `useTemplateRef` can infer this type automatically.
 
 ### Events
 
@@ -192,9 +234,9 @@ You can bind events with Vue's `v-on` directive.
 ```
 
 > [!NOTE]
-> Only the `.once` event modifier is supported as other modifiers are tightly coupled with the DOM event system.
+> ECharts and ZRender events only support the `.once` modifier; other modifiers are specific to DOM events. Listeners using the `native:` prefix support Vue's normal DOM event modifiers.
 
-Vue ECharts support the following events:
+Vue ECharts supports the following events:
 
 - `highlight` [→](https://echarts.apache.org/en/api.html#events.highlight)
 - `downplay` [→](https://echarts.apache.org/en/api.html#events.downplay)
@@ -207,6 +249,13 @@ Vue ECharts support the following events:
 - `legendscroll` [→](https://echarts.apache.org/en/api.html#events.legendscroll)
 - `datazoom` [→](https://echarts.apache.org/en/api.html#events.datazoom)
 - `datarangeselected` [→](https://echarts.apache.org/en/api.html#events.datarangeselected)
+- `graphroam` [→](https://echarts.apache.org/en/api.html#events.graphroam)
+- `georoam` [→](https://echarts.apache.org/en/api.html#events.georoam)
+- `treeroam` [→](https://echarts.apache.org/en/api.html#events.treeroam)
+- `sankeyroam` [→](https://echarts.apache.org/en/api.html#events.sankeyroam)
+- `focusnodeadjacency`, `unfocusnodeadjacency` (legacy graph adjacency focus actions)
+- `dragnode` [→](https://echarts.apache.org/en/api.html#events.dragnode)
+- `treeexpandandcollapse` [→](https://echarts.apache.org/en/api.html#events.treeexpandandcollapse)
 - `timelinechanged` [→](https://echarts.apache.org/en/api.html#events.timelinechanged)
 - `timelineplaychanged` [→](https://echarts.apache.org/en/api.html#events.timelineplaychanged)
 - `restore` [→](https://echarts.apache.org/en/api.html#events.restore)
@@ -215,11 +264,16 @@ Vue ECharts support the following events:
 - `geoselectchanged` [→](https://echarts.apache.org/en/api.html#events.geoselectchanged)
 - `geoselected` [→](https://echarts.apache.org/en/api.html#events.geoselected)
 - `geounselected` [→](https://echarts.apache.org/en/api.html#events.geounselected)
+- `axisbreakchanged` [→](https://echarts.apache.org/en/api.html#events.axisbreakchanged)
 - `axisareaselected` [→](https://echarts.apache.org/en/api.html#events.axisareaselected)
 - `brush` [→](https://echarts.apache.org/en/api.html#events.brush)
-- `brushEnd` [→](https://echarts.apache.org/en/api.html#events.brushEnd)
+- `brushend` [→](https://echarts.apache.org/en/api.html#events.brushEnd)
 - `brushselected` [→](https://echarts.apache.org/en/api.html#events.brushselected)
+- `showtip` [→](https://echarts.apache.org/en/api.html#action.tooltip.showTip)
+- `hidetip` [→](https://echarts.apache.org/en/api.html#action.tooltip.hideTip)
+- `updateaxispointer` [→](https://echarts.apache.org/en/api.html#action.axisPointer.updateAxisPointer)
 - `globalcursortaken` [→](https://echarts.apache.org/en/api.html#events.globalcursortaken)
+- `updated` (after an ECharts update completes)
 - `rendered` [→](https://echarts.apache.org/en/api.html#events.rendered)
 - `finished` [→](https://echarts.apache.org/en/api.html#events.finished)
 - Mouse events
@@ -234,11 +288,22 @@ Vue ECharts support the following events:
   - `contextmenu` [→](https://echarts.apache.org/en/api.html#events.Mouse%20events.contextmenu)
 - ZRender events
   - `zr:click`
-  - `zr:mousedown`
-  - `zr:mouseup`
-  - `zr:mousewheel`
   - `zr:dblclick`
+  - `zr:mouseout`
+  - `zr:mouseover`
+  - `zr:mouseup`
+  - `zr:mousedown`
+  - `zr:mousemove`
   - `zr:contextmenu`
+  - `zr:globalout`
+  - `zr:mousewheel`
+  - `zr:drag`
+  - `zr:dragstart`
+  - `zr:dragend`
+  - `zr:dragenter`
+  - `zr:dragleave`
+  - `zr:dragover`
+  - `zr:drop`
 
 See supported events in the [ECharts API reference →](https://echarts.apache.org/en/api.html#events)
 
@@ -252,12 +317,18 @@ As Vue ECharts binds events to the ECharts instance by default, there is some ca
 </template>
 ```
 
-Event handlers passed via attrs are reactive by default. Updating `onClick`, `onZr:*`, or `onNative:*` handlers will rebind them automatically.
+Case-sensitive custom events are supported by writing their exact name after `native:`, for example `@native:ChartReady`.
+
+Event handlers passed via attrs are reactive by default. Updates to `onClick`, `onZr:*`, or `onNative:*` handlers take effect automatically.
+Multiword handlers accept idiomatic camel case, such as `onDataZoom`, `onBrushEnd`, and `onZr:mouseMove`; existing forms such as `onDatazoom`, `onBrushend`, and `onZr:mousemove` remain supported.
 
 ### Provide / inject
 
 Vue ECharts provides provide/inject API for `theme`, `init-options`, `update-options` and `loading-options` to help configuring contextual options. eg. for `theme` you can use the provide API like this:
 
+Explicit props take precedence over injected values.
+Reactive providers may resolve to `null` or `undefined` while a contextual value is unavailable.
+
 <details>
 <summary>Composition API</summary>
 
@@ -280,56 +351,87 @@ provide(THEME_KEY, () => theme.value);
 <details>
 <summary>Options API</summary>
 
+Static value:
+
 ```js
-import { THEME_KEY } from 'vue-echarts'
-import { computed } from 'vue'
+import { THEME_KEY } from "vue-echarts";
 
 export default {
-  {
-    provide: {
-      [THEME_KEY]: 'dark'
-    }
-  }
-}
+  provide: {
+    [THEME_KEY]: "dark",
+  },
+};
+```
+
+Reactive value:
+
+```js
+import { THEME_KEY } from "vue-echarts";
+import { computed } from "vue";
 
-// Or make injections reactive
 export default {
   data() {
     return {
-      theme: 'dark'
-    }
+      theme: "dark",
+    };
   },
   provide() {
     return {
-      [THEME_KEY]: computed(() => this.theme)
-    }
-  }
-}
+      [THEME_KEY]: computed(() => this.theme),
+    };
+  },
+};
 ```
 
 </details>
 
+### Properties
+
+- `chart: ECharts | undefined`
+
+  The current underlying ECharts instance. This property is read-only and changes when the component re-initializes the chart; it becomes `undefined` after disposal. Prefer the methods below for supported operations. Direct option mutations are not tracked by the smart updater, so use `manual-update` when driving `setOption` imperatively.
+
+- `root: HTMLElement | undefined`
+
+  The component's read-only `<x-vue-echarts>` root element, available after mounting.
+
 ### Methods
 
 - `setOption` [→](https://echarts.apache.org/en/api.html#echartsInstance.setOption)
 - `getWidth` [→](https://echarts.apache.org/en/api.html#echartsInstance.getWidth)
 - `getHeight` [→](https://echarts.apache.org/en/api.html#echartsInstance.getHeight)
 - `getDom` [→](https://echarts.apache.org/en/api.html#echartsInstance.getDom)
+- `getZr` [→](https://echarts.apache.org/en/api.html#echartsInstance.getZr)
+- `getId` [→](https://echarts.apache.org/en/api.html#echartsInstance.getId)
 - `getOption` [→](https://echarts.apache.org/en/api.html#echartsInstance.getOption)
+- `isSSR` [→](https://echarts.apache.org/en/api.html#echartsInstance.isSSR)
+- `getDevicePixelRatio` [→](https://echarts.apache.org/en/api.html#echartsInstance.getDevicePixelRatio)
 - `resize` [→](https://echarts.apache.org/en/api.html#echartsInstance.resize)
+- `makeActionFromEvent` [→](https://echarts.apache.org/en/api.html#echartsInstance.makeActionFromEvent)
 - `dispatchAction` [→](https://echarts.apache.org/en/api.html#echartsInstance.dispatchAction)
+- `updateLabelLayout` [→](https://echarts.apache.org/en/api.html#echartsInstance.updateLabelLayout)
 - `convertToPixel` [→](https://echarts.apache.org/en/api.html#echartsInstance.convertToPixel)
+- `convertToLayout` [→](https://echarts.apache.org/en/api.html#echartsInstance.convertToLayout)
 - `convertFromPixel` [→](https://echarts.apache.org/en/api.html#echartsInstance.convertFromPixel)
 - `containPixel` [→](https://echarts.apache.org/en/api.html#echartsInstance.containPixel)
+- `getVisual` [→](https://echarts.apache.org/en/api.html#echartsInstance.getVisual)
+- `renderToCanvas` [→](https://echarts.apache.org/en/api.html#echartsInstance.renderToCanvas)
+- `renderToSVGString` [→](https://echarts.apache.org/en/api.html#echartsInstance.renderToSVGString)
+- `getSvgDataURL` [→](https://echarts.apache.org/en/api.html#echartsInstance.getSvgDataURL)
 - `getDataURL` [→](https://echarts.apache.org/en/api.html#echartsInstance.getDataURL)
 - `getConnectedDataURL` [→](https://echarts.apache.org/en/api.html#echartsInstance.getConnectedDataURL)
+- `appendData` [→](https://echarts.apache.org/en/api.html#echartsInstance.appendData)
 - `clear` [→](https://echarts.apache.org/en/api.html#echartsInstance.clear)
+- `isDisposed` [→](https://echarts.apache.org/en/api.html#echartsInstance.isDisposed)
 - `dispose` [→](https://echarts.apache.org/en/api.html#echartsInstance.dispose)
 
+`dispose` is terminal for the current component instance. Use it instead of calling `dispose` on
+the raw `chart` instance; remount the component to initialize a new chart.
+
 > [!NOTE]
 > The following ECharts instance methods aren't exposed because their functionality is already provided by component [props](#props):
 >
-> - [`showLoading`](https://echarts.apache.org/en/api.html#echartsInstance.showLoading) / [`hideLoading`](https://echarts.apache.org/en/api.html#echartsInstance.hideLoading): use the `loading` and `loading-options` props instead.
+> - [`showLoading`](https://echarts.apache.org/en/api.html#echartsInstance.showLoading) / [`hideLoading`](https://echarts.apache.org/en/api.html#echartsInstance.hideLoading): use the `loading`, `loading-type` and `loading-options` props instead.
 > - [`setTheme`](https://echarts.apache.org/en/api.html#echartsInstance.setTheme): use the `theme` prop instead.
 
 ### Slots
@@ -345,16 +447,21 @@ Vue ECharts supports three slot categories:
 These naming rules apply to callback slots only. The graphic slot name is always `#graphic`.
 
 - Slot names begin with `tooltip`/`dataView`, followed by hyphen-separated path segments to the target.
-- Each segment corresponds to an `option` property name or an array index (for arrays, use the numeric index).
+- If `tooltip` or `toolbox` is an array, place its numeric component index immediately after the slot prefix; any remaining segments still locate the owning option.
+- Each non-empty segment corresponds to an `option` property name or an array index (for arrays, use the numeric index).
+- Array segments are patched only when the corresponding array entries already exist; callback slots do not create missing component or data arrays.
+- The reserved JavaScript path segment `__proto__` is rejected.
 - The constructed slot name maps directly to the nested callback it overrides.
 
 **Example mappings**:
 
 - `tooltip` → `option.tooltip.formatter`
+- `tooltip-0` → `option.tooltip[0].formatter`
 - `tooltip-baseOption` → `option.baseOption.tooltip.formatter`
 - `tooltip-xAxis-1` → `option.xAxis[1].tooltip.formatter`
 - `tooltip-series-2-data-4` → `option.series[2].data[4].tooltip.formatter`
 - `dataView` → `option.toolbox.feature.dataView.optionToContent`
+- `dataView-1` → `option.toolbox[1].feature.dataView.optionToContent`
 - `dataView-media-1-option` → `option.media[1].option.toolbox.feature.dataView.optionToContent`
 
 The slot props correspond to the first parameter of the callback function.
@@ -407,6 +514,8 @@ The slot props correspond to the first parameter of the callback function.
 
 > [!NOTE]
 > Slots take precedence over the corresponding callback defined in `props.option`.
+> Removing a callback slot explicitly clears its injected function without rebuilding the chart.
+> After adding or removing a callback slot in `manual-update` mode, call `chartRef.setOption(...)` to submit the latest slot set.
 
 #### Graphic slot&nbsp;<sup><a href="#slots"><img src="https://img.shields.io/badge/new-A855F7" alt="new" align="middle" height="16"></a></sup>
 
@@ -419,6 +528,7 @@ Available components:
 - `GGroup`
 - `GRect`
 - `GCircle`
+- `GEllipse`
 - `GText`
 - `GLine`
 - `GPolyline`
@@ -428,7 +538,6 @@ Available components:
 - `GRing`
 - `GArc`
 - `GBezierCurve`
-- `GCompoundPath`
 
 Read more at [ECharts `option.graphic` →](https://echarts.apache.org/en/option.html#graphic)
 
@@ -436,7 +545,12 @@ Read more at [ECharts `option.graphic` →](https://echarts.apache.org/en/option
 >
 > - Graphic element events additionally support `dblclick` and `contextmenu`.
 > - Event listeners support the `.once` modifier.
+> - Returning `true` from a graphic element listener stops the event from bubbling.
+> - Path components accept `auto-batch` to opt into ZRender's Canvas path batching.
+> - The `option` prop may be omitted for graphic-only charts.
 > - `#graphic` overrides `option.graphic`. In `manual-update` mode, call `chartRef.setOption(...)` to apply changes.
+> - Wrapper components and Fragments preserve their rendered graphic order. Compatible property changes update only changed elements, preserving unchanged elements and their running animations. Removing fields, changing types, or changing tree structure rebuilds the graphic component.
+> - Graphic-only changes omit unrelated source options when safe. Explicit `notMerge` or `replaceMerge` targeting other components still submits the full source option.
 
 <details>
 <summary>Usage</summary>
@@ -469,7 +583,7 @@ function onDrag(event: ElementEvent) {
           :x="10"
           :y="8"
           :text="`x: ${Math.round(overlay.x)} y: ${Math.round(overlay.y)}`"
-          text-fill="#fff"
+          fill="#fff"
         />
       </GGroup>
     </template>
@@ -485,6 +599,10 @@ Static methods can be accessed from [`echarts` itself](https://echarts.apache.or
 
 ## CSP: `style-src` or `style-src-elem`
 
+Vue ECharts injects its base styles into the global document when its module is evaluated. Shadow
+roots and other documents do not receive these styles; include `vue-echarts/style.css` in each
+target styling scope when needed.
+
 If you are **both** enforcing a strict CSP that prevents inline `<style>` injection and targeting browsers that don't support the [CSSStyleSheet() constructor](https://developer.mozilla.org/en-US/docs/Web/API/CSSStyleSheet/CSSStyleSheet#browser_compatibility), you need to manually include `vue-echarts/style.css`.
 
 ## Migration to v8