hyperprop-charting-library 0.1.138 → 0.1.139

package/dist/hyperprop-charting-library.cjs

@@ -2853,6 +2853,7 @@ var DEFAULT_OPTIONS = {
   doubleClickAction: "reset",
   keyboard: { enabled: true, panBars: 1, deleteSelectedDrawing: true },
   accessibility: { label: "Price chart", description: "", focusable: true },
+  downsampling: { enabled: true, thresholdPx: 1.5 },
   crosshair: DEFAULT_CROSSHAIR_OPTIONS,
   grid: DEFAULT_GRID_OPTIONS,
   watermark: DEFAULT_WATERMARK_OPTIONS,
@@ -2903,6 +2904,10 @@ var mergeChartOptions = (baseOptions, options = {}) => ({
     ...baseOptions.accessibility,
     ...options.accessibility ?? {}
   },
+  downsampling: {
+    ...baseOptions.downsampling,
+    ...options.downsampling ?? {}
+  },
   crosshair: {
     ...baseOptions.crosshair,
     ...options.crosshair ?? {}
@@ -3778,6 +3783,64 @@ function createChart(element, options = {}) {
     heikinAshiFingerprint = fingerprint;
     return result;
   };
+  let compareSeriesStates = [];
+  const prepareCompareSeries = (options2) => {
+    const rows = [];
+    for (const point of options2.data ?? []) {
+      const t = new Date(point.t).getTime();
+      const c = Number(point.c);
+      if (Number.isFinite(t) && Number.isFinite(c)) rows.push({ t, c });
+    }
+    rows.sort((a, b) => a.t - b.t);
+    return {
+      options: options2,
+      times: rows.map((row) => row.t),
+      closes: rows.map((row) => row.c),
+      aligned: null,
+      alignedFingerprint: ""
+    };
+  };
+  const mainDataFingerprint = () => {
+    const last = data[data.length - 1];
+    return last ? `${data.length}|${data[0].time.getTime()}|${last.time.getTime()}` : "empty";
+  };
+  const getAlignedCompareValues = (state) => {
+    const fingerprint = `${mainDataFingerprint()}|${state.times.length}|${state.times[state.times.length - 1] ?? 0}`;
+    if (state.aligned && state.alignedFingerprint === fingerprint) {
+      return state.aligned;
+    }
+    const aligned = new Float64Array(data.length).fill(Number.NaN);
+    let cursor = 0;
+    let lastValue = Number.NaN;
+    for (let i = 0; i < data.length; i += 1) {
+      const barTime = data[i].time.getTime();
+      while (cursor < state.times.length && state.times[cursor] <= barTime) {
+        lastValue = state.closes[cursor];
+        cursor += 1;
+      }
+      aligned[i] = lastValue;
+    }
+    state.aligned = aligned;
+    state.alignedFingerprint = fingerprint;
+    return aligned;
+  };
+  const visibleCompareSeries = () => compareSeriesStates.filter((state) => state.options.visible !== false && state.times.length > 0);
+  const setCompareSeries = (series) => {
+    compareSeriesStates = (series ?? []).filter((entry) => entry && entry.id).map(prepareCompareSeries);
+    scheduleDraw({ updateAutoScale: true });
+  };
+  const addCompareSeries = (series) => {
+    if (!series?.id) return;
+    compareSeriesStates = [...compareSeriesStates.filter((state) => state.options.id !== series.id), prepareCompareSeries(series)];
+    scheduleDraw({ updateAutoScale: true });
+  };
+  const removeCompareSeries = (id) => {
+    const next = compareSeriesStates.filter((state) => state.options.id !== id);
+    if (next.length === compareSeriesStates.length) return;
+    compareSeriesStates = next;
+    scheduleDraw({ updateAutoScale: true });
+  };
+  const getCompareSeries = () => compareSeriesStates.map((state) => state.options);
   const formatHoverTimeLabel = (time, mode) => {
     if (mode === "time") {
       return time.toLocaleTimeString(void 0, {
@@ -4383,6 +4446,31 @@ function createChart(element, options = {}) {
     const chartType = mergedOptions.chartType;
     const seriesData = chartType === "heikin-ashi" ? getHeikinAshiData() : data;
     const isLineStyleChart = chartType === "line" || chartType === "area" || chartType === "baseline";
+    const comparePlans = [];
+    for (const state of visibleCompareSeries()) {
+      const aligned = getAlignedCompareValues(state);
+      let anchorIndex = -1;
+      for (let index = startIndex; index <= endIndex; index += 1) {
+        if (Number.isFinite(aligned[index] ?? Number.NaN)) {
+          anchorIndex = index;
+          break;
+        }
+      }
+      if (anchorIndex < 0) continue;
+      const baseCompare = aligned[anchorIndex];
+      const baseMain = seriesData[anchorIndex]?.c ?? 0;
+      const usePercent = (state.options.scale ?? "percent") !== "price";
+      const toPrice = usePercent && baseCompare > 0 ? (value) => baseMain * value / baseCompare : (value) => value;
+      let lastNativeValue = Number.NaN;
+      for (let index = endIndex; index >= startIndex; index -= 1) {
+        const value = aligned[index];
+        if (value !== void 0 && Number.isFinite(value)) {
+          lastNativeValue = value;
+          break;
+        }
+      }
+      comparePlans.push({ state, aligned, toPrice, usePercent, baseCompare, lastNativeValue });
+    }
     const skipLatestIndex = mergedOptions.autoScaleIgnoreLatestCandle && data.length > 1 ? data.length - 1 : -1;
     const scanCandleRange = (from, to) => {
       let min = Number.POSITIVE_INFINITY;
@@ -4428,6 +4516,23 @@ function createChart(element, options = {}) {
         maxPrice = Math.max(maxPrice, weightedMax);
       }
     }
+    for (const plan of comparePlans) {
+      if (plan.state.options.includeInAutoScale === false) continue;
+      let compareMin = Number.POSITIVE_INFINITY;
+      let compareMax = Number.NEGATIVE_INFINITY;
+      for (let index = startIndex; index <= endIndex; index += 1) {
+        const value = plan.aligned[index];
+        if (value === void 0 || !Number.isFinite(value)) continue;
+        const price = plan.toPrice(value);
+        if (!Number.isFinite(price)) continue;
+        if (price < compareMin) compareMin = price;
+        if (price > compareMax) compareMax = price;
+      }
+      if (compareMin <= compareMax) {
+        minPrice = Math.min(minPrice, compareMin);
+        maxPrice = Math.max(maxPrice, compareMax);
+      }
+    }
     const priceRange = maxPrice - minPrice || 1;
     const autoMin = minPrice - priceRange * 0.08;
     const autoMax = maxPrice + priceRange * 0.08;
@@ -5539,7 +5644,106 @@ function createChart(element, options = {}) {
       }
       return data[index]?.v;
     };
-    if (isLineStyleChart) {
+    const downsamplingOptions = mergedOptions.downsampling ?? DEFAULT_OPTIONS.downsampling;
+    const downsampleThresholdPx = Math.max(0.2, downsamplingOptions?.thresholdPx ?? 1.5);
+    const shouldDownsample = (downsamplingOptions?.enabled ?? true) && candleSpacing < downsampleThresholdPx && endIndex - startIndex > 2;
+    const seriesColumns = [];
+    if (shouldDownsample) {
+      let current = null;
+      let currentColumn = Number.NaN;
+      for (let index = startIndex; index <= endIndex; index += 1) {
+        const point = seriesData[index];
+        if (!point) continue;
+        const column = Math.round(chartLeft + (index + 0.5 - xStart) / xSpan * chartWidth);
+        if (!current || column !== currentColumn) {
+          currentColumn = column;
+          current = {
+            x: column,
+            open: point.o,
+            high: point.h,
+            low: point.l,
+            close: point.c,
+            minClose: point.c,
+            maxClose: point.c,
+            minCloseIndex: index,
+            maxCloseIndex: index
+          };
+          seriesColumns.push(current);
+          continue;
+        }
+        if (point.h > current.high) current.high = point.h;
+        if (point.l < current.low) current.low = point.l;
+        current.close = point.c;
+        if (point.c < current.minClose) {
+          current.minClose = point.c;
+          current.minCloseIndex = index;
+        }
+        if (point.c > current.maxClose) {
+          current.maxClose = point.c;
+          current.maxCloseIndex = index;
+        }
+      }
+    }
+    if (shouldDownsample && !isLineStyleChart) {
+      const upColumns = new Path2D();
+      const downColumns = new Path2D();
+      for (const column of seriesColumns) {
+        const path = column.close >= column.open ? upColumns : downColumns;
+        const x = column.x + 0.5;
+        const top = crisp(yFromPrice(column.high));
+        const bottom = crisp(yFromPrice(column.low));
+        path.moveTo(x, top);
+        path.lineTo(x, bottom === top ? bottom + 1 : bottom);
+      }
+      ctx.lineWidth = 1;
+      ctx.strokeStyle = mergedOptions.upColor;
+      ctx.stroke(upColumns);
+      ctx.strokeStyle = mergedOptions.downColor;
+      ctx.stroke(downColumns);
+    } else if (shouldDownsample && isLineStyleChart) {
+      const seriesLineWidth = Math.max(1, mergedOptions.lineWidth);
+      const linePath = new Path2D();
+      let started = false;
+      let firstX = 0;
+      let lastX = 0;
+      for (const column of seriesColumns) {
+        const lowFirst = column.minCloseIndex <= column.maxCloseIndex;
+        const first = lowFirst ? column.minClose : column.maxClose;
+        const second = lowFirst ? column.maxClose : column.minClose;
+        const x = column.x;
+        if (!started) {
+          linePath.moveTo(x, yFromPrice(first));
+          firstX = x;
+          started = true;
+        } else {
+          linePath.lineTo(x, yFromPrice(first));
+        }
+        if (second !== first) {
+          linePath.lineTo(x, yFromPrice(second));
+        }
+        lastX = x;
+      }
+      if (started) {
+        if (chartType === "area" || chartType === "baseline") {
+          const baseY = chartType === "baseline" ? yFromPrice(mergedOptions.baselinePrice ?? (yMin + yMax) / 2) : chartBottom;
+          const fillPath = new Path2D(linePath);
+          fillPath.lineTo(lastX, baseY);
+          fillPath.lineTo(firstX, baseY);
+          fillPath.closePath();
+          ctx.save();
+          ctx.globalAlpha = Math.max(0, Math.min(1, mergedOptions.areaFillOpacity));
+          ctx.fillStyle = chartType === "baseline" ? mergedOptions.upColor : mergedOptions.lineColor;
+          ctx.fill(fillPath);
+          ctx.restore();
+        }
+        ctx.save();
+        ctx.strokeStyle = chartType === "baseline" ? mergedOptions.upColor : mergedOptions.lineColor;
+        ctx.lineWidth = seriesLineWidth;
+        ctx.lineJoin = "round";
+        ctx.stroke(linePath);
+        ctx.restore();
+      }
+    } else if (isLineStyleChart) {
       const seriesLineWidth = Math.max(1, mergedOptions.lineWidth);
       const linePath = new Path2D();
       let started = false;
@@ -5705,6 +5909,105 @@ function createChart(element, options = {}) {
         ctx.stroke(downHollowBodies);
       }
     }
+    const compareAxisTags = [];
+    for (const plan of comparePlans) {
+      const color = plan.state.options.color ?? "#f59e0b";
+      const lineWidth = Math.max(1, plan.state.options.lineWidth ?? 1.5);
+      const path = new Path2D();
+      let started = false;
+      let firstX = 0;
+      let lastX = 0;
+      let lastY = 0;
+      let lastPrice = Number.NaN;
+      const emit = (x, y) => {
+        if (!started) {
+          path.moveTo(x, y);
+          firstX = x;
+          started = true;
+        } else {
+          path.lineTo(x, y);
+        }
+        lastX = x;
+        lastY = y;
+      };
+      const xForIndex = (index) => chartLeft + (index + 0.5 - xStart) / xSpan * chartWidth;
+      if (shouldDownsample) {
+        let column = Number.NaN;
+        let minValue = 0;
+        let maxValue = 0;
+        let minIndex = 0;
+        let maxIndex = 0;
+        let hasColumn = false;
+        const flushColumn = () => {
+          if (!hasColumn) return;
+          const lowFirst = minIndex <= maxIndex;
+          const first = plan.toPrice(lowFirst ? minValue : maxValue);
+          const second = plan.toPrice(lowFirst ? maxValue : minValue);
+          if (Number.isFinite(first)) emit(column, yFromPrice(first));
+          if (Number.isFinite(second) && second !== first) emit(column, yFromPrice(second));
+          lastPrice = plan.toPrice(maxIndex >= minIndex ? maxValue : minValue);
+        };
+        for (let index = startIndex; index <= endIndex; index += 1) {
+          const value = plan.aligned[index];
+          if (value === void 0 || !Number.isFinite(value)) continue;
+          const nextColumn = Math.round(xForIndex(index));
+          if (!hasColumn || nextColumn !== column) {
+            flushColumn();
+            column = nextColumn;
+            minValue = value;
+            maxValue = value;
+            minIndex = index;
+            maxIndex = index;
+            hasColumn = true;
+            continue;
+          }
+          if (value < minValue) {
+            minValue = value;
+            minIndex = index;
+          }
+          if (value > maxValue) {
+            maxValue = value;
+            maxIndex = index;
+          }
+        }
+        flushColumn();
+      } else {
+        for (let index = startIndex; index <= endIndex; index += 1) {
+          const value = plan.aligned[index];
+          if (value === void 0 || !Number.isFinite(value)) continue;
+          const price = plan.toPrice(value);
+          if (!Number.isFinite(price)) continue;
+          lastPrice = price;
+          emit(xForIndex(index), yFromPrice(price));
+        }
+      }
+      if (!started) continue;
+      if (plan.state.options.style === "area") {
+        const fillPath = new Path2D(path);
+        fillPath.lineTo(lastX, chartBottom);
+        fillPath.lineTo(firstX, chartBottom);
+        fillPath.closePath();
+        ctx.save();
+        ctx.globalAlpha = Math.max(0, Math.min(1, mergedOptions.areaFillOpacity)) * 0.6;
+        ctx.fillStyle = color;
+        ctx.fill(fillPath);
+        ctx.restore();
+      }
+      ctx.save();
+      ctx.strokeStyle = color;
+      ctx.lineWidth = lineWidth;
+      ctx.lineJoin = "round";
+      ctx.stroke(path);
+      ctx.restore();
+      if (Number.isFinite(lastPrice)) {
+        const label = plan.state.options.label ?? plan.state.options.id;
+        const nativeLast = plan.lastNativeValue;
+        const usePercentTag = plan.usePercent && plan.baseCompare > 0 && Number.isFinite(nativeLast);
+        const changePct = usePercentTag ? (nativeLast / plan.baseCompare - 1) * 100 : 0;
+        const shortText = usePercentTag ? `${changePct >= 0 ? "+" : ""}${changePct.toFixed(2)}%` : formatPrice(nativeLast);
+        compareAxisTags.push({ y: lastY, text: `${label} ${shortText}`, shortText, color });
+      }
+    }
     const activeOverlayIndicators = indicators.filter((indicator) => indicator.visible).map((indicator) => ({ indicator, plugin: indicatorRegistry.get(indicator.type) })).filter(
       (value) => value.plugin !== void 0 && (value.indicator.pane ?? value.plugin.pane ?? "overlay") === "overlay"
     ).sort((a, b) => a.indicator.zIndex - b.indicator.zIndex);
@@ -6479,6 +6782,35 @@ function createChart(element, options = {}) {
       drawText(countdownText, chartRight + 6, (fullChartBottom + height) / 2, "left", "middle", xAxis.textColor);
       ctx.font = prevFont;
     }
+    if (compareAxisTags.length > 0 && width - chartRight > 0) {
+      const prevFont = ctx.font;
+      const tagFontSize = Math.max(9, (resolvedAxis.fontSize ?? 12) - 2);
+      ctx.font = `${tagFontSize}px ${mergedOptions.fontFamily}`;
+      ctx.textBaseline = "middle";
+      ctx.textAlign = "left";
+      const placed = [];
+      const tagHeight = tagFontSize + 6;
+      const gutterWidth = width - chartRight - 4;
+      for (const tag of [...compareAxisTags].sort((a, b) => a.y - b.y)) {
+        const text = measureTextWidth(tag.text) + 10 <= gutterWidth ? tag.text : tag.shortText;
+        const tagWidth = Math.min(gutterWidth, measureTextWidth(text) + 10);
+        if (tagWidth <= 0) continue;
+        let tagY = clamp(tag.y - tagHeight / 2, chartTop, chartBottom - tagHeight);
+        for (const slot of placed) {
+          if (tagY < slot.bottom + 2 && tagY + tagHeight > slot.top - 2) {
+            tagY = slot.bottom + 2;
+          }
+        }
+        placed.push({ top: tagY, bottom: tagY + tagHeight });
+        ctx.save();
+        ctx.fillStyle = tag.color;
+        fillRoundedRect(chartRight + 2, Math.round(tagY), Math.round(tagWidth), tagHeight, 3);
+        ctx.fillStyle = labelTextColorOn(tag.color, "#ffffff");
+        ctx.fillText(text, chartRight + 7, Math.round(tagY + tagHeight / 2));
+        ctx.restore();
+      }
+      ctx.font = prevFont;
+    }
     if (baseCtx) {
       if (baseCanvas.width !== canvas.width || baseCanvas.height !== canvas.height) {
         baseCanvas.width = canvas.width;
@@ -9580,6 +9912,10 @@ function createChart(element, options = {}) {
     getMagnetMode,
     setPriceScale,
     getPriceScale,
+    setCompareSeries,
+    addCompareSeries,
+    removeCompareSeries,
+    getCompareSeries,
     cancelDrawing,
     setTradeMarkers,
     setSelectedDrawing,

package/dist/hyperprop-charting-library.d.ts

@@ -80,6 +80,7 @@ interface ChartOptions {
     doubleClickAction?: "reset" | "placeLimitOrder";
     keyboard?: KeyboardOptions;
     accessibility?: AccessibilityOptions;
+    downsampling?: DownsamplingOptions;
     crosshair?: CrosshairOptions;
     grid?: GridOptions;
     watermark?: WatermarkOptions;
@@ -552,6 +553,45 @@ interface KeyboardOptions {
     /** Delete/Backspace removes the selected drawing. Default true. */
     deleteSelectedDrawing?: boolean;
 }
+/**
+ * Deep zoom-out rendering. Once bars are narrower than `thresholdPx`, several
+ * of them share a pixel column and drawing each one is wasted work, so the
+ * chart aggregates every column into one min/max bucket: path operations then
+ * scale with the chart's width instead of the number of bars. Extremes are
+ * preserved exactly (a spike never disappears), which is why this uses
+ * min/max rather than sampling.
+ */
+interface DownsamplingOptions {
+    /** Default true. */
+    enabled?: boolean;
+    /** Bar width in pixels below which columns are aggregated. Default 1.5. */
+    thresholdPx?: number;
+}
+/**
+ * An extra instrument overlaid on the main pane ("compare" in TradingView).
+ * The host owns the data and keeps it fresh; the chart aligns it to the main
+ * series by timestamp and draws it.
+ */
+interface CompareSeriesOptions {
+    id: string;
+    /** Shown on the right-axis tag, e.g. "NQ1!". */
+    label?: string;
+    /** Bars for the compared instrument; aligned to the main series by time. */
+    data: OhlcDataPoint[];
+    color?: string;
+    lineWidth?: number;
+    style?: "line" | "area";
+    /**
+     * "percent" (default) normalises both instruments to their first visible
+     * bar so shapes can be compared regardless of nominal price — the same
+     * thing TradingView does when you add a comparison. "price" plots the raw
+     * values on the main scale, which only makes sense for related instruments.
+     */
+    scale?: "percent" | "price";
+    visible?: boolean;
+    /** Let this series widen the price scale. Default true. */
+    includeInAutoScale?: boolean;
+}
 interface AccessibilityOptions {
     /** aria-label on the canvas. Default "Price chart". */
     label?: string;
@@ -708,6 +748,17 @@ interface ChartInstance {
      */
     setPriceScale: (options: Partial<PriceScaleOptions>) => void;
     getPriceScale: () => PriceScaleOptions;
+    /**
+     * Overlay other instruments on the main pane for comparison. Series are
+     * aligned to the main series by timestamp (last known value carries forward
+     * across gaps) and, by default, normalised to percent change from the first
+     * visible bar so differently-priced instruments stay comparable. Data is not
+     * part of `saveState()` — the host re-supplies it.
+     */
+    setCompareSeries: (series: CompareSeriesOptions[]) => void;
+    addCompareSeries: (series: CompareSeriesOptions) => void;
+    removeCompareSeries: (id: string) => void;
+    getCompareSeries: () => CompareSeriesOptions[];
     cancelDrawing: () => boolean;
     setTradeMarkers: (markers: TradeMarkerOptions[]) => void;
     onDrawingHover: (handler: ((event: DrawingHoverEvent) => void) | null) => void;
@@ -897,4 +948,4 @@ declare const compileScriptIndicator: (definition: ScriptIndicatorDefinition) =>
 
 declare function createChart(element: HTMLElement, options?: ChartOptions): ChartInstance;
 
-export { type AccessibilityOptions, type AxisOptions, type BuiltInIndicatorInfo, type ChartClickEvent, type ChartContextMenuEvent, type ChartContextMenuRegion, type ChartInstance, type ChartKeyboardAction, type ChartKeyboardShortcutEvent, type ChartOptions, type ChartSavedState, type ChartType, type CrosshairMoveEvent, type CrosshairOptions, type CrosshairPriceActionEvent, type DashPatternOptions, type DrawingBounds, type DrawingDefaults, type DrawingHoverEvent, type DrawingObjectOptions, type DrawingPoint, type DrawingSelectEvent, type DrawingSelectionChangeEvent, type DrawingToolType, FIB_DEFAULT_PALETTE, type GridOptions, type IndicatorInstanceOptions, type IndicatorPane, type IndicatorPaneActionEvent, type IndicatorPaneAxisOptions, type IndicatorPaneGuideLine, type IndicatorPaneHeightChangeEvent, type IndicatorPaneRenderInfo, type IndicatorPaneValue, type IndicatorPaneValueLabel, type IndicatorPlugin, type IndicatorRenderContext, type KeyboardOptions, type LabelsOptions, type OhlcDataPoint, type OrderActionButton, type OrderActionEvent, type OrderLineOptions, POSITION_DEFAULT_COLORS, type PriceLineOptions, type PriceScaleMode, type PriceScaleOptions, SCRIPT_SOURCE_INPUT_VALUES, type ScriptComputeResult, type ScriptIndicatorDefinition, type ScriptIndicatorInputDef, type ScriptInputHelper, type ScriptInputOptions, type ScriptPlotSpec, type TickerLineOptions, type TradeMarkerOptions, type ViewportState, type WatermarkOptions, compileScriptIndicator, createChart, extractScriptInputs, validateScriptSource };
+export { type AccessibilityOptions, type AxisOptions, type BuiltInIndicatorInfo, type ChartClickEvent, type ChartContextMenuEvent, type ChartContextMenuRegion, type ChartInstance, type ChartKeyboardAction, type ChartKeyboardShortcutEvent, type ChartOptions, type ChartSavedState, type ChartType, type CompareSeriesOptions, type CrosshairMoveEvent, type CrosshairOptions, type CrosshairPriceActionEvent, type DashPatternOptions, type DownsamplingOptions, type DrawingBounds, type DrawingDefaults, type DrawingHoverEvent, type DrawingObjectOptions, type DrawingPoint, type DrawingSelectEvent, type DrawingSelectionChangeEvent, type DrawingToolType, FIB_DEFAULT_PALETTE, type GridOptions, type IndicatorInstanceOptions, type IndicatorPane, type IndicatorPaneActionEvent, type IndicatorPaneAxisOptions, type IndicatorPaneGuideLine, type IndicatorPaneHeightChangeEvent, type IndicatorPaneRenderInfo, type IndicatorPaneValue, type IndicatorPaneValueLabel, type IndicatorPlugin, type IndicatorRenderContext, type KeyboardOptions, type LabelsOptions, type OhlcDataPoint, type OrderActionButton, type OrderActionEvent, type OrderLineOptions, POSITION_DEFAULT_COLORS, type PriceLineOptions, type PriceScaleMode, type PriceScaleOptions, SCRIPT_SOURCE_INPUT_VALUES, type ScriptComputeResult, type ScriptIndicatorDefinition, type ScriptIndicatorInputDef, type ScriptInputHelper, type ScriptInputOptions, type ScriptPlotSpec, type TickerLineOptions, type TradeMarkerOptions, type ViewportState, type WatermarkOptions, compileScriptIndicator, createChart, extractScriptInputs, validateScriptSource };