From 22c1ba6b19653a8c4358438ea89e47c53ecd4219 Mon Sep 17 00:00:00 2001 From: Mark Silverwood <3482679+SlicedSilver@users.noreply.github.com> Date: Mon, 9 Dec 2024 16:28:21 +0000 Subject: [PATCH] Move up down markers into a wrapper --- .size-limit.js | 2 +- debug/debug-esm.mjs.example | 3 +- debug/debug-standalone.html.example | 2 +- dts-config.json | 3 +- src/index.ts | 2 +- src/plugins/series-markers/wrapper.ts | 4 +- .../up-down-markers-plugin/primitive.ts | 57 +------ src/plugins/up-down-markers-plugin/wrapper.ts | 147 ++++++++++++++++++ .../test-cases/plugins/image-watermark.js | 6 +- .../test-cases/plugins/up-down-markers.js | 3 +- .../test-cases/plugins/up-down-markers.js | 3 +- website/tutorials/demos/.eslintrc.js | 2 +- .../demos/yield-curve-with-update-markers.js | 3 +- .../demos/yield-curve-with-update-markers.mdx | 6 +- 14 files changed, 168 insertions(+), 75 deletions(-) create mode 100644 src/plugins/up-down-markers-plugin/wrapper.ts diff --git a/.size-limit.js b/.size-limit.js index dcf95b6348..84ec9439b0 100644 --- a/.size-limit.js +++ b/.size-limit.js @@ -133,7 +133,7 @@ export default [ { name: 'Plugin: UpDownMarkersPrimitive', path: 'dist/lightweight-charts.production.mjs', - import: '{ UpDownMarkersPrimitive }', + import: '{ createUpDownMarkers }', ignore: ['fancy-canvas'], limit: '2.50 KB', }, diff --git a/debug/debug-esm.mjs.example b/debug/debug-esm.mjs.example index 18534d5a8e..94ade9fdbc 100644 --- a/debug/debug-esm.mjs.example +++ b/debug/debug-esm.mjs.example @@ -1,6 +1,7 @@ /* eslint-env browser */ import { createChart, + LineSeries, } from '../dist/lightweight-charts.standalone.development.mjs'; /** @type {HTMLDivElement | null} */ @@ -17,7 +18,7 @@ const chart = createChart(container, options); // @ts-ignore expose the chart api for easier debugging window.chart = chart; -const mainSeries = chart.addLineSeries({ +const mainSeries = chart.addSeries(LineSeries, { priceFormat: { minMove: 1, precision: 0, diff --git a/debug/debug-standalone.html.example b/debug/debug-standalone.html.example index 6eada1f65e..9215bca472 100644 --- a/debug/debug-standalone.html.example +++ b/debug/debug-standalone.html.example @@ -30,7 +30,7 @@ const chart = LightweightCharts.createChart(document.getElementById('container')); - const mainSeries = chart.addLineSeries({ + const mainSeries = chart.addSeries(LightweightCharts.LineSeries, { priceFormat: { minMove: 1, precision: 0, diff --git a/dts-config.json b/dts-config.json index 4fd0c7e575..4a39c8aa45 100644 --- a/dts-config.json +++ b/dts-config.json @@ -9,7 +9,8 @@ "output": { "sortNodes": true, "respectPreserveConstEnum": true - } + }, + "failOnClass": true } ] } diff --git a/src/index.ts b/src/index.ts index 695d814af3..4f5a0b96aa 100644 --- a/src/index.ts +++ b/src/index.ts @@ -36,7 +36,7 @@ export { histogramSeries as HistogramSeries } from './model/series/histogram-ser export { createTextWatermark } from './plugins/text-watermark/primitive'; export { createImageWatermark } from './plugins/image-watermark/primitive'; export { createSeriesMarkers } from './plugins/series-markers/wrapper'; -export { UpDownMarkersPrimitive } from './plugins/up-down-markers-plugin/primitive'; +export { createUpDownMarkers } from './plugins/up-down-markers-plugin/wrapper'; /** * Returns the current version as a string. For example `'3.3.0'`. diff --git a/src/plugins/series-markers/wrapper.ts b/src/plugins/series-markers/wrapper.ts index 7f533389c0..9415bdac51 100644 --- a/src/plugins/series-markers/wrapper.ts +++ b/src/plugins/series-markers/wrapper.ts @@ -25,7 +25,9 @@ export interface ISeriesMarkersPluginApi extends ISeriesPrimitive detach: () => void; } -class SeriesMarkersPrimitiveWrapper extends SeriesPrimitiveAdapter> implements ISeriesPrimitiveWrapper, ISeriesMarkersPluginApi { +class SeriesMarkersPrimitiveWrapper + extends SeriesPrimitiveAdapter> + implements ISeriesPrimitiveWrapper, ISeriesMarkersPluginApi { public constructor(series: ISeriesApi, primitive: SeriesMarkersPrimitive, markers?: SeriesMarker[]) { super(series, primitive); if (markers) { diff --git a/src/plugins/up-down-markers-plugin/primitive.ts b/src/plugins/up-down-markers-plugin/primitive.ts index 90b974ef69..7cea48522e 100644 --- a/src/plugins/up-down-markers-plugin/primitive.ts +++ b/src/plugins/up-down-markers-plugin/primitive.ts @@ -1,6 +1,6 @@ import { IChartApiBase } from '../../api/ichart-api'; import { ISeriesApi } from '../../api/iseries-api'; -import { SeriesAttachedParameter } from '../../api/iseries-primitive-api'; +import { ISeriesPrimitive, SeriesAttachedParameter } from '../../api/iseries-primitive-api'; import { ensureDefined } from '../../helpers/assertions'; @@ -23,29 +23,10 @@ function isLineData( return type === 'Line' || type === 'Area'; } -/** - * UpDownMarkersPrimitive class for showing the direction of price changes on the chart. - * This plugin can only be used with Line and Area series types. - * 1. Manual control: - * - * - Use the `setMarkers` method to manually add markers to the chart. - * This will replace any existing markers. - * - Use `clearMarkers` to remove all markers. - * - * 2. Automatic updates: - * - * Use `setData` and `update` from this primitive instead of the those on the series to let the - * primitive handle the creation of price change markers automatically. - * - * - Use `setData` to initialize or replace all data points. - * - Use `update` to modify individual data points. This will automatically - * create markers for price changes on existing data points. - * - The `updateVisibilityDuration` option controls how long markers remain visible. - */ export class UpDownMarkersPrimitive< HorzScaleItem, TData extends SeriesDataItemTypeMap[UpDownMarkersSupportedSeriesTypes] = SeriesDataItemTypeMap['Line'] -> { +> implements ISeriesPrimitive { private _chart: IChartApiBase | undefined = undefined; private _series: ISeriesApi | undefined = undefined; @@ -69,10 +50,6 @@ export class UpDownMarkersPrimitive< }; } - /** - * Applies new options to the plugin. - * @param options - Partial options to apply. - */ public applyOptions(options: Partial): void { this._options = { ...this._options, @@ -81,10 +58,6 @@ export class UpDownMarkersPrimitive< this.requestUpdate(); } - /** - * Manually sets markers on the chart. - * @param markers - Array of SeriesUpDownMarker to set. - */ public setMarkers(markers: SeriesUpDownMarker[]): void { this._markersManager.clearAllMarkers(); const horzBehaviour = this._horzScaleBehavior; @@ -96,25 +69,14 @@ export class UpDownMarkersPrimitive< }); } - /** - * Retrieves the current markers on the chart. - * @returns An array of SeriesUpDownMarker. - */ public markers(): readonly SeriesUpDownMarker[] { return this._markersManager.getMarkers(); } - /** - * Requests an update of the chart. - */ public requestUpdate(): void { this._requestUpdate?.(); } - /** - * Attaches the primitive to the chart and series. - * @param params - Parameters for attaching the primitive. - */ public attached(params: SeriesAttachedParameter): void { const { chart, @@ -142,9 +104,6 @@ export class UpDownMarkersPrimitive< this.requestUpdate(); } - /** - * Detaches the primitive from the chart and series. - */ public detached(): void { this._chart = undefined; this._series = undefined; @@ -170,10 +129,6 @@ export class UpDownMarkersPrimitive< return this._paneViews; } - /** - * Sets the data for the series and manages data points for marker updates. - * @param data - Array of data points to set. - */ public setData(data: TData[]): void { if (!this._series) { throw new Error('Primitive not attached to series'); @@ -191,11 +146,6 @@ export class UpDownMarkersPrimitive< ensureDefined(this._series).setData(data); } - /** - * Updates a single data point and manages marker updates for existing data points. - * @param data - The data point to update. - * @param historicalUpdate - Optional flag for historical updates. - */ public update(data: TData, historicalUpdate?: boolean): void { if (!this._series || !this._horzScaleBehavior) { throw new Error('Primitive not attached to series'); @@ -222,9 +172,6 @@ export class UpDownMarkersPrimitive< ensureDefined(this._series).update(data, historicalUpdate); } - /** - * Clears all markers from the chart. - */ public clearMarkers(): void { this._markersManager.clearAllMarkers(); } diff --git a/src/plugins/up-down-markers-plugin/wrapper.ts b/src/plugins/up-down-markers-plugin/wrapper.ts new file mode 100644 index 0000000000..ab675aa8e3 --- /dev/null +++ b/src/plugins/up-down-markers-plugin/wrapper.ts @@ -0,0 +1,147 @@ +import { ISeriesApi } from '../../api/iseries-api'; + +import { + LineData, + SeriesDataItemTypeMap, + WhitespaceData, +} from '../../model/data-consumer'; +import { SeriesType } from '../../model/series-options'; + +import { + ISeriesPrimitiveWrapper, + SeriesPrimitiveAdapter, +} from '../series-primitive-adapter'; +import { UpDownMarkersPluginOptions } from './options'; +import { UpDownMarkersPrimitive } from './primitive'; +import { SeriesUpDownMarker, UpDownMarkersSupportedSeriesTypes } from './types'; + +/** + * UpDownMarkersPrimitive Plugin for showing the direction of price changes on the chart. + * This plugin can only be used with Line and Area series types. + * 1. Manual control: + * + * - Use the `setMarkers` method to manually add markers to the chart. + * This will replace any existing markers. + * - Use `clearMarkers` to remove all markers. + * + * 2. Automatic updates: + * + * Use `setData` and `update` from this primitive instead of the those on the series to let the + * primitive handle the creation of price change markers automatically. + * + * - Use `setData` to initialize or replace all data points. + * - Use `update` to modify individual data points. This will automatically + * create markers for price changes on existing data points. + * - The `updateVisibilityDuration` option controls how long markers remain visible. + */ +export interface ISeriesUpDownMarkerPluginApi< + HorzScaleItem, + TData extends SeriesDataItemTypeMap[UpDownMarkersSupportedSeriesTypes] = SeriesDataItemTypeMap['Line'] +> extends ISeriesPrimitiveWrapper { + /** + * Applies new options to the plugin. + * @param options - Partial options to apply. + */ + applyOptions: (options: Partial) => void; + /** + * Sets the data for the series and manages data points for marker updates. + * @param data - Array of data points to set. + */ + setData: (data: TData[]) => void; + /** + * Updates a single data point and manages marker updates for existing data points. + * @param data - The data point to update. + * @param historicalUpdate - Optional flag for historical updates. + */ + update: (data: TData, historicalUpdate?: boolean) => void; + /** + * Retrieves the current markers on the chart. + * @returns An array of SeriesUpDownMarker. + */ + markers: () => readonly SeriesUpDownMarker[]; + /** + * Manually sets markers on the chart. + * @param markers - Array of SeriesUpDownMarker to set. + */ + setMarkers: (markers: SeriesUpDownMarker[]) => void; + /** + * Clears all markers from the chart. + */ + clearMarkers: () => void; +} + +class SeriesUpDownMarkerPrimitiveWrapper + extends SeriesPrimitiveAdapter< + HorzScaleItem, + unknown, + UpDownMarkersPrimitive + > + implements ISeriesPrimitiveWrapper, ISeriesUpDownMarkerPluginApi { + public setData( + data: (LineData | WhitespaceData)[] + ): void { + return this._primitive.setData(data); + } + + public update( + data: LineData | WhitespaceData, + historicalUpdate?: boolean + ): void { + return this._primitive.update(data, historicalUpdate); + } + + public markers(): readonly SeriesUpDownMarker[] { + return this._primitive.markers(); + } + + public setMarkers(markers: SeriesUpDownMarker[]): void { + return this._primitive.setMarkers(markers); + } + + public clearMarkers(): void { + return this._primitive.clearMarkers(); + } +} + +/** + * Creates and attaches the Series Up Down Markers Plugin. + * + * @param series - Series to which attach the Up Down Markers Plugin + * @param options - options for the Up Down Markers Plugin + * + * @returns Api for Series Up Down Marker Plugin. {@link ISeriesUpDownMarkerPluginApi} + * + * @example + * ```js + * import { createUpDownMarkers, createChart, LineSeries } from 'lightweight-charts'; + * + * const chart = createChart('container'); + * const lineSeries = chart.addSeries(LineSeries); + * const upDownMarkers = createUpDownMarkers(lineSeries, { + * positiveColor: '#22AB94', + * negativeColor: '#F7525F', + * updateVisibilityDuration: 5000, + * }); + * // to add some data + * upDownMarkers.setData( + * [ + * { time: '2020-02-02', value: 12.34 }, + * //... more line series data + * ] + * ); + * // ... Update some values + * upDownMarkers.update({ time: '2020-02-02', value: 13.54 }, true); + * // to remove plugin from the series + * upDownMarkers.detach(); + * ``` + */ +export function createUpDownMarkers( + series: ISeriesApi, + options: Partial = {} +): ISeriesUpDownMarkerPluginApi { + const wrapper = new SeriesUpDownMarkerPrimitiveWrapper( + series, + new UpDownMarkersPrimitive(options) + ); + return wrapper; +} diff --git a/tests/e2e/coverage/test-cases/plugins/image-watermark.js b/tests/e2e/coverage/test-cases/plugins/image-watermark.js index a8d57dc81d..b038679126 100644 --- a/tests/e2e/coverage/test-cases/plugins/image-watermark.js +++ b/tests/e2e/coverage/test-cases/plugins/image-watermark.js @@ -70,14 +70,12 @@ function beforeInteractions(container) { mainSeries.setData(simpleData()); - const imageWatermark = new LightweightCharts.ImageWatermark(imageDataUrl, { + const pane = chart.panes()[0]; + LightweightCharts.createImageWatermark(pane, imageDataUrl, { alpha: 0.5, padding: 20, }); - const pane = chart.panes()[0]; - pane.attachPrimitive(imageWatermark); - return Promise.resolve(); } diff --git a/tests/e2e/coverage/test-cases/plugins/up-down-markers.js b/tests/e2e/coverage/test-cases/plugins/up-down-markers.js index dc28edaa48..fa1a29c583 100644 --- a/tests/e2e/coverage/test-cases/plugins/up-down-markers.js +++ b/tests/e2e/coverage/test-cases/plugins/up-down-markers.js @@ -37,8 +37,7 @@ function beforeInteractions(container) { pointMarkersVisible: true, }); - const primitive = new LightweightCharts.UpDownMarkersPrimitive(); - series1.attachPrimitive(primitive); + const primitive = LightweightCharts.createUpDownMarkers(series1); primitive.setData(curve1); primitive.update({ time: 24, value: 4.3 }, true); // up diff --git a/tests/e2e/graphics/test-cases/plugins/up-down-markers.js b/tests/e2e/graphics/test-cases/plugins/up-down-markers.js index 99b5fab268..00f143f593 100644 --- a/tests/e2e/graphics/test-cases/plugins/up-down-markers.js +++ b/tests/e2e/graphics/test-cases/plugins/up-down-markers.js @@ -36,8 +36,7 @@ function runTestCase(container) { pointMarkersVisible: true, }); - const primitive = new LightweightCharts.UpDownMarkersPrimitive(); - series1.attachPrimitive(primitive); + const primitive = LightweightCharts.createUpDownMarkers(series1); primitive.setData(curve1); primitive.update({ time: 24, value: 4.3 }, true); // up diff --git a/website/tutorials/demos/.eslintrc.js b/website/tutorials/demos/.eslintrc.js index 3b7bfe92ee..44975df39c 100644 --- a/website/tutorials/demos/.eslintrc.js +++ b/website/tutorials/demos/.eslintrc.js @@ -3,7 +3,7 @@ module.exports = { document: false, createChart: false, createYieldCurveChart: false, - UpDownMarkersPrimitive: false, + createUpDownMarkers: false, LineSeries: false, AreaSeries: false, BarSeries: false, diff --git a/website/tutorials/demos/yield-curve-with-update-markers.js b/website/tutorials/demos/yield-curve-with-update-markers.js index d9474e72ed..1358df8cf6 100644 --- a/website/tutorials/demos/yield-curve-with-update-markers.js +++ b/website/tutorials/demos/yield-curve-with-update-markers.js @@ -70,8 +70,7 @@ const series1 = chart.addSeries(LineSeries, { pointMarkersVisible: true, lineWidth: 2, }); -const priceChangeMarkers = new UpDownMarkersPrimitive(); -series1.attachPrimitive(priceChangeMarkers); +const priceChangeMarkers = createUpDownMarkers(series1); priceChangeMarkers.setData(curve1); const series2 = chart.addSeries(LineSeries, { diff --git a/website/tutorials/demos/yield-curve-with-update-markers.mdx b/website/tutorials/demos/yield-curve-with-update-markers.mdx index 2fc8947dc4..9c1bbbce03 100644 --- a/website/tutorials/demos/yield-curve-with-update-markers.mdx +++ b/website/tutorials/demos/yield-curve-with-update-markers.mdx @@ -15,7 +15,7 @@ keywords: This sample demonstrates how to create a yield curve chart with real-time updates using Lightweight Charts™. The chart displays two [yield curves](/docs/next/chart-types#yield-curve-chart) and utilizes the -[UpDownMarkersPrimitive](/docs/next/api/classes/UpDownMarkersPrimitive) plugin +[UpDownMarkersPrimitive](/docs/next/api/classes/createUpDownMarkers) plugin to show price change markers for updates. The chart is initialized with historical yield curve data for two series. By @@ -31,8 +31,8 @@ Key features of this demo: 3. Usage of the UpDownMarkersPrimitive plugin for displaying update markers. 4. Simulated real-time updates to demonstrate dynamic data handling. -The UpDownMarkersPrimitive is attached to the first series using -`series1.attachPrimitive(priceChangeMarkers)`. We then use +The UpDownMarkersPrimitive is attached to the first series when created using +`priceChangeMarkers = createUpDownMarkers(series1)`. We then use `priceChangeMarkers.setData(curve1)` to initialize the data and `priceChangeMarkers.update(...)` for subsequent updates. This approach allows the primitive to manage both the series data and the markers, providing a