@highcharts/dashboards
Version:
Highcharts Dashboards framework
771 lines (770 loc) • 25.7 kB
TypeScript
import type AxisType from './Axis/AxisType';
import type Chart from './Chart/Chart';
import type CSSObject from './Renderer/CSSObject';
import type { DeepPartial } from '../Shared/Types';
import type { DOMElementType, HTMLDOMElement } from './Renderer/DOMElementType';
import type EventCallback from './EventCallback';
import type HTMLAttributes from './Renderer/HTML/HTMLAttributes';
import type Series from './Series/Series';
import type SVGAttributes from './Renderer/SVG/SVGAttributes';
import type Time from './Time';
import type Types from '../Shared/Types';
type NonArray<T> = T extends Array<unknown> ? never : T;
type NonFunction<T> = T extends Function ? never : T;
type NullType = (null | undefined);
/**
* Provide error messages for debugging, with links to online explanation. This
* function can be overridden to provide custom error handling.
*
* @sample highcharts/chart/highcharts-error/
* Custom error handler
*
* @function Highcharts.error
*
* @param {number|string} code
* The error code. See
* [errors.xml](https://github.com/highcharts/highcharts/blob/master/errors/errors.xml)
* for available codes. If it is a string, the error message is printed
* directly in the console.
*
* @param {boolean} [stop=false]
* Whether to throw an error or just log a warning in the console.
*
* @param {Highcharts.Chart} [chart]
* Reference to the chart that causes the error. Used in 'debugger'
* module to display errors directly on the chart.
* Important note: This argument is undefined for errors that lack
* access to the Chart instance. In such case, the error will be
* displayed on the last created chart.
*
* @param {Highcharts.Dictionary<string>} [params]
* Additional parameters for the generated message.
*
* @return {void}
*/
declare function error(code: (number | string), stop?: boolean, chart?: Chart, params?: Record<string, string>): void;
declare namespace error {
const messages: Array<string>;
}
declare function merge<T = object>(extend: true, a?: T, ...n: Array<DeepPartial<T> | undefined>): (T);
declare function merge<T1 extends object = object, T2 = unknown, T3 = unknown, T4 = unknown, T5 = unknown, T6 = unknown, T7 = unknown, T8 = unknown, T9 = unknown>(a?: T1, b?: T2, c?: T3, d?: T4, e?: T5, f?: T6, g?: T7, h?: T8, i?: T9): (T1 & T2 & T3 & T4 & T5 & T6 & T7 & T8 & T9);
/**
* Constrain a value to within a lower and upper threshold.
*
* @private
* @param {number} value The initial value
* @param {number} min The lower threshold
* @param {number} max The upper threshold
* @return {number} Returns a number value within min and max.
*/
declare function clamp(value: number, min: number, max: number): number;
/**
* Utility for crisping a line position to the nearest full pixel depening on
* the line width
* @param {number} value The raw pixel position
* @param {number} lineWidth The line width
* @param {boolean} [inverted] Whether the containing group is inverted.
* Crisping round numbers on the y-scale need to go
* to the other side because the coordinate system
* is flipped (scaleY is -1)
* @return {number} The pixel position to use for a crisp display
*/
declare function crisp(value: number, lineWidth?: number, inverted?: boolean): number;
/**
* Return the deep difference between two objects. It can either return the new
* properties, or optionally return the old values of new properties.
* @private
*/
declare function diffObjects(newer: AnyRecord, older: AnyRecord, keepOlder?: boolean, collectionsWithUpdate?: string[]): AnyRecord;
/**
* Shortcut for parseInt
*
* @private
* @function Highcharts.pInt
*
* @param {*} s
* any
*
* @param {number} [mag]
* Magnitude
*
* @return {number}
* number
*/
declare function pInt(s: any, mag?: number): number;
/**
* Utility function to check for string type.
*
* @function Highcharts.isString
*
* @param {*} s
* The item to check.
*
* @return {boolean}
* True if the argument is a string.
*/
declare function isString(s: unknown): s is string;
/**
* Utility function to check if an item is an array.
*
* @function Highcharts.isArray
*
* @param {*} obj
* The item to check.
*
* @return {boolean}
* True if the argument is an array.
*/
declare function isArray(obj: unknown): obj is Array<unknown>;
declare function isObject<T>(obj: T, strict: true): obj is object & NonArray<NonFunction<NonNullable<T>>>;
declare function isObject<T>(obj: T, strict?: false): obj is object & NonFunction<NonNullable<T>>;
/**
* Utility function to check if an Object is a HTML Element.
*
* @function Highcharts.isDOMElement
*
* @param {*} obj
* The item to check.
*
* @return {boolean}
* True if the argument is a HTML Element.
*/
declare function isDOMElement(obj: unknown): obj is HTMLDOMElement;
/**
* Utility function to check if an Object is a class.
*
* @function Highcharts.isClass
*
* @param {object|undefined} obj
* The item to check.
*
* @return {boolean}
* True if the argument is a class.
*/
declare function isClass<T>(obj: (object | undefined)): obj is Class<T>;
/**
* Utility function to check if an item is a number and it is finite (not NaN,
* Infinity or -Infinity).
*
* @function Highcharts.isNumber
*
* @param {*} n
* The item to check.
*
* @return {boolean}
* True if the item is a finite number
*/
declare function isNumber(n: unknown): n is number;
/**
* Remove the last occurence of an item from an array.
*
* @function Highcharts.erase
*
* @param {Array<*>} arr
* The array.
*
* @param {*} item
* The item to remove.
*
* @return {void}
*/
declare function erase(arr: Array<unknown>, item: unknown): void;
/**
* Insert a series or an axis in a collection with other items, either the
* chart series or yAxis series or axis collections, in the correct order
* according to the index option and whether it is internal. Used internally
* when adding series and axes.
*
* @private
* @function Highcharts.Chart#insertItem
* @param {Highcharts.Series|Highcharts.Axis} item
* The item to insert
* @param {Array<Highcharts.Series>|Array<Highcharts.Axis>} collection
* A collection of items, like `chart.series` or `xAxis.series`.
* @return {number} The index of the series in the collection.
*/
declare function insertItem(item: Series | AxisType, collection: Array<Series | AxisType>): number;
/**
* Adds an item to an array, if it is not present in the array.
*
* @function Highcharts.pushUnique
*
* @param {Array<unknown>} array
* The array to add the item to.
*
* @param {unknown} item
* The item to add.
*
* @return {boolean}
* Returns true, if the item was not present and has been added.
*/
declare function pushUnique(array: Array<unknown>, item: unknown): boolean;
/**
* Check if an object is null or undefined.
*
* @function Highcharts.defined
*
* @param {*} obj
* The object to check.
*
* @return {boolean}
* False if the object is null or undefined, otherwise true.
*/
declare function defined<T>(obj: T): obj is NonNullable<T>;
declare function attr(elem: DOMElementType, prop: (HTMLAttributes | SVGAttributes)): undefined;
declare function attr(elem: DOMElementType, prop: string, value?: undefined): (string | null);
declare function attr(elem: DOMElementType, prop: string, value: (number | string)): undefined;
/**
* Check if an element is an array, and if not, make it into an array.
*
* @function Highcharts.splat
*
* @param {*} obj
* The object to splat.
*
* @return {Array}
* The produced or original array.
*/
declare function splat<T>(obj: T | Array<T>): Array<T>;
/**
* Set a timeout if the delay is given, otherwise perform the function
* synchronously.
*
* @function Highcharts.syncTimeout
*
* @param {Function} fn
* The function callback.
*
* @param {number} delay
* Delay in milliseconds.
*
* @param {*} [context]
* An optional context to send to the function callback.
*
* @return {number}
* An identifier for the timeout that can later be cleared with
* Highcharts.clearTimeout. Returns -1 if there is no timeout.
*/
declare function syncTimeout(fn: Function, delay: number, context?: unknown): number;
/**
* Internal clear timeout. The function checks that the `id` was not removed
* (e.g. by `chart.destroy()`). For the details see
* [issue #7901](https://github.com/highcharts/highcharts/issues/7901).
*
* @function Highcharts.clearTimeout
*
* @param {number|undefined} id
* Id of a timeout.
*/
declare function internalClearTimeout(id: (number | undefined)): void;
/**
* Utility function to extend an object with the members of another.
*
* @function Highcharts.extend<T>
*
* @param {T|undefined} a
* The object to be extended.
*
* @param {Partial<T>} b
* The object to add to the first one.
*
* @return {T}
* Object a, the original object.
*/
declare function extend<T extends object>(a: (T | undefined), b: Partial<T>): T;
declare function pick<T1, T2, T3, T4, T5>(...args: [T1, T2, T3, T4, T5]): T1 extends NullType ? T2 extends NullType ? T3 extends NullType ? T4 extends NullType ? T5 extends NullType ? undefined : T5 : T4 : T3 : T2 : T1;
declare function pick<T1, T2, T3, T4>(...args: [T1, T2, T3, T4]): T1 extends NullType ? T2 extends NullType ? T3 extends NullType ? T4 extends NullType ? undefined : T4 : T3 : T2 : T1;
declare function pick<T1, T2, T3>(...args: [T1, T2, T3]): T1 extends NullType ? T2 extends NullType ? T3 extends NullType ? undefined : T3 : T2 : T1;
declare function pick<T1, T2>(...args: [T1, T2]): T1 extends NullType ? T2 extends NullType ? undefined : T2 : T1;
declare function pick<T1>(...args: [T1]): T1 extends NullType ? undefined : T1;
declare function pick<T>(...args: Array<T | null | undefined>): T | undefined;
/**
* Set CSS on a given element.
*
* @function Highcharts.css
*
* @param {Highcharts.HTMLDOMElement|Highcharts.SVGDOMElement} el
* An HTML DOM element.
*
* @param {Highcharts.CSSObject} styles
* Style object with camel case property names.
*
* @return {void}
*/
declare function css(el: DOMElementType, styles: CSSObject): void;
/**
* Utility function to create an HTML element with attributes and styles.
*
* @function Highcharts.createElement
*
* @param {string} tag
* The HTML tag.
*
* @param {Highcharts.HTMLAttributes} [attribs]
* Attributes as an object of key-value pairs.
*
* @param {Highcharts.CSSObject} [styles]
* Styles as an object of key-value pairs.
*
* @param {Highcharts.HTMLDOMElement} [parent]
* The parent HTML object.
*
* @param {boolean} [nopad=false]
* If true, remove all padding, border and margin.
*
* @return {Highcharts.HTMLDOMElement}
* The created DOM element.
*/
declare function createElement(tag: string, attribs?: HTMLAttributes, styles?: CSSObject, parent?: HTMLDOMElement, nopad?: boolean): HTMLDOMElement;
/**
* Extend a prototyped class by new members.
*
* @deprecated
* @function Highcharts.extendClass<T>
*
* @param {Highcharts.Class<T>} parent
* The parent prototype to inherit.
*
* @param {Highcharts.Dictionary<*>} members
* A collection of prototype members to add or override compared to the
* parent prototype.
*
* @return {Highcharts.Class<T>}
* A new prototype.
*/
declare function extendClass<T, TReturn = T>(parent: Class<T>, members: any): Class<TReturn>;
/**
* Left-pad a string to a given length by adding a character repetitively.
*
* @function Highcharts.pad
*
* @param {number} number
* The input string or number.
*
* @param {number} [length]
* The desired string length.
*
* @param {string} [padder=0]
* The character to pad with.
*
* @return {string}
* The padded string.
*/
declare function pad(number: number, length?: number, padder?: string): string;
/**
* Return a length based on either the integer value, or a percentage of a base.
*
* @function Highcharts.relativeLength
*
* @param {Highcharts.RelativeSize} value
* A percentage string or a number.
*
* @param {number} base
* The full length that represents 100%.
*
* @param {number} [offset=0]
* A pixel offset to apply for percentage values. Used internally in
* axis positioning.
*
* @return {number}
* The computed length.
*/
declare function relativeLength(value: Utilities.RelativeSize, base: number, offset?: number): number;
/**
* Replaces text in a string with a given replacement in a loop to catch nested
* matches after previous replacements.
*
* @function Highcharts.replaceNested
*
* @param {string} text
* Text to search and modify.
*
* @param {...Array<(RegExp|string)>} replacements
* One or multiple tuples with search pattern (`[0]: (string|RegExp)`) and
* replacement (`[1]: string`) for matching text.
*
* @return {string}
* Text with replacements.
*/
declare function replaceNested(text: string, ...replacements: Array<[pattern: (string | RegExp), replacement: string]>): string;
/**
* Wrap a method with extended functionality, preserving the original function.
*
* @function Highcharts.wrap
*
* @param {*} obj
* The context object that the method belongs to. In real cases, this is
* often a prototype.
*
* @param {string} method
* The name of the method to extend.
*
* @param {Highcharts.WrapProceedFunction} func
* A wrapper function callback. This function is called with the same
* arguments as the original function, except that the original function
* is unshifted and passed as the first argument.
*/
declare function wrap<T, K extends FunctionNamesOf<T>>(obj: T, method: K, func: Utilities.WrapProceedFunction<T[K] & ArrowFunction>): void;
/**
* Get the magnitude of a number.
*
* @function Highcharts.getMagnitude
*
* @param {number} num
* The number.
*
* @return {number}
* The magnitude, where 1-9 are magnitude 1, 10-99 magnitude 2 etc.
*/
declare function getMagnitude(num: number): number;
/**
* Take an interval and normalize it to multiples of round numbers.
*
* @deprecated
* @function Highcharts.normalizeTickInterval
*
* @param {number} interval
* The raw, un-rounded interval.
*
* @param {Array<*>} [multiples]
* Allowed multiples.
*
* @param {number} [magnitude]
* The magnitude of the number.
*
* @param {boolean} [allowDecimals]
* Whether to allow decimals.
*
* @param {boolean} [hasTickAmount]
* If it has tickAmount, avoid landing on tick intervals lower than
* original.
*
* @return {number}
* The normalized interval.
*
* @todo
* Move this function to the Axis prototype. It is here only for historical
* reasons.
*/
declare function normalizeTickInterval(interval: number, multiples?: Array<number>, magnitude?: number, allowDecimals?: boolean, hasTickAmount?: boolean): number;
/**
* Sort an object array and keep the order of equal items. The ECMAScript
* standard does not specify the behaviour when items are equal.
*
* @function Highcharts.stableSort
*
* @param {Array<*>} arr
* The array to sort.
*
* @param {Function} sortFunction
* The function to sort it with, like with regular Array.prototype.sort.
*/
declare function stableSort<T>(arr: Array<T>, sortFunction: (a: T, b: T) => number): void;
/**
* Non-recursive method to find the lowest member of an array. `Math.min` raises
* a maximum call stack size exceeded error in Chrome when trying to apply more
* than 150.000 points. This method is slightly slower, but safe.
*
* @function Highcharts.arrayMin
*
* @param {Array<*>} data
* An array of numbers.
*
* @return {number}
* The lowest number.
*/
declare function arrayMin(data: Array<any> | Types.TypedArray): number;
/**
* Non-recursive method to find the lowest member of an array. `Math.max` raises
* a maximum call stack size exceeded error in Chrome when trying to apply more
* than 150.000 points. This method is slightly slower, but safe.
*
* @function Highcharts.arrayMax
*
* @param {Array<*>} data
* An array of numbers.
*
* @return {number}
* The highest number.
*/
declare function arrayMax(data: Array<any> | Types.TypedArray): number;
/**
* Utility method that destroys any SVGElement instances that are properties on
* the given object. It loops all properties and invokes destroy if there is a
* destroy method. The property is then delete.
*
* @function Highcharts.destroyObjectProperties
*
* @param {*} obj
* The object to destroy properties on.
*
* @param {*} [except]
* Exception, do not destroy this property, only delete it.
*/
declare function destroyObjectProperties(obj: any, except?: any, destructablesOnly?: boolean): void;
/**
* Discard a HTML element
*
* @function Highcharts.discardElement
*
* @param {Highcharts.HTMLDOMElement} element
* The HTML node to discard.
*/
declare function discardElement(element?: HTMLDOMElement): void;
/**
* Fix JS round off float errors.
*
* @function Highcharts.correctFloat
*
* @param {number} num
* A float number to fix.
*
* @param {number} [prec=14]
* The precision.
*
* @return {number}
* The corrected float number.
*/
declare function correctFloat(num: number, prec?: number): number;
/**
* Find the closest distance between two values of a two-dimensional array
* @private
* @function Highcharts.getClosestDistance
*
* @param {Array<Array<number>>} arrays
* An array of arrays of numbers
*
* @return {number | undefined}
* The closest distance between values
*/
declare function getClosestDistance(arrays: (number[] | Types.TypedArray)[], onError?: Function): (number | undefined);
/**
* Returns the value of a property path on a given object.
*
* @private
* @function getNestedProperty
*
* @param {string} path
* Path to the property, for example `custom.myValue`.
*
* @param {unknown} obj
* Instance containing the property on the specific path.
*
* @return {unknown}
* The unknown property value.
*/
declare function getNestedProperty(path: string, parent: unknown): unknown;
declare function getStyle(el: HTMLDOMElement, prop: string, toInt: true): (number | undefined);
declare function getStyle(el: HTMLDOMElement, prop: string, toInt?: false): (number | string | undefined);
/**
* Get the element's offset position, corrected for `overflow: auto`.
*
* @function Highcharts.offset
*
* @param {global.Element} el
* The DOM element.
*
* @return {Highcharts.OffsetObject}
* An object containing `left` and `top` properties for the position in
* the page.
*/
declare function offset(el: Element): Utilities.OffsetObject;
/**
* Iterate over object key pairs in an object.
*
* @function Highcharts.objectEach<T>
*
* @param {*} obj
* The object to iterate over.
*
* @param {Highcharts.ObjectEachCallbackFunction<T>} fn
* The iterator callback. It passes three arguments:
* * value - The property value.
* * key - The property key.
* * obj - The object that objectEach is being applied to.
*
* @param {T} [ctx]
* The context.
*/
declare function objectEach<TObject, TContext>(obj: TObject, fn: Utilities.ObjectEachCallback<TObject, TContext>, ctx?: TContext): void;
/**
* Add an event listener.
*
* @function Highcharts.addEvent<T>
*
* @param {Highcharts.Class<T>|T} el
* The element or object to add a listener to. It can be a
* {@link HTMLDOMElement}, an {@link SVGElement} or any other object.
*
* @param {string} type
* The event type.
*
* @param {Highcharts.EventCallbackFunction<T>|Function} fn
* The function callback to execute when the event is fired.
*
* @param {Highcharts.EventOptionsObject} [options]
* Options for adding the event.
*
* @sample highcharts/members/addevent
* Use a general `render` event to draw shapes on a chart
*
* @return {Function}
* A callback function to remove the added event.
*/
declare function addEvent<T>(el: (Class<T> | T), type: string, fn: (EventCallback<T> | Function), options?: Utilities.EventOptions): Function;
/**
* Remove an event that was added with {@link Highcharts#addEvent}.
*
* @function Highcharts.removeEvent<T>
*
* @param {Highcharts.Class<T>|T} el
* The element to remove events on.
*
* @param {string} [type]
* The type of events to remove. If undefined, all events are removed
* from the element.
*
* @param {Highcharts.EventCallbackFunction<T>} [fn]
* The specific callback to remove. If undefined, all events that match
* the element and optionally the type are removed.
*
* @return {void}
*/
declare function removeEvent<T>(el: (Class<T> | T), type?: string, fn?: (EventCallback<T> | Function)): void;
/**
* Fire an event that was registered with {@link Highcharts#addEvent}.
*
* @function Highcharts.fireEvent<T>
*
* @param {T} el
* The object to fire the event on. It can be a {@link HTMLDOMElement},
* an {@link SVGElement} or any other object.
*
* @param {string} type
* The type of event.
*
* @param {Highcharts.Dictionary<*>|Event} [eventArguments]
* Custom event arguments that are passed on as an argument to the event
* handler.
*
* @param {Highcharts.EventCallbackFunction<T>|Function} [defaultFunction]
* The default function to execute if the other listeners haven't
* returned false.
*
* @return {void}
*/
declare function fireEvent<T>(el: T, type: string, eventArguments?: (AnyRecord | Event), defaultFunction?: (EventCallback<T> | Function)): void;
/**
* Activates a serial mode for element IDs provided by
* {@link Highcharts.uniqueKey}. This mode can be used in automated tests, where
* a simple comparison of two rendered SVG graphics is needed.
*
* **Note:** This is only for testing purposes and will break functionality in
* webpages with multiple charts.
*
* @example
* if (
* process &&
* process.env.NODE_ENV === 'development'
* ) {
* Highcharts.useSerialIds(true);
* }
*
* @function Highcharts.useSerialIds
*
* @param {boolean} [mode]
* Changes the state of serial mode.
*
* @return {boolean|undefined}
* State of the serial mode.
*/
declare function useSerialIds(mode?: boolean): (boolean | undefined);
declare function isFunction(obj: unknown): obj is Function;
declare function ucfirst(s: unknown): string;
declare namespace Utilities {
type RelativeSize = (number | string);
interface ErrorMessageEventObject {
chart?: Chart;
code: number;
message?: string;
params?: Record<string, string>;
}
interface EventOptions {
order?: number;
passive?: boolean;
}
interface EventWrapperObject<T> {
fn: EventCallback<T>;
order: number;
}
interface FindCallback<T> {
(value: T, index: number): unknown;
}
interface ObjectEachCallback<TObject, TContext> {
(this: TContext, value: TObject[keyof TObject], key: Extract<keyof TObject, string>, obj: TObject): void;
}
interface OffsetObject {
height: number;
left: number;
top: number;
width: number;
}
interface WrapProceedFunction<T extends ArrowFunction> {
(proceed: (T & ArrowFunction), ...args: Array<any>): ReturnType<T>;
}
}
declare const Utilities: {
addEvent: typeof addEvent;
arrayMax: typeof arrayMax;
arrayMin: typeof arrayMin;
attr: typeof attr;
clamp: typeof clamp;
clearTimeout: typeof internalClearTimeout;
correctFloat: typeof correctFloat;
createElement: typeof createElement;
crisp: typeof crisp;
css: typeof css;
defined: typeof defined;
destroyObjectProperties: typeof destroyObjectProperties;
diffObjects: typeof diffObjects;
discardElement: typeof discardElement;
erase: typeof erase;
error: typeof error;
extend: typeof extend;
extendClass: typeof extendClass;
find: <T>(arr: Array<T>, callback: Utilities.FindCallback<T>) => (T | undefined);
fireEvent: typeof fireEvent;
getAlignFactor: (align?: string) => number;
getClosestDistance: typeof getClosestDistance;
getMagnitude: typeof getMagnitude;
getNestedProperty: typeof getNestedProperty;
getStyle: typeof getStyle;
insertItem: typeof insertItem;
isArray: typeof isArray;
isClass: typeof isClass;
isDOMElement: typeof isDOMElement;
isFunction: typeof isFunction;
isNumber: typeof isNumber;
isObject: typeof isObject;
isString: typeof isString;
merge: typeof merge;
normalizeTickInterval: typeof normalizeTickInterval;
objectEach: typeof objectEach;
offset: typeof offset;
pad: typeof pad;
pick: typeof pick;
pInt: typeof pInt;
pushUnique: typeof pushUnique;
relativeLength: typeof relativeLength;
removeEvent: typeof removeEvent;
replaceNested: typeof replaceNested;
splat: typeof splat;
stableSort: typeof stableSort;
syncTimeout: typeof syncTimeout;
timeUnits: Record<Time.TimeUnit, number>;
ucfirst: typeof ucfirst;
uniqueKey: () => string;
useSerialIds: typeof useSerialIds;
wrap: typeof wrap;
};
export default Utilities;