From 9c27f748018f54bc3148318150face1f3800209b Mon Sep 17 00:00:00 2001 From: Jukka Kurkela Date: Mon, 3 Aug 2020 19:33:41 +0300 Subject: [PATCH] Export extensible classes in ESM compatible way (#7650) * Export extensible classes in ESM compatible way * Export collection helperrs * Remove reduntant registry assignment --- docs/docs/developers/axes.md | 4 +-- docs/docs/developers/charts.md | 31 +++++++++++++---------- docs/docs/developers/publishing.md | 31 +++++++++++++++++++++++ docs/docs/getting-started/v3-migration.md | 1 + docs/sidebars.js | 3 ++- src/helpers/index.js | 2 ++ src/index.js | 9 ++++--- test/specs/global.namespace.tests.js | 2 +- 8 files changed, 63 insertions(+), 20 deletions(-) create mode 100644 docs/docs/developers/publishing.md diff --git a/docs/docs/developers/axes.md b/docs/docs/developers/axes.md index 474dbd089..e28f937c8 100644 --- 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 05ab8025a..385132b8e 100644 --- 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 index 000000000..6c419f879 --- /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 f45c42d06..15ffddc0a 100644 --- 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 d19eb365a..941c8870a 100644 --- 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 143775bda..cbe2e817b 100644 --- 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 ac3f0d39e..8d1bfce48 100644 --- 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 577c751e2..2c8c6bb42 100644 --- 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(); -- 2.47.2