openalgo-charts 1.0.1 → 1.0.3

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 /** Library version string. Matches package.json (published npm release). */
-declare const VERSION = "1.0.1";
+declare const VERSION = "1.0.3";
 /** Returns the current library version. */
 declare function version(): string;
 
@@ -220,6 +220,18 @@ declare class TimeScale {
     xToIndex(x: number): number;
     /** Currently visible logical index range (fractional, unclamped to data). */
     visibleRange(): LogicalRange;
+    /** Alias of `visibleRange()` for naming parity with common charting APIs. */
+    getVisibleLogicalRange(): LogicalRange;
+    /**
+     * Set the visible logical range (best effort): pick a bar spacing so the span
+     * fills the width and anchor the right edge at `range.to`. Bar spacing is
+     * clamped to [min,max], so an extreme span lands at the nearest zoom. Fires the
+     * change handler so a host that mutates the scale directly still repaints.
+     */
+    setVisibleLogicalRange(range: LogicalRange): void;
+    /** Repaint hook injected by the host chart, fired after `setVisibleLogicalRange`. */
+    setChangeHandler(fn: (() => void) | null): void;
+    private _onChange;
     /**
      * Pan by a pixel delta. Positive `dx` drags chart content to the right
      * (revealing older bars), matching a natural left-button drag.
@@ -351,8 +363,18 @@ interface SeriesStyle {
     hollow?: boolean;
     /** Scale candle body width by volume / maxVisibleVolume (volume candles). */
     volumeScaled?: boolean;
+    /** Whether the series is drawn and counted in autoscale. Default true. */
+    visible?: boolean;
+    /** Optional label carried with the series (for host-drawn legends). */
+    title?: string;
+    /** Show the dashed horizontal last-price line across the plot. Default true. */
+    priceLineVisible?: boolean;
+    /** Show the last-value tag on the price axis. Default true. */
+    lastValueVisible?: boolean;
     color?: string;
     lineWidth?: number;
+    /** Line dash style for line/step/area/HLC series. Default 'solid'. */
+    lineStyle?: 'solid' | 'dashed' | 'dotted';
     step?: boolean;
     markers?: boolean;
     markerRadius?: number;
@@ -385,6 +407,18 @@ interface ChartTheme {
     axisText: string;
     axisLine: string;
     crosshair: string;
+    /** Axis label font size in px (default 11). */
+    axisFontSize?: number;
+    /** Grid line dash style (default 'solid'). */
+    gridStyle?: 'solid' | 'dashed' | 'dotted';
+    /** Crosshair line dash style (default 'dashed'). */
+    crosshairStyle?: 'solid' | 'dashed' | 'dotted';
+    /** Crosshair line width in device px (default 1 = hairline). */
+    crosshairWidth?: number;
+    /** Background of the crosshair value tags (defaults to `crosshair`). */
+    crosshairLabelBackground?: string;
+    /** Show the crosshair price/time value tags (default true). */
+    crosshairLabelVisible?: boolean;
     upColor: string;
     downColor: string;
     wickUpColor: string;
@@ -526,10 +560,17 @@ declare class SeriesMarkers implements IPrimitive {
  * so the core never switches on type.
  */
 
+/**
+ * Which price axis a series maps to. 'right' (default) and 'left' each draw an
+ * axis and autoscale independently; '' is a hidden overlay scale (no axis, its
+ * own autoscale) used to pin a volume histogram inside the price pane.
+ */
+type PriceScaleId = 'right' | 'left' | '';
 interface SeriesRecord {
     dataId: SeriesId;
     type: SeriesType;
     style: SeriesStyle;
+    scaleId: PriceScaleId;
 }
 /** Public handle returned by `chart.addSeries(...)`. */
 interface SeriesApi {
@@ -541,10 +582,30 @@ interface SeriesApi {
     update(bar: SeriesDataItem): void;
     /** Current bars for this series (sorted old -> new, normalized to OHLC). Handy for computing the next live update. */
     getData(): Bar[];
+    /** Merge a partial style into the series and repaint (recolor, `{ visible:false }` to hide, ...). */
+    applyOptions(style: Partial<SeriesStyle>): void;
+    /** Remove the series from its pane and free its data rows. */
+    remove(): void;
+    /** The price scale this series maps to (call `.setOptions({ marginTop, marginBottom })` on it). */
+    priceScale(): PriceScale;
     /** Create a markers layer (buy/sell signals, shapes) bound to this series. */
     createMarkers(): SeriesMarkers;
 }
 
+/**
+ * Axis label rendering (ARCHITECTURE.md §6, §5.3). Price axis (right strip) and
+ * time axis (bottom strip). Time labels switch from clock to date at IST day
+ * boundaries; gaps are already collapsed by the logical-index time scale.
+ */
+
+/**
+ * Boundary class of a time-axis label, passed to a custom `timeFormatter` as a
+ * hint so a host can render adaptive labels (year at year boundaries, month at
+ * month boundaries, day otherwise, clock intraday) — parity with common
+ * `tickMarkFormatter(time, tickMarkType)` APIs.
+ */
+type TickMarkType = 'year' | 'month' | 'day' | 'time' | 'timeWithSeconds';
+
 /**
  * A pane is one vertically-stacked drawing region (price pane, volume pane,
  * indicator pane). It owns a base + top canvas (ARCHITECTURE.md §3.1) and a
@@ -556,6 +617,8 @@ interface PaneRenderContext {
     dataLayer: DataLayer;
     dpr: number;
     priceAxisWidth: number;
+    /** Left inset (px) reserved chart-wide for a left price axis; 0/absent when none. */
+    leftAxisWidth?: number;
     timeAxisHeight: number;
     /** Only the bottom pane draws the time axis. */
     showTimeAxis: boolean;
@@ -570,13 +633,16 @@ interface PaneRenderContext {
     /** Draw the horizontal (price) grid lines. */
     showHorzGrid: boolean;
     /** Optional custom time label formatter (UTC seconds -> string). Defaults to IST. */
-    timeFormatter?: (utcSeconds: number) => string;
+    timeFormatter?: (utcSeconds: number, tickMark?: TickMarkType) => string;
 }
 declare class Pane {
     readonly element: HTMLElement;
     readonly base: CanvasLayer;
     readonly top: CanvasLayer;
     readonly priceScale: PriceScale;
+    /** Extra scales created on demand: left axis and a hidden overlay (volume). */
+    private _leftScale;
+    private _overlayScale;
     /** Relative height weight within the chart (price=1, volume≈0.3). */
     weight: number;
     private readonly _series;
@@ -585,6 +651,14 @@ declare class Pane {
     private _height;
     constructor(doc: Document);
     addSeries(record: SeriesRecord): void;
+    /** The PriceScale for a scale id, creating the left/overlay scale on first use. */
+    private _scaleFor;
+    /** The price scale a series maps to (for the series handle's `priceScale()`). */
+    scaleOf(record: SeriesRecord): PriceScale;
+    /** True when a left-axis scale is active (some series maps to it). */
+    hasLeftScale(): boolean;
+    /** Remove a series record if present; returns true if it was found. */
+    removeSeries(record: SeriesRecord): boolean;
     series(): readonly SeriesRecord[];
     addPrimitive(primitive: IPrimitive, host: PrimitiveHost): void;
     /** Remove a primitive if present; returns true if it was found. */
@@ -596,8 +670,9 @@ declare class Pane {
     hitTestPrimitives(x: number, y: number, ctx: PaneRenderContext): PrimitiveHit | null;
     resize(width: number, height: number, dpr: number): void;
     private _layout;
-    /** Recompute the price range from the visible bars of all series in this pane. */
+    /** Autoscale each active price scale from its own series (independent axes). */
     autoscale(ctx: PaneRenderContext): void;
+    private _autoscaleScale;
     /** Paint background + grid + series + axes on the base canvas. */
     paintBase(ctx: PaneRenderContext): void;
     /**
@@ -1014,14 +1089,37 @@ interface ChartOptions {
      * omitted, labels use IST (Indian market default). e.g. for UTC:
      * `(s) => new Date(s * 1000).toISOString().slice(11, 16)`.
      */
-    timeFormatter?: (utcSeconds: number) => string;
+    timeFormatter?: (utcSeconds: number, tickMark?: TickMarkType) => string;
 }
 interface AddSeriesOptions {
     /** Target pane index (0 = price). Higher panes are created on demand. */
     paneIndex?: number;
     /** Style overrides merged onto the chart type's defaults. */
     style?: SeriesStyle;
+    /**
+     * Which price axis this series maps to. 'right' (default) and 'left' each draw
+     * an axis and autoscale independently; '' is a hidden overlay scale (no axis)
+     * for a volume histogram inside the price pane.
+     */
+    priceScaleId?: PriceScaleId;
+    /**
+     * Value formatting applied to this series' price scale (axis + crosshair tag):
+     * `price` (tick-size precision), `volume` (compact 1.2K / 3.4M / 5.6B), or a
+     * `custom` formatter (currency, percent, ...).
+     */
+    priceFormat?: {
+        type: 'price';
+        precision?: number;
+        minMove?: number;
+    } | {
+        type: 'volume';
+    } | {
+        type: 'custom';
+        formatter: (value: number) => string;
+    };
 }
+/** Compact volume/number formatter (1.2K / 3.4M / 5.6B). */
+declare function compactVolume(v: number): string;
 /**
  * Emitted on every crosshair move (and `null` fields on pointer-leave) so a host
  * can render an OHLC legend / tooltip. `bar` is the hovered bar of the primary
@@ -1047,7 +1145,7 @@ declare class Chart {
     private readonly _container;
     private readonly _doc;
     private readonly _pixelRatio;
-    private readonly _theme;
+    private _theme;
     private readonly _panes;
     private readonly _loop;
     private readonly _dataLayer;
@@ -1106,6 +1204,7 @@ declare class Chart {
     private _priceFormatter;
     private _priceScaleOptions;
     private _timeFormatter;
+    private _leftAxisWidth;
     constructor(container: HTMLElement, options?: ChartOptions);
     /** Register a callback fired when the user pans near the left (oldest) edge. */
     setHistoryLoader(loader: () => void): void;
@@ -1113,6 +1212,12 @@ declare class Chart {
     historyLoadComplete(): void;
     get dataLayer(): DataLayer;
     get timeScale(): TimeScale;
+    /** Restore a saved logical range (e.g. preserve the user's zoom across a data reload). */
+    setVisibleLogicalRange(range: LogicalRange): void;
+    /** The current visible logical range. */
+    getVisibleLogicalRange(): LogicalRange;
+    /** Fit all bars into view (no-arg convenience; bar count from the data). */
+    fitContent(): void;
     /** The keyboard shortcut manager (null when shortcuts are disabled). */
     get shortcuts(): ShortcutManager | null;
     /**
@@ -1203,12 +1308,30 @@ declare class Chart {
      * Set a custom time-axis + crosshair label formatter (UTC seconds -> string)
      * at runtime. Pass undefined to restore the IST default.
      */
-    setTimeFormatter(fn: ((utcSeconds: number) => string) | undefined): void;
+    setTimeFormatter(fn: ((utcSeconds: number, tickMark?: TickMarkType) => string) | undefined): void;
+    /** Swap the palette at runtime (dark/light toggle) without recreating the chart. */
+    setTheme(theme: ChartTheme): void;
+    /**
+     * Apply a subset of chart options at runtime (theme, grid, formatters,
+     * crosshair mode) without recreating the chart.
+     */
+    applyOptions(opts: {
+        theme?: ChartTheme;
+        grid?: {
+            vertLines?: boolean;
+            horzLines?: boolean;
+        };
+        priceFormatter?: ((price: number) => string) | null;
+        timeFormatter?: ((utcSeconds: number, tickMark?: TickMarkType) => string) | undefined;
+        crosshairMode?: CrosshairMode;
+    }): void;
     panes(): readonly Pane[];
     invalidate(build: (mask: InvalidateMask) => void): void;
     applySize(width: number, height: number): void;
     /** Distribute height across panes by weight; sync the shared time-scale width. */
     private _relayout;
+    /** Reserve a chart-wide left-axis column when any pane has a left price scale. */
+    private _recomputeLeftAxis;
     private _weightTotal;
     /** Cumulative top + height of each pane, by weight (the source of truth for hit-testing). */
     private _paneLayout;
@@ -2031,4 +2154,4 @@ declare function lerp(a: number, b: number, t: number): number;
  */
 declare function roundToTick(value: number, step: number): number;
 
-export { ALT_PRESET, type AddSeriesOptions, type AggTick, BUILTIN_COMMANDS, type Bar, type BarUpdate, type BarsRequest, CandleBuilder, type CandleBuilderOptions, type CandleStyle, type CandleUpdate, Chart, type ChartEvent, type ChartOptions, type ChartTheme, type CrosshairMoveEvent, type CustomShortcut, DEFAULT_CANDLE_BUILDER_OPTIONS, DEFAULT_CANDLE_STYLE, DEFAULT_HISTOGRAM_STYLE, DEFAULT_KEYMAP, DEFAULT_PRICE_SCALE_OPTIONS, DEFAULT_THEME, DEFAULT_TIME_SCALE_OPTIONS, DEFAULT_TRADING_COLORS, type DataFeed, type DepthLevel, type DrawItem, EventMarkers, FakeDataFeed, type FeedScheduler, type HistogramStyle, type IPrimitive, IST_OFFSET_SECONDS, InvalidationLevel, type KeymapEntry, type LateTickPolicy, type LinePoint, type LogicalRange, LogoWatermark, type LogoWatermarkOptions, type LtpEvent, type MarkerPosition, type MarkerShape, type MarkerSize, type MarketDepth, type OpenAlgoConfig, OpenAlgoDataFeed, type OpenAlgoLiveConfig, OpenAlgoLiveDataFeed, type OpenAlgoTradeConfig, OpenAlgoTradeFeed, type OpenAlgoWsConfig, OpenAlgoWsFeed, type OrderSide$1 as OrderSide, type OrderType$1 as OrderType, type OriginalTime, Pane, type PaneInvalidation, type PlaceOrder, type PositionSide, PriceLine, type PriceLineOptions, type PriceRange, PriceScale, type PriceScaleMode, type PriceScaleOptions, type PrimitiveHit, type PrimitiveHost, type PrimitiveRenderContext, type RendererEntry, type SeriesApi, type SeriesDataItem, type SeriesMarker, SeriesMarkers, type SeriesRenderContext, type SeriesStyle, type SeriesType, type ShortcutListItem, ShortcutManager, type ShortcutManagerOptions, type ShortcutPreset, type ShortcutScope, type ShortcutTriggerEvent, type Size, type SocketFactory, type SocketLike, type SupertrendPoint, type Tick, TickBarAggregator, type TickTimeframe, TimeScale, type TimeScaleOp, type TimeScaleOptions, type TradeFeed, type TradeMarkerVariant, TradeMarkersPrimitive, type TradingColors, TradingController, type TradingHost, type TradingLineStyle, type TradingLineVariant, type TradingOrder, type TradingOrderSide, type TradingOrderType, type TradingPosition, type TradingSettings, type TradingSyncPayload, type TradingTrade, type UTCSeconds, type UnsubscribeFn, VERSION, type VolumeMode, type WatermarkPosition, type Whitespace, type WsControlMessage, type WsMode, type WsState, type ZOrder, atr, autoscaleRange, bestHit, bitmapSize, clamp, conflateBars, conflateItems, conflationGroupSize, createChart, darkTheme, drawShape, effectiveMarkerPx, ema, emaSeries, epochMsToUtcSeconds, eventToCombo, formatCombo, formatIstDate, formatIstTime, formatIstTimeSeconds, formatSubscribe, formatUnsubscribe, generateBars, getChartType, intervalToSeconds, isNewIstDay, isReservedCombo, isValidCombo, isWhitespace, istStringToUtcSeconds, lerp, lightTheme, mapHistoryResponse, mapOrder, mapPosition, markerSizePx, mergeBars, niceTicks, normalizeCombo, optimalBarWidth, parseCombo, parseMessage, precisionForStep, registerChartType, registeredChartTypes, roundToTick, rowTimeToUtcSeconds, rsi, rsiSeries, snapToDevicePixel, supertrend, supertrendSeries, toBar, trueRange, utcSecondsToIstDateString, utcSecondsToIstParts, version, verticalGradient, watermarkRect };
+export { ALT_PRESET, type AddSeriesOptions, type AggTick, BUILTIN_COMMANDS, type Bar, type BarUpdate, type BarsRequest, CandleBuilder, type CandleBuilderOptions, type CandleStyle, type CandleUpdate, Chart, type ChartEvent, type ChartOptions, type ChartTheme, type CrosshairMoveEvent, type CustomShortcut, DEFAULT_CANDLE_BUILDER_OPTIONS, DEFAULT_CANDLE_STYLE, DEFAULT_HISTOGRAM_STYLE, DEFAULT_KEYMAP, DEFAULT_PRICE_SCALE_OPTIONS, DEFAULT_THEME, DEFAULT_TIME_SCALE_OPTIONS, DEFAULT_TRADING_COLORS, type DataFeed, type DepthLevel, type DrawItem, EventMarkers, FakeDataFeed, type FeedScheduler, type HistogramStyle, type IPrimitive, IST_OFFSET_SECONDS, InvalidationLevel, type KeymapEntry, type LateTickPolicy, type LinePoint, type LogicalRange, LogoWatermark, type LogoWatermarkOptions, type LtpEvent, type MarkerPosition, type MarkerShape, type MarkerSize, type MarketDepth, type OpenAlgoConfig, OpenAlgoDataFeed, type OpenAlgoLiveConfig, OpenAlgoLiveDataFeed, type OpenAlgoTradeConfig, OpenAlgoTradeFeed, type OpenAlgoWsConfig, OpenAlgoWsFeed, type OrderSide$1 as OrderSide, type OrderType$1 as OrderType, type OriginalTime, Pane, type PaneInvalidation, type PlaceOrder, type PositionSide, PriceLine, type PriceLineOptions, type PriceRange, PriceScale, type PriceScaleId, type PriceScaleMode, type PriceScaleOptions, type PrimitiveHit, type PrimitiveHost, type PrimitiveRenderContext, type RendererEntry, type SeriesApi, type SeriesDataItem, type SeriesMarker, SeriesMarkers, type SeriesRenderContext, type SeriesStyle, type SeriesType, type ShortcutListItem, ShortcutManager, type ShortcutManagerOptions, type ShortcutPreset, type ShortcutScope, type ShortcutTriggerEvent, type Size, type SocketFactory, type SocketLike, type SupertrendPoint, type Tick, TickBarAggregator, type TickMarkType, type TickTimeframe, TimeScale, type TimeScaleOp, type TimeScaleOptions, type TradeFeed, type TradeMarkerVariant, TradeMarkersPrimitive, type TradingColors, TradingController, type TradingHost, type TradingLineStyle, type TradingLineVariant, type TradingOrder, type TradingOrderSide, type TradingOrderType, type TradingPosition, type TradingSettings, type TradingSyncPayload, type TradingTrade, type UTCSeconds, type UnsubscribeFn, VERSION, type VolumeMode, type WatermarkPosition, type Whitespace, type WsControlMessage, type WsMode, type WsState, type ZOrder, atr, autoscaleRange, bestHit, bitmapSize, clamp, compactVolume, conflateBars, conflateItems, conflationGroupSize, createChart, darkTheme, drawShape, effectiveMarkerPx, ema, emaSeries, epochMsToUtcSeconds, eventToCombo, formatCombo, formatIstDate, formatIstTime, formatIstTimeSeconds, formatSubscribe, formatUnsubscribe, generateBars, getChartType, intervalToSeconds, isNewIstDay, isReservedCombo, isValidCombo, isWhitespace, istStringToUtcSeconds, lerp, lightTheme, mapHistoryResponse, mapOrder, mapPosition, markerSizePx, mergeBars, niceTicks, normalizeCombo, optimalBarWidth, parseCombo, parseMessage, precisionForStep, registerChartType, registeredChartTypes, roundToTick, rowTimeToUtcSeconds, rsi, rsiSeries, snapToDevicePixel, supertrend, supertrendSeries, toBar, trueRange, utcSecondsToIstDateString, utcSecondsToIstParts, version, verticalGradient, watermarkRect };