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 f4fa7563b9b78e9359255d5c1ca52055f5131538..da937ded13ce6c8480f0e8ffbed7c9a6370edda9 100644 (file)
--- 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 feb63fc413a738aa8d481aaaf1306d5c9f9611aa..1b41b4e13c822527d78e8570fa6b1324d9d267ec 100644 (file)
--- 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 3b2296a6ec8d0c2eda09691edfc8d11437c92b27..2f7c88b6664bf6da742149431d5274237546b757 100644 (file)
--- 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
+        }
+    }
+}
+```