hyperprop-charting-library 0.1.134 → 0.1.136

package/docs/API.md

@@ -482,11 +482,52 @@ chart.setActiveDrawingTool("fib-retracement"); // first click starts, second cli
 chart.setActiveDrawingTool("fib-extension");   // three clicks: trend start, trend end, projection origin
 chart.setActiveDrawingTool("long-position");   // single click drops a long risk/reward box
 chart.setActiveDrawingTool("short-position");  // single click drops a short risk/reward box
+chart.setActiveDrawingTool("measure");         // next drag (or click-move-click) measures; see below
+chart.setActiveDrawingTool("parallel-channel"); // three clicks: base start, base end, parallel offset
+chart.setActiveDrawingTool("ellipse");         // two clicks: opposite corners of the bounding box
+chart.setActiveDrawingTool("arrow");           // like trendline, with an arrowhead at the second point
+chart.setActiveDrawingTool("brush");           // press and drag to draw freehand; release commits
+chart.setActiveDrawingTool("callout");         // two clicks: anchor tip, then text box (opens text editor)
 chart.setActiveDrawingTool(null);              // back to normal cursor/pan
 ```
 
+New shape/annotation tools:
+
+- `parallel-channel`: three-point channel, TradingView style. The first two
+  clicks set the base trendline; the third click sets the parallel offset.
+  Renders both lines, a dashed centre line, and a translucent fill. Handles:
+  the two base anchors plus a third on the parallel line. The offset is
+  constant in price, so the channel stays parallel at any zoom.
+- `ellipse`: two-anchor bounding-box ellipse, created and resized exactly like
+  `rectangle` (corner handles, including the derived corners).
+- `arrow`: a `trendline` with a filled arrowhead at the second point (head
+  size scales with `width`). Supports the same Shift 0/45/90° constraint.
+- `brush`: freehand polyline. Press and drag to draw; release commits. Points
+  are appended only when the cursor moves ≥3px, and strokes render smoothed
+  with quadratic curves. No reshape handles — drag the stroke body to move it.
+- `callout`: anchored text box. First click drops the anchor (arrow tip),
+  second click places the box, and `onDrawingEditText` fires so the host can
+  show its text editor. Stores content in `label` and size in `fontSize`, like
+  `text`/`note`. The connector line + arrowhead re-route to the box edge
+  nearest the anchor.
+
 Use `getDrawings()` / `setDrawings()` for persistence.
 
+### Measure tool (TradingView-style ruler)
+
+`"measure"` is transient — the only tool that never creates a drawing. Drag
+(or click, move, click) across the plot to get a translucent box with
+direction arrows and a stats pill: signed price change, % move, tick count
+(when `tickSize` is configured), bar count, and wall-clock duration. Blue for
+an up measurement, red for down.
+
+- The overlay stays pinned to its bars/prices through pans and zooms.
+- It clears on the next click, on Escape, on `cancelDrawing()`, or when the
+  active tool changes; it is never emitted through `onDrawingsChange`.
+- After each measurement the chart reverts to the cursor (one-shot, like
+  TradingView) and reports it via `onActiveDrawingToolChange`.
+- Shortcut: **Shift+drag** on the plot measures without arming the tool.
+
 ---
 
 ## `ChartInstance` Methods
@@ -517,13 +558,14 @@ Use `getDrawings()` / `setDrawings()` for persistence.
 - `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)
 - `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` 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 })`). `text`/`note` drawings store their content in `label` and size in `fontSize`.
+- `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` to constrain it to the nearest 0/45/90° angle (e.g. a perfectly horizontal line).
+- 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.
-- `setActiveDrawingTool(tool: DrawingToolType | null): void` (`DrawingToolType` = `"horizontal-line" | "vertical-line" | "trendline" | "ray" | "fib-retracement"`)
+- `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`
+- `onActiveDrawingToolChange(handler: ((tool: DrawingToolType | null) => void) | null): void` — fires whenever the active tool changes, including the chart auto-reverting to the cursor after a tool completes (all tools do this when their shape is placed; `measure` does it after every measurement). Keeps host toolbars in sync without polling.
 - `setDrawings(drawings: DrawingObjectOptions[]): void`
 - `getDrawings(): DrawingObjectOptions[]`
 - `addDrawing(drawing: DrawingObjectOptions): string`
@@ -541,6 +583,22 @@ Use `getDrawings()` / `setDrawings()` for persistence.
 - `updateIndicator(id: string, patch: Partial<IndicatorInstanceOptions>): void`
 - `removeIndicator(id: string): void`
 - `setIndicators(indicators: IndicatorInstanceOptions[]): void`
+- `saveState(): ChartSavedState` — one JSON-serializable snapshot of the full user-visible setup: `{ version: 1, chartType, viewport, drawings, indicators, magnetMode, drawingDefaults }`. Chart *data* is not included; keep feeding bars through `setData`/`upsertBar`.
+- `loadState(state: Partial<ChartSavedState>): void` — restore a `saveState()` blob. Tolerant of partial blobs (missing sections are left untouched), so it doubles as a bulk setter. Register custom script indicator plugins with `registerIndicator` *before* calling it so their instances resolve. Viewport is applied last so pane changes don't clobber the restore.
+- `takeScreenshot(options?: { type?: "image/png" | "image/jpeg"; quality?: number }): string` — returns a data URL of the current frame (default PNG) at the chart's device pixel ratio. Everything on the canvas is included: series, indicators, panes, drawings, legends.
+
+```ts
+// Persist / restore the user's whole chart setup
+localStorage.setItem("layout", JSON.stringify(chart.saveState()));
+chart.loadState(JSON.parse(localStorage.getItem("layout")!));
+
+// Download a chart snapshot
+const link = document.createElement("a");
+link.href = chart.takeScreenshot();
+link.download = "chart.png";
+link.click();
+```
+
 - `resize(width?: number, height?: number): void`
 - `destroy(): void`
 

package/package.json

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