hyperprop-charting-library 0.1.135 → 0.1.137

package/docs/API.md

@@ -483,9 +483,34 @@ chart.setActiveDrawingTool("fib-extension");   // three clicks: trend start, tre
 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)
@@ -533,12 +558,13 @@ an up measurement, red for down.
 - `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" | "fib-extension" | "long-position" | "short-position" | "price-range" | "rectangle" | "text" | "note" | "measure"`)
+- `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`
 - `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`
@@ -558,6 +584,22 @@ an up measurement, red for down.
 - `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, priceScale, 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`
 
@@ -612,6 +654,43 @@ Script contract:
 - `bars`: `Array<{ time: Date, o, h, l, c, v? }>` — the full series.
 - `inputs`: resolved input values (defaults merged with per-instance overrides). `showValueLine`
   is injected automatically and honored by separate panes.
+
+### Pine-style input declarations
+
+Instead of maintaining a separate JSON `inputs` schema, scripts can declare their settings inline
+at the top level — the same idea as TradingView's `input.int(14, "Length")`. The declared
+constants always hold the live settings values, and hosts can auto-generate the settings dialog
+from the declarations:
+
+```ts
+const length = input.int("Length", 14, { min: 1, max: 500 });
+const source = input.source("Source", "close"); // open/high/low/close/hl2/hlc3/ohlc4
+const smooth = input.bool("Smooth", true);
+const color  = input.color("Line color", "#f59e0b");
+
+function compute(bars, inputs, hp) {
+  const values = bars.map(b => source === "open" ? b.o : b.c);
+  const line = smooth ? hp.ema(values, length) : hp.sma(values, length);
+  return { plots: [{ title: "MA", values: line, color }] };
+}
+```
+
+Available declarations (all return the resolved value; `opts` is `{ key?, min?, max?, step? }`):
+
+- `input.int(label, default, opts?)` / `input.float(label, default, opts?)` → number
+- `input.bool(label, default?)` → boolean
+- `input.color(label, default)` → color string
+- `input.string(label, default?)` → string
+- `input.select(label, default, choices)` → string (choices: `string[]` or `{value, label}[]`)
+- `input.source(label?, default?)` → one of `open/high/low/close/hl2/hlc3/ohlc4`
+
+Settings keys default to a slug of the label (`"Line color"` → `line_color`); pass
+`{ key: "..." }` to pin one explicitly (keeps saved settings stable if you rename the label).
+
+`extractScriptInputs(source: string): { inputs: ScriptIndicatorInputDef[], error: string | null }`
+— runs the script's top level with a recording helper and returns the declared schema; hosts use
+this to auto-generate settings dialogs. The legacy JSON `inputs` array on
+`ScriptIndicatorDefinition` still works; on key collisions the inline declarations win.
 - `hp`: TA helpers, all `(values: Array<number|null>, length) => Array<number|null>` unless noted:
   `sma`, `ema`, `rma`, `highest`, `lowest`, `stdev`, `change(values, length = 1)`,
   `atr(bars, length)`.

package/package.json

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