Merge pull request #1934 from cll-355_overlay-histogram

Add Dual Range Histogram Series plugin example

Author: SlicedSilver

plugin-examples/package-lock.json

@@ -26,16 +26,17 @@ <h2>Combined Examples</h2>
         <h2>Custom Series</h2>
 		<ul>
             <li><a href="./plugins/brushable-area-series/example/">Brushable Area Series</a></li>
+			<li><a href="./plugins/dual-range-histogram-series/example/">Dual Range Histogram Series</a></li>
             <li><a href="./plugins/grouped-bars-series/example/">GroupedBars Series</a></li>
             <li>Heatmap Series: <a href="./plugins/heatmap-series/example/">Example 1</a> / <a href="./plugins/heatmap-series/example/example2.html">Example 2</a></li>
             <li><a href="./plugins/hlc-area-series/example/">HLC Area Series</a></li>
             <li><a href="./plugins/pretty-histogram/example/">Pretty Histogram</a></li>
             <li><a href="./plugins/lollipop-series/example/">Lollipop Series</a></li>
 			<li><a href="./plugins/rounded-candles-series/example/">Rounded Candle Series</a></li>
-            <li><a href="./plugins/background-shade-series/example/">Shaded Background Series</a></li>
+			<li><a href="./plugins/background-shade-series/example/">Shaded Background Series</a></li>
 			<li><a href="./plugins/stacked-area-series/example/">Stacked Area Series</a></li>
 			<li><a href="./plugins/stacked-bars-series/example/">Stacked Bars Series</a></li>
-            <li><a href="./plugins/box-whisker-series/example/">Whisker Box Series</a></li>
+			<li><a href="./plugins/box-whisker-series/example/">Whisker Box Series</a></li>
 		</ul>
         <h2>Primitives</h2>
 		<ul>

plugin-examples/src/index.html

@@ -0,0 +1,114 @@
+export type LeftTopRightTopRightBottomLeftBottomRadii = [
+	number,
+	number,
+	number,
+	number
+];
+
+function changeBorderRadius(
+	borderRadius: LeftTopRightTopRightBottomLeftBottomRadii,
+	offset: number
+): typeof borderRadius {
+	return borderRadius.map((x: number) =>
+		x === 0 ? x : x + offset
+	) as typeof borderRadius;
+}
+
+export function drawRoundRect(
+	// eslint-disable-next-line max-params
+	ctx: CanvasRenderingContext2D,
+	x: number,
+	y: number,
+	w: number,
+	h: number,
+	radii: LeftTopRightTopRightBottomLeftBottomRadii
+): void {
+	/**
+	 * As of May 2023, all of the major browsers now support ctx.roundRect() so we should
+	 * be able to switch to the native version soon.
+	 */
+	ctx.beginPath();
+	if (ctx.roundRect) {
+		ctx.roundRect(x, y, w, h, radii);
+		return;
+	}
+	/*
+	 * Deprecate the rest in v5.
+	 */
+	ctx.lineTo(x + w - radii[1], y);
+	if (radii[1] !== 0) {
+		ctx.arcTo(x + w, y, x + w, y + radii[1], radii[1]);
+	}
+
+	ctx.lineTo(x + w, y + h - radii[2]);
+	if (radii[2] !== 0) {
+		ctx.arcTo(x + w, y + h, x + w - radii[2], y + h, radii[2]);
+	}
+
+	ctx.lineTo(x + radii[3], y + h);
+	if (radii[3] !== 0) {
+		ctx.arcTo(x, y + h, x, y + h - radii[3], radii[3]);
+	}
+
+	ctx.lineTo(x, y + radii[0]);
+	if (radii[0] !== 0) {
+		ctx.arcTo(x, y, x + radii[0], y, radii[0]);
+	}
+}
+
+/**
+ * Draws a rounded rect with a border.
+ *
+ * This function assumes that the colors will be solid, without
+ * any alpha. (This allows us to fix a rendering artefact.)
+ *
+ * @param outerBorderRadius - The radius of the border (outer edge)
+ */
+// eslint-disable-next-line max-params
+export function drawRoundRectWithBorder(
+	ctx: CanvasRenderingContext2D,
+	left: number,
+	top: number,
+	width: number,
+	height: number,
+	backgroundColor: string,
+	borderWidth: number = 0,
+	outerBorderRadius: LeftTopRightTopRightBottomLeftBottomRadii = [0, 0, 0, 0],
+	borderColor: string = ''
+): void {
+	ctx.save();
+
+	if (!borderWidth || !borderColor || borderColor === backgroundColor) {
+		drawRoundRect(ctx, left, top, width, height, outerBorderRadius);
+		ctx.fillStyle = backgroundColor;
+		ctx.fill();
+		ctx.restore();
+		return;
+	}
+
+	const halfBorderWidth = borderWidth / 2;
+	const radii = changeBorderRadius(outerBorderRadius, -halfBorderWidth);
+
+	drawRoundRect(
+		ctx,
+		left + halfBorderWidth,
+		top + halfBorderWidth,
+		width - borderWidth,
+		height - borderWidth,
+		radii
+	);
+
+	if (backgroundColor !== 'transparent') {
+		ctx.fillStyle = backgroundColor;
+		ctx.fill();
+	}
+
+	if (borderColor !== 'transparent') {
+		ctx.lineWidth = borderWidth;
+		ctx.strokeStyle = borderColor;
+		ctx.closePath();
+		ctx.stroke();
+	}
+
+	ctx.restore();
+}

