TypeScript updates (#8190)

* Update type definitions and docs for legends

* Fix types for onHover and onClick callbacks

core.controller.js's implementation also passes the Chart instance as `this`. However, that isn't documented, and it's my impression that Chart.js is moving away from passing items as `this`, so I didn't declare it in the type definitions.

* Allow multi-line ticks

* Stricter DeepPartial definition

The previous definition resolved to `{}` (which can allow primitives) if it was given a function, so it was far too broad for any `Scriptable<>` properties.

* Grammar and writing style

* Updates to animation docs

Document the `fn` option, since it's in the type definitions.

Fix callback usage to match example code.

* Fix AnimationEvent parameter

The onProgress and onComplete events were mistakenly declared as taking the standard DOM AnimationEvent.  (Should Chart.js's AnimationEvent be renamed to ChartAnimationEvent to avoid any possible ambiguity?)

* Allow false for disabling animations

* Add comments explaining the layout and usage of Rollup

Author: joshkel

docs/docs/configuration/animations.mdx

@@ -123,7 +123,7 @@ The default configuration is defined here: <a href="https://github.com/chartjs/C
 | [[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)
+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
 
@@ -153,6 +153,7 @@ A property option is defined by the same options of the main [animation configur
 | `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`
 | `to`  | <code>`number`&#124;`Color`&#124;`boolean`</code> | `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
 
@@ -183,7 +184,7 @@ These default collections are overridden by most dataset controllers.
 
 ## Disabling 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`.
+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
@@ -232,15 +233,15 @@ See [Robert Penner's easing equations](http://robertpenner.com/easing/).
 
 ## Animation Callbacks
 
-The animation configuration enables the callbacks which  are useful for synchronizing an external draw to the chart animation.
+The animation configuration provides 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:
+The callback is passed the following object:
 
 ```javascript
 {
@@ -264,7 +265,7 @@ var chart = new Chart(ctx, {
     options: {
         animation: {
             onProgress: function(animation) {
-                progress.value = animation.animationObject.currentStep / animation.animationObject.numSteps;
+                progress.value = animation.currentStep / animation.numSteps;
             }
         }
     }

docs/docs/configuration/legend.md

@@ -82,6 +82,9 @@ Items passed to the legend `onClick` function are the ones returned from `labels
     // Label that will be displayed
     text: string,
 
+    // Index of the associated dataset
+    datasetIndex: number,
+
     // Fill style of the legend box
     fillStyle: Color,
 

types/core/index.d.ts

@@ -874,7 +874,7 @@ export const registry: Registry;
 
 export interface Tick {
 	value: number;
-	label?: string;
+	label?: string | string[];
 	major?: boolean;
 }
 

types/core/interfaces.d.ts

@@ -1,4 +1,4 @@
-import { Chart, Element, InteractionMode } from '.';
+import { ActiveElement, AnimationEvent, Chart, InteractionMode } from '.';
 import { ChartDataset } from '../interfaces';
 import { ParsingOptions } from '../controllers';
 import { PluginOptions } from '../plugins';
@@ -85,14 +85,14 @@ export interface HoverInteractionOptions extends CoreInteractionOptions {
   /**
    * Called when any of the events fire. Passed the event, an array of active elements (bars, points, etc), and the chart.
    */
-  onHover(event: ChartEvent, elements: Element[]): void;
+  onHover(event: ChartEvent, elements: ActiveElement[], chart: Chart): void;
 }
 
 export interface CoreChartOptions extends ParsingOptions {
-  animation: Scriptable<AnimationOptions>;
+  animation: Scriptable<AnimationOptions | false>;
 
   datasets: {
-    animation: Scriptable<AnimationOptions>;
+    animation: Scriptable<AnimationOptions | false>;
   };
 
   /**
@@ -131,7 +131,7 @@ export interface CoreChartOptions extends ParsingOptions {
    * @default 2
    */
   aspectRatio: number;
-	
+
   /**
    * Locale used for number formatting (using `Intl.NumberFormat`).
    * @default user's browser setting
@@ -162,12 +162,12 @@ export interface CoreChartOptions extends ParsingOptions {
   /**
    * Called when any of the events fire. Passed the event, an array of active elements (bars, points, etc), and the chart.
    */
-  onHover(event: ChartEvent, elements: Element[]): void;
+  onHover(event: ChartEvent, elements: ActiveElement[], chart: Chart): void;
 
   /**
    * Called if the event is of type 'mouseup' or 'click'. Passed the event, an array of active elements, and the chart.
    */
-  onClick(event: ChartEvent, elements: Element[]): void;
+  onClick(event: ChartEvent, elements: ActiveElement[], chart: Chart): void;
 
   layout: {
     padding: Scriptable<number | ChartArea>;
@@ -261,7 +261,7 @@ export interface AnimationPropertySpec extends AnimationCommonSpec {
 }
 
 export type AnimationSpecContainer = AnimationCommonSpec & {
-	[prop: string]: AnimationPropertySpec;
+	[prop: string]: AnimationPropertySpec | false;
 };
 
 export type AnimationOptions = AnimationSpecContainer & {
@@ -270,15 +270,15 @@ export type AnimationOptions = AnimationSpecContainer & {
 	 */
 	onProgress: (this: Chart, event: AnimationEvent) => void;
 	/**
-	 *Callback called when all animations are completed.
+	 * Callback called when all animations are completed.
 	 */
 	onComplete: (this: Chart, event: AnimationEvent) => void;
 
-	active: AnimationSpecContainer;
-	hide: AnimationSpecContainer;
-	reset: AnimationSpecContainer;
-	resize: AnimationSpecContainer;
-	show: AnimationSpecContainer;
+	active: AnimationSpecContainer | false;
+	hide: AnimationSpecContainer | false;
+	reset: AnimationSpecContainer | false;
+	resize: AnimationSpecContainer | false;
+	show: AnimationSpecContainer | false;
 };
 
 export interface FontSpec {

types/index.esm.d.ts

@@ -1,3 +1,17 @@
+/**
+ * Top-level type definitions.  These are processed by Rollup and rollup-plugin-dts
+ * to make a combined .d.ts file under dist; that way, all of the type definitions
+ * appear directly within the "chart.js" module; that matches the layout of the
+ * distributed chart.esm.js bundle and means that users of Chart.js can easily use
+ * module augmentation to extend Chart.js's types and plugins within their own
+ * code, like so:
+ *
+ * @example
+ * declare module "chart.js" {
+ *   // Add types here
+ * }
+ */
+
 export * from './controllers';
 export * from './core';
 export * from './elements';

types/interfaces.d.ts

@@ -32,11 +32,18 @@ import {
   TimeScaleOptions,
 } from './scales';
 
-export type DeepPartial<T> = T extends {}
-  ? {
-      [K in keyof T]?: DeepPartial<T[K]>;
-    }
-  : T;
+// DeepPartial implementation taken from the utility-types NPM package, which is
+// Copyright (c) 2016 Piotr Witek <piotrek.witek@gmail.com> (http://piotrwitek.github.io)
+// and used under the terms of the MIT license
+export type DeepPartial<T> = T extends Function
+  ? T
+  : T extends Array<infer U>
+  ? _DeepPartialArray<U>
+  : T extends object
+  ? _DeepPartialObject<T>
+  : T | undefined;
+interface _DeepPartialArray<T> extends Array<DeepPartial<T>> {}
+type _DeepPartialObject<T> = { [P in keyof T]?: DeepPartial<T[P]> };
 
 export type DistributiveArray<T> = T extends unknown ? T[] : never
 

types/plugins/index.d.ts

@@ -41,59 +41,64 @@ export interface LegendItem {
    */
   text: string;
 
+  /**
+   * Index of the associated dataset
+   */
+  datasetIndex: number;
+
   /**
    * Fill style of the legend box
    */
-  fillStyle: CanvasLineCap;
+  fillStyle?: Color;
 
   /**
    * If true, this item represents a hidden dataset. Label will be rendered with a strike-through effect
    */
-  hidden: boolean;
+  hidden?: boolean;
 
   /**
    * For box border.
    * @see https://developer.mozilla.org/en/docs/Web/API/CanvasRenderingContext2D/lineCap
    */
-  lineCap: CanvasLineCap;
+  lineCap?: CanvasLineCap;
 
   /**
    * For box border.
    * @see https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash
    */
-  lineDash: number[];
+  lineDash?: number[];
 
   /**
    * For box border.
    * @see https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset
    */
-  lineDashOffset: number;
+  lineDashOffset?: number;
 
   /**
    * For box border.
    * @see https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin
    */
-  lineJoin: CanvasLineJoin;
+  lineJoin?: CanvasLineJoin;
 
   /**
    * Width of box border
    */
-  lineWidth: number;
+  lineWidth?: number;
 
   /**
    * Stroke style of the legend box
    */
-  strokeStyle: Color;
+  strokeStyle?: Color;
 
   /**
    * Point style of the legend box (only used if usePointStyle is true)
    */
-  pointStyle: PointStyle;
+  pointStyle?: PointStyle;
 
   /**
    * Rotation of the point in degrees (only used if usePointStyle is true)
    */
-  rotation: number;
+  rotation?: number;
 }
 
 export interface LegendElement extends Element {}
@@ -129,11 +134,11 @@ export interface LegendOptions {
    */
   onClick(this: LegendElement, e: ChartEvent, legendItem: LegendItem, legend: LegendElement): void;
   /**
-   *	A callback that is called when a 'mousemove' event is registered on top of a label item
+   * A callback that is called when a 'mousemove' event is registered on top of a label item
    */
   onHover(this: LegendElement, e: ChartEvent, legendItem: LegendItem, legend: LegendElement): void;
   /**
-   *	A callback that is called when a 'mousemove' event is registered outside of a previously hovered label item.
+   * A callback that is called when a 'mousemove' event is registered outside of a previously hovered label item.
    */
   onLeave(this: LegendElement, e: ChartEvent, legendItem: LegendItem, legend: LegendElement): void;
 
@@ -176,7 +181,7 @@ export interface LegendOptions {
     pointStyle: PointStyle;
 
     /**
-     * Label style will match corresponding point style (size is based on the mimimum value between boxWidth and font.size).
+     * Label style will match corresponding point style (size is based on the minimum value between boxWidth and font.size).
      * @default false
      */
     usePointStyle: boolean;