types: use more precise typings for event handlers, update peer deps for echarts

CHANGELOG.md

@@ -1,3 +1,20 @@
+## 6.5.0
+
+* Use more precise typings for all event params.
+* Updated peer deps for `echarts` to `^5.4.1`.
+
+## 6.4.1
+
+* Improve typings for mouse event params.
+
+## 6.4.0
+
+* Delay the disposal of the ECharts instance to the moment the element is disconnected from the DOM if possible (#433).
+
+## 6.3.3
+
+* Make autoresize work for grid layout by default (#675).
+
 ## 6.3.2
 
 * Added basic types for events (only event names).

README.md

@@ -20,13 +20,13 @@ Not ready yet? Read documentation for older versions [here →](https://github.c
 $ npm install echarts vue-echarts
 ```
 
-To make `vue-echarts` work for *Vue 2* (<2.7.0), you need to have `@vue/composition-api` installed:
+To make `vue-echarts` work for _Vue 2_ (<2.7.0), you need to have `@vue/composition-api` installed:
 
 ```sh
 npm i -D @vue/composition-api
 ```
 
-If you are using *NuxtJS* on top of *Vue 2* (<2.7.0), you'll also need `@nuxtjs/composition-api`:
+If you are using _NuxtJS_ on top of _Vue 2_ (<2.7.0), you'll also need `@nuxtjs/composition-api`:
 
 ```sh
 npm i -D @nuxtjs/composition-api
@@ -34,87 +34,7 @@ npm i -D @nuxtjs/composition-api
 
 And then add `'@nuxtjs/composition-api/module'` in the `buildModules` option in your `nuxt.config.js`.
 
-<details>
+#### Example
-<summary>Vue 3</summary>
-
-```js
-import { createApp } from 'vue'
-import ECharts from 'vue-echarts'
-import { use } from "echarts/core"
-
-// import ECharts modules manually to reduce bundle size
-import {
-  CanvasRenderer
-} from 'echarts/renderers'
-import {
-  BarChart
-} from 'echarts/charts'
-import {
-  GridComponent,
-  TooltipComponent
-} from 'echarts/components'
-
-use([
-  CanvasRenderer,
-  BarChart,
-  GridComponent,
-  TooltipComponent
-])
-
-const app = createApp(...)
-
-// register globally (or you can do it locally)
-app.component('v-chart', ECharts)
-
-app.mount(...)
-```
-
-</details>
-
-<details>
-<summary>Vue 2</summary>
-
-```js
-import Vue from 'vue'
-import ECharts from 'vue-echarts'
-import { use } from 'echarts/core'
-
-// import ECharts modules manually to reduce bundle size
-import {
-  CanvasRenderer
-} from 'echarts/renderers'
-import {
-  BarChart
-} from 'echarts/charts'
-import {
-  GridComponent,
-  TooltipComponent
-} from 'echarts/components'
-
-use([
-  CanvasRenderer,
-  BarChart,
-  GridComponent,
-  TooltipComponent
-]);
-
-// register globally (or you can do it locally)
-Vue.component('v-chart', ECharts)
-
-new Vue(...)
-```
-
-</details>
-
-We encourage manually importing components and charts from ECharts for smaller bundle size. See all supported renderers/charts/components [here →](https://github.com/apache/echarts/blob/master/src/echarts.all.ts)
-
-But if you really want to import the whole ECharts bundle without having to import modules manually, just add this in your code:
-
-```js
-import "echarts";
-```
-
-#### SFC example
 
 <details>
 <summary>Vue 3 <a href="https://stackblitz.com/edit/vue-echarts-vue-3?file=src%2FApp.vue">Demo →</a></summary>
@@ -124,7 +44,7 @@ import "echarts";
   <v-chart class="chart" :option="option" />
 </template>
 
-<script>
+<script setup>
 import { use } from "echarts/core";
 import { CanvasRenderer } from "echarts/renderers";
 import { PieChart } from "echarts/charts";
@@ -134,7 +54,7 @@ import {
   LegendComponent
 } from "echarts/components";
 import VChart, { THEME_KEY } from "vue-echarts";
-import { ref, defineComponent } from "vue";
+import { ref, provide } from "vue";
 
 use([
   CanvasRenderer,
@@ -144,16 +64,9 @@ use([
   LegendComponent
 ]);
 
-export default defineComponent({
+provide(THEME_KEY, "dark");
-  name: "HelloWorld",
+
-  components: {
+const option = ref({
-    VChart
-  },
-  provide: {
-    [THEME_KEY]: "dark"
-  },
-  setup () {
-    const option = ref({
   title: {
     text: "Traffic Sources",
     left: "center"
@@ -189,10 +102,6 @@ export default defineComponent({
       }
     }
   ]
-    });
-
-    return { option };
-  }
 });
 </script>
 
@@ -299,6 +208,14 @@ export default {
 
 </details>
 
+We encourage manually importing components and charts from ECharts for smaller bundle size. See all supported renderers/charts/components [here →](https://github.com/apache/echarts/blob/master/src/echarts.all.ts)
+
+But if you really want to import the whole ECharts bundle without having to import modules manually, just add this in your code:
+
+```js
+import "echarts";
+```
+
 ### CDN & Global variable
 
 Drop `<script>` inside your HTML file and access the component via `window.VueECharts`.
@@ -310,7 +227,7 @@ Drop `<script>` inside your HTML file and access the component via `window.VueEC
 ```html
 <script src="https://cdn.jsdelivr.net/npm/vue@3.2.37"></script>
 <script src="https://cdn.jsdelivr.net/npm/echarts@5.3.3"></script>
-<script src="https://cdn.jsdelivr.net/npm/vue-echarts@6.3.2"></script>
+<script src="https://cdn.jsdelivr.net/npm/vue-echarts@6.5.0"></script>
 ```
 <!-- vue3Scripts:end -->
 
@@ -330,7 +247,7 @@ app.component('v-chart', VueECharts)
 ```html
 <script src="https://cdn.jsdelivr.net/npm/vue@2.7.5"></script>
 <script src="https://cdn.jsdelivr.net/npm/echarts@5.3.3"></script>
-<script src="https://cdn.jsdelivr.net/npm/vue-echarts@6.3.2"></script>
+<script src="https://cdn.jsdelivr.net/npm/vue-echarts@6.5.0"></script>
 ```
 <!-- vue2Scripts:end -->
 
@@ -448,6 +365,7 @@ import { THEME_KEY } from 'vue-echarts'
 >   }
 > }
 > ```
+
 </details>
 
 ### Methods
@@ -479,7 +397,7 @@ You can bind events with Vue's `v-on` directive.
 
 ```vue
 <template>
-  <v-chart :option="option" @highlight="handleHighlight"/>
+  <v-chart :option="option" @highlight="handleHighlight" />
 </template>
 ```
 

README.zh-Hans.md

@@ -18,13 +18,13 @@
 $ npm install echarts vue-echarts
 ```
 
-要在 *Vue 2*（<2.7.0）下使用 `vue-echarts`，需要确保 `@vue/composition-api` 已经安装：
+要在 _Vue 2_（<2.7.0）下使用 `vue-echarts`，需要确保 `@vue/composition-api` 已经安装：
 
 ```sh
 npm i -D @vue/composition-api
 ```
 
-如果你在使用基于 *Vue 2*（<2.7.0）的 *NuxtJS*，那么还需要安装 `@nuxtjs/composition-api`：
+如果你在使用基于 _Vue 2_（<2.7.0）的 _NuxtJS_，那么还需要安装 `@nuxtjs/composition-api`：
 
 ```sh
 npm i -D @nuxtjs/composition-api
@@ -32,87 +32,7 @@ npm i -D @nuxtjs/composition-api
 
 然后在 `nuxt.config.js` 的 `buildModules` 选项中添加 `'@nuxtjs/composition-api/module'`。
 
-<details>
+#### 示例
-<summary>Vue 3</summary>
-
-```js
-import { createApp } from 'vue'
-import ECharts from 'vue-echarts'
-import { use } from "echarts/core";
-
-// 手动引入 ECharts 各模块来减小打包体积
-import {
-  CanvasRenderer
-} from 'echarts/renderers'
-import {
-  BarChart
-} from 'echarts/charts'
-import {
-  GridComponent,
-  TooltipComponent
-} from 'echarts/components'
-
-use([
-  CanvasRenderer,
-  BarChart,
-  GridComponent,
-  TooltipComponent
-]);
-
-const app = createApp(...)
-
-// 全局注册组件（也可以使用局部注册）
-app.component('v-chart', ECharts)
-
-app.mount(...)
-```
-
-</details>
-
-<details>
-<summary>Vue 2</summary>
-
-```js
-import Vue from 'vue'
-import ECharts from 'vue-echarts'
-import { use } from 'echarts/core'
-// 手动引入 ECharts 各模块来减小打包体积
-
-import {
-  CanvasRenderer
-} from 'echarts/renderers'
-import {
-  BarChart
-} from 'echarts/charts'
-import {
-  GridComponent,
-  TooltipComponent
-} from 'echarts/components'
-
-use([
-  CanvasRenderer,
-  BarChart,
-  GridComponent,
-  TooltipComponent
-]);
-
-// 全局注册组件（也可以使用局部注册）
-Vue.component('v-chart', ECharts)
-
-new Vue(...)
-```
-
-</details>
-
-为了更小的打包体积，我们建议手动从 ECharts 引入单个图表和组件。请参考所有支持的渲染器/图表/组件。[前往 →](https://github.com/apache/echarts/blob/master/src/echarts.all.ts)
-
-但如果你实在需要全量引入 ECharts 从而无需手动引入模块，只需要在代码中添加：
-
-```js
-import "echarts";
-```
-
-#### 单文件组件示例
 
 <details>
 <summary>Vue 3 <a href="https://stackblitz.com/edit/vue-echarts-vue-3?file=src%2FApp.vue">Demo →</a></summary>
@@ -122,7 +42,7 @@ import "echarts";
   <v-chart class="chart" :option="option" />
 </template>
 
-<script>
+<script setup>
 import { use } from "echarts/core";
 import { CanvasRenderer } from "echarts/renderers";
 import { PieChart } from "echarts/charts";
@@ -132,7 +52,7 @@ import {
   LegendComponent
 } from "echarts/components";
 import VChart, { THEME_KEY } from "vue-echarts";
-import { ref, defineComponent } from "vue";
+import { ref, provide } from "vue";
 
 use([
   CanvasRenderer,
@@ -142,16 +62,9 @@ use([
   LegendComponent
 ]);
 
-export default defineComponent({
+provide(THEME_KEY, "dark");
-  name: "HelloWorld",
+
-  components: {
+const option = ref({
-    VChart
-  },
-  provide: {
-    [THEME_KEY]: "dark"
-  },
-  setup: () => {
-    const option = ref({
   title: {
     text: "Traffic Sources",
     left: "center"
@@ -187,10 +100,6 @@ export default defineComponent({
       }
     }
   ]
-    });
-
-    return { option };
-  }
 });
 </script>
 
@@ -297,6 +206,14 @@ export default {
 
 </details>
 
+为了更小的打包体积，我们建议手动从 ECharts 引入单个图表和组件。请参考所有支持的渲染器/图表/组件。[前往 →](https://github.com/apache/echarts/blob/master/src/echarts.all.ts)
+
+但如果你实在需要全量引入 ECharts 从而无需手动引入模块，只需要在代码中添加：
+
+```js
+import "echarts";
+```
+
 ### CDN & 全局变量
 
 用如下方式在 HTML 中插入 `<script>` 标签，并且通过 `window.VueECharts` 来访问组件接口：
@@ -304,12 +221,11 @@ export default {
 <details>
 <summary>Vue 3 <a href="https://stackblitz.com/edit/vue-echarts-vue-3-global?file=index.html">Demo →</a></summary>
 
-
 <!-- vue3Scripts:start -->
 ```html
 <script src="https://cdn.jsdelivr.net/npm/vue@3.2.37"></script>
 <script src="https://cdn.jsdelivr.net/npm/echarts@5.3.3"></script>
-<script src="https://cdn.jsdelivr.net/npm/vue-echarts@6.3.2"></script>
+<script src="https://cdn.jsdelivr.net/npm/vue-echarts@6.5.0"></script>
 ```
 <!-- vue3Scripts:end -->
 
@@ -329,7 +245,7 @@ app.component('v-chart', VueECharts)
 ```html
 <script src="https://cdn.jsdelivr.net/npm/vue@2.7.5"></script>
 <script src="https://cdn.jsdelivr.net/npm/echarts@5.3.3"></script>
-<script src="https://cdn.jsdelivr.net/npm/vue-echarts@6.3.2"></script>
+<script src="https://cdn.jsdelivr.net/npm/vue-echarts@6.5.0"></script>
 ```
 <!-- vue2Scripts:end -->
 
@@ -396,7 +312,7 @@ Vue.component("v-chart", VueECharts);
 
 ```vue
 <template>
-  <v-chart :option="option" @highlight="handleHighlight"/>
+  <v-chart :option="option" @highlight="handleHighlight" />
 </template>
 ```
 
@@ -509,6 +425,7 @@ import { THEME_KEY } from 'vue-echarts'
 >   }
 > }
 > ```
+
 </details>
 
 ### 方法

package.json

@@ -1,6 +1,6 @@
 {
   "name": "vue-echarts",
-  "version": "6.3.2",
+  "version": "6.5.0",
   "description": "Vue.js component for Apache ECharts.",
   "author": "GU Yiling <justice360@gmail.com>",
   "scripts": {
@@ -40,7 +40,7 @@
     "@vue/eslint-config-typescript": "^10.0.0",
     "comment-mark": "^1.0.0",
     "core-js": "^3.23.0",
-    "echarts": "^5.3.2",
+    "echarts": "^5.4.1",
     "echarts-liquidfill": "^3.1.0",
     "eslint": "^7.20.0",
     "eslint-plugin-prettier": "^3.3.1",
@@ -67,7 +67,7 @@
   },
   "peerDependencies": {
     "@vue/composition-api": "^1.0.5",
-    "echarts": "^5.1.2",
+    "echarts": "^5.4.1",
     "vue": "^2.6.12 || ^3.1.1"
   },
   "jsdelivr": "dist/index.umd.min.js",

pnpm-lock.yaml

@@ -15,7 +15,7 @@ specifiers:
   '@vue/eslint-config-typescript': ^10.0.0
   comment-mark: ^1.0.0
   core-js: ^3.23.0
-  echarts: ^5.3.2
+  echarts: ^5.4.1
   echarts-liquidfill: ^3.1.0
   eslint: ^7.20.0
   eslint-plugin-prettier: ^3.3.1
@@ -60,8 +60,8 @@ devDependencies:
   '@vue/eslint-config-typescript': 10.0.0_yzev4ryi2uowr3tzgilgj3i2em
   comment-mark: 1.1.1
   core-js: 3.23.3
-  echarts: 5.3.3
+  echarts: 5.4.1
-  echarts-liquidfill: 3.1.0_echarts@5.3.3
+  echarts-liquidfill: 3.1.0_echarts@5.4.1
   eslint: 7.32.0
   eslint-plugin-prettier: 3.4.1_fqyzhpusvewbsl54pqqbxqaegm
   eslint-plugin-vue: 8.7.1_eslint@7.32.0
@@ -3925,19 +3925,19 @@ packages:
     engines: {node: '>=6.0.0'}
     dev: true
 
-  /echarts-liquidfill/3.1.0_echarts@5.3.3:
+  /echarts-liquidfill/3.1.0_echarts@5.4.1:
     resolution: {integrity: sha512-5Dlqs/jTsdTUAsd+K5LPLLTgrbbNORUSBQyk8PSy1Mg2zgHDWm83FmvA4s0ooNepCJojFYRITTQ4GU1UUSKYLw==}
     peerDependencies:
       echarts: ^5.0.1
     dependencies:
-      echarts: 5.3.3
+      echarts: 5.4.1
     dev: true
 
-  /echarts/5.3.3:
+  /echarts/5.4.1:
-    resolution: {integrity: sha512-BRw2serInRwO5SIwRviZ6Xgm5Lb7irgz+sLiFMmy/HOaf4SQ+7oYqxKzRHAKp4xHQ05AuHw1xvoQWJjDQq/FGw==}
+    resolution: {integrity: sha512-9ltS3M2JB0w2EhcYjCdmtrJ+6haZcW6acBolMGIuf01Hql1yrIV01L1aRj7jsaaIULJslEP9Z3vKlEmnJaWJVQ==}
     dependencies:
       tslib: 2.3.0
-      zrender: 5.3.2
+      zrender: 5.4.1
     dev: true
 
   /ee-first/1.1.1:
@@ -7831,8 +7831,8 @@ packages:
       strip-indent: 2.0.0
     dev: true
 
-  /zrender/5.3.2:
+  /zrender/5.4.1:
-    resolution: {integrity: sha512-8IiYdfwHj2rx0UeIGZGGU4WEVSDEdeVCaIg/fomejg1Xu6OifAL1GVzIPHg2D+MyUkbNgPWji90t0a8IDk+39w==}
+    resolution: {integrity: sha512-M4Z05BHWtajY2241EmMPHglDQAJ1UyHQcYsxDNzD9XLSkPDqMq4bB28v9Pb4mvHnVQ0GxyTklZ/69xCFP6RXBA==}
     dependencies:
       tslib: 2.3.0
     dev: true

src/ECharts.ts

@@ -8,7 +8,7 @@ import {
   computed,
   inject,
   onMounted,
-  onUnmounted,
+  onBeforeUnmount,
   h,
   nextTick,
   watchEffect,
@@ -38,9 +38,10 @@ import {
   loadingProps
 } from "./composables";
 import { omitOn, unwrapInjected } from "./utils";
+import { register, TAG_NAME, type EChartsElement } from "./wc";
 import "./style.css";
 
-const TAG_NAME = "x-vue-echarts";
+const wcRegistered = register();
 
 if (Vue2) {
   Vue2.config.ignoredElements.push(TAG_NAME);
@@ -70,7 +71,7 @@ export default defineComponent({
   emits: [] as unknown as Emits,
   inheritAttrs: false,
   setup(props, { attrs }) {
-    const root = shallowRef<HTMLElement>();
+    const root = shallowRef<EChartsElement>();
     const chart = shallowRef<EChartsType>();
     const manualOption = shallowRef<Option>();
     const defaultTheme = inject(THEME_KEY, null);
@@ -273,7 +274,17 @@ export default defineComponent({
       init();
     });
 
-    onUnmounted(cleanup);
+    onBeforeUnmount(() => {
+      if (wcRegistered && root.value) {
+        // For registered web component, we can leverage the
+        // `disconnectedCallback` to dispose the chart instance
+        // so that we can delay the cleanup after exsiting leaving
+        // transition.
+        root.value.__dispose = cleanup;
+      } else {
+        cleanup();
+      }
+    });
 
     return {
       chart,

src/style.css

@@ -1 +1 @@
-x-vue-echarts{display:block;width:100%;height:100%}
+x-vue-echarts{display:block;width:100%;height:100%;min-width:0}

src/types.ts

@@ -1,4 +1,9 @@
-import { init, type SetOptionOpts } from "echarts/core";
+import {
+  init,
+  type SetOptionOpts,
+  type ECElementEvent,
+  type ElementEvent
+} from "echarts/core";
 import type { Ref } from "vue";
 
 export type Injection<T> = T | null | Ref<T | null> | { value: T | null };
@@ -20,16 +25,28 @@ export type EventTarget = EChartsType | ZRenderType;
 type SetOptionType = EChartsType["setOption"];
 export type Option = Parameters<SetOptionType>[0];
 
-type EChartsEventName =
+type ElementEventName =
   | "click"
   | "dblclick"
+  | "mousewheel"
+  | "mouseout"
+  | "mouseover"
+  | "mouseup"
   | "mousedown"
   | "mousemove"
-  | "mouseup"
-  | "mouseover"
-  | "mouseout"
-  | "globalout"
   | "contextmenu"
+  | "drag"
+  | "dragstart"
+  | "dragend"
+  | "dragenter"
+  | "dragleave"
+  | "dragover"
+  | "drop"
+  | "globalout";
+
+type ZRenderEventName = `zr:${ElementEventName}`;
+
+type OtherEventName =
   | "highlight"
   | "downplay"
   | "selectchanged"
@@ -56,28 +73,22 @@ type EChartsEventName =
   | "brush"
   | "brushEnd"
   | "brushselected"
-  | "globalcursortaken"
+  | "globalcursortaken";
-  | "rendered"
+
-  | "finished";
+type ElementEmits = {
-type ZRenderEventName =
+  [key in ElementEventName]: (params: ECElementEvent) => boolean;
-  | "click"
-  | "dblclick"
-  | "mousewheel"
-  | "mouseout"
-  | "mouseover"
-  | "mouseup"
-  | "mousedown"
-  | "mousemove"
-  | "contextmenu"
-  | "drag"
-  | "dragstart"
-  | "dragend"
-  | "dragenter"
-  | "dragleave"
-  | "dragover"
-  | "drop"
-  | "globalout";
-type EventName = EChartsEventName | `zr:${ZRenderEventName}`;
-export type Emits = {
-  [key in EventName]: null;
 };
+
+type ZRenderEmits = {
+  [key in ZRenderEventName]: (params: ElementEvent) => boolean;
+};
+
+type OtherEmits = {
+  [key in OtherEventName]: null;
+};
+
+export type Emits = ElementEmits &
+  OtherEmits & {
+    rendered: (params: { elapsedTime: number }) => boolean;
+    finished: () => boolean;
+  } & ZRenderEmits;

src/wc.ts

@@ -0,0 +1,51 @@
+let registered: boolean | null = null;
+
+export const TAG_NAME = "x-vue-echarts";
+
+export interface EChartsElement extends HTMLElement {
+  __dispose: (() => void) | null;
+}
+
+export function register(): boolean {
+  if (registered != null) {
+    return registered;
+  }
+
+  if (
+    typeof HTMLElement === "undefined" ||
+    typeof customElements === "undefined"
+  ) {
+    return (registered = false);
+  }
+
+  try {
+    // Class definitions cannot be transpiled to ES5
+    // so we are doing a little trick here to ensure
+    // we are using native classes. As we use this as
+    // a progressive enhancement, it will be fine even
+    // if the browser doesn't support native classes.
+    const reg = new Function(
+      "tag",
+      `class EChartsElement extends HTMLElement {
+  __dispose = null;
+
+  disconnectedCallback() {
+    if (this.__dispose) {
+      this.__dispose();
+      this.__dispose = null;
+    }
+  }
+}
+
+if (customElements.get(tag) == null) {
+  customElements.define(tag, EChartsElement);
+}
+`
+    );
+    reg(TAG_NAME);
+  } catch (e) {
+    return (registered = false);
+  }
+
+  return (registered = true);
+}