react-klinecharts-ui 0.2.0 → 0.4.0

package/README.md

@@ -2,6 +2,8 @@
 
 **react-klinecharts-ui** is a headless React library for building financial trading terminals on top of [klinecharts](https://github.com/liihuu/KLineChart). It provides a state provider, a set of hooks, and overlay templates. No UI components are included — use any UI framework you prefer.
 
+**[Live Demo](https://nemezzizz.github.io/react-klinecharts-ui/)**
+
 ### Acknowledgments
 
 Many features in this library — including 11 TradingView-style indicators, 9 drawing overlays, the TA math library, undo/redo, layout manager, and script editor — were ported from the [QUANTIX Extended Edition](https://github.com/dsavenk0/KLineChart-Pro) fork of KLineChart-Pro by [@dsavenk0](https://github.com/dsavenk0). The original fork implements these as a tightly-coupled Vue 3 application; this library re-implements them as headless React hooks following the composable, framework-agnostic architecture.
@@ -34,6 +36,11 @@ Many features in this library — including 11 TradingView-style indicators, 9 d
    - [useUndoRedo](#useundoredo)
    - [useLayoutManager](#uselayoutmanager)
    - [useScriptEditor](#usescripteditor)
+   - [useWatchlist](#usewatchlist)
+   - [useCompare](#usecompare)
+   - [useMeasure](#usemeasure)
+   - [useAnnotations](#useannotations)
+   - [useReplay](#usereplay)
 6. [Utilities](#utilities)
    - [createDataLoader](#createdataloader)
    - [TA (Technical Analysis)](#ta-technical-analysis)
@@ -48,14 +55,12 @@ Many features in this library — including 11 TradingView-style indicators, 9 d
 
 ## Installation
 
-> **Note:** `react-klinecharts` is not yet published to the npm registry. Install it directly from GitHub:
-
 ```bash
-npm install react-klinecharts-ui github:NemeZZiZZ/react-klinecharts
+npm install react-klinecharts-ui react-klinecharts
 # or with pnpm
-pnpm add react-klinecharts-ui github:NemeZZiZZ/react-klinecharts
+pnpm add react-klinecharts-ui react-klinecharts
 # or with yarn
-yarn add react-klinecharts-ui github:NemeZZiZZ/react-klinecharts
+yarn add react-klinecharts-ui react-klinecharts
 ```
 
 ---
@@ -201,6 +206,7 @@ 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 }
   styles: DeepPartial<Styles> | undefined; // Custom klinecharts styles
   screenshotUrl: string | null; // URL of the last screenshot
 }
@@ -220,6 +226,7 @@ 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_STYLES"; styles: DeepPartial<Styles> | undefined }
   | { type: "SET_LOCALE"; locale: string }
   | { type: "SET_SCREENSHOT_URL"; url: string | null };
@@ -454,6 +461,9 @@ const {
   getIndicatorParams,
   isMainIndicatorActive,
   isSubIndicatorActive,
+  indicatorAxes,
+  getIndicatorAxis,
+  bindIndicatorToNewAxis,
 } = useIndicators();
 ```
 
@@ -479,9 +489,9 @@ 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                                       |
@@ -492,6 +502,32 @@ interface IndicatorInfo {
 | `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
 
@@ -909,6 +945,188 @@ return rsi.map((v, i) => ({
 
 ---
 
+### useWatchlist
+
+Manage a list of tracked symbols with live price updates from your datafeed.
+
+```typescript
+import { useWatchlist } from "react-klinecharts-ui";
+
+const {
+  items,
+  addSymbol,
+  removeSymbol,
+  switchSymbol,
+  activeSymbol,
+} = useWatchlist();
+```
+
+#### Return type: `UseWatchlistReturn`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `items` | `WatchlistItem[]` | Array of tracked symbols with price data |
+| `addSymbol` | `(ticker: string) => void` | Add a symbol to the watchlist |
+| `removeSymbol` | `(ticker: string) => void` | Remove a symbol from the watchlist |
+| `switchSymbol` | `(ticker: string) => void` | Change the chart to display a symbol |
+| `activeSymbol` | `string \| null` | Currently displayed symbol ticker |
+
+#### WatchlistItem
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `ticker` | `string` | Symbol identifier |
+| `lastPrice` | `number \| null` | Last traded price |
+| `change` | `number \| null` | Absolute price change |
+| `changePercent` | `number \| null` | 24h percentage change |
+
+---
+
+### useCompare
+
+Compare multiple symbols on the same chart with individual colors and visibility toggle.
+
+```typescript
+import { useCompare } from "react-klinecharts-ui";
+
+const {
+  symbols,
+  addSymbol,
+  removeSymbol,
+  toggleSymbol,
+  clearAll,
+} = useCompare();
+```
+
+#### Return type: `UseCompareReturn`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `symbols` | `CompareSymbol[]` | Array of comparison symbols with metadata |
+| `addSymbol` | `(ticker: string) => void` | Add a symbol to compare |
+| `removeSymbol` | `(ticker: string) => void` | Remove a comparison symbol |
+| `toggleSymbol` | `(ticker: string) => void` | Toggle visibility of a symbol |
+| `clearAll` | `() => void` | Remove all comparison symbols |
+
+#### CompareSymbol
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `ticker` | `string` | Symbol identifier |
+| `visible` | `boolean` | Whether the symbol is currently visible on chart |
+| `color` | `string` | Hex color code for the symbol's line |
+
+---
+
+### useMeasure
+
+Measure price changes, percentage swings, bar count, and time intervals between two points on the chart.
+
+```typescript
+import { useMeasure } from "react-klinecharts-ui";
+
+const {
+  isActive,
+  startMeasure,
+  cancelMeasure,
+  result,
+} = useMeasure();
+```
+
+#### Return type: `UseMeasureReturn`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `isActive` | `boolean` | Whether measurement mode is enabled |
+| `startMeasure` | `() => void` | Enter measurement mode (click two points) |
+| `cancelMeasure` | `() => void` | Exit measurement mode |
+| `result` | `MeasureResult \| null` | Measurement data (null if not measured yet) |
+
+#### MeasureResult
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `priceDiff` | `number` | Absolute price difference |
+| `pricePercent` | `number` | Percentage change |
+| `bars` | `number` | Number of bars between points |
+| `timeDiff` | `number` | Time difference in milliseconds |
+
+---
+
+### useAnnotations
+
+Add text annotations at specific price levels and timestamps with optional colors.
+
+```typescript
+import { useAnnotations } from "react-klinecharts-ui";
+
+const {
+  annotations,
+  addAnnotation,
+  removeAnnotation,
+  updateAnnotation,
+  clearAnnotations,
+} = useAnnotations();
+```
+
+#### Return type: `UseAnnotationsReturn`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `annotations` | `Annotation[]` | Array of all annotations |
+| `addAnnotation` | `(text, price, timestamp, color?) => string` | Add annotation; returns ID |
+| `removeAnnotation` | `(id: string) => void` | Remove annotation by ID |
+| `updateAnnotation` | `(id, updates) => void` | Update text or color |
+| `clearAnnotations` | `() => void` | Remove all annotations |
+
+#### Annotation
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `id` | `string` | Unique identifier |
+| `text` | `string` | Annotation text |
+| `price` | `number` | Price level |
+| `timestamp` | `number` | Candle timestamp |
+| `color` | `string \| undefined` | Optional hex color |
+
+---
+
+### useReplay
+
+Replay historical candles at various speeds with play/pause/step controls and progress tracking.
+
+```typescript
+import { useReplay } from "react-klinecharts-ui";
+
+const {
+  isPlaying,
+  speed,
+  currentIndex,
+  totalBars,
+  play,
+  pause,
+  stop,
+  step,
+  setSpeed,
+} = useReplay();
+```
+
+#### Return type: `UseReplayReturn`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `isPlaying` | `boolean` | Whether replay is running |
+| `speed` | `number` | Current playback speed (0.25, 0.5, 1, 2, 4) |
+| `currentIndex` | `number` | Current bar index being displayed |
+| `totalBars` | `number` | Total bars in the dataset |
+| `play` | `() => void` | Start replay from current position |
+| `pause` | `() => void` | Pause replay (can resume with play) |
+| `stop` | `() => void` | Stop replay and reset to start |
+| `step` | `() => void` | Advance one bar when paused |
+| `setSpeed` | `(speed: number) => void` | Set playback speed multiplier |
+
+---
+
 ## Utilities
 
 ### createDataLoader
@@ -1208,6 +1426,58 @@ interface OrderLinePadding {
 
 All sub-interfaces (`OrderLineLineStyle`, `OrderLineMarkStyle`, `OrderLineLabelStyle`, `OrderLineFontStyle`, `OrderLinePadding`) are exported as named types from both the main and `extensions` entry points.
 
+### depthOverlay
+
+Overlay template for visualizing order book depth as horizontal liquidity bars at each price level. Shows cumulative buy/sell volume at price levels, useful for understanding support/resistance zones.
+
+```typescript
+import { depthOverlay, KlinechartsUIProvider } from "react-klinecharts-ui/extensions";
+
+<KlinechartsUIProvider overlays={[depthOverlay]}>...</KlinechartsUIProvider>;
+```
+
+**Implementation details:**
+
+- `needDefaultPointFigure: false`, `needDefaultXAxisFigure: false`, `needDefaultYAxisFigure: false` — entirely custom rendering
+- `createPointFigures` — draws rect figures at each price level using `yAxis.convertToPixel(price)` for positioning
+- `zLevel: -1` — renders behind the main candlestick data
+- Dynamic data via `extendData` — update with `chart.overrideOverlay({ id, extendData: newData })`
+
+#### DepthOverlayExtendData
+
+```typescript
+interface DepthOverlayExtendData {
+  rows?: DepthOverlayRow[];
+  /** Optional: customize buy side color. Default: "rgba(16, 186, 156, 0.3)" */
+  buyColor?: string;
+  /** Optional: customize sell side color. Default: "rgba(239, 68, 68, 0.3)" */
+  sellColor?: string;
+}
+
+interface DepthOverlayRow {
+  price: number;
+  buyVolume: number;
+  sellVolume: number;
+}
+```
+
+**Usage example:**
+
+```typescript
+const chart = state.chart;
+if (chart) {
+  const rows: DepthOverlayRow[] = [
+    { price: 40000, buyVolume: 5.2, sellVolume: 3.1 },
+    { price: 40100, buyVolume: 4.8, sellVolume: 4.2 },
+    // ...
+  ];
+  chart.overrideOverlay({
+    id: "depthOverlay",
+    extendData: { rows, buyColor: "rgba(34, 197, 94, 0.3)" },
+  });
+}
+```
+
 ### overlays (array)
 
 Array of all built-in drawing overlays — for direct access to the list:

package/dist/{chunk-47JXSAIT.cjs → chunk-PIFLJKYF.cjs}

@@ -2410,6 +2410,50 @@ var orderLine = {
 };
 var orderLine_default = orderLine;
 
+// src/extensions/overlays/depthOverlay.ts
+var depthOverlay = {
+  name: "depthOverlay",
+  totalStep: 2,
+  needDefaultPointFigure: false,
+  needDefaultXAxisFigure: false,
+  needDefaultYAxisFigure: false,
+  lock: true,
+  visible: true,
+  zLevel: -1,
+  createPointFigures: ({ overlay, bounding, yAxis }) => {
+    const d = overlay.extendData;
+    if (!d || !d.rows || d.rows.length === 0 || !yAxis) return [];
+    const maxBarFraction = d.maxBarWidth ?? 0.3;
+    const maxBarPx = bounding.width * maxBarFraction;
+    const askColor = d.askColor ?? "rgba(239,83,80,0.25)";
+    const bidColor = d.bidColor ?? "rgba(38,166,154,0.25)";
+    const maxQty = d.maxQty || 1;
+    const figures = [];
+    for (const row of d.rows) {
+      const y = yAxis.convertToPixel(row.price);
+      if (y == null || y < 0 || y > bounding.height) continue;
+      const barWidth = row.qty / maxQty * maxBarPx;
+      const barHeight = Math.max(2, bounding.height / d.rows.length * 0.8);
+      const color = row.side === "ask" ? askColor : bidColor;
+      figures.push({
+        type: "rect",
+        attrs: {
+          x: bounding.width - barWidth,
+          y: y - barHeight / 2,
+          width: barWidth,
+          height: barHeight
+        },
+        styles: {
+          color
+        },
+        ignoreEvent: true
+      });
+    }
+    return figures;
+  }
+};
+var depthOverlay_default = depthOverlay;
+
 // src/extensions/index.ts
 var overlays = Object.values(overlays_exports);
 var indicators = Object.values(indicators_exports);
@@ -2429,6 +2473,7 @@ exports.bollTv_default = bollTv_default;
 exports.brush_default = brush_default;
 exports.cci_default = cci_default;
 exports.circle_default = circle_default;
+exports.depthOverlay_default = depthOverlay_default;
 exports.eightWaves_default = eightWaves_default;
 exports.elliottWave_default = elliottWave_default;
 exports.fibRetracement_default = fibRetracement_default;
@@ -2463,5 +2508,5 @@ exports.threeWaves_default = threeWaves_default;
 exports.triangle_default = triangle_default;
 exports.vwap_default = vwap_default;
 exports.xabcd_default = xabcd_default;
-//# sourceMappingURL=chunk-47JXSAIT.cjs.map
-//# sourceMappingURL=chunk-47JXSAIT.cjs.map
+//# sourceMappingURL=chunk-PIFLJKYF.cjs.map
+//# sourceMappingURL=chunk-PIFLJKYF.cjs.map