Add documentation and type for 'common' plugin option (#733)

* Add documentation and type for 'common' plugin option

* rephrases sentence about common in migration guide

Author: stockiNail

docs/guide/configuration.md

@@ -10,14 +10,13 @@ The following options are available at the top level. They apply to all annotati
 | ---- | ---- | :----: | ---- | ----
 | [`animations`](#animations) | `object` | No | [see here](#default-animations) | To configure which element properties are animated and how.
 | `clip` | `boolean` | No | `true` | Are the annotations clipped to the chartArea.
-| `drawTime` | `string` | Yes | `'afterDatasetsDraw'` | See [drawTime](options#draw-time).
-| [`interaction`](options#interaction) | `Object` | No | `options.interaction` | To configure which events trigger plugin interactions
+| [`common`](#common) | `Object` | No | | To configure common options apply to all annotations
 
 :::warning
 
 Setting `clip` to `false`, you can enable the possibility to draw part of the annotation outside of the chart area.
 
-Nevertheless events are only catched over the chartArea.
+Nevertheless events are only caught over the chartArea.
 
 :::
 
@@ -57,6 +56,15 @@ const options = {
 | `numbers` | `properties` | `['x', 'y', 'x2', 'y2', 'width', 'height', 'centerX', 'centerY', 'pointX', 'pointY', 'labelX', 'labelY', 'labelWidth', 'labelHeight', 'radius']`
 | `numbers` | `type` | `number`
 
+## Common
+
+The following options apply to all annotations unless they are overwritten on a per-annotation basis.
+
+| Name | Type | [Scriptable](options#scriptable-options) | Default | Notes
+| ---- | ---- | :----: | ---- | ----
+| `drawTime` | `string` | Yes | `'afterDatasetsDraw'` | See [drawTime](options#draw-time).
+| [`interaction`](options#interaction) | `Object` | No | `options.interaction` | To configure which events trigger plugin interactions
+
 ## Events
 
 The following options are available for all annotation types. These options can be specified per annotation, or at the top level which apply to all annotations.

docs/guide/migrationV2.md

@@ -4,7 +4,7 @@
 
 ## Chart.js version
 
-The annotation plugin requires at least version 3.7.0 to work because of some bug fixes that happend within chart.js itself.
+The annotation plugin requires at least version 3.7.0 to work because of some bug fixes that happened within chart.js itself.
 
 ## Options
 
@@ -17,6 +17,20 @@ A number of changes were made to the configuration options passed to the plugin
  * `xPadding` and `yPadding` options were merged into a single `padding` object in the label configuration of line annotation to align with Chart.js options.
  * `enabled` option was replaced by `display` in the callout configuration of label annotation, in the label configuration of line and box annotations and in the arrow heads configuration of line annotation to have the same option on all elements.
  * `dblClickSpeed` option was removed from the plugin options because `dblclick` event hook is not available anymore.
+ * `drawTime` option at top level plugin configuration is moved to new `common` object in the plugin annotation options, which contains options to apply to all annotations: 
+
+```javascript
+plugins: {
+  annotation: {
+    common: {
+      drawTime: 'afterDraw'
+    },
+    annotations: [
+      ...
+    ]
+  }
+}
+```
 
 ## Elements
 

docs/samples/box/quarters.md

@@ -105,7 +105,9 @@ const config = {
     },
     plugins: {
       annotation: {
-        drawTime: 'beforeDraw',
+        common: {
+          drawTime: 'beforeDraw'
+        },
         annotations: {
           annotation1,
           annotation2,

docs/samples/line/labelVisibility.md

@@ -88,7 +88,9 @@ const config = {
         display: false,
       },
       annotation: {
-        drawTime: 'beforeDatasetsDraw',
+        common: {
+          drawTime: 'beforeDatasetsDraw'
+        },
         annotations: {
           annotation1,
           annotation2

docs/samples/line/limited.md

@@ -95,7 +95,9 @@ const config = {
     },
     plugins: {
       annotation: {
-        drawTime: 'beforeDraw',
+        common: {
+          drawTime: 'beforeDraw'
+        },
         annotations: {
           annotation1,
           annotation2,

docs/samples/point/combined.md

@@ -106,7 +106,9 @@ const config = {
     },
     plugins: {
       annotation: {
-        drawTime: 'beforeDraw',
+        common: {
+          drawTime: 'beforeDraw'
+        },
         annotations: {
           annotation1,
           annotation2,

docs/samples/point/outsideChartArea.md

@@ -73,7 +73,9 @@ const config = {
     plugins: {
       annotation: {
         clip: false,
-        drawTime: 'afterDraw',
+        common: {
+          drawTime: 'afterDraw'
+        },
         annotations: {
           annotation1,
           annotation2

docs/samples/polygon/outsideChartArea.md

@@ -84,7 +84,9 @@ const config = {
     plugins: {
       annotation: {
         clip: false,
-        drawTime: 'afterDraw',
+        common: {
+          drawTime: 'afterDraw'
+        },
         annotations: {
           annotation1,
           annotation2,

types/options.d.ts

@@ -151,10 +151,14 @@ interface PolygonAnnotationOptions extends CoreAnnotationOptions, AnnotationPoin
   yAdjust?: Scriptable<number, PartialEventContext>,
 }
 
+export interface AnnotationPluginCommonOptions {
+  drawTime?: Scriptable<DrawTime, PartialEventContext>,
+  interaction?: CoreInteractionOptions
+}
+
 export interface AnnotationPluginOptions extends AnnotationEvents {
   animations?: Record<string, unknown>,
   annotations: AnnotationOptions[] | Record<string, AnnotationOptions>,
   clip?: boolean,
-  drawTime?: Scriptable<DrawTime, PartialEventContext>,
-  interaction?: CoreInteractionOptions
+  common?: AnnotationPluginCommonOptions
 }

types/tests/exports.ts

@@ -16,10 +16,12 @@ const chart = new Chart('id', {
     plugins: {
       annotation: {
         clip: false,
-        interaction: {
-          mode: 'nearest',
-          axis: 'xy',
-          intersect: true
+        common: {
+          interaction: {
+            mode: 'nearest',
+            axis: 'xy',
+            intersect: true
+          }
         },
         annotations: [{
           type: 'line',