react-klinecharts-ui 0.6.0 → 1.1.0

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import * as react from 'react';
 import { Dispatch, RefObject, ReactNode, ReactElement } from 'react';
-import { Period, SymbolInfo, KLineData, Chart, DeepPartial, Styles, OverlayTemplate, YAxisOverride, HotkeyTemplate, Hotkey, XAxisOverride, DataLoader, IndicatorTemplate } from 'react-klinecharts';
-export { Hotkey, HotkeyActionParams, HotkeyTemplate, XAxisOverride, YAxisOverride } from 'react-klinecharts';
+import { Period, SymbolInfo, KLineData, Chart, DeepPartial, Styles, OverlayTemplate, YAxisOverride, HotkeyTemplate, Hotkey, XAxisOverride, DataLoader, IndicatorTemplate } from 'klinecharts';
+export { Hotkey, HotkeyActionParams, HotkeyTemplate, XAxisOverride, YAxisOverride } from 'klinecharts';
 import { AlertLineExtendData, OrderLineExtendData } from './extensions.cjs';
 export { DepthOverlayExtendData, DepthOverlayRow, OrderLineFontStyle, OrderLineLabelStyle, OrderLineLineStyle, OrderLineMarkStyle, OrderLinePadding, alertLine, depthOverlay, indicators, orderLine, overlays, registerExtensions } from './extensions.cjs';
 
@@ -22,12 +22,36 @@ declare const DEFAULT_PERIODS: TerminalPeriod[];
  */
 
 type AlertCondition = "crossing_up" | "crossing_down" | "crossing";
