Do not rely on any to extend the option context

This is a breaking change for TypeScript projects since now, in order
to extend the option context, it's required to declare a custom type
or to use module augmentation. Add TypeScript documentation but also
a migration guide for the upcoming versions 1.x & 2.x.

README.md

@@ -24,6 +24,8 @@ Requires [Chart.js](https://github.com/chartjs/Chart.js/releases) **2.7.0** or l
 - [Positioning](https://chartjs-plugin-datalabels.netlify.app/guide/positioning.html)
 - [Formatting](https://chartjs-plugin-datalabels.netlify.app/guide/formatting.html)
 - [Events](https://chartjs-plugin-datalabels.netlify.app/guide/events.html)
+- [TypeScript](https://chartjs-plugin-datalabels.netlify.app/guide/typescript.html)
+- [Migration](https://chartjs-plugin-datalabels.netlify.app/guide/migration.html)
 - [Samples](https://chartjs-plugin-datalabels.netlify.app/samples/)
 
 ## Development

docs/.vuepress/config.js

@@ -54,6 +54,8 @@ module.exports = {
                 'positioning',
                 'formatting',
                 'events',
+                'typescript',
+                'migration',
             ],
             '/samples/': [
                 {

docs/guide/README.md

@@ -16,8 +16,10 @@ This plugin doesn't provide any public API (except the plugin options), thus you
 * [Options](options.md)
 * [Labels](labels.md)
 * [Positioning](positioning.md)
-* [Formating](formatting.md)
+* [Formatting](formatting.md)
 * [Events](events.md)
+* [TypeScript](typescript)
+* [Migration](migration)
 * [Samples](../samples)
 
 ## License

docs/guide/migration.md

@@ -0,0 +1,20 @@
+# Migration
+
+## Migrating to v1.0.0
+
+### Breaking Changes
+
+#### Extending the Option Context <Badge text="TS only"/>
+
+In order to extend the [option context](options.md#option-context), you now need to use one of the methods described [in this section](typescript.md#option-context). Peviously, this feature relied on the use of `any`. If for whatever reasons you need that flexibility, the old behavior can be achieved using:
+
+```ts
+import {Context} from 'chartjs-plugin-datalabels';
+
+// OLD BEHAVIOR: NOT RECOMMENDED!
+declare module 'chartjs-plugin-datalabels' {
+  interface Context {
+    [key: string]: any;
+  }
+}
+```

docs/guide/options.md

@@ -71,6 +71,10 @@ The context object contains the following properties:
 | `dataset` | `object` | The dataset at index `datasetIndex`.
 | `datasetIndex` | `number` | The index of the associated dataset.
 
+::: tip
+The option context can be extended dynamically with user custom properties, for example to implement [event based label customizations & interactions](events.md#listeners).
+:::
+
 ## Indexable Options
 
 Indexable options also accept an array in which each item corresponds to the element at the same index. Note that this method requires to provide as many items as data, so, in most cases, using a [function](#scriptable-options) is more appropriate.

docs/guide/typescript.md

@@ -0,0 +1,94 @@
+# TypeScript
+
+This plugin provides TypeScript type declaration files bundled in the npm package so that types of this plugin options are checked when building your TypeScript project. Note that you also need the `@types/chart.js` package, if not already installed:
+
+```sh
+npm install --save-dev @types/chart.js
+```
+
+## Option Context
+
+The declaration of the [option context](options.md#option-context) is exported as `Context`:
+
+```ts
+import {Context} from 'chartjs-plugin-datalabels';
+
+const chart = new Chart('foo', {
+  options: {
+    plugins: {
+      datalabels: {
+        rotation: (ctx: Context) => {
+          return ctx.dataIndex % 2 ? 180 : 0;
+        },
+      }
+    }
+  }
+});
+```
+
+Extending this context can be done using one of the following methods:
+
+### Custom Interface
+
+```ts
+import {Context} from 'chartjs-plugin-datalabels';
+
+interface FooContext extends Context {
+  foo?: number;
+}
+
+const chart = new Chart('foo', {
+  options: {
+    plugins: {
+      datalabels: {
+        rotation: (ctx: FooContext) => ctx.foo || 0,
+        listeners: {
+          click: (ctx: FooContext) => {
+            ctx.foo += (ctx.foo || 0) + 10;
+            return true;
+          }
+        }
+      }
+    }
+  }
+});
+```
+
+::: tip
+This method allows to declare different context interfaces to use in different charts.
+:::
+
+### Module Augmentation
+
+```ts
+// shims-chartjs-plugin-datalabels.d.ts
+import {Context} from 'chartjs-plugin-datalabels';
+
+declare module 'chartjs-plugin-datalabels' {
+  interface Context {
+    foo?: number;
+  }
+}
+```
+
+```ts
+// index.ts
+const chart = new Chart('foo', {
+  options: {
+    plugins: {
+      datalabels: {
+        rotation: (ctx: Context) => ctx.foo || 0,
+        listeners: {
+          click: (ctx: Context) => {
+            ctx.foo += (ctx.foo || 0) + 10;
+            return true;
+          }
+        }
+      }
+    }
+  }
+});
+```
+::: warning
+The augmented `Context` declaration will be the same for all charts. This method should be considered only if all charts should share the same context declaration. Read more about [module augmentation](https://www.typescriptlang.org/docs/handbook/declaration-merging.html#module-augmentation).
+:::

types/context.d.ts

@@ -35,10 +35,4 @@ export interface Context {
 	 * @since 0.1.0
 	 */
 	datasetIndex: number;
-
-	// NOTE(SB) context can be extended dynamically with user properties, for
-	// example to implement event based label customizations / interactions.
-	// https://chartjs-plugin-datalabels.netlify.app/guide/events.html#example
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
-	[key: string]: any;
 }

types/test/options.basic.ts

@@ -48,7 +48,7 @@ const options: Options = {
 				click: (ctx: Context) => true,
 				enter: (ctx: Context) => false,
 				leave: (ctx: Context) => {
-					ctx.foo = 42;
+					// return void
 				}
 			},
 			padding: {
@@ -69,7 +69,7 @@ const options: Options = {
 		click: (ctx: Context) => true,
 		enter: (ctx: Context) => false,
 		leave: (ctx: Context) => {
-			ctx.foo = 42;
+			// return void
 		}
 	},
 	offset: 42,

types/test/options.context.ts

@@ -0,0 +1,31 @@
+import {Chart} from 'chart.js';
+import {Context} from '../context';
+import {Options} from '../options';
+
+interface CustomContext extends Context {
+	foo?: number;
+}
+
+const options: Options = {
+	rotation: (ctx: CustomContext) => ctx.foo || 0,
+	listeners: {
+		click: (ctx: CustomContext) => {
+			ctx.foo = 42;
+		}
+	},
+};
+
+const chart = new Chart('id', {
+	data: {
+		datasets: [
+			{
+				datalabels: options
+			}
+		]
+	},
+	options: {
+		plugins: {
+			datalabels: options
+		}
+	}
+});