@pradeepjadhav/trading-reload-chart 1.2.0 → 1.3.0

package/dist/canvas/layers/CrosshairLayer.d.ts

@@ -9,6 +9,7 @@ export declare class CrosshairLayer {
     crosshairStyle: CrosshairStyle;
     constructor(options: CrosshairLayerOptions);
     updateMousePosition(x: number, y: number, options?: UpdateMousePositionOptions): void;
+    setPosition(x: number, y: number): void;
     hide(): void;
     applyCrosshairStyle(): void;
     drawVerticalCrosshairLine(ctx: CanvasRenderingContext2D, height: number): void;

package/dist/canvas/layers/ExistingCandlesLayer.d.ts

@@ -1,4 +1,5 @@
 import { Candle } from '../../models/Candle.types';
+import { ChartCursorState, ChartViewState } from '../../models/ChartSync.types';
 import { ChartViewport } from '../../models/ChartViewport.types';
 import { VisibleRange } from '../../models/VisibleRange.types';
 import { DrawCandlesOptions, DrawPriceLineOptions, DrawSingleCandleOptions, ExistingCandlesLayerOptions } from './ExistingCandlesLayer.types';
@@ -60,6 +61,14 @@ export declare class ExistingCandlesLayer {
     get liveCandle(): Candle;
     get viewport(): ChartViewport;
     getVisibleRange(chartWidth: number): VisibleRange;
+    getViewState(): ChartViewState | null;
+    setViewState(view: ChartViewState): void;
+    setCursorState(cursor: ChartCursorState): {
+        candle: Candle;
+        candleIndex: number;
+        x: number;
+        y: number;
+    } | null;
     getCandleX(candleIndex: number): number;
     getCandleCenterX(candleIndex: number): number;
     getNearestCandleIndexByX(x: number): number | null;
@@ -90,12 +99,40 @@ export declare class ExistingCandlesLayer {
     private getInitialPriceRange;
     private getInitialFallbackPercent;
     private detectCandleTimeframeMs;
+    private hasUsableTimeframe;
     private applyManualViewportOverrides;
     private closeLastCandle;
     private appendLiveCandle;
     private updateAutoFollowAfterAppend;
     private clampCandleIndex;
     private getRightEdgeCandleIndex;
+    private getRightmostVisibleTime;
+    private getRightmostVisibleX;
+    private getRightmostVisibleIndex;
+    private getRightEdgeTime;
+    private getVisibleDurationMs;
+    private getTimeDeltaInCandleSlots;
+    /**
+     * Resolves a timestamp to the candle whose span contains it.
+     *
+     * Synced cursors arrive from charts of a different timeframe, so the
+     * incoming timestamp is not a multiple of this chart's timeframe away from
+     * the first candle. Dividing by this chart's timeframe to derive an index
+     * therefore drifts by the timeframe ratio, and clamping that drift pinned
+     * the crosshair to the last candle. Binary searching the real candle times
+     * is correct for any incoming timestamp and any target timeframe.
+     *
+     * Containment is measured against the candle's open time, so a finer
+     * timeframe hovering partway through a coarse candle snaps to the coarse
+     * candle that is actually covering that moment, rather than to whichever
+     * neighbour happens to start closest to the timestamp.
+     */
+    private getCandleIndexByTime;
+    /**
+     * Binary search for the first candle whose time is greater than or equal to
+     * `targetTime`, falling back to the last index when every candle is earlier.
+     */
+    private findCandleIndexAtOrAfter;
     private getNextHorizontalZoom;
     private getNextVerticalPriceRange;
     private clearCanvas;

package/dist/chart/ChartController.d.ts

@@ -1,8 +1,13 @@
+import { ChartCursorState, ChartViewState } from '../models/ChartSync.types';
 import { ChartControllerProps } from './ChartController.types';
 export declare class ChartController {
     #private;
     constructor(container: HTMLElement, props: ChartControllerProps);
     updateProps(props: ChartControllerProps): void;
     resetChartView(): void;
+    setView(view: ChartViewState): void;
+    getView(): ChartViewState | null;
+    setCursor(cursor: ChartCursorState | null): void;
+    hideCursor(): void;
     destroy(): void;
 }

package/dist/chart/ChartController.types.d.ts

@@ -1,6 +1,7 @@
 import { Shape, ShapeAddedPayload, ShapeModifiedPayload, ShapeSelectedPayload, ShapeToolType } from '../canvas/layers/ShapesLayer/ShapesLayer.types';
 import { ChartConfig } from '../config/chartConfig.types';
 import { Candle } from '../models/Candle.types';
+import { ChartCursorState, ChartViewState } from '../models/ChartSync.types';
 import { ClosedTrade, OpenTrade } from '../models/Trade.types';
 import { DeepPartial } from './utils/deepPartial.types';
 /**
@@ -249,4 +250,13 @@ export type ChartControllerProps = {
     onTradeClose?: (payload: {
         ticket: number;
     }) => void;
+    /**
+     * Called after a local pan, zoom, reset, or resize changes the chart view.
+     * The timestamp-based payload can be applied to charts with different candle timeframes.
+     */
+    onViewChange?: (view: ChartViewState) => void;
+    /**
+     * Called when the local crosshair moves, and with `null` when it leaves the chart.
+     */
+    onCursorMove?: (cursor: ChartCursorState | null) => void;
 };

package/dist/index.d.ts

@@ -6,6 +6,7 @@ export type { CanvasPoint } from './chart/utils/getCanvasPoint.types';
 export { CHART_CONFIG } from './config/chartConfig';
 export type { ChartConfig, PreviousDayHighLowConfig } from './config/chartConfig.types';
 export type { Candle } from './models/Candle.types';
+export type { ChartCursorState, ChartViewState } from './models/ChartSync.types';
 export type { ChartViewport } from './models/ChartViewport.types';
 export type { Point2D } from './models/Point.types';
 export type { BaseTrade, ClosedTrade, OpenTrade, TradeDirection } from './models/Trade.types';

package/dist/models/ChartSync.types.d.ts

@@ -0,0 +1,16 @@
+export type ChartViewState = {
+    /** UTC timestamp of the chart's rightmost visible candle. */
+    rightmostVisibleTime: number;
+    /** Normalized screen position of that candle, from 0 to 1. */
+    rightmostVisibleX: number;
+    /** UTC timestamp of the plot's right edge. */
+    rightEdgeTime: number;
+    /** Visible duration represented by the plot, in milliseconds. */
+    visibleDurationMs: number;
+};
+export type ChartCursorState = {
+    /** UTC timestamp selected by the vertical crosshair. */
+    time: number;
+    /** Price selected by the horizontal crosshair. */
+    price: number;
+};

package/dist/react/TradingReload.types.d.ts

@@ -1,5 +1,6 @@
 import { CSSProperties } from 'react';
 import { ChartControllerProps } from '../chart/ChartController.types';
+import { ChartCursorState, ChartViewState } from '../models/ChartSync.types';
 /**
  * Imperative methods exposed through the `ref` passed to {@link TradingReload}.
  *
@@ -24,6 +25,45 @@ export type TradingReloadHandle = {
      * ```
      */
     resetChartView: () => void;
+    /**
+     * Returns the current timestamp-based view state, or `null` when the chart
+     * has no candles to describe.
+     *
+     * @example
+     * ```tsx
+     * const view = chartRef.current?.getView();
+     * ```
+     */
+    getView: () => ChartViewState | null;
+    /**
+     * Applies a timestamp-based view state so charts with different candle
+     * timeframes stay aligned. Does not emit `onViewChange`.
+     *
+     * @example
+     * ```tsx
+     * chartRef.current?.setView(sourceView);
+     * ```
+     */
+    setView: (view: ChartViewState) => void;
+    /**
+     * Draws a synced crosshair at the given time and price, snapped to the
+     * nearest candle. Does not emit `onCursorMove`.
+     *
+     * @example
+     * ```tsx
+     * chartRef.current?.setCursor({ time, price });
+     * ```
+     */
+    setCursor: (cursor: ChartCursorState | null) => void;
+    /**
+     * Hides the crosshair and axis labels.
+     *
+     * @example
+     * ```tsx
+     * chartRef.current?.hideCursor();
+     * ```
+     */
+    hideCursor: () => void;
 };
 /**
  * Props accepted by the public `TradingReload` React component.