acttrader-charts 1.0.21 → 1.1.0-beta.6

package/README.md

@@ -1,4 +1,4 @@
-# acttrader-charts
+# ActCharts
 
 A performant, zero-dependency stock charting library built on Canvas 2D.
 Dual ESM/CJS output, TypeScript-first.
@@ -84,6 +84,35 @@ chart.removeIndicator('SMA');
 
 Indicator pills appear inline above the chart (up to 2 visible; beyond that collapses into a dropdown).
 
+#### Multiple instances of the same study
+
+Parameterized studies support **multiple simultaneous instances** — e.g. EMA-20, EMA-50 and
+EMA-200, or RSI-14 alongside RSI-7. Each instance gets an auto-cycled color so they're visually
+distinct, and oscillators (RSI, MACD, …) each render in their own stacked sub-pane.
+
+```ts
+chart.addIndicatorByName('EMA');                 // EMA-20 (default)
+chart.addIndicatorByName('EMA');                 // a 2nd EMA, different color
+// or build instances directly with different params:
+chart.addIndicator(new EMA(50, '#22c55e'));
+chart.addIndicator(new EMA(200, '#ef4444'));
+```
+
+Selecting an already-active study in the Studies dropdown **adds another instance**. Remove a
+specific instance via its pill **×** or the settings dialog's Remove button.
+
+Each instance has a unique `instanceId` (e.g. `"EMA#3"`). Listen for it via the `indicatorAdded`
+event and pass it to `removeIndicator` to target one instance:
+
+```ts
+chart.on('indicatorAdded', ({ instanceId, shortName, params }) => { /* track it */ });
+chart.removeIndicator('EMA#3');   // remove that one instance
+chart.removeIndicator('EMA');     // (back-compat) remove ALL EMA instances
+```
+
+A handful of studies remain **single-instance** (re-selecting toggles them off): `VOL`, `OBV`,
+`A/D`, `AO`, `VWAP`, `Ichimoku`, `PSAR`, `Pivot`, and Heikin-Ashi.
+
 ### Drawing Tools
 
 ```ts
@@ -115,6 +144,50 @@ To push ticks directly without an adapter (e.g. from your own WebSocket handler)
 chart.pushTick({ time: Date.now(), bid: 1.2055, ask: 1.2057, volume: 120 });
 ```
 
+### Compare symbols
+
+Overlay one or more comparison instruments on the main chart, normalized to
+percent change from the leftmost visible bar — TradingView-style. Compares are
+historical-only (no live streaming) and persist across primary symbol /
+timeframe switches; the library refetches them automatically against the new
+primary range whenever the chart's range changes.
+
+```ts
+const chart = new ChartEngine({
+    container: document.getElementById('chart')!,
+    symbol: 'AAPL',
+    isins: ['AAPL', 'MSFT', 'GOOG', 'SPY', 'NVDA'],
+    headerLayout: 'advanced',          // Compare button lives in this toolbar
+    initialCompares: ['SPY'],          // optional — added on first dataLoaded
+    maxCompares: 8,                    // optional — default 8
+    compareDataLoader: async ({ symbol, start, end, interval }) => {
+        const res = await fetch(
+            `/api/bars?symbol=${symbol}&interval=${interval}` +
+            `&start=${start.toISOString()}&end=${end.toISOString()}`
+        );
+        return res.json();             // OHLCVBar[]
+    },
+    dataLoader: async (params) => fetchBars('AAPL', params),
+});
+
+// Programmatic API
+await chart.addCompare('MSFT');
+chart.removeCompare('MSFT');
+chart.clearCompares();
+chart.getCompares(); // [{ symbol, color, status }]
+
+// Events
+chart.on('compareAdded',   ({ symbol, color }) => console.log('+', symbol));
+chart.on('compareRemoved', ({ symbol })        => console.log('-', symbol));
+chart.on('compareError',   ({ symbol, message }) => console.warn(symbol, message));
+```
+
+When any compare is active the Y-axis switches to percent (`+12.34%` /
+`-5.67%`); removing every compare returns it to absolute-price labels.
+The Compare button in the advanced toolbar opens an in-chart picker filtered
+by `isins` (with the primary symbol and active compares hidden). To keep the
+old consumer-owned flow, omit `compareDataLoader` and wire `onCompareClick`.
+
 ### Trade From Chart (TFC) — `setLevels`
 
 TFC renders draggable price levels for open positions and pending orders.