plugin-examples/src/plugins/dual-range-histogram-series/canvas-utils.ts

@@ -0,0 +1,8 @@
+import { CustomData } from 'lightweight-charts';
+
+/**
+ * DualRangeHistogram Series Data
+ */
+export interface DualRangeHistogramData extends CustomData {
+	values: number[];
+}

plugin-examples/src/plugins/dual-range-histogram-series/data.ts

@@ -0,0 +1,43 @@
+import {
+	CustomSeriesPricePlotValues,
+	ICustomSeriesPaneView,
+	PaneRendererCustomData,
+	WhitespaceData,
+	Time,
+} from 'lightweight-charts';
+import { DualRangeHistogramSeriesOptions, defaultOptions } from './options';
+import { DualRangeHistogramSeriesRenderer } from './renderer';
+import { DualRangeHistogramData } from './data';
+
+export class DualRangeHistogramSeries<TData extends DualRangeHistogramData>
+	implements ICustomSeriesPaneView<Time, TData, DualRangeHistogramSeriesOptions>
+{
+	_renderer: DualRangeHistogramSeriesRenderer<TData>;
+
+	constructor() {
+		this._renderer = new DualRangeHistogramSeriesRenderer();
+	}
+
+	priceValueBuilder(): CustomSeriesPricePlotValues {
+		return [0]; // keep zero line in view with autoscaling
+	}
+
+	isWhitespace(data: TData | WhitespaceData): data is WhitespaceData {
+		return !Boolean((data as Partial<TData>).values?.length);
+	}
+
+	renderer(): DualRangeHistogramSeriesRenderer<TData> {
+		return this._renderer;
+	}
+
+	update(
+		data: PaneRendererCustomData<Time, TData>,
+		options: DualRangeHistogramSeriesOptions
+	): void {
+		this._renderer.update(data, options);
+	}
+
+	defaultOptions() {
+		return defaultOptions;
+	}
+}

plugin-examples/src/plugins/dual-range-histogram-series/dual-range-histogram-series.ts

@@ -0,0 +1,57 @@
+import { BaselineSeries, createChart } from 'lightweight-charts';
+import { DualRangeHistogramSeries } from '../dual-range-histogram-series';
+import { generateLineData, shuffleValuesWithLimit } from '../../../sample-data';
+import { centerLineData, generateDualRangeHistogramData } from './sample-data';
+
+const numberPoints = 200;
+
+const chart = ((window as unknown as any).chart = createChart('chart', {
+	autoSize: true,
+	timeScale: {
+		minBarSpacing: 4,
+		barSpacing: 21,
+	},
+}));
+
+const dualRangeHistogramSeriesView = new DualRangeHistogramSeries();
+const dualRangeHistogramSeries = chart.addCustomSeries(
+	dualRangeHistogramSeriesView,
+	{
+		/* Options */
+		color: 'black', // for the price line,
+		priceLineVisible: false,
+		lastValueVisible: false,
+	}
+);
+
+const data = generateDualRangeHistogramData(numberPoints);
+dualRangeHistogramSeries.setData(data);
+
+const baselineSeries = chart.addSeries(BaselineSeries, {
+	baseValue: { type: 'price', price: 0 },
+});
+const lineData = centerLineData(
+	shuffleValuesWithLimit(generateLineData(numberPoints), 3)
+);
+baselineSeries.setData(lineData);
+
+// The following code is for ensuring that the histogram remains in view
+// because we are purposely not telling the library the priceValues so
+// it doesn't adjust the price scale normally. This is so we can keep the
+// series on the zero line of the main price scale but not affect it's scaling
+function setPriceScaleMargins(): void {
+	const { height } = chart.paneSize();
+	const seriesHeight = dualRangeHistogramSeries.options().maxHeight;
+	const margin = Math.min(0.3, seriesHeight / 2 / height);
+	dualRangeHistogramSeries.priceScale().applyOptions({
+		scaleMargins: {
+			top: margin,
+			bottom: margin,
+		},
+	});
+}
+const resizeObserver = new ResizeObserver(_ => {
+	setPriceScaleMargins();
+});
+resizeObserver.observe(chart.chartElement());
+setPriceScaleMargins();

