@qfo/qfchart 0.6.4 → 0.6.6

package/src/types.ts

@@ -1,205 +1,205 @@
-import { EventBus } from './utils/EventBus';
-
-export interface OHLCV {
-    time: number;
-    open: number;
-    high: number;
-    low: number;
-    close: number;
-    volume: number;
-}
-
-export interface IndicatorPoint {
-    time: number;
-    value: number | number[] | null;
-    options?: {
-        color?: string;
-        offset?: number;
-        wickcolor?: string;
-        bordercolor?: string;
-    };
-}
-
-export type IndicatorStyle =
-    | 'line'
-    | 'step'
-    | 'columns'
-    | 'histogram'
-    | 'circles'
-    | 'cross'
-    | 'background'
-    | 'shape'
-    | 'char'
-    | 'bar'
-    | 'candle'
-    | 'barcolor'
-    | 'fill';
-
-export interface IndicatorOptions {
-    style: IndicatorStyle;
-    color: string;
-    overlay?: boolean; // Override indicator-level overlay setting for this specific plot
-    offset?: number;
-    linewidth?: number;
-    smooth?: boolean;
-    shape?: string;
-    size?: string;
-    text?: string;
-    textcolor?: string;
-    location?: string;
-    width?: number;
-    height?: number;
-    wickcolor?: string;
-    bordercolor?: string;
-}
-
-export interface IndicatorPlot {
-    data?: IndicatorPoint[]; // Optional for fill plots
-    options: IndicatorOptions;
-    plot1?: string; // For fill plots: reference to first plot ID
-    plot2?: string; // For fill plots: reference to second plot ID
-}
-
-// A collection of plots that make up a single indicator (e.g. MACD has macd line, signal line, histogram)
-export interface Indicator {
-    id: string;
-    plots: { [name: string]: IndicatorPlot };
-    paneIndex: number;
-    height?: number; // Desired height in percentage (e.g. 15 for 15%)
-    collapsed?: boolean;
-    titleColor?: string;
-    controls?: {
-        collapse?: boolean;
-        maximize?: boolean;
-    };
-}
-
-export interface QFChartOptions {
-    title?: string; // Title for the main chart (e.g. "BTC/USDT")
-    titleColor?: string;
-    backgroundColor?: string;
-    upColor?: string;
-    downColor?: string;
-    fontColor?: string;
-    fontFamily?: string;
-    padding?: number; // Horizontal padding (empty candles on sides), defaults to 0.2
-    yAxisPadding?: number; // Vertical Y-axis padding in percentage (e.g., 5 = 5% padding), defaults to 5
-    yAxisMin?: number | 'auto'; // Fixed minimum value for main Y-axis, or 'auto' for dynamic
-    yAxisMax?: number | 'auto'; // Fixed maximum value for main Y-axis, or 'auto' for dynamic
-    yAxisLabelFormatter?: (value: number) => string; // Custom formatter function for Y-axis labels
-    yAxisDecimalPlaces?: number; // Number of decimal places for Y-axis labels (default: 2)
-    lastPriceLine?: {
-        // Configuration for the horizontal line showing the last price
-        visible?: boolean;
-        color?: string; // Defaults to current candle color or '#fff'
-        lineStyle?: 'solid' | 'dashed' | 'dotted'; // Defaults to 'dashed'
-        showCountdown?: boolean; // Show countdown to bar close
-    };
-    interval?: number; // Bar interval in milliseconds (required for countdown)
-    height?: string | number;
-    controls?: {
-        collapse?: boolean;
-        maximize?: boolean;
-        fullscreen?: boolean;
-    };
-    dataZoom?: {
-        visible?: boolean;
-        position?: 'top' | 'bottom';
-        height?: number; // height in %, default 6
-        start?: number; // 0-100, default 50
-        end?: number; // 0-100, default 100
-        zoomOnTouch?: boolean; // Enable inside zoom on touch devices, default true
-    };
-    databox?: {
-        position: 'floating' | 'left' | 'right';
-        triggerOn?: 'mousemove' | 'click' | 'none'; // When to show tooltip/crosshair, default 'mousemove'
-    };
-    layout?: {
-        mainPaneHeight: string; // e.g. "60%"
-        gap: number; // e.g. 5 (percent)
-    };
-    watermark?: boolean; // Default true
-}
-
-// Plugin System Types
-
-export interface Coordinate {
-    x: number;
-    y: number;
-}
-
-export interface DataCoordinate {
-    timeIndex: number;
-    value: number;
-    paneIndex?: number; // Optional pane index
-}
-
-export interface ChartContext {
-    // Core Access
-    getChart(): any; // echarts.ECharts instance
-    getMarketData(): OHLCV[];
-    getTimeToIndex(): Map<number, number>;
-    getOptions(): QFChartOptions;
-
-    // Event Bus
-    events: EventBus;
-
-    // Helpers
-    coordinateConversion: {
-        pixelToData: (point: Coordinate) => DataCoordinate | null;
-        dataToPixel: (point: DataCoordinate) => Coordinate | null;
-    };
-
-    // Interaction Control
-    disableTools(): void; // To disable other active tools
-
-    // Zoom Control
-    setZoom(start: number, end: number): void;
-
-    // Drawing Management
-    addDrawing(drawing: DrawingElement): void;
-    removeDrawing(id: string): void;
-    getDrawing(id: string): DrawingElement | undefined;
-    updateDrawing(drawing: DrawingElement): void;
-
-    // Interaction Locking
-    lockChart(): void;
-    unlockChart(): void;
-}
-
-export type DrawingType = 'line' | 'fibonacci';
-
-export interface DrawingElement {
-    id: string;
-    type: DrawingType;
-    points: DataCoordinate[]; // [start, end]
-    paneIndex?: number; // Pane where this drawing belongs (default 0)
-    style?: {
-        color?: string;
-        lineWidth?: number;
-    };
-}
-
-export interface PluginConfig {
-    id: string;
-    name?: string;
-    icon?: string;
-    hotkey?: string;
-}
-
-export interface Plugin {
-    id: string;
-    name?: string;
-    icon?: string;
-
-    init(context: ChartContext): void;
-
-    // Called when the tool button is clicked/activated
-    activate?(): void;
-
-    // Called when the tool is deactivated
-    deactivate?(): void;
-
-    // Cleanup when plugin is removed
-    destroy?(): void;
-}
+import { EventBus } from './utils/EventBus';
+
+export interface OHLCV {
+    time: number;
+    open: number;
+    high: number;
+    low: number;
+    close: number;
+    volume: number;
+}
+
+export interface IndicatorPoint {
+    time: number;
+    value: number | number[] | null;
+    options?: {
+        color?: string;
+        offset?: number;
+        wickcolor?: string;
+        bordercolor?: string;
+    };
+}
+
+export type IndicatorStyle =
+    | 'line'
+    | 'step'
+    | 'columns'
+    | 'histogram'
+    | 'circles'
+    | 'cross'
+    | 'background'
+    | 'shape'
+    | 'char'
+    | 'bar'
+    | 'candle'
+    | 'barcolor'
+    | 'fill';
+
+export interface IndicatorOptions {
+    style: IndicatorStyle;
+    color: string;
+    overlay?: boolean; // Override indicator-level overlay setting for this specific plot
+    offset?: number;
+    linewidth?: number;
+    smooth?: boolean;
+    shape?: string;
+    size?: string;
+    text?: string;
+    textcolor?: string;
+    location?: string;
+    width?: number;
+    height?: number;
+    wickcolor?: string;
+    bordercolor?: string;
+}
+
+export interface IndicatorPlot {
+    data?: IndicatorPoint[]; // Optional for fill plots
+    options: IndicatorOptions;
+    plot1?: string; // For fill plots: reference to first plot ID
+    plot2?: string; // For fill plots: reference to second plot ID
+}
+
+// A collection of plots that make up a single indicator (e.g. MACD has macd line, signal line, histogram)
+export interface Indicator {
+    id: string;
+    plots: { [name: string]: IndicatorPlot };
+    paneIndex: number;
+    height?: number; // Desired height in percentage (e.g. 15 for 15%)
+    collapsed?: boolean;
+    titleColor?: string;
+    controls?: {
+        collapse?: boolean;
+        maximize?: boolean;
+    };
+}
+
+export interface QFChartOptions {
+    title?: string; // Title for the main chart (e.g. "BTC/USDT")
+    titleColor?: string;
+    backgroundColor?: string;
+    upColor?: string;
+    downColor?: string;
+    fontColor?: string;
+    fontFamily?: string;
+    padding?: number; // Horizontal padding (empty candles on sides), defaults to 0.2
+    yAxisPadding?: number; // Vertical Y-axis padding in percentage (e.g., 5 = 5% padding), defaults to 5
+    yAxisMin?: number | 'auto'; // Fixed minimum value for main Y-axis, or 'auto' for dynamic
+    yAxisMax?: number | 'auto'; // Fixed maximum value for main Y-axis, or 'auto' for dynamic
+    yAxisLabelFormatter?: (value: number) => string; // Custom formatter function for Y-axis labels
+    yAxisDecimalPlaces?: number; // Number of decimal places for Y-axis labels. If undefined, auto-detected from data.
+    lastPriceLine?: {
+        // Configuration for the horizontal line showing the last price
+        visible?: boolean;
+        color?: string; // Defaults to current candle color or '#fff'
+        lineStyle?: 'solid' | 'dashed' | 'dotted'; // Defaults to 'dashed'
+        showCountdown?: boolean; // Show countdown to bar close
+    };
+    interval?: number; // Bar interval in milliseconds (required for countdown)
+    height?: string | number;
+    controls?: {
+        collapse?: boolean;
+        maximize?: boolean;
+        fullscreen?: boolean;
+    };
+    dataZoom?: {
+        visible?: boolean;
+        position?: 'top' | 'bottom';
+        height?: number; // height in %, default 6
+        start?: number; // 0-100, default 50
+        end?: number; // 0-100, default 100
+        zoomOnTouch?: boolean; // Enable inside zoom on touch devices, default true
+    };
+    databox?: {
+        position: 'floating' | 'left' | 'right';
+        triggerOn?: 'mousemove' | 'click' | 'none'; // When to show tooltip/crosshair, default 'mousemove'
+    };
+    layout?: {
+        mainPaneHeight: string; // e.g. "60%"
+        gap: number; // e.g. 5 (percent)
+    };
+    watermark?: boolean; // Default true
+}
+
+// Plugin System Types
+
+export interface Coordinate {
+    x: number;
+    y: number;
+}
+
+export interface DataCoordinate {
+    timeIndex: number;
+    value: number;
+    paneIndex?: number; // Optional pane index
+}
+
+export interface ChartContext {
+    // Core Access
+    getChart(): any; // echarts.ECharts instance
+    getMarketData(): OHLCV[];
+    getTimeToIndex(): Map<number, number>;
+    getOptions(): QFChartOptions;
+
+    // Event Bus
+    events: EventBus;
+
+    // Helpers
+    coordinateConversion: {
+        pixelToData: (point: Coordinate) => DataCoordinate | null;
+        dataToPixel: (point: DataCoordinate) => Coordinate | null;
+    };
+
+    // Interaction Control
+    disableTools(): void; // To disable other active tools
+
+    // Zoom Control
+    setZoom(start: number, end: number): void;
+
+    // Drawing Management
+    addDrawing(drawing: DrawingElement): void;
+    removeDrawing(id: string): void;
+    getDrawing(id: string): DrawingElement | undefined;
+    updateDrawing(drawing: DrawingElement): void;
+
+    // Interaction Locking
+    lockChart(): void;
+    unlockChart(): void;
+}
+
+export type DrawingType = 'line' | 'fibonacci';
+
+export interface DrawingElement {
+    id: string;
+    type: DrawingType;
+    points: DataCoordinate[]; // [start, end]
+    paneIndex?: number; // Pane where this drawing belongs (default 0)
+    style?: {
+        color?: string;
+        lineWidth?: number;
+    };
+}
+
+export interface PluginConfig {
+    id: string;
+    name?: string;
+    icon?: string;
+    hotkey?: string;
+}
+
+export interface Plugin {
+    id: string;
+    name?: string;
+    icon?: string;
+
+    init(context: ChartContext): void;
+
+    // Called when the tool button is clicked/activated
+    activate?(): void;
+
+    // Called when the tool is deactivated
+    deactivate?(): void;
+
+    // Cleanup when plugin is removed
+    destroy?(): void;
+}

package/src/utils/AxisUtils.ts

@@ -0,0 +1,63 @@
+import { OHLCV } from '../types';
+
+export class AxisUtils {
+    // Create min/max functions that apply padding
+    public static createMinFunction(paddingPercent: number) {
+        return (value: { min: number; max: number }) => {
+            const range = value.max - value.min;
+            const padding = range * (paddingPercent / 100);
+            return value.min - padding;
+        };
+    }
+
+    public static createMaxFunction(paddingPercent: number) {
+        return (value: { min: number; max: number }) => {
+            const range = value.max - value.min;
+            const padding = range * (paddingPercent / 100);
+            return value.max + padding;
+        };
+    }
+
+    /**
+     * Auto-detect the appropriate number of decimal places for price display
+     * based on actual market data values.
+     *
+     * For prices like BTCUSDC (~97000), returns 2.
+     * For prices like PUMPUSDT (~0.002), returns 6.
+     *
+     * The algorithm examines a representative close price and determines
+     * how many decimals are needed to show meaningful precision.
+     */
+    public static autoDetectDecimals(marketData: OHLCV[]): number {
+        if (!marketData || marketData.length === 0) return 2;
+
+        // Use the last close price as the representative value
+        const price = marketData[marketData.length - 1].close;
+
+        if (price === 0 || !isFinite(price) || isNaN(price)) return 2;
+
+        const absPrice = Math.abs(price);
+
+        // For prices >= 1, use 2 decimals (e.g. 97000.12, 1.45)
+        if (absPrice >= 1) return 2;
+
+        // For prices < 1, count leading zeros after the decimal point
+        // and add 4 extra digits for meaningful precision (increased from 2).
+        // e.g. 0.002119 -> 3 leading zeros -> 3 + 4 = 7
+        // We cap at 10 to avoid excessive precision.
+        const leadingZeros = Math.ceil(-Math.log10(absPrice));
+        return Math.min(leadingZeros + 4, 10);
+    }
+
+    /**
+     * Format a numeric value with the given number of decimal places.
+     * This is the centralized formatting function used by Y-axis labels,
+     * markLine labels, and countdown labels.
+     */
+    public static formatValue(value: number, decimals: number): string {
+        if (typeof value === 'number') {
+            return value.toFixed(decimals);
+        }
+        return String(value);
+    }
+}

package/src/utils/ColorUtils.ts

@@ -0,0 +1,32 @@
+export class ColorUtils {
+    /**
+     * Parse color string and extract opacity
+     * Supports: hex (#RRGGBB), named colors (green, red), rgba(r,g,b,a), rgb(r,g,b)
+     */
+    public static parseColor(colorStr: string): { color: string; opacity: number } {
+        if (!colorStr) {
+            return { color: '#888888', opacity: 0.2 };
+        }
+
+        // Check for rgba format
+        const rgbaMatch = colorStr.match(/rgba?\((\d+),\s*(\d+),\s*(\d+)(?:,\s*([\d.]+))?\)/);
+        if (rgbaMatch) {
+            const r = rgbaMatch[1];
+            const g = rgbaMatch[2];
+            const b = rgbaMatch[3];
+            const a = rgbaMatch[4] ? parseFloat(rgbaMatch[4]) : 1;
+
+            // Return rgb color and separate opacity
+            return {
+                color: `rgb(${r},${g},${b})`,
+                opacity: a,
+            };
+        }
+
+        // For hex or named colors, default opacity to 0.3 for fill areas
+        return {
+            color: colorStr,
+            opacity: 0.3,
+        };
+    }
+}

package/src/utils/ShapeUtils.ts

@@ -0,0 +1,140 @@
+export class ShapeUtils {
+    public static getShapeSymbol(shape: string): string {
+        // SVG Paths need to be:
+        // 1. Valid SVG path data strings
+        // 2. Ideally centered around the origin or a standard box (e.g., 0 0 24 24)
+        // 3. ECharts path:// format expects just the path data usually, but complex shapes might need 'image://' or better paths.
+        // For simple shapes, standard ECharts symbols or simple paths work.
+
+        switch (shape) {
+            case 'arrowdown':
+                // Blocky arrow down
+                return 'path://M12 24l-12-12h8v-12h8v12h8z';
+
+            case 'arrowup':
+                // Blocky arrow up
+                return 'path://M12 0l12 12h-8v12h-8v-12h-8z';
+
+            case 'circle':
+                return 'circle';
+
+            case 'cross':
+                // Plus sign (+)
+                return 'path://M11 2h2v9h9v2h-9v9h-2v-9h-9v-2h9z';
+
+            case 'diamond':
+                return 'diamond'; // Built-in
+
+            case 'flag':
+                // Flag on a pole
+                return 'path://M6 2v20h2v-8h12l-2-6 2-6h-12z';
+
+            case 'labeldown':
+                // Bubble pointing down: Rounded rect with a triangle at bottom
+                return 'path://M4 2h16a2 2 0 0 1 2 2v12a2 2 0 0 1 -2 2h-6l-2 4l-2 -4h-6a2 2 0 0 1 -2 -2v-12a2 2 0 0 1 2 -2z';
+
+            case 'labelup':
+                // Bubble pointing up: Rounded rect with triangle at top
+                return 'path://M12 2l2 4h6a2 2 0 0 1 2 2v12a2 2 0 0 1 -2 2h-16a2 2 0 0 1 -2 -2v-12a2 2 0 0 1 2 -2h6z';
+
+            case 'square':
+                return 'rect';
+
+            case 'triangledown':
+                // Pointing down
+                return 'path://M12 21l-10-18h20z';
+
+            case 'triangleup':
+                // Pointing up
+                return 'triangle'; // Built-in is pointing up
+
+            case 'xcross':
+                // 'X' shape
+                return 'path://M19 6.41L17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12z';
+
+            default:
+                return 'circle';
+        }
+    }
+
+    public static getShapeRotation(shape: string): number {
+        // With custom paths defined above, we might not need rotation unless we reuse shapes.
+        // Built-in triangle is UP.
+        return 0;
+    }
+
+    public static getShapeSize(size: string, width?: number, height?: number): number | number[] {
+        // If both width and height are specified, use them directly
+        if (width !== undefined && height !== undefined) {
+            return [width, height];
+        }
+
+        // Base size from the size parameter
+        let baseSize: number;
+        switch (size) {
+            case 'tiny':
+                baseSize = 8;
+                break;
+            case 'small':
+                baseSize = 12;
+                break;
+            case 'normal':
+            case 'auto':
+                baseSize = 16;
+                break;
+            case 'large':
+                baseSize = 24;
+                break;
+            case 'huge':
+                baseSize = 32;
+                break;
+            default:
+                baseSize = 16;
+        }
+
+        // If only width is specified, preserve aspect ratio (assume square default)
+        if (width !== undefined) {
+            return [width, width];
+        }
+
+        // If only height is specified, preserve aspect ratio (assume square default)
+        if (height !== undefined) {
+            return [height, height];
+        }
+
+        // Default uniform size
+        return baseSize;
+    }
+
+    // Helper to determine label position and distance relative to shape BASED ON LOCATION
+    public static getLabelConfig(shape: string, location: string): { position: string; distance: number } {
+        // Text position should be determined by location, not shape direction
+
+        switch (location) {
+            case 'abovebar':
+                // Shape is above the candle, text should be above the shape
+                return { position: 'top', distance: 5 };
+
+            case 'belowbar':
+                // Shape is below the candle, text should be below the shape
+                return { position: 'bottom', distance: 5 };
+
+            case 'top':
+                // Shape at top of chart, text below it
+                return { position: 'bottom', distance: 5 };
+
+            case 'bottom':
+                // Shape at bottom of chart, text above it
+                return { position: 'top', distance: 5 };
+
+            case 'absolute':
+            default:
+                // For labelup/down, text is INSIDE the shape
+                if (shape === 'labelup' || shape === 'labeldown') {
+                    return { position: 'inside', distance: 0 };
+                }
+                // For other shapes, text above by default
+                return { position: 'top', distance: 5 };
+        }
+    }
+}