@@ -252,6 +325,7 @@ When `enableTrading` is on and live BID/ASK data is streaming, hovering / activa
 | `series` | | `"candlestick"` | Initial chart type |
 | `showVolume` | | `true` | Show volume overlay |
 | `showUI` | | `true` | Render top / bottom / left bars. When `false`, the loading overlay is also suppressed (mobile wrappers provide their own) |
+| `hideHeader` | | `false` | Hide only the chart header (TopBar / AdvancedToolbar / CompactToolbar, per `headerLayout`). Bottom bar, left drawing tools, and on-canvas overlays remain on their own flags. Drive the chart from your own UI via `setTimeframe(tf)`, `setSeries(type)`, `addIndicatorByName(name)`, `removeIndicator(name)` |
 | `showDrawingTools` | | `true` | Show drawing toolbar and pencil button |
 | `showFullscreenButton` | | `true` | Show the fullscreen toggle button in the top bar. Set to `false` to hide it entirely. Mobile wrappers (Android / iOS) default this to `false` |
 | `timeframe` | | `"1D"` | Initial timeframe |
@@ -274,23 +348,30 @@ When `enableTrading` is on and live BID/ASK data is streaming, hovering / activa
 | `targetCandleWidth` | | `10` | Target px width per candle for auto-calculating initial bar count |
 | `durationTimeframeMap` | | *(see below)* | Override duration → timeframe pairings |
 | `dataLoader` | | — | `(params) => Promise<OHLCVBar[]>` auto-called on load / change |
+| `compareDataLoader` | | — | `({ symbol, start, end, interval }) => Promise<OHLCVBar[]>` — fetches bars for a compare symbol. Set this to enable the library-owned Compare flow. |
+| `initialCompares` | | — | Symbols to auto-add as compares once the initial primary range is loaded |
+| `maxCompares` | | `8` | Maximum concurrent compare symbols. Adding beyond emits `compareError` |
 | `themeOverrides` | | — | Deep-partial color overrides applied on top of the built-in dark/light themes |
 | `uiConfig` | | `DEFAULT_UI_CONFIG` | Deep-partial size / font overrides per component |
 | `labels` | | `DEFAULT_LABELS` | Deep-partial string overrides for i18n/translation |
 | `tickClosePriceSource` | | `"bid"` | Which quote side drives live tick close/high/low (`"bid"` or `"ask"`) |
 | `showBidAskLines` | | `false` | Show both bid and ask as dashed lines during a live stream |
 | `showActLogo` | | `false` | Show the ACT watermark logo in the bottom-left corner |
-| `showCandleCountdown` | | `true` | Show countdown timer on the live candle |
+| `showCandleCountdown` | | `true` | Show countdown timer on the live candle (time axis) |
 | `candleCountdownTimeframes` | | intraday only | Timeframes where the countdown appears; `'all'` or `Timeframe[]` |
+| `showPriceAxisCountdown` | | `false` | Show candle countdown timer on the right price axis, just below the live price tag. Honours `candleCountdownTimeframes`. Toggleable from the Settings dialog (Appearance tab). |
 | `maxSubPanes` | | `3` | Max simultaneous oscillator sub-panes |
 | `tradeDisplayFilter` | | `"all"` | Which TFC levels are visible: `"all"` · `"positions"` · `"orders"` · `"none"` |
 | `positionRenderStyle` | | auto | Force position render style: `"line"` or `"dot"` |
 | `hideLevelConfirmCancel` | | `false` | Hide on-canvas ✓/✗ confirm-cancel buttons for TFC level edits |
+| `deselectActiveOnOutsideClick` | | `false` | When `true`, clicking/tapping anywhere outside a selected trade level dismisses it (reverting any pending edits, mirroring ✗ Cancel). Default `false` keeps the level active so incidental clicks — price-axis resize, taps outside the QTY input — don't drop an in-progress edit. The level can still be dismissed via ✓/✗, tapping the level again, or `setLevels()` removing it |
+| `showTradeLevelsAlways` | | `false` | Always render SL/TP bracket lines + price pills, even when the parent level is not hovered or selected. The close (×) button stays hover-only so the chart isn't cluttered. Toggleable from the Settings dialog (Trading tab). Persisted in `localStorage`. |
 | `tradeLevelButtonScale` | | `1` | Multiplier for trade-level Confirm/Cancel/Edit/Close button radii and gaps. Scales visuals **and** hit/drag areas together — raise it on touch devices for larger tap targets. Clamped to `[1, 3]`. Also settable at runtime via `chart.setTradeLevelButtonScale(scale)` |
 | `tfcEnabled` | | `true` | Enable the TFC toggle button in the top bar. When `false`, TFC is completely disabled — the toggle button is hidden and all trade levels, draft orders, and the floating trade button are suppressed |
 | `levelClusteringEnabled` | | `true` | Enable trade-level fan-out clustering; overlapping levels group into expandable badges |
 | `clusterThresholdDistance` | | `20` | Pixel proximity threshold for clustering (only when `levelClusteringEnabled` is `true`) |
