hyperprop-charting-library 0.1.137 → 0.1.139

package/docs/API.md

@@ -557,12 +557,18 @@ an up measurement, red for down.
 - `fitContent(): void` (x-only fit, keeps y zoom)
 - `resetViewport(): void` (fit x + reset y auto-scale)
 - `setSelectedDrawing(id: string | null): void` (marks a drawing selected; only the selected/drafted drawing renders its handles, and position tools render their lines/labels only while selected)
+- `onSelectionChange(handler: ((event: DrawingSelectionChangeEvent | null) => void) | null): void` — selection geometry stream for a floating toolbar; see "Context menus, selection toolbars and keyboard" below
+- `getSelectedDrawing(): { drawing: DrawingObjectOptions; bounds: DrawingBounds } | null`
+- `onContextMenu(handler: ((event: ChartContextMenuEvent) => void) | null): void` — typed right-click with region + hit info
+- `onKeyboardShortcut(handler: ((event: ChartKeyboardShortcutEvent) => void) | null): void`
+- `focus(): void` — focus the canvas so keyboard shortcuts apply
 - `onDrawingDoubleClick(handler): void` (fires when a drawing is double-clicked; use it to open a settings dialog, e.g. for position tools)
 - `onDrawingEditText(handler): void` (fires when a `text`/`note`/`callout` tool is placed or double-clicked; use it to show an inline text editor at `{x, y}` and write the result back via `updateDrawing(id, { label })`). These drawings store their content in `label` and size in `fontSize`.
 - `setTradeMarkers(markers: TradeMarkerOptions[]): void` — draw trade execution markers (arrow + `qty @ price` label) on the candle of each fill's `time`. Buy = arrow below the low pointing up; sell = arrow above the high pointing down. Each marker: `{ time (ms|ISO), price, side: "buy"|"sell", qty?, text?, color?, textColor? }` (defaults: buy `#2962ff`, sell `#f23645`, text `#d1d4dc`). Markers resolve to bars by time, so they persist across timeframe switches and scrolling. Pass `[]` to clear.
 - `cancelDrawing(): boolean` — abort an in-progress multi-click drawing (between the first click and the final point, e.g. a half-drawn trendline/ray/fib). Returns `true` if a draft was cancelled. Wire it to Escape.
 - Hold **Shift** while drawing or dragging an endpoint of a `trendline`/`ray`/`arrow` to constrain it to the nearest 0/45/90° angle (e.g. a perfectly horizontal line).
 - `setMagnetMode(mode): void` / `getMagnetMode()` — magnet/snap for all drawing tools. `"none"` off, `"weak"` snaps to a candle's OHLC only when the cursor is near a value, `"strong"` always snaps to the nearest OHLC of the bar under the cursor. Holding Cmd/Ctrl while drawing/dragging forces strong snapping regardless of the mode.
+- `setCompareSeries(series: CompareSeriesOptions[]): void` / `addCompareSeries(series)` / `removeCompareSeries(id)` / `getCompareSeries()` — overlay other instruments on the main pane; see "Compare overlays" below
 - `setPriceScale(options: { mode?: "linear" | "log" | "percent"; inverted?: boolean }): void` / `getPriceScale()` — price-scale modes for the main pane (TradingView-style). `"log"` maps prices through log10 (wide ranges get 1/2/5-per-decade axis marks). `"percent"` keeps the linear mapping but relabels the axis (ticks, last-price/PDC/H/L/bid/ask tags and the crosshair) as % change from the first visible bar's close, updating as you pan. `inverted: true` flips the axis top-to-bottom. All viewport state stays in plain price space, so switching modes never moves your zoom, and drawings/orders/indicators follow automatically. Indicator panes keep their own scales. Included in `saveState()` as `priceScale`.
 - `setActiveDrawingTool(tool: DrawingToolType | null): void` (`DrawingToolType` = `"horizontal-line" | "vertical-line" | "trendline" | "ray" | "fib-retracement" | "fib-extension" | "long-position" | "short-position" | "price-range" | "rectangle" | "text" | "note" | "parallel-channel" | "ellipse" | "arrow" | "brush" | "callout" | "measure"`)
 - `getActiveDrawingTool(): DrawingToolType | null`
@@ -605,6 +611,151 @@ link.click();
 
 ---
 
