From: Jacco van den Berg <jaccoberg2281@gmail.com>
Date: Mon, 22 Aug 2022 18:20:35 +0000 (+0200)
Subject: Documentation: how to add static typing to plugins (#10607)
X-Git-Tag: v4.0.0~46
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=96633cc0f62f2bb3a48d0dfcd728603cb23a434e;p=thirdparty%2FChart.js.git

Documentation: how to add static typing to plugins (#10607)

* Add documentation on how to add static typing to plugins

* make the options optional

* Fix syntax
---

diff --git a/docs/configuration/canvas-background.md b/docs/configuration/canvas-background.md
index f4fa7563b..da937ded1 100644
--- a/docs/configuration/canvas-background.md
+++ b/docs/configuration/canvas-background.md
@@ -34,11 +34,11 @@ const data = {
 // Note: changes to the plugin code is not reflected to the chart, because the plugin is loaded at chart construction time and editor changes only trigger an chart.update().
 const plugin = {
   id: 'custom_canvas_background_color',
-  beforeDraw: (chart) => {
+  beforeDraw: (chart, args, options) => {
     const {ctx} = chart;
     ctx.save();
     ctx.globalCompositeOperation = 'destination-over';
-    ctx.fillStyle = 'lightGreen';
+    ctx.fillStyle = options.color || '#99ffff';
     ctx.fillRect(0, 0, chart.width, chart.height);
     ctx.restore();
   }
@@ -49,6 +49,11 @@ const plugin = {
 const config = {
   type: 'doughnut',
   data: data,
+  options: {
+    plugins: {
+      color: 'lightGreen',
+    }
+  },
   plugins: [plugin],
 };
 // </block:config>
diff --git a/docs/developers/charts.md b/docs/developers/charts.md
index feb63fc41..1b41b4e13 100644
--- a/docs/developers/charts.md
+++ b/docs/developers/charts.md
@@ -126,7 +126,7 @@ new Chart(ctx, {
 
 If you want your new chart type to be statically typed, you must provide a `.d.ts` TypeScript declaration file. Chart.js provides a way to augment built-in types with user-defined ones, by using the concept of "declaration merging".
 
-When adding a new chart type, `ChartTypeRegistry` must contains the declarations for the new type, either by extending an existing entry in `ChartTypeRegistry` or by creating a new one.
+When adding a new chart type, `ChartTypeRegistry` must contain the declarations for the new type, either by extending an existing entry in `ChartTypeRegistry` or by creating a new one.
 
 For example, to provide typings for a new chart type that extends from a bubble chart, you would add a `.d.ts` containing:
 
diff --git a/docs/developers/plugins.md b/docs/developers/plugins.md
index 3b2296a6e..2f7c88b66 100644
--- a/docs/developers/plugins.md
+++ b/docs/developers/plugins.md
@@ -181,3 +181,23 @@ Plugins are notified during the destroy process. These hooks can be used to dest
 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)
+
+## TypeScript Typings
+
+If you want your plugin to be statically typed, you must provide a `.d.ts` TypeScript declaration file. Chart.js provides a way to augment built-in types with user-defined ones, by using the concept of "declaration merging".
+
+When adding a plugin, `PluginOptionsByType` must contain the declarations for the plugin.
+
+For example, to provide typings for the [`canvas backgroundColor plugin`](../configuration/canvas-background.md), you would add a `.d.ts` containing:
+
+```ts
+import { ChartType, Plugin } from 'chart.js'
+
+declare module 'chart.js' {
+    interface PluginOptionsByType<TType extends ChartType> {
+        custom_canvas_background_color?: {
+            color?: string
+        }
+    }
+}
+```