-| `hideSymbolAndTick` | | `false` | Hide the symbol name, OHLC strip, and tick-activity dot overlay |
+| `hideSymbolAndTick` | | `false` | Hide the symbol name and tick-activity (streaming) dot in the top-left overlay. Does **not** affect the OHLC(V) strip — use `hideOHLCV` for that |
+| `hideOHLCV` | | `false` | Hide the OHLC(V) data strip (`O: H: L: C: V:`) in the top-left overlay. Independent of `hideSymbolAndTick` — set both to `true` to hide the entire overlay |
 | `showBottomBar` | | `false` | Show the bottom duration-selector bar |
 | `hideQtyButton` | | `false` | Hide the floating Qty input overlay on draft orders |
 | `showQuantityField` | | `false` | Render an editable QTY pill at the left of the draft order info box. Clicking the pill opens a flyout input to edit the quantity before submitting |
@@ -551,10 +632,16 @@ chart.setVolume(show: boolean): this
 ### Indicators
 
 ```ts
-chart.addIndicator(indicator: IIndicator): this
-chart.removeIndicator(name: string): this
+chart.addIndicator(indicator: IIndicator, initialParams?: IndicatorParams): this
+chart.addIndicatorByName(shortName: string, params?: IndicatorParams): void
+chart.removeIndicator(idOrShortName: string): this
 ```
 
