hyperprop-charting-library 0.1.136 → 0.1.138

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.
+- `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.
@@ -583,7 +589,7 @@ 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, drawingDefaults }`. Chart *data* is not included; keep feeding bars through `setData`/`upsertBar`.
+- `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.
 
@@ -604,6 +610,101 @@ link.click();
 
 ---
 
+## 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
@@ -653,6 +754,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.136",
+  "version": "0.1.138",
   "description": "Lightweight TypeScript charting core",
   "type": "module",
   "main": "./dist/hyperprop-charting-library.cjs",