+## Compare overlays (multi-series)
+
+Overlay other instruments on the main pane. The host owns the data (it already
+has a datafeed); the chart aligns each series to the main bars by timestamp and
+draws it.
+
+```ts
+chart.setCompareSeries([
+  { id: "NQ", label: "NQ1!", data: nqBars, color: "#22d3ee" },
+  { id: "BTC", label: "BTCUSD", data: btcBars, color: "#a855f7", style: "area" },
+]);
+```
+
+- **Alignment** is by timestamp, computed once per data change (a merge walk,
+  not a search per bar), so different session hours and holidays are fine — the
+  last known value carries forward across gaps, and bars before a compared
+  instrument starts are simply not drawn.
+- **`scale`** defaults to `"percent"`: both instruments are normalised to their
+  first visible bar, so a $180 index and a $60,000 coin can be compared by
+  shape. It re-anchors as you pan, exactly like TradingView. Use `"price"` to
+  plot raw values on the main scale (only sensible for related instruments).
+- **Autoscale** includes compare series unless `includeInAutoScale: false`.
+- Each series gets a colored tag in the price gutter showing its own % move
+  (or value in price mode); tags stack instead of overlapping, and drop the
+  label when the gutter is too narrow.
+- Compare data is **not** in `saveState()` — it can be megabytes and the host
+  re-fetches it anyway. Persist the symbol list yourself and re-supply data on
+  load.
+
+## Deep zoom-out (viewport downsampling)
+
+Once bars are narrower than `downsampling.thresholdPx` (default 1.5px), several
+bars share a pixel column, and drawing each one separately is wasted work. The
+chart aggregates each column into one min/max bucket, so path operations scale
+with the chart's width rather than the number of bars. Extremes are preserved
+exactly — a one-bar spike still reaches full height — because the bucket keeps
+the true high and low rather than sampling. Candle and bar styles converge to a
+single colored high-low column (the body is sub-pixel at that density anyway);
+line/area/baseline keep a min/max envelope so the shape of the move survives.
+
+Measured on the playground benchmark (50,000 bars, 120Hz display):
+
+| Scenario | Per-bar (before) | Downsampled |
+| --- | --- | --- |
+| zoom 100 ↔ 20k bars | 21.3ms avg, 49.8ms p95, 47fps, 53 slow frames | 8.3ms avg, 10.3ms p95, 120fps, 0 slow frames |
+| deep zoom-out, 50k bars | 52.7ms avg, 58.8ms p95, 19fps, 240 slow frames | 8.3ms avg, 10.2ms p95, 120fps, 0 slow frames |
+
+Turn it off with `downsampling: { enabled: false }`, or tune when it kicks in
+with `thresholdPx`.
+
+## Context menus, selection toolbars and keyboard
+
+Three pieces of chrome that every host previously rebuilt by hand. The chart
+does the hit-testing and geometry; the host still renders its own menus and
+toolbar, so it keeps full control of styling and framework.
+
+### `onContextMenu(handler)`
+
+Right-click anywhere on the chart. The browser's native menu is always
+suppressed. The event says *what* was under the pointer, so a host switches on
+`region` instead of re-deriving it from coordinates:
+
+```ts
+chart.onContextMenu((event) => {
+  switch (event.region) {
+    case "drawing":
+      // event.drawing / drawingTarget / pointIndex — the chart has already
+      // selected this drawing, exactly like TradingView.
+      showDrawingMenu(event.clientX, event.clientY, event.drawing!);
+      break;
+    case "indicator-pane":
+      showIndicatorMenu(event.clientX, event.clientY, event.indicator!); // { id, type }
+      break;
+    case "y-axis":
+      showPriceScaleMenu(event.clientX, event.clientY); // log / percent / invert
+      break;
+    case "x-axis":
+      showTimeScaleMenu(event.clientX, event.clientY);
+      break;
+    case "plot":
+      showChartMenu(event.clientX, event.clientY, event.price); // + index/time/point
+      break;
+  }
+});
+```
+
+`clientX`/`clientY` are viewport coordinates, ready to position a DOM menu;
+`x`/`y` are canvas-relative. `price`, `index`, `time` and `point` describe the
+bar under the pointer (`price` only in the main pane).
+
+### `onSelectionChange(handler)` — floating drawing toolbar
+
+Fires when a drawing is selected or deselected (payload `null`) **and on every
+frame where the selected drawing's box moves** — drag, resize, pan, zoom. That
+is what lets a host toolbar sit above the shape and track it, instead of
+floating at a fixed corner:
+
+```ts
+chart.onSelectionChange((event) => {
+  if (!event) return hideToolbar();
+  const rect = container.getBoundingClientRect();
+  // Above the shape, flipping below when there's no room.
+  const above = rect.top + event.bounds.top - toolbarHeight - 10;
+  positionToolbar({
+    left: rect.left + event.bounds.centerX - toolbarWidth / 2,
+    top: above > rect.top + 8 ? above : rect.top + event.bounds.bottom + 10,
+  });
+  showToolbarFor(event.drawing);
+});
+```
+
+`bounds` is `{ left, top, right, bottom, centerX, centerY }` in canvas pixels,
+clamped to the plot; `plot` gives the plot rectangle for keeping the toolbar
+inside the chart; `dragging` is true mid-drag (dim or lock the toolbar if you
+prefer it out of the way). `getSelectedDrawing()` returns the same
+`{ drawing, bounds }` on demand, and `DrawingSelectEvent` now carries `bounds`
+too.
+
+### Keyboard shortcuts and accessibility
+
+The canvas is focusable (`tabIndex 0`, `role="application"`, `aria-label`,
+`aria-keyshortcuts`) and takes focus on pointer-down, so shortcuts apply to the
+chart the user is actually using and **never swallow typing in host inputs**.
+The focus ring only shows for keyboard focus.
+
+| Key | Action |
+| --- | --- |
+| `←` / `→` | Pan one bar (`Shift` = 10) |
+| `↑` / `↓` | Pan price by 5% of the visible range (`Shift` = 5×) |
+| `+` / `-` | Zoom in / out |
+| `Delete` / `Backspace` | Delete the selected drawing |
+| `Escape` | Cancel a half-drawn shape, then the armed tool, then the selection |
+| `Home` | Fit all bars |
+| `End` | Scroll to realtime |
+| `R` | Reset the viewport |
+
+Chords with Cmd/Ctrl/Alt are ignored so host and browser shortcuts still work.
+Configure with `keyboard: { enabled, panBars, deleteSelectedDrawing }` and
+`accessibility: { label, description, focusable }` in `ChartOptions`, and
+subscribe to `onKeyboardShortcut(handler)` to mirror actions in your own UI
+(the event includes the removed `drawing` for `"delete-drawing"`, so hosts can
+offer undo). `focus()` puts keyboard focus on the chart programmatically.
+
+---
+
 ## Script Indicators (user-authored)
 
 `compileScriptIndicator(definition: ScriptIndicatorDefinition): IndicatorPlugin` — compiles a

package/package.json

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