react-klinecharts-ui 0.3.0 → 0.5.0

package/README.md

@@ -41,6 +41,9 @@ Many features in this library — including 11 TradingView-style indicators, 9 d
    - [useMeasure](#usemeasure)
    - [useAnnotations](#useannotations)
    - [useReplay](#usereplay)
+   - [useAlerts](#usealerts)
+   - [useCrosshair](#usecrosshair)
+   - [useDataExport](#usedataexport)
 6. [Utilities](#utilities)
    - [createDataLoader](#createdataloader)
    - [TA (Technical Analysis)](#ta-technical-analysis)
@@ -49,7 +52,8 @@ Many features in this library — including 11 TradingView-style indicators, 9 d
 9. [Drawing Overlays](#drawing-overlays)
 10. [Extensions](#extensions)
 11. [State Callbacks](#state-callbacks)
-12. [Full Export List](#full-export-list)
+12. [Backend Signals & Notifications](#backend-signals--notifications)
+13. [Full Export List](#full-export-list)
 
 ---
 
@@ -206,6 +210,11 @@ interface KlinechartsUIState {
   periods: TerminalPeriod[]; // List of available timeframes
   mainIndicators: string[]; // Active main chart indicators
   subIndicators: Record<string, string>; // Active sub-indicators: { name → paneId }
+  indicatorAxes: Record<string, string>; // Custom Y-axis bindings: { indicatorId → yAxisId }
+  indicatorVisibility: Record<string, boolean>; // Visibility overrides: { indicatorId → false } (sparse)
+  alerts: Alert[]; // Price alerts (useAlerts) — shared across all consumers
+  measure: MeasureState; // Measure-tool state (useMeasure): { isActive, fromPoint, result }
+  replay: ReplayState; // Replay control state (useReplay): { isReplaying, isPaused, speed, barIndex, totalBars }
   styles: DeepPartial<Styles> | undefined; // Custom klinecharts styles
   screenshotUrl: string | null; // URL of the last screenshot
 }
@@ -225,6 +234,11 @@ type KlinechartsUIAction =
   | { type: "SET_LOADING"; isLoading: boolean }
   | { type: "SET_MAIN_INDICATORS"; indicators: string[] }
   | { 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 }
   | { type: "SET_LOCALE"; locale: string }
   | { type: "SET_SCREENSHOT_URL"; url: string | null };
@@ -455,10 +469,15 @@ const {
   moveToMain,
   moveToSub,
   setIndicatorVisible,
+  isIndicatorVisible,
   updateIndicatorParams,
   getIndicatorParams,
   isMainIndicatorActive,
   isSubIndicatorActive,
+  indicatorAxes,
+  getIndicatorAxis,
+  indicatorVisibility,
+  bindIndicatorToNewAxis,
 } = useIndicators();
 ```
 
@@ -466,17 +485,20 @@ const {
 
 | Field                     | Type                     | Description                                |
 | ------------------------- | ------------------------ | ------------------------------------------ |
-| `mainIndicators`          | `IndicatorInfo[]`        | All main indicators with `isActive` flag   |
-| `subIndicators`           | `IndicatorInfo[]`        | All sub-indicators with `isActive` flag    |
+| `mainIndicators`          | `IndicatorInfo[]`        | All main indicators with `isActive` + `visible` flags |
+| `subIndicators`           | `IndicatorInfo[]`        | All sub-indicators with `isActive` + `visible` flags  |
 | `activeMainIndicators`    | `string[]`               | Active main indicator names only           |
 | `activeSubIndicators`     | `Record<string, string>` | Active sub-indicators: `{ name → paneId }` |
 | `availableMainIndicators` | `string[]`               | Full list from `MAIN_INDICATORS`           |
 | `availableSubIndicators`  | `string[]`               | Full list from `SUB_INDICATORS`            |
+| `indicatorAxes`           | `Record<string, string>` | Custom Y-axis bindings: `{ indicatorId → yAxisId }` |
+| `indicatorVisibility`     | `Record<string, boolean>`| Visibility overrides: `{ indicatorId → false }` (sparse — only hidden indicators; absent means visible) |
 
 ```typescript
 interface IndicatorInfo {
   name: string; // "MA", "MACD", "RSI", etc.
   isActive: boolean; // Whether it is currently on the chart
+  visible: boolean; // Whether it is currently shown (vs hidden); true when inactive
 }
 ```
 
@@ -484,19 +506,46 @@ interface IndicatorInfo {
 
 | Method                                        | Description                                                   |
 | --------------------------------------------- | ------------------------------------------------------------- |
-| `addMainIndicator(name)`                      | Creates the indicator on `candle_pane` with id `main_${name}` |
+| `addMainIndicator(name, options?)`            | Creates the indicator on `candle_pane` with id `main_${name}`. Pass `{ yAxis }` to bind it to a secondary axis (see below) |
 | `removeMainIndicator(name)`                   | Removes the indicator and updates state                       |
-| `addSubIndicator(name)`                       | Creates the indicator on a new sub-pane with id `sub_${name}` |
+| `addSubIndicator(name, options?)`             | Creates the indicator on a new sub-pane with id `sub_${name}`. Also accepts `{ yAxis }` |
 | `removeSubIndicator(name)`                    | Removes the sub-indicator and its pane                        |
 | `toggleMainIndicator(name)`                   | `add` if inactive, `remove` if active                         |
 | `toggleSubIndicator(name)`                    | Same for sub-indicators                                       |
 | `moveToMain(name)`                            | Moves from sub-pane to `candle_pane`                          |
 | `moveToSub(name)`                             | Moves from `candle_pane` to a new sub-pane                    |
-| `setIndicatorVisible(name, isMain, visible)`  | Show/hide indicator via `chart.overrideIndicator`             |
+| `setIndicatorVisible(name, isMain, visible)`  | Show/hide indicator via `chart.overrideIndicator`; mirrors the flag into `indicatorVisibility` |
+| `isIndicatorVisible(name, isMain)`            | Reactive read counterpart to `setIndicatorVisible`; returns `true` for the default/inactive state |
 | `updateIndicatorParams(name, paneId, params)` | Update `calcParams` via `chart.overrideIndicator`             |
 | `getIndicatorParams(name)`                    | Returns `[{ label, defaultValue }]` or `[]` if no parameters  |
 | `isMainIndicatorActive(name)`                 | Quick active check                                            |
 | `isSubIndicatorActive(name)`                  | Quick active check                                            |
+| `getIndicatorAxis(name, isMain)`              | Returns the custom `yAxisId` an indicator is bound to, or `undefined` for the default axis |
+| `bindIndicatorToNewAxis(name, isMain, yAxis?)`| Rebinds an existing indicator to a different Y-axis (omit `yAxis` to return it to the default axis) |
+
+#### Secondary Y-axis binding (multiple Y-axes)
+
+klinecharts v10 supports several independent Y-axes on one pane, so an indicator whose value range differs sharply from price (RSI 0–100, volume, …) can get its own scale instead of distorting the shared price axis or being forced into a separate sub-pane.
+
+```typescript
+// Add RSI on the main pane, on its own left axis (price scale stays intact)
+addMainIndicator("RSI", { yAxis: { id: "rsi_axis", position: "left" } });
+
+// Later: move it back to the shared price axis
+bindIndicatorToNewAxis("RSI", true);
+
+// Or move an indicator already on the chart onto a dedicated right axis
+bindIndicatorToNewAxis("VOL", true, { id: "vol_axis", position: "right" });
+```
+
+`yAxis` is a klinecharts `YAxisOverride`; the key field is **`id`** — indicators sharing the same `id` share one axis. Useful extras: `position` (`"left" | "right"`), `name` (scale type: `"normal" | "percentage" | "log"`), `inside`, and `needWidget` (set `false` for an invisible axis — own scale, no labels).
+
+This binding is a **persistent property, not a one-shot action**. It is tracked in provider state (`indicatorAxes`, keyed by indicator id) and preserved across:
+
+- **undo/redo** — toggling an indicator off and back on (`useUndoRedo`) restores it on the same axis, not the price axis;
+- **layout presets** — `useLayoutManager` save/load reproduces each indicator's axis 1:1.
+
+> Note: `bindIndicatorToNewAxis` removes and recreates the indicator (v10 `overrideIndicator` cannot rebind an axis), preserving calc params, styles and visibility. The rebind action itself is not pushed onto the undo stack.
 
 #### Available indicators
 
@@ -991,6 +1040,8 @@ const {
 
 Measure price changes, percentage swings, bar count, and time intervals between two points on the chart.
 
+> **Multi-instance safe.** State lives in the shared provider store (`state.measure`), so calling `useMeasure()` in several components (e.g. a toolbar toggle and a separate result panel) keeps them in sync — no need to hoist a single instance.
+
 ```typescript
 import { useMeasure } from "react-klinecharts-ui";
 
@@ -1064,6 +1115,8 @@ const {
 
 Replay historical candles at various speeds with play/pause/step controls and progress tracking.
 
+> **Multi-instance safe.** Control state lives in the shared store (`state.replay`) and the playback timer + data buffers are owned by the provider, so there is exactly one replay session no matter how many `useReplay()` instances are mounted — start in one component and step in another, and they drive the same session.
+
 ```typescript
 import { useReplay } from "react-klinecharts-ui";
 
@@ -1096,6 +1149,128 @@ const {
 
 ---
 
+### useAlerts
+
+Client-side price alerts. Draws a locked horizontal line on the chart for each alert and polls the latest candle once per second, firing a callback when the close price crosses the alert level. This is the primary hook for reacting to price events — e.g. forwarding a buy/sell signal to your backend or triggering a push notification (see [Backend Signals & Notifications](#backend-signals--notifications)).
+
+> **Multi-instance safe.** The alert list lives in the shared store (`state.alerts`) and the crossing poller is owned by the provider (one poller, active only while alerts exist), so multiple `useAlerts()` instances share one list. Note: `onAlertTriggered` registers a **single** listener — the last registration wins.
+
+```typescript
+import { useAlerts } from "react-klinecharts-ui";
+
+const {
+  alerts,
+  addAlert,
+  removeAlert,
+  clearAlerts,
+  onAlertTriggered,
+} = useAlerts();
+
+const id = addAlert(65000, "crossing_up", "BTC broke 65k");
+
+onAlertTriggered((alert) => {
+  console.log("Alert fired:", alert.message, alert.price);
+});
+```
+
+#### Return type: `UseAlertsReturn`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `alerts` | `Alert[]` | Current alerts (active and triggered) |
+| `addAlert` | `(price: number, condition: AlertCondition, message?: string) => string` | Create an alert at a price level; returns its id |
+| `removeAlert` | `(id: string) => void` | Remove a single alert and its chart line |
+| `clearAlerts` | `() => void` | Remove all alerts |
+| `onAlertTriggered` | `(callback: (alert: Alert) => void) => void` | Register a callback fired once when an alert's condition is met |
+
+#### Types
+
+```typescript
+type AlertCondition = "crossing_up" | "crossing_down" | "crossing";
+
+interface Alert {
+  id: string;
+  price: number;
+  condition: AlertCondition;
+  message?: string;
+  triggered: boolean;
+}
+```
+
+| Condition | Fires when |
+|-----------|------------|
+| `crossing_up` | Previous close `<` price **and** current close `>=` price |
+| `crossing_down` | Previous close `>` price **and** current close `<=` price |
+| `crossing` | Either direction |
+
+> Detection is based on the **latest candle's close**, polled every second from `chart.getDataList()`. An alert fires at most once (its `triggered` flag flips to `true`); recreate it to re-arm.
+
+---
+
+### useCrosshair
+
+Tracks the OHLCV data of the bar currently under the crosshair. Returns `null` when the cursor is off-chart. Updates are throttled with `requestAnimationFrame`, making it suitable for driving a live data panel / legend that follows the cursor.
+
+```typescript
+import { useCrosshair } from "react-klinecharts-ui";
+
+const { barData } = useCrosshair();
+
+// barData is null until the cursor is over a candle
+if (barData) {
+  console.log(barData.close, barData.changePercent);
+}
+```
+
+#### Return type: `UseCrosshairReturn`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `barData` | `CrosshairBarData \| null` | OHLCV of the hovered bar, or `null` when off-chart |
+
+#### CrosshairBarData
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `open` | `number` | Open price |
+| `high` | `number` | High price |
+| `low` | `number` | Low price |
+| `close` | `number` | Close price |
+| `volume` | `number` | Volume |
+| `timestamp` | `number` | Bar timestamp (ms) |
+| `change` | `number` | `close - open`, rounded to the symbol's price precision |
+| `changePercent` | `number` | Percent change relative to open, 2 decimals |
+
+---
+
+### useDataExport
+
+Export chart candle data to a downloaded file in CSV or JSON format. Columns: `Date` (ISO), `Open`, `High`, `Low`, `Close`, `Volume`. The file is named `<ticker>_<YYYY-MM-DD>.<format>`.
+
+```typescript
+import { useDataExport } from "react-klinecharts-ui";
+
+const { exportAll, exportVisible } = useDataExport();
+
+exportAll("csv");      // every loaded bar
+exportVisible("json"); // only the currently visible range
+```
+
+#### Return type: `UseDataExportReturn`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `exportAll` | `(format: ExportFormat) => void` | Download all loaded candles |
+| `exportVisible` | `(format: ExportFormat) => void` | Download only the visible range (falls back to all bars if the range is unavailable) |
+
+```typescript
+type ExportFormat = "csv" | "json";
+```
+
+> No-op when the chart is not ready or holds no data.
+
+---
+
 ## Utilities
 
 ### createDataLoader
@@ -1240,6 +1415,29 @@ const PRICE_AXIS_TYPES = ["normal", "percentage", "log"] as const;
 type PriceAxisType = "normal" | "percentage" | "log";
 ```
 
+### YAXIS_POSITIONS
+
+```typescript
+const YAXIS_POSITIONS = ["left", "right"] as const;
+type YAxisPosition = "left" | "right";
+```
+
+### COMPARE_RULES
+
+Baseline rule used when overlaying compared symbols (see [useCompare](#usecompare)).
+
+```typescript
+const COMPARE_RULES = ["current_open", "prev_close"] as const;
+type CompareRule = "current_open" | "prev_close";
+```
+
+### TOOLTIP_SHOW_RULES
+
+```typescript
+const TOOLTIP_SHOW_RULES = ["always", "follow_cross", "none"] as const;
+type TooltipShowRule = "always" | "follow_cross" | "none";
+```
+
 ---
 
 ## Custom Indicator Templates
@@ -1508,6 +1706,97 @@ const savedTheme = localStorage.getItem('theme') ?? 'dark';
 
 ---
 
+## Backend Signals & Notifications
+
+A common question: **how do front-end indicators connect to a backend for buy/sell signals or push notifications?**
+
+This library is **headless by design** — it owns chart state, datafeed wiring, and overlay management, but it deliberately does **not** generate trading signals, execute orders, or send notifications. Those belong to your application/backend layer. What the library provides is the full set of extension points to connect the two. Backend-driven signals are **not** a built-in feature and are not planned as one, because they fall outside the headless UI scope.
+
+There are two directions to wire up.
+
+### Backend → chart (display server signals)
+
+Push signals computed on your backend into the chart through the `Datafeed` and overlay hooks:
+
+- **`Datafeed.subscribe`** — your real-time channel (WebSocket/SSE). Stream live candles, and alongside them any backend-computed signal payloads.
+- **[`useOrderLines`](#useorderlines)** — render entry/SL/TP levels as draggable horizontal lines; `onPriceChange` reports the new price when a user drags one.
+- **[`useAnnotations`](#useannotations)** — drop markers/notes on the chart at the bars where signals fired.
+
+```tsx
+// A WebSocket carrying both candles and backend signals
+const datafeed: Datafeed = {
+  // ...searchSymbols / getHistoryKLineData
+  subscribe(symbol, period, callback) {
+    const ws = new WebSocket(`wss://api.example.com/stream/${symbol.ticker}`);
+    ws.onmessage = (e) => {
+      const msg = JSON.parse(e.data);
+      if (msg.type === "kline") callback(msg.candle);
+      if (msg.type === "signal") signalBus.emit(msg); // hand off to your UI
+    };
+    sockets.set(symbol.ticker, ws);
+  },
+  unsubscribe(symbol) {
+    sockets.get(symbol.ticker)?.close();
+    sockets.delete(symbol.ticker);
+  },
+};
+```
+
+```tsx
+// Render a backend signal as an order line + annotation
+function SignalLayer() {
+  const { createOrderLine } = useOrderLines();
+  const { addAnnotation } = useAnnotations();
+
+  useEffect(() => {
+    return signalBus.on("signal", (s) => {
+      createOrderLine({ price: s.entry, text: `${s.side} @ ${s.entry}` });
+      addAnnotation(s.side === "buy" ? "▲" : "▼", s.entry, s.timestamp);
+    });
+  }, [createOrderLine, addAnnotation]);
+
+  return null;
+}
+```
+
+### Chart → backend (react to price events)
+
+Detect a price event on the client and forward it to your backend (webhook, order placement) or fire a push notification — all inside the [`useAlerts`](#usealerts) callback:
+
+```tsx
+function PriceAlertBridge() {
+  const { addAlert, onAlertTriggered } = useAlerts();
+
+  useEffect(() => {
+    addAlert(65000, "crossing_up", "BTC > 65k");
+
+    onAlertTriggered(async (alert) => {
+      // 1. Notify your backend (e.g. to place/adjust an order)
+      await fetch("https://api.example.com/signals", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ price: alert.price, condition: alert.condition }),
+      });
+
+      // 2. Browser push notification
+      if (Notification.permission === "granted") {
+        new Notification("Price alert", { body: alert.message });
+      }
+    });
+  }, [addAlert, onAlertTriggered]);
+
+  return null;
+}
+```
+
+> The chart-side `useAlerts` detection is a convenience based on the latest candle close (polled once per second) — it is **not** a substitute for authoritative server-side alerting. For guaranteed delivery, run the alert/signal logic on your backend and use the **Backend → chart** path above to visualize it.
+
+### Observing state
+
+Use **[State Callbacks](#state-callbacks)** (`onStateChange`, `onSymbolChange`, `onSubIndicatorsChange`, …) to forward symbol/period/indicator changes to your backend — for example, to subscribe the right server-side signal stream for whatever the user is currently viewing.
+
+---
+
 ## Full Export List
 
 ```typescript
@@ -1534,7 +1823,12 @@ export { useKlinechartsUILoading, type UseKlinechartsUILoadingReturn };
 export { usePeriods, type UsePeriodsReturn };
 export { useTimezone, type UseTimezoneReturn, type TimezoneItem };
 export { useSymbolSearch, type UseSymbolSearchReturn };
-export { useIndicators, type UseIndicatorsReturn, type IndicatorInfo };
+export {
+  useIndicators,
+  type UseIndicatorsReturn,
+  type IndicatorInfo,
+  type AddIndicatorOptions,
+};
 export {
   useDrawingTools,
   type UseDrawingToolsReturn,
@@ -1567,6 +1861,19 @@ export {
   type UseScriptEditorReturn,
   type ScriptPlacement,
 };
+export { useCrosshair, type UseCrosshairReturn, type CrosshairBarData };
+export { useAlerts, type UseAlertsReturn, type Alert, type AlertCondition };
+export { useDataExport, type UseDataExportReturn, type ExportFormat };
+export { useWatchlist, type UseWatchlistReturn, type WatchlistItem };
+export { useReplay, type UseReplayReturn, type ReplaySpeed };
+export { useCompare, type UseCompareReturn, type CompareSymbol };
+export {
+  useMeasure,
+  type UseMeasureReturn,
+  type MeasureResult,
+  type MeasurePoint,
+};
+export { useAnnotations, type UseAnnotationsReturn, type Annotation };
 
 // Data
 export { DEFAULT_PERIODS, type TerminalPeriod };
@@ -1619,7 +1926,7 @@ export {
 export * from "./indicators";
 
 // Extensions
-export { registerExtensions, overlays, indicators, orderLine };
+export { registerExtensions, overlays, indicators, orderLine, depthOverlay };
 export type {
   OrderLineExtendData,
   OrderLineLineStyle,
@@ -1627,5 +1934,7 @@ export type {
   OrderLineLabelStyle,
   OrderLineFontStyle,
   OrderLinePadding,
+  DepthOverlayExtendData,
+  DepthOverlayRow,
 };
 ```

package/dist/{chunk-U325AHHX.js → chunk-DTBNTO4M.js}

@@ -929,18 +929,14 @@ var ray = {
   needDefaultYAxisFigure: true,
   createPointFigures: ({ coordinates, bounding }) => {
     if (coordinates.length > 1) {
-      let coordinate = { x: 0, y: 0 };
-      if (coordinates[0].x === coordinates[1].x && coordinates[0].y !== coordinates[1].y) {
-        if (coordinates[0].y < coordinates[1].y) {
-          coordinate = { x: coordinates[0].x, y: bounding.height };
-        } else {
-          coordinate = { x: coordinates[0].x, y: 0 };
+      const coordinate = (() => {
+        if (coordinates[0].x === coordinates[1].x && coordinates[0].y !== coordinates[1].y) {
+          return coordinates[0].y < coordinates[1].y ? { x: coordinates[0].x, y: bounding.height } : { x: coordinates[0].x, y: 0 };
         }
-      } else {
         const x = coordinates[0].x < coordinates[1].x ? bounding.width : 0;
         const y = (coordinates[1].y - coordinates[0].y) / (coordinates[1].x - coordinates[0].x) * (x - coordinates[0].x) + coordinates[0].y;
-        coordinate = { x, y };
-      }
+        return { x, y };
+      })();
       return [
         {
           type: "line",
@@ -1950,14 +1946,7 @@ var macdTv = {
       styles: (data) => {
         const current = data.current?.histogram ?? 0;
         const pre = data.prev?.histogram ?? 0;
-        let color = "#26A69A";
-        if (current > 0) {
-          color = current > pre ? "#26A69A" : "#B2DFDB";
-        } else if (current < 0) {
-          color = current < pre ? "#FF5252" : "#FFCDD2";
-        } else {
-          color = "#B2DFDB";
-        }
+        const color = current > 0 ? current > pre ? "#26A69A" : "#B2DFDB" : current < 0 ? current < pre ? "#FF5252" : "#FFCDD2" : "#B2DFDB";
         return { color };
       }
     },
@@ -2464,5 +2453,5 @@ function registerExtensions() {
 }
 
 export { TA_default, abcd_default, anyWaves_default, arrow_default, bollTv_default, brush_default, cci_default, circle_default, depthOverlay_default, eightWaves_default, elliottWave_default, fibRetracement_default, fibonacciCircle_default, fibonacciExtension_default, fibonacciSegment_default, fibonacciSpeedResistanceFan_default, fibonacciSpiral_default, fiveWaves_default, gannBox_default, gannFan_default, hma_default, ichimoku_default, indicators, longPosition_default, maRibbon_default, macdTv_default, measure_default, orderLine_default, overlays, parallelChannel_default, parallelogram_default, pivotPoints_default, ray_default, rect_default, registerExtensions, rsiTv_default, shortPosition_default, stochastic_default, superTrend_default, threeWaves_default, triangle_default, vwap_default, xabcd_default };
-//# sourceMappingURL=chunk-U325AHHX.js.map
-//# sourceMappingURL=chunk-U325AHHX.js.map
+//# sourceMappingURL=chunk-DTBNTO4M.js.map
+//# sourceMappingURL=chunk-DTBNTO4M.js.map