add beforeDestroy hook (#9933)

* add `beforeDestroy` hook
* add documentation of destroy lifecycle, add `afterDestroy` hook and deprecate destroy

diff --git a/docs/developers/destroy_flowchart.png b/docs/developers/destroy_flowchart.png
new file mode 100644 (file)
index 0000000..c8d5cba
Binary files /dev/null and b/docs/developers/destroy_flowchart.png differ

diff --git a/docs/developers/plugins.md b/docs/developers/plugins.md
index 64efe2096bad98ac27b8474de9dc878e1f754905..e24cc9d82d21139aa632f19465c341c9ef45ecdb 100644 (file)
--- a/docs/developers/plugins.md
+++ b/docs/developers/plugins.md
@@ -147,3 +147,10 @@ Plugins can interact with the chart throughout the render process. The rendering
 Plugins can interact with the chart during the event handling process. The event handling flow is documented in the flowchart below. Each of the green processes is a plugin notification. If a plugin makes changes that require a re-render, the plugin can set `args.changed` to `true` to indicate that a render is needed. The built-in tooltip plugin uses this method to indicate when the tooltip has changed.
 
 ![Chart.js event handling flowchart](./event_flowchart.png)
+
+### Chart destroy
+
+Plugins are notified during the destroy process. These hooks can be used to destroy things that the plugin made and used during its life.
+The `destroy` hook has been deprecated since Chart.js version 3.7.0, use the `afterDestroy` hook instead.
+
+![Chart.js destroy flowchart](./destroy_flowchart.png)

diff --git a/src/core/core.controller.js b/src/core/core.controller.js
index e7621f8c91573c0a74acc90c9241e70c1c0e5e9e..01fcd0975caf1e676a6206780f7ba6e91e8d6546 100644 (file)
--- a/src/core/core.controller.js
+++ b/src/core/core.controller.js
@@ -891,6 +891,7 @@ class Chart {
   }
 
   destroy() {
+    this.notifyPlugins('beforeDestroy');
     const {canvas, ctx} = this;
 
     this._stop();
@@ -904,9 +905,12 @@ class Chart {
       this.ctx = null;
     }
 
+    // TODO V4: delete destroy hook and reference to it in plugin flowchart
     this.notifyPlugins('destroy');
 
     delete instances[this.id];
+
+    this.notifyPlugins('afterDestroy');
   }
 
   toBase64Image(...args) {

diff --git a/src/core/core.plugins.js b/src/core/core.plugins.js
index 480f42391331fda2aacbf56dbfc47036aabed524..27a07bb0c91403484e8d1914d6dc14bae09d51b6 100644 (file)
--- a/src/core/core.plugins.js
+++ b/src/core/core.plugins.js
@@ -41,7 +41,7 @@ export default class PluginService {
     const descriptors = filter ? this._descriptors(chart).filter(filter) : this._descriptors(chart);
     const result = this._notify(descriptors, chart, hook, args);
 
-    if (hook === 'destroy') {
+    if (hook === 'afterDestroy') {
       this._notify(descriptors, chart, 'stop');
       this._notify(this._init, chart, 'uninstall');
     }

diff --git a/types/index.esm.d.ts b/types/index.esm.d.ts
index cb02b1c91aab197dd1ec853c056bc9aeef466f7e..d848b54d17bc1f6c07dbac404ed706e8b6597196 100644 (file)
--- a/types/index.esm.d.ts
+++ b/types/index.esm.d.ts
@@ -1053,13 +1053,28 @@ export interface Plugin<TType extends ChartType = ChartType, O = AnyObject> exte
    * @param {object} options - The plugin options.
    */
   resize?(chart: Chart, args: { size: { width: number, height: number } }, options: O): void;
+  /**
+   * Called before the chart is being destroyed.
+   * @param {Chart} chart - The chart instance.
+   * @param {object} args - The call arguments.
+   * @param {object} options - The plugin options.
+   */
+  beforeDestroy?(chart: Chart, args: EmptyObject, options: O): void;
   /**
    * Called after the chart has been destroyed.
    * @param {Chart} chart - The chart instance.
    * @param {object} args - The call arguments.
    * @param {object} options - The plugin options.
+   * @deprecated since version 3.7.0 in favour of afterDestroy
    */
   destroy?(chart: Chart, args: EmptyObject, options: O): void;
+  /**
+   * Called after the chart has been destroyed.
+   * @param {Chart} chart - The chart instance.
+   * @param {object} args - The call arguments.
+   * @param {object} options - The plugin options.
+   */
+  afterDestroy?(chart: Chart, args: EmptyObject, options: O): void;
   /**
    * Called after chart is destroyed on all plugins that were installed for that chart. This hook is also invoked for disabled plugins (options === false).
    * @param {Chart} chart - The chart instance.