Export extensible classes in ESM compatible way (#7650)

* Export extensible classes in ESM compatible way
* Export collection helperrs
* Remove reduntant registry assignment

diff --git a/docs/docs/developers/axes.md b/docs/docs/developers/axes.md
index 474dbd089956491b8691d6dd48e3d08749364257..e28f937c85d3edc4e5991d968e43b57f301ad796 100644 (file)
--- a/docs/docs/developers/axes.md
+++ b/docs/docs/developers/axes.md
@@ -31,12 +31,12 @@ MyScale.defaults = defaultConfigObject;
 // MyScale is now derived from Chart.Scale
 ```
 
-Once you have created your scale class, you need to register it with the global chart object so that it can be used. A default config for the scale may be provided when registering the constructor. The first parameter to the register function is a string key that is used later to identify which scale type to use for a chart.
+Once you have created your scale class, you need to register it with the global chart object so that it can be used.
 
 ```javascript
 Chart.register(MyScale);
 
-// If the scale is created in classical way, the prototype can not be used to detect what
+// If the new scale is not extending Chart.Scale, the prototype can not be used to detect what
 // you are trying to register - so you need to be explicit:
 
 // Chart.registry.addScales(MyScale);

diff --git a/docs/docs/developers/charts.md b/docs/docs/developers/charts.md
index 05ab8025a37df55f48ddf7f45fde3e934fa2e006..385132b8ea53db85ec7b24308ef977a20b37786a 100644 (file)
--- a/docs/docs/developers/charts.md
+++ b/docs/docs/developers/charts.md
@@ -2,14 +2,14 @@
 title: New Charts
 ---
 
-Chart.js 2.0 introduces the concept of controllers for each dataset. Like scales, new controllers can be written as needed.
+Chart.js 2.0 introduced the concept of controllers for each dataset. Like scales, new controllers can be written as needed.
 
 ```javascript
 class MyType extends Chart.DatasetController {
 
 }
 
-Chart.controllers.MyType = MyType;
+Chart.register(MyType);
 
 // Now we can create a new instance of our chart, using the Chart.js API
 new Chart(ctx, {
@@ -66,17 +66,22 @@ Extending or replacing an existing controller type is easy. Simply replace the c
 
 The built in controller types are:
 
-* `Chart.controllers.line`
-* `Chart.controllers.bar`
-* `Chart.controllers.radar`
-* `Chart.controllers.doughnut`
-* `Chart.controllers.polarArea`
-* `Chart.controllers.bubble`
+* `BarController`
+* `BubbleController`
+* `DoughnutController`
+* `LineController`
+* `PieController`
+* `PolarAreaController`
+* `RadarController`
+* `ScatterController`
+
+These controllers are also available in the UMD package, directly under `Chart`. Eg: `Chart.BarController`.
 
 For example, to derive a new chart type that extends from a bubble chart, you would do the following.
 
 ```javascript
-class Custom extends Chart.controllers.bubble {
+import {BubbleController} from 'chart.js';
+class Custom extends BubbleController {
     draw() {
         // Call super method first
         super.draw(arguments);
@@ -95,7 +100,7 @@ class Custom extends Chart.controllers.bubble {
     }
 });
 Custom.id = 'derivedBubble';
-Custom.defaults = Chart.defaults.bubble;
+Custom.defaults = BubbleController.defaults;
 
 // Stores the controller so that the chart initialization routine can look it up
 Chart.register(Custom);
@@ -112,14 +117,14 @@ Same example in classic style
 
 ```javascript
 function Custom() {
-  Chart.controllers.bubble.apply(this, arguments);
+  Chart.BubbleController.apply(this, arguments);
   // constructor stuff
 }
-Custom.prototype = Object.create(Chart.controllers.bubble.prototype);
+Custom.prototype = Object.create(Chart.BubbleController.prototype);
 Custom.prototype.constructor = Custom;
 
 Custom.prototype.draw = function(ctx) {
-    Chart.controllers.bubble.prototype.draw.apply(this, arguments);
+    Chart.BubbleController.prototype.draw.apply(this, arguments);
 
     var meta = this.getMeta();
     var pt0 = meta.data[0];

diff --git a/docs/docs/developers/publishing.md b/docs/docs/developers/publishing.md
new file mode 100644 (file)
index 0000000..6c419f8
--- /dev/null
+++ b/docs/docs/developers/publishing.md
@@ -0,0 +1,31 @@
+---
+title: Publishing an extension
+---
+
+If you are planning on publishing an extension for Chart.js, here are a some pointers.
+
+## Awesome
+
+You'd probably want your extension to be listed in the [awesome](https://github.com/chartjs/awesome).
+
+Note the minimum extension age requirement of 30 days.
+
+## ESM
+
+If you are utilizing ESM, you probably still want to publish an UMD bundle of your extension. Because Chart.js v3 is tree shakeable, the interface is a bit different.
+UMD package's global `Chart` includes everything, while ESM package exports all the things separately.
+Fortunately, most of the exports can be mapped automatically by the bundlers.
+
+But not the helpers.
+
+In UMD, helpers are available through `Chart.helpers`. In ESM, they are imported from `chart.js/helpers`.
+
+There are multiple namespaces under helpers. Some of the namespaces are bundled directly under `Chart.helpers` for backward compatibility, those are: `core`, `color` and `extras`.
+
+For example `import {isNullOrUndef} from 'chart.js/helpers/core'` is available at `Chart.helpers.isNullOrUndef` for UMD.
+
+### Rollup
+
+`output.globals` can be used to convert the helpers.
+
+For convinience, a plugin is available for the configuration: [rollup-plugin-chartjs-globals](https://www.npmjs.com/package/rollup-plugin-chartjs-globals).

diff --git a/docs/docs/getting-started/v3-migration.md b/docs/docs/getting-started/v3-migration.md
index f45c42d0623bbb86fefb38f94f1277db7041a5db..15ffddc0a12923818767d445459b3b6cdc81d5f6 100644 (file)
--- a/docs/docs/getting-started/v3-migration.md
+++ b/docs/docs/getting-started/v3-migration.md
@@ -245,6 +245,7 @@ The following properties and methods were removed:
 
 #### Chart
 
+* `Chart.animationService`
 * `Chart.active`
 * `Chart.borderWidth`
 * `Chart.chart.chart`

diff --git a/docs/sidebars.js b/docs/sidebars.js
index d19eb365a98aa4bcba3799a22ea8d72124e1c62d..941c8870ad844481684e4901969c43c6693bc39d 100644 (file)
--- a/docs/sidebars.js
+++ b/docs/sidebars.js
@@ -70,7 +70,8 @@ module.exports = {
                        'developers/plugins',
                        'developers/charts',
                        'developers/axes',
-                       'developers/contributing'
+                       'developers/contributing',
+                       'developers/publishing'
                ],
                'Additional Notes': [
                        'notes/comparison',

diff --git a/src/helpers/index.js b/src/helpers/index.js
index 143775bda553f8fc9345842ae1b880a90a1fba2f..cbe2e817be7de94c8c533ccd1fd1d6f6c3d8fe62 100644 (file)
--- a/src/helpers/index.js
+++ b/src/helpers/index.js
@@ -2,6 +2,7 @@
 
 import * as coreHelpers from './helpers.core';
 import * as canvas from './helpers.canvas';
+import * as collection from './helpers.collection';
 import * as curve from './helpers.curve';
 import * as dom from './helpers.dom';
 import effects from './helpers.easing';
@@ -15,6 +16,7 @@ import {requestAnimFrame, fontString} from './helpers.extras';
 export default {
        ...coreHelpers,
        canvas,
+       collection,
        curve,
        dom,
        easing: {effects},

diff --git a/src/index.js b/src/index.js
index ac3f0d39e7efe9a50f157d1ce33665bbf857260e..8d1bfce48dcd03af6e1c3f20c1a00eb1140f1bfc 100644 (file)
--- a/src/index.js
+++ b/src/index.js
@@ -9,7 +9,7 @@ import helpers from './helpers/index';
 import _adapters from './core/core.adapters';
 import Animation from './core/core.animation';
 import animator from './core/core.animator';
-import animationService from './core/core.animations';
+import Animations from './core/core.animations';
 import * as controllers from './controllers';
 import DatasetController from './core/core.datasetController';
 import Element from './core/core.element';
@@ -30,8 +30,8 @@ Chart.register(controllers, scales, elements, plugins);
 Chart.helpers = helpers;
 Chart._adapters = _adapters;
 Chart.Animation = Animation;
+Chart.Animations = Animations;
 Chart.animator = animator;
-Chart.animationService = animationService;
 Chart.controllers = registry.controllers.items;
 Chart.DatasetController = DatasetController;
 Chart.Element = Element;
@@ -39,10 +39,13 @@ Chart.elements = elements;
 Chart.Interaction = Interaction;
 Chart.layouts = layouts;
 Chart.platforms = platforms;
-Chart.registry = registry;
 Chart.Scale = Scale;
 Chart.Ticks = Ticks;
 
+// Compatibility with ESM extensions
+Object.assign(Chart, controllers, scales, elements, plugins, platforms);
+Chart.Chart = Chart;
+
 if (typeof window !== 'undefined') {
        // @ts-ignore
        window.Chart = Chart;

diff --git a/test/specs/global.namespace.tests.js b/test/specs/global.namespace.tests.js
index 577c751e2ab4f3536051a670baeaf30347174bc0..2c8c6bb423fc1631607172ca61fd6b23d2daabdc 100644 (file)
--- a/test/specs/global.namespace.tests.js
+++ b/test/specs/global.namespace.tests.js
@@ -6,7 +6,7 @@ describe('Chart namespace', function() {
                it('should define "core" properties', function() {
                        expect(Chart instanceof Function).toBeTruthy();
                        expect(Chart.Animation instanceof Object).toBeTruthy();
-                       expect(Chart.animationService instanceof Object).toBeTruthy();
+                       expect(Chart.Animations instanceof Object).toBeTruthy();
                        expect(Chart.defaults instanceof Object).toBeTruthy();
                        expect(Chart.Element instanceof Object).toBeTruthy();
                        expect(Chart.Interaction instanceof Object).toBeTruthy();