vue-echarts 8.1.0 → 8.2.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.2.0"></script>
 ```
 
 <!-- scripts:end -->
@@ -142,16 +150,20 @@ 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.
+
   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.
+  - 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 update rebuilds once to establish a safe structural baseline.
   - 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`.
+  - 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 +177,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 +227,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 +242,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 +257,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 +281,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 +310,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 +344,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 +440,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 +507,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 +521,7 @@ Available components:
 - `GGroup`
 - `GRect`
 - `GCircle`
+- `GEllipse`
 - `GText`
 - `GLine`
 - `GPolyline`
@@ -428,7 +531,6 @@ Available components:
 - `GRing`
 - `GArc`
 - `GBezierCurve`
-- `GCompoundPath`
 
 Read more at [ECharts `option.graphic` →](https://echarts.apache.org/en/option.html#graphic)
 
@@ -436,6 +538,9 @@ 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.
 
 <details>
@@ -469,7 +574,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 +590,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