@tradecanvas/chart 0.4.0 → 0.6.0

package/README.md

@@ -8,7 +8,7 @@ High-performance canvas trading chart with built-in indicators, drawing tools, a
 
 Most chart libraries make you choose: pretty charts with no trading features, or trading features with an ugly API. TradeCanvas gives you both.
 
-- **20+ built-in indicators** — MA, EMA, RSI, MACD, Bollinger, Ichimoku, and more. No separate calculation library needed.
+- **33+ built-in indicators** — MA, EMA, Hull MA, RSI, MACD, Bollinger, Ichimoku, Pivot Points, Anchored VWAP, ZigZag, Linear Regression Channel, Awesome / Chaikin Oscillator, and more. No separate calculation library needed.
 - **10+ drawing tools** — Trendlines, Fibonacci retracement, horizontal/vertical lines, rectangles, channels, Elliott waves, Gann fans. With undo/redo.
 - **Trading overlay** — Render open positions with entry line, P&L zone, and SL/TP markers. Orders as dashed lines. Users can drag SL/TP to modify.
 - **Real-time streaming** — Built-in Binance adapter. Plug in your own data source with the adapter interface.
@@ -55,6 +55,55 @@ chart.connect({
 
 That's it. A full-featured trading chart with live data in 15 lines.
 
+## Widget (Complete UI)
+
+For a complete TradingView-like experience with built-in toolbar, drawing tools, and settings — no UI code needed:
+
+```typescript
+import { ChartWidget } from '@tradecanvas/chart/widget'
+import { BinanceAdapter } from '@tradecanvas/chart'
+
+const widget = new ChartWidget(document.getElementById('chart')!, {
+  symbol: 'BTCUSDT',
+  timeframe: '5m',
+  adapter: new BinanceAdapter(),
+  theme: 'dark',
+})
+```
+
+That's it. Full toolbar, drawing sidebar, settings modal, and status bar — all included.
+
+### Widget Options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `symbol` | `string` | `'BTCUSDT'` | Initial trading symbol |
+| `timeframe` | `TimeFrame` | `'5m'` | Initial timeframe |
+| `theme` | `'dark' \| 'light' \| Theme` | `'dark'` | Chart theme |
+| `adapter` | `DataAdapter` | — | Data source adapter |
+| `toolbar` | `boolean` | `true` | Show top toolbar |
+| `drawingTools` | `boolean` | `true` | Show left drawing sidebar |
+| `settings` | `boolean` | `true` | Show settings button |
+| `trading` | `boolean` | `true` | Enable trading overlay |
+| `statusBar` | `boolean` | `true` | Show bottom status bar |
+| `symbols` | `string[]` | BTC/ETH/SOL/BNB | Available symbols |
+| `timeframes` | `TimeFrame[]` | 1m to 1d | Available timeframes |
+| `chartTypes` | `ChartType[]` | 7 types | Available chart types |
+| `onSymbolChange` | `(symbol) => void` | — | Symbol change callback |
+| `onTimeframeChange` | `(tf) => void` | — | Timeframe change callback |
+| `onReady` | `(chart) => void` | — | Fired when chart is ready |
+
+### Widget vs Headless
+
+| | `Chart` (headless) | `ChartWidget` |
+|---|---|---|
+| Import | `@tradecanvas/chart` | `@tradecanvas/chart/widget` |
+| UI included | None — build your own | Complete toolbar, sidebar, settings |
+| Bundle impact | ~50 KB gzip | ~65 KB gzip (includes UI) |
+| Framework | Any (React, Vue, Svelte, vanilla) | Vanilla JS DOM (works everywhere) |
+| Customization | Full control | Toggle sections on/off |
+| Advanced access | Direct API | `widget.getChart()` for direct API |
+
 ## Features
 
 ### Chart Types
@@ -72,6 +121,7 @@ That's it. A full-featured trading chart with live data in 15 lines.
 | Kagi | Reversal-based line chart |
 | Point & Figure | X/O columns for supply/demand analysis |
 | Line Break | Three-line break charts |
+| Range Bars | Fixed price-range bars — each bar's high − low equals a configured range |
 
 ### Finance Charts
 
@@ -126,10 +176,12 @@ gauge.setValue(85) // animates smoothly
 ### Indicators (built-in)
 
 **Overlay** (drawn on the price chart):
-SMA, EMA, Bollinger Bands, Keltner Channel, Donchian Channel, Ichimoku Cloud, Parabolic SAR, Supertrend, VWAP
+SMA, EMA, Hull MA, Bollinger Bands, Keltner Channel, Donchian Channel, Ichimoku Cloud, Parabolic SAR, Supertrend, VWAP, Anchored VWAP, Pivot Points (Classic), ZigZag, Linear Regression Channel
 
 **Panel** (separate sub-chart):
-RSI, MACD, Stochastic, ATR, ADX, CCI, CMF, MFI, OBV, ROC, TSI, Williams %R, Volume Profile, VROC, Standard Deviation, Accumulation/Distribution, Aroon
+RSI, MACD, Stochastic, ATR, ADX, CCI, CMF, MFI, OBV, ROC, TSI, Williams %R, Awesome Oscillator, Chaikin Oscillator, Volume Profile, VROC, Standard Deviation, Accumulation/Distribution, Aroon
+
+All indicator parameters are validated at runtime — invalid values (NaN, Infinity, non-numeric strings, missing keys) fall back to documented defaults instead of silently propagating to calculations.
 
 ### Drawing Tools
 
@@ -153,6 +205,7 @@ chart.setPositions([{
   side: 'buy',
   entryPrice: 3500,
   quantity: 1.5,
+  closedQuantity: 0.5,   // partial close — visualized as a left-edge dim band
   stopLoss: 3400,
   takeProfit: 3700,
 }])
@@ -167,6 +220,18 @@ chart.setOrders([{
   draggable: true,
 }])
 
+// Customize the position zone color via P&L thresholds
+chart.setTradingConfig({
+  pnlThresholds: [
+    { pnl: -Infinity, color: '#b91c1c' },
+    { pnl: 0,         color: '#94a3b8' },
+    { pnl: 50,        color: '#16a34a' },
+    { pnl: 200,       color: '#15803d' },
+  ],
+  // Custom label template — tokens: {side} {qty} {openQty} {closedQty} {entry} {price} {pnl} {pnlPct} {pnlSign}
+  positionLabel: '{side} {openQty}/{qty} @ {entry} | {pnlSign}{pnl} ({pnlPct})',
+})
+
 // Listen for user drag-to-modify
 chart.on('positionModify', (e) => console.log('SL/TP moved:', e.payload))
 chart.on('orderModify', (e) => console.log('Order moved:', e.payload))
@@ -190,6 +255,43 @@ chart.updateLastBar(updatedBar)
 chart.setCurrentPrice(3500.42)
 ```
 
+### Web Worker indicator pipeline
+
+Heavy charts (1,000+ bars × 10+ indicators) can stutter when `calculate()` runs on the main thread. `IndicatorWorkerHost` offloads calculation to a worker so the render loop stays smooth.
+
+```typescript
+import { IndicatorWorkerHost } from '@tradecanvas/core'
+
+// Bundler-supported worker URL (Vite, webpack 5, esbuild, etc.)
+const worker = new Worker(
+  new URL('@tradecanvas/core/dist/indicator.worker.js', import.meta.url),
+  { type: 'module' },
+)
+const host = new IndicatorWorkerHost(worker, { timeoutMs: 30_000 })
+
+const output = await host.calculate(
+  'rsi',
+  { id: 'rsi', instanceId: 'rsi-1', params: { period: 14 } },
+  bars,
+)
+
+// Health check / cleanup
+await host.ping()
+host.terminate()
+```
+
+No worker available (SSR, tests, or as a safety net)? Pass `null` and register fallback plugins for synchronous calculation:
+
+```typescript
+import { IndicatorWorkerHost, RSIIndicator } from '@tradecanvas/core'
+
+const host = new IndicatorWorkerHost(null)
+host.registerFallbackPlugin(new RSIIndicator())
+const output = await host.calculate('rsi', config, bars)  // runs synchronously
+```
+
+Render still happens on the main thread (it needs `CanvasRenderingContext2D`). Only the heavy compute moves off-thread.
+
 ### Save / Load
 
 ```typescript
@@ -206,8 +308,12 @@ await chart.loadStateFromFile()
 ### Themes
 
 ```typescript
-import { DARK_THEME, LIGHT_THEME } from '@tradecanvas/chart'
+import { DARK_THEME, LIGHT_THEME, DARK_TERMINAL } from '@tradecanvas/chart'
+
+// Built-in presets: DARK_THEME, LIGHT_THEME, DARK_TERMINAL
+chart.setTheme(DARK_TERMINAL)  // fintech terminal: #0E0E0E bg, #00FF87/#FF3B4D candles, monospace
 
+// Or customize any preset
 chart.setTheme({
   ...DARK_THEME,
   candleUp: '#26A69A',
@@ -241,9 +347,9 @@ const { current, total, percent } = chart.getReplayProgress()
 
 | Feature | @tradecanvas/chart | lightweight-charts | chart.js | Highcharts Stock |
 |---|---|---|---|---|
-| Chart types | 11 + 4 finance | 4 | 8 (non-financial) | 10+ |
-| Finance charts | Sparkline, Depth, Equity, Heatmap | None | None | Some |
-| Built-in indicators | 20+ | 0 | 0 | ~30 |
+| Chart types | 12 + 6 finance | 4 | 8 (non-financial) | 10+ |
+| Finance charts | Sparkline, Depth, Equity, Heatmap, Waterfall, Gauge | None | None | Some |
+| Built-in indicators | 33+ | 0 | 0 | ~30 |
 | Drawing tools | 23 | 0 | 0 | Some |
 | Trading overlay | Full (pos + orders + drag) | None | None | None |
 | Real-time streaming | Built-in (Binance) | Manual | Manual | Built-in |
@@ -252,6 +358,7 @@ const { current, total, percent } = chart.getReplayProgress()
 | Multi-panel | Yes | No | No | Yes |
 | Bundle (gzip) | ~50 KB | ~45 KB | ~70 KB | ~200 KB |
 | Dependencies | 0 | 1 | 0 | 0 |
+| Widget (complete UI) | Yes (`ChartWidget`) | No | No | No |
 | License | MIT | Apache 2.0 | MIT | Commercial |
 
 ## API Overview
@@ -279,11 +386,15 @@ chart.setNumberLocale('de-DE')  // 65.234,00
 |---|---|
 | `setData(bars)` | Load historical OHLCV data |
 | `appendBar(bar)` | Append a new candle |
+| `appendBars(bars)` | Bulk append (reconnect catch-up) |
 | `updateLastBar(bar)` | Update the in-progress candle |
-| `setCurrentPrice(price)` | Show a live price line |
+| `setCurrentPrice(price, pulseColor?)` | Show a live price line |
 | `connect(config)` | Connect to a real-time data source |
+| `setTimeframe(tf)` | Switch timeframe on active stream |
 | `setChartType(type)` | Switch chart type |
-| `setTheme(theme)` | Apply a theme |
+| `setTheme(theme)` | Apply a theme (DARK_THEME, LIGHT_THEME, DARK_TERMINAL) |
+| `setNumberLocale(locale)` | Set number format locale (en-US, de-DE, vi-VN) |
+| `setStatusText(text)` | Show status in legend area ("LIVE · 8ms") |
 | `addIndicator(id, params?)` | Add a technical indicator |
 | `removeIndicator(instanceId)` | Remove an indicator |
 | `setDrawingTool(tool)` | Activate a drawing tool |