+- `addIndicator` / `addIndicatorByName` — add a study. Multi-instance studies add a new instance
+  per call (auto-cycled color); single-instance studies toggle. `params` overrides period/color/source.
+- `removeIndicator` — pass an `instanceId` (e.g. `"EMA#3"`, from the `indicatorAdded` event) to remove
+  that one instance, or a `shortName` (e.g. `"EMA"`) to remove **all** instances of that type.
+
 ### Drawing Tools
 
 ```ts
@@ -782,6 +869,8 @@ chart.on('seriesChange',   ({ series }) => {});
 chart.on('streamStatus',   ({ status }) => {}); // 'connected' | 'reconnecting' | 'disconnected'
 chart.on('dataLoaded',     ({ timeframe, interval, start, end }) => {});
 chart.on('newBar',         ({ completedBar, openingBar, intervalMs }) => {});
+chart.on('indicatorAdded',   ({ instanceId, shortName, params }) => {}); // a study instance was added — keep instanceId to remove it later
+chart.on('indicatorRemoved', ({ instanceId, shortName }) => {});
 chart.on('stateChange',    ({ symbol, state }) => {
     // Fires after every user-driven config change (timeframe, series, theme,
     // indicators, drawings, volume). `state` is a full serializable snapshot.
@@ -813,6 +902,135 @@ chart.on('tradeLevelBracketActivated', ({ label, bracketType, price, isFullscree
 
 ---
 
+## Multi-Pane Layouts
+
+The library ships everything you need to put multiple synchronised `ChartEngine`s on one screen — preset definitions, a layout-picker popover, cross-pane sync, and a composite snapshot helper. The library *emits intent*; the host renders the grid.
+
+### Enabling the layout & snapshot UI
+
+Pass two flags to `ChartConfig` (and optionally pick a header variant):
+
+```ts
+const chart = new ChartEngine({
+    container,
+    headerLayout:          'advanced',  // 'simple' (default) | 'advanced' | 'compact'
+    enableMultipleLayouts: true,        // shows Layout button + 26 preset picker
+    enableSnapshot:        true,        // shows Snapshot button + Download/Copy popover
+    layoutSync:            { symbol: false, interval: true }, // optional — seed the popover's sync toggles
+});
+
+chart.on('layoutChange', ({ presetId, preset, sync }) => {
+    // Mount / teardown panes to match preset.count
+    // Apply sync flags to your ChartGroup
+});
+
+chart.on('snapshot', ({ dataUrl, action }) => {
+    // Native wrappers can intercept here to save via platform APIs
+});
+```
+
+### Seeding & restoring the popover's sync toggles
+
+The layout popover's five sync toggles (`symbol` / `interval` / `crosshair` / `time` / `dateRange`) default to `DEFAULT_LAYOUT_SYNC`. To open the popover in a different state — e.g. restoring a user's saved preference — pass a **partial** `layoutSync` at construction (omitted keys keep their `DEFAULT_LAYOUT_SYNC` value):
+
+```ts
+const chart = new ChartEngine({
+    container,
+    enableMultipleLayouts: true,
+    layoutSync: savedSync ?? { symbol: false, interval: false, crosshair: false, time: false, dateRange: false },
+});
+```
+
+To change the toggles on an **already-mounted** chart (e.g. mirroring a host-owned settings UI), call `setLayoutSync()`:
+
+```ts
+chart.setLayoutSync({ crosshair: true });        // partial — other toggles unchanged
+const current = chart.getLayoutSync();           // read the current state
+```
+
+`setLayoutSync()` updates the popover's toggles in place and — unlike a user click inside the popover — does **not** emit a `layoutChange` event, so a host can call it in response to its own state without re-entrancy. It no-ops when the resolved state is unchanged.
+
+### `ChartGroup` — cross-pane sync
+
+`ChartGroup` listens to events on the *active* engine and mirrors them to the others:
+
+| Sync flag    | Source event       | Action on other panes
+| ------------ | ------------------ | ----------------------------------------
+| `interval`   | `timeframeChange`  | `setTimeframe` (skip if equal)
+| `crosshair`  | `crosshair`        | `timeToBarIndex` → `setCrosshair`
+| `time`       | `pan`              | `setViewport({ startIndex, endIndex })`
+| `dateRange`  | `zoom`             | `setViewport({ startIndex, endIndex })`
+| `symbol`     | push (`broadcastSymbol`) | `setSymbol` (host still fetches data)
+
+```ts
+import { ChartGroup, DEFAULT_LAYOUT_SYNC } from 'acttrader-charts';
+
+const group = new ChartGroup({ sync: DEFAULT_LAYOUT_SYNC });
+group.add('p1', engineA);
+group.add('p2', engineB);
+group.setActive('p1');
+
+// react to user picking a preset
+chart.on('layoutChange', ({ sync }) => group.setSync(sync));
+
+// user picked a new symbol on the active pane
+group.broadcastSymbol('AAPL', 'p1');
+```
+
+`ChartEngine.setViewport` / `setCrosshair` deliberately do **not** re-emit `pan` / `zoom` / `crosshair`, so the mirror is safe from feedback loops.
+
+### Custom layout presets
+
+Register an extra preset alongside the 26 built-ins; it appears in the picker automatically:
+
+```ts
+import { registerCustomPreset } from 'acttrader-charts';
+
+registerCustomPreset({
+    id:    'my-3-wide-left',
+    count: 3,
+    cols:  '2fr 1fr',
+    rows:  '1fr 1fr',
+    areas: '"a b" "a c"',
+    areaOrder: ['a', 'b', 'c'],
+    icon:  '<svg>…</svg>',
+});
+```
+
+Persistence is the host's job — serialise the preset to your store, call `registerCustomPreset` again on app boot.
+
+### Composite snapshot of a multi-pane grid
+
+`SnapshotPopover` captures the single active chart. For a whole-grid PNG, hand the cell rectangles to the group:
+
+```ts
+const containerRect = gridEl.getBoundingClientRect();
+const rects = paneIds.map(id => {
+    const cell = cellEls.get(id)!.getBoundingClientRect();
+    return {
+        paneId: id,
+        x: cell.left - containerRect.left,
+        y: cell.top  - containerRect.top,
+        w: cell.width,
+        h: cell.height,
+    };
+});
+
+const dataUrl = group.toCompositeDataUrl({
+    width:  containerRect.width,
+    height: containerRect.height,
+    rects,
+});
+```
+
+The composite excludes trade levels (positions, SL/TP) — same rule as `chart.toDataUrl()`.
+
+### Native wrapper parity
+
+`enableMultipleLayouts`, `enableSnapshot`, `headerLayout`, the `layoutChange` event, and the `snapshot` event are all exposed by [charts-android](../charts-android) and [charts-ios](../charts-ios) — see their READMEs for native usage.
+
+---
+
 ## Custom Indicator
 
 Implement `IIndicator` and pass it to `addIndicator()`: