@highcharts/grid-pro 2.0.0

package/es-modules/Shared/TimeBase.d.ts

@@ -0,0 +1,353 @@
+import type { LangOptionsCore } from './LangOptionsCore';
+declare module '../Core/Options' {
+    interface Options {
+        time?: TimeBase.TimeOptions;
+    }
+}
+/**
+ * The Time class. Time settings are applied in general for each page using
+ * `Highcharts.setOptions`, or individually for each Chart item through the
+ * [time](https://api.highcharts.com/highcharts/time) options set.
+ *
+ * The Time object is available from {@link Highcharts.Chart#time}, which refers
+ * to  `Highcharts.time` unless individual time settings are applied for each
+ * chart.
+ *
+ * When configuring time settings for individual chart instances, be aware that
+ * using `Highcharts.dateFormat` or `Highcharts.time.dateFormat` within
+ * formatter callbacks relies on the global time object, which applies the
+ * global language and time zone settings. To ensure charts with local time
+ * settings function correctly, use `chart.time.dateFormat? instead. However,
+ * the recommended best practice is to use `setOptions` to define global time
+ * settings unless specific configurations are needed for each chart.
+ *
+ * @example
+ * // Apply time settings globally
+ * Highcharts.setOptions({
+ *     time: {
+ *         timezone: 'Europe/London'
+ *     }
+ * });
+ *
+ * // Apply time settings by instance
+ * const chart = Highcharts.chart('container', {
+ *     time: {
+ *         timezone: 'America/New_York'
+ *     },
+ *     series: [{
+ *         data: [1, 4, 3, 5]
+ *     }]
+ * });
+ *
+ * // Use the Time object of a chart instance
+ * console.log(
+ *        'Current time in New York',
+ *        chart.time.dateFormat('%Y-%m-%d %H:%M:%S', Date.now())
+ * );
+ *
+ * // Standalone use
+ * const time = new Highcharts.Time({
+ *    timezone: 'America/New_York'
+ * });
+ * const s = time.dateFormat('%Y-%m-%d %H:%M:%S', Date.UTC(2020, 0, 1));
+ * console.log(s); // => 2019-12-31 19:00:00
+ *
+ * @since 6.0.5
+ *
+ * @class
+ * @name Highcharts.Time
+ *
+ * @param {Highcharts.TimeOptions} [options] Time options as defined in
+ * [chart.options.time](/highcharts/time).
+ */
+declare class TimeBase {
+    dTLCache: Record<string, Intl.DateTimeFormat>;
+    constructor(options?: TimeBase.TimeOptions, lang?: LangOptionsCore);
+    options: TimeBase.TimeOptions;
+    private lang?;
+    timezone?: string;
+    variableTimezone: boolean;
+    Date: typeof Date;
+    private months;
+    private shortMonths;
+    private weekdays;
+    private shortWeekdays;
+    /**
+     * Update the Time object with current options. It is called internally on
+     * initializing Highcharts, after running `Highcharts.setOptions` and on
+     * `Chart.update`.
+     *
+     * @private
+     * @function Highcharts.Time#update
+     *
+     * @param {Highcharts.TimeOptions} [options]
+     *
+     */
+    update(options?: TimeBase.TimeOptions): void;
+    /**
+     * Get a date in terms of numbers (year, month, day etc) for further
+     * processing. Takes the current `timezone` setting into account. Inverse of
+     * `makeTime` and the native `Date` constructor and `Date.UTC`.
+     *
+     * The date is returned in array format with the following indices:
+     *
+     * 0: year,
+     * 1: month (zero based),
+     * 2: day,
+     * 3: hours,
+     * 4: minutes,
+     * 5: seconds,
+     * 6: milliseconds,
+     * 7: weekday (Sunday as 0)
+     *
+     * @function Highcharts.Time#toParts
+     *
+     * @param {number|Date} [timestamp]
+     *                 The timestamp in milliseconds since January 1st 1970.
+     *                 A Date object is also accepted.
+     *
+     * @return {Array<number>} The date parts in array format.
+     */
+    toParts(timestamp?: number | Date): number[];
+    /**
+     * Shorthand to get a cached `Intl.DateTimeFormat` instance.
+     */
+    dateTimeFormat(options: Intl.DateTimeFormatOptions | string, timestamp?: number | Date, locale?: string | Array<string> | undefined): string;
+    /**
+     * Take a locale-aware string format and return a full DateTimeFormat in
+     * object form.
+     */
+    private str2dtf;
+    /**
+     * Make a time and returns milliseconds. Similar to `Date.UTC`, but takes
+     * the current `timezone` setting into account.
+     *
+     * @function Highcharts.Time#makeTime
+     *
+     * @param {number} year
+     *        The year
+     *
+     * @param {number} month
+     *        The month. Zero-based, so January is 0.
+     *
+     * @param {number} [date=1]
+     *        The day of the month
+     *
+     * @param {number} [hours=0]
+     *        The hour of the day, 0-23.
+     *
+     * @param {number} [minutes=0]
+     *        The minutes
+     *
+     * @param {number} [seconds=0]
+     *        The seconds
+     *
+     * @return {number}
+     *         The time in milliseconds since January 1st 1970.
+     */
+    makeTime(year: number, month: number, date?: number, hours?: number, minutes?: number, seconds?: number, milliseconds?: number): number;
+    /**
+     * Parse a datetime string. Unless the string contains time zone
+     * information, apply the current `timezone` from options. If the argument
+     * is a number, return it.
+     *
+     * @function Highcharts.Time#parse
+     * @param    {string|number|undefined} s The datetime string to parse
+     * @return   {number|undefined}          Parsed JavaScript timestamp
+     */
+    parse(s: string | number | undefined | null): number | undefined;
+    /**
+     * Get the time zone offset based on the current timezone information as
+     * set in the global options.
+     *
+     * @function Highcharts.Time#getTimezoneOffset
+     *
+     * @param {number} timestamp
+     *        The JavaScript timestamp to inspect.
+     *
+     * @return {number}
+     *         The timezone offset in minutes compared to UTC.
+     */
+    getTimezoneOffset(timestamp: number | Date): number;
+    /**
+     * Formats a JavaScript date timestamp (milliseconds since January 1 1970)
+     * into a human readable date string.
+     *
+     * The `format` parameter accepts two types of values:
+     * - An object containing settings that are passed directly on to
+     *   [Intl.DateTimeFormat.prototype.format](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/format).
+     * - A format string containing either individual or locale-aware format
+     *   keys. **Individual keys**, for example `%Y-%m-%d`, are listed below.
+     *   **Locale-aware keys** are grouped by square brackets, for example
+     *   `%[Ymd]`. The order of keys within the square bracket doesn't affect
+     *   the output, which is determined by the locale. See example below.
+     *   Internally, the locale-aware format keys are just a shorthand for the
+     *   full object formats, but are particularly practical in
+     *   [templating](https://www.highcharts.com/docs/chart-concepts/templating)
+     *   where full object definitions are not an option.
+     *
+     * The available string format keys are listed below. Additional formats can
+     * be given in the {@link Highcharts.dateFormats} hook.
+     *
+     * Supported format keys:
+     * | Key  | Description                     | Notes on locale-aware format |
+     * -------|----------------------------------------------|-------|
+     * | `%A` | Long weekday, like 'Monday'                  |       |
+     * | `%a` | Short weekday, like 'Mon'                    |       |
+     * | `%E` | Narrow weekday, single character             |       |
+     * | `%d` | Two digit day of the month, 01 to 31         |       |
+     * | `%e` | Day of the month, 1 through 31               |       |
+     * | `%w` | Day of the week, 0 through 6                 | N/A   |
+     * | `%v` | The prefix "week from", read from `lang.weekFrom` | N/A |
+     * | `%b` | Short month, like 'Jan'                      |       |
+     * | `%B` | Long month, like 'January'                   |       |
+     * | `%m` | Two digit month number, 01 through 12        |       |
+     * | `%o` | Month number, 1 through 12                   |       |
+     * | `%y` | Two digits year, like 24 for 2024            |       |
+     * | `%Y` | Four digits year, like 2024                  |       |
+     * | `%H` | Two digits hours in 24h format, 00 through 23 | Depending on the locale, 12h format may be instered. |
+     * | `%k` | Hours in 24h format, 0 through 23            | Depending on the locale, 12h format may be instered. |
+     * | `%I` | Two digits hours in 12h format, 00 through 11 | N/A. The locale determines the hour format. |
+     * | `%l` | Hours in 12h format, 1 through 12            | N/A. The locale determines the hour format. |
+     * | `%M` | Two digits minutes, 00 through 59            |       |
+     * | `%p` | Upper case AM or PM                          | N/A. The locale determines whether to add AM and PM. |
+     * | `%P` | Lower case AM or PM                          | N/A. The locale determines whether to add AM and PM. |
+     * | `%S` | Two digits seconds, 00 through 59            |       |
+     * | `%L` | Milliseconds (naming from Ruby)              |       |
+     *
+     * @example
+     * // Object format, US English
+     * const time1 = new Highcharts.Time({ locale: 'en-US' });
+     * console.log(
+     *     time1.dateFormat({
+     *         day: 'numeric',
+     *         month: 'short',
+     *         year: 'numeric',
+     *         hour: 'numeric',
+     *         minute: 'numeric'
+     *     }, Date.UTC(2024, 11, 31))
+     * ); // => Dec 31, 2024, 12:00 AM
+     *
+     * // Object format, British English
+     * const time2 = new Highcharts.Time({ locale: 'en-GB' });
+     * console.log(
+     *     time2.dateFormat({
+     *         day: 'numeric',
+     *         month: 'short',
+     *         year: 'numeric',
+     *         hour: 'numeric',
+     *         minute: 'numeric'
+     *     }, Date.UTC(2024, 11, 31))
+     * ); // => 31 Dec 2024, 00:00
+     *
+     * // Individual key string replacement
+     * const time3 = new Highcharts.Time();
+     * console.log(
+     *     time3.dateFormat('%Y-%m-%d %H:%M:%S', Date.UTC(2024, 11, 31))
+     * ); // => 2024-12-31 00:00:00
+     *
+     * // Locale-aware keys, US English
+     * const time4 = new Highcharts.Time({ locale: 'en-US' });
+     * console.log(
+     *     time4.dateFormat('%[YebHM]', Date.UTC(2024, 11, 31))
+     * ); // => Dec 31, 2024, 12:00 AM
+     *
+     * // Locale-aware keys, British English
+     * const time5 = new Highcharts.Time({ locale: 'en-GB' });
+     * console.log(
+     *     time5.dateFormat('%[YebHM]', Date.UTC(2024, 11, 31))
+     * ); // => 31 Dec 2024, 00:00
+     *
+     * // Mixed locale-aware and individual keys
+     * console.log(
+     *     time5.dateFormat('%[Yeb], %H:%M', Date.UTC(2024, 11, 31))
+     * ); // => 31 Dec 2024, 00:00
+     *
+     * @function Highcharts.Time#dateFormat
+     *
+     * @param {string|Highcharts.DateTimeFormatOptions} format
+     *        The desired string format where various time representations are
+     *        prefixed with %, or an object representing the locale-aware format
+     *        options.
+     *
+     * @param {number} [timestamp]
+     *        The JavaScript timestamp.
+     *
+     * @param {boolean} [upperCaseFirst=false]
+     *        Upper case first letter in the return.
+     *
+     * @return {string}
+     *         The formatted date.
+     */
+    dateFormat(format?: TimeBase.DateTimeFormat | null, timestamp?: number, upperCaseFirst?: boolean): string;
+    /**
+     * Resolve legacy formats of dateTimeLabelFormats (strings and arrays) into
+     * an object.
+     * @private
+     * @param {string|Array<T>|Highcharts.Dictionary<T>} f
+     * General format description
+     * @return {Highcharts.Dictionary<T>}
+     * The object definition
+     */
+    resolveDTLFormat(f: TimeBase.DateTimeLabelFormatOption): TimeBase.DateTimeLabelFormatObject;
+    /**
+     * Get the optimal date format for a point, based on a range.
+     *
+     * @private
+     * @function Highcharts.Time#getDateFormat
+     *
+     * @param {number} range
+     *        The time range
+     *
+     * @param {number} timestamp
+     *        The timestamp of the date
+     *
+     * @param {number} startOfWeek
+     *        An integer representing the first day of the week, where 0 is
+     *        Sunday.
+     *
+     * @param {Highcharts.Dictionary<string>} dateTimeLabelFormats
+     *        A map of time units to formats.
+     *
+     * @return {string}
+     *         The optimal date format for a point.
+     */
+    getDateFormat(range: number | undefined, timestamp: number, startOfWeek: number, dateTimeLabelFormats: TimeBase.DateTimeLabelFormatsOption): TimeBase.DateTimeFormat | undefined;
+}
+declare namespace TimeBase {
+    interface DateTimeFormatOptions extends Intl.DateTimeFormatOptions {
+        dateStyle?: 'full' | 'long' | 'medium' | 'short';
+        fractionalSecondDigits?: number;
+        prefix?: string;
+        suffix?: string;
+        timeStyle?: 'full' | 'long' | 'medium' | 'short';
+    }
+    type DateTimeFormat = string | DateTimeFormatOptions;
+    interface DateTimeLabelFormatObject {
+        from?: DateTimeFormat;
+        list?: DateTimeFormat[];
+        main: DateTimeFormat;
+        range?: boolean;
+        to?: DateTimeFormat;
+    }
+    type DateTimeLabelFormatOption = (DateTimeFormat | Array<string> | TimeBase.DateTimeLabelFormatObject);
+    type DateTimeLabelFormatsOption = (Record<TimeUnit, DateTimeLabelFormatOption>);
+    interface TimeOptions {
+        Date?: any;
+        locale?: string | Array<string>;
+        timezone?: string;
+        timezoneOffset?: number;
+        useUTC?: boolean;
+    }
+    interface TimeFormatCallbackFunction {
+        (this: TimeBase, timestamp: number): string;
+    }
+    interface TimeNormalizedObject {
+        count: number;
+        unitName: TimeUnit;
+        unitRange: number;
+    }
+    type TimeUnit = ('millisecond' | 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'year');
+    type TimeUnitValue = ('Date' | 'Day' | 'FullYear' | 'Hours' | 'Milliseconds' | 'Minutes' | 'Month' | 'Seconds');
+}
+export default TimeBase;