react-klinecharts-ui 0.1.0 → 0.3.0

package/dist/index.d.cts

@@ -1,8 +1,8 @@
 import * as react from 'react';
 import { Dispatch, RefObject, ReactNode, ReactElement } from 'react';
-import { Period, SymbolInfo, KLineData, Chart, DeepPartial, Styles, OverlayTemplate, DataLoader } from 'react-klinecharts';
+import { Period, SymbolInfo, KLineData, Chart, DeepPartial, Styles, OverlayTemplate, DataLoader, IndicatorTemplate } from 'react-klinecharts';
 import { OrderLineExtendData } from './extensions.cjs';
-export { OrderLineFontStyle, OrderLineLabelStyle, OrderLineLineStyle, OrderLineMarkStyle, OrderLinePadding, orderLine, overlays, registerExtensions } from './extensions.cjs';
+export { DepthOverlayExtendData, DepthOverlayRow, OrderLineFontStyle, OrderLineLabelStyle, OrderLineLineStyle, OrderLineMarkStyle, OrderLinePadding, depthOverlay, indicators, orderLine, overlays, registerExtensions } from './extensions.cjs';
 
 interface TerminalPeriod extends Period {
     label: string;
@@ -102,12 +102,19 @@ type KlinechartsUIAction = {
     type: "SET_SCREENSHOT_URL";
     url: string | null;
 };
+/** Callback pushed by useUndoRedo so other hooks can record actions. */
+type UndoRedoListener = (action: {
+    type: string;
+    data: unknown;
+}) => void;
 /** The stable, dispatch-only slice of the context (never changes after mount). */
 interface KlinechartsUIDispatchValue {
     dispatch: Dispatch<KlinechartsUIAction>;
     datafeed: Datafeed;
     onSettingsChange?: (settings: Record<string, unknown>) => void;
     fullscreenContainerRef: RefObject<HTMLElement | null>;
+    /** Ref populated by useUndoRedo; other hooks call it to record actions. */
+    undoRedoListenerRef: RefObject<UndoRedoListener | null>;
 }
 /** Combined context value returned by `useKlinechartsUI()`. */
 interface KlinechartsUIContextValue extends KlinechartsUIDispatchValue {
@@ -192,6 +199,14 @@ interface UseIndicatorsReturn {
     }[];
     isMainIndicatorActive: (name: string) => boolean;
     isSubIndicatorActive: (name: string) => boolean;
+    /** Collapse a sub-indicator pane to minimal height (30px). */
+    collapseSubIndicator: (name: string) => void;
+    /** Expand a previously collapsed sub-indicator pane to its prior height. */
+    expandSubIndicator: (name: string) => void;
+    /** Whether the given sub-indicator pane is currently collapsed. */
+    isSubIndicatorCollapsed: (name: string) => boolean;
+    /** Reorder a sub-indicator pane up or down relative to other sub-indicators. */
+    reorderSubIndicator: (name: string, direction: "up" | "down") => void;
 }
 declare function useIndicators(): UseIndicatorsReturn;
 
@@ -220,12 +235,16 @@ interface UseDrawingToolsReturn {
     magnetMode: MagnetMode;
     isLocked: boolean;
     isVisible: boolean;
+    /** Whether drawing tools auto-retrigger after completing a shape. Default: true. */
+    autoRetrigger: boolean;
     selectTool: (name: string) => void;
     clearActiveTool: () => void;
     setMagnetMode: (mode: MagnetMode) => void;
     toggleLock: () => void;
     toggleVisibility: () => void;
     removeAllDrawings: () => void;
+    /** Enable/disable auto-retrigger mode. */
+    setAutoRetrigger: (enabled: boolean) => void;
 }
 declare function useDrawingTools(): UseDrawingToolsReturn;
 
@@ -358,6 +377,311 @@ interface UseOrderLinesReturn {
 }
 declare function useOrderLines(): UseOrderLinesReturn;
 
+type UndoRedoActionType = "overlay_added" | "overlays_removed" | "indicator_toggled";
+interface UndoRedoAction {
+    type: UndoRedoActionType;
+    /** Snapshot data needed to undo/redo this action */
+    data: any;
+}
+interface UseUndoRedoReturn {
+    /** Whether there are actions to undo */
+    canUndo: boolean;
+    /** Whether there are actions to redo */
+    canRedo: boolean;
+    /** Undo the last action */
+    undo: () => void;
+    /** Redo the last undone action */
+    redo: () => void;
+    /** Push a new action onto the undo stack (clears redo stack) */
+    pushAction: (action: UndoRedoAction) => void;
+    /** Clear all undo/redo history */
+    clear: () => void;
+}
+/**
+ * Headless hook for undo/redo of drawing overlays and indicator toggles.
+ *
+ * Supports keyboard shortcuts: Ctrl+Z (undo), Ctrl+Y / Ctrl+Shift+Z (redo).
+ */
+declare function useUndoRedo(): UseUndoRedoReturn;
+
+interface ChartLayoutState {
+    version: string;
+    meta: {
+        symbol: string;
+        period: string;
+        timestamp: number;
+        lastModified: number;
+    };
+    indicators: Array<{
+        paneId: string;
+        name: string;
+        calcParams: any[];
+        visible: boolean;
+        styles?: any;
+    }>;
+    drawings: Array<{
+        name: string;
+        points: any[];
+        styles?: any;
+        extendData?: any;
+    }>;
+}
+interface LayoutEntry {
+    id: string;
+    name: string;
+    symbol: string;
+    period: string;
+    timestamp: number;
+    lastModified: number;
+    state: ChartLayoutState;
+}
+interface UseLayoutManagerReturn {
+    /** List of saved layout entries */
+    layouts: LayoutEntry[];
+    /** Save current chart state as a named layout */
+    saveLayout: (name: string) => string | null;
+    /** Load a layout by ID and apply to the chart */
+    loadLayout: (id: string) => boolean;
+    /** Delete a layout by ID */
+    deleteLayout: (id: string) => void;
+    /** Rename a layout */
+    renameLayout: (id: string, name: string) => boolean;
+    /** Refresh the layouts list from localStorage */
+    refreshLayouts: () => void;
+    /** Whether auto-save is enabled */
+    autoSaveEnabled: boolean;
+    /** Toggle auto-save on/off */
+    setAutoSaveEnabled: (enabled: boolean) => void;
+}
+/**
+ * Headless hook for saving, loading, and managing named chart layouts
+ * via localStorage. Supports auto-save with 5-second debounce.
+ */
+declare function useLayoutManager(): UseLayoutManagerReturn;
+
+type ScriptPlacement = "main" | "sub";
+interface UseScriptEditorReturn {
+    /** Current script source code */
+    code: string;
+    setCode: (code: string) => void;
+    /** Display name of the script */
+    scriptName: string;
+    setScriptName: (name: string) => void;
+    /** Comma-separated numeric params (e.g. "14, 26, 9") */
+    params: string;
+    setParams: (params: string) => void;
+    /** Where to place the indicator */
+    placement: ScriptPlacement;
+    setPlacement: (p: ScriptPlacement) => void;
+    /** Last error message (empty = no error) */
+    error: string;
+    /** Last status message */
+    status: string;
+    /** Whether the script is currently running */
+    isRunning: boolean;
+    /** Whether there is a script indicator currently on the chart */
+    hasActiveScript: boolean;
+    /** Execute the script and register the indicator */
+    runScript: () => void;
+    /** Remove the current script indicator from the chart */
+    removeScript: () => void;
+    /** Reset code to the default template */
+    resetCode: () => void;
+    /** Export the current code as a downloadable .js file */
+    exportScript: () => void;
+    /** Import a script from a File object */
+    importScript: (file: File) => void;
+    /** The default template code */
+    defaultScript: string;
+}
+/**
+ * Headless hook for a Pine Script-style custom indicator editor.
+ *
+ * Scripts are plain JavaScript function bodies that receive:
+ *   - `TA`       — technical analysis math library
+ *   - `dataList` — KLineData[] (open, high, low, close, volume, timestamp)
+ *   - `params`   — number[] from the params input
+ *
+ * Must return an array of objects, one per candle. Each key = one chart series.
+ */
+declare function useScriptEditor(): UseScriptEditorReturn;
+
+interface CrosshairBarData {
+    open: number;
+    high: number;
+    low: number;
+    close: number;
+    volume: number;
+    timestamp: number;
+    change: number;
+    changePercent: number;
+}
+interface UseCrosshairReturn {
+    /** OHLCV data of the bar under the crosshair. Null when cursor is off-chart. */
+    barData: CrosshairBarData | null;
+}
+declare function useCrosshair(): UseCrosshairReturn;
+
+type AlertCondition = "crossing_up" | "crossing_down" | "crossing";
+interface Alert {
+    id: string;
+    price: number;
+    condition: AlertCondition;
+    message?: string;
+    triggered: boolean;
+}
+interface UseAlertsReturn {
+    alerts: Alert[];
+    addAlert: (price: number, condition: AlertCondition, message?: string) => string;
+    removeAlert: (id: string) => void;
+    clearAlerts: () => void;
+    onAlertTriggered: (callback: (alert: Alert) => void) => void;
+}
+declare function useAlerts(): UseAlertsReturn;
+
+type ExportFormat = "csv" | "json";
+interface UseDataExportReturn {
+    /** Export all chart data */
+    exportAll: (format: ExportFormat) => void;
+    /** Export only the visible range */
+    exportVisible: (format: ExportFormat) => void;
+}
+declare function useDataExport(): UseDataExportReturn;
+
+interface WatchlistItem {
+    ticker: string;
+    lastPrice: number | null;
+    change: number | null;
+    changePercent: number | null;
+}
+interface UseWatchlistReturn {
+    items: WatchlistItem[];
+    addSymbol: (ticker: string) => void;
+    removeSymbol: (ticker: string) => void;
+    switchSymbol: (ticker: string) => void;
+    activeSymbol: string | null;
+}
+declare function useWatchlist(): UseWatchlistReturn;
+
+type ReplaySpeed = 1 | 2 | 5 | 10;
+interface UseReplayReturn {
+    /** Whether a replay session is active */
+    isReplaying: boolean;
+    /** Whether the replay is currently paused */
+    isPaused: boolean;
+    /** Current playback speed multiplier */
+    speed: ReplaySpeed;
+    /** Current bar index in the replay */
+    barIndex: number;
+    /** Total number of bars in the saved data */
+    totalBars: number;
+    /** Start replaying from the beginning */
+    startReplay: () => void;
+    /** Stop replay and restore original data */
+    stopReplay: () => void;
+    /** Toggle play/pause */
+    togglePause: () => void;
+    /** Advance one bar while paused */
+    stepForward: () => void;
+    /** Go back one bar while paused */
+    stepBackward: () => void;
+    /** Seek to a specific bar index (0-based). Pauses playback. */
+    seekTo: (index: number) => void;
+    /** Change the playback speed */
+    setSpeed: (speed: ReplaySpeed) => void;
+}
+/**
+ * Headless hook for historical data replay (bar-by-bar playback).
+ *
+ * Loads the current chart data, clears the chart, then progressively adds
+ * bars back one at a time at the configured speed. Useful for backtesting
+ * and reviewing price action.
+ */
+declare function useReplay(): UseReplayReturn;
+
+interface CompareSymbol {
+    ticker: string;
+    /** Base price (first bar close) used for percentage normalization */
+    basePrice: number | null;
+    color: string;
+    visible: boolean;
+}
+interface UseCompareReturn {
+    /** Currently compared symbols */
+    symbols: CompareSymbol[];
+    /** Add a symbol — fetches data, normalizes to %, renders as indicator line */
+    addSymbol: (ticker: string, color?: string) => Promise<void>;
+    /** Remove a symbol overlay */
+    removeSymbol: (ticker: string) => void;
+    /** Toggle visibility of a compared symbol */
+    toggleSymbol: (ticker: string) => void;
+    /** Clear all comparisons */
+    clearAll: () => void;
+}
+/**
+ * Headless hook for comparing multiple symbols on the same chart.
+ *
+ * Fetches historical data for each added symbol via the datafeed,
+ * normalizes prices to percentage change from the first bar,
+ * and renders each as a custom indicator line on the main pane.
+ */
+declare function useCompare(): UseCompareReturn;
+
+interface MeasurePoint {
+    price: number;
+    timestamp: number;
+    barIndex: number;
+}
+interface MeasureResult {
+    from: MeasurePoint;
+    to: MeasurePoint;
+    /** Absolute price difference */
+    priceDiff: number;
+    /** Percentage change from → to */
+    pricePercent: number;
+    /** Number of bars between the two points */
+    bars: number;
+    /** Time difference in milliseconds */
+    timeDiff: number;
+}
+interface UseMeasureReturn {
+    /** Whether measure mode is active (waiting for clicks) */
+    isActive: boolean;
+    /** Start measure mode — next two clicks on chart set from/to */
+    startMeasure: () => void;
+    /** Cancel measure mode */
+    cancelMeasure: () => void;
+    /** Current measurement result (null until both points are set) */
+    result: MeasureResult | null;
+    /** Clear the current measurement */
+    clearResult: () => void;
+    /** First point (set after first click) */
+    fromPoint: MeasurePoint | null;
+}
+/**
+ * Headless hook for measuring distance/time/percentage between two points.
+ *
+ * Activates measure mode, captures two clicks on the chart via overlay
+ * interaction, then computes price diff, %, bar count, and time diff.
+ */
+declare function useMeasure(): UseMeasureReturn;
+
+interface Annotation {
+    id: string;
+    text: string;
+    price: number;
+    timestamp: number;
+    color?: string;
+}
+interface UseAnnotationsReturn {
+    annotations: Annotation[];
+    addAnnotation: (text: string, price: number, timestamp: number, color?: string) => string;
+    removeAnnotation: (id: string) => void;
+    updateAnnotation: (id: string, updates: Partial<Pick<Annotation, "text" | "color">>) => void;
+    clearAnnotations: () => void;
+}
+declare function useAnnotations(): UseAnnotationsReturn;
+
 interface TimezoneOption {
     key: string;
     localeKey: string;
@@ -389,6 +713,76 @@ declare const INDICATOR_PARAMS: Record<string, IndicatorDefinition>;
  */
 declare function createDataLoader(datafeed: Datafeed, dispatch: Dispatch<KlinechartsUIAction>): DataLoader;
 
+/**
+ * Technical Analysis (TA) Utility Library
+ * Ported logic to match TradingView / Pine Script calculations.
+ */
+declare const TA: {
+    /**
+     * Simple Moving Average (SMA)
+     * Optimized with running sum.
+     */
+    sma: (data: number[], period: number) => (number | null)[];
+    /**
+     * Exponential Moving Average (EMA)
+     * alpha = 2 / (period + 1)
+     */
+    ema: (data: number[], period: number) => (number | null)[];
+    /**
+     * Running Moving Average (RMA / Wilder's MA)
+     * Used in RSI, alpha = 1 / period
+     */
+    rma: (data: number[], period: number) => (number | null)[];
+    /**
+     * Standard Deviation
+     */
+    stdev: (data: number[], period: number) => (number | null)[];
+    /**
+     * Relative Strength Index (RSI)
+     */
+    rsi: (data: number[], period: number) => (number | null)[];
+    /**
+     * Moving Average Convergence Divergence (MACD)
+     */
+    macd: (data: number[], fastPeriod: number, slowPeriod: number, signalPeriod: number) => {
+        dif: (number | null)[];
+        dea: (number | null)[];
+        macd: (number | null)[];
+    };
+    /**
+     * Bollinger Bands (BOLL)
+     */
+    bollinger: (data: number[], period: number, multiplier: number) => {
+        mid: (number | null)[];
+        upper: (number | null)[];
+        lower: (number | null)[];
+    };
+    /**
+     * Weighted Moving Average (WMA)
+     */
+    wma: (data: number[], period: number) => (number | null)[];
+    /**
+     * True Range (TR)
+     */
+    tr: (highs: number[], lows: number[], closes: number[]) => number[];
+    /**
+     * Average True Range (ATR)
+     */
+    atr: (highs: number[], lows: number[], closes: number[], period: number) => (number | null)[];
+    /**
+     * Volume Weighted Average Price (VWAP)
+     */
+    vwap: (highs: number[], lows: number[], closes: number[], volumes: number[]) => (number | null)[];
+    /**
+     * Commodity Channel Index (CCI)
+     */
+    cci: (highs: number[], lows: number[], closes: number[], period: number) => (number | null)[];
+    /**
+     * Hull Moving Average (HMA)
+     */
+    hma: (data: number[], period: number) => (number | null)[];
+};
+
 declare const arrow: OverlayTemplate;
 
 declare const circle: OverlayTemplate;
@@ -409,8 +803,12 @@ declare const fibonacciSpeedResistanceFan: OverlayTemplate;
 
 declare const fibonacciExtension: OverlayTemplate;
 
+declare const fibRetracement: OverlayTemplate;
+
 declare const gannBox: OverlayTemplate;
 
+declare const gannFan: OverlayTemplate;
+
 declare const threeWaves: OverlayTemplate;
 
 declare const fiveWaves: OverlayTemplate;
@@ -419,8 +817,48 @@ declare const eightWaves: OverlayTemplate;
 
 declare const anyWaves: OverlayTemplate;
 
+declare const elliottWave: OverlayTemplate;
+
 declare const abcd: OverlayTemplate;
 
 declare const xabcd: OverlayTemplate;
 
-export { CANDLE_TYPES, COMPARE_RULES, type CandleTypeItem, type CandleTypeOption, type CompareRule, DEFAULT_PERIODS, DRAWING_CATEGORIES, type Datafeed, type DrawingCategoryItem, type DrawingTool, type DrawingToolCategory, type DrawingToolItem, INDICATOR_PARAMS, type IndicatorDefinition, type IndicatorInfo, type IndicatorParamConfig, type KlinechartsUIAction, type KlinechartsUIContextValue, KlinechartsUIDispatchContext, type KlinechartsUIDispatchValue, type KlinechartsUIOptions, KlinechartsUIProvider, type KlinechartsUISettingsState, type KlinechartsUIState, KlinechartsUIStateContext, MAIN_INDICATORS, type MagnetMode, OrderLineExtendData, type OrderLineOptions, PRICE_AXIS_TYPES, type PartialSymbolInfo, type PriceAxisType, SUB_INDICATORS, TIMEZONES, TOOLTIP_SHOW_RULES, type TerminalPeriod, type TimezoneItem, type TimezoneOption, type TooltipShowRule, type UseDrawingToolsReturn, type UseFullscreenReturn, type UseIndicatorsReturn, type UseKlinechartsUILoadingReturn, type UseKlinechartsUISettingsReturn, type UseKlinechartsUIThemeReturn, type UseOrderLinesReturn, type UsePeriodsReturn, type UseScreenshotReturn, type UseSymbolSearchReturn, type UseTimezoneReturn, YAXIS_POSITIONS, type YAxisPosition, abcd, anyWaves, arrow, circle, createDataLoader, eightWaves, fibonacciCircle, fibonacciExtension, fibonacciSegment, fibonacciSpeedResistanceFan, fibonacciSpiral, fiveWaves, gannBox, parallelogram, rect, threeWaves, triangle, useDrawingTools, useFullscreen, useIndicators, useKlinechartsUI, useKlinechartsUILoading, useKlinechartsUISettings, useKlinechartsUITheme, useOrderLines, usePeriods, useScreenshot, useSymbolSearch, useTimezone, xabcd };
+declare const ray: OverlayTemplate;
+
+declare const parallelChannel: OverlayTemplate;
+
+declare const longPosition: OverlayTemplate;
+
+declare const shortPosition: OverlayTemplate;
+
+declare const measure: OverlayTemplate;
+
+declare const brush: OverlayTemplate;
+
+declare const bollTv: IndicatorTemplate;
+
+declare const cci: IndicatorTemplate;
+
+declare const hma: IndicatorTemplate;
+
+declare const ichimoku: IndicatorTemplate;
+
+declare const maRibbon: IndicatorTemplate;
+
+declare const macdTv: IndicatorTemplate;
+
+declare const pivotPoints: IndicatorTemplate;
+
+/**
+ * TradingView-style RSI with RMA-based calculation,
+ * dashed level lines at 70/50/30, and gradient fills.
+ */
+declare const rsiTv: IndicatorTemplate;
+
+declare const stochastic: IndicatorTemplate;
+
+declare const superTrend: IndicatorTemplate;
+
+declare const vwap: IndicatorTemplate;
+
+export { type Alert, type AlertCondition, type Annotation, CANDLE_TYPES, COMPARE_RULES, type CandleTypeItem, type CandleTypeOption, type ChartLayoutState, type CompareRule, type CompareSymbol, type CrosshairBarData, DEFAULT_PERIODS, DRAWING_CATEGORIES, type Datafeed, type DrawingCategoryItem, type DrawingTool, type DrawingToolCategory, type DrawingToolItem, type ExportFormat, INDICATOR_PARAMS, type IndicatorDefinition, type IndicatorInfo, type IndicatorParamConfig, type KlinechartsUIAction, type KlinechartsUIContextValue, KlinechartsUIDispatchContext, type KlinechartsUIDispatchValue, type KlinechartsUIOptions, KlinechartsUIProvider, type KlinechartsUISettingsState, type KlinechartsUIState, KlinechartsUIStateContext, type LayoutEntry, MAIN_INDICATORS, type MagnetMode, type MeasurePoint, type MeasureResult, OrderLineExtendData, type OrderLineOptions, PRICE_AXIS_TYPES, type PartialSymbolInfo, type PriceAxisType, type ReplaySpeed, SUB_INDICATORS, type ScriptPlacement, TA, TIMEZONES, TOOLTIP_SHOW_RULES, type TerminalPeriod, type TimezoneItem, type TimezoneOption, type TooltipShowRule, type UndoRedoAction, type UndoRedoActionType, type UseAlertsReturn, type UseAnnotationsReturn, type UseCompareReturn, type UseCrosshairReturn, type UseDataExportReturn, type UseDrawingToolsReturn, type UseFullscreenReturn, type UseIndicatorsReturn, type UseKlinechartsUILoadingReturn, type UseKlinechartsUISettingsReturn, type UseKlinechartsUIThemeReturn, type UseLayoutManagerReturn, type UseMeasureReturn, type UseOrderLinesReturn, type UsePeriodsReturn, type UseReplayReturn, type UseScreenshotReturn, type UseScriptEditorReturn, type UseSymbolSearchReturn, type UseTimezoneReturn, type UseUndoRedoReturn, type UseWatchlistReturn, type WatchlistItem, YAXIS_POSITIONS, type YAxisPosition, abcd, anyWaves, arrow, bollTv, brush, cci, circle, createDataLoader, eightWaves, elliottWave, fibRetracement, fibonacciCircle, fibonacciExtension, fibonacciSegment, fibonacciSpeedResistanceFan, fibonacciSpiral, fiveWaves, gannBox, gannFan, hma, ichimoku, longPosition, maRibbon, macdTv, measure, parallelChannel, parallelogram, pivotPoints, ray, rect, rsiTv, shortPosition, stochastic, superTrend, threeWaves, triangle, useAlerts, useAnnotations, useCompare, useCrosshair, useDataExport, useDrawingTools, useFullscreen, useIndicators, useKlinechartsUI, useKlinechartsUILoading, useKlinechartsUISettings, useKlinechartsUITheme, useLayoutManager, useMeasure, useOrderLines, usePeriods, useReplay, useScreenshot, useScriptEditor, useSymbolSearch, useTimezone, useUndoRedo, useWatchlist, vwap, xabcd };