From 7695b429216050e5dae822b8bc8dd6759a42d0a9 Mon Sep 17 00:00:00 2001 From: stockiNail Date: Mon, 16 May 2022 11:55:12 +0200 Subject: [PATCH 1/2] Add documentation and type for 'common' plugin option --- docs/guide/configuration.md | 14 +++++++++++--- docs/guide/migrationV2.md | 16 +++++++++++++++- docs/samples/box/quarters.md | 4 +++- docs/samples/line/labelVisibility.md | 4 +++- docs/samples/line/limited.md | 4 +++- docs/samples/point/combined.md | 4 +++- docs/samples/point/outsideChartArea.md | 4 +++- docs/samples/polygon/outsideChartArea.md | 4 +++- types/options.d.ts | 8 ++++++-- types/tests/exports.ts | 10 ++++++---- 10 files changed, 56 insertions(+), 16 deletions(-) diff --git a/docs/guide/configuration.md b/docs/guide/configuration.md index 309ed1d73..f92047a2a 100644 --- a/docs/guide/configuration.md +++ b/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. diff --git a/docs/guide/migrationV2.md b/docs/guide/migrationV2.md index 7ebdc5b5f..22c803695 100644 --- a/docs/guide/migrationV2.md +++ b/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` option in the plugin annotation, which contains options to apply to all annotations: + +```javascript +plugins: { + annotation: { + common: { + drawTime: 'afterDraw' + }, + annotations: [ + ... + ] + } +} +``` ## Elements diff --git a/docs/samples/box/quarters.md b/docs/samples/box/quarters.md index 563f82121..c04f6b003 100644 --- a/docs/samples/box/quarters.md +++ b/docs/samples/box/quarters.md @@ -105,7 +105,9 @@ const config = { }, plugins: { annotation: { - drawTime: 'beforeDraw', + common: { + drawTime: 'beforeDraw' + }, annotations: { annotation1, annotation2, diff --git a/docs/samples/line/labelVisibility.md b/docs/samples/line/labelVisibility.md index fcd43e654..48b78f990 100644 --- a/docs/samples/line/labelVisibility.md +++ b/docs/samples/line/labelVisibility.md @@ -88,7 +88,9 @@ const config = { display: false, }, annotation: { - drawTime: 'beforeDatasetsDraw', + common: { + drawTime: 'beforeDatasetsDraw' + }, annotations: { annotation1, annotation2 diff --git a/docs/samples/line/limited.md b/docs/samples/line/limited.md index cad8c0df9..2024e2c15 100644 --- a/docs/samples/line/limited.md +++ b/docs/samples/line/limited.md @@ -95,7 +95,9 @@ const config = { }, plugins: { annotation: { - drawTime: 'beforeDraw', + common: { + drawTime: 'beforeDraw' + }, annotations: { annotation1, annotation2, diff --git a/docs/samples/point/combined.md b/docs/samples/point/combined.md index 5d7b37fd8..208539e91 100644 --- a/docs/samples/point/combined.md +++ b/docs/samples/point/combined.md @@ -106,7 +106,9 @@ const config = { }, plugins: { annotation: { - drawTime: 'beforeDraw', + common: { + drawTime: 'beforeDraw' + }, annotations: { annotation1, annotation2, diff --git a/docs/samples/point/outsideChartArea.md b/docs/samples/point/outsideChartArea.md index 916e41803..5ce2f1c78 100644 --- a/docs/samples/point/outsideChartArea.md +++ b/docs/samples/point/outsideChartArea.md @@ -73,7 +73,9 @@ const config = { plugins: { annotation: { clip: false, - drawTime: 'afterDraw', + common: { + drawTime: 'afterDraw' + }, annotations: { annotation1, annotation2 diff --git a/docs/samples/polygon/outsideChartArea.md b/docs/samples/polygon/outsideChartArea.md index 141316dda..3229c371d 100644 --- a/docs/samples/polygon/outsideChartArea.md +++ b/docs/samples/polygon/outsideChartArea.md @@ -84,7 +84,9 @@ const config = { plugins: { annotation: { clip: false, - drawTime: 'afterDraw', + common: { + drawTime: 'afterDraw' + }, annotations: { annotation1, annotation2, diff --git a/types/options.d.ts b/types/options.d.ts index 5d7af8f41..fe0b7b4a9 100644 --- a/types/options.d.ts +++ b/types/options.d.ts @@ -151,10 +151,14 @@ interface PolygonAnnotationOptions extends CoreAnnotationOptions, AnnotationPoin yAdjust?: Scriptable, } +export interface AnnotationPluginCommonOptions { + drawTime?: Scriptable, + interaction?: CoreInteractionOptions +} + export interface AnnotationPluginOptions extends AnnotationEvents { animations?: Record, annotations: AnnotationOptions[] | Record, clip?: boolean, - drawTime?: Scriptable, - interaction?: CoreInteractionOptions + common?: AnnotationPluginCommonOptions } diff --git a/types/tests/exports.ts b/types/tests/exports.ts index 324117691..373e975dc 100644 --- a/types/tests/exports.ts +++ b/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', From 1342e10b5c7fa275625b0963c109e70c7b671642 Mon Sep 17 00:00:00 2001 From: stockiNail Date: Mon, 16 May 2022 12:01:45 +0200 Subject: [PATCH 2/2] rephrases sentence about common in migration guide --- docs/guide/migrationV2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guide/migrationV2.md b/docs/guide/migrationV2.md index 22c803695..9a935c8d8 100644 --- a/docs/guide/migrationV2.md +++ b/docs/guide/migrationV2.md @@ -17,7 +17,7 @@ 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` option in the plugin annotation, which contains options to apply to all annotations: + * `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: {