react-klinecharts-ui 0.3.0 → 0.5.0

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 import * as react from 'react';
 import { Dispatch, RefObject, ReactNode, ReactElement } from 'react';
-import { Period, SymbolInfo, KLineData, Chart, DeepPartial, Styles, OverlayTemplate, DataLoader, IndicatorTemplate } from 'react-klinecharts';
+import { Period, SymbolInfo, KLineData, Chart, DeepPartial, Styles, OverlayTemplate, YAxisOverride, DataLoader, IndicatorTemplate } from 'react-klinecharts';
 import { OrderLineExtendData } from './extensions.cjs';
 export { DepthOverlayExtendData, DepthOverlayRow, OrderLineFontStyle, OrderLineLabelStyle, OrderLineLineStyle, OrderLineMarkStyle, OrderLinePadding, depthOverlay, indicators, orderLine, overlays, registerExtensions } from './extensions.cjs';
 
@@ -9,6 +9,63 @@ interface TerminalPeriod extends Period {
 }
 declare const DEFAULT_PERIODS: TerminalPeriod[];
 
+/**
+ * Shared domain types for stateful feature hooks (`useAlerts`, `useMeasure`,
+ * `useReplay`).
+ *
+ * These live in a neutral module so they can be referenced both by the
+ * provider store (`KlinechartsUIState` / actions in `./types`) and by the
+ * hooks, without creating a circular import between the two. The hooks
+ * re-export them so the public API surface (consumed via the package root)
+ * stays unchanged.
+ */
+type AlertCondition = "crossing_up" | "crossing_down" | "crossing";
+interface Alert {
+    id: string;
+    price: number;
+    condition: AlertCondition;
+    message?: string;
+    triggered: boolean;
+}
+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 MeasureState {
+    /** Whether measure mode is active (waiting for clicks) */
+    isActive: boolean;
+    /** First point (set after first click) */
+    fromPoint: MeasurePoint | null;
+    /** Current measurement result (null until both points are set) */
+    result: MeasureResult | null;
+}
+type ReplaySpeed = 1 | 2 | 5 | 10;
+interface ReplayState {
+    /** 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;
+}
+
 /**
  * Explicit partial symbol type — avoids `PickPartial<SymbolInfo, ...>` which
  * degenerates when SymbolInfo has an index signature `[key: string]: unknown`.
@@ -65,6 +122,46 @@ interface KlinechartsUIState {
     periods: TerminalPeriod[];
     mainIndicators: string[];
     subIndicators: Record<string, string>;
+    /**
+     * Custom Y-axis bindings for indicators, keyed by indicator id
+     * (`main_<name>` / `sub_<name>`), value is the bound `yAxisId`.
+     * Only populated for indicators explicitly bound to a secondary
+     * (non-default) axis via `useIndicators`. Indicators on the shared
+     * default axis are absent. Used to persist bindings across
+     * undo/redo and layout presets.
+     */
+    indicatorAxes: Record<string, string>;
+    /**
+     * Visibility overrides for indicators, keyed by indicator id
+     * (`main_<name>` / `sub_<name>`), value is whether the indicator is shown.
+     * Mirrors the `visible` flag held inside klinecharts so `useIndicators` can
+     * expose a reactive getter (the chart instance has no React-friendly read
+     * path). Only populated for indicators whose visibility has been toggled
+     * away from the default; an absent key means visible (`true`). Updated by
+     * `setIndicatorVisible` and the collapse/expand helpers, and rebuilt when a
+     * layout preset is restored so the mirror never drifts from the chart.
+     */
+    indicatorVisibility: Record<string, boolean>;
+    /**
+     * Price alerts (`useAlerts`). Lives in the shared store rather than per-hook
+     * local state so every consumer (toolbar, list panel, status bar, sound
+     * trigger) observes one synchronized list. The crossing poller and the
+     * `onAlertTriggered` listener are owned by the provider, not the hook.
+     */
+    alerts: Alert[];
+    /**
+     * Measure-tool state (`useMeasure`). Shared so the toolbar toggle and the
+     * result readout panel stay in sync regardless of where each is mounted.
+     */
+    measure: MeasureState;
+    /**
+     * Historical-replay control state (`useReplay`). Shared so play/pause/step
+     * controls in different components drive one session. The playback interval
+     * and data buffers are owned by the provider (see the `replay*Ref` fields on
+     * the dispatch value), guaranteeing a single timer no matter how many hook
+     * instances are mounted.
+     */
+    replay: ReplayState;
     styles: DeepPartial<Styles> | undefined;
     screenshotUrl: string | null;
 }
@@ -92,6 +189,21 @@ type KlinechartsUIAction = {
 } | {
     type: "SET_SUB_INDICATORS";
     indicators: Record<string, string>;
+} | {
+    type: "SET_INDICATOR_AXES";
+    axes: Record<string, string>;
+} | {
+    type: "SET_INDICATOR_VISIBILITY";
+    visibility: Record<string, boolean>;
+} | {
+    type: "SET_ALERTS";
+    alerts: Alert[];
+} | {
+    type: "SET_MEASURE";
+    measure: Partial<MeasureState>;
+} | {
+    type: "SET_REPLAY";
+    replay: Partial<ReplayState>;
 } | {
     type: "SET_STYLES";
     styles: DeepPartial<Styles> | undefined;
@@ -115,6 +227,20 @@ interface KlinechartsUIDispatchValue {
     fullscreenContainerRef: RefObject<HTMLElement | null>;
     /** Ref populated by useUndoRedo; other hooks call it to record actions. */
     undoRedoListenerRef: RefObject<UndoRedoListener | null>;
+    /**
+     * Listener set by `useAlerts.onAlertTriggered`; invoked by the provider-owned
+     * crossing poller when an alert fires. Last writer wins (one active listener).
+     */
+    alertTriggeredListenerRef: RefObject<((alert: Alert) => void) | null>;
+    /**
+     * Provider-owned replay resources, shared across every `useReplay` instance
+     * so there is exactly one playback timer and one data buffer. The hook reads
+     * and writes these instead of its own refs; the provider clears the interval
+     * on unmount.
+     */
+    replayIntervalRef: RefObject<ReturnType<typeof setInterval> | null>;
+    replaySavedDataRef: RefObject<KLineData[]>;
+    replayIndexRef: RefObject<number>;
 }
 /** Combined context value returned by `useKlinechartsUI()`. */
 interface KlinechartsUIContextValue extends KlinechartsUIDispatchValue {
@@ -175,6 +301,23 @@ declare function useSymbolSearch(debounceMs?: number): UseSymbolSearchReturn;
 interface IndicatorInfo {
     name: string;
     isActive: boolean;
+    /**
+     * Whether the indicator is currently visible on the chart. Defaults to
+     * `true`; only `false` after the indicator has been hidden via
+     * `setIndicatorVisible` or `collapseSubIndicator`. Meaningful only when
+     * `isActive` is `true` (inactive indicators are always reported `true`).
+     */
+    visible: boolean;
+}
+/** Options accepted when adding an indicator. */
+interface AddIndicatorOptions {
+    /**
+     * Bind the indicator to a custom Y-axis (klinecharts v10 multiple y-axes).
+     * Provide a stable `id` to create/share a secondary axis; e.g.
+     * `{ id: "rsi_axis", position: "left" }`. Omit to use the pane's default
+     * (shared) axis.
+     */
+    yAxis?: YAxisOverride;
 }
 interface UseIndicatorsReturn {
     mainIndicators: IndicatorInfo[];
@@ -183,15 +326,22 @@ interface UseIndicatorsReturn {
     activeSubIndicators: Record<string, string>;
     availableMainIndicators: string[];
     availableSubIndicators: string[];
-    addMainIndicator: (name: string) => void;
+    addMainIndicator: (name: string, options?: AddIndicatorOptions) => void;
     removeMainIndicator: (name: string) => void;
-    addSubIndicator: (name: string) => void;
+    addSubIndicator: (name: string, options?: AddIndicatorOptions) => 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;
+    /**
+     * Read whether an indicator is currently visible. Returns `true` for the
+     * default (un-toggled) state and for inactive indicators. This is the
+     * reactive read counterpart to `setIndicatorVisible` — UI no longer needs to
+     * track visibility locally or reach into the chart instance.
+     */
+    isIndicatorVisible: (name: string, isMain: boolean) => boolean;
     updateIndicatorParams: (name: string, paneId: string, params: number[]) => void;
     getIndicatorParams: (name: string) => {
         label: string;
@@ -207,6 +357,28 @@ interface UseIndicatorsReturn {
     isSubIndicatorCollapsed: (name: string) => boolean;
     /** Reorder a sub-indicator pane up or down relative to other sub-indicators. */
     reorderSubIndicator: (name: string, direction: "up" | "down") => void;
+    /**
+     * Custom Y-axis bindings, keyed by indicator id (`main_<name>` /
+     * `sub_<name>`). Only contains indicators bound to a secondary axis.
+     */
+    indicatorAxes: Record<string, string>;
+    /** Get the custom `yAxisId` an indicator is bound to, or `undefined` for the default axis. */
+    getIndicatorAxis: (name: string, isMain: boolean) => string | undefined;
+    /**
+     * Visibility overrides keyed by indicator id (`main_<name>` / `sub_<name>`).
+     * Only contains indicators hidden away from the default; an absent key means
+     * visible. Mirror of the provider state, exposed for layout-preset
+     * persistence and direct rendering.
+     */
+    indicatorVisibility: Record<string, boolean>;
+    /**
+     * Rebind an existing indicator to a different Y-axis. Because klinecharts v10
+     * `overrideIndicator` cannot change axis binding, this removes and recreates
+     * the indicator (preserving calc params, styles and visibility).
+     * Pass `yAxis` to bind to a secondary axis, or omit it to return the
+     * indicator to the pane's default (shared) axis.
+     */
+    bindIndicatorToNewAxis: (name: string, isMain: boolean, yAxis?: YAxisOverride) => void;
 }
 declare function useIndicators(): UseIndicatorsReturn;
 
@@ -418,6 +590,8 @@ interface ChartLayoutState {
         calcParams: any[];
         visible: boolean;
         styles?: any;
+        /** Custom Y-axis the indicator is bound to (klinecharts v10 multiple y-axes). */
+        yAxisId?: string;
     }>;
     drawings: Array<{
         name: string;
@@ -522,14 +696,6 @@ interface UseCrosshairReturn {
 }
 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;
@@ -537,6 +703,15 @@ interface UseAlertsReturn {
     clearAlerts: () => void;
     onAlertTriggered: (callback: (alert: Alert) => void) => void;
 }
+/**
+ * Headless hook for price-crossing alerts.
+ *
+ * The alert list lives in the shared provider store, and the 1s crossing
+ * poller + the `onAlertTriggered` listener are owned by the provider. This
+ * means several `useAlerts()` instances (toolbar, list panel, sound trigger)
+ * observe and mutate one synchronized list and share a single poller — they no
+ * longer drift apart or each spawn their own interval.
+ */
 declare function useAlerts(): UseAlertsReturn;
 
 type ExportFormat = "csv" | "json";
@@ -563,7 +738,6 @@ interface UseWatchlistReturn {
 }
 declare function useWatchlist(): UseWatchlistReturn;
 
-type ReplaySpeed = 1 | 2 | 5 | 10;
 interface UseReplayReturn {
     /** Whether a replay session is active */
     isReplaying: boolean;
@@ -594,8 +768,13 @@ interface UseReplayReturn {
  * 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.
+ * bars back one at a time at the configured speed.
+ *
+ * Replay control state lives in the shared provider store and the playback
+ * interval + data buffers are owned by the provider (accessed through stable
+ * refs). This guarantees a single playback session even when `useReplay()` is
+ * mounted in several components (e.g. toolbar + bottom controls + status bar):
+ * starting in one and stepping in another drives the same timer and buffer.
  */
 declare function useReplay(): UseReplayReturn;
 
@@ -627,23 +806,6 @@ interface UseCompareReturn {
  */
 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;
@@ -662,7 +824,10 @@ interface UseMeasureReturn {
  * 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.
+ * interaction, then computes price diff, %, bar count, and time diff. The
+ * measure state (active/from/result) lives in the shared provider store, so a
+ * toolbar toggle and a separate result-readout panel stay in sync no matter
+ * where each is mounted.
  */
 declare function useMeasure(): UseMeasureReturn;
 
@@ -861,4 +1026,4 @@ 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 };
+export { type AddIndicatorOptions, 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 };