react-klinecharts-ui 0.5.0 → 1.0.0

package/README.md

@@ -2,7 +2,7 @@
 
 **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/)**
+**[Live Demo](https://nemezzizz.github.io/tradedash/)** · **[Examples](https://nemezzizz.github.io/react-klinecharts-ui/examples/)**
 
 ### Acknowledgments
 
@@ -44,6 +44,8 @@ Many features in this library — including 11 TradingView-style indicators, 9 d
    - [useAlerts](#usealerts)
    - [useCrosshair](#usecrosshair)
    - [useDataExport](#usedataexport)
+   - [useHotkeys](#usehotkeys)
+   - [useChartAxes](#usechartaxes)
 6. [Utilities](#utilities)
    - [createDataLoader](#createdataloader)
    - [TA (Technical Analysis)](#ta-technical-analysis)
@@ -60,11 +62,11 @@ Many features in this library — including 11 TradingView-style indicators, 9 d
 ## Installation
 
 ```bash
-npm install react-klinecharts-ui react-klinecharts
+npm install react-klinecharts-ui klinecharts
 # or with pnpm
-pnpm add react-klinecharts-ui react-klinecharts
+pnpm add react-klinecharts-ui klinecharts
 # or with yarn
-yarn add react-klinecharts-ui react-klinecharts
+yarn add react-klinecharts-ui klinecharts
 ```
 
 ---
@@ -520,6 +522,10 @@ interface IndicatorInfo {
 | `getIndicatorParams(name)`                    | Returns `[{ label, defaultValue }]` or `[]` if no parameters  |
 | `isMainIndicatorActive(name)`                 | Quick active check                                            |
 | `isSubIndicatorActive(name)`                  | Quick active check                                            |
+| `collapseSubIndicator(name)`                  | Collapse a sub-indicator pane to minimal height (30px)        |
+| `expandSubIndicator(name)`                    | Expand a previously collapsed sub-indicator pane              |
+| `isSubIndicatorCollapsed(name)`               | Whether the given sub-indicator pane is currently collapsed   |
+| `reorderSubIndicator(name, direction)`        | Reorder a sub-indicator pane `"up"` or `"down"`               |
 | `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) |
 
@@ -568,12 +574,14 @@ const {
   magnetMode,
   isLocked,
   isVisible,
+  autoRetrigger,
   selectTool,
   clearActiveTool,
   setMagnetMode,
   toggleLock,
   toggleVisibility,
   removeAllDrawings,
+  setAutoRetrigger,
 } = useDrawingTools();
 ```
 
@@ -584,12 +592,14 @@ const {
 | `magnetMode`          | `"normal" \| "weak" \| "strong"` | Snap-to-OHLC mode                                       |
 | `isLocked`            | `boolean`                        | Whether all drawings are locked                         |
 | `isVisible`           | `boolean`                        | Whether all drawings are visible                        |
+| `autoRetrigger`       | `boolean`                        | Re-arm the tool after finishing a shape (default `true`) |
 | `selectTool(name)`    | —                                | Start drawing via `chart.createOverlay`                 |
 | `clearActiveTool()`   | —                                | Deselect tool (local state only)                        |
 | `setMagnetMode(mode)` | —                                | Change magnet mode for all existing and future drawings |
 | `toggleLock()`        | —                                | Toggle lock on all drawings                             |
 | `toggleVisibility()`  | —                                | Show/hide all drawings                                  |
 | `removeAllDrawings()` | —                                | Remove all drawings in the `drawing_tools` group        |
+| `setAutoRetrigger(enabled)` | —                          | Enable/disable auto re-arming                           |
 
 ```typescript
 interface DrawingToolItem {
@@ -612,6 +622,9 @@ interface DrawingCategoryItem {
 | `polygon`        | circle, rect, parallelogram, triangle                                                                                                                                  |
 | `fibonacci`      | fibonacciLine, fibonacciSegment, fibonacciCircle, fibonacciSpiral, fibonacciSpeedResistanceFan, fibonacciExtension, gannBox                                            |
 | `wave`           | xabcd, abcd, threeWaves, fiveWaves, eightWaves, anyWaves                                                                                                               |
+| `annotation`     | brush                                                                                                                                                                  |
+
+> **Freehand drawing.** The `brush` tool (category `annotation`) uses klinecharts' continuous (freehand) drawing mode — hold and drag to sketch. It is a built-in overlay added in **klinecharts 10.0.0-beta3**, so it requires beta3+ to render.
 
 ---
 
@@ -627,20 +640,25 @@ const settings = useKlinechartsUISettings();
 
 | Field                    | Type            | Default          | Description               |
 | ------------------------ | --------------- | ---------------- | ------------------------- |
-| `candleType`             | `string`        | `"candle_solid"` | Candle display type       |
-| `candleUpColor`          | `string`        | `"#2DC08E"`      | Bullish candle color      |
-| `candleDownColor`        | `string`        | `"#F92855"`      | Bearish candle color      |
-| `showLastPrice`          | `boolean`       | `true`           | Last price mark on Y-axis |
-| `showHighPrice`          | `boolean`       | `true`           | High price mark           |
-| `showLowPrice`           | `boolean`       | `true`           | Low price mark            |
-| `showIndicatorLastValue` | `boolean`       | `true`           | Indicator last value mark |
-| `priceAxisType`          | `PriceAxisType` | `"normal"`       | Y-axis scale type         |
-| `reverseCoordinate`      | `boolean`       | `false`          | Invert Y-axis             |
-| `showTimeAxis`           | `boolean`       | `true`           | Show X-axis               |
-| `showGrid`               | `boolean`       | `true`           | Show grid                 |
-| `showCrosshair`          | `boolean`       | `true`           | Show crosshair            |
-| `showCandleTooltip`      | `boolean`       | `true`           | OHLCV tooltip             |
-| `showIndicatorTooltip`   | `boolean`       | `true`           | Indicator tooltip         |
+| `candleType`             | `string`         | `"candle_solid"`  | Candle display type           |
+| `candleUpColor`          | `string`         | `"#2DC08E"`       | Bullish candle color          |
+| `candleDownColor`        | `string`         | `"#F92855"`       | Bearish candle color          |
+| `compareRule`            | `CompareRule`    | `"current_open"`  | Baseline rule for compared symbols |
+| `showLastPrice`          | `boolean`        | `true`            | Last price mark on Y-axis     |
+| `showLastPriceLine`      | `boolean`        | `true`            | Last price horizontal line    |
+| `showHighPrice`          | `boolean`        | `true`            | High price mark               |
+| `showLowPrice`           | `boolean`        | `true`            | Low price mark                |
+| `showIndicatorLastValue` | `boolean`        | `true`            | Indicator last value mark     |
+| `priceAxisType`          | `PriceAxisType`  | `"normal"`        | Y-axis scale type             |
+| `yAxisPosition`          | `YAxisPosition`  | `"right"`         | Y-axis side (`"left" \| "right"`) |
+| `yAxisInside`            | `boolean`        | `false`           | Draw the Y-axis inside the pane |
+| `reverseCoordinate`      | `boolean`        | `false`           | Invert Y-axis                 |
+| `showTimeAxis`           | `boolean`        | `true`            | Show X-axis                   |
+| `showGrid`               | `boolean`        | `true`            | Show grid                     |
+| `showCrosshair`          | `boolean`        | `true`            | Show crosshair                |
+| `showCandleTooltip`      | `boolean`        | `true`            | OHLCV tooltip                 |
+| `showIndicatorTooltip`   | `boolean`        | `true`            | Indicator tooltip             |
+| `tooltipShowRule`        | `TooltipShowRule`| `"always"`        | When to show tooltips         |
 
 **Candle types:** `candle_solid`, `candle_stroke`, `candle_up_stroke`, `candle_down_stroke`, `ohlc`, `area`
 
@@ -648,14 +666,17 @@ const settings = useKlinechartsUISettings();
 
 #### Extra fields
 
-| Field            | Type                                          | Description                                           |
-| ---------------- | --------------------------------------------- | ----------------------------------------------------- |
-| `candleTypes`    | `CandleTypeItem[]`                            | List of `{ key, localeKey }` for rendering a selector |
-| `priceAxisTypes` | `{ key: PriceAxisType; localeKey: string }[]` | List for rendering a selector                         |
+| Field              | Type                                            | Description                                           |
+| ------------------ | ----------------------------------------------- | ----------------------------------------------------- |
+| `candleTypes`      | `CandleTypeItem[]`                              | List of `{ key, localeKey }` for rendering a selector |
+| `priceAxisTypes`   | `{ key: PriceAxisType; localeKey: string }[]`   | List for rendering a selector                         |
+| `yAxisPositions`   | `{ key: YAxisPosition; localeKey: string }[]`   | List for rendering a selector                         |
+| `compareRules`     | `{ key: CompareRule; localeKey: string }[]`     | List for rendering a selector                         |
+| `tooltipShowRules` | `{ key: TooltipShowRule; localeKey: string }[]` | List for rendering a selector                         |
 
 #### Setters
 
-Each field has a corresponding setter: `setCandleType`, `setCandleUpColor`, `setCandleDownColor`, `setShowLastPrice`, `setShowHighPrice`, `setShowLowPrice`, `setShowIndicatorLastValue`, `setPriceAxisType`, `setReverseCoordinate`, `setShowTimeAxis`, `setShowGrid`, `setShowCrosshair`, `setShowCandleTooltip`, `setShowIndicatorTooltip`.
+Each field has a corresponding setter: `setCandleType`, `setCandleUpColor`, `setCandleDownColor`, `setCompareRule`, `setShowLastPrice`, `setShowLastPriceLine`, `setShowHighPrice`, `setShowLowPrice`, `setShowIndicatorLastValue`, `setPriceAxisType`, `setYAxisPosition`, `setYAxisInside`, `setReverseCoordinate`, `setShowTimeAxis`, `setShowGrid`, `setShowCrosshair`, `setShowCandleTooltip`, `setShowIndicatorTooltip`, `setTooltipShowRule`.
 
 All setters immediately apply changes via `chart.setStyles(...)`.
 
@@ -736,7 +757,7 @@ const { containerRef, toggle, isFullscreen } = useFullscreen();
 
 Create and manage horizontal price level lines (order lines).
 
-> **Requirement:** The `orderLine` overlay must be registered via `overlays={[orderLine]}` on the provider.
+> **No setup required.** The `orderLine` overlay is registered automatically by `registerExtensions()` (enabled by default). Passing `overlays={[orderLine]}` to the provider still works and is harmless, but is no longer necessary.
 
 ```typescript
 const {
@@ -1021,7 +1042,7 @@ const {
 | Property | Type | Description |
 |----------|------|-------------|
 | `symbols` | `CompareSymbol[]` | Array of comparison symbols with metadata |
-| `addSymbol` | `(ticker: string) => void` | Add a symbol to compare |
+| `addSymbol` | `(ticker: string, color?: string) => Promise<void>` | Add a symbol to compare (optional line color) |
 | `removeSymbol` | `(ticker: string) => void` | Remove a comparison symbol |
 | `toggleSymbol` | `(ticker: string) => void` | Toggle visibility of a symbol |
 | `clearAll` | `() => void` | Remove all comparison symbols |
@@ -1050,6 +1071,8 @@ const {
   startMeasure,
   cancelMeasure,
   result,
+  clearResult,
+  fromPoint,
 } = useMeasure();
 ```
 
@@ -1061,6 +1084,8 @@ const {
 | `startMeasure` | `() => void` | Enter measurement mode (click two points) |
 | `cancelMeasure` | `() => void` | Exit measurement mode |
 | `result` | `MeasureResult \| null` | Measurement data (null if not measured yet) |
+| `clearResult` | `() => void` | Clear the current measurement result |
+| `fromPoint` | `MeasurePoint \| null` | The first picked point while measuring (null when inactive) |
 
 #### MeasureResult
 
@@ -1121,14 +1146,17 @@ Replay historical candles at various speeds with play/pause/step controls and pr
 import { useReplay } from "react-klinecharts-ui";
 
 const {
-  isPlaying,
+  isReplaying,
+  isPaused,
   speed,
-  currentIndex,
+  barIndex,
   totalBars,
-  play,
-  pause,
-  stop,
-  step,
+  startReplay,
+  stopReplay,
+  togglePause,
+  stepForward,
+  stepBackward,
+  seekTo,
   setSpeed,
 } = useReplay();
 ```
@@ -1137,24 +1165,29 @@ const {
 
 | 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 |
+| `isReplaying` | `boolean` | Whether a replay session is active |
+| `isPaused` | `boolean` | Whether the replay is currently paused |
+| `speed` | `ReplaySpeed` | Current playback speed multiplier (`1 \| 2 \| 5 \| 10`) |
+| `barIndex` | `number` | Current bar index in the replay |
+| `totalBars` | `number` | Total bars in the saved dataset |
+| `startReplay` | `() => void` | Start replaying from the beginning |
+| `stopReplay` | `() => void` | Stop replay and restore the original data |
+| `togglePause` | `() => void` | Toggle play/pause |
+| `stepForward` | `() => void` | Advance one bar while paused |
+| `stepBackward` | `() => void` | Go back one bar while paused |
+| `seekTo` | `(index: number) => void` | Seek to a specific bar index (pauses playback) |
+| `setSpeed` | `(speed: ReplaySpeed) => void` | Change the playback speed |
 
 ---
 
 ### 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)).
+Client-side price alerts. Draws a **labelled** locked horizontal line (price tag on the Y-axis + a bell-marked caption above the 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.
 
+> **No manual overlay registration.** The `alertLine` overlay template the hook draws with is registered automatically (both by `registerExtensions()` and lazily inside `useAlerts` before the first overlay is created) — you don't need to pass it through the provider's `overlays` prop.
+
 ```typescript
 import { useAlerts } from "react-klinecharts-ui";
 
@@ -1166,8 +1199,15 @@ const {
   onAlertTriggered,
 } = useAlerts();
 
+// Default: orange dashed line, bell + price/message caption.
 const id = addAlert(65000, "crossing_up", "BTC broke 65k");
 
+// Customize the look via the optional 4th argument (AlertLineExtendData).
+addAlert(70000, "crossing_up", "Take profit", {
+  color: "#e91e63",
+  showBell: true,
+});
+
 onAlertTriggered((alert) => {
   console.log("Alert fired:", alert.message, alert.price);
 });
@@ -1178,7 +1218,7 @@ onAlertTriggered((alert) => {
 | 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 |
+| `addAlert` | `(price: number, condition: AlertCondition, message?: string, extendData?: AlertLineExtendData) => string` | Create an alert at a price level; returns its id. The optional `extendData` customizes the line/label look |
 | `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 |
@@ -1194,9 +1234,28 @@ interface Alert {
   condition: AlertCondition;
   message?: string;
   triggered: boolean;
+  /** Visual style of the alert line; persisted so it survives undo/redo & layout presets. */
+  extendData?: AlertLineExtendData;
+}
+
+interface AlertLineExtendData {
+  /** Primary color for the line, the Y-axis mark bg, and label fallback. Default: "#ff9800" */
+  color?: string;
+  /** Caption above the line. Defaults to `message ?? formatted price` (symbol precision). */
+  text?: string;
+  /** Line style overrides (style / width / dashedValue). Default: dashed. */
+  line?: OrderLineLineStyle;
+  /** Y-axis price mark style overrides. */
+  mark?: OrderLineMarkStyle;
+  /** Caption text style overrides. */
+  label?: OrderLineLabelStyle;
+  /** Show a 🔔 marker before the caption. Default: true */
+  showBell?: boolean;
 }
 ```
 
+The `line` / `mark` / `label` style types are shared with [`useOrderLines`](#useorderlines) (`OrderLineLineStyle`, `OrderLineMarkStyle`, `OrderLineLabelStyle`).
+
 | Condition | Fires when |
 |-----------|------------|
 | `crossing_up` | Previous close `<` price **and** current close `>=` price |
@@ -1271,6 +1330,83 @@ type ExportFormat = "csv" | "json";
 
 ---
 
+### useHotkeys
+
+Keyboard shortcuts (klinecharts v10, requires **klinecharts 10.0.0-beta3+**). Register custom hotkeys globally and toggle hotkey handling per chart. The `action` callback receives the chart instance, the keyboard event, the matched key, and the hotkey template.
+
+```typescript
+import { useHotkeys } from "react-klinecharts-ui";
+
+const { registerHotkey, setHotkeysEnabled, supportedHotkeys } = useHotkeys();
+
+// Register a custom shortcut — Ctrl/Cmd+L removes all overlays.
+registerHotkey({
+  name: "remove-all-overlays",
+  keys: ["ctrl+l", "meta+l"],
+  preventDefault: true,
+  action: ({ chart }) => chart.removeOverlay(),
+});
+
+// Disable all built-in shortcuts except undo/redo.
+setHotkeysEnabled(true, ["undo", "redo"]);
+```
+
+#### Return type: `UseHotkeysReturn`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `registerHotkey` | `(template: HotkeyTemplate) => void` | Register a custom hotkey globally (idempotent per `name`) |
+| `getHotkey` | `(name: string) => HotkeyTemplate \| null` | Look up a registered hotkey by name |
+| `supportedHotkeys` | `string[]` | Names of every registered hotkey (built-in + custom) |
+| `setHotkeysEnabled` | `(enabled: boolean, exclude?: string[]) => void` | Enable/disable hotkey handling for the chart; optionally exclude names |
+| `getHotkeysConfig` | `() => Hotkey \| null` | Current `{ enabled, exclude }` config for the chart |
+
+```typescript
+interface HotkeyTemplate {
+  name: string;
+  keys: string | string[];
+  preventDefault?: boolean;
+  stopPropagation?: boolean;
+  check?: (params: HotkeyActionParams) => boolean;
+  action: (params: HotkeyActionParams) => void;
+  extendData?: unknown;
+}
+
+interface Hotkey {
+  enabled: boolean;
+  exclude: string[];
+}
+```
+
+> Custom hotkeys register **globally** (shared by every chart on the page); the enable/exclude switches are per-chart. klinecharts exposes no removal API, so a registered hotkey lives for the page session.
+
+---
+
+### useChartAxes
+
+Override the chart's built-in X (time) and Y (value) axes (klinecharts v10 `overrideXAxis` / `overrideYAxis`, added in **beta2**). For binding indicators to additional secondary Y-axes, use [useIndicators](#useindicators) instead.
+
+```typescript
+import { useChartAxes } from "react-klinecharts-ui";
+
+const { overrideXAxis, overrideYAxis } = useChartAxes();
+
+overrideYAxis({ reverse: true });            // flip the price scale
+overrideYAxis({ inside: true });             // draw price labels inside the pane
+overrideXAxis({ scrollZoomEnabled: false }); // lock time-axis zoom
+```
+
+#### Return type: `UseChartAxesReturn`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `overrideXAxis` | `(override: XAxisOverride) => void` | Override the main X (time) axis (`name`, `scrollZoomEnabled`, `createTicks`) |
+| `overrideYAxis` | `(override: YAxisOverride) => void` | Override a Y (value) axis (`reverse`, `inside`, `position`, `scrollZoomEnabled`, `createRange`, `createTicks`, `id`/`paneId` to target one) |
+
+> klinecharts beta3 ships these two methods with their parameter types **crossed** in its published typings; this hook shields you behind semantically-correct signatures, so `overrideYAxis` takes `YAxisOverride` and `overrideXAxis` takes `XAxisOverride` as expected.
+
+---
+
 ## Utilities
 
 ### createDataLoader
@@ -1344,7 +1480,6 @@ import { TA } from "react-klinecharts-ui";
 | `TA.atr` | `(highs: number[], lows: number[], closes: number[], period: number)` | `number[]` — Average True Range |
 | `TA.vwap` | `(highs: number[], lows: number[], closes: number[], volumes: number[])` | `number[]` — Volume Weighted Average Price |
 | `TA.cci` | `(highs: number[], lows: number[], closes: number[], period: number)` | `number[]` — Commodity Channel Index |
-| `TA.stoch` | `(highs: number[], lows: number[], closes: number[], kPeriod?, kSmooth?, dPeriod?)` | `{ k, d }` — each `(number \| null)[]` |
 
 ---
 
@@ -1513,7 +1648,7 @@ import { indicators } from "react-klinecharts-ui";
 
 ### registerExtensions
 
-Registers all built-in drawing overlays via `registerOverlay`. Called automatically by the provider when `registerExtensions: true`.
+Registers all built-in drawing overlays plus the feature overlays (`orderLine`, `alertLine`, `depthOverlay`) via `registerOverlay`. Called automatically by the provider when `registerExtensions: true`.
 
 ```typescript
 import { registerExtensions } from "react-klinecharts-ui";
@@ -1522,12 +1657,11 @@ registerExtensions(); // Idempotent — repeated calls are ignored
 
 ### orderLine
 
-Overlay template for horizontal price level lines. **Not registered automatically** — must be passed explicitly to the provider.
+Overlay template for horizontal price level lines. **Registered automatically** by `registerExtensions()` (default), so `useOrderLines` works out of the box. Passing it through `overlays={[orderLine]}` is optional.
 
 ```typescript
-import { orderLine, KlinechartsUIProvider } from "react-klinecharts-ui";
-
-<KlinechartsUIProvider overlays={[orderLine]}>...</KlinechartsUIProvider>;
+import { orderLine } from "react-klinecharts-ui";
+// No provider wiring needed — registered automatically.
 ```
 
 **Implementation details:**
@@ -1557,7 +1691,9 @@ interface OrderLineExtendData {
 }
 
 interface OrderLineLineStyle {
-  style?: "solid" | "dashed" | "dotted"; // Default: "dashed"
+  // klinecharts only supports "solid" and "dashed"; a dotted effect is done
+  // via `dashedValue` (e.g. [2, 2]).
+  style?: "solid" | "dashed"; // Default: "dashed"
   width?: number; // Default: 1
   dashedValue?: [number, number]; // Default: [4, 2]
 }
@@ -1593,14 +1729,24 @@ interface OrderLinePadding {
 
 All sub-interfaces (`OrderLineLineStyle`, `OrderLineMarkStyle`, `OrderLineLabelStyle`, `OrderLineFontStyle`, `OrderLinePadding`) are exported as named types from both the main and `extensions` entry points.
 
-### depthOverlay
+### alertLine
 
-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.
+Overlay template drawn by [`useAlerts`](#usealerts) for price alerts: a locked horizontal line with a Y-axis price mark and a bell-marked caption above the line. **Registered automatically** by `registerExtensions()` and lazily by `useAlerts` itself, so no provider wiring is required.
 
 ```typescript
-import { depthOverlay, KlinechartsUIProvider } from "react-klinecharts-ui/extensions";
+import { alertLine } from "react-klinecharts-ui";
+// Used internally by useAlerts; exported for advanced/manual overlay use.
+```
 
-<KlinechartsUIProvider overlays={[depthOverlay]}>...</KlinechartsUIProvider>;
+Its `extendData` shape is [`AlertLineExtendData`](#types) — it reuses the `OrderLineLineStyle` / `OrderLineMarkStyle` / `OrderLineLabelStyle` sub-types from `orderLine` and adds `showBell?: boolean` (default `true`). When no `text` is supplied the caption falls back to the formatted price (using `chart.getSymbol()?.pricePrecision`).
+
+### 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. **Registered automatically** by `registerExtensions()` (default); explicit `overlays={[depthOverlay]}` wiring is optional.
+
+```typescript
+import { depthOverlay } from "react-klinecharts-ui/extensions";
+// No provider wiring needed — registered automatically.
 ```
 
 **Implementation details:**
@@ -1926,7 +2072,7 @@ export {
 export * from "./indicators";
 
 // Extensions
-export { registerExtensions, overlays, indicators, orderLine, depthOverlay };
+export { registerExtensions, overlays, indicators, orderLine, alertLine, depthOverlay };
 export type {
   OrderLineExtendData,
   OrderLineLineStyle,
@@ -1934,6 +2080,7 @@ export type {
   OrderLineLabelStyle,
   OrderLineFontStyle,
   OrderLinePadding,
+  AlertLineExtendData,
   DepthOverlayExtendData,
   DepthOverlayRow,
 };