Isolate properties / modes from animation options (#8332)

* Isolate properties / modes from animation options
* tabs, something wrong with the linter
* Update misleading variable name

Author: kurkle

docs/docs/configuration/animations.mdx

@@ -33,21 +33,21 @@ function example() {
         }]
       },
       options: {
-          animation: {
-              tension: {
-                  duration: 1000,
-                  easing: 'linear',
-                  from: 1,
-                  to: 0,
-                  loop: true
-              }
-          },
-          scales: {
-            y: { // defining min and max so hiding the dataset does not change scale range
-              min: 0,
-              max: 100
-            }
+        animations: {
+          tension: {
+            duration: 1000,
+            easing: 'linear',
+            from: 1,
+            to: 0,
+            loop: true
+          }
+        },
+        scales: {
+          y: { // defining min and max so hiding the dataset does not change scale range
+            min: 0,
+            max: 100
           }
+        }
       }
     };
     const chart = new Chart(ctx, cfg);
@@ -77,24 +77,24 @@ function example() {
         }]
       },
       options: {
-          animation: {
-            show: {
-                x: {
-                    from: 0
-                },
-                y: {
-                    from: 0
-                }
+        transitions: {
+          show: {
+            x: {
+                from: 0
             },
-            hide: {
-                x: {
-                    to: 0
-                },
-                y: {
-                    to: 0
-                }
+            y: {
+                from: 0
+            }
+          },
+          hide: {
+            x: {
+                to: 0
+            },
+            y: {
+                to: 0
             }
           }
+        }
       }
     };
     const chart = new Chart(ctx, cfg);
@@ -107,10 +107,30 @@ function example() {
 </TabItem>
 </Tabs>
 
-## Animation Configuration
+## Animation configuration
+
+Animation configuration consists of 3 keys.
+
+| Name | Type | Details
+| ---- | ---- | -------
+| animation | `object` | [animation](#animation)
+| animations | `object` | [animations](#animations)
+| transitions | `object` | [transitions](#transitions)
+
+These keys can be configured in following paths:
 
-The default configuration is defined here: <a href="https://github.com/chartjs/Chart.js/blob/master/src/core/core.animations.js#L6-L55" target="_blank">core.animations.js</a>
-Namespace:  `options.animation`, the global options are defined in `Chart.defaults.animation`.
+* `` - chart options
+* `controllers[type]` - controller type options
+* `controllers[type].datasets` - dataset type options
+* `datasets[type]` - dataset type options
+
+These paths are valid under `defaults` for global confuguration and `options` for instance configuration.
+
+## animation
+
+The default configuration is defined here: <a href="https://github.com/chartjs/Chart.js/blob/master/src/core/core.animations.js#L9-L56" target="_blank">core.animations.js</a>
+
+Namespace: `options.animation`
 
 | Name | Type | Default | Description
 | ---- | ---- | ------- | -----------
@@ -119,84 +139,65 @@ Namespace:  `options.animation`, the global options are defined in `Chart.defaul
 | `debug` | `boolean` | `undefined` | Running animation count + FPS display in upper left corner of the chart.
 | `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
+## animations
 
-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).
+Animations options configures which element properties are animated and how.
+In addition to the main [animation configuration](#animation-configuration), the following options are available:
 
-### Default modes
-
-Namespace: `options.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).
-| `show` | 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).
-| `hide` | 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:
-
-Namespace: `options.animation[animation]`
+Namespace: `options.animations[animation]`
 
 | Name | Type | Default | Description
 | ---- | ---- | ------- | -----------
+| `properties` | `string[]` | `key` | The property names this configuration applies to. Defaults to the key name of this object.
 | `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`  | `number`\|`Color`\|`boolean` | `undefined` | Start value for the animation. Current value is used when `undefined`
 | `to`  | `number`\|`Color`\|`boolean` | `undefined` | End value for the animation. Updated value is used when `undefined`
 | `fn` | <code>&lt;T&gt;(from: T, to: T, factor: number) => T;</code> | `undefined` | Optional custom interpolator, instead of using a predefined interpolator from `type` |
 
-## 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 as the [animation property configuration](#animation-property-configuration), adding the following one:
-
-The animation properties collection configuration can be adjusted in the `options.animation[collection]` namespace.
-
-| Name | Type | Default | Description
-| ---- | ---- | ------- | -----------
-| `properties` | `string[]` | `undefined` | Set of properties to use to animate the chart.
-
-### Default collections
+### Default animations
 
 | Name | Option | Value
 | ---- | ------ | -----
-| `numbers` | `type` | `'number'`
 | `numbers` | `properties` | `['x', 'y', 'borderWidth', 'radius', 'tension']`
+| `numbers` | `type` | `'number'`
+| `colors` | `properties` | `['color', 'borderColor', 'backgroundColor']`
 | `colors` | `type` | `'color'`
-| `colors` | `properties` | `['borderColor', 'backgroundColor']`
-
-Direct property configuration overrides configuration of same property in a collection.
-
-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.
+These default animations are overridden by most of the dataset controllers.
 :::
 
+## transitions
+
+The core transitions are `'active'`, `'hide'`, `'reset'`, `'resize'`, `'show'`.
+A custom transtion can be used by passing a custom `mode` to [update](../developers/api.md#updatemode).
+Transition extends the main [animation configuration](#animation-configuration) and [animations configuration](#animations-configuration).
+
+### Default transitions
+
+Namespace: `options.transitions[mode]`
+
+| Mode | Option | Value | Description
+| -----| ------ | ----- | -----
+| `'active'` | animation.duration | 400 | Override default duration to 400ms for hover animations
+| `'resize'` | animation.duration | 0 | Override default duration to 0ms (= no animation) for resize
+| `'show'` | animations.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).
+| `'show'` | animations.visible | `{ type: 'boolean', duration: 0 }` | Dataset visiblity is immediately changed to true so the color transition from transparent is visible.
+| `'hide'` | animations.colors | `{ type: 'color', properties: ['borderColor', 'backgroundColor'], to: 'transparent' }` | Colors are faded to transparent when dataset id hidden using legend / [api](../developers/api.md#hidedatasetIndex).
+| `'hide'` | animations.visible | `{ type: 'boolean', easing: 'easeInExpo' }` | Visibility is changed to false at a very late phase of animation
+
 ## Disabling animation
 
 To disable an animation configuration, the animation node must be set to `false`, with the exception for animation modes which can be disabled by 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
+chart.options.animation = false; // disables all animations
+chart.options.animations.colors = false; // disables animation defined by the collection of 'colors' properties
+chart.options.animations.x = false; // disables animation defined by the 'x' property
+chart.options.transitions.active.animation.duration = 0; // disables the animation for 'active' mode
 ```
 
 ## Easing

docs/docs/developers/api.md

@@ -28,7 +28,7 @@ myLineChart.data.datasets[0].data[2] = 50; // Would update the first dataset's v
 myLineChart.update(); // Calling update now animates the position of March from 90 to 50.
 ```
 
-A `mode` string can be provided to indicate what should be updated and what animation configuration should be used. Core calls this method using any of `'active'`, `'hide'`, `'reset'`, `'resize'`, `'show'` or `undefined`. `'none'` is also a supported mode for skipping animations for single update. Please see [animations](../configuration/animations.mdx) docs for more details.
+A `mode` string can be provided to indicate transition configuration should be used. Core calls this method using any of `'active'`, `'hide'`, `'reset'`, `'resize'`, `'show'` or `undefined`. `'none'` is also a supported mode for skipping animations for single update. Please see [animations](../configuration/animations.mdx) docs for more details.
 
 Example:
 

samples/animations/drop.html

@@ -33,13 +33,13 @@
 				labels: ['January', 'February', 'March', 'April', 'May', 'June', 'July'],
 				datasets: [{
 					label: 'My First dataset',
-					animation: {
+					animations: {
 						y: {
 							duration: 2000,
-							delay: 100
+							delay: 500
 						}
 					},
-					backgroundColor: window.chartColors.red,
+					backgroundColor: 'rgba(170,0,0,0.1)',
 					borderColor: window.chartColors.red,
 					data: [
 						randomScalingFactor(),
@@ -50,7 +50,8 @@
 						randomScalingFactor(),
 						randomScalingFactor()
 					],
-					fill: false,
+					fill: 1,
+					tension: 0.5
 				}, {
 					label: 'My Second dataset',
 					fill: false,
@@ -68,10 +69,17 @@
 				}]
 			},
 			options: {
-				animation: {
+				animations: {
 					y: {
 						easing: 'easeInOutElastic',
-						from: 0
+						from: (ctx) => {
+							if (ctx.type === 'data') {
+								if (ctx.mode === 'default' && !ctx.dropped) {
+									ctx.dropped = true;
+									return 0;
+								}
+							}
+						}
 					}
 				},
 				responsive: true,

samples/animations/loop.html

@@ -62,7 +62,7 @@
 				}]
 			},
 			options: {
-				animation: {
+				animations: {
 					radius: {
 						duration: 400,
 						easing: 'linear',
@@ -74,23 +74,18 @@
 						hoverRadius: 6
 					}
 				},
-				responsive: true,
+				interaction: {
+					mode: 'nearest',
+					axis: 'x',
+					intersect: false
+				},
 				plugins: {
 					title: {
 						display: true,
 						text: 'Chart.js Line Chart'
 					},
-					tooltip: {
-						mode: 'nearest',
-						axis: 'x',
-						intersect: false,
-					},
-				},
-				hover: {
-					mode: 'nearest',
-					axis: 'x',
-					intersect: false
 				},
+				responsive: true,
 				scales: {
 					x: {
 						display: true,

src/controllers/controller.bar.js

@@ -520,7 +520,7 @@ BarController.defaults = {
   datasets: {
     categoryPercentage: 0.8,
     barPercentage: 0.9,
-    animation: {
+    animations: {
       numbers: {
         type: 'number',
         properties: ['x', 'y', 'base', 'width', 'height']

src/controllers/controller.bubble.js

@@ -133,8 +133,9 @@ BubbleController.id = 'bubble';
 BubbleController.defaults = {
   datasetElementType: false,
   dataElementType: 'point',
-  animation: {
+  animations: {
     numbers: {
+      type: 'number',
       properties: ['x', 'y', 'borderWidth', 'radius']
     }
   },

src/controllers/controller.doughnut.js

@@ -329,15 +329,17 @@ DoughnutController.defaults = {
   datasetElementType: false,
   dataElementType: 'arc',
   animation: {
-    numbers: {
-      type: 'number',
-      properties: ['circumference', 'endAngle', 'innerRadius', 'outerRadius', 'startAngle', 'x', 'y', 'offset', 'borderWidth']
-    },
     // Boolean - Whether we animate the rotation of the Doughnut
     animateRotate: true,
     // Boolean - Whether we animate scaling the Doughnut from the centre
     animateScale: false
   },
+  animations: {
+    numbers: {
+      type: 'number',
+      properties: ['circumference', 'endAngle', 'innerRadius', 'outerRadius', 'startAngle', 'x', 'y', 'offset', 'borderWidth']
+    },
+  },
   aspectRatio: 1,
 
   datasets: {

src/controllers/controller.polarArea.js

@@ -122,12 +122,14 @@ PolarAreaController.id = 'polarArea';
 PolarAreaController.defaults = {
   dataElementType: 'arc',
   animation: {
+    animateRotate: true,
+    animateScale: true
+  },
+  animations: {
     numbers: {
       type: 'number',
       properties: ['x', 'y', 'startAngle', 'endAngle', 'innerRadius', 'outerRadius']
     },
-    animateRotate: true,
-    animateScale: true
   },
   aspectRatio: 1,
   indexAxis: 'r',

src/core/core.animation.js

@@ -28,7 +28,7 @@ export default class Animation {
 
     this._active = true;
     this._fn = cfg.fn || interpolators[cfg.type || typeof from];
-    this._easing = effects[cfg.easing || 'linear'];
+    this._easing = effects[cfg.easing] || effects.linear;
     this._start = Math.floor(Date.now() + (cfg.delay || 0));
     this._duration = Math.floor(cfg.duration);
     this._loop = !!cfg.loop;