hyperprop-charting-library 0.1.138 → 0.1.140

package/docs/API.md

@@ -568,6 +568,9 @@ an up measurement, red for down.
 - `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.
+- `setDatafeed(datafeed: ChartDatafeed | null): Promise<void>` — attach a pull-based data source with lazy history; see "Datafeed" below
+- `onLongPress(handler: ((event: ChartLongPressEvent) => void) | null): void` — touch press-and-hold inspection
+- `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`
@@ -610,6 +613,109 @@ link.click();
 
 ---
 
+## Datafeed (optional, pull-based)
+
+By default the host pushes bars in with `setData`/`upsertBar`. Attach a
+datafeed instead and the chart pulls what it needs — including older history
+as the user scrolls left, which every host otherwise hand-rolls as infinite
+scroll. The shape follows TradingView's datafeed closely enough to port an
+existing adapter.
+
+```ts
+await chart.setDatafeed({
+  onReady: async () => { /* optional, awaited once before the first getBars */ },
+  getBars: async ({ fromMs, toMs, countBack, firstRequest }) => {
+    // countBack is authoritative; fromMs is a hint derived from bar spacing.
+    return fetchBars({ symbol, to: toMs, limit: countBack });
+  },
+  subscribeBars: (onBar) => {
+    const socket = openStream(symbol, onBar);
+    return () => socket.close();     // teardown, called on replace/destroy
+  },
+  onError: (error, request) => report(error, request),
+});
+```
+
+- The chart loads `initialVisibleBars × 3` bars, then calls `subscribeBars` and
+  upserts every streamed bar.
+- **Lazy history**: when the viewport comes within
+  `datafeedOptions.prefetchThresholdBars` (default 150) of the oldest loaded
+  bar, the chart requests the next `chunkBars` (default 1500) and merges them,
+  re-anchoring on time so the view doesn't jump. A `cooldownMs` (default 1200)
+  keeps a fast scroll from stampeding the backend.
+- **Return an empty array to mean "no more history"** — the chart stops asking
+  until a new datafeed is attached.
+- `setData`/`upsertBar` keep working while a datafeed is attached, so hosts can
+  migrate one surface at a time. `setDatafeed(null)` detaches and unsubscribes.
+
+## Touch
+
+Touch input gets its own ergonomics, configured with `touch` in `ChartOptions`:
+
+- **Bigger targets.** Every drawing, handle and pane-divider tolerance is
+  multiplied by `hitToleranceScale` (default 2.2) while the last input was
+  touch or pen, so a line you can grab within 7px with a mouse is grabbable
+  within ~15px with a finger. Mouse precision is untouched, and the mode
+  flips back the moment a mouse moves.
+- **Press-and-hold to inspect.** Holding still on the plot for
+  `longPressMs` (default 400) puts the crosshair on that bar and draws an OHLC
+  tooltip (time, O/H/L/C, change with %, volume) offset clear of the fingertip.
+  The finger then *scrubs* — it moves the reading instead of panning the chart
+  — until it lifts, which clears both. Turn the built-in tooltip off with
+  `longPressTooltip: false`; subscribe with `onLongPress(handler)` to drive
+  your own UI (the event carries the bar, price, index and client coords, and
+  `scrubbing` distinguishes the initial press from the drag that follows).
+
+## 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

package/package.json

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