@pipsend/charts 2.0.1 → 2.2.0

package/README.md

@@ -18,6 +18,7 @@ Simple • Powerful • Framework-Agnostic • TypeScript • Production-Ready
 - [Installation](#-installation)
 - [Quick Start](#-quick-start)
 - [Demo & Examples](#-demo--examples)
+- [Chart Types](#-chart-types)
 - [Available Technical Indicators](#-available-technical-indicators)
 - [Interactive Trading Lines API](#-interactive-trading-lines-api)
 - [Framework Integration Examples](#-framework-integration-examples)
@@ -228,6 +229,75 @@ document.getElementById('btnAlert').onclick = async () => {
 
 ---
 
+## 📈 Chart Types
+
+Every series is added with `chart.addSeries(<Type>, options?, paneIndex?)`.
+
+| Series | Import | Data shape |
+|---|---|---|
+| Candlestick | `CandlestickSeries` | `{ time, open, high, low, close }` |
+| Bar (OHLC) | `BarSeries` | `{ time, open, high, low, close }` |
+| Line | `LineSeries` | `{ time, value }` |
+| Area | `AreaSeries` | `{ time, value }` |
+| Baseline | `BaselineSeries` | `{ time, value }` |
+| Histogram | `HistogramSeries` | `{ time, value, color? }` |
+| Custom | `chart.addCustomSeries(paneView)` | your own |
+
+### Heikin Ashi
+
+Heikin Ashi is a transform of the OHLC bars, not a separate series type, so it
+is applied on top of an existing candlestick or bar series:
+
+```javascript
+import { createChart, CandlestickSeries, applyHeikinAshi } from '@pipsend/charts';
+
+const series = chart.addSeries(CandlestickSeries);
+series.setData(bars);
+
+const ha = applyHeikinAshi(series, chart);
+
+// Back to regular candles
+ha.remove();
+```
+
+The source series keeps its real prices and is only painted transparent, not
+hidden: indicators bound to it keep computing on the true OHLC, its price lines
+and primitives (positions, alerts, drawings) stay on screen, and `remove()`
+restores the chart exactly as it was — which makes this usable as a chart-type
+toggle. New bars pushed to the source are transformed automatically.
+
+The same trick is exported as `hideSeriesPaint(series)` for drawing any other
+view over a series: it blanks the paint, leaves the series visible to the engine,
+and returns a function that puts the paint back.
+
+Colors can be changed on a running transform, and are the candlestick ones:
+
+```javascript
+applyHeikinAshi(series, chart, {
+    upColor: '#26a69a',
+    downColor: '#ef5350',
+    borderVisible: true,
+    wickVisible: true,
+    hideSource: true,   // set false to draw over the raw candles
+    paneIndex: 0
+});
+```
+
+If you only want the numbers — to feed a different series, or to compute on them
+— use the transform on its own:
+
+```javascript
+import { calculateHeikinAshi } from '@pipsend/charts';
+
+const haBars = calculateHeikinAshi(bars);
+```
+
+Each Heikin Ashi bar folds in the one before it, so the result depends on where
+the data starts. Pass the whole series rather than a recent window when you can;
+the difference decays over a few bars.
+
+---
+
 ## 📊 Available Technical Indicators
 
 ### Overlay Indicators (appear on main chart)

package/dist/pipsend-charts.development.mjs

@@ -1,6 +1,6 @@
 /*!
  * @license
- * Pipsend Charts v2.0.1
+ * Pipsend Charts v2.2.0
  * Copyright (c) 2026 Pipsend
  * Licensed under MIT License
  * Built on TradingView Lightweight Charts™ (Apache 2.0)
@@ -15520,6 +15520,85 @@ function hasSeriesVolumes(series) {
     return volumes !== undefined && volumes.size > 0;
 }
 
+const TRANSPARENT = 'rgba(0, 0, 0, 0)';
+/**
+ * Take a series off the screen without hiding it.
+ *
+ * `visible: false` takes down everything hung off the series as well: its
+ * price lines, primitives and price-axis label stop rendering. A transform
+ * that only wants the bars themselves out of the way — Heikin Ashi drawing
+ * over its source — needs the series to stay visible to the engine, so its
+ * paint is made transparent instead and the last-value label and price line
+ * are switched off. Custom series have no known colours; those fall back to
+ * `visible: false`.
+ *
+ * @param series - Series to blank out.
+ * @returns Puts back the options the series had when it was blanked.
+ */
+function hideSeriesPaint(series) {
+    switch (series.seriesType()) {
+        case 'Candlestick':
+            return blank(series, {
+                upColor: TRANSPARENT,
+                downColor: TRANSPARENT,
+                borderVisible: false,
+                wickVisible: false,
+            });
+        case 'Bar':
+            return blank(series, {
+                upColor: TRANSPARENT,
+                downColor: TRANSPARENT,
+            });
+        case 'Line':
+            return blank(series, {
+                color: TRANSPARENT,
+                crosshairMarkerVisible: false,
+                pointMarkersVisible: false,
+            });
+        case 'Area':
+            return blank(series, {
+                lineColor: TRANSPARENT,
+                topColor: TRANSPARENT,
+                bottomColor: TRANSPARENT,
+                crosshairMarkerVisible: false,
+                pointMarkersVisible: false,
+            });
+        case 'Baseline':
+            return blank(series, {
+                topLineColor: TRANSPARENT,
+                topFillColor1: TRANSPARENT,
+                topFillColor2: TRANSPARENT,
+                bottomLineColor: TRANSPARENT,
+                bottomFillColor1: TRANSPARENT,
+                bottomFillColor2: TRANSPARENT,
+                crosshairMarkerVisible: false,
+                pointMarkersVisible: false,
+            });
+        case 'Histogram':
+            return blank(series, {
+                color: TRANSPARENT,
+            });
+        default:
+            return blank(series, { visible: false });
+    }
+}
+function blank(series, paint) {
+    const patch = {
+        ...paint,
+        lastValueVisible: false,
+        priceLineVisible: false,
+    };
+    const before = series.options();
+    const snapshot = {};
+    for (const key of Object.keys(patch)) {
+        snapshot[key] = before[key];
+    }
+    series.applyOptions(patch);
+    return () => {
+        series.applyOptions(snapshot);
+    };
+}
+
 /**
  * Pins a bounded indicator (RSI, Stochastic…) to a fixed price range.
  *
@@ -17154,6 +17233,168 @@ function applyPivotPoints(series, chart, options = {}) {
     };
 }
 
+function isOhlc(bar) {
+    return bar !== null
+        && bar !== undefined
+        && typeof bar.close === 'number';
+}
+/**
+ * Turns raw OHLC bars into Heikin Ashi ones.
+ *
+ * Heikin Ashi is a price transform, not an overlay: each candle averages itself
+ * with the one before it, which drops most of the single-bar noise and leaves
+ * runs of same-coloured bodies while a trend holds.
+ *
+ * ```
+ * close = (O + H + L + C) / 4
+ * open  = (previous open + previous close) / 2      // first bar: (O + C) / 2
+ * high  = max(H, open, close)
+ * low   = min(L, open, close)
+ * ```
+ *
+ * Because every bar folds in the one before it, the result depends on where the
+ * data starts: the same bar computed from a longer history differs slightly.
+ * The difference decays over a few bars, so pass the whole series rather than a
+ * recent window when you can.
+ *
+ * Whitespace items are passed through untouched, and do not advance the
+ * running open/close — a gap in the data is not a bar.
+ *
+ * @param bars - Source bars, ordered oldest to newest.
+ * @returns The transformed bars, one per input item.
+ */
+function calculateHeikinAshi(bars) {
+    const result = [];
+    let previousOpen = null;
+    let previousClose = null;
+    for (const bar of bars) {
+        if (!isOhlc(bar)) {
+            if (bar !== null && bar !== undefined) {
+                result.push({ time: bar.time, customValues: bar.customValues });
+            }
+            continue;
+        }
+        const haClose = (bar.open + bar.high + bar.low + bar.close) / 4;
+        const haOpen = previousOpen === null || previousClose === null
+            ? (bar.open + bar.close) / 2
+            : (previousOpen + previousClose) / 2;
+        result.push({
+            time: bar.time,
+            open: haOpen,
+            high: Math.max(bar.high, haOpen, haClose),
+            low: Math.min(bar.low, haOpen, haClose),
+            close: haClose,
+            customValues: bar.customValues,
+        });
+        previousOpen = haOpen;
+        previousClose = haClose;
+    }
+    return result;
+}
+/**
+ * Draw a source series as Heikin Ashi candles.
+ *
+ * The source series is left in place holding its real prices — it is only
+ * painted transparent — so indicators bound to it keep computing on the true
+ * OHLC, its price lines and primitives stay on screen, and `remove()` puts the
+ * chart back exactly as it was. That makes this usable as a chart-type toggle:
+ *
+ * ```js
+ * const ha = applyHeikinAshi(candleSeries, chart);
+ * // …back to regular candles:
+ * ha.remove();
+ * ```
+ *
+ * @param series - Source OHLC series (a candlestick or bar series).
+ * @param chart - Chart instance.
+ * @param options - Heikin Ashi configuration options.
+ * @returns The Heikin Ashi candlestick series, plus live control over its options.
+ */
+function applyHeikinAshi(series, chart, options = {}) {
+    const resolved = {
+        paneIndex: options.paneIndex ?? 0,
+        upColor: options.upColor ?? '#26a69a',
+        downColor: options.downColor ?? '#ef5350',
+        borderVisible: options.borderVisible ?? true,
+        borderUpColor: options.borderUpColor ?? '#26a69a',
+        borderDownColor: options.borderDownColor ?? '#ef5350',
+        wickVisible: options.wickVisible ?? true,
+        wickUpColor: options.wickUpColor ?? '#26a69a',
+        wickDownColor: options.wickDownColor ?? '#ef5350',
+        hideSource: options.hideSource ?? true,
+    };
+    const sourceOptions = series.options();
+    // Same price scale and the same formatting as the source: the candles are a
+    // restatement of that series, not a second instrument, so they must not
+    // autoscale on their own axis or round to a different precision.
+    const haSeries = chart.addSeries(candlestickSeries, {
+        upColor: resolved.upColor,
+        downColor: resolved.downColor,
+        borderVisible: resolved.borderVisible,
+        borderUpColor: resolved.borderUpColor,
+        borderDownColor: resolved.borderDownColor,
+        wickVisible: resolved.wickVisible,
+        wickUpColor: resolved.wickUpColor,
+        wickDownColor: resolved.wickDownColor,
+        priceScaleId: sourceOptions.priceScaleId,
+        priceFormat: sourceOptions.priceFormat,
+    }, resolved.paneIndex);
+    let restoreSourcePaint = null;
+    const blankSource = (blank) => {
+        if (blank && restoreSourcePaint === null) {
+            restoreSourcePaint = hideSeriesPaint(series);
+        }
+        else if (!blank && restoreSourcePaint !== null) {
+            restoreSourcePaint();
+            restoreSourcePaint = null;
+        }
+    };
+    const runtime = bindIndicator({
+        _internal_source: series,
+        _internal_chart: chart,
+        _internal_outputs: [haSeries],
+        _internal_label: 'Heikin Ashi',
+        _internal_options: resolved,
+        // Every option here is a colour or a toggle on the series itself, so a
+        // change never needs the transform run again.
+        _internal_recomputeOn: [],
+        _internal_compute: (data) => [
+            [haSeries, calculateHeikinAshi(data)],
+        ],
+        _internal_applyStyle: (current) => {
+            haSeries.applyOptions({
+                upColor: current.upColor,
+                downColor: current.downColor,
+                borderVisible: current.borderVisible,
+                borderUpColor: current.borderUpColor,
+                borderDownColor: current.borderDownColor,
+                wickVisible: current.wickVisible,
+                wickUpColor: current.wickUpColor,
+                wickDownColor: current.wickDownColor,
+            });
+            blankSource(current.hideSource === true);
+        },
+    });
+    const handle = {
+        _internal_series: haSeries,
+        options: runtime.options,
+        applyOptions: runtime.applyOptions,
+        recalculate: runtime.recalculate,
+        remove: () => {
+            runtime.remove();
+            // The source outlives the indicator, so its paint is ours to put
+            // back — otherwise removing a Heikin Ashi overlay leaves a blank chart.
+            try {
+                blankSource(false);
+            }
+            catch (error) {
+                // The series may already be gone if the chart was disposed
+            }
+        },
+    };
+    return handle;
+}
+
 /**
  * Apply RSI indicator to a series
  * @param series - Source series to calculate RSI from
@@ -29212,7 +29453,7 @@ const customSeriesDefaultOptions = {
  * Returns the current version as a string. For example `'1.0.0'`.
  */
 function version() {
-    return "2.0.1";
+    return "2.2.0";
 }
 
-export { areaSeries as AreaSeries, ArrowTool, barSeries as BarSeries, baselineSeries as BaselineSeries, BrushTool, candlestickSeries as CandlestickSeries, CircleTool, ColorType, CrossLineTool, CrosshairMode, DEFAULT_SESSIONS, DraggablePriceLine, DrawingToolsManager, EXTENDED_FIBONACCI_RATIOS, FibonacciCalculator, FibonacciExtensionTool, FibonacciFanTool, FibonacciTool, GanttTool, histogramSeries as HistogramSeries, HorizontalLineTool, InteractiveLineManager, LastPriceAnimationMode, lineSeries as LineSeries, LineStyle, LineType, MismatchDirection, ParallelChannelTool, PitchforkTool, PolygonTool, PositionCalculator, PositionMarkersManager, PositionTool, PriceLineSource, PriceScaleMode, RectangleTool, RulerCalculator, RulerTool, STANDARD_FIBONACCI_RATIOS, TextTool, TickMarkType, TrackingModeExitMode, TradingSessionsIndicator, TrendLineTool, VerticalLineTool, VolumeProfileIndicator, applyADX, applyATR, applyBollingerBands, applyCCI, applyDonchianChannels, applyEMA, applyIchimoku, applyKeltnerChannels, applyMACD, applyMFI, applyOBV, applyParabolicSAR, applyPivotPoints, applyRSI, applySMA, applyStochastic, applySuperTrend, applyVWAP, applyVolume, applyWMA, applyWilliamsR, calculatePipConfig, coordinateFromTime, createArrowTool, createBrushTool, createChart, createChartEx, createCircleTool, createCrossLineTool, createFibonacciExtensionTool, createFibonacciFanTool, createFibonacciTool, createGanttTool, createHorizontalLineTool, createImageWatermark, createInteractiveLineManager, createOptionsChart, createParallelChannelTool, createPitchforkTool, createPolygonTool, createPositionMarkers, createPositionTool, createRectangleTool, createRulerTool, createSeriesMarkers, createTextTool, createTextWatermark, createTradingLine, createTradingSessionsIndicator, createTrendLineTool, createUpDownMarkers, createVerticalLineTool, createVolumeProfileIndicator, createYieldCurveChart, customSeriesDefaultOptions, defaultHorzScaleBehavior, getPipConfig, isBusinessDay, isUTCTimestamp, setSeriesVolumes, setVolumeProfileData, timeFromCoordinate, version };
+export { areaSeries as AreaSeries, ArrowTool, barSeries as BarSeries, baselineSeries as BaselineSeries, BrushTool, candlestickSeries as CandlestickSeries, CircleTool, ColorType, CrossLineTool, CrosshairMode, DEFAULT_SESSIONS, DraggablePriceLine, DrawingToolsManager, EXTENDED_FIBONACCI_RATIOS, FibonacciCalculator, FibonacciExtensionTool, FibonacciFanTool, FibonacciTool, GanttTool, histogramSeries as HistogramSeries, HorizontalLineTool, InteractiveLineManager, LastPriceAnimationMode, lineSeries as LineSeries, LineStyle, LineType, MismatchDirection, ParallelChannelTool, PitchforkTool, PolygonTool, PositionCalculator, PositionMarkersManager, PositionTool, PriceLineSource, PriceScaleMode, RectangleTool, RulerCalculator, RulerTool, STANDARD_FIBONACCI_RATIOS, TextTool, TickMarkType, TrackingModeExitMode, TradingSessionsIndicator, TrendLineTool, VerticalLineTool, VolumeProfileIndicator, applyADX, applyATR, applyBollingerBands, applyCCI, applyDonchianChannels, applyEMA, applyHeikinAshi, applyIchimoku, applyKeltnerChannels, applyMACD, applyMFI, applyOBV, applyParabolicSAR, applyPivotPoints, applyRSI, applySMA, applyStochastic, applySuperTrend, applyVWAP, applyVolume, applyWMA, applyWilliamsR, calculateHeikinAshi, calculatePipConfig, coordinateFromTime, createArrowTool, createBrushTool, createChart, createChartEx, createCircleTool, createCrossLineTool, createFibonacciExtensionTool, createFibonacciFanTool, createFibonacciTool, createGanttTool, createHorizontalLineTool, createImageWatermark, createInteractiveLineManager, createOptionsChart, createParallelChannelTool, createPitchforkTool, createPolygonTool, createPositionMarkers, createPositionTool, createRectangleTool, createRulerTool, createSeriesMarkers, createTextTool, createTextWatermark, createTradingLine, createTradingSessionsIndicator, createTrendLineTool, createUpDownMarkers, createVerticalLineTool, createVolumeProfileIndicator, createYieldCurveChart, customSeriesDefaultOptions, defaultHorzScaleBehavior, getPipConfig, hideSeriesPaint, isBusinessDay, isUTCTimestamp, setSeriesVolumes, setVolumeProfileData, timeFromCoordinate, version };