plugin-examples/src/plugins/dual-range-histogram-series/example/example.ts

@@ -0,0 +1,31 @@
+<!DOCTYPE html>
+<html lang="en">
+	<head>
+		<meta charset="UTF-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+		<title>Lightweight Charts - DualRangeHistogram Series Plugin Example</title>
+		<link href="../../../examples-base.css" rel="stylesheet" />
+	</head>
+	<body>
+		<div id="chart"></div>
+		<div id="description">
+			<h1>Dual Range Histogram Series</h1>
+			<p>
+				The Dual Range Histogram is a versatile column-based visualisation
+				designed to represent paired positive and negative value ranges for each
+				time point. Each group of columns consists of two positive (upward)
+				bars—typically differentiated by light and dark shades—and two negative
+				(downward) bars, also in contrasting shades. The lighter columns
+				represent the total extent of a metric (such as run-up or drawdown),
+				while the darker columns indicate a subset or related component that
+				must always be less than or equal to the corresponding lighter column.
+				This structure allows for clear comparison between total and partial
+				values within both positive and negative domains. The Dual Range
+				Histogram is well-suited for financial analysis, performance
+				backtesting, or any scenario where it is useful to visualise both the
+				magnitude and composition of upward and downward movements over time.
+			</p>
+		</div>
+		<script type="module" src="./example.ts"></script>
+	</body>
+</html>

plugin-examples/src/plugins/dual-range-histogram-series/example/index.html

@@ -0,0 +1,35 @@
+import { LineData, WhitespaceData } from 'lightweight-charts';
+import { multipleBarData } from '../../../sample-data';
+import { DualRangeHistogramData } from '../data';
+
+export function centerLineData(lineData: LineData[]): LineData[] {
+	const lineDataValues = lineData.map(i => i.value);
+	const min = Math.min(...lineDataValues);
+	const max = Math.max(...lineDataValues);
+	const mid = (max - min) / 2 + min;
+	const adjustedLineData = lineData.map(i => {
+		return {
+			...i,
+			value: i.value - mid,
+		};
+	});
+	return adjustedLineData;
+}
+
+export function generateDualRangeHistogramData(
+	numberPoints: number
+): (DualRangeHistogramData | WhitespaceData)[] {
+	return multipleBarData(4, numberPoints, 20).map(datum => {
+		const positiveValues = datum.values.slice(0, 2).sort().reverse();
+		positiveValues[1] *= 0.5 + Math.random() * 0.5;
+		const negativeValues = datum.values
+			.slice(2)
+			.sort()
+			.map(i => -1 * i);
+		negativeValues[1] *= 0.5 + Math.random() * 0.5;
+		return {
+			...datum,
+			values: [...positiveValues, ...negativeValues],
+		};
+	});
+}

plugin-examples/src/plugins/dual-range-histogram-series/example/sample-data.ts

@@ -0,0 +1,17 @@
+import {
+	CustomSeriesOptions,
+	customSeriesDefaultOptions,
+} from 'lightweight-charts';
+
+export interface DualRangeHistogramSeriesOptions extends CustomSeriesOptions {
+	colors: readonly string[];
+	borderRadius: readonly number[];
+	maxHeight: number;
+}
+
+export const defaultOptions: DualRangeHistogramSeriesOptions = {
+	...customSeriesDefaultOptions,
+	colors: ['#ACE5DC', '#42BDA8', '#FCCACD', '#F77C80'],
+	borderRadius: [2, 0, 2, 0],
+	maxHeight: 130,
+} as const;