react-klinecharts-ui 0.2.0 → 0.3.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
 ```
 
 ---
@@ -909,6 +914,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 +1395,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