export createPrimitive functions instead of primitive class

.size-limit.js

@@ -8,31 +8,31 @@ export default [
 	{
 		name: 'ESM',
 		path: 'dist/lightweight-charts.production.mjs',
-		limit: '44.50 KB',
+		limit: '45.00 KB',
 		import: '*',
 		ignore: ['fancy-canvas'],
 		brotli: true,
 	},
 	{
 		name: 'ESM createChart',
 		path: 'dist/lightweight-charts.production.mjs',
-		limit: '41.30 KB',
+		limit: '45.00 KB',
 		import: '{ createChart }',
 		ignore: ['fancy-canvas'],
 		brotli: true,
 	},
 	{
 		name: 'ESM createChartEx',
 		path: 'dist/lightweight-charts.production.mjs',
-		limit: '40.00 KB',
+		limit: '45.00 KB',
 		import: '{ createChartEx }',
 		ignore: ['fancy-canvas'],
 		brotli: true,
 	},
 	{
 		name: 'ESM Standalone',
 		path: 'dist/lightweight-charts.standalone.production.mjs',
-		limit: '45.90 KB',
+		limit: '50.00 KB',
 		import: '*',
 		brotli: true,
 	},
@@ -45,25 +45,25 @@ export default [
 	{
 		name: 'Plugin: Text Watermark',
 		path: 'dist/lightweight-charts.production.mjs',
-		import: '{ TextWatermark }',
+		import: '{ createTextWatermark }',
 		ignore: ['fancy-canvas'],
 		limit: '2.00 KB',
 		brotli: true,
 	},
 	{
 		name: 'Plugin: Image Watermark',
 		path: 'dist/lightweight-charts.production.mjs',
-		import: '{ ImageWatermark }',
+		import: '{ createImageWatermark }',
 		ignore: ['fancy-canvas'],
 		limit: '2.00 KB',
 		brotli: true,
 	},
 	{
 		name: 'Plugin: Series Markers',
 		path: 'dist/lightweight-charts.production.mjs',
-		import: '{ createSeriesMarkersPrimitive }',
+		import: '{ createSeriesMarkers }',
 		ignore: ['fancy-canvas'],
-		limit: '3.90 KB',
+		limit: '4.08 KB',
 		brotli: true,
 	},
 ];

package.json

@@ -106,7 +106,7 @@
     "tslint-eslint-rules": "~5.4.0",
     "tslint-microsoft-contrib": "~6.2.0",
     "tsx": "~4.16.2",
-    "typescript": "~5.4.5",
+    "typescript": "~5.5.4",
     "yargs": "~17.7.2"
   },
   "scripts": {

src/index.ts

@@ -24,9 +24,9 @@ export { createChart, createChartEx, defaultHorzScaleBehavior } from './api/crea
 /*
 	Plugins
 */
-export { TextWatermark } from './plugins/text-watermark/primitive';
-export { ImageWatermark } from './plugins/image-watermark/primitive';
-export { createSeriesMarkersPrimitive } from './plugins/series-markers/primitive';
+export { createTextWatermark } from './plugins/text-watermark/primitive';
+export { createImageWatermark } from './plugins/image-watermark/primitive';
+export { createSeriesMarkers } from './plugins/series-markers/wrapper';
 
 /**
  * Returns the current version as a string. For example `'3.3.0'`.

src/model/autoscale-info-impl.ts

@@ -28,7 +28,7 @@ export class AutoscaleInfoImpl {
 		return this._margins;
 	}
 
-	public toRaw(): AutoscaleInfo | null {
+	public toRaw(): AutoscaleInfo {
 		return {
 			priceRange: this._priceRange === null ? null : this._priceRange.toRaw(),
 			margins: this._margins || undefined,

src/plugins/image-watermark/primitive.ts

@@ -1,13 +1,14 @@
+import { IPaneApi } from '../../api/ipane-api';
 import {
 	IPanePrimitive,
 	PaneAttachedParameter,
 } from '../../api/ipane-primitive-api';
 
 import { DeepPartial } from '../../helpers/strict-type-checks';
 
-import { Time } from '../../model/horz-scale-behavior-time/types';
 import { IPanePrimitivePaneView } from '../../model/ipane-primitive';
 
+import { IPanePrimitiveWithOptions, PanePrimitiveWrapper } from '../pane-primitive-wrapper';
 import {
 	ImageWatermarkOptions,
 	imageWatermarkOptionsDefaults,
@@ -23,23 +24,7 @@ function mergeOptionsWithDefaults(
 	};
 }
 
-/**
- * A pane primitive for rendering a image watermark.
- *
- * @example
- * ```js
- * import { ImageWatermark } from 'lightweight-charts';
- *
- * const imageWatermark = new ImageWatermark('/images/my-image.png', {
- *   alpha: 0.5,
- *   padding: 20,
- * });
- *
- * const firstPane = chart.panes()[0];
- * firstPane.attachPrimitive(imageWatermark);
- * ```
- */
-export class ImageWatermark<T = Time> implements IPanePrimitive<T> {
+class ImageWatermark<T> implements IPanePrimitive<T> {
 	private _requestUpdate?: () => void;
 	private _paneViews: ImageWatermarkPaneView<T>[];
 	private _options: ImageWatermarkOptions;
@@ -109,3 +94,31 @@ export class ImageWatermark<T = Time> implements IPanePrimitive<T> {
 		);
 	}
 }
+
+/**
+ * Creates an image watermark.
+ *
+ * @param pane - Target pane.
+ * @param imageUrl - Image URL.
+ * @param options - Watermark options.
+ *
+ * @returns Image watermark wrapper.
+ *
+ * @example
+ * ```js
+ * import { createImageWatermark } from 'lightweight-charts';
+ *
+ * const firstPane = chart.panes()[0];
+ * const imageWatermark = createImageWatermark(firstPane, '/images/my-image.png', {
+ *   alpha: 0.5,
+ *   padding: 20,
+ * });
+ * // to change options
+ * imageWatermark.applyOptions({ padding: 10 });
+ * // to remove watermark from the pane
+ * imageWatermark.detach();
+ * ```
+ */
+export function createImageWatermark<T>(pane: IPaneApi<T>, imageUrl: string, options: DeepPartial<ImageWatermarkOptions>): PanePrimitiveWrapper<T, ImageWatermarkOptions, IPanePrimitiveWithOptions<T, ImageWatermarkOptions>> {
+	return new PanePrimitiveWrapper<T, ImageWatermarkOptions, IPanePrimitiveWithOptions<T, ImageWatermarkOptions>>(pane, new ImageWatermark(imageUrl, options));
+}

src/plugins/pane-primitive-wrapper.ts

@@ -0,0 +1,43 @@
+import { IPaneApi } from '../api/ipane-api';
+import { IPanePrimitive } from '../api/ipane-primitive-api';
+
+import { DeepPartial } from '../helpers/strict-type-checks';
+
+import { IPrimitiveWrapper } from './primitive-wrapper-base';
+
+/**
+ * Interface for a primitive with options.
+ */
+export interface IPanePrimitiveWithOptions<T, K> extends IPanePrimitive<T> {
+	/**
+	 * @param options - Options to apply. The options are deeply merged with the current options.
+	 */
+	applyOptions?: (options: DeepPartial<K>) => void;
+}
+
+export class PanePrimitiveWrapper<T, Options = unknown, TPrimitive extends IPanePrimitiveWithOptions<T, Options> = IPanePrimitive<T>> implements IPrimitiveWrapper<T, Options> {
+	protected _primitive: TPrimitive;
+	protected _pane: IPaneApi<T>;
+
+	public constructor(pane: IPaneApi<T>, primitive: TPrimitive) {
+		this._pane = pane;
+		this._primitive = primitive;
+		this._attach();
+	}
+
+	public detach(): void {
+		this._pane.detachPrimitive(this._primitive);
+	}
+
+	public getPane(): IPaneApi<T> {
+		return this._pane;
+	}
+
+	public applyOptions(options: DeepPartial<Options>): void {
+		this._primitive.applyOptions?.(options);
+	}
+
+	private _attach(): void {
+		this._pane.attachPrimitive(this._primitive);
+	}
+}

src/plugins/primitive-wrapper-base.ts

@@ -0,0 +1,25 @@
+import { DeepPartial } from '../helpers/strict-type-checks';
+
+/**
+ * Interface for a primitive wrapper. It must be implemented to add some plugin to the chart.
+ */
+export interface IPrimitiveWrapper<T, Options = unknown> {
+	/**
+	 * @param options - Options to apply. The options are deeply merged with the current options.
+	 */
+	applyOptions(options: DeepPartial<Options>): void;
+	/**
+	 * Detaches the plugin from the pane/series.
+	 */
+	detach(): void;
+}
+
+/**
+ * Interface for a plugin that adds primitive with options.
+ */
+export interface IPrimitiveWithOptions<Options = unknown> {
+	/**
+	 * @param options - Options to apply. The options are deeply merged with the current options.
+	 */
+	applyOptions(options: DeepPartial<Options>): void;
+}

src/plugins/primitive-wrapper.ts

@@ -0,0 +1,27 @@
+import { IPanePrimitive, PaneAttachedParameter } from '../api/ipane-primitive-api';
+
+import { DeepPartial } from '../helpers/strict-type-checks';
+
+export abstract class PrimitiveWrapper<T, Options = unknown> {
+	protected _primitive: IPanePrimitive<T>;
+	protected _options: Options;
+
+	public constructor(primitive: IPanePrimitive<T>, options: Options) {
+		this._primitive = primitive;
+		this._options = options;
+	}
+
+	public detach(): void {
+		this._primitive.detached?.();
+	}
+
+	public abstract applyOptions(options: DeepPartial<Options>): void;
+
+	protected _attachToPrimitive(params: PaneAttachedParameter<T>): void {
+		this._primitive.attached?.(params);
+	}
+
+	protected _requestUpdate(): void {
+		this._primitive.updateAllViews?.();
+	}
+}

src/plugins/series-markers/primitive.ts

@@ -19,8 +19,7 @@ import {
 	shapeMargin as calculateShapeMargin,
 } from './utils';
 
-class SeriesMarkersPrimitive<HorzScaleItem> implements ISeriesPrimitive<HorzScaleItem> {
-	private _attached: SeriesAttachedParameter<HorzScaleItem> | null = null;
+export class SeriesMarkersPrimitive<HorzScaleItem> implements ISeriesPrimitive<HorzScaleItem> {
 	private _paneView: SeriesMarkersPaneView<HorzScaleItem> | null = null;
 	private _markers: SeriesMarker<HorzScaleItem>[] = [];
 	private _indexedMarkers: InternalSeriesMarker<TimePointIndex>[] = [];
@@ -33,7 +32,6 @@ class SeriesMarkersPrimitive<HorzScaleItem> implements ISeriesPrimitive<HorzScal
 	private _markersPositions: MarkerPositions | null = null;
 
 	public attached(param: SeriesAttachedParameter<HorzScaleItem>): void {
-		this._attached = param;
 		this._recalculateMarkers();
 		this._chart = param.chart;
 		this._series = param.series;
@@ -50,12 +48,11 @@ class SeriesMarkersPrimitive<HorzScaleItem> implements ISeriesPrimitive<HorzScal
 	}
 
 	public detached(): void {
-		if (this._attached && this._dataChangedHandler) {
-			this._attached.series.unsubscribeDataChanged(this._dataChangedHandler);
+		if (this._series && this._dataChangedHandler) {
+			this._series.unsubscribeDataChanged(this._dataChangedHandler);
 		}
 		this._chart = null;
 		this._series = null;
-		this._attached = null;
 		this._paneView = null;
 		this._dataChangedHandler = null;
 	}
@@ -122,7 +119,7 @@ class SeriesMarkersPrimitive<HorzScaleItem> implements ISeriesPrimitive<HorzScal
 		return this._autoScaleMargins;
 	}
 
-	protected _getMarkerPositions(): MarkerPositions {
+	private _getMarkerPositions(): MarkerPositions {
 		if (this._markersPositions === null) {
 			this._markersPositions = this._markers.reduce(
 				(acc: MarkerPositions, marker: SeriesMarker<HorzScaleItem>) => {
@@ -187,43 +184,3 @@ class SeriesMarkersPrimitive<HorzScaleItem> implements ISeriesPrimitive<HorzScal
 	}
 }
 
-/**
- * A function to create a series markers primitive.
- *
- * @param series - The series to which the primitive will be attached.
- *
- * @param markers - An array of markers to be displayed on the series.
- *
- * @example
- * ```js
- * import { createSeriesMarkersPrimitive } from 'lightweight-charts';
- *
- *	const seriesMarkersPrimitive = createSeriesMarkersPrimitive(
- *		series,
- *		[
- *			{
- *				color: 'green',
- *				position: 'inBar',
- * 				shape: 'arrowDown',
- *				time: 1556880900,
- *			},
- *		]
- *	);
- *  // and then you can modify the markers
- *  // set it to empty array to remove all markers
- *  seriesMarkersPrimitive.setMarkers([]);
- *
- *  // `seriesMarkersPrimitive.markers()` returns current markers
- * ```
- */
-export function createSeriesMarkersPrimitive<HorzScaleItem>(
-	series: ISeriesApi<SeriesType, HorzScaleItem>,
-	markers?: SeriesMarker<HorzScaleItem>[]
-): SeriesMarkersPrimitive<HorzScaleItem> {
-	const primitive = new SeriesMarkersPrimitive<HorzScaleItem>();
-	if (markers) {
-		primitive.setMarkers(markers);
-	}
-	series.attachPrimitive(primitive);
-	return primitive;
-}

src/plugins/series-markers/types.ts

@@ -1,5 +1,3 @@
-import { Time } from '../../model/horz-scale-behavior-time/types';
-
 /**
  * Represents the position of a series marker relative to a bar.
  */
@@ -13,7 +11,7 @@ export type SeriesMarkerShape = 'circle' | 'square' | 'arrowUp' | 'arrowDown';
 /**
  * Represents a series marker.
  */
-export interface SeriesMarker<TimeType = Time> {
+export interface SeriesMarker<TimeType> {
 	/**
 	 * The time of the marker.
 	 */
@@ -44,11 +42,6 @@ export interface SeriesMarker<TimeType = Time> {
 	 * @defaultValue `1`
 	 */
 	size?: number;
-
-	/**
-	 * @internal
-	 */
-	originalTime: unknown;
 }
 
 export type MarkerPositions = Record<SeriesMarkerPosition, boolean>;