Merge branch 'master' into innerLabelProto

Author: stockiNail

docs/.vuepress/config.ts

@@ -135,6 +135,7 @@ export default defineConfig({
             'types/doughnutLabel'
           ]
         },
+        'developers',
         {
           title: 'Migration',
           collapsable: true,

docs/guide/configuration.md

@@ -9,6 +9,7 @@ The following options are available at the top level. They apply to all annotati
 | Name | Type | [Scriptable](options.md#scriptable-options) | Default | Notes
 | ---- | ---- | :----: | ---- | ----
 | [`animations`](#animations) | `object` | No | [see here](#default-animations) | To configure which element properties are animated and how.
+| `annnotations` | `object`\|`array` | Yes | `undefined` | To configure all annotations to draw.
 | `clip` | `boolean` | No | `true` | Are the annotations clipped to the chartArea.
 | [`common`](#common) | `Object` | No | | To configure common options apply to all annotations
 | [`interaction`](options.md#interaction) | `Object` | No | `options.interaction` | To configure which events trigger plugin interactions
@@ -65,7 +66,7 @@ The following options apply to all annotations unless they are overwritten on a
 
 | Name | Type | [Scriptable](options.md#scriptable-options) | Default | Notes
 | ---- | ---- | :----: | ---- | ----
-| `drawTime` | `string` | Yes | `'afterDatasetsDraw'` | See [drawTime](options#draw-time).
+| `drawTime` | `string`\|`number` | Yes | `'afterDatasetsDraw'` | See [drawTime](options#draw-time).
 | `init` | `boolean`  | [See initial animation](#initial-animation) | `false` | Enable the animation to the annotations when they are drawing at chart initialization
 
 ### Initial animation

docs/guide/developers.md

@@ -0,0 +1,33 @@
+# Developers
+
+## Access to the annotation elements
+
+The annotation plugin uses Chart.js elements to draw the annotation requested by the user. The following APIs allows the user to get the created annotation elements to use in callbacks or for other purposes.
+The APIs are available in the annotation plugin instance.
+
+#### Script Tag
+
+```html
+<script>
+  // get annotation plugin instance
+  const annotationPlugin = window['chartjs-plugin-annotation'];
+</script>
+```
+
+#### Bundlers (Webpack, Rollup, etc.)
+
+```javascript
+// get annotation plugin instance
+import annotationPlugin from 'chartjs-plugin-annotation';
+```
+
+### `.getAnnotations(chart: Chart): AnnotationElement[]`
+
+It provides all annotation elements configured by the plugin options, even if the annotations are not visible.
+
+```javascript
+const myLineChart = new Chart(ctx, config);
+// get all annotation elements
+const elements = annotationPlugin.getAnnotations(myLineChart);
+```
+ 

docs/guide/integration.md

@@ -7,10 +7,10 @@ title: Integration
 ## Script Tag
 
 ```html
-<script src="path/to/chartjs/dist/chart.min.js"></script>
+<script src="path/to/chartjs/dist/chart.umd.js"></script>
 <script src="path/to/chartjs-plugin-annotation/dist/chartjs-plugin-annotation.min.js"></script>
 <script>
-    var myChart = new Chart(ctx, {...});
+    const myChart = new Chart(ctx, {...});
 </script>
 ```
 

docs/guide/options.md

@@ -83,7 +83,7 @@ module.exports = {
 
 ## Draw Time
 
-The `drawTime` option for an annotation determines where in the chart lifecycle the drawing occurs. Four potential options are available:
+The `drawTime` option for an annotation determines where in the chart lifecycle the drawing occurs. Four potential predefined options are available:
 
 | Option | Notes
 | ---- | ----
@@ -92,6 +92,8 @@ The `drawTime` option for an annotation determines where in the chart lifecycle
 | `'afterDatasetsDraw'` | Occurs after drawing of datasets but before items such as the tooltip
 | `'afterDraw'` | After other drawing is completed.
 
+Furthermore, the `drawTime` option can be set as number which represents the dataset index used to draw the annotation, before that dataset will be.
+
 ## Option Context
 
 The option context is used to give contextual information when resolving options and only applies to scriptable options. The object is preserved, so it can be used to store and pass information between calls / options.
@@ -116,6 +118,7 @@ In addition to [chart](#chart)
 
 * `id`: the annotation id
 * `element`: the annotation element
+* `elements`: the array which contains the already created annotation elements.
 * `type`: `'annotation'`
 
 The [annotation](#annotation) option context is passed to scriptable options in all other cases, except when resolving `id`, `type` or adjusting scale ranges. The same values resolved in `afterDataLimits` with [chart](#chart) context are again evaluated in `afterUpdate` with [annotation](#annotation) context.

docs/guide/types/_commonInnerLabel.md

@@ -9,9 +9,10 @@ All of these options can be [Scriptable](../options.md#scriptable-options)
 | [`color`](#fonts-and-colors) | [`Color`\|`Color[]`](../options#color) | `'black'` | Text color.
 | `content` | `string`\|`string[]`\|[`Image`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/Image)\|[`HTMLCanvasElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement) | `null` | The content to show in the label.
 | `display` | `boolean` | `false` | Whether or not the label is shown.
-| `drawTime` | `string` | `options.drawTime` | See [drawTime](../options#draw-time). Defaults to the annotation draw time if unset
+| `drawTime` | `string`\|`number` | `options.drawTime` | See [drawTime](../options#draw-time). Defaults to the annotation draw time if unset
 | [`font`](#fonts-and-colors) | [`Font`\|`Font[]`](../options#font) | `{ weight: 'bold' }` | Label font
 | `height` | `number`\|`string` | `undefined` | Overrides the height of the image or canvas element. Could be set in pixel by a number, or in percentage of current height of image or canvas element by a string. If undefined, uses the height of the image or canvas element. It is used only when the content is an image or canvas element.
+| `hitTolerance` | `number` | `undefined` | Amount of pixels to interact with annotations within some distance of the mouse point.
 | `opacity` | `number` | `undefined` | Overrides the opacity of the image or canvas element. Could be set a number in the range 0.0 to 1.0, inclusive. If undefined, uses the opacity of the image or canvas element. It is used only when the content is an image or canvas element.
 | `padding` | [`Padding`](../options.md#padding) | `6` | The padding to add around the text label.
 | [`position`](#position) | `string`\|`{x: string, y: string}` | `'center'` | Anchor position of label in the annotation.

docs/guide/types/_commonOptions.md

@@ -11,7 +11,8 @@ The following options are available for all annotations.
 | [`borderDashOffset`](#styling) | `number` | Yes | `0`
 | [`borderShadowColor`](#styling) | [`Color`](../options.md#color) | Yes | `'transparent'`
 | [`display`](#general) | `boolean` | Yes | `true`
-| [`drawTime`](#general) | `string` | Yes | `'afterDatasetsDraw'`
+| [`drawTime`](#general) | `string`\|`number` | Yes | `'afterDatasetsDraw'`
+| [`hitTolerance`](#general) | `number` | Yes | `0` 
 | [`init`](../configuration.html#common) | `boolean`  | [See initial animation](../configuration.html#initial-animation) | `undefined`
 | [`id`](#general) | `string` | No | `undefined`
 | [`shadowBlur`](#styling) | `number` | Yes | `0`

docs/guide/types/box.md

@@ -71,6 +71,7 @@ If one of the axes does not match an axis in the chart, the box will take the en
 | `adjustScaleRange` | Should the scale range be adjusted if this annotation is out of range.
 | `display` | Whether or not this annotation is visible.
 | `drawTime` | See [drawTime](../options.md#draw-time).
+| `hitTolerance` | Amount of pixels to interact with annotations within some distance of the mouse point.
 | `id` | Identifies a unique id  for the annotation and it will be stored in the element context. When the annotations are defined by an object, the id is automatically set using the key used to store the annotations in the object. When the annotations are configured by an array, the id, passed by this option in the annotation, will be used. 
 | `rotation` | Rotation of the box in degrees.
 | `xMax` | Right edge of the box in units along the x axis.

docs/guide/types/ellipse.md

@@ -68,6 +68,7 @@ If one of the axes does not match an axis in the chart, the ellipse will take th
 | `adjustScaleRange` | Should the scale range be adjusted if this annotation is out of range.
 | `display` | Whether or not this annotation is visible.
 | `drawTime` | See [drawTime](../options.md#draw-time).
+| `hitTolerance` | Amount of pixels to interact with annotations within some distance of the mouse point.
 | `id` | Identifies a unique id  for the annotation and it will be stored in the element context. When the annotations are defined by an object, the id is automatically set using the key used to store the annotations in the object. When the annotations are configured by an array, the id, passed by this option in the annotation, will be used. 
 | `rotation` | Rotation of the ellipse in degrees, default is 0.
 | `xMax` | Right edge of the ellipse in units along the x axis.

docs/guide/types/label.md

@@ -92,6 +92,7 @@ The 4 coordinates, xMin, xMax, yMin, yMax are optional. If not specified, the bo
 | `display` | Whether or not this annotation is visible.
 | `drawTime` | See [drawTime](../options.md#draw-time).
 | `height` | Overrides the height of the image or canvas element. Could be set in pixel by a number, or in percentage of current height of image or canvas element by a string. If undefined, uses the height of the image or canvas element. It is used only when the content is an image or canvas element.
+| `hitTolerance` | Amount of pixels to interact with annotations within some distance of the mouse point.
 | `id` | Identifies a unique id  for the annotation and it will be stored in the element context. When the annotations are defined by an object, the id is automatically set using the key used to store the annotations in the object. When the annotations are configured by an array, the id, passed by this option in the annotation, will be used. 
 | `padding` | The padding to add around the text label.
 | `rotation` | Rotation of the label in degrees.

docs/guide/types/line.md

@@ -89,6 +89,8 @@ If `scaleID` is unset, then `xScaleID` and `yScaleID` are used to draw a line fr
 | `display` | Whether or not this annotation is visible.
 | `drawTime` | See [drawTime](../options.md#draw-time).
 | `endValue` | End two of the line when a single scale is specified.
+| `hitTolerance` | Amount of pixels to interact with annotations within some distance of the mouse point.
+| `id` | Identifies a unique id  for the annotation and it will be stored in the element context. When the annotations are defined by an object, the id is automatically set using the key used to store the annotations in the object. When the annotations are configured by an array, the id, passed by this option in the annotation, will be used. 
 | `scaleID` | ID of the scale in single scale mode. If unset, `xScaleID` and `yScaleID` are used.
 | `value` | End one of the line when a single scale is specified.
 | `xMax` | X coordinate of end two of the line in units along the x axis.
@@ -134,9 +136,10 @@ All of these options can be [Scriptable](../options.md#scriptable-options)
 | [`color`](#fonts-and-colors) | [`Color`\|`Color[]`](../options#color) | `'#fff'` | Text color.
 | `content` | `string`\|`string[]`\|[`Image`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/Image)\|[`HTMLCanvasElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement) | `null` | The content to show in the label.
 | `display` | `boolean` | `false` | Whether or not the label is shown.
-| `drawTime` | `string` | `options.drawTime` | See [drawTime](../options#draw-time). Defaults to the line annotation draw time if unset.
+| `drawTime` | `string`\|`number` | `options.drawTime` | See [drawTime](../options#draw-time). Defaults to the line annotation draw time if unset.
 | [`font`](#fonts-and-colors) | [`Font`\|`Font[]`](../options#font) | `{ weight: 'bold' }` | Label font.
 | `height` | `number`\|`string` | `undefined` | Overrides the height of the image or canvas element. Could be set in pixel by a number, or in percentage of current height of image or canvas element by a string. If undefined, uses the height of the image or canvas element. It is used only when the content is an image or canvas element.
+| `hitTolerance` | `number` | `undefined` | Amount of pixels to interact with annotations within some distance of the mouse point.
 | `opacity` | `number` | `undefined` | Overrides the opacity of the image or canvas element. Could be set a number in the range 0.0 to 1.0, inclusive. If undefined, uses the opacity of the image or canvas element. It is used only when the content is an image or canvas element.
 | `padding` | [`Padding`](../options.md#padding) | `6` | The padding to add around the text label.
 | `position` | `string` | `'center'` | Anchor position of label on line. Possible options are: `'start'`, `'center'`, `'end'`. It can be set by a string in percentage format `'number%'` which are representing the percentage on the width of the line where the label will be located.

docs/guide/types/point.md

@@ -73,6 +73,7 @@ The 4 coordinates, xMin, xMax, yMin, yMax are optional. If not specified, the bo
 | `adjustScaleRange` | Should the scale range be adjusted if this annotation is out of range.
 | `display` | Whether or not this annotation is visible.
 | `drawTime` | See [drawTime](../options.md#draw-time).
+| `hitTolerance` | Amount of pixels to interact with annotations within some distance of the mouse point.
 | `id` | Identifies a unique id  for the annotation and it will be stored in the element context. When the annotations are defined by an object, the id is automatically set using the key used to store the annotations in the object. When the annotations are configured by an array, the id, passed by this option in the annotation, will be used. 
 | `radius` | Size of the point in pixels.
 | `rotation` | Rotation of point, in degrees.

docs/guide/types/polygon.md

@@ -78,6 +78,7 @@ The 4 coordinates, xMin, xMax, yMin, yMax are optional. If not specified, the bo
 | `adjustScaleRange` | Should the scale range be adjusted if this annotation is out of range.
 | `display` | Whether or not this annotation is visible.
 | `drawTime` | See [drawTime](../options.md#draw-time).
+| `hitTolerance` | Amount of pixels to interact with annotations within some distance of the mouse point.
 | `id` | Identifies a unique id  for the annotation and it will be stored in the element context. When the annotations are defined by an object, the id is automatically set using the key used to store the annotations in the object. When the annotations are configured by an array, the id, passed by this option in the annotation, will be used. 
 | `radius` | Size of the polygon in pixels.
 | `rotation` | Rotation of polygon, in degrees.