Enable initial animation on annotations

docs/.vuepress/config.js

@@ -144,6 +144,7 @@ module.exports = {
             'box/disclosure',
             'box/canvas',
             'box/image',
+            'box/initAnim',
             'box/gradient',
           ]
         },
@@ -196,6 +197,7 @@ module.exports = {
             'point/combined',
             'point/outsideChartArea',
             'point/shadow',
+            'point/initAnim',
           ]
         },
         {

docs/guide/configuration.md

@@ -63,7 +63,36 @@ 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.md#draw-time).
+| `drawTime` | `string` | 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
+
+The `init` option is scriptable but it doesn't get the [options context](./options#option-context) as argument but a specific context because the element has not been initialized yet, when the callback is invoked.
+
+This is the signature of the scriptable option:
+
+```javascript
+({chart, properties, options}) => void | boolean | AnnotationBoxModel
+```
+
+where the properties is the element model
+
+```javascript
+{
+  x: number,
+  y: number,
+  x2: number,
+  y2: number,
+  centerX: number,
+  centerY: number,
+  width: number,
+  height: number,
+  radius?: number
+}
+```
+
+which can be used in the callback to return an object with the initial values of the element, to provide own initial animation. 
 
 ## Events
 

docs/guide/types/_commonOptions.md

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

docs/samples/box/initAnim.md

@@ -0,0 +1,120 @@
+# Initial animations
+
+```js chart-editor
+// <block:setup:4>
+const DATA_COUNT = 12;
+const MIN = 10;
+const MAX = 100;
+
+const numberCfg = {count: DATA_COUNT, min: MIN, max: MAX};
+
+const data = {
+  labels: ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December'],
+  datasets: [{
+    data: Utils.numbers(numberCfg)
+  }]
+};
+// </block:setup>
+
+// <block:annotation1:1>
+const annotation1 = {
+  type: 'box',
+  backgroundColor: 'rgba(0, 150, 0, 0.2)',
+  borderColor: 'rgba(0, 150, 0)',
+  borderRadius: 4,
+  borderWidth: 1,
+  init: true,
+  label: {
+    display: true,
+    content: 'Fade'
+  },
+  xMax: 6.5,
+  xMin: 4.5,
+  yMax: 60,
+  yMin: 40
+};
+// </block:annotation1>
+
+// <block:annotation2:2>
+const annotation2 = {
+  type: 'box',
+  backgroundColor: 'rgba(0, 150, 0, 0.2)',
+  borderColor: 'rgba(0, 150, 0)',
+  borderRadius: 4,
+  borderWidth: 1,
+  init: () => ({y: 0, y2: 0}),
+  label: {
+    display: true,
+    content: 'Flyin from top'
+  },
+  xMax: 2.5,
+  xMin: 0.5,
+  yMax: 30,
+  yMin: 10
+};
+// </block:annotation2>
+
+// <block:annotation3:3>
+const annotation3 = {
+  type: 'box',
+  backgroundColor: 'rgba(0, 150, 0, 0.2)',
+  borderColor: 'rgba(0, 150, 0)',
+  borderRadius: 4,
+  borderWidth: 1,
+  init: () => ({x: 0, x2: 0}),
+  label: {
+    display: true,
+    content: 'Flyin from left'
+  },
+  xMax: 10.5,
+  xMin: 8.5,
+  yMax: 90,
+  yMin: 70
+};
+// </block:annotation3>
+
+/* <block:config:0> */
+const config = {
+  type: 'line',
+  data,
+  options: {
+    scales: {
+      y: {
+        beginAtZero: true,
+        max: 100,
+        min: 0
+      }
+    },
+    plugins: {
+      annotation: {
+        common: {
+          drawTime: 'afterDraw'
+        },
+        annotations: {
+          annotation1,
+          annotation2,
+          annotation3
+        }
+      }
+    }
+  }
+};
+/* </block:config> */
+
+const actions = [
+  {
+    name: 'Randomize',
+    handler: function(chart) {
+      chart.data.datasets.forEach(function(dataset, i) {
+        dataset.data = dataset.data.map(() => Utils.rand(MIN, MAX));
+      });
+      chart.update();
+    }
+  }
+];
+
+module.exports = {
+  actions: actions,
+  config: config,
+};
+```

docs/samples/point/initAnim.md

@@ -0,0 +1,156 @@
+# Initial animations
+
+```js chart-editor
+// <block:setup:4>
+const DATA_COUNT = 12;
+const MIN = 10;
+const MAX = 100;
+
+const numberCfg = {count: DATA_COUNT, min: MIN, max: MAX};
+
+const data = {
+  labels: ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December'],
+  datasets: [{
+    data: Utils.numbers(numberCfg)
+  }]
+};
+// </block:setup>
+
+// <block:annotation1:1>
+const annotation1 = {
+  type: 'point',
+  backgroundColor: 'rgba(0, 150, 0, 0.2)',
+  borderColor: 'rgba(0, 150, 0)',
+  borderRadius: 4,
+  borderWidth: 1,
+  init: true,
+  label: {
+    display: true,
+    content: 'Fade',
+    textAlign: 'center'
+  },
+  radius: 40,
+  xMax: 6.5,
+  xMin: 4.5,
+  yMax: 60,
+  yMin: 40
+};
+const labelAnnotation1 = {
+  type: 'label',
+  init: true,
+  content: 'Fade',
+  xMax: 6.5,
+  xMin: 4.5,
+  yMax: 60,
+  yMin: 40
+};
+// </block:annotation1>
+
+// <block:annotation2:2>
+const annotation2 = {
+  type: 'point',
+  backgroundColor: 'rgba(0, 150, 0, 0.2)',
+  borderColor: 'rgba(0, 150, 0)',
+  borderRadius: 4,
+  borderWidth: 1,
+  init: () => ({centerY: 0}),
+  label: {
+    display: true,
+    content: 'Flyin from top',
+    textAlign: 'center'
+  },
+  radius: 40,
+  xMax: 2.5,
+  xMin: 0.5,
+  yMax: 30,
+  yMin: 10
+};
+const labelAnnotation2 = {
+  type: 'label',
+  init: () => ({y: 0, y2: 0, width: 0, height: 0}),
+  content: 'Flyin from top',
+  xMax: 2.5,
+  xMin: 0.5,
+  yMax: 30,
+  yMin: 10
+};
+// </block:annotation2>
+
+// <block:annotation3:3>
+const annotation3 = {
+  type: 'point',
+  backgroundColor: 'rgba(0, 150, 0, 0.2)',
+  borderColor: 'rgba(0, 150, 0)',
+  borderRadius: 4,
+  borderWidth: 1,
+  init: () => ({centerX: 0}),
+  label: {
+    display: true,
+    content: 'Flyin from left',
+    textAlign: 'center'
+  },
+  radius: 40,
+  xMax: 10.5,
+  xMin: 8.5,
+  yMax: 90,
+  yMin: 70
+};
+const labelAnnotation3 = {
+  type: 'label',
+  init: () => ({x: 0, x2: 0, width: 0, height: 0}),
+  content: 'Flyin from left',
+  xMax: 10.5,
+  xMin: 8.5,
+  yMax: 90,
+  yMin: 70
+};
+// </block:annotation3>
+
+/* <block:config:0> */
+const config = {
+  type: 'line',
+  data,
+  options: {
+    scales: {
+      y: {
+        beginAtZero: true,
+        max: 100,
+        min: 0
+      }
+    },
+    plugins: {
+      annotation: {
+        common: {
+          drawTime: 'afterDraw'
+        },
+        annotations: {
+          annotation1,
+          labelAnnotation1,
+          annotation2,
+          labelAnnotation2,
+          annotation3,
+          labelAnnotation3
+        }
+      }
+    }
+  }
+};
+/* </block:config> */
+
+const actions = [
+  {
+    name: 'Randomize',
+    handler: function(chart) {
+      chart.data.datasets.forEach(function(dataset, i) {
+        dataset.data = dataset.data.map(() => Utils.rand(MIN, MAX));
+      });
+      chart.update();
+    }
+  }
+];
+
+module.exports = {
+  actions: actions,
+  config: config,
+};
+```

src/annotation.js

@@ -120,14 +120,15 @@ export default {
     },
     common: {
       drawTime: 'afterDatasetsDraw',
+      init: false,
       label: {
       }
     }
   },
 
   descriptors: {
     _indexable: false,
-    _scriptable: (prop) => !hooks.includes(prop),
+    _scriptable: (prop) => !hooks.includes(prop) && prop !== 'init',
     annotations: {
       _allKeys: false,
       _fallback: (prop, opts) => `elements.${annotationTypes[resolveType(opts.type)].id}`