flat helpers (chartjs#7806)

* generate a flat helpers package
* move helpers built files to dist
* upgrade docs for flat helpers

Author: sgratzl

.gitignore

@@ -3,7 +3,6 @@
 /custom
 /dist
 /gh-pages
-/helpers
 
 # Node.js
 node_modules/

docs/docs/developers/publishing.md

@@ -20,12 +20,19 @@ 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.
+For example `import {isNullOrUndef} from 'chart.js/helpers'` 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).
+```js
+{
+    output: {
+        globals: {
+            'chart.js': 'Chart',
+            'chart.js/helpers': 'Chart.helpers'
+        }
+    }
+}
+```

docs/docs/getting-started/v3-migration.md

@@ -306,9 +306,9 @@ The following properties and methods were removed:
 * `helpers.getValueAtIndexOrDefault`. Use `helpers.resolve` instead.
 * `helpers.indexOf`
 * `helpers.lineTo`
-* `helpers.longestText` was moved to the `helpers.canvas` namespace and made private
+* `helpers.longestText` was made private
 * `helpers.max`
-* `helpers.measureText` was moved to the `helpers.canvas` namespace and made private
+* `helpers.measureText` was made private
 * `helpers.min`
 * `helpers.nextItem`
 * `helpers.niceNum`
@@ -369,29 +369,12 @@ The following properties were renamed during v3 development:
 
 * `Chart.Animation.animationObject` was renamed to `Chart.Animation`
 * `Chart.Animation.chartInstance` was renamed to `Chart.Animation.chart`
-* `Chart.canvasHelpers` was renamed to `Chart.helpers.canvas`
+* `Chart.canvasHelpers` was merged with `Chart.helpers`
 * `Chart.layoutService` was renamed to `Chart.layouts`
 * `Chart.pluginService` was renamed to `Chart.plugins`
-* `helpers._decimalPlaces` was renamed to `helpers.math._decimalPlaces`
-* `helpers.almostEquals` was renamed to `helpers.math.almostEquals`
-* `helpers.almostWhole` was renamed to `helpers.math.almostWhole`
 * `helpers.callCallback` was renamed to `helpers.callback`
-* `helpers.clear` was renamed to `helpers.canvas.clear`
-* `helpers.distanceBetweenPoints` was renamed to `helpers.math.distanceBetweenPoints`
-* `helpers.drawRoundedRectangle` was renamed to `helpers.canvas.roundedRect`
-* `helpers.getAngleFromPoint` was renamed to `helpers.math.getAngleFromPoint`
-* `helpers.getRelativePosition` was renamed to `helpers.dom.getRelativePosition`
-* `helpers.getStyle` was renamed to `helpers.dom.getStyle`
+* `helpers.drawRoundedRectangle` was renamed to `helpers.roundedRect`
 * `helpers.getValueOrDefault` was renamed to `helpers.valueOrDefault`
-* `helpers.easingEffects` was renamed to `helpers.easing.effects`
-* `helpers.log10` was renamed to `helpers.math.log10`
-* `helpers.isNumber` was renamed to `helpers.math.isNumber`
-* `helpers.sign` was renamed to `helpers.math.sign`
-* `helpers.retinaScale` was renamed to `helpers.dom.retinaScale`
-* `helpers.splineCurve` was renamed to `helpers.curve.splineCurve`
-* `helpers.splineCurveMonotone` was renamed to `helpers.curve.splineCurveMonotone`
-* `helpers.toDegrees` was renamed to `helpers.math.toDegrees`
-* `helpers.toRadians` was renamed to `helpers.math.toRadians`
 * `Scale.calculateTickRotation` was renamed to `Scale.calculateLabelRotation`
 * `Tooltip.options.legendColorBackgroupd` was renamed to `Tooltip.options.multiKeyBackground`
 
@@ -426,8 +409,6 @@ The private APIs listed below were renamed:
 * `DatasetController.resyncElements` was renamed to `DatasetController._resyncElements`
 * `RadialLinearScale.setReductions` was renamed to `RadialLinearScale._setReductions`
 * `Scale.handleMargins` was renamed to `Scale._handleMargins`
-* `helpers._alignPixel` was renamed to `helpers.canvas._alignPixel`
-* `helpers._decimalPlaces` was renamed to `helpers.math._decimalPlaces`
 
 ### Changed
 
@@ -472,6 +453,8 @@ The APIs listed in this section have changed in signature or behaviour from vers
 
 #### Helpers
 
+All helpers are now exposed in a flat hierarchy, e.g., `Chart.helpers.canvas.clipArea` -> `Chart.helpers.clipArea`
+
 ##### Canvas Helper
 
 * The second parameter to `drawPoint` is now the full options object, so `style`, `rotation`, and `radius` are no longer passed explicitly

helpers/helpers.esm.d.ts

@@ -0,0 +1 @@
+export * from '../dist/helpers.esm';

helpers/helpers.esm.js

@@ -0,0 +1 @@
+export * from '../dist/helpers.esm';

helpers/helpers.js

@@ -0,0 +1 @@
+module.exports = require('..').helpers;

helpers/package.json

@@ -0,0 +1,8 @@
+{
+    "name": "chart.js-helpers",
+    "private": true,
+    "description": "helper package",
+    "main": "helpers.js",
+    "module": "helpers.esm.js",
+    "types": "helpers.esm.d.ts"
+}

rollup.config.js

@@ -4,7 +4,6 @@
 const babel = require('rollup-plugin-babel');
 const cleanup = require('rollup-plugin-cleanup');
 const dts = require('rollup-plugin-dts').default;
-const glob = require('glob');
 const inject = require('@rollup/plugin-inject');
 const json = require('@rollup/plugin-json');
 const resolve = require('@rollup/plugin-node-resolve').default;
@@ -14,16 +13,12 @@ const pkg = require('./package.json');
 const input = 'src/index.js';
 const inputESM = {
 	'dist/chart.esm': 'src/index.esm.js',
+	'dist/helpers.esm': 'src/helpers/index.js'
+};
+const inputESMTypings = {
+	'dist/chart.esm': 'types/index.esm.d.ts',
+	'dist/helpers.esm': 'types/helpers/index.d.ts'
 };
-const inputESMTypings = {};
-glob('src/helpers/helpers.*.js', (_er, files) => {
-	files.forEach(file => {
-		inputESM[file.replace(/src\/|helpers\.|\.js/g, '')] = file;
-	});
-	Object.keys(inputESM).forEach((key) => {
-		inputESMTypings[key.replace('src', 'types')] = inputESM[key].replace('src', 'types').replace(/\.js$/, '.d.ts');
-	});
-});
 
 const banner = `/*!
  * Chart.js v${pkg.version}
@@ -96,7 +91,7 @@ module.exports = [
 		],
 		output: {
 			dir: './',
-			chunkFileNames: 'helpers/chunks/[name].js',
+			chunkFileNames: 'dist/chunks/[name].js',
 			banner,
 			format: 'esm',
 			indent: false,
@@ -112,7 +107,7 @@ module.exports = [
 		],
 		output: {
 			dir: './',
-			chunkFileNames: 'helpers/chunks/[name].ts',
+			chunkFileNames: 'dist/chunks/[name].ts',
 			banner,
 			format: 'esm',
 			indent: false,

src/helpers/index.js

@@ -1,36 +1,16 @@
 /* eslint-disable import/no-namespace */
 
-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';
-import * as interpolation from './helpers.interpolation';
-import * as options from './helpers.options';
-import * as math from './helpers.math';
-import * as rtl from './helpers.rtl';
-import * as segment from './helpers.segment';
+export * from './helpers.core';
+export * from './helpers.canvas';
+export * from './helpers.collection';
+export * from './helpers.curve';
+export * from './helpers.dom';
+export {default as easingEffects} from './helpers.easing';
+export * from './helpers.interpolation';
+export * from './helpers.options';
+export * from './helpers.math';
+export * from './helpers.rtl';
+export * from './helpers.segment';
 
-import {color, getHoverColor} from './helpers.color';
-import {requestAnimFrame, fontString} from './helpers.extras';
-
-export default {
-	...coreHelpers,
-	canvas,
-	collection,
-	curve,
-	dom,
-	easing: {effects},
-	interpolation,
-	options,
-	math,
-	rtl,
-	segment,
-
-	requestAnimFrame,
-	// -- Canvas methods
-	fontString,
-	color,
-	getHoverColor
-};
+export {color, getHoverColor} from './helpers.color';
+export {requestAnimFrame, fontString} from './helpers.extras';

src/index.js

@@ -6,7 +6,7 @@
  */
 import Chart from './core/core.controller';
 
-import helpers from './helpers/index';
+import * as helpers from './helpers/index';
 import _adapters from './core/core.adapters';
 import Animation from './core/core.animation';
 import animator from './core/core.animator';
@@ -27,7 +27,7 @@ import Ticks from './core/core.ticks';
 // Register built-ins
 Chart.register(controllers, scales, elements, plugins);
 
-Chart.helpers = helpers;
+Chart.helpers = {...helpers};
 Chart._adapters = _adapters;
 Chart.Animation = Animation;
 Chart.Animations = Animations;

test/specs/helpers.canvas.tests.js

@@ -1,7 +1,7 @@
 'use strict';
 
 describe('Chart.helpers.canvas', function() {
-	describe('auto', jasmine.fixture.specs('helpers.canvas'));
+	describe('auto', jasmine.fixture.specs('helpers'));
 
 	var helpers = Chart.helpers;
 
@@ -15,7 +15,7 @@ describe('Chart.helpers.canvas', function() {
 
 			spyOn(chart.ctx, 'clearRect');
 
-			helpers.canvas.clear(chart);
+			helpers.clear(chart);
 
 			expect(chart.ctx.clearRect.calls.count()).toBe(1);
 			expect(chart.ctx.clearRect.calls.first().object).toBe(chart.ctx);
@@ -25,7 +25,7 @@ describe('Chart.helpers.canvas', function() {
 
 	describe('isPointInArea', function() {
 		it('should determine if a point is in the area', function() {
-			var isPointInArea = helpers.canvas._isPointInArea;
+			var isPointInArea = helpers._isPointInArea;
 			var area = {left: 0, top: 0, right: 512, bottom: 256};
 
 			expect(isPointInArea({x: 0, y: 0}, area)).toBe(true);
@@ -45,8 +45,8 @@ describe('Chart.helpers.canvas', function() {
 
 
 		// Regardless 'FooBar' is the longest label it should return (characters * 10)
-		expect(helpers.canvas._longestText(context, font, arrayOfThings1D, {})).toEqual(60);
-		expect(helpers.canvas._longestText(context, font, arrayOfThings2D, {})).toEqual(80);
+		expect(helpers._longestText(context, font, arrayOfThings1D, {})).toEqual(60);
+		expect(helpers._longestText(context, font, arrayOfThings2D, {})).toEqual(80);
 		// We check to make sure we made the right calls to the canvas.
 		expect(context.getCalls()).toEqual([{
 			name: 'save',
@@ -84,9 +84,9 @@ describe('Chart.helpers.canvas', function() {
 		var gc = [];
 		var longest = 70;
 
-		expect(helpers.canvas._measureText(context, data, gc, longest, 'foobar')).toEqual(70);
-		expect(helpers.canvas._measureText(context, data, gc, longest, 'foobar_')).toEqual(70);
-		expect(helpers.canvas._measureText(context, data, gc, longest, 'foobar_1')).toEqual(80);
+		expect(helpers._measureText(context, data, gc, longest, 'foobar')).toEqual(70);
+		expect(helpers._measureText(context, data, gc, longest, 'foobar_')).toEqual(70);
+		expect(helpers._measureText(context, data, gc, longest, 'foobar_1')).toEqual(80);
 		// We check to make sure we made the right calls to the canvas.
 		expect(context.getCalls()).toEqual([{
 			name: 'measureText',

test/specs/helpers.collection.tests.js

@@ -1,4 +1,4 @@
-const {_filterBetween, _lookup, _lookupByKey, _rlookupByKey} = Chart.helpers.collection;
+const {_filterBetween, _lookup, _lookupByKey, _rlookupByKey} = Chart.helpers;
 
 describe('helpers.collection', function() {
 	it('Should do binary search', function() {

test/specs/helpers.curve.tests.js

@@ -2,7 +2,7 @@ describe('Curve helper tests', function() {
 	let helpers;
 
 	beforeAll(function() {
-		helpers = window.Chart.helpers.curve;
+		helpers = window.Chart.helpers;
 	});
 
 	it('should spline curves', function() {

test/specs/helpers.dom.tests.js

@@ -2,7 +2,7 @@ describe('DOM helpers tests', function() {
 	let helpers;
 
 	beforeAll(function() {
-		helpers = window.Chart.helpers.dom;
+		helpers = window.Chart.helpers;
 	});
 
 	it ('should get the maximum size for a node', function() {

test/specs/helpers.easing.tests.js

@@ -1,7 +1,7 @@
 'use strict';
 
-describe('Chart.helpers.easing', function() {
-	var easing = Chart.helpers.easing;
+describe('Chart.helpers.easingEffects', function() {
+	var helpers = Chart.helpers;
 
 	describe('effects', function() {
 		var expected = {
@@ -39,7 +39,7 @@ describe('Chart.helpers.easing', function() {
 		};
 
 		function generate(method) {
-			var fn = easing.effects[method];
+			var fn = helpers.easingEffects[method];
 			var accuracy = Math.pow(10, 8);
 			var count = 10;
 			var values = [];
@@ -52,7 +52,7 @@ describe('Chart.helpers.easing', function() {
 			return values;
 		}
 
-		Object.keys(easing.effects).forEach(function(method) {
+		Object.keys(helpers.easingEffects).forEach(function(method) {
 			it ('"' + method + '" should return expected values', function() {
 				expect(generate(method)).toEqual(expected[method]);
 			});

test/specs/helpers.interpolation.tests.js

@@ -1,4 +1,4 @@
-const {_pointInLine, _steppedInterpolation, _bezierInterpolation} = Chart.helpers.interpolation;
+const {_pointInLine, _steppedInterpolation, _bezierInterpolation} = Chart.helpers;
 
 describe('helpers.interpolation', function() {
 	it('Should interpolate a point in line', function() {

test/specs/helpers.math.tests.js

@@ -1,4 +1,4 @@
-const math = Chart.helpers.math;
+const math = Chart.helpers;
 
 describe('Chart.helpers.math', function() {
 	var factorize = math._factorize;

test/specs/helpers.options.tests.js

@@ -1,4 +1,4 @@
-const {toLineHeight, toPadding, toFont, resolve} = Chart.helpers.options; // from '../../src/helpers/helpers.options';
+const {toLineHeight, toPadding, toFont, resolve} = Chart.helpers; // from '../../src/helpers/helpers.options';
 
 describe('Chart.helpers.options', function() {
 	describe('toLineHeight', function() {

test/specs/helpers.segment.tests.js

@@ -1,4 +1,4 @@
-const {_boundSegment} = Chart.helpers.segment;
+const {_boundSegment} = Chart.helpers;
 
 describe('helpers.segments', function() {
 	describe('_boundSegment', function() {

types/helpers/helpers.easing.d.ts

@@ -2,4 +2,4 @@ import { EasingFunction } from '../core/interfaces';
 
 export type EasingFunctionSignature = (t: number) => number;
 
-export const easing: Record<EasingFunction, EasingFunctionSignature>;
+export const easingEffects: Record<EasingFunction, EasingFunctionSignature>;