scichart
Version:
Fast WebGL JavaScript Charting Library and Framework
328 lines (327 loc) • 14.1 kB
TypeScript
import { ELabelProviderType } from "../../../../types/LabelProviderType";
import { ENumericFormat } from "../../../../types/NumericFormat";
import { LabelProviderBase2D, ILabel2DOptions } from "./LabelProviderBase2D";
export declare enum ETradeChartLabelFormat {
Nanoseconds = "Nanoseconds",
Microseconds = "Microseconds",
/** @example `04:01`, `45.1234`, `46.3456` */
MilliSeconds = "MilliSeconds",
/** @example `Apr 25`, `04:01:45`, `02:02:30` */
Seconds = "Seconds",
/** @example `Apr 25`, `01:34`, `02:24` */
Minutes = "Minutes",
/** @example `Apr`, `08`, `13` */
Days = "Days",
/** @example `2020`, `Jan`, `Feb` */
Months = "Months"
}
export declare enum EDatePrecision {
/** "Second" or "Unix", where 1 second = 1.0 value */
Seconds = 1,
/** 1 second = 1,000 value */
Milliseconds = 1000,
/** 1 second = 1,000,000 value */
Microseconds = 1000000,
/** 1 second = 1,000,000,000 value */
Nanoseconds = 1000000000
}
export declare enum EHighPrecisionLabelMode {
/**
* Formats the precise values with their respective suffix (`ms`, `µs`, `ns`).
*
* @note It can also show seconds, depending on {@link SmartDateLabelProvider.showSecondsOnPreciseDate}
*
* @example
* "345ms"
* "59s345ms"
*/
Suffix = "Suffix",
/**
* Formats the precise values as fractional seconds.
*
* @note It can also show seconds, depending on {@link SmartDateLabelProvider.showSecondsOnPreciseDate}
*
* @example
* ".00345"
* "59.00345"
*/
Fractional = "Fractional",
/**
* Formats the precise values in scientific notation.
*
* @example
* "4.00e-1s"
*/
Scientific = "Scientific"
}
/**
* Type for label thresholds mapping.
* Maps each {@link ETradeChartLabelFormat} to its maximum time range in seconds.
*/
export declare type TLabelThresholds = Partial<Record<ETradeChartLabelFormat, number>>;
/**
* Default label thresholds used by SmartDateLabelProvider.
* Maps each label format to its maximum time range in seconds.
*/
export declare const DEFAULT_LABEL_THRESHOLDS: Record<ETradeChartLabelFormat, number>;
export interface ISmartDateLabelProviderOptions extends ILabel2DOptions {
/**
* Sets whether the first label should be formatted using the wider format (eg Month Day).
* If false the wider format will only be used when it changes (eg day/month boundary).
* Default true.
*/
showWiderDateOnFirstLabel?: boolean;
/**
* Sets whether the year should be shown in the wider format used on first label.
* Default false.
*/
showYearOnWiderDate?: boolean;
/**
* A timestamp in seconds to add to the value being formatted. This allows you to
* plot dates with more than millisecond precision but still show a full date
* with year on the axis.
*/
dateOffset?: number;
/**
* Defines the precision of the input data values.
* Defaults to Seconds (Unix time).
*/
datePrecision?: EDatePrecision;
/**
* How to format high-precision (nano / micro / milli) labels.
* Default `EHighPrecisionLabelMode.Fractional`
*/
highPrecisionLabelMode?: EHighPrecisionLabelMode;
/**
* Custom label thresholds that map label formats to maximum time ranges in seconds.
* Allows you to customize when different label formats are used based on the visible time range.
* You can update individual thresholds by providing a partial object.
* Defaults to {@link DEFAULT_LABEL_THRESHOLDS}.
*
* @example
* ```typescript
* // Override only the Minutes threshold
* labelThresholds: {
* [ETradeChartLabelFormat.Minutes]: 60 * 60 * 24 * 7 // 7 days instead of 5
* }
* ```
*/
labelThresholds?: TLabelThresholds;
/**
* Flag that decides whether your wide formatted dates have a comma in between date + month, and everything else
*
* @example
* "Jan 1, 2026" // when true
* "Jan 1 2026" // when false
*
* Default: true
*/
splitWideDateWithComma?: boolean;
/**
* Whether to show the seconds component on wide date formats.
* This will NOT affect precise formats (e.g. `59s123ms`).
*
* @example
* "Jan 1 2026 12:59:59" // when true
* "Jan 1 2026 12:59" // when false
*
* @remark You may use this alongside {@link showSecondsOnPreciseDate}. When one is `true`, the other can be set to `false` (to keep labels tidy & avoid repetitions).
*
* Default: true
*/
showSecondsOnWideDate?: boolean;
/**
* Whether to show the seconds component on precise date formats.
* This will NOT affect wide formats (e.g. `Jan 1 2026 12:59:59`).
*
* @example
* "59.123456ms" // when true
* "123456ms" // when false
*
* @note only applies to {@link EHighPrecisionLabelMode.Suffix} and {@link EHighPrecisionLabelMode.Fractional}
*
* @remark You may use this alongside {@link showSecondsOnWideDate}. When one is `true`, the other can be set to `false` (to keep labels tidy & avoid repetitions).
*
* Default: false
*/
showSecondsOnPreciseDate?: boolean;
}
/**
* The {@link SmartDateLabelProvider} formats Axis Labels and Cursor / Tooltips for {@link NumericAxis} types
*/
export declare class SmartDateLabelProvider extends LabelProviderBase2D {
readonly type = ELabelProviderType.SmartDate;
textVariesForSameTick: boolean;
/** The time range used to determine the current formating style */
format: ETradeChartLabelFormat | string | undefined;
private prevValue;
private prevPrevValue;
private showWiderDateOnFirstLabelProperty;
private showYearOnWiderDateProperty;
private dateOffsetProperty;
private datePrecisionProperty;
private highPrecisionLabelModeProperty;
private labelThresholdsProperty;
private labelThresholdsUpdated;
private splitWideDateWithCommaProperty;
private showSecondsOnWideDateProperty;
private showSecondsOnPreciseDateProperty;
protected firstLabel: boolean;
/**
* Creates an instance of {@link SmartDateLabelProvider}
*/
constructor(options?: ISmartDateLabelProviderOptions);
/**
* Convert value from current precision (ticks) to standard Unix Seconds.
* @note High precision values (nano) will lose precision here.
* Use only for coarse-grained logic (year / month / day checks).
*/
convertToUnixSeconds(value: number): number;
/**
* Convert raw ticks to Unix seconds, preserving integer seconds.
* Returns only the whole seconds part, discarding sub-second precision.
*/
private getWholeSeconds;
get showWiderDateOnFirstLabel(): boolean;
set showWiderDateOnFirstLabel(value: boolean);
/**
* A timestamp in seconds to add to the value being formatted.
*/
get dateOffset(): number;
set dateOffset(value: number);
/**
* Gets or sets the precision of the input data values.
* Defaults to `EDatePrecision.Seconds` (Unix).
*/
get datePrecision(): EDatePrecision;
set datePrecision(value: EDatePrecision);
/**
* Gets or Sets the high precision label mode.
* Default `EHighPrecisionLabelMode.Fractional`
*/
get highPrecisionLabelMode(): EHighPrecisionLabelMode;
set highPrecisionLabelMode(value: EHighPrecisionLabelMode);
/**
* Gets or Sets whether the year should be shown in the wider format used on first label. Default false.
*/
get showYearOnWiderDate(): boolean;
set showYearOnWiderDate(value: boolean);
/**
* Gets or sets the custom label thresholds that map label formats to maximum time ranges.
* Allows you to customize when different label formats are used based on the visible time range.
* You can update individual thresholds by providing a partial object.
* Default {@link DEFAULT_LABEL_THRESHOLDS}.
*
* @example
* ```typescript
* // Override only the Minutes threshold
* labelProvider.labelThresholds = {
* [ETradeChartLabelFormat.Minutes]: 60 * 60 * 24 * 7 // 7 days
* };
* ```
*/
get labelThresholds(): TLabelThresholds;
set labelThresholds(value: TLabelThresholds);
/**
* Gets or Sets whether your wide formatted dates have a comma in between date + month, and everything else
*/
get splitWideDateWithComma(): boolean;
set splitWideDateWithComma(value: boolean);
/**
* Gets or Sets whether to show the seconds component on wide date formats.
*/
get showSecondsOnWideDate(): boolean;
set showSecondsOnWideDate(value: boolean);
/**
* Gets or Sets whether to show the seconds component on precise date formats.
*/
get showSecondsOnPreciseDate(): boolean;
set showSecondsOnPreciseDate(value: boolean);
/** @inheritDoc */
get numericFormat(): ENumericFormat;
/** @inheritDoc */
set numericFormat(value: ENumericFormat);
onBeginAxisDraw(): void;
/**
* @inheritDoc
*/
getLabels(majorTicks: number[]): string[];
/**
* Formats the value in a wider format, used for the first label and when the formatted value changes
* (e.g., when crossing day/hour boundaries). This method can be overridden to customize wide label formatting.
*
* @param labelRange - The label format range determined by the visible time span (e.g., Nanoseconds, Seconds, Days)
* @param valueInSeconds - The data value converted to Unix seconds with dateOffset already applied
* @returns The formatted wide label string
*
* @example
* // For high precision: "Jan 2, 2026 12:59:59"
* // For months: "Jan 2026"
* // For years: "2026"
*/
formatDateWide(labelRange: ETradeChartLabelFormat | string, valueInSeconds: number): string;
/**
* Formats the value using the precise format for non-wide labels. The format depends on the
* `highPrecisionLabelMode` setting. This method can be overridden to customize precise label formatting.
*
* @param labelRange - The label format range determined by the visible time span (e.g., Nanoseconds, Seconds, Days)
* @param valueInSeconds - The data value converted to Unix seconds with dateOffset already applied
* @param rawValue - The original raw tick value, used to extract sub-second precision without floating point loss
* @returns The formatted precise label string
*
* @remarks
* For high precision formats (ns/µs/ms), the raw value is essential for maintaining precision. See {@link EHighPrecisionLabelMode} for more formatting details.
*
* @remarks
* For coarser formats, only `valueInSeconds` is used.
*/
formatDatePrecise(labelRange: ETradeChartLabelFormat | string, valueInSeconds: number, rawValue?: number): string;
toJSON(): {
type: string;
options: Required<Omit<import("./LabelProvider").ILabelOptions, never>>;
};
/** This method is bound to the formatLabel method of the base labelProvider. */
protected doFormat(dataValue: number): string;
/**
* Return a range string, based on the numeric range of the axis.
* This will be used to choose which formatting to use.
* Uses the {@link labelThresholds} property to determine the appropriate format.
*/
protected getLabelRange(timeRangeSeconds: number, ticksNumber: number): ETradeChartLabelFormat | string;
/**
* Main smart label formatting logic that determines when to display wide vs precise labels.
* This method can be overridden to customize the overall label selection strategy.
*
* @param format - The label format range (Nanoseconds, Microseconds, MilliSeconds, Seconds, Minutes, Days, Months)
* @param valueInSeconds - The current data value converted to Unix seconds with dateOffset applied
* @param prevValueInSeconds - The previous label's value in Unix seconds (undefined for first label)
* @param prevPrevValueInSeconds - The label before the previous one in Unix seconds (used for month formatting)
* @param originalRawValue - The current raw tick value, preserving sub-second precision
* @returns The formatted label string (either wide or precise format)
*
* @remarks
* The method decides between wide and precise formats based on:
* 1. Whether this is the first label (controlled by `showWiderDateOnFirstLabel`)
* 2. Whether the wide-formatted value has changed from the previous label
* 3. Special logic for month boundaries
*
* Wide labels provide date/time context (e.g., "1/1/2026 12:59:59"), while precise labels
* show incremental values (e.g., "00.000004000" or "4000ns").
*/
protected formatSmartLabel(
/** The label format range determined by the visible time span (e.g., Nanoseconds, Seconds, Days) */
format: ETradeChartLabelFormat | string,
/** The data value converted to Unix seconds with dateOffset already applied */
valueInSeconds: number,
/** The previous label's value in Unix seconds (undefined for first label) */
prevValueInSeconds: number | undefined,
/** The label before the previous one in Unix seconds (used for month formatting) */
prevPrevValueInSeconds: number | undefined,
/** The original raw tick value, used to extract sub-second precision without floating point loss */
originalRawValue?: number): string;
private getTicksPerSecond;
private getTicksWithinSecond;
private getMillisecondsWithinSecond;
private getMicrosecondsWithinSecond;
private getNanosecondsWithinSecond;
}