refactor: migrate helpers.options to typescript (#10753)

* refactor: migrate helpers.options to typescript

* chore: nitpicks

src/helpers/helpers.options.js → src/helpers/helpers.options.ts

@@ -1,23 +1,25 @@
 import defaults from '../core/core.defaults';
 import {isArray, isObject, toDimension, valueOrDefault} from './helpers.core';
-import {toFontString} from './helpers.canvas';
+import {Point, toFontString} from './helpers.canvas';
+import type {ChartArea, FontSpec} from '../../types';
+import type {TRBL, TRBLCorners} from '../../types/geometric';
 
-const LINE_HEIGHT = new RegExp(/^(normal|(\d+(?:\.\d+)?)(px|em|%)?)$/);
-const FONT_STYLE = new RegExp(/^(normal|italic|initial|inherit|unset|(oblique( -?[0-9]?[0-9]deg)?))$/);
+const LINE_HEIGHT = /^(normal|(\d+(?:\.\d+)?)(px|em|%)?)$/;
+const FONT_STYLE = /^(normal|italic|initial|inherit|unset|(oblique( -?[0-9]?[0-9]deg)?))$/;
 
 /**
  * @alias Chart.helpers.options
  * @namespace
  */
 /**
  * Converts the given line height `value` in pixels for a specific font `size`.
- * @param {number|string} value - The lineHeight to parse (eg. 1.6, '14px', '75%', '1.6em').
- * @param {number} size - The font size (in pixels) used to resolve relative `value`.
- * @returns {number} The effective line height in pixels (size * 1.2 if value is invalid).
+ * @param value - The lineHeight to parse (eg. 1.6, '14px', '75%', '1.6em').
+ * @param size - The font size (in pixels) used to resolve relative `value`.
+ * @returns The effective line height in pixels (size * 1.2 if value is invalid).
  * @see https://developer.mozilla.org/en-US/docs/Web/CSS/line-height
  * @since 2.7.0
  */
-export function toLineHeight(value, size) {
+export function toLineHeight(value: number | string, size: number): number {
   const matches = ('' + value).match(LINE_HEIGHT);
   if (!matches || matches[1] === 'normal') {
     return size * 1.2;
@@ -26,25 +28,27 @@ export function toLineHeight(value, size) {
   value = +matches[2];
 
   switch (matches[3]) {
-  case 'px':
-    return value;
-  case '%':
-    value /= 100;
-    break;
-  default:
-    break;
+    case 'px':
+      return value;
+    case '%':
+      value /= 100;
+      break;
+    default:
+      break;
   }
 
   return size * value;
 }
 
-const numberOrZero = v => +v || 0;
+const numberOrZero = (v: unknown) => +v || 0;
 
 /**
- * @param {any} value
- * @param {string[] | Record<string, string>} props
+ * @param value
+ * @param props
  */
-export function _readValueToProps(value, props) {
+export function _readValueToProps<K extends string>(value: number | Record<K, number>, props: K[]): Record<K, number>;
+export function _readValueToProps<K extends string, T extends string>(value: number | Record<K & T, number>, props: Record<T, K>): Record<T, number>;
+export function _readValueToProps(value: number | Record<string, number>, props: string[] | Record<string, string>) {
   const ret = {};
   const objProps = isObject(props);
   const keys = objProps ? Object.keys(props) : props;
@@ -62,55 +66,59 @@ export function _readValueToProps(value, props) {
 
 /**
  * Converts the given value into a TRBL object.
- * @param {number|object} value - If a number, set the value to all TRBL component,
+ * @param value - If a number, set the value to all TRBL component,
  *  else, if an object, use defined properties and sets undefined ones to 0.
  *  x / y are shorthands for same value for left/right and top/bottom.
- * @returns {object} The padding values (top, right, bottom, left)
+ * @returns The padding values (top, right, bottom, left)
  * @since 3.0.0
  */
-export function toTRBL(value) {
+export function toTRBL(value: number | TRBL | Point) {
   return _readValueToProps(value, {top: 'y', right: 'x', bottom: 'y', left: 'x'});
 }
 
 /**
  * Converts the given value into a TRBL corners object (similar with css border-radius).
- * @param {number|object} value - If a number, set the value to all TRBL corner components,
+ * @param value - If a number, set the value to all TRBL corner components,
  *  else, if an object, use defined properties and sets undefined ones to 0.
- * @returns {object} The TRBL corner values (topLeft, topRight, bottomLeft, bottomRight)
+ * @returns The TRBL corner values (topLeft, topRight, bottomLeft, bottomRight)
  * @since 3.0.0
  */
-export function toTRBLCorners(value) {
+export function toTRBLCorners(value: number | TRBLCorners) {
   return _readValueToProps(value, ['topLeft', 'topRight', 'bottomLeft', 'bottomRight']);
 }
 
 /**
  * Converts the given value into a padding object with pre-computed width/height.
- * @param {number|object} value - If a number, set the value to all TRBL component,
+ * @param value - If a number, set the value to all TRBL component,
  *  else, if an object, use defined properties and sets undefined ones to 0.
  *  x / y are shorthands for same value for left/right and top/bottom.
- * @returns {object} The padding values (top, right, bottom, left, width, height)
+ * @returns The padding values (top, right, bottom, left, width, height)
  * @since 2.7.0
  */
-export function toPadding(value) {
-  const obj = toTRBL(value);
+export function toPadding(value?: number | TRBL): ChartArea {
+  const obj = toTRBL(value) as ChartArea;
 
   obj.width = obj.left + obj.right;
   obj.height = obj.top + obj.bottom;
 
   return obj;
 }
 
+export interface CanvasFontSpec extends FontSpec {
+  string: string;
+}
 
 /**
  * Parses font options and returns the font object.
- * @param {object} options - A object that contains font options to be parsed.
- * @param {object} [fallback] - A object that contains fallback font options.
- * @return {object} The font object.
+ * @param options - A object that contains font options to be parsed.
+ * @param fallback - A object that contains fallback font options.
+ * @return The font object.
  * @private
  */
-export function toFont(options, fallback) {
+
+export function toFont(options: Partial<FontSpec>, fallback?: Partial<FontSpec>) {
   options = options || {};
-  fallback = fallback || defaults.font;
+  fallback = fallback || defaults.font as FontSpec;
 
   let size = valueOrDefault(options.size, fallback.size);
 
@@ -120,7 +128,7 @@ export function toFont(options, fallback) {
   let style = valueOrDefault(options.style, fallback.style);
   if (style && !('' + style).match(FONT_STYLE)) {
     console.warn('Invalid font style specified: "' + style + '"');
-    style = '';
+    style = undefined;
   }
 
   const font = {
@@ -138,18 +146,18 @@ export function toFont(options, fallback) {
 
 /**
  * Evaluates the given `inputs` sequentially and returns the first defined value.
- * @param {Array} inputs - An array of values, falling back to the last value.
- * @param {object} [context] - If defined and the current value is a function, the value
+ * @param inputs - An array of values, falling back to the last value.
+ * @param context - If defined and the current value is a function, the value
  * is called with `context` as first argument and the result becomes the new input.
- * @param {number} [index] - If defined and the current value is an array, the value
+ * @param index - If defined and the current value is an array, the value
  * at `index` become the new input.
- * @param {object} [info] - object to return information about resolution in
- * @param {boolean} [info.cacheable] - Will be set to `false` if option is not cacheable.
+ * @param info - object to return information about resolution in
+ * @param info.cacheable - Will be set to `false` if option is not cacheable.
  * @since 2.7.0
  */
-export function resolve(inputs, context, index, info) {
+export function resolve(inputs: Array<unknown>, context?: object, index?: number, info?: { cacheable: boolean }) {
   let cacheable = true;
-  let i, ilen, value;
+  let i: number, ilen: number, value: unknown;
 
   for (i = 0, ilen = inputs.length; i < ilen; ++i) {
     value = inputs[i];
@@ -174,15 +182,15 @@ export function resolve(inputs, context, index, info) {
 }
 
 /**
- * @param {{min: number, max: number}} minmax
- * @param {number|string} grace
- * @param {boolean} beginAtZero
+ * @param minmax
+ * @param grace
+ * @param beginAtZero
  * @private
  */
-export function _addGrace(minmax, grace, beginAtZero) {
+export function _addGrace(minmax: { min: number; max: number; }, grace: number | string, beginAtZero: boolean) {
   const {min, max} = minmax;
   const change = toDimension(grace, (max - min) / 2);
-  const keepZero = (value, add) => beginAtZero && value === 0 ? 0 : value + add;
+  const keepZero = (value: number, add: number) => beginAtZero && value === 0 ? 0 : value + add;
   return {
     min: keepZero(min, -Math.abs(change)),
     max: keepZero(max, change)
@@ -191,10 +199,10 @@ export function _addGrace(minmax, grace, beginAtZero) {
 
 /**
  * Create a context inheriting parentContext
- * @param {object|null} parentContext
- * @param {object} context
- * @returns {object}
+ * @param parentContext
+ * @param context
+ * @returns
  */
-export function createContext(parentContext, context) {
+export function createContext<P extends T, T extends object>(parentContext: P, context: T): P extends null ? T : P & T {
   return Object.assign(Object.create(parentContext), context);
 }

src/helpers/types.ts

@@ -14,5 +14,6 @@ export * from './helpers.extras';
 export * from './helpers.interpolation';
 export * from './helpers.intl';
 export * from './helpers.math';
+export * from './helpers.options';
 export * from './helpers.rtl';
 export * from '../../types/helpers';

types/helpers/helpers.canvas.d.ts

@@ -1,7 +1,7 @@
 import { PointStyle } from '..';
 import { Color } from '../color';
 import { ChartArea, RoundedRect } from '../geometric';
-import { CanvasFontSpec } from './helpers.options';
+import { CanvasFontSpec } from '../../src/helpers/helpers.options';
 
 export function clearCanvas(canvas: HTMLCanvasElement, ctx?: CanvasRenderingContext2D): void;
 

types/helpers/index.d.ts

@@ -1,4 +1,3 @@
 export * from './helpers.canvas';
-export * from './helpers.options';
 export * from './helpers.canvas';
 export * from './helpers.segment';

types/tests/helpers/options.ts

@@ -1,4 +1,4 @@
-import { createContext } from '../../helpers/helpers.options';
+import { createContext } from '../../../src/helpers/helpers.options';
 
 const context1 = createContext(null, { type: 'test1', parent: true });
 const context2 = createContext(context1, { type: 'test2' });