@qfo/qfchart 0.5.0

package/dist/index.d.ts

@@ -0,0 +1,465 @@
+import * as echarts from 'echarts';
+
+type EventType = 'mouse:down' | 'mouse:move' | 'mouse:up' | 'mouse:click' | 'chart:resize' | 'chart:dataZoom' | 'chart:updated' | 'plugin:activated' | 'plugin:deactivated' | 'drawing:hover' | 'drawing:mouseout' | 'drawing:mousedown' | 'drawing:click' | 'drawing:point:hover' | 'drawing:point:mouseout' | 'drawing:point:mousedown' | 'drawing:point:click' | 'drawing:selected' | 'drawing:deselected' | 'drawing:deleted';
+type EventHandler<T = any> = (payload: T) => void;
+declare class EventBus {
+    private handlers;
+    on<T = any>(event: EventType, handler: EventHandler<T>): void;
+    off<T = any>(event: EventType, handler: EventHandler<T>): void;
+    emit<T = any>(event: EventType, payload?: T): void;
+    clear(): void;
+}
+
+interface OHLCV {
+    time: number;
+    open: number;
+    high: number;
+    low: number;
+    close: number;
+    volume: number;
+}
+interface IndicatorPoint {
+    time: number;
+    value: number | null;
+    options?: {
+        color?: string;
+    };
+}
+type IndicatorStyle = 'line' | 'columns' | 'histogram' | 'circles' | 'cross' | 'background';
+interface IndicatorOptions {
+    style: IndicatorStyle;
+    color: string;
+    linewidth?: number;
+}
+interface IndicatorPlot {
+    data: IndicatorPoint[];
+    options: IndicatorOptions;
+}
+interface Indicator$1 {
+    id: string;
+    plots: {
+        [name: string]: IndicatorPlot;
+    };
+    paneIndex: number;
+    height?: number;
+    collapsed?: boolean;
+    titleColor?: string;
+    controls?: {
+        collapse?: boolean;
+        maximize?: boolean;
+    };
+}
+interface QFChartOptions {
+    title?: string;
+    titleColor?: string;
+    backgroundColor?: string;
+    upColor?: string;
+    downColor?: string;
+    fontColor?: string;
+    fontFamily?: string;
+    padding?: number;
+    height?: string | number;
+    controls?: {
+        collapse?: boolean;
+        maximize?: boolean;
+        fullscreen?: boolean;
+    };
+    dataZoom?: {
+        visible?: boolean;
+        position?: 'top' | 'bottom';
+        height?: number;
+        start?: number;
+        end?: number;
+    };
+    databox?: {
+        position: 'floating' | 'left' | 'right';
+    };
+    layout?: {
+        mainPaneHeight: string;
+        gap: number;
+    };
+    watermark?: boolean;
+}
+interface Coordinate {
+    x: number;
+    y: number;
+}
+interface DataCoordinate {
+    timeIndex: number;
+    value: number;
+    paneIndex?: number;
+}
+interface ChartContext {
+    getChart(): any;
+    getMarketData(): OHLCV[];
+    getTimeToIndex(): Map<number, number>;
+    getOptions(): QFChartOptions;
+    events: EventBus;
+    coordinateConversion: {
+        pixelToData: (point: Coordinate) => DataCoordinate | null;
+        dataToPixel: (point: DataCoordinate) => Coordinate | null;
+    };
+    disableTools(): void;
+    setZoom(start: number, end: number): void;
+    addDrawing(drawing: DrawingElement): void;
+    removeDrawing(id: string): void;
+    getDrawing(id: string): DrawingElement | undefined;
+    updateDrawing(drawing: DrawingElement): void;
+    lockChart(): void;
+    unlockChart(): void;
+}
+type DrawingType = 'line' | 'fibonacci';
+interface DrawingElement {
+    id: string;
+    type: DrawingType;
+    points: DataCoordinate[];
+    paneIndex?: number;
+    style?: {
+        color?: string;
+        lineWidth?: number;
+    };
+}
+interface PluginConfig {
+    id: string;
+    name?: string;
+    icon?: string;
+    hotkey?: string;
+}
+interface Plugin {
+    id: string;
+    name?: string;
+    icon?: string;
+    init(context: ChartContext): void;
+    activate?(): void;
+    deactivate?(): void;
+    destroy?(): void;
+}
+
+declare class Indicator implements Indicator$1 {
+    id: string;
+    plots: {
+        [name: string]: IndicatorPlot;
+    };
+    paneIndex: number;
+    height?: number;
+    collapsed: boolean;
+    titleColor?: string;
+    controls?: {
+        collapse?: boolean;
+        maximize?: boolean;
+    };
+    constructor(id: string, plots: {
+        [name: string]: IndicatorPlot;
+    }, paneIndex: number, options?: {
+        height?: number;
+        collapsed?: boolean;
+        titleColor?: string;
+        controls?: {
+            collapse?: boolean;
+            maximize?: boolean;
+        };
+    });
+    toggleCollapse(): void;
+    isVisible(): boolean;
+    /**
+     * Update indicator data incrementally by merging new points
+     *
+     * @param plots - New plots data to merge (same structure as constructor)
+     *
+     * @remarks
+     * This method merges new indicator data with existing data by timestamp.
+     * - New timestamps are added
+     * - Existing timestamps are updated with new values
+     * - All data is automatically sorted by time after merge
+     *
+     * **Important**: This method only updates the indicator's internal data structure.
+     * To see the changes reflected in the chart, you MUST call `chart.updateData()`
+     * after updating indicator data.
+     *
+     * **Usage Pattern**:
+     * ```typescript
+     * // 1. Update indicator data first
+     * indicator.updateData({
+     *   macd: { data: [{ time: 1234567890, value: 150 }], options: { style: 'line', color: '#2962FF' } }
+     * });
+     *
+     * // 2. Then update chart data to trigger re-render
+     * chart.updateData([
+     *   { time: 1234567890, open: 100, high: 105, low: 99, close: 103, volume: 1000 }
+     * ]);
+     * ```
+     *
+     * **Note**: If you update indicator data without corresponding market data changes,
+     * this typically indicates a recalculation scenario. In normal workflows, indicator
+     * values are derived from market data, so indicator updates should correspond to
+     * new or modified market bars.
+     */
+    updateData(plots: {
+        [name: string]: IndicatorPlot;
+    }): void;
+}
+
+declare class QFChart implements ChartContext {
+    private chart;
+    private options;
+    private marketData;
+    private indicators;
+    private timeToIndex;
+    private pluginManager;
+    private drawingEditor;
+    events: EventBus;
+    private isMainCollapsed;
+    private maximizedPaneId;
+    private selectedDrawingId;
+    private drawings;
+    coordinateConversion: {
+        pixelToData: (point: {
+            x: number;
+            y: number;
+        }) => {
+            timeIndex: number;
+            value: number;
+            paneIndex: number;
+        } | null;
+        dataToPixel: (point: {
+            timeIndex: number;
+            value: number;
+            paneIndex?: number;
+        }) => {
+            x: number;
+            y: number;
+        } | null;
+    };
+    private readonly upColor;
+    private readonly downColor;
+    private readonly defaultPadding;
+    private padding;
+    private dataIndexOffset;
+    private rootContainer;
+    private layoutContainer;
+    private toolbarContainer;
+    private leftSidebar;
+    private rightSidebar;
+    private chartContainer;
+    constructor(container: HTMLElement, options?: QFChartOptions);
+    private onKeyDown;
+    private onFullscreenChange;
+    private bindDrawingEvents;
+    getChart(): echarts.ECharts;
+    getMarketData(): OHLCV[];
+    getTimeToIndex(): Map<number, number>;
+    getOptions(): QFChartOptions;
+    disableTools(): void;
+    registerPlugin(plugin: Plugin): void;
+    addDrawing(drawing: DrawingElement): void;
+    removeDrawing(id: string): void;
+    getDrawing(id: string): DrawingElement | undefined;
+    updateDrawing(drawing: DrawingElement): void;
+    private isLocked;
+    private lockedState;
+    lockChart(): void;
+    unlockChart(): void;
+    setZoom(start: number, end: number): void;
+    setMarketData(data: OHLCV[]): void;
+    /**
+     * Update market data incrementally without full re-render
+     * Merges new/updated OHLCV data with existing data by timestamp
+     *
+     * @param data - Array of OHLCV data to merge
+     *
+     * @remarks
+     * **Performance Optimization**: This method only triggers a chart update if the data array contains
+     * new or modified bars. If an empty array is passed, no update occurs (expected behavior).
+     *
+     * **Usage Pattern for Updating Indicators**:
+     * When updating both market data and indicators, follow this order:
+     *
+     * 1. Update indicator data first using `indicator.updateData(plots)`
+     * 2. Then call `chart.updateData(newBars)` with the new/modified market data
+     *
+     * The chart update will trigger a re-render that includes the updated indicator data.
+     *
+     * **Important**: If you update indicator data without updating market data (e.g., recalculation
+     * with same bars), you must still call `chart.updateData([...])` with at least one bar
+     * to trigger the re-render. Calling with an empty array will NOT trigger an update.
+     *
+     * @example
+     * ```typescript
+     * // Step 1: Update indicator data
+     * macdIndicator.updateData({
+     *   macd: { data: [{ time: 1234567890, value: 150 }], options: { style: 'line', color: '#2962FF' } }
+     * });
+     *
+     * // Step 2: Update market data (triggers re-render with new indicator data)
+     * chart.updateData([
+     *   { time: 1234567890, open: 100, high: 105, low: 99, close: 103, volume: 1000 }
+     * ]);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // If only updating existing bar (e.g., real-time tick updates):
+     * const lastBar = { ...existingBar, close: newPrice, high: Math.max(existingBar.high, newPrice) };
+     * chart.updateData([lastBar]); // Updates by timestamp
+     * ```
+     */
+    updateData(data: OHLCV[]): void;
+    addIndicator(id: string, plots: {
+        [name: string]: IndicatorPlot;
+    }, options?: {
+        isOverlay?: boolean;
+        height?: number;
+        titleColor?: string;
+        controls?: {
+            collapse?: boolean;
+            maximize?: boolean;
+        };
+    }): Indicator;
+    setIndicator(id: string, plot: IndicatorPlot, isOverlay?: boolean): void;
+    removeIndicator(id: string): void;
+    toggleIndicator(id: string, action?: 'collapse' | 'maximize' | 'fullscreen'): void;
+    resize(): void;
+    destroy(): void;
+    private rebuildTimeIndex;
+    private render;
+}
+
+declare abstract class AbstractPlugin implements Plugin {
+    id: string;
+    name?: string;
+    icon?: string;
+    protected context: ChartContext;
+    private eventListeners;
+    constructor(config: PluginConfig);
+    init(context: ChartContext): void;
+    /**
+     * Lifecycle hook called after context is initialized.
+     * Override this instead of init().
+     */
+    protected onInit(): void;
+    activate(): void;
+    /**
+     * Lifecycle hook called when the plugin is activated.
+     */
+    protected onActivate(): void;
+    deactivate(): void;
+    /**
+     * Lifecycle hook called when the plugin is deactivated.
+     */
+    protected onDeactivate(): void;
+    destroy(): void;
+    /**
+     * Lifecycle hook called when the plugin is destroyed.
+     */
+    protected onDestroy(): void;
+    /**
+     * Register an event listener that will be automatically cleaned up on destroy.
+     */
+    protected on(event: EventType, handler: EventHandler): void;
+    /**
+     * Remove a specific event listener.
+     */
+    protected off(event: EventType, handler: EventHandler): void;
+    /**
+     * Remove all listeners registered by this plugin.
+     */
+    protected removeAllListeners(): void;
+    /**
+     * Access to the ECharts instance.
+     */
+    protected get chart(): any;
+    /**
+     * Access to market data.
+     */
+    protected get marketData(): OHLCV[];
+}
+
+declare class MeasureTool extends AbstractPlugin {
+    private zr;
+    private state;
+    private startPoint;
+    private endPoint;
+    private group;
+    private rect;
+    private labelRect;
+    private labelText;
+    private lineV;
+    private lineH;
+    private arrowStart;
+    private arrowEnd;
+    constructor(options: {
+        name?: string;
+        icon?: string;
+    });
+    protected onInit(): void;
+    protected onActivate(): void;
+    protected onDeactivate(): void;
+    protected onDestroy(): void;
+    private onMouseDown;
+    private onChartInteraction;
+    private onClick;
+    private enableClearListeners;
+    private clearHandlers;
+    private disableClearListeners;
+    private onMouseMove;
+    private initGraphic;
+    private removeGraphic;
+    private updateGraphic;
+}
+
+declare class LineTool extends AbstractPlugin {
+    private zr;
+    private state;
+    private startPoint;
+    private endPoint;
+    private group;
+    private line;
+    private startCircle;
+    private endCircle;
+    constructor(options: {
+        name?: string;
+        icon?: string;
+    });
+    protected onInit(): void;
+    protected onActivate(): void;
+    protected onDeactivate(): void;
+    protected onDestroy(): void;
+    private onMouseDown;
+    private onChartInteraction;
+    private onClick;
+    private saveDataCoordinates;
+    private updateGraphicFromData;
+    private enableClearListeners;
+    private clearHandlers;
+    private disableClearListeners;
+    private onMouseMove;
+    private initGraphic;
+    private removeGraphic;
+    private updateGraphic;
+}
+
+declare class FibonacciTool extends AbstractPlugin {
+    private startPoint;
+    private endPoint;
+    private state;
+    private graphicGroup;
+    private readonly levels;
+    private readonly colors;
+    constructor(options?: {
+        name?: string;
+        icon?: string;
+    });
+    onActivate(): void;
+    onDeactivate(): void;
+    private bindEvents;
+    private unbindEvents;
+    private onClick;
+    private onMouseMove;
+    private initGraphic;
+    private removeGraphic;
+    private updateGraphic;
+    private saveDrawing;
+}
+
+export { AbstractPlugin, FibonacciTool, LineTool, MeasureTool, QFChart };
+export type { ChartContext, Coordinate, DataCoordinate, DrawingElement, DrawingType, Indicator$1 as Indicator, IndicatorOptions, IndicatorPlot, IndicatorPoint, IndicatorStyle, OHLCV, Plugin, PluginConfig, QFChartOptions };