hyperprop-charting-library 0.1.20 → 0.1.22

package/docs/API.md

@@ -61,6 +61,7 @@ Top-level options:
 - `orderLines?: OrderLineOptions[]`
 - `tickerLine?: TickerLineOptions`
 - `dashPatterns?: Partial<DashPatternOptions>` (controls dotted/dashed spacing)
+- `indicators?: IndicatorInstanceOptions[]` (initial indicator instances, built-in includes `"volume"`)
 
 ### `AxisOptions`
 
@@ -238,6 +239,62 @@ Connector/fill visuals:
 - `fillToPrice?: number`
 - `fillColor?: string`
 
+### `IndicatorInstanceOptions`
+
+- `id?: string`
+- `type: string` (registered indicator id, e.g. `"volume"`)
+- `visible?: boolean` (default `true`)
+- `pane?: "overlay" | "separate"`
+- `paneHeightRatio?: number` (for separate panes; `0.08` to `0.45` recommended)
+- `inputs?: Record<string, unknown>` (plugin-specific parameters)
+
+### `IndicatorPlugin`
+
+- `id: string`
+- `name: string`
+- `pane?: "overlay" | "separate"` (default `"overlay"`)
+- `paneHeightRatio?: number` (for separate panes)
+- `defaultInputs?: Record<string, unknown>`
+- `draw(ctx, renderContext, inputs): void`
+
+`IndicatorRenderContext` includes:
+
+- shared x-window and visible index range (`startIndex`, `endIndex`, `xStart`, `xSpan`)
+- pane bounds (`chartLeft`, `chartRight`, `chartTop`, `chartBottom`, `chartWidth`, `chartHeight`)
+- `xFromIndex(index)` helper
+- `yFromPrice(price)` helper (available for overlay indicators, `null` for separate-pane indicators)
+- theme colors (`upColor`, `downColor`)
+
+Built-in:
+
+- `"volume"`: separate pane histogram (uses `OhlcDataPoint.v`)
+- `"sma"`: Simple Moving Average (overlay)
+- `"ema"`: Exponential Moving Average (overlay)
+- `"rsi"`: Relative Strength Index (separate pane, 30/50/70 guides)
+- `"wma"`: Weighted Moving Average (overlay)
+- `"vwma"`: Volume Weighted Moving Average (overlay, uses `OhlcDataPoint.v`)
+- `"rma"`: Wilder's Moving Average (overlay)
+- `"hma"`: Hull Moving Average (overlay)
+- `"stddev"`: Standard Deviation (separate pane)
+- `"atr"`: Average True Range (separate pane)
+
+Example:
+
+```ts
+const emaId = chart.addIndicator("ema", { length: 34, source: "close" });
+const rsiId = chart.addIndicator("rsi", { length: 14 }, { pane: "separate", paneHeightRatio: 0.18 });
+
+// resize pane later (useful for drag-handle UX in frontend)
+chart.updateIndicator(rsiId, { paneHeightRatio: 0.12 });
+
+// remove when needed
+chart.removeIndicator(emaId);
+```
+
+Volume/VWMA note:
+
+- if your data has no `v`, `volume`/`vwma` will have limited or no output.
+
 ---
 
 ## `ChartInstance` Methods
@@ -264,5 +321,11 @@ Connector/fill visuals:
 - `resetViewport(): void` (fit x + reset y auto-scale)
 - `setDoubleClickEnabled(enabled: boolean): void`
 - `setDoubleClickAction(action: "reset" | "placeLimitOrder"): void`
+- `registerIndicator(plugin: IndicatorPlugin): void`
+- `unregisterIndicator(type: string): void`
+- `addIndicator(type: string, inputs?: Record<string, unknown>, options?: Partial<IndicatorInstanceOptions>): string`
+- `updateIndicator(id: string, patch: Partial<IndicatorInstanceOptions>): void`
+- `removeIndicator(id: string): void`
+- `setIndicators(indicators: IndicatorInstanceOptions[]): void`
 - `resize(width?: number, height?: number): void`
 - `destroy(): void`

package/docs/RECIPES.md

@@ -91,6 +91,67 @@ const chart = createChart(root, {
 });
 ```
 
+## Add built-in indicators
+
+```ts
+const emaId = chart.addIndicator("ema", { length: 34, source: "close" });
+const rsiId = chart.addIndicator("rsi", { length: 14 }, { pane: "separate", paneHeightRatio: 0.18 });
+const volumeId = chart.addIndicator("volume", { upOpacity: 0.72, downOpacity: 0.72 });
+```
+
+Available built-ins:
+
+- `volume`, `sma`, `ema`, `rsi`, `wma`, `vwma`, `rma`, `hma`, `stddev`, `atr`
+
+## Resize indicator pane from frontend
+
+Use `paneHeightRatio` so your app can wire a drag handle or slider:
+
+```ts
+const volumeId = chart.addIndicator("volume", {}, { paneHeightRatio: 0.2 });
+
+// e.g. on slider/drag updates:
+chart.updateIndicator(volumeId, { paneHeightRatio: 0.1 });
+```
+
+Recommended range:
+
+- `0.08` to `0.45` (library clamps to safe bounds)
+
+## Remove or hide indicators
+
+```ts
+const id = chart.addIndicator("ema", { length: 21 });
+chart.updateIndicator(id, { visible: false }); // hide
+chart.removeIndicator(id); // remove
+```
+
+## Volume and VWMA data requirement
+
+`volume` and `vwma` use `OhlcDataPoint.v`. If `v` is missing, output can be empty/limited.
+
+```ts
+const data = [
+  { t: "2026-01-01T00:00:00Z", o: 100, h: 103, l: 99, c: 102, v: 125000 }
+];
+chart.setData(data);
+```
+
+## Register a custom indicator plugin
+
+```ts
+chart.registerIndicator({
+  id: "my-overlay-line",
+  name: "My Overlay Line",
+  pane: "overlay",
+  defaultInputs: { color: "#22d3ee", width: 2 },
+  draw: (ctx, rc, inputs) => {
+    if (!rc.yFromPrice) return;
+    // draw custom line with rc.xFromIndex + rc.yFromPrice
+  }
+});
+```
+
 ## Add a draggable pending limit line
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hyperprop-charting-library",
-  "version": "0.1.20",
+  "version": "0.1.22",
   "description": "Lightweight TypeScript charting core",
   "type": "module",
   "main": "./dist/hyperprop-charting-library.cjs",