react-klinecharts-ui 0.4.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)
 
 ---
 
@@ -207,6 +211,10 @@ interface KlinechartsUIState {
   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
 }
@@ -227,6 +235,10 @@ type KlinechartsUIAction =
   | { 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 };
@@ -457,12 +469,14 @@ const {
   moveToMain,
   moveToSub,
   setIndicatorVisible,
+  isIndicatorVisible,
   updateIndicatorParams,
   getIndicatorParams,
   isMainIndicatorActive,
   isSubIndicatorActive,
   indicatorAxes,
   getIndicatorAxis,
+  indicatorVisibility,
   bindIndicatorToNewAxis,
 } = useIndicators();
 ```
@@ -471,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
 }
 ```
 
@@ -497,7 +514,8 @@ interface IndicatorInfo {
 | `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                                            |
@@ -1022,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";
 
@@ -1095,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";
 
@@ -1127,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
@@ -1271,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
@@ -1539,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
@@ -1565,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,
@@ -1598,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 };
@@ -1650,7 +1926,7 @@ export {
 export * from "./indicators";
 
 // Extensions
-export { registerExtensions, overlays, indicators, orderLine };
+export { registerExtensions, overlays, indicators, orderLine, depthOverlay };
 export type {
   OrderLineExtendData,
   OrderLineLineStyle,
@@ -1658,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