@stocksharp/trading-controls 1.2.0 → 1.4.0

package/src/option-smile-widget.ts

@@ -0,0 +1,281 @@
+// Option smile — multi-instance.
+//
+// One expiry's implied volatility against strike, call side and put side as two curves on one
+// scale, drawn by @stocksharp/chart.
+//
+// The engine is a time-series engine and this axis is a ladder of strikes, which looked at first
+// like a reason to draw the chart by hand. It is not: the axis carries numbers, and what turns
+// them into dates is `timeScale.formatter` - one function shared by the tick labels and the
+// crosshair label. Given a formatter that words a number as a strike, the axis is a strike axis,
+// and the crosshair, the legend readout, the zoom and the pan come with it rather than being
+// written again here.
+//
+// `mode: 'ordinal'` on top of that, because a listed chain is evenly spaced by listing rather
+// than by the gaps between its numbers: a venue that lists 67000, 67250 and then 68000 means
+// three rungs, not a hole.
+import { formatPrice } from './formatters.js';
+import { makeElement, makeIconButton, makePanelId, makePanelRoot } from './dom.js';
+import { ControlTypes } from './control-types.js';
+import { TradingHost, assertHost } from './trading-host.js';
+import type { OptionChainContext, OptionSide, OptionStrike } from './option-desk-widget.js';
+import {
+    CrosshairMode, LineSeries, createChart,
+    type CrosshairEvent, type IChartApi, type ISeriesApi, type LineData, type Time,
+} from './chart-engine.js';
+
+/// What the panel needs beyond the host port. Nothing: a smile is read, not acted on.
+export interface OptionSmileDeps {
+    host: TradingHost;
+}
+
+const LINE_WIDTH = 2;
+
+/// The volatility a side is drawn at: what it last traded at, or the middle of its quote when it
+/// has not traded. Null when neither is known - a strike nobody has quoted is a gap in the curve,
+/// and a line drawn through it invents a quote nobody made.
+export function sideVolatility(side: OptionSide | undefined): number | null {
+    if (side === undefined || side === null) return null;
+
+    const last = side.ivLast;
+    if (typeof last === 'number' && isFinite(last) && last > 0) return last;
+
+    const bid = side.ivBid;
+    const ask = side.ivAsk;
+    const quoted = [bid, ask].filter((v): v is number => typeof v === 'number' && isFinite(v) && v > 0);
+    if (quoted.length === 0) return null;
+    return quoted.reduce((sum, v) => sum + v, 0) / quoted.length;
+}
+
+/// The chain in the order it is drawn: by strike, lowest first, whatever order it arrived in.
+export function sortedChain(strikes: readonly OptionStrike[]): OptionStrike[] {
+    return [...strikes]
+        .filter(row => row !== null && row !== undefined && isFinite(row.strike))
+        .sort((a, b) => a.strike - b.strike);
+}
+
+/// One side as a series, and the strikes it was drawn at.
+///
+/// The x value is the strike itself rather than an index: the axis words it back through the
+/// formatter, so the number on the wire and the number on the label are the same one and no
+/// lookup can put them out of step.
+export function toSmileSeries(chain: readonly OptionStrike[], put: boolean): LineData[] {
+    const out: LineData[] = [];
+    for (const row of chain) {
+        const volatility = sideVolatility(put ? row.put : row.call);
+        // Whitespace rather than a point: the engine keeps the rung on the axis and leaves the
+        // line broken across it, which is what a strike quoted on one side only looks like.
+        if (volatility === null) out.push({ time: row.strike as Time } as LineData);
+        else out.push({ time: row.strike as Time, value: volatility * 100 });
+    }
+    return out;
+}
+
+export class OptionSmileWidget {
+    static TYPE = ControlTypes.OptionSmile;
+
+    rootEl: HTMLElement;
+    // `//` rather than `///` from here down — see the note in positions-widget.
+    _host: TradingHost;
+    _closeBtn: HTMLElement | null;
+    _resetBtn: HTMLElement | null;
+    _emptyEl: HTMLElement | null;
+    _chartEl: HTMLElement | null;
+    _spotEl: HTMLElement | null;
+    _hoverEl: HTMLElement | null;
+    _chart: IChartApi | null;
+    _call: ISeriesApi<LineData> | null;
+    _put: ISeriesApi<LineData> | null;
+    _strikes: OptionStrike[];
+    _context: OptionChainContext;
+    _resizeObserver: ResizeObserver | null;
+
+    static create(hostEl: HTMLElement, state: Record<string, unknown>, deps: OptionSmileDeps): OptionSmileWidget {
+        const host = assertHost(deps?.host, 'OptionSmileWidget');
+        const root = OptionSmileWidget._buildRoot(host);
+        root.id = makePanelId(OptionSmileWidget.TYPE);
+        hostEl.appendChild(root);
+        return new OptionSmileWidget(root, state || {}, deps);
+    }
+
+    static _buildRoot(host: TradingHost): HTMLElement {
+        const title = host.t('OptionSmile');
+        return makePanelRoot('option-smile-panel', title, [
+            makeElement('div', 'panel-header', {}, [
+                makeElement('span', '', {}, [title]),
+                makeIconButton('bt-icon-btn option-smile-reset-btn', host.t('ResetView'), 'bi-arrow-clockwise', { type: 'button' }),
+                makeIconButton('bt-icon-btn bt-icon-cancel panel-close-btn', host.t('ClosePanel'), 'bi-x', { type: 'button' }),
+            ]),
+            makeElement('div', 'panel-body', {}, [
+                makeElement('div', 'option-smile-legend', {}, [
+                    makeElement('span', 'option-smile-axis', {}, [host.t('ImpliedVolatility')]),
+                    makeElement('span', 'option-smile-key', {}, [
+                        makeElement('span', 'option-smile-dot option-smile-dot-call', {}, []),
+                        host.t('Call'),
+                    ]),
+                    makeElement('span', 'option-smile-key', {}, [
+                        makeElement('span', 'option-smile-dot option-smile-dot-put', {}, []),
+                        host.t('Put'),
+                    ]),
+                    makeElement('span', 'option-smile-spot', {}, []),
+                ]),
+                makeElement('div', 'option-smile-chart', { role: 'img', 'aria-label': host.t('OptionChain') }, [
+                    // Over the chart, not in the panel header: a reading about the point under the
+                    // pointer belongs beside that point, and a host that lifts panel headers into a
+                    // tab strip would otherwise write it into a tab title.
+                    makeElement('div', 'option-smile-hover', {}, []),
+                    makeElement('div', 'option-smile-empty', {}, [host.t('NoOptions')]),
+                ]),
+            ]),
+        ]);
+    }
+
+    constructor(rootEl: HTMLElement, _state: Record<string, unknown>, deps: OptionSmileDeps) {
+        this._host = assertHost(deps?.host, 'OptionSmileWidget');
+
+        this.rootEl = rootEl;
+        this._closeBtn = this.rootEl.querySelector('.panel-close-btn');
+        this._resetBtn = this.rootEl.querySelector('.option-smile-reset-btn');
+        this._emptyEl = this.rootEl.querySelector('.option-smile-empty');
+        this._chartEl = this.rootEl.querySelector('.option-smile-chart');
+        this._spotEl = this.rootEl.querySelector('.option-smile-spot');
+        this._hoverEl = this.rootEl.querySelector('.option-smile-hover');
+        this._chart = null;
+        this._call = null;
+        this._put = null;
+        this._strikes = [];
+        this._context = {};
+        this._resizeObserver = null;
+
+        this._closeBtn?.addEventListener('click', (e) => { e.preventDefault(); this._host.close(); });
+        this._resetBtn?.addEventListener('click', (e) => { e.preventDefault(); this.resetZoom(); });
+
+        if (this._chartEl !== null && typeof ResizeObserver !== 'undefined') {
+            this._resizeObserver = new ResizeObserver(() => this._fit());
+            this._resizeObserver.observe(this._chartEl);
+        }
+
+        this._render();
+        this._host.register(this);
+    }
+
+    dispose(): void {
+        try { this._resizeObserver?.disconnect(); } catch { /* already torn down */ }
+        this._resizeObserver = null;
+        try { this._chart?.remove(); } catch { /* already gone */ }
+        this._chart = null;
+        this._call = null;
+        this._put = null;
+        this._host.unregister(this);
+        try { this.rootEl.remove(); } catch { /* already detached */ }
+    }
+
+    /// Show this chain, priced against this context.
+    ///
+    /// The desk's two arguments unchanged, and for the same reason it takes them together: they
+    /// are one observation. A smile marked with a spot the curves never saw is two moments.
+    update(strikes: OptionStrike[], context: OptionChainContext = {}): void {
+        this._strikes = strikes || [];
+        this._context = context || {};
+        this._render();
+    }
+
+    /// Show the whole chain again, after a zoom.
+    resetZoom(): void {
+        try { this._chart?.timeScale().fitContent(); } catch { /* no chart yet */ }
+    }
+
+    /// The engine, for a host that wants to add to this chart - a second expiry, a marker.
+    chart(): IChartApi | null {
+        return this._chart;
+    }
+
+    _ensureChart(): boolean {
+        if (this._chart !== null) return true;
+        if (this._chartEl === null) return false;
+
+        const palette = this._host.presentation.canvasPalette();
+        this._chart = createChart(this._chartEl, {
+            layout: {
+                background: { type: 'solid', color: 'transparent' },
+                textColor: palette.grid,
+                fontFamily: palette.font,
+                fontSize: 11,
+                attributionLogo: false,
+            },
+            grid: { vertLines: { color: palette.grid }, horzLines: { color: palette.grid } },
+            crosshair: { mode: CrosshairMode.Normal },
+            rightPriceScale: { borderColor: palette.grid },
+            timeScale: {
+                borderColor: palette.grid,
+                // Evenly spaced by listing, and worded as strikes: the axis carries the strike
+                // itself, so the label and the value can never drift apart.
+                mode: 'ordinal',
+                formatter: (value: Time) => formatPrice(Number(value)),
+            },
+        });
+
+        this._call = this._chart.addSeries(LineSeries, { lineWidth: LINE_WIDTH, color: palette.up });
+        this._put = this._chart.addSeries(LineSeries, { lineWidth: LINE_WIDTH, color: palette.down });
+        this._chart.subscribeCrosshairMove((param) => this._renderHover(param));
+        return true;
+    }
+
+    _render(): void {
+        const chain = sortedChain(this._strikes);
+        const quoted = chain.some(row =>
+            sideVolatility(row.call) !== null || sideVolatility(row.put) !== null);
+
+        if (this._emptyEl !== null) this._emptyEl.hidden = quoted;
+        this._renderSpot();
+        if (!quoted) return;
+        if (!this._ensureChart() || this._call === null || this._put === null) return;
+
+        this._call.setData(toSmileSeries(chain, false));
+        this._put.setData(toSmileSeries(chain, true));
+        this._fit();
+    }
+
+    _fit(): void {
+        if (this._chart === null || this._chartEl === null) return;
+        const rect = this._chartEl.getBoundingClientRect();
+        if (rect.width <= 0 || rect.height <= 0) return;
+        try {
+            this._chart.resize(rect.width, rect.height);
+        } catch { /* the engine is between frames */ }
+    }
+
+    // Where the money is. Not a line on the chart: an ordinal axis has a rung per listed strike
+    // and the spot is between two of them, so it is stated rather than drawn at a place the
+    // ladder does not have.
+    _renderSpot(): void {
+        const el = this._spotEl;
+        if (el === null) return;
+
+        const spot = this._context.assetPrice;
+        if (typeof spot !== 'number' || !isFinite(spot)) {
+            el.textContent = '';
+            return;
+        }
+        el.textContent = `${this._host.t('Underlying')} ${formatPrice(spot)}`;
+    }
+
+    // What the pointer is over: the strike and both sides at it. Both, because a smile is read by
+    // the distance between the two curves - a readout naming one of them answers half of it.
+    _renderHover(param: CrosshairEvent): void {
+        const el = this._hoverEl;
+        if (el === null) return;
+
+        if (param.time === null) {
+            el.textContent = '';
+            return;
+        }
+
+        const at = (series: ISeriesApi<LineData> | null): string => {
+            const point = series === null ? undefined : param.seriesData.get(series);
+            const value = (point as { value?: number } | undefined)?.value;
+            return typeof value === 'number' && isFinite(value) ? `${value.toFixed(2)}%` : '--';
+        };
+
+        el.textContent = `${formatPrice(Number(param.time))}  ${at(this._call)} / ${at(this._put)}`;
+    }
+}

package/src/pnl-curve.ts

@@ -0,0 +1,216 @@
+// The geometry of a cumulative P&L curve, as pure functions over numbers.
+//
+// The same curve is read in three places and drawn at three sizes: a strategy row's sparkline,
+// a statistics card, and a backtest's own chart. Only the last of those is a price chart - it
+// shares the price axis and belongs to the chart engine. The other two are a curve in a box,
+// and this is that curve: where each point lands, where the baseline sits, and which way the
+// run ended. No canvas, so it can be checked against arithmetic rather than against pixels.
+
+/// One sample of a run's cumulative P&L. Time is whatever the caller counts in - seconds, unix
+/// milliseconds - because only the spacing between samples is used, never the absolute value.
+export interface PnlPoint {
+    time: number;
+    value: number;
+}
+
+/// The box one curve fills, in device pixels. The padding keeps a curve at its extreme off the
+/// edge, where a stroke would be clipped in half.
+export interface PnlBox {
+    width: number;
+    height: number;
+    padX: number;
+    padY: number;
+}
+
+export interface PnlCurve {
+    /// The curve, in draw order.
+    points: [number, number][];
+    /// The curve closed down to the baseline, ready to fill.
+    area: [number, number][];
+    /// Y of zero P&L. Always inside the box: the range is widened to include it.
+    zeroY: number;
+    /// The value range the box covers, zero included.
+    min: number;
+    max: number;
+    /// The stretch of time the box covers. Compression keeps the run's first and last samples
+    /// exactly, so these are where it started and where it stands - which is what lets a panel
+    /// wide enough for a time axis date both ends without laying the run out a second time.
+    from: number;
+    to: number;
+    /// The value the run ended at. `positive` is this figure's sign; a panel with room to print
+    /// a number wants the figure.
+    last: number;
+    /// Whether the run ended at or above where it started. What the curve is coloured by - and
+    /// the last value, not the highest: a run that peaked and gave it all back is a loss.
+    positive: boolean;
+}
+
+/// A run reduced to at most `count` samples, spanning the same stretch of time.
+///
+/// A sparkline that keeps only the newest N samples marches sideways: each new sample pushes the
+/// oldest off the left edge, so the shape slides and the run's beginning is lost. Compressing
+/// instead keeps the whole run in the box and re-buckets it, so a new sample changes the curve's
+/// shape rather than its position - which is what makes two readings of the same strategy
+/// comparable.
+///
+/// A bucket is summarised by its LAST sample, not by an average. This is a cumulative figure:
+/// the last value in a bucket is where the run actually stood at that moment, while an average
+/// would draw a rising run below the line it was on. Every point returned is therefore a real
+/// sample, never a computed one, and the first and last are kept exactly - they are where the
+/// run started and where it stands now.
+export function compressPnl(points: readonly PnlPoint[], count: number): PnlPoint[] {
+    if (points.length <= count || count < 2) return points.slice();
+
+    const first = points[0];
+    const last = points[points.length - 1];
+    const span = last.time - first.time;
+
+    // Every sample at the same instant: there is no time to bucket by, so fall back to position.
+    if (!(span > 0)) {
+        const step = (points.length - 1) / (count - 1);
+        return Array.from({ length: count }, (_, i) => points[Math.round(i * step)]);
+    }
+
+    // One bucket per output point, the last sample in each standing for it. Buckets that caught
+    // nothing are skipped rather than repeated, so a quiet stretch reads as a long flat segment
+    // instead of as a row of identical points.
+    // `count - 1` buckets, not `count`: the first sample is seeded and the last is appended, so
+    // the buckets between them may contribute at most `count - 2` points. Sized any wider the
+    // result can overrun `count`, and trimming it afterwards would drop the run's start - the
+    // one point this function exists to keep.
+    const buckets = count - 1;
+    const out: PnlPoint[] = [first];
+    let bucket = 0;
+    for (let i = 1; i < points.length; i++) {
+        const index = Math.min(buckets - 1, Math.floor(((points[i].time - first.time) / span) * buckets));
+        if (index > bucket) {
+            out.push(points[i - 1]);
+            bucket = index;
+        }
+    }
+    if (out[out.length - 1] !== last) out.push(last);
+
+    return out;
+}
+
+/// Lay a run out in a box, or null when there is no curve to draw.
+///
+/// Two rules that are not arbitrary. Zero is always in the range, so a run that only ever won
+/// still shows the line it started from and the height of the curve means something. And the
+/// horizontal axis is time, not sample index: a strategy that traded twice in the morning and
+/// forty times after lunch should look like that, not like a curve with evenly spaced steps.
+export function pnlCurve(points: readonly PnlPoint[], box: PnlBox): PnlCurve | null {
+    const clean = points
+        .filter(p => p !== null && p !== undefined && Number.isFinite(p.time) && Number.isFinite(p.value))
+        .slice()
+        .sort((a, b) => a.time - b.time);
+
+    if (clean.length < 2) return null;
+
+    // One sample per drawable pixel is as much as a box can show; past that the extra points are
+    // strokes on top of strokes. Compressing here rather than asking the caller to do it is what
+    // lets a host keep the whole run and still get a curve that does not slide.
+    const drawable = Math.max(2, Math.round(box.width - box.padX * 2));
+    const shown = compressPnl(clean, drawable);
+
+    const values = shown.map(p => p.value);
+    const min = Math.min(0, ...values);
+    const max = Math.max(0, ...values);
+
+    const left = box.padX;
+    const right = box.width - box.padX;
+    const top = box.padY;
+    const bottom = box.height - box.padY;
+
+    const firstTime = shown[0].time;
+    const lastTime = shown[shown.length - 1].time;
+    const timeSpan = lastTime - firstTime;
+    const valueSpan = max - min;
+
+    // A run with no spread in one axis collapses onto a line rather than dividing by nothing:
+    // every sample at the same instant stacks at the left edge, every sample at the same value
+    // rests on the top edge, which for a flat run is also its baseline.
+    const x = (time: number): number => (timeSpan === 0 ? left : left + ((time - firstTime) / timeSpan) * (right - left));
+    const y = (value: number): number => (valueSpan === 0 ? top : bottom - ((value - min) / valueSpan) * (bottom - top));
+
+    const curve = shown.map(p => [x(p.time), y(p.value)] as [number, number]);
+    const zeroY = y(0);
+    const last = shown[shown.length - 1].value;
+
+    return {
+        points: curve,
+        // Closed along the baseline rather than along the foot of the box: a run entirely above
+        // water fills the gap between itself and zero, and nothing below it.
+        area: [...curve, [curve[curve.length - 1][0], zeroY], [curve[0][0], zeroY]],
+        zeroY,
+        min,
+        max,
+        from: firstTime,
+        to: lastTime,
+        last,
+        positive: last >= 0,
+    };
+}
+
+/// What a curve is drawn with. Colours come from the caller because the page owns its palette;
+/// the two directions are the same pair every other control uses for up and down.
+export interface PnlCurveStyle {
+    up: string;
+    down: string;
+    /// The zero line. A curve is read against it, so it is drawn even when nothing crosses it.
+    baseline: string;
+    lineWidth: number;
+    /// How much of the direction colour the filled area keeps, 0 to 1.
+    fillOpacity: number;
+}
+
+/// The 2D calls one paint makes. Narrow on purpose: a test supplies a recorder, and a control
+/// that started reaching for something else shows up here rather than in a screenshot.
+export interface PnlCurveContext {
+    clearRect(x: number, y: number, w: number, h: number): void;
+    beginPath(): void;
+    moveTo(x: number, y: number): void;
+    lineTo(x: number, y: number): void;
+    closePath(): void;
+    stroke(): void;
+    fill(): void;
+    setLineDash(segments: number[]): void;
+    globalAlpha: number;
+    // The browser's own type for these, so a real 2D context satisfies this contract as
+    // it stands: it accepts a gradient or a pattern where this only ever writes a colour.
+    strokeStyle: string | CanvasGradient | CanvasPattern;
+    fillStyle: string | CanvasGradient | CanvasPattern;
+    lineWidth: number;
+}
+
+/// Paint a laid-out curve: the baseline, the filled area under it, then the line itself.
+export function drawPnlCurve(ctx: PnlCurveContext, curve: PnlCurve, box: PnlBox, style: PnlCurveStyle): void {
+    const colour = curve.positive ? style.up : style.down;
+
+    ctx.clearRect(0, 0, box.width, box.height);
+
+    ctx.setLineDash([2, 3]);
+    ctx.strokeStyle = style.baseline;
+    ctx.lineWidth = 1;
+    ctx.beginPath();
+    ctx.moveTo(box.padX, curve.zeroY);
+    ctx.lineTo(box.width - box.padX, curve.zeroY);
+    ctx.stroke();
+    ctx.setLineDash([]);
+
+    ctx.globalAlpha = style.fillOpacity;
+    ctx.fillStyle = colour;
+    ctx.beginPath();
+    ctx.moveTo(curve.area[0][0], curve.area[0][1]);
+    for (const [px, py] of curve.area.slice(1)) ctx.lineTo(px, py);
+    ctx.closePath();
+    ctx.fill();
+    ctx.globalAlpha = 1;
+
+    ctx.strokeStyle = colour;
+    ctx.lineWidth = style.lineWidth;
+    ctx.beginPath();
+    ctx.moveTo(curve.points[0][0], curve.points[0][1]);
+    for (const [px, py] of curve.points.slice(1)) ctx.lineTo(px, py);
+    ctx.stroke();
+}