react-klinecharts-ui 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,426 @@
+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 { OrderLineExtendData } from './extensions.cjs';
+export { OrderLineFontStyle, OrderLineLabelStyle, OrderLineLineStyle, OrderLineMarkStyle, OrderLinePadding, orderLine, overlays, registerExtensions } from './extensions.cjs';
+
+interface TerminalPeriod extends Period {
+    label: string;
+}
+declare const DEFAULT_PERIODS: TerminalPeriod[];
+
+/**
+ * Explicit partial symbol type — avoids `PickPartial<SymbolInfo, ...>` which
+ * degenerates when SymbolInfo has an index signature `[key: string]: unknown`.
+ */
+interface PartialSymbolInfo {
+    ticker: string;
+    pricePrecision?: number;
+    volumePrecision?: number;
+    [key: string]: unknown;
+}
+interface Datafeed {
+    searchSymbols(search: string, signal?: AbortSignal): Promise<PartialSymbolInfo[]>;
+    getHistoryKLineData(symbol: SymbolInfo, period: TerminalPeriod, from: number, to: number): Promise<KLineData[]>;
+    subscribe(symbol: SymbolInfo, period: TerminalPeriod, callback: (data: KLineData) => void): void;
+    unsubscribe(symbol: SymbolInfo, period: TerminalPeriod): void;
+}
+interface KlinechartsUIOptions {
+    datafeed: Datafeed;
+    defaultSymbol?: PartialSymbolInfo;
+    defaultPeriod?: TerminalPeriod;
+    defaultTheme?: string;
+    defaultTimezone?: string;
+    defaultMainIndicators?: string[];
+    defaultSubIndicators?: string[];
+    defaultLocale?: string;
+    periods?: TerminalPeriod[];
+    styles?: DeepPartial<Styles>;
+    registerExtensions?: boolean;
+    /**
+     * Additional overlay templates to register on mount (e.g. `orderLine`, custom overlays).
+     * These are registered once, alongside the built-in drawing-tool overlays.
+     */
+    overlays?: OverlayTemplate[];
+    children: ReactNode;
+    /** Called on every dispatched action with the resulting new state and previous state. */
+    onStateChange?: (action: KlinechartsUIAction, nextState: KlinechartsUIState, prevState: KlinechartsUIState) => void;
+    onSymbolChange?: (symbol: PartialSymbolInfo) => void;
+    onPeriodChange?: (period: TerminalPeriod) => void;
+    onThemeChange?: (theme: string) => void;
+    onTimezoneChange?: (timezone: string) => void;
+    onMainIndicatorsChange?: (indicators: string[]) => void;
+    onSubIndicatorsChange?: (indicators: Record<string, string>) => void;
+    onSettingsChange?: (settings: Record<string, unknown>) => void;
+}
+interface KlinechartsUIState {
+    chart: Chart | null;
+    datafeed: Datafeed;
+    symbol: PartialSymbolInfo | null;
+    period: TerminalPeriod;
+    theme: string;
+    timezone: string;
+    isLoading: boolean;
+    locale: string;
+    periods: TerminalPeriod[];
+    mainIndicators: string[];
+    subIndicators: Record<string, string>;
+    styles: DeepPartial<Styles> | undefined;
+    screenshotUrl: string | null;
+}
+type KlinechartsUIAction = {
+    type: "SET_CHART";
+    chart: Chart;
+} | {
+    type: "SET_SYMBOL";
+    symbol: PartialSymbolInfo;
+} | {
+    type: "SET_PERIOD";
+    period: TerminalPeriod;
+} | {
+    type: "SET_THEME";
+    theme: string;
+} | {
+    type: "SET_TIMEZONE";
+    timezone: string;
+} | {
+    type: "SET_LOADING";
+    isLoading: boolean;
+} | {
+    type: "SET_MAIN_INDICATORS";
+    indicators: string[];
+} | {
+    type: "SET_SUB_INDICATORS";
+    indicators: Record<string, string>;
+} | {
+    type: "SET_STYLES";
+    styles: DeepPartial<Styles> | undefined;
+} | {
+    type: "SET_LOCALE";
+    locale: string;
+} | {
+    type: "SET_SCREENSHOT_URL";
+    url: string | null;
+};
+/** 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>;
+}
+/** Combined context value returned by `useKlinechartsUI()`. */
+interface KlinechartsUIContextValue extends KlinechartsUIDispatchValue {
+    state: KlinechartsUIState;
+}
+
+declare function KlinechartsUIProvider({ datafeed, defaultSymbol, defaultPeriod, defaultTheme, defaultTimezone, defaultMainIndicators, defaultSubIndicators, defaultLocale, periods, styles, registerExtensions: shouldRegister, overlays: extraOverlays, children, onStateChange, onSymbolChange, onPeriodChange, onThemeChange, onTimezoneChange, onMainIndicatorsChange, onSubIndicatorsChange, onSettingsChange, }: KlinechartsUIOptions): ReactElement;
+
+declare const KlinechartsUIStateContext: react.Context<KlinechartsUIState | null>;
+declare const KlinechartsUIDispatchContext: react.Context<KlinechartsUIDispatchValue | null>;
+/**
+ * Primary hook — returns the full combined context value.
+ * For performance-sensitive cases, prefer the two split hooks internally.
+ */
+declare function useKlinechartsUI(): KlinechartsUIContextValue;
+
+interface UseKlinechartsUIThemeReturn {
+    theme: string;
+    setTheme: (theme: string) => void;
+    toggleTheme: () => void;
+}
+declare function useKlinechartsUITheme(): UseKlinechartsUIThemeReturn;
+
+interface UseKlinechartsUILoadingReturn {
+    isLoading: boolean;
+}
+declare function useKlinechartsUILoading(): UseKlinechartsUILoadingReturn;
+
+interface UsePeriodsReturn {
+    periods: TerminalPeriod[];
+    activePeriod: TerminalPeriod;
+    setPeriod: (period: TerminalPeriod) => void;
+}
+declare function usePeriods(): UsePeriodsReturn;
+
+interface TimezoneItem {
+    key: string;
+    localeKey: string;
+}
+interface UseTimezoneReturn {
+    timezones: TimezoneItem[];
+    activeTimezone: string;
+    setTimezone: (timezone: string) => void;
+}
+declare function useTimezone(): UseTimezoneReturn;
+
+interface UseSymbolSearchReturn {
+    query: string;
+    results: PartialSymbolInfo[];
+    isSearching: boolean;
+    activeSymbol: PartialSymbolInfo | null;
+    setQuery: (query: string) => void;
+    selectSymbol: (symbol: PartialSymbolInfo) => void;
+    clearResults: () => void;
+}
+declare function useSymbolSearch(debounceMs?: number): UseSymbolSearchReturn;
+
+interface IndicatorInfo {
+    name: string;
+    isActive: boolean;
+}
+interface UseIndicatorsReturn {
+    mainIndicators: IndicatorInfo[];
+    subIndicators: IndicatorInfo[];
+    activeMainIndicators: string[];
+    activeSubIndicators: Record<string, string>;
+    availableMainIndicators: string[];
+    availableSubIndicators: string[];
+    addMainIndicator: (name: string) => void;
+    removeMainIndicator: (name: string) => void;
+    addSubIndicator: (name: string) => void;
+    removeSubIndicator: (name: string) => void;
+    toggleMainIndicator: (name: string) => void;
+    toggleSubIndicator: (name: string) => void;
+    moveToMain: (name: string) => void;
+    moveToSub: (name: string) => void;
+    setIndicatorVisible: (name: string, isMain: boolean, visible: boolean) => void;
+    updateIndicatorParams: (name: string, paneId: string, params: number[]) => void;
+    getIndicatorParams: (name: string) => {
+        label: string;
+        defaultValue: number;
+    }[];
+    isMainIndicatorActive: (name: string) => boolean;
+    isSubIndicatorActive: (name: string) => boolean;
+}
+declare function useIndicators(): UseIndicatorsReturn;
+
+interface DrawingTool {
+    name: string;
+    localeKey: string;
+}
+interface DrawingToolCategory {
+    key: string;
+    tools: DrawingTool[];
+}
+declare const DRAWING_CATEGORIES: DrawingToolCategory[];
+type MagnetMode = "normal" | "weak" | "strong";
+
+interface DrawingToolItem {
+    name: string;
+    localeKey: string;
+}
+interface DrawingCategoryItem {
+    key: string;
+    tools: DrawingToolItem[];
+}
+interface UseDrawingToolsReturn {
+    categories: DrawingCategoryItem[];
+    activeTool: string | null;
+    magnetMode: MagnetMode;
+    isLocked: boolean;
+    isVisible: boolean;
+    selectTool: (name: string) => void;
+    clearActiveTool: () => void;
+    setMagnetMode: (mode: MagnetMode) => void;
+    toggleLock: () => void;
+    toggleVisibility: () => void;
+    removeAllDrawings: () => void;
+}
+declare function useDrawingTools(): UseDrawingToolsReturn;
+
+interface CandleTypeOption {
+    key: string;
+    localeKey: string;
+}
+declare const CANDLE_TYPES: CandleTypeOption[];
+declare const PRICE_AXIS_TYPES: readonly ["normal", "percentage", "logarithm"];
+type PriceAxisType = (typeof PRICE_AXIS_TYPES)[number];
+declare const YAXIS_POSITIONS: readonly ["left", "right"];
+type YAxisPosition = (typeof YAXIS_POSITIONS)[number];
+declare const COMPARE_RULES: readonly ["current_open", "prev_close"];
+type CompareRule = (typeof COMPARE_RULES)[number];
+declare const TOOLTIP_SHOW_RULES: readonly ["always", "follow_cross", "none"];
+type TooltipShowRule = (typeof TOOLTIP_SHOW_RULES)[number];
+
+interface CandleTypeItem {
+    key: string;
+    localeKey: string;
+}
+interface KlinechartsUISettingsState {
+    candleType: string;
+    candleUpColor: string;
+    candleDownColor: string;
+    compareRule: CompareRule;
+    showLastPrice: boolean;
+    showLastPriceLine: boolean;
+    showHighPrice: boolean;
+    showLowPrice: boolean;
+    showIndicatorLastValue: boolean;
+    priceAxisType: PriceAxisType;
+    yAxisPosition: YAxisPosition;
+    yAxisInside: boolean;
+    reverseCoordinate: boolean;
+    showTimeAxis: boolean;
+    showGrid: boolean;
+    showCrosshair: boolean;
+    showCandleTooltip: boolean;
+    showIndicatorTooltip: boolean;
+    tooltipShowRule: TooltipShowRule;
+}
+interface UseKlinechartsUISettingsReturn extends KlinechartsUISettingsState {
+    candleTypes: CandleTypeItem[];
+    priceAxisTypes: {
+        key: PriceAxisType;
+        localeKey: string;
+    }[];
+    yAxisPositions: {
+        key: YAxisPosition;
+        localeKey: string;
+    }[];
+    compareRules: {
+        key: CompareRule;
+        localeKey: string;
+    }[];
+    tooltipShowRules: {
+        key: TooltipShowRule;
+        localeKey: string;
+    }[];
+    setCandleType: (type: string) => void;
+    setCandleUpColor: (color: string) => void;
+    setCandleDownColor: (color: string) => void;
+    setCompareRule: (rule: CompareRule) => void;
+    setShowLastPrice: (show: boolean) => void;
+    setShowLastPriceLine: (show: boolean) => void;
+    setShowHighPrice: (show: boolean) => void;
+    setShowLowPrice: (show: boolean) => void;
+    setShowIndicatorLastValue: (show: boolean) => void;
+    setPriceAxisType: (type: PriceAxisType) => void;
+    setYAxisPosition: (position: YAxisPosition) => void;
+    setYAxisInside: (inside: boolean) => void;
+    setReverseCoordinate: (reverse: boolean) => void;
+    setShowTimeAxis: (show: boolean) => void;
+    setShowGrid: (show: boolean) => void;
+    setShowCrosshair: (show: boolean) => void;
+    setShowCandleTooltip: (show: boolean) => void;
+    setShowIndicatorTooltip: (show: boolean) => void;
+    setTooltipShowRule: (rule: TooltipShowRule) => void;
+    resetToDefaults: () => void;
+}
+declare function useKlinechartsUISettings(): UseKlinechartsUISettingsReturn;
+
+interface UseScreenshotReturn {
+    screenshotUrl: string | null;
+    capture: () => void;
+    download: (filename?: string) => void;
+    clear: () => void;
+}
+declare function useScreenshot(): UseScreenshotReturn;
+
+interface UseFullscreenReturn {
+    isFullscreen: boolean;
+    toggle: () => void;
+    enter: () => void;
+    exit: () => void;
+    containerRef: React.RefObject<HTMLElement | null>;
+}
+declare function useFullscreen(): UseFullscreenReturn;
+
+interface OrderLineOptions extends OrderLineExtendData {
+    /** Unique identifier. Auto-generated if omitted. */
+    id?: string;
+    /** Price level for the line. */
+    price: number;
+    /** Whether the user can drag the line to change its price. Defaults to false. */
+    draggable?: boolean;
+    /**
+     * Called when the user finishes dragging the line to a new price.
+     * Receives the final price value after the drag ends.
+     */
+    onPriceChange?: (price: number) => void;
+}
+interface UseOrderLinesReturn {
+    /**
+     * Creates an order line overlay at the given price level.
+     * Returns the line id, or null if the chart is not yet ready.
+     */
+    createOrderLine: (options: OrderLineOptions) => string | null;
+    /**
+     * Updates an existing order line.
+     * Supply only the fields you want to change.
+     * Updating onPriceChange replaces the previous callback.
+     */
+    updateOrderLine: (id: string, options: Partial<Omit<OrderLineOptions, "id">>) => void;
+    /** Removes the order line with the given id. */
+    removeOrderLine: (id: string) => void;
+    /** Removes all order lines created with this hook. */
+    removeAllOrderLines: () => void;
+}
+declare function useOrderLines(): UseOrderLinesReturn;
+
+interface TimezoneOption {
+    key: string;
+    localeKey: string;
+}
+declare const TIMEZONES: TimezoneOption[];
+
+interface IndicatorParamConfig {
+    label: string;
+    defaultValue: number;
+}
+interface IndicatorDefinition {
+    name: string;
+    localeKey: string;
+    params: IndicatorParamConfig[];
+}
+declare const MAIN_INDICATORS: string[];
+declare const SUB_INDICATORS: string[];
+declare const INDICATOR_PARAMS: Record<string, IndicatorDefinition>;
+
+/**
+ * Creates a klinecharts DataLoader from a Datafeed instance.
+ * This bridges the react-klinecharts-ui Datafeed interface to the
+ * klinecharts native DataLoader format used by KLineChart component.
+ *
+ * In klinecharts terminology:
+ * - "init" = initial data load
+ * - "forward" = load older data (user scrolled left into history)
+ * - "backward" = load newer data (user scrolled right)
+ */
+declare function createDataLoader(datafeed: Datafeed, dispatch: Dispatch<KlinechartsUIAction>): DataLoader;
+
+declare const arrow: OverlayTemplate;
+
+declare const circle: OverlayTemplate;
+
+declare const rect: OverlayTemplate;
+
+declare const triangle: OverlayTemplate;
+
+declare const parallelogram: OverlayTemplate;
+
+declare const fibonacciCircle: OverlayTemplate;
+
+declare const fibonacciSegment: OverlayTemplate;
+
+declare const fibonacciSpiral: OverlayTemplate;
+
+declare const fibonacciSpeedResistanceFan: OverlayTemplate;
+
+declare const fibonacciExtension: OverlayTemplate;
+
+declare const gannBox: OverlayTemplate;
+
+declare const threeWaves: OverlayTemplate;
+
+declare const fiveWaves: OverlayTemplate;
+
+declare const eightWaves: OverlayTemplate;
+
+declare const anyWaves: 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 };