hyperprop-charting-library 0.1.139 → 0.1.140

package/docs/API.md

@@ -568,6 +568,8 @@ 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"`)
@@ -611,6 +613,59 @@ 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

package/package.json

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