openalgo-charts 1.0.9 → 1.0.10

package/dist/draw/index.d.ts

@@ -828,6 +828,8 @@ declare class Pane {
     /** Remove a series record if present; returns true if it was found. */
     removeSeries(record: SeriesRecord): boolean;
     series(): readonly SeriesRecord[];
+    /** Primitives attached to this pane, in draw order. */
+    primitives(): readonly IPrimitive[];
     addPrimitive(primitive: IPrimitive, host: PrimitiveHost): void;
     /** Remove a primitive if present; returns true if it was found. */
     removePrimitive(primitive: IPrimitive): boolean;
@@ -1408,6 +1410,53 @@ declare class EventMarkers implements IPrimitive {
     hitTest(x: number, y: number): PrimitiveHit | null;
 }
 
+/**
+ * Time navigator (ARCHITECTURE.md §8) — the hover-revealed zoom / step controls
+ * that sit just above the time axis: `−` `+` to zoom, `‹` `›` to step one bar.
+ *
+ * Invisible until the pointer nears the bottom of the chart, so a clean chart
+ * stays clean. It fades in and out rather than snapping, which is what keeps it
+ * from reading as a glitch when the cursor crosses the reveal band.
+ *
+ * Reveal is driven by an explicit `setPointer` from the chart, **not** by
+ * `rc.hoverId`. Hover ids come from `bestHit`, which picks the nearest primitive
+ * — so a drawing or an order line near the bottom of the chart would win the
+ * hit and silently hide the controls. Pointer position is the honest input here;
+ * hit-testing still owns the buttons themselves.
+ */
+
+/** Command each button runs. These are `Chart` shortcut command ids. */
+type TimeNavigatorAction = 'zoomOut' | 'zoomIn' | 'panLeftBar' | 'panRightBar';
+interface TimeNavigatorOptions {
+    /** Prefix for hit ids. Lets a host run more than one. */
+    id: string;
+    /** Buttons, left to right. A `null` inserts a gap between groups. */
+    buttons: readonly (TimeNavigatorAction | null)[];
+    /** Button box size in media px. */
+    size: number;
+    /** Gap between buttons, and the wider gap a `null` produces. */
+    gap: number;
+    groupGap: number;
+    /** Distance from the bottom of the plot to the bottom of the buttons. */
+    bottomMargin: number;
+    /**
+     * Height of the reveal band above the plot bottom. The pointer anywhere in
+     * this band brings the controls in.
+     */
+    revealHeight: number;
+    /** Seconds the fade takes. 0 disables the animation. */
+    fadeSeconds: number;
+    /** Tooltip label per action. */
+    labels: Record<TimeNavigatorAction, string>;
+    /** Optional keyboard hint shown next to the label, e.g. `"Ctrl + −"`. */
+    hints: Partial<Record<TimeNavigatorAction, string>>;
+    /** Show the tooltip above the hovered button. */
+    showTooltip: boolean;
+    font: number;
+    radius: number;
+    zOrder: ZOrder;
+}
+
 /**
  * Top-level chart orchestrator (ARCHITECTURE.md §3.3). Owns the shared
  * DataLayer + time scale, the panes, the invalidate mask, and the render loop.
@@ -1468,6 +1517,12 @@ interface ChartOptions {
      * `(s) => new Date(s * 1000).toISOString().slice(11, 16)`.
      */
     timeFormatter?: (utcSeconds: number, tickMark?: TickMarkType) => string;
+    /**
+     * Hover-revealed zoom / step controls above the time axis (TradingView-style).
+     * `true` by default — they stay invisible until the pointer nears the bottom
+     * of the chart. Pass `false` to drop them, or an options object to restyle.
+     */
+    timeNavigator?: boolean | Partial<TimeNavigatorOptions>;
 }
 interface AddSeriesOptions {
     /** Target pane index (0 = price). Higher panes are created on demand. */
@@ -1603,6 +1658,9 @@ declare class Chart {
     private _priceScaleOptions;
     private _timeFormatter;
     private _leftAxisWidth;
+    private _timeNav;
+    /** Pane the navigator is currently attached to, so it can follow the bottom. */
+    private _timeNavPane;
     constructor(container: HTMLElement, options?: ChartOptions);
     /** Register a callback fired when the user pans near the left (oldest) edge. */
     setHistoryLoader(loader: () => void): void;
@@ -1875,6 +1933,22 @@ declare class Chart {
     private _handleLegendAction;
     /** Cumulative top + height of each pane, by weight (the source of truth for hit-testing). */
     private _paneLayout;
+    /**
+     * Keyboard hints for the navigator tooltips, read from the live keymap so a
+     * rebind shows up in the tooltip instead of a stale hardcoded string. The
+     * one-bar step buttons have no default binding, so they get no hint.
+     */
+    private _navHints;
+    /**
+     * Keep the navigator on the bottom pane — it belongs just above the time
+     * axis, and adding or removing a pane moves which one that is.
+     */
+    private _syncTimeNavPane;
+    /**
+     * Push the pointer to the navigator and keep painting while it fades, so the
+     * animation runs even when nothing else on the chart is changing.
+     */
+    private _feedTimeNav;
     private _renderContext;
     private _observeSize;
     private _onFrame;

package/dist/index.d.ts

@@ -707,6 +707,8 @@ declare class Pane {
     /** Remove a series record if present; returns true if it was found. */
     removeSeries(record: SeriesRecord): boolean;
     series(): readonly SeriesRecord[];
+    /** Primitives attached to this pane, in draw order. */
+    primitives(): readonly IPrimitive[];
     addPrimitive(primitive: IPrimitive, host: PrimitiveHost): void;
     /** Remove a primitive if present; returns true if it was found. */
     removePrimitive(primitive: IPrimitive): boolean;
@@ -1532,6 +1534,98 @@ declare class EventMarkers implements IPrimitive {
     hitTest(x: number, y: number): PrimitiveHit | null;
 }
 
+/**
+ * Time navigator (ARCHITECTURE.md §8) — the hover-revealed zoom / step controls
+ * that sit just above the time axis: `−` `+` to zoom, `‹` `›` to step one bar.
+ *
+ * Invisible until the pointer nears the bottom of the chart, so a clean chart
+ * stays clean. It fades in and out rather than snapping, which is what keeps it
+ * from reading as a glitch when the cursor crosses the reveal band.
+ *
+ * Reveal is driven by an explicit `setPointer` from the chart, **not** by
+ * `rc.hoverId`. Hover ids come from `bestHit`, which picks the nearest primitive
+ * — so a drawing or an order line near the bottom of the chart would win the
+ * hit and silently hide the controls. Pointer position is the honest input here;
+ * hit-testing still owns the buttons themselves.
+ */
+
+/** Command each button runs. These are `Chart` shortcut command ids. */
+type TimeNavigatorAction = 'zoomOut' | 'zoomIn' | 'panLeftBar' | 'panRightBar';
+interface TimeNavigatorOptions {
+    /** Prefix for hit ids. Lets a host run more than one. */
+    id: string;
+    /** Buttons, left to right. A `null` inserts a gap between groups. */
+    buttons: readonly (TimeNavigatorAction | null)[];
+    /** Button box size in media px. */
+    size: number;
+    /** Gap between buttons, and the wider gap a `null` produces. */
+    gap: number;
+    groupGap: number;
+    /** Distance from the bottom of the plot to the bottom of the buttons. */
+    bottomMargin: number;
+    /**
+     * Height of the reveal band above the plot bottom. The pointer anywhere in
+     * this band brings the controls in.
+     */
+    revealHeight: number;
+    /** Seconds the fade takes. 0 disables the animation. */
+    fadeSeconds: number;
+    /** Tooltip label per action. */
+    labels: Record<TimeNavigatorAction, string>;
+    /** Optional keyboard hint shown next to the label, e.g. `"Ctrl + −"`. */
+    hints: Partial<Record<TimeNavigatorAction, string>>;
+    /** Show the tooltip above the hovered button. */
+    showTooltip: boolean;
+    font: number;
+    radius: number;
+    zOrder: ZOrder;
+}
+declare const DEFAULT_TIME_NAVIGATOR_OPTIONS: TimeNavigatorOptions;
+declare class TimeNavigator implements IPrimitive {
+    private _opts;
+    private _host;
+    /** Button geometry from the last paint, in media px relative to the plot. */
+    private _boxes;
+    /** Pointer in plot-local media px, or null when it left the pane. */
+    private _pointer;
+    /** 0 hidden, 1 fully shown. Eased toward the target each frame. */
+    private _opacity;
+    private _lastFrameMs;
+    private _now;
+    constructor(opts?: Partial<TimeNavigatorOptions>, now?: () => number);
+    attached(host: PrimitiveHost): void;
+    detached(): void;
+    zOrder(): ZOrder;
+    options(): TimeNavigatorOptions;
+    setOptions(patch: Partial<TimeNavigatorOptions>): void;
+    /**
+     * Tell the navigator where the pointer is, in plot-local media px. `null`
+     * when it leaves. The chart calls this; hosts driving their own navigator
+     * should too.
+     */
+    setPointer(p: {
+        x: number;
+        y: number;
+    } | null): void;
+    /** True when the pointer is inside the reveal band. */
+    private _revealed;
+    private _targetOpacity;
+    /** Top of the reveal band, recomputed each paint from the plot height. */
+    private _revealTop;
+    /** Whether the fade is still running — the chart keeps painting while true. */
+    animating(): boolean;
+    draw(ctx: CanvasRenderingContext2D, rc: PrimitiveRenderContext): void;
+    /** Which button the pointer is over, or null. */
+    private _hoveredAction;
+    private _button;
+    private _tooltip;
+    /**
+     * Buttons hit-test only while visible, so a hidden navigator never steals a
+     * click from the chart body underneath it.
+     */
+    hitTest(x: number, y: number): PrimitiveHit | null;
+}
+
 /**
  * Top-level chart orchestrator (ARCHITECTURE.md §3.3). Owns the shared
  * DataLayer + time scale, the panes, the invalidate mask, and the render loop.
@@ -1592,6 +1686,12 @@ interface ChartOptions {
      * `(s) => new Date(s * 1000).toISOString().slice(11, 16)`.
      */
     timeFormatter?: (utcSeconds: number, tickMark?: TickMarkType) => string;
+    /**
+     * Hover-revealed zoom / step controls above the time axis (TradingView-style).
+     * `true` by default — they stay invisible until the pointer nears the bottom
+     * of the chart. Pass `false` to drop them, or an options object to restyle.
+     */
+    timeNavigator?: boolean | Partial<TimeNavigatorOptions>;
 }
 interface AddSeriesOptions {
     /** Target pane index (0 = price). Higher panes are created on demand. */
@@ -1729,6 +1829,9 @@ declare class Chart {
     private _priceScaleOptions;
     private _timeFormatter;
     private _leftAxisWidth;
+    private _timeNav;
+    /** Pane the navigator is currently attached to, so it can follow the bottom. */
+    private _timeNavPane;
     constructor(container: HTMLElement, options?: ChartOptions);
     /** Register a callback fired when the user pans near the left (oldest) edge. */
     setHistoryLoader(loader: () => void): void;
@@ -2001,6 +2104,22 @@ declare class Chart {
     private _handleLegendAction;
     /** Cumulative top + height of each pane, by weight (the source of truth for hit-testing). */
     private _paneLayout;
+    /**
+     * Keyboard hints for the navigator tooltips, read from the live keymap so a
+     * rebind shows up in the tooltip instead of a stale hardcoded string. The
+     * one-bar step buttons have no default binding, so they get no hint.
+     */
+    private _navHints;
+    /**
+     * Keep the navigator on the bottom pane — it belongs just above the time
+     * axis, and adding or removing a pane moves which one that is.
+     */
+    private _syncTimeNavPane;
+    /**
+     * Push the pointer to the navigator and keep painting while it fades, so the
+     * animation runs even when nothing else on the chart is changing.
+     */
+    private _feedTimeNav;
     private _renderContext;
     private _observeSize;
     private _onFrame;
@@ -2964,4 +3083,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, BuySellButtons, type BuySellButtonsOptions, CHART_STATE_VERSION, CandleBuilder, type CandleBuilderOptions, type CandleStyle, type CandleUpdate, Chart, type ChartEvent, type ChartOptions, type ChartState, 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, INDICATOR_LINE_STYLES, INDICATOR_SOURCES, type IPrimitive, IST_OFFSET_SECONDS, type IndicatorApi, type IndicatorAttachContext, type IndicatorDescriptor, type IndicatorHost, type IndicatorInput, type IndicatorLevel, type IndicatorPlot, type IndicatorSettings, type IndicatorSource, type IndicatorState, type IndicatorStore, type IndicatorValues, InvalidationLevel, type KeymapEntry, type LateTickPolicy, type LegendValue, 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, PaneLegend, type PaneLegendAction, type PaneLegendOptions, type PaneState, type PlaceOrder, type PositionSide, PriceLine, type PriceLineOptions, type PriceRange, PriceScale, type PriceScaleId, type PriceScaleMode, type PriceScaleOptions, type PriceScaleState, type PrimitiveHit, type PrimitiveHost, type PrimitiveRenderContext, type RendererEntry, type RestoreReport, type SeriesApi, type SeriesDataItem, type SeriesMarker, SeriesMarkers, type SeriesRenderContext, type SeriesState, 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, getIndicator, hasIndicator, indicatorDefaults, indicatorStyleInputs, intervalToSeconds, isNewIstDay, isReservedCombo, isValidCombo, isWhitespace, istStringToUtcSeconds, lerp, lightTheme, mapHistoryResponse, mapOrder, mapPosition, markerSizePx, mergeBars, niceTicks, normalizeCombo, optimalBarWidth, parseCombo, parseMessage, plotStyleKeys, precisionForStep, registerChartType, registerIndicator, registeredChartTypes, registeredIndicators, roundToTick, rowTimeToUtcSeconds, rsi, rsiSeries, snapToDevicePixel, sourceValue, sourceValues, supertrend, supertrendSeries, toBar, trueRange, utcSecondsToIstDateString, utcSecondsToIstParts, version, verticalGradient, watermarkRect };
+export { ALT_PRESET, type AddSeriesOptions, type AggTick, BUILTIN_COMMANDS, type Bar, type BarUpdate, type BarsRequest, BuySellButtons, type BuySellButtonsOptions, CHART_STATE_VERSION, CandleBuilder, type CandleBuilderOptions, type CandleStyle, type CandleUpdate, Chart, type ChartEvent, type ChartOptions, type ChartState, 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_NAVIGATOR_OPTIONS, DEFAULT_TIME_SCALE_OPTIONS, DEFAULT_TRADING_COLORS, type DataFeed, type DepthLevel, type DrawItem, EventMarkers, FakeDataFeed, type FeedScheduler, type HistogramStyle, INDICATOR_LINE_STYLES, INDICATOR_SOURCES, type IPrimitive, IST_OFFSET_SECONDS, type IndicatorApi, type IndicatorAttachContext, type IndicatorDescriptor, type IndicatorHost, type IndicatorInput, type IndicatorLevel, type IndicatorPlot, type IndicatorSettings, type IndicatorSource, type IndicatorState, type IndicatorStore, type IndicatorValues, InvalidationLevel, type KeymapEntry, type LateTickPolicy, type LegendValue, 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, PaneLegend, type PaneLegendAction, type PaneLegendOptions, type PaneState, type PlaceOrder, type PositionSide, PriceLine, type PriceLineOptions, type PriceRange, PriceScale, type PriceScaleId, type PriceScaleMode, type PriceScaleOptions, type PriceScaleState, type PrimitiveHit, type PrimitiveHost, type PrimitiveRenderContext, type RendererEntry, type RestoreReport, type SeriesApi, type SeriesDataItem, type SeriesMarker, SeriesMarkers, type SeriesRenderContext, type SeriesState, 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, TimeNavigator, type TimeNavigatorAction, type TimeNavigatorOptions, 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, getIndicator, hasIndicator, indicatorDefaults, indicatorStyleInputs, intervalToSeconds, isNewIstDay, isReservedCombo, isValidCombo, isWhitespace, istStringToUtcSeconds, lerp, lightTheme, mapHistoryResponse, mapOrder, mapPosition, markerSizePx, mergeBars, niceTicks, normalizeCombo, optimalBarWidth, parseCombo, parseMessage, plotStyleKeys, precisionForStep, registerChartType, registerIndicator, registeredChartTypes, registeredIndicators, roundToTick, rowTimeToUtcSeconds, rsi, rsiSeries, snapToDevicePixel, sourceValue, sourceValues, supertrend, supertrendSeries, toBar, trueRange, utcSecondsToIstDateString, utcSecondsToIstParts, version, verticalGradient, watermarkRect };