Merge pull request #1856 from tradingview/feat/boundaries-price-marks

feat: boundaries price marks

Author: SlicedSilver

src/api/iprice-scale-api.ts

@@ -1,6 +1,7 @@
 import { DeepPartial } from '../helpers/strict-type-checks';
 
 import { PriceScaleOptions } from '../model/price-scale';
+import { IRange } from '../model/time-data';
 
 /** Interface to control chart's price scale */
 export interface IPriceScaleApi {
@@ -22,4 +23,25 @@ export interface IPriceScaleApi {
 	 * Returns a width of the price scale if it's visible or 0 if invisible.
 	 */
 	width(): number;
+
+	/**
+	 * Sets the visible range of the price scale.
+	 *
+	 * @param range - The visible range to set, with `from` and `to` properties.
+	 */
+	setVisibleRange(range: IRange<number>): void;
+
+	/**
+	 * Returns the visible range of the price scale.
+	 *
+	 * @returns The visible range of the price scale, or null if the range is not set.
+	 */
+	getVisibleRange(): IRange<number> | null;
+
+	/**
+	 * Sets the auto scale mode of the price scale.
+	 *
+	 * @param on - If true, enables auto scaling; if false, disables it.
+	 */
+	setAutoScale(on: boolean): void;
 }

src/api/options/price-scale-options-defaults.ts

@@ -15,4 +15,5 @@ export const priceScaleOptionsDefaults: PriceScaleOptions = {
 		top: 0.2,
 	},
 	minimumWidth: 0,
+	ensureEdgeTickMarksVisible: false,
 };

src/api/price-scale-api.ts

@@ -4,7 +4,9 @@ import { ensureNotNull } from '../helpers/assertions';
 import { DeepPartial } from '../helpers/strict-type-checks';
 
 import { isDefaultPriceScale } from '../model/default-price-scale';
+import { PriceRangeImpl } from '../model/price-range-impl';
 import { PriceScale, PriceScaleOptions } from '../model/price-scale';
+import { IRange } from '../model/time-data';
 
 import { IPriceScaleApi } from './iprice-scale-api';
 
@@ -35,6 +37,23 @@ export class PriceScaleApi implements IPriceScaleApi {
 		return this._chartWidget.getPriceAxisWidth(this._priceScaleId);
 	}
 
+	public setVisibleRange(range: IRange<number>): void {
+		this.setAutoScale(false);
+		this._priceScale().setCustomPriceRange(new PriceRangeImpl(range.from, range.to));
+	}
+
+	public getVisibleRange(): IRange<number> | null {
+		const range = this._priceScale().priceRange();
+		return range === null ? null : {
+			from: range.minValue(),
+			to: range.maxValue(),
+		};
+	}
+
+	public setAutoScale(on: boolean): void {
+		this.applyOptions({ autoScale: on });
+	}
+
 	private _priceScale(): PriceScale {
 		return ensureNotNull(this._chartWidget.model().findPriceScale(this._priceScaleId, this._paneIndex)).priceScale;
 	}

src/index.ts

@@ -18,7 +18,7 @@ export const customSeriesDefaultOptions: CustomSeriesOptions = {
 	...seriesOptionsDefaults,
 	...customStyleDefaults,
 };
-export { ICustomSeriesPaneView, ICustomSeriesPaneRenderer, CustomBarItemData, CustomData } from './model/icustom-series';
+export type { ICustomSeriesPaneView, ICustomSeriesPaneRenderer, CustomBarItemData, CustomData } from './model/icustom-series';
 
 export { createChart, createChartEx, defaultHorzScaleBehavior } from './api/create-chart';
 export { createYieldCurveChart } from './api/create-yield-curve-chart';

src/model/price-scale.ts

@@ -192,6 +192,15 @@ export interface PriceScaleOptions {
 	 * @defaultValue 0
 	 */
 	minimumWidth: number;
+
+	/**
+	 * Ensures that tick marks are always visible at the very top and bottom of the price scale,
+	 * regardless of the data range. When enabled, a tick mark will be drawn at both edges of the scale,
+	 * providing clear boundary indicators.
+	 *
+	 * @defaultValue false
+	 */
+	ensureEdgeTickMarksVisible: boolean;
 }
 
 interface RangeCache {
@@ -224,6 +233,8 @@ export class PriceScale {
 	private _priceRangeSnapshot: PriceRangeImpl | null = null;
 	private _invalidatedForRange: RangeCache = { isValid: false, visibleBars: null };
 
+	private _isCustomPriceRange: boolean = false;
+
 	private _marginAbove: number = 0;
 	private _marginBelow: number = 0;
 
@@ -251,7 +262,12 @@ export class PriceScale {
 		this._layoutOptions = layoutOptions;
 		this._localizationOptions = localizationOptions;
 		this._colorParser = colorParser;
-		this._markBuilder = new PriceTickMarkBuilder(this, 100, this._coordinateToLogical.bind(this), this._logicalToCoordinate.bind(this));
+		this._markBuilder = new PriceTickMarkBuilder(
+			this,
+			100,
+			this._coordinateToLogical.bind(this),
+			this._logicalToCoordinate.bind(this)
+		);
 	}
 
 	public id(): string {
@@ -295,6 +311,10 @@ export class PriceScale {
 		return this._options.autoScale;
 	}
 
+	public isCustomPriceRange(): boolean {
+		return this._isCustomPriceRange;
+	}
+
 	public isLog(): boolean {
 		return this._options.mode === PriceScaleMode.Logarithmic;
 	}
@@ -307,6 +327,10 @@ export class PriceScale {
 		return this._options.mode === PriceScaleMode.IndexedTo100;
 	}
 
+	public getLogFormula(): LogFormula {
+		return this._logFormula;
+	}
+
 	public mode(): PriceScaleState {
 		return {
 			autoScale: this._options.autoScale,
@@ -422,6 +446,11 @@ export class PriceScale {
 		this._priceRange = newPriceRange;
 	}
 
+	public setCustomPriceRange(newPriceRange: PriceRangeImpl | null): void {
+		this.setPriceRange(newPriceRange);
+		this._toggleCustomPriceRange(newPriceRange !== null);
+	}
+
 	public isEmpty(): boolean {
 		this._makeSureItIsValid();
 		return this._height === 0 || !this._priceRange || this._priceRange.isEmpty();
@@ -792,6 +821,14 @@ export class PriceScale {
 		this._dataSources.forEach((s: IPriceDataSource) => s.updateAllViews());
 	}
 
+	public hasVisibleEdgeMarks(): boolean {
+		return this._options.ensureEdgeTickMarksVisible && this.isAutoScale();
+	}
+
+	public getEdgeMarksPadding(): number {
+		return this.fontSize() / 2;
+	}
+
 	public updateFormatter(): void {
 		this._marksCache = null;
 
@@ -842,6 +879,10 @@ export class PriceScale {
 		return this._colorParser;
 	}
 
+	private _toggleCustomPriceRange(v: boolean): void {
+		this._isCustomPriceRange = v;
+	}
+
 	private _topMarginPx(): number {
 		return this.isInverted()
 			? this._options.scaleMargins.bottom * this.height() + this._marginBelow
@@ -899,6 +940,10 @@ export class PriceScale {
 
 	// eslint-disable-next-line complexity
 	private _recalculatePriceRangeImpl(): void {
+		if (this.isCustomPriceRange() && !this.isAutoScale()) {
+			return;
+		}
+
 		const visibleBars = this._invalidatedForRange.visibleBars;
 		if (visibleBars === null) {
 			return;
@@ -952,6 +997,11 @@ export class PriceScale {
 			}
 		}
 
+		if (this.hasVisibleEdgeMarks()) {
+			marginAbove = Math.max(marginAbove, this.getEdgeMarksPadding());
+			marginBelow = Math.max(marginBelow, this.getEdgeMarksPadding());
+		}
+
 		if (marginAbove !== this._marginAbove || marginBelow !== this._marginBelow) {
 			this._marginAbove = marginAbove;
 			this._marginBelow = marginBelow;
@@ -1001,8 +1051,6 @@ export class PriceScale {
 				this._logFormula = logFormulaForPriceRange(null);
 			}
 		}
-
-		this._invalidatedForRange.isValid = true;
 	}
 
 	private _getCoordinateTransformer(): PriceTransformer | null {

src/model/price-tick-mark-builder.ts

@@ -1,7 +1,9 @@
+import { ensure } from '../helpers/assertions';
 import { min } from '../helpers/mathex';
 
 import { Coordinate } from './coordinate';
 import { PriceMark, PriceScale } from './price-scale';
+import { convertPriceRangeFromLog } from './price-scale-conversions';
 import { PriceTickSpanCalculator } from './price-tick-span-calculator';
 
 export type CoordinateToLogicalConverter = (x: number, firstValue: number) => number;
@@ -74,12 +76,51 @@ export class PriceTickMarkBuilder {
 
 		const high = Math.max(bottom, top);
 		const low = Math.min(bottom, top);
+
 		if (high === low) {
 			this._marks = [];
 			return;
 		}
 
-		let span = this.tickSpan(high, low);
+		const span = this.tickSpan(high, low);
+		this._updateMarks(
+			firstValue,
+			span,
+			high,
+			low,
+			minCoord,
+			maxCoord
+		);
+
+		if (priceScale.hasVisibleEdgeMarks() && this._shouldApplyEdgeMarks(span, low, high)) {
+			const padding = this._priceScale.getEdgeMarksPadding();
+			this._applyEdgeMarks(
+				firstValue,
+				span,
+				minCoord,
+				maxCoord,
+				padding,
+				padding * 2
+			);
+		}
+	}
+
+	public marks(): PriceMark[] {
+		return this._marks;
+	}
+
+	private _fontHeight(): number {
+		return this._priceScale.fontSize();
+	}
+
+	private _tickMarkHeight(): number {
+		return Math.ceil(this._fontHeight() * TICK_DENSITY);
+	}
+
+	private _updateMarks(firstValue: number, span: number, high: number, low: number, minCoord: number, maxCoord: number): void {
+		const marks = this._marks;
+		const priceScale = this._priceScale;
+
 		let mod = high % span;
 		mod += mod < 0 ? span : 0;
 
@@ -102,11 +143,11 @@ export class PriceTickMarkBuilder {
 				continue;
 			}
 
-			if (targetIndex < this._marks.length) {
-				this._marks[targetIndex].coord = coord as Coordinate;
-				this._marks[targetIndex].label = priceScale.formatLogical(logical);
+			if (targetIndex < marks.length) {
+				marks[targetIndex].coord = coord as Coordinate;
+				marks[targetIndex].label = priceScale.formatLogical(logical);
 			} else {
-				this._marks.push({
+				marks.push({
 					coord: coord as Coordinate,
 					label: priceScale.formatLogical(logical),
 				});
@@ -120,18 +161,77 @@ export class PriceTickMarkBuilder {
 				span = this.tickSpan(logical * sign, low);
 			}
 		}
-		this._marks.length = targetIndex;
+
+		marks.length = targetIndex;
 	}
 
-	public marks(): PriceMark[] {
-		return this._marks;
+	private _applyEdgeMarks(
+		firstValue: number,
+		span: number,
+		minCoord: number,
+		maxCoord: number,
+		minPadding: number,
+		maxPadding: number
+	): void {
+		const marks = this._marks;
+		// top boundary
+		const topMark = this._computeBoundaryPriceMark(
+			firstValue,
+			minCoord,
+			minPadding,
+			maxPadding
+		);
+
+		// bottom boundary
+		const bottomMark = this._computeBoundaryPriceMark(
+			firstValue,
+			maxCoord,
+			-maxPadding,
+			-minPadding
+		);
+
+		const spanPx = this._logicalToCoordinateFunc(0, firstValue, true)
+			- this._logicalToCoordinateFunc(span, firstValue, true);
+
+		if (marks.length > 0 && marks[0].coord - topMark.coord < spanPx / 2) {
+			marks.shift();
+		}
+
+		if (marks.length > 0 && bottomMark.coord - marks[marks.length - 1].coord < spanPx / 2) {
+			marks.pop();
+		}
+
+		marks.unshift(topMark);
+		marks.push(bottomMark);
 	}
 
-	private _fontHeight(): number {
-		return this._priceScale.fontSize();
+	private _computeBoundaryPriceMark(
+		firstValue: number,
+		coord: number,
+		minPadding: number,
+		maxPadding: number
+	): PriceMark {
+		const avgPadding = (minPadding + maxPadding) / 2;
+		const value1 = this._coordinateToLogicalFunc(coord + minPadding, firstValue);
+		const value2 = this._coordinateToLogicalFunc(coord + maxPadding, firstValue);
+		const minValue = Math.min(value1, value2);
+		const maxValue = Math.max(value1, value2);
+		const valueSpan = Math.max(0.1, this.tickSpan(maxValue, minValue));
+
+		const value = this._coordinateToLogicalFunc(coord + avgPadding, firstValue);
+		const roundedValue = value - (value % valueSpan);
+		const roundedCoord = this._logicalToCoordinateFunc(roundedValue, firstValue, true);
+
+		return { label: this._priceScale.formatLogical(roundedValue), coord: roundedCoord as Coordinate };
 	}
 
-	private _tickMarkHeight(): number {
-		return Math.ceil(this._fontHeight() * TICK_DENSITY);
+	private _shouldApplyEdgeMarks(span: number, low: number, high: number): boolean {
+		let range = ensure(this._priceScale.priceRange());
+
+		if (this._priceScale.isLog()) {
+			range = convertPriceRangeFromLog(range, this._priceScale.getLogFormula());
+		}
+
+		return (range.minValue() - low < span) && (high - range.maxValue() < span);
 	}
 }