+/**
+ * What an alert watches. Defaults to a price level on the main symbol; an
+ * `indicator` target watches a specific figure series value (e.g. RSI
+ * crossing 70, MACD signal crossover).
+ */
+type AlertTarget = {
+    type: "price";
+} | {
+    type: "indicator";
+    /** Indicator id as registered with klinecharts (e.g. `sub_RSI_TV`). */
+    indicatorId: string;
+    /** Figure key whose value is compared (e.g. `rsi`, `macd`, `signal`). */
+    figureKey: string;
+};
 interface Alert {
     id: string;
+    /**
+     * The threshold the target is compared against. For a `price` target this is
+     * a price level; for an `indicator` target it is the indicator value to
+     * cross (e.g. 70 for RSI overbought).
+     */
     price: number;
     condition: AlertCondition;
     message?: string;
     triggered: boolean;
+    /**
+     * What the alert watches. Omit / `"price"` for the classic price-crossing
+     * behaviour; use `"indicator"` for indicator-value crossing.
+     */
+    target?: AlertTarget;
     /**
      * Visual style for the alert line overlay (color, label text, line/mark
      * styling, bell marker). Persisted in the store so it survives undo/redo
@@ -74,6 +98,77 @@ interface ReplayState {
     totalBars: number;
 }
 
+/**
+ * Web Storage-compatible adapter. Pass `localStorage`, `sessionStorage`, a
+ * remote/IndexedDB wrapper, or an in-memory fake.
+ *
+ * Methods are **synchronous** to match the Web Storage API. For async backends
+ * (IndexedDB, fetch-to-server), wrap them in a sync cache that reads from
+ * memory and flushes in the background — the adapter contract is sync.
+ */
+interface StorageAdapter {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+/**
+ * Which slices of the provider store are persisted. Defaults to all three.
+ *
+ * - `"alerts"` — the price-alert list (`state.alerts`, including each alert's
+ *   `triggered` flag and `extendData`).
+ * - `"settings"` — the `useKlinechartsUISettings` object (candle type, colors,
+ *   axes, grid, tooltips, …).
+ * - `"indicators"` — the active main/sub indicator lists, their pane ids,
+ *   custom Y-axis bindings, and visibility overrides.
+ */
+type StorageNamespace = "alerts" | "settings" | "indicators";
+declare const DEFAULT_STORAGE_NAMESPACES: readonly StorageNamespace[];
+/** Default key prefix; namespaced keys become `${prefix}${namespace}`. */
+declare const DEFAULT_STORAGE_KEY_PREFIX = "rkui:";
+/**
+ * Options passed to `<KlinechartsUIProvider storage={...}>`. All fields
+ * optional; omitting `storage` entirely disables persistence (the default —
+ * backward-compatible with pre-1.1.0 behaviour).
+ */
+interface StorageOptions {
+    /**
+     * The adapter instance. Defaults to `localStorage` (SSR-safe: a no-op
+     * adapter when `localStorage` is undefined, e.g. during server rendering).
+     */
+    adapter?: StorageAdapter;
+    /** Key prefix. Default `"rkui:"`. */
+    keyPrefix?: string;
+    /** Which namespaces to persist. Default: all three. */
+    namespaces?: readonly StorageNamespace[];
+}
+/**
+ * Resolved storage configuration (adapter + namespaces + prefix), computed
+ * once on mount and exposed via the dispatch context so hooks/tests can read
+ * and write through the same adapter the provider uses.
+ */
+interface ResolvedStorage {
+    adapter: StorageAdapter;
+    namespaces: ReadonlySet<StorageNamespace>;
+    keyPrefix: string;
+    /** Build the storage key for a namespace: `${keyPrefix}${namespace}`. */
+    key(namespace: StorageNamespace): string;
+    /** Whether a namespace is configured for persistence. */
+    persists(namespace: StorageNamespace): boolean;
+}
+
+/**
+ * Resolve `window.localStorage` lazily and SSR-safely. Never throws; falls
+ * back to `NOOP_ADAPTER` when the global is absent or access is denied (e.g.
+ * cookies disabled in some browsers throw on `localStorage` access).
+ */
+declare function createDefaultStorage(): StorageAdapter;
+/**
+ * Turn raw `StorageOptions` into a `ResolvedStorage` with helpers. Called once
+ * on mount by the provider; the result is referentially stable for the life
+ * of the provider instance.
+ */
+declare function resolveStorage(options: StorageOptions | undefined): ResolvedStorage;
+
 /**
  * Explicit partial symbol type — avoids `PickPartial<SymbolInfo, ...>` which
  * degenerates when SymbolInfo has an index signature `[key: string]: unknown`.
@@ -107,6 +202,17 @@ interface KlinechartsUIOptions {
      * These are registered once, alongside the built-in drawing-tool overlays.
      */
     overlays?: OverlayTemplate[];
+    /**
+     * Optional persistence configuration. When provided, the provider hydrates
+     * the listed namespaces (alerts, settings, indicators) from the adapter on
+     * mount and writes them back on every change. Defaults to `localStorage`
+     * (SSR-safe). Omit entirely to disable persistence (pre-1.1.0 behaviour).
+     *
+     * Note: this covers the reducer store only. Per-hook `useState` values
+     * (script code, compared symbols, watchlist, annotations) are not yet
+     * persisted — see the roadmap.
+     */
+    storage?: StorageOptions;
     children: ReactNode;
     /** Called on every dispatched action with the resulting new state and previous state. */
     onStateChange?: (action: KlinechartsUIAction, nextState: KlinechartsUIState, prevState: KlinechartsUIState) => void;
@@ -206,6 +312,17 @@ type KlinechartsUIAction = {
 } | {
     type: "SET_ALERTS";
     alerts: Alert[];
+} | {
+    type: "ADD_ALERT";
+    alert: Alert;
+} | {
+    type: "REMOVE_ALERT";
+    id: string;
+} | {
+    type: "CLEAR_ALERTS";
+} | {
+    type: "MARK_ALERT_TRIGGERED";
+    ids: string[];
 } | {
     type: "SET_MEASURE";
     measure: Partial<MeasureState>;
@@ -236,10 +353,12 @@ interface KlinechartsUIDispatchValue {
     /** 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).
+     * Listener set registered via `useAlerts.onAlertTriggered`; invoked by the
+     * provider-owned crossing poller when an alert fires. A Set so multiple
+     * components (toolbar, status bar, sound trigger) can all observe firings
+     * without one overwriting the other. `onAlertTriggered` returns an unsubscribe.
      */
-    alertTriggeredListenerRef: RefObject<((alert: Alert) => void) | null>;
+    alertTriggeredListenersRef: RefObject<Set<(alert: Alert) => void>>;
     /**
      * Provider-owned replay resources, shared across every `useReplay` instance
      * so there is exactly one playback timer and one data buffer. The hook reads
@@ -249,13 +368,19 @@ interface KlinechartsUIDispatchValue {
     replayIntervalRef: RefObject<ReturnType<typeof setInterval> | null>;
     replaySavedDataRef: RefObject<KLineData[]>;
     replayIndexRef: RefObject<number>;
+    /**
+     * Resolved persistence configuration, or `null` when the consumer did not
+     * pass the `storage` option (persistence disabled — pre-1.1.0 behaviour).
+     * Hooks and tests read/write through this so they share one adapter.
+     */
+    storage: ResolvedStorage | 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 function KlinechartsUIProvider({ datafeed, defaultSymbol, defaultPeriod, defaultTheme, defaultTimezone, defaultMainIndicators, defaultSubIndicators, defaultLocale, periods, styles, registerExtensions: shouldRegister, overlays: extraOverlays, storage: storageOptions, 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>;
@@ -758,10 +883,18 @@ declare function useCrosshair(): UseCrosshairReturn;
 
 interface UseAlertsReturn {
     alerts: Alert[];
-    addAlert: (price: number, condition: AlertCondition, message?: string, extendData?: AlertLineExtendData) => string;
+    addAlert: (price: number, condition: AlertCondition, message?: string, extendData?: AlertLineExtendData, 
+    /** Alert target: price (default) or an indicator figure value. */
+    target?: AlertTarget) => string;
     removeAlert: (id: string) => void;
     clearAlerts: () => void;
-    onAlertTriggered: (callback: (alert: Alert) => void) => void;
+    /**
+     * Register a callback fired when any alert crosses its target. Returns an
+     * unsubscribe function. Multiple components can register simultaneously —
+     * every registered listener is invoked on each firing (no longer
+     * last-writer-wins).
+     */
+    onAlertTriggered: (callback: (alert: Alert) => void) => () => void;
 }
 /**
  * Headless hook for price-crossing alerts.
@@ -1008,6 +1141,110 @@ declare const TA: {
     hma: (data: number[], period: number) => (number | null)[];
 };
 
+/** One chart cell in a workspace grid. */
+interface ChartCell {
+    /** Stable cell id (used as React key + workspace registry key). */
+    id: string;
+    symbol: PartialSymbolInfo;
+    period: TerminalPeriod;
+}
+/** Top-level workspace state. */
+interface WorkspaceState {
+    /** The chart cells that make up the layout grid. */
+    cells: ChartCell[];
+    /** Currently focused cell (drives keyboard shortcuts etc.). */
+    activeCellId: string | null;
+}
+type WorkspaceAction = {
+    type: "SET_CELLS";
+    cells: ChartCell[];
+} | {
+    type: "ADD_CELL";
+    cell: ChartCell;
+} | {
+    type: "REMOVE_CELL";
+    id: string;
+} | {
+    type: "SET_CELL_SYMBOL";
+    id: string;
+    symbol: PartialSymbolInfo;
+} | {
+    type: "SET_CELL_PERIOD";
+    id: string;
+    period: TerminalPeriod;
+} | {
+    type: "SET_ACTIVE_CELL";
+    id: string | null;
+};
+/** Channels that can be mirrored between charts in the workspace. */
+type SyncChannel = "crosshair" | "scroll" | "zoom" | "symbol" | "period";
+/** Default: every channel mirrored (fully-linked workspace). */
+declare const DEFAULT_SYNC_CONFIG: Record<SyncChannel, boolean>;
+/** Per-channel enable/disable for chart mirroring. */
+type SyncConfig = Partial<Record<SyncChannel, boolean>>;
+/**
+ * The workspace context value. Exposes the reducer state, the dispatch, and a
+ * chart-instance registry that `useChartSync` populates and the sync logic
+ * iterates over. The registry is intentionally a mutable ref (Map) — chart
+ * instances come and go as cells mount/unmount and we don't want a state bump
+ * on every registration.
+ */
+interface WorkspaceContextValue {
+    state: WorkspaceState;
+    dispatch: Dispatch<WorkspaceAction>;
+    /** cellId → Chart instance registry. */
+    chartsRef: {
+        current: Map<string, Chart>;
+    };
+    /** Re-entrancy guard so mirroring doesn't feedback-loop. */
+    broadcastingRef: {
+        current: boolean;
+    };
+    /** Resolved sync config (defaults merged in). */
+    sync: Record<SyncChannel, boolean>;
+}
+
+interface WorkspaceProviderProps {
+    /** Initial chart cells for the grid. */
+    defaultCells: ChartCell[];
+    /** Per-channel sync enable/disable. Defaults to all channels on. */
+    sync?: SyncConfig;
+    children: ReactNode;
+}
+/**
+ * Coordinator above a grid of `<KlinechartsUIProvider>` trees. Holds the
+ * workspace layout state (cells, active cell), a chart-instance registry that
+ * `useChartSync` populates, and the sync configuration. Charts stay isolated
+ * per provider — alerts/replay/drawings are per-cell in this foundation.
+ */
+declare function WorkspaceProvider({ defaultCells, sync, children, }: WorkspaceProviderProps): ReactNode;
+
+/**
+ * Read the workspace context. Throws if used outside a `<WorkspaceProvider>`.
+ */
+declare function useWorkspace(): WorkspaceContextValue;
+
+interface UseChartSyncOptions {
+    /** This cell's id; must match a cell in the workspace state. */
+    cellId: string;
+}
+/**
+ * Bridge hook: call this inside a `<KlinechartsUIProvider>` (typically via a
+ * `<ChartSyncBridge cellId={...} />` component). It registers the provider's
+ * chart with the workspace registry and mirrors viewport/crosshair/zoom events
+ * to the other registered charts, and keeps the workspace's notion of this
+ * cell's symbol/period up to date.
+ *
+ * Mirroring uses only the PUBLIC klinecharts API (`executeAction`,
+ * `scrollToTimestamp`, `setBarSpace`), not internal `_chartStore` fields, so it
+ * survives klinecharts version upgrades. A re-entrancy guard
+ * (`broadcastingRef`) prevents feedback loops.
+ *
+ * Limitations: klinecharts has no `setVisibleRange`, so scroll sync aligns the
+ * right edge via `scrollToTimestamp(realTo)` — close but not pixel-exact.
+ */
+declare function useChartSync({ cellId }: UseChartSyncOptions): void;
+
 declare const arrow: OverlayTemplate;
 
 declare const circle: OverlayTemplate;
@@ -1086,4 +1323,4 @@ declare const superTrend: IndicatorTemplate;
 
 declare const vwap: IndicatorTemplate;
 
-export { type AddIndicatorOptions, type Alert, type AlertCondition, AlertLineExtendData, 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 UseChartAxesReturn, type UseCompareReturn, type UseCrosshairReturn, type UseDataExportReturn, type UseDrawingToolsReturn, type UseFullscreenReturn, type UseHotkeysReturn, 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, useChartAxes, useCompare, useCrosshair, useDataExport, useDrawingTools, useFullscreen, useHotkeys, 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, AlertLineExtendData, type AlertTarget, type Annotation, CANDLE_TYPES, COMPARE_RULES, type CandleTypeItem, type CandleTypeOption, type ChartCell, type ChartLayoutState, type CompareRule, type CompareSymbol, type CrosshairBarData, DEFAULT_PERIODS, DEFAULT_STORAGE_KEY_PREFIX, DEFAULT_STORAGE_NAMESPACES, DEFAULT_SYNC_CONFIG, 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, type ResolvedStorage, SUB_INDICATORS, type ScriptPlacement, type StorageAdapter, type StorageNamespace, type StorageOptions, type SyncChannel, type SyncConfig, TA, TIMEZONES, TOOLTIP_SHOW_RULES, type TerminalPeriod, type TimezoneItem, type TimezoneOption, type TooltipShowRule, type UndoRedoAction, type UndoRedoActionType, type UseAlertsReturn, type UseAnnotationsReturn, type UseChartAxesReturn, type UseChartSyncOptions, type UseCompareReturn, type UseCrosshairReturn, type UseDataExportReturn, type UseDrawingToolsReturn, type UseFullscreenReturn, type UseHotkeysReturn, 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, type WorkspaceAction, type WorkspaceContextValue, WorkspaceProvider, type WorkspaceProviderProps, type WorkspaceState, YAXIS_POSITIONS, type YAxisPosition, abcd, anyWaves, arrow, bollTv, brush, cci, circle, createDataLoader, createDefaultStorage, eightWaves, elliottWave, fibRetracement, fibonacciCircle, fibonacciExtension, fibonacciSegment, fibonacciSpeedResistanceFan, fibonacciSpiral, fiveWaves, gannBox, gannFan, hma, ichimoku, longPosition, maRibbon, macdTv, measure, parallelChannel, parallelogram, pivotPoints, ray, rect, resolveStorage, rsiTv, shortPosition, stochastic, superTrend, threeWaves, triangle, useAlerts, useAnnotations, useChartAxes, useChartSync, useCompare, useCrosshair, useDataExport, useDrawingTools, useFullscreen, useHotkeys, useIndicators, useKlinechartsUI, useKlinechartsUILoading, useKlinechartsUISettings, useKlinechartsUITheme, useLayoutManager, useMeasure, useOrderLines, usePeriods, useReplay, useScreenshot, useScriptEditor, useSymbolSearch, useTimezone, useUndoRedo, useWatchlist, useWorkspace, vwap, xabcd };