Merge pull request #1956 from tpunt/plugin-api-improvements

Plugin API improvements

Author: SlicedSilver

src/api/iseries-api.ts

@@ -4,6 +4,7 @@ import { BarPrice } from '../model/bar';
 import { Coordinate } from '../model/coordinate';
 import { SeriesDataItemTypeMap } from '../model/data-consumer';
 import { Time } from '../model/horz-scale-behavior-time/types';
+import { LastValueDataResult } from '../model/iseries';
 import { MismatchDirection } from '../model/plot-list';
 import { CreatePriceLineOptions } from '../model/price-line-options';
 import {
@@ -303,6 +304,22 @@ export interface ISeriesApi<
 	 */
 	seriesType(): TSeriesType;
 
+	/**
+	 * Return the last value data of the series.
+	 *
+	 * @param globalLast - If false, get the last value in the current visible range. Otherwise, fetch the absolute last value
+	 * @returns The last value data of the series.
+	 * @example
+	 * ```js
+	 * const lineSeries = chart.addSeries(LineSeries);
+	 * console.log(lineSeries.lastValueData(true)); // { noData: false, price: 24.11, color: '#000000' }
+	 *
+	 * const candlestickSeries = chart.addCandlestickSeries();
+	 * console.log(candlestickSeries.lastValueData(false)); // { noData: false, price: 145.72, color: '#000000' }
+	 * ```
+	 */
+	lastValueData(globalLast: boolean): LastValueDataResult;
+
 	/**
 	 * Attaches additional drawing primitive to the series
 	 *

src/api/series-api.ts

@@ -11,6 +11,7 @@ import { CustomPriceLine } from '../model/custom-price-line';
 import { DataUpdatesConsumer, SeriesDataItemTypeMap, WhitespaceData } from '../model/data-consumer';
 import { checkItemsAreOrdered, checkPriceLineOptions, checkSeriesValuesType } from '../model/data-validators';
 import { IHorzScaleBehavior } from '../model/ihorz-scale-behavior';
+import { LastValueDataResult } from '../model/iseries';
 import { ISeriesPrimitiveBase } from '../model/iseries-primitive';
 import { Pane } from '../model/pane';
 import { MismatchDirection } from '../model/plot-list';
@@ -229,6 +230,22 @@ export class SeriesApi<
 		return this._series.seriesType();
 	}
 
+	public lastValueData(globalLast: boolean): LastValueDataResult {
+		const result = this._series.lastValueData(globalLast);
+
+		if (result.noData) {
+			return {
+				noData: true,
+			};
+		}
+
+		return {
+			noData: false,
+			price: result.price,
+			color: result.color,
+		};
+	}
+
 	public attachPrimitive(primitive: ISeriesPrimitive<HorzScaleItem>): void {
 		// at this point we cast the generic to unknown because we
 		// don't want the model to know the types of the API (◑_◑)

src/model/ipane-primitive.ts

@@ -1,5 +1,7 @@
 import { CanvasRenderingTarget2D } from 'fancy-canvas';
 
+import { LineStyle } from '../renderers/draw-line';
+
 /**
  * This interface represents rendering some element on the canvas
  */
@@ -8,18 +10,20 @@ export interface IPrimitivePaneRenderer {
 	 * Method to draw main content of the element
 	 *
 	 * @param target - canvas context to draw on, refer to FancyCanvas library for more details about this class
+	 * @param utils - exposes drawing utilities (such as setLineStyle) from the library to plugins
 	 *
 	 */
-	draw(target: CanvasRenderingTarget2D): void;
+	draw(target: CanvasRenderingTarget2D, utils?: DrawingUtils): void;
 
 	/**
 	 * Optional method to draw the background.
 	 * Some elements could implement this method to draw on the background of the chart.
 	 * Usually this is some kind of watermarks or time areas highlighting.
 	 *
 	 * @param target - canvas context to draw on, refer FancyCanvas library for more details about this class
+	 * @param utils - exposes drawing utilities (such as setLineStyle) from the library to plugins
 	 */
-	drawBackground?(target: CanvasRenderingTarget2D): void;
+	drawBackground?(target: CanvasRenderingTarget2D, utils?: DrawingUtils): void;
 }
 
 /**
@@ -141,3 +145,16 @@ export interface IPanePrimitiveBase<TPaneAttachedParameters = unknown> {
 	 */
 	hitTest?(x: number, y: number): PrimitiveHoveredItem | null;
 }
+
+/**
+ * Helper drawing utilities exposed by the library to a Primitive (a.k.a plugin).
+ */
+export interface DrawingUtils {
+	/**
+	 * Drawing utility to change the line style on the canvas context to one of the
+	 * built-in line styles.
+	 * @param ctx - 2D rendering context for the target canvas.
+	 * @param lineStyle - Built-in {@link LineStyle} to set on the canvas context.
+	 */
+	readonly setLineStyle: (ctx: CanvasRenderingContext2D, lineStyle: LineStyle) => void;
+}

src/model/iseries.ts

@@ -7,10 +7,10 @@ import { SeriesPlotList } from './series-data';
 import { SeriesOptionsMap, SeriesType } from './series-options';
 import { TimePointIndex } from './time-data';
 
-export interface LastValueDataResultWithoutData {
+export interface LastValueDataInternalResultWithoutData {
 	noData: true;
 }
-export interface LastValueDataResultWithData {
+export interface LastValueDataInternalResultWithData {
 	noData: false;
 
 	price: number;
@@ -22,7 +22,34 @@ export interface LastValueDataResultWithData {
 	index: TimePointIndex;
 }
 
-export type LastValueDataResult = LastValueDataResultWithoutData | LastValueDataResultWithData;
+export type LastValueDataInternalResult = LastValueDataInternalResultWithoutData | LastValueDataInternalResultWithData;
+
+/** Represents last value data result of a series for plugins when there is no data */
+export interface LastValueDataResultWithoutData {
+	/**
+	 * Indicates if the series has data.
+	 */
+	noData: true;
+}
+
+/** Represents last value data result of a series for plugins when there is data */
+export interface LastValueDataResultWithData {
+	/**
+	 * Indicates if the series has data.
+	 */
+	noData: false;
+	/**
+	 * The last price of the series.
+	 */
+	price: number;
+	/**
+	 * The color of the last value.
+	 */
+	color: string;
+}
+
+/** Represents last value data result of a series for plugins */
+export type LastValueDataResult = LastValueDataResultWithData | LastValueDataResultWithoutData;
 
 export interface MarkerData {
 	price: BarPrice;
@@ -48,7 +75,7 @@ export interface ISeries<T extends SeriesType> extends IPriceDataSource {
 	options(): Readonly<SeriesOptionsMap[T]>;
 	title(): string;
 	priceScale(): PriceScale;
-	lastValueData(globalLast: boolean): LastValueDataResult;
+	lastValueData(globalLast: boolean): LastValueDataInternalResult;
 	barColorer(): ISeriesBarColorer<T>;
 	markerDataAtIndex(index: TimePointIndex): MarkerData | null;
 	dataAt(time: TimePointIndex): SeriesDataAtTypeMap[SeriesType] | null;

src/model/pane-primitive-wrapper.ts

@@ -14,6 +14,7 @@ import {
 import {
 	ISeriesPrimitiveBase,
 } from './iseries-primitive';
+import { drawingUtils } from './primitive-drawing-utils';
 
 class PrimitiveRendererWrapper implements IPaneRenderer {
 	private readonly _baseRenderer: IPrimitivePaneRenderer;
@@ -23,11 +24,11 @@ class PrimitiveRendererWrapper implements IPaneRenderer {
 	}
 
 	public draw(target: CanvasRenderingTarget2D, isHovered: boolean, hitTestData?: unknown): void {
-		this._baseRenderer.draw(target);
+		this._baseRenderer.draw(target, drawingUtils);
 	}
 
 	public drawBackground?(target: CanvasRenderingTarget2D, isHovered: boolean, hitTestData?: unknown): void {
-		this._baseRenderer.drawBackground?.(target);
+		this._baseRenderer.drawBackground?.(target, drawingUtils);
 	}
 }
 

src/model/primitive-drawing-utils.ts

@@ -0,0 +1,7 @@
+import { setLineStyle } from '../renderers/draw-line';
+
+import { DrawingUtils } from './ipane-primitive';
+
+export const drawingUtils: DrawingUtils = {
+	setLineStyle: setLineStyle,
+};

src/model/series-primitive-wrapper.ts

@@ -15,6 +15,7 @@ import {
 } from './iseries-primitive';
 import { PrimitiveWrapper } from './pane-primitive-wrapper';
 import { PriceScale } from './price-scale';
+import { drawingUtils } from './primitive-drawing-utils';
 import { Series } from './series';
 import { AutoscaleInfo, SeriesType } from './series-options';
 import { Logical, TimePointIndex } from './time-data';
@@ -28,11 +29,11 @@ class SeriesPrimitiveRendererWrapper implements IPaneRenderer {
 	}
 
 	public draw(target: CanvasRenderingTarget2D, isHovered: boolean, hitTestData?: unknown): void {
-		this._baseRenderer.draw(target);
+		this._baseRenderer.draw(target, drawingUtils);
 	}
 
 	public drawBackground?(target: CanvasRenderingTarget2D, isHovered: boolean, hitTestData?: unknown): void {
-		this._baseRenderer.drawBackground?.(target);
+		this._baseRenderer.drawBackground?.(target, drawingUtils);
 	}
 }
 

src/model/series.ts

@@ -26,7 +26,7 @@ import { isDefaultPriceScale } from './default-price-scale';
 import { CustomData, CustomSeriesWhitespaceData, ICustomSeriesPaneView, WhitespaceCheck } from './icustom-series';
 import { PrimitiveHoveredItem, PrimitivePaneViewZOrder } from './ipane-primitive';
 import { FirstValue } from './iprice-data-source';
-import { ISeries, LastValueDataResult, LastValueDataResultWithoutData, MarkerData, SeriesDataAtTypeMap } from './iseries';
+import { ISeries, LastValueDataInternalResult, LastValueDataInternalResultWithoutData, MarkerData, SeriesDataAtTypeMap } from './iseries';
 import { ISeriesPrimitiveBase } from './iseries-primitive';
 import { Pane } from './pane';
 import { PlotRowValueIndex } from './plot-data';
@@ -140,8 +140,8 @@ export class Series<T extends SeriesType> extends PriceDataSource implements IDe
 		return this._options.priceLineColor || lastBarColor;
 	}
 
-	public lastValueData(globalLast: boolean): LastValueDataResult {
-		const noDataRes: LastValueDataResultWithoutData = { noData: true };
+	public lastValueData(globalLast: boolean): LastValueDataInternalResult {
+		const noDataRes: LastValueDataInternalResultWithoutData = { noData: true };
 
 		const priceScale = this.priceScale();
 

src/views/price-axis/series-price-axis-view.ts

@@ -1,4 +1,4 @@
-import { ISeries, LastValueDataResultWithData } from '../../model/iseries';
+import { ISeries, LastValueDataInternalResultWithData } from '../../model/iseries';
 import { PriceAxisLastValueMode, SeriesType } from '../../model/series-options';
 import { PriceAxisViewRendererCommonData, PriceAxisViewRendererData } from '../../renderers/iprice-axis-view-renderer';
 
@@ -62,7 +62,7 @@ export class SeriesPriceAxisView extends PriceAxisView {
 	}
 
 	protected _paneText(
-		lastValue: LastValueDataResultWithData,
+		lastValue: LastValueDataInternalResultWithData,
 		showSeriesLastValue: boolean,
 		showSymbolLabel: boolean,
 		showPriceAndPercentage: boolean
@@ -83,7 +83,7 @@ export class SeriesPriceAxisView extends PriceAxisView {
 		return result.trim();
 	}
 
-	protected _axisText(lastValueData: LastValueDataResultWithData, showSeriesLastValue: boolean, showPriceAndPercentage: boolean): string {
+	protected _axisText(lastValueData: LastValueDataInternalResultWithData, showSeriesLastValue: boolean, showPriceAndPercentage: boolean): string {
 		if (!showSeriesLastValue) {
 			return '';
 		}

tests/e2e/graphics/test-cases/api/series-data-last-value.js

@@ -0,0 +1,51 @@
+function runTestCase(container) {
+	const chart = window.chart = LightweightCharts.createChart(container, { layout: { attributionLogo: false } });
+
+	const lineSeries = chart.addSeries(LightweightCharts.LineSeries);
+
+	lineSeries.setData([
+		{ time: '1990-04-24', value: 0 },
+		{ time: '1990-04-25', value: 1 },
+		{ time: '1990-04-26', value: 2 },
+		{ time: '1990-04-27', value: 3 },
+		{ time: '1990-04-28', value: 4, color: 'green' },
+		{ time: '1990-04-29', value: 5, color: 'red' },
+	]);
+
+	chart.timeScale().fitContent();
+	chart.timeScale().scrollToPosition(-1);
+
+	return new Promise(resolve => {
+		requestAnimationFrame(() => {
+			const lastValueInView = lineSeries.lastValueData(false);
+			console.assert(
+				lastValueInView.noData === false,
+				'expected to find data for last value in view'
+			);
+			console.assert(
+				lastValueInView.price === 4,
+				`expected to find price 4 as last value in view, but found ${lastValueInView.price}`
+			);
+			console.assert(
+				lastValueInView.color === 'green',
+				`expected to find color green as last value in view, but found ${lastValueInView.color}`
+			);
+
+			const lastValueGlobal = lineSeries.lastValueData(true);
+			console.assert(
+				lastValueGlobal.noData === false,
+				'expected to find data for last value globally'
+			);
+			console.assert(
+				lastValueGlobal.price === 5,
+				`expected to find price 5 as last value globally, but found ${lastValueGlobal.price}`
+			);
+			console.assert(
+				lastValueGlobal.color === 'red',
+				`expected to find color red as last value globally, but found ${lastValueGlobal.color}`
+			);
+
+			resolve();
+		});
+	});
+}