react-klinecharts-ui 0.4.0 → 0.5.0

package/dist/index.d.cts

@@ -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`.
@@ -74,6 +131,37 @@ interface KlinechartsUIState {
      * 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;
 }
@@ -104,6 +192,18 @@ type KlinechartsUIAction = {
 } | {
     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;
@@ -127,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 {
@@ -187,6 +301,13 @@ 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 {
@@ -214,6 +335,13 @@ interface UseIndicatorsReturn {
     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;
@@ -236,6 +364,13 @@ interface UseIndicatorsReturn {
     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
@@ -561,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;
@@ -576,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";
@@ -602,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;
@@ -633,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;
 
@@ -666,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;
@@ -701,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;
 

package/dist/index.d.ts

@@ -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`.
@@ -74,6 +131,37 @@ interface KlinechartsUIState {
      * 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;
 }
@@ -104,6 +192,18 @@ type KlinechartsUIAction = {
 } | {
     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;
@@ -127,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 {
@@ -187,6 +301,13 @@ 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 {
@@ -214,6 +335,13 @@ interface UseIndicatorsReturn {
     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;
@@ -236,6 +364,13 @@ interface UseIndicatorsReturn {
     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
@@ -561,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;
@@ -576,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";
@@ -602,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;
@@ -633,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;
 
@@ -666,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;
@@ -701,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;