From: stockiNail <stocki.nail@gmail.com>
Date: Fri, 31 Jul 2020 13:49:17 +0000 (+0200)
Subject: Add some additional info and sections to animation documentation (#7685)
X-Git-Tag: v3.0.0-beta.2~22
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=65c31cfd6e6ce5daaf838496391624255e654859;p=thirdparty%2FChart.js.git

Add some additional info and sections to animation documentation (#7685)
---

diff --git a/docs/docs/configuration/animations.mdx b/docs/docs/configuration/animations.mdx
index da7881ee4..5088f0f15 100644
--- a/docs/docs/configuration/animations.mdx
+++ b/docs/docs/configuration/animations.mdx
@@ -115,17 +115,52 @@ The default configuration is defined here: <a href="https://github.com/chartjs/C
 | `duration` | `number` | `1000` | The number of milliseconds an animation takes.
 | `easing` | `string` | `'easeOutQuart'` | Easing function to use. [more...](#easing)
 | `debug` | `boolean` | `undefined` | Running animation count + FPS display in upper left corner of the chart.
-| `onProgress` | `function` | `null` | Callback called on each step of an animation. [more...](#animation-callbacks)
-| `onComplete` | `function` | `null` | Callback called when all animations are completed. [more...](#animation-callbacks)
 | `delay` | `number` | `undefined` | Delay before starting the animations.
 | `loop` | `boolean` | `undefined` | If set to `true`, the animations loop endlessly.
+| [[mode]](#animation-mode-configuration) | `object` | [defaults...](#default-modes) | Option overrides for update mode. Core modes: `'active'`, `'hide'`, `'reset'`, `'resize'`, `'show'`. See **Hide and show [mode]** example above. 
+| [[property]](#animation-property-configuration) | `object` | `undefined` | Option overrides for a single element `[property]`. These have precedence over `[collection]`. See **Looping tension [property]** example above.
+| [[collection]](#animation-properties-collection-configuration) | `object` | [defaults...](#default-collections) | Option overrides for multiple properties, identified by `properties` array.
+
+These defaults can be overridden in `options.animation` or `dataset.animation` and `tooltip.animation`. These keys are also [Scriptable](../general/options.md#scriptable-options)
+
+## Animation mode configuration
+
+Mode option configures how an update mode animates the chart. 
+The cores modes are `'active'`, `'hide'`, `'reset'`, `'resize'`, `'show'`. 
+A custom mode can be used by passing a custom `mode` to [update](../developers/api.md#updatemode).
+A mode option is defined by the same options of the main [animation configuration](#animation-configuration).
+
+### Default modes
+
+| Mode | Option | Value | Description
+| -----| ------ | ----- | -----
+| `'active'` | duration | 400 | Override default duration to 400ms for hover animations
+| `'resize'` | duration | 0 | Override default duration to 0ms (= no animation) for resize
+| `'show'` | colors | `{ type: 'color', properties: ['borderColor', 'backgroundColor'], from: 'transparent' }` | Colors are faded in from transparent when dataset is shown using legend / [api](../developers/api.md#showdatasetIndex).
+| | visible | `{ type: 'boolean', duration: 0 }` | Dataset visiblity is immediately changed to true so the color transition from transparent is visible.
+| `'hide'` | colors | `{ type: 'color', properties: ['borderColor', 'backgroundColor'], to: 'transparent' }` | Colors are faded to transparent when dataset id hidden using legend / [api](../developers/api.md#hidedatasetIndex).
+| | visible | `{ type: 'boolean', easing: 'easeInExpo' }` | Visibility is changed to false at a very late phase of animation
+
+## Animation property configuration
+
+Property option configures which element property to use to animate the chart and its starting and ending values.
+A property option is defined by the same options of the main [animation configuration](#animation-configuration), adding the following ones:
+
+| Name | Type | Default | Description
+| ---- | ---- | ------- | -----------
 | `type` | `string` | `typeof property` | Type of property, determines the interpolator used. Possible values: `'number'`, `'color'` and `'boolean'`. Only really needed for `'color'`, because `typeof` does not get that right.
 | `from`  | <code>`number`&#124;`Color`&#124;`boolean`</code> | `undefined` | Start value for the animation. Current value is used when `undefined`
-| `active` | `object` | `{ duration: 400 }` | Option overrides for `active` animations (hover)
-| `resize` | `object` | `{ duration: 0 }` | Option overrides for `resize` animations.
-| [property] | `object` | `undefined` | Option overrides for a single element `[property]`. These have precedence over `[collection]`. See **Looping tension [property]** example above.
-| [collection] | `object` | [defaults...](#default-collections) | Option overrides for multiple properties, identified by `properties` array. Collection can be named whatever you like, but should not collide with a `[property]` or `[mode]`.
-| [mode] | `object` | [defaults...](#default-modes) | Option overrides for update mode. Core modes: `'active'`, `'hide'`, `'reset'`, `'resize'`, `'show'`. See **Hide and show [mode]** example above. A custom mode can be used by passing a custom `mode` to [update](../developers/api.md#updatemode)
+| `to`  | <code>`number`&#124;`Color`&#124;`boolean`</code> | `undefined` | End value for the animation. Updated value is used when `undefined`
+
+## Animation properties collection configuration
+
+Properties collection option configures which set of element properties to use to animate the chart.
+Collection can be named whatever you like, but should not collide with a `[property]` or `[mode]`.
+A properties collection option is defined by the same options of the [animation property configuration](#animation-property-configuration), adding the following one:
+
+| Name | Type | Default | Description
+| ---- | ---- | ------- | -----------
+| `properties` | `string[]` | `undefined` | Set of properties to use to animate the chart.
 
 ### Default collections
 
@@ -138,22 +173,22 @@ The default configuration is defined here: <a href="https://github.com/chartjs/C
 
 Direct property configuration overrides configuration of same property in a collection.
 
-These defaults can be overridden in `options.animation` or `dataset.animation` and `tooltip.animation`. These keys are also [Scriptable](../general/options.md#scriptable-options)
+From collections, a property gets its configuration from first one that has its name in properties.
 
 :::note
 These default collections are overridden by most dataset controllers.
 :::
 
-### Default modes
+## Disabling animation
 
-| Mode | Option | Value | Description
-| -----| ------ | ----- | -----
-| `'active'` | duration | 400 | Override default duration to 400ms for hover animations
-| `'resize'` | duration | 0 | Override default duration to 0ms (= no animation) for resize
-| `'show'` | colors | `{ type: 'color', properties: ['borderColor', 'backgroundColor'], from: 'transparent' }` | Colors are faded in from transparent when dataset is shown using legend / [api](../developers/api.md#showdatasetIndex).
-| | visible | `{ type: 'boolean', duration: 0 }` | Dataset visiblity is immediately changed to true so the color transition from transparent is visible.
-| `'hide'` | colors | `{ type: 'color', properties: ['borderColor', 'backgroundColor'], to: 'transparent' }` | Colors are faded to transparent when dataset id hidden using legend / [api](../developers/api.md#hidedatasetIndex).
-| | visible | `{ type: 'boolean', easing: 'easeInExpo' }` | Visibility is changed to false very at late phase of animation
+To disable an animation configuration, the animation node must be set to `false`, with the exception for animation modes which can be disable setting the `duration` to `0`. 
+
+```javascript
+chart.options.animation = false; // disables the whole animation
+chart.options.animation.active.duration = 0; // disables the animation for 'active' mode
+chart.options.animation.colors = false; // disables animation defined by the collection of 'colors' properties
+chart.options.animation.x = false; // disables animation defined by the 'x' property 
+```
 
 ## Easing
 
@@ -195,7 +230,15 @@ See [Robert Penner's easing equations](http://robertpenner.com/easing/).
 
 ## Animation Callbacks
 
-The `onProgress` and `onComplete` callbacks are useful for synchronizing an external draw to the chart animation. The callback is passed following object:
+The animation configuration enables the callbacks which  are useful for synchronizing an external draw to the chart animation.
+The callbacks can be set only at main [animation configuration](#animation-configuration).
+
+| Name | Type | Default | Description
+| ---- | ---- | ------- | -----------
+| `onProgress` | `function` | `null` | Callback called on each step of an animation.
+| `onComplete` | `function` | `null` | Callback called when all animations are completed.
+
+The callback is passed following object:
 
 ```javascript
 {