hyperprop-charting-library 0.1.137 → 0.1.138

package/dist/index.d.ts

@@ -78,6 +78,8 @@ interface ChartOptions {
     pinOutOfRangeLines?: boolean;
     doubleClickEnabled?: boolean;
     doubleClickAction?: "reset" | "placeLimitOrder";
+    keyboard?: KeyboardOptions;
+    accessibility?: AccessibilityOptions;
     crosshair?: CrosshairOptions;
     grid?: GridOptions;
     watermark?: WatermarkOptions;
@@ -164,6 +166,36 @@ interface DrawingSelectEvent {
     pointIndex?: number;
     x: number;
     y: number;
+    /** On-screen box of the drawing, for anchoring a host toolbar to it. */
+    bounds?: DrawingBounds;
+}
+/** Canvas-pixel bounding box of a drawing, relative to the chart canvas. */
+interface DrawingBounds {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+    centerX: number;
+    centerY: number;
+}
+/**
+ * Emitted whenever the selected drawing's on-screen box moves — selection,
+ * deselection (payload `null`), drag, edit, pan, zoom or resize. Hosts render
+ * their own floating toolbar and position it from `bounds`, keeping it inside
+ * `plot`; the chart never has to draw toolbar chrome itself.
+ */
+interface DrawingSelectionChangeEvent {
+    drawing: DrawingObjectOptions;
+    bounds: DrawingBounds;
+    /** Plot rectangle, so a toolbar can be clamped inside the chart area. */
+    plot: {
+        left: number;
+        top: number;
+        right: number;
+        bottom: number;
+    };
+    /** True while the drawing is actively being dragged or resized. */
+    dragging: boolean;
 }
 interface DrawingHoverEvent {
     drawing: DrawingObjectOptions | null;
@@ -470,6 +502,67 @@ interface CrosshairPriceActionEvent {
     y: number;
     price: number;
 }
+/**
+ * What the pointer was over when the context menu was requested. Hosts switch
+ * on this to show the right menu instead of re-deriving it from coordinates.
+ */
+type ChartContextMenuRegion = "plot" | "drawing" | "indicator-pane" | "x-axis" | "y-axis";
+interface ChartContextMenuEvent {
+    region: ChartContextMenuRegion;
+    /** Canvas-relative position. */
+    x: number;
+    y: number;
+    /** Viewport position, ready to place a DOM menu without re-measuring. */
+    clientX: number;
+    clientY: number;
+    /** Price under the pointer (main pane regions only). */
+    price?: number;
+    index?: number;
+    time?: string;
+    point?: OhlcDataPoint;
+    /** Set for region "drawing"; the drawing is also selected by the chart. */
+    drawing?: DrawingObjectOptions;
+    drawingTarget?: "line" | "handle";
+    pointIndex?: number;
+    /** Set for region "indicator-pane". */
+    indicator?: {
+        id: string;
+        type: string;
+    };
+}
+/** Built-in keyboard actions, reported after the chart applies them. */
+type ChartKeyboardAction = "delete-drawing" | "cancel" | "pan-left" | "pan-right" | "pan-up" | "pan-down" | "zoom-in" | "zoom-out" | "reset-viewport" | "scroll-to-realtime";
+interface ChartKeyboardShortcutEvent {
+    action: ChartKeyboardAction;
+    /** The originating `KeyboardEvent.key`. */
+    key: string;
+    shiftKey: boolean;
+    /** The drawing that was removed, for "delete-drawing" (so hosts can undo). */
+    drawing?: DrawingObjectOptions;
+}
+interface KeyboardOptions {
+    /**
+     * Master switch for the built-in shortcuts. Shortcuts only fire while the
+     * chart canvas has focus, so they never swallow typing in host inputs.
+     * Default true.
+     */
+    enabled?: boolean;
+    /** Bars panned per arrow-key press (Shift multiplies by 10). Default 1. */
+    panBars?: number;
+    /** Delete/Backspace removes the selected drawing. Default true. */
+    deleteSelectedDrawing?: boolean;
+}
+interface AccessibilityOptions {
+    /** aria-label on the canvas. Default "Price chart". */
+    label?: string;
+    /**
+     * Longer description exposed via aria-description, e.g. the symbol and
+     * interval currently shown.
+     */
+    description?: string;
+    /** Make the canvas focusable so keyboard users can reach it. Default true. */
+    focusable?: boolean;
+}
 interface TickerLineOptions {
     visible?: boolean;
     style?: "solid" | "dotted" | "dashed";
@@ -581,6 +674,29 @@ interface ChartInstance {
     onDrawingSelect: (handler: ((event: DrawingSelectEvent) => void) | null) => void;
     onDrawingDoubleClick: (handler: ((event: DrawingSelectEvent) => void) | null) => void;
     onDrawingEditText: (handler: ((event: DrawingSelectEvent) => void) | null) => void;
+    /**
+     * Selection geometry stream for a host-rendered floating toolbar. Fires on
+     * select/deselect and on every frame where the selected drawing's box moves
+     * (drag, pan, zoom, resize), so the toolbar can track the shape instead of
+     * sitting in a fixed corner. Payload is `null` when nothing is selected.
+     */
+    onSelectionChange: (handler: ((event: DrawingSelectionChangeEvent | null) => void) | null) => void;
+    /** Current selection and its on-screen box, for imperative reads. */
+    getSelectedDrawing: () => {
+        drawing: DrawingObjectOptions;
+        bounds: DrawingBounds;
+    } | null;
+    /**
+     * Right-click (or long-press equivalent) with everything the host needs to
+     * open the correct menu: which region was hit, the price/bar under the
+     * pointer, and the drawing or indicator pane it landed on. The chart always
+     * suppresses the browser's native menu.
+     */
+    onContextMenu: (handler: ((event: ChartContextMenuEvent) => void) | null) => void;
+    /** Fires after a built-in keyboard shortcut is applied. */
+    onKeyboardShortcut: (handler: ((event: ChartKeyboardShortcutEvent) => void) | null) => void;
+    /** Focus the chart canvas so keyboard shortcuts apply to it. */
+    focus: () => void;
     setMagnetMode: (mode: "none" | "weak" | "strong") => void;
     getMagnetMode: () => "none" | "weak" | "strong";
     /**
@@ -781,4 +897,4 @@ declare const compileScriptIndicator: (definition: ScriptIndicatorDefinition) =>
 
 declare function createChart(element: HTMLElement, options?: ChartOptions): ChartInstance;
 
-export { type AxisOptions, type BuiltInIndicatorInfo, type ChartClickEvent, type ChartInstance, type ChartOptions, type ChartSavedState, type ChartType, type CrosshairMoveEvent, type CrosshairOptions, type CrosshairPriceActionEvent, type DashPatternOptions, type DrawingDefaults, type DrawingHoverEvent, type DrawingObjectOptions, type DrawingPoint, type DrawingSelectEvent, type DrawingToolType, FIB_DEFAULT_PALETTE, type GridOptions, type IndicatorInstanceOptions, type IndicatorPane, type IndicatorPaneActionEvent, type IndicatorPaneAxisOptions, type IndicatorPaneGuideLine, type IndicatorPaneHeightChangeEvent, type IndicatorPaneRenderInfo, type IndicatorPaneValue, type IndicatorPaneValueLabel, type IndicatorPlugin, type IndicatorRenderContext, type LabelsOptions, type OhlcDataPoint, type OrderActionButton, type OrderActionEvent, type OrderLineOptions, POSITION_DEFAULT_COLORS, type PriceLineOptions, type PriceScaleMode, type PriceScaleOptions, SCRIPT_SOURCE_INPUT_VALUES, type ScriptComputeResult, type ScriptIndicatorDefinition, type ScriptIndicatorInputDef, type ScriptInputHelper, type ScriptInputOptions, type ScriptPlotSpec, type TickerLineOptions, type TradeMarkerOptions, type ViewportState, type WatermarkOptions, compileScriptIndicator, createChart, extractScriptInputs, validateScriptSource };
+export { type AccessibilityOptions, type AxisOptions, type BuiltInIndicatorInfo, type ChartClickEvent, type ChartContextMenuEvent, type ChartContextMenuRegion, type ChartInstance, type ChartKeyboardAction, type ChartKeyboardShortcutEvent, type ChartOptions, type ChartSavedState, type ChartType, type CrosshairMoveEvent, type CrosshairOptions, type CrosshairPriceActionEvent, type DashPatternOptions, type DrawingBounds, type DrawingDefaults, type DrawingHoverEvent, type DrawingObjectOptions, type DrawingPoint, type DrawingSelectEvent, type DrawingSelectionChangeEvent, type DrawingToolType, FIB_DEFAULT_PALETTE, type GridOptions, type IndicatorInstanceOptions, type IndicatorPane, type IndicatorPaneActionEvent, type IndicatorPaneAxisOptions, type IndicatorPaneGuideLine, type IndicatorPaneHeightChangeEvent, type IndicatorPaneRenderInfo, type IndicatorPaneValue, type IndicatorPaneValueLabel, type IndicatorPlugin, type IndicatorRenderContext, type KeyboardOptions, type LabelsOptions, type OhlcDataPoint, type OrderActionButton, type OrderActionEvent, type OrderLineOptions, POSITION_DEFAULT_COLORS, type PriceLineOptions, type PriceScaleMode, type PriceScaleOptions, SCRIPT_SOURCE_INPUT_VALUES, type ScriptComputeResult, type ScriptIndicatorDefinition, type ScriptIndicatorInputDef, type ScriptInputHelper, type ScriptInputOptions, type ScriptPlotSpec, type TickerLineOptions, type TradeMarkerOptions, type ViewportState, type WatermarkOptions, compileScriptIndicator, createChart, extractScriptInputs, validateScriptSource };

package/dist/index.js

@@ -2819,6 +2819,8 @@ var DEFAULT_OPTIONS = {
   pinOutOfRangeLines: false,
   doubleClickEnabled: true,
   doubleClickAction: "reset",
+  keyboard: { enabled: true, panBars: 1, deleteSelectedDrawing: true },
+  accessibility: { label: "Price chart", description: "", focusable: true },
   crosshair: DEFAULT_CROSSHAIR_OPTIONS,
   grid: DEFAULT_GRID_OPTIONS,
   watermark: DEFAULT_WATERMARK_OPTIONS,
@@ -2861,6 +2863,14 @@ var mergeChartOptions = (baseOptions, options = {}) => ({
     ...options.axisColor ? { lineColor: options.axisColor, textColor: options.axisColor } : {},
     ...options.yAxis ?? {}
   },
+  keyboard: {
+    ...baseOptions.keyboard,
+    ...options.keyboard ?? {}
+  },
+  accessibility: {
+    ...baseOptions.accessibility,
+    ...options.accessibility ?? {}
+  },
   crosshair: {
     ...baseOptions.crosshair,
     ...options.crosshair ?? {}
@@ -3034,6 +3044,10 @@ function createChart(element, options = {}) {
   let drawingSelectHandler = null;
   let drawingDoubleClickHandler = null;
   let drawingEditTextHandler = null;
+  let selectionChangeHandler = null;
+  let contextMenuHandler = null;
+  let keyboardShortcutHandler = null;
+  let lastSelectionSignature = null;
   let magnetMode = "none";
   let priceScaleMode = "linear";
   let priceScaleInverted = false;
@@ -3196,6 +3210,39 @@ function createChart(element, options = {}) {
   canvas.style.setProperty("-webkit-user-select", "none");
   canvas.style.setProperty("-webkit-touch-callout", "none");
   canvas.setAttribute("draggable", "false");
+  const applyAccessibilityAttributes = () => {
+    const a11y = mergedOptions.accessibility ?? {};
+    const focusable = a11y.focusable !== false;
+    if (focusable) {
+      canvas.tabIndex = 0;
+    } else {
+      canvas.removeAttribute("tabindex");
+    }
+    canvas.setAttribute("role", "application");
+    canvas.setAttribute("aria-label", a11y.label ?? "Price chart");
+    if (a11y.description) {
+      canvas.setAttribute("aria-description", a11y.description);
+    } else {
+      canvas.removeAttribute("aria-description");
+    }
+    if (focusable && (mergedOptions.keyboard?.enabled ?? true)) {
+      canvas.setAttribute(
+        "aria-keyshortcuts",
+        "ArrowLeft ArrowRight ArrowUp ArrowDown Plus Minus Home End Delete Escape"
+      );
+    } else {
+      canvas.removeAttribute("aria-keyshortcuts");
+    }
+  };
+  applyAccessibilityAttributes();
+  let focusFromPointer = false;
+  canvas.addEventListener("focus", () => {
+    canvas.style.outline = focusFromPointer ? "none" : "";
+    focusFromPointer = false;
+  });
+  canvas.addEventListener("blur", () => {
+    canvas.style.outline = "none";
+  });
   element.innerHTML = "";
   element.appendChild(canvas);
   const baseCanvas = document.createElement("canvas");
@@ -6423,6 +6470,7 @@ function createChart(element, options = {}) {
       xSpan
     };
     paintCrosshairOverlay();
+    emitSelectionChangeIfMoved();
   };
   const paintCrosshairOverlay = () => {
     crosshairPriceActionRegion = null;
@@ -7023,6 +7071,98 @@ function createChart(element, options = {}) {
     const ratio = (priceScaleTransform(price) - scaledMin) / scaledRange;
     return priceScaleInverted ? drawState.chartTop + ratio * drawState.chartHeight : drawState.chartBottom - ratio * drawState.chartHeight;
   };
+  const getDrawingBounds = (drawing) => {
+    if (!drawState || drawing.points.length === 0) {
+      return null;
+    }
+    const { chartLeft, chartRight, chartTop, chartBottom } = drawState;
+    let left;
+    let right;
+    let top;
+    let bottom;
+    if (drawing.type === "horizontal-line") {
+      const y = canvasYFromDrawingPrice(drawing.points[0].price);
+      left = chartLeft;
+      right = chartRight;
+      top = y;
+      bottom = y;
+    } else if (drawing.type === "vertical-line") {
+      const x = canvasXFromDrawingPoint(drawing.points[0]);
+      left = x;
+      right = x;
+      top = chartTop;
+      bottom = chartBottom;
+    } else {
+      const xs = drawing.points.map((point) => canvasXFromDrawingPoint(point));
+      const ys = drawing.points.map((point) => canvasYFromDrawingPrice(point.price));
+      left = Math.min(...xs);
+      right = Math.max(...xs);
+      top = Math.min(...ys);
+      bottom = Math.max(...ys);
+      if (drawing.type === "ray") {
+        right = chartRight;
+      }
+    }
+    const clampX = (value) => clamp(value, chartLeft, chartRight);
+    const clampY = (value) => clamp(value, chartTop, chartBottom);
+    left = clampX(left);
+    right = clampX(right);
+    top = clampY(top);
+    bottom = clampY(bottom);
+    return {
+      left,
+      top,
+      right,
+      bottom,
+      centerX: (left + right) / 2,
+      centerY: (top + bottom) / 2
+    };
+  };
+  const getSelectedDrawingWithBounds = () => {
+    if (!selectedDrawingId) {
+      return null;
+    }
+    const drawing = drawings.find((entry) => entry.id === selectedDrawingId);
+    if (!drawing || !drawing.visible) {
+      return null;
+    }
+    const bounds = getDrawingBounds(drawing);
+    return bounds ? { drawing: serializeDrawing(drawing), bounds } : null;
+  };
+  const emitSelectionChangeIfMoved = () => {
+    if (!selectionChangeHandler) {
+      lastSelectionSignature = null;
+      return;
+    }
+    const selection = getSelectedDrawingWithBounds();
+    if (!selection || !drawState) {
+      if (lastSelectionSignature !== null) {
+        lastSelectionSignature = null;
+        selectionChangeHandler(null);
+      }
+      return;
+    }
+    const dragging = drawingDragState !== null;
+    const { bounds } = selection;
+    const signature = `${selection.drawing.id}:${Math.round(bounds.left)}:${Math.round(bounds.top)}:${Math.round(
+      bounds.right
+    )}:${Math.round(bounds.bottom)}:${dragging ? 1 : 0}`;
+    if (signature === lastSelectionSignature) {
+      return;
+    }
+    lastSelectionSignature = signature;
+    selectionChangeHandler({
+      drawing: selection.drawing,
+      bounds,
+      plot: {
+        left: drawState.chartLeft,
+        top: drawState.chartTop,
+        right: drawState.chartRight,
+        bottom: drawState.chartBottom
+      },
+      dragging
+    });
+  };
   const distanceToSegment = (x, y, x1, y1, x2, y2) => {
     const dx = x2 - x1;
     const dy = y2 - y1;
@@ -7989,6 +8129,10 @@ function createChart(element, options = {}) {
     if (event.pointerType === "touch" || event.pointerType === "pen") {
       event.preventDefault();
     }
+    if (mergedOptions.accessibility?.focusable !== false && document.activeElement !== canvas) {
+      focusFromPointer = true;
+      canvas.focus({ preventScroll: true });
+    }
     cancelKineticPan();
     panVelocitySamples.length = 0;
     magnetModifierActive = event.metaKey || event.ctrlKey;
@@ -8106,12 +8250,14 @@ function createChart(element, options = {}) {
       const drawingHit = getDrawingHit(point.x, point.y);
       if (drawingHit) {
         selectedDrawingId = drawingHit.drawing.id;
+        const selectBounds = getDrawingBounds(drawingHit.drawing);
         drawingSelectHandler?.({
           drawing: serializeDrawing(drawingHit.drawing),
           target: drawingHit.target,
           ...drawingHit.pointIndex === void 0 ? {} : { pointIndex: drawingHit.pointIndex },
           x: point.x,
-          y: point.y
+          y: point.y,
+          ...selectBounds ? { bounds: selectBounds } : {}
         });
         if (!drawingHit.drawing.locked) {
           const startCanvasPoint = drawingPointFromCanvas(point.x, point.y, false);
@@ -8672,7 +8818,152 @@ function createChart(element, options = {}) {
   };
   const onContextMenu = (event) => {
     event.preventDefault();
+    if (!contextMenuHandler || !drawState) {
+      return;
+    }
+    const point = getCanvasPoint(event);
+    const hitRegion = getHitRegion(point.x, point.y);
+    if (hitRegion === "outside") {
+      return;
+    }
+    const pane = hitRegion === "plot" ? getPaneAt(point.x, point.y) : null;
+    const drawingHit = hitRegion === "plot" && !pane ? getDrawingHit(point.x, point.y) : null;
+    if (drawingHit) {
+      if (selectedDrawingId !== drawingHit.drawing.id) {
+        selectedDrawingId = drawingHit.drawing.id;
+        scheduleDraw();
+      }
+    }
+    const region = drawingHit ? "drawing" : pane ? "indicator-pane" : hitRegion;
+    const index = indexFromCanvasX(point.x);
+    const barTime = index === null ? null : getTimeForIndex(index);
+    const bar = index === null ? void 0 : data[index];
+    const inMainPane = !pane && (hitRegion === "plot" || hitRegion === "y-axis");
+    contextMenuHandler({
+      region,
+      x: point.x,
+      y: point.y,
+      clientX: event.clientX,
+      clientY: event.clientY,
+      ...inMainPane ? { price: roundToPricePrecision(priceFromCanvasY(point.y)) } : {},
+      ...index === null ? {} : { index },
+      ...barTime ? { time: barTime.toISOString() } : {},
+      ...bar ? {
+        point: {
+          t: bar.time.toISOString(),
+          o: bar.o,
+          h: bar.h,
+          l: bar.l,
+          c: bar.c,
+          ...bar.v === void 0 ? {} : { v: bar.v }
+        }
+      } : {},
+      ...drawingHit ? {
+        drawing: serializeDrawing(drawingHit.drawing),
+        drawingTarget: drawingHit.target,
+        ...drawingHit.pointIndex === void 0 ? {} : { pointIndex: drawingHit.pointIndex }
+      } : {},
+      ...pane ? { indicator: { id: pane.id, type: pane.type } } : {}
+    });
+  };
+  const onCanvasKeyDown = (event) => {
+    const keyboard = mergedOptions.keyboard ?? {};
+    if (keyboard.enabled === false) {
+      return;
+    }
+    if (event.altKey || event.ctrlKey || event.metaKey) {
+      return;
+    }
+    const panStep = Math.max(1, keyboard.panBars ?? 1) * (event.shiftKey ? 10 : 1);
+    const emit = (action, drawing) => {
+      keyboardShortcutHandler?.({
+        action,
+        key: event.key,
+        shiftKey: event.shiftKey,
+        ...drawing ? { drawing } : {}
+      });
+    };
+    switch (event.key) {
+      case "Delete":
+      case "Backspace": {
+        if (keyboard.deleteSelectedDrawing === false || !selectedDrawingId) {
+          return;
+        }
+        const target = drawings.find((entry) => entry.id === selectedDrawingId);
+        if (!target) {
+          return;
+        }
+        const removed = serializeDrawing(target);
+        removeDrawing(selectedDrawingId);
+        selectedDrawingId = null;
+        scheduleDraw();
+        emit("delete-drawing", removed);
+        break;
+      }
+      case "Escape": {
+        if (cancelDrawing()) {
+          emit("cancel");
+          break;
+        }
+        if (activeDrawingTool) {
+          setActiveDrawingTool(null);
+          emit("cancel");
+          break;
+        }
+        if (selectedDrawingId) {
+          setSelectedDrawing(null);
+          emit("cancel");
+          break;
+        }
+        return;
+      }
+      case "ArrowLeft":
+        panX(-panStep);
+        emit("pan-left");
+        break;
+      case "ArrowRight":
+        panX(panStep);
+        emit("pan-right");
+        break;
+      case "ArrowUp":
+      case "ArrowDown": {
+        if (!drawState) {
+          return;
+        }
+        const step = (drawState.yMax - drawState.yMin) / 20 * (event.shiftKey ? 5 : 1);
+        panY(event.key === "ArrowUp" ? step : -step);
+        emit(event.key === "ArrowUp" ? "pan-up" : "pan-down");
+        break;
+      }
+      case "+":
+      case "=":
+        zoomInX();
+        emit("zoom-in");
+        break;
+      case "-":
+      case "_":
+        zoomOutX();
+        emit("zoom-out");
+        break;
+      case "Home":
+        fitContent();
+        emit("reset-viewport");
+        break;
+      case "End":
+        setFollowingLatest(true);
+        emit("scroll-to-realtime");
+        break;
+      case "r":
+      case "R":
+        resetViewport();
+        emit("reset-viewport");
+        break;
+      default:
+        return;
+    }
+    event.preventDefault();
   };
+  canvas.addEventListener("keydown", onCanvasKeyDown);
   canvas.addEventListener("pointerdown", onPointerDown);
   canvas.addEventListener("pointermove", onPointerMove);
   canvas.addEventListener("pointerup", endPointerDrag);
@@ -8719,6 +9010,7 @@ function createChart(element, options = {}) {
     resetRightMarginCache();
     doubleClickEnabled = mergedOptions.doubleClickEnabled;
     doubleClickAction = mergedOptions.doubleClickAction;
+    applyAccessibilityAttributes();
     const isTickerSmoothingEnabled = mergedOptions.tickerLine?.smoothing ?? false;
     if (!isTickerSmoothingEnabled) {
       smoothedTickerPrice = null;
@@ -9102,6 +9394,23 @@ function createChart(element, options = {}) {
   const onDrawingHover = (handler) => {
     drawingHoverHandler = handler;
   };
+  const onSelectionChange = (handler) => {
+    selectionChangeHandler = handler;
+    lastSelectionSignature = null;
+    if (handler) {
+      emitSelectionChangeIfMoved();
+    }
+  };
+  const getSelectedDrawing = () => getSelectedDrawingWithBounds();
+  const onContextMenuHandler = (handler) => {
+    contextMenuHandler = handler;
+  };
+  const onKeyboardShortcut = (handler) => {
+    keyboardShortcutHandler = handler;
+  };
+  const focus = () => {
+    canvas.focus({ preventScroll: true });
+  };
   const saveState = () => {
     const drawingDefaults = {};
     for (const [tool, defaults] of drawingToolDefaults) {
@@ -9166,6 +9475,7 @@ function createChart(element, options = {}) {
       drawRafId = null;
       pendingDrawUpdateAutoScale = false;
     }
+    canvas.removeEventListener("keydown", onCanvasKeyDown);
     canvas.removeEventListener("pointerdown", onPointerDown);
     canvas.removeEventListener("pointermove", onPointerMove);
     canvas.removeEventListener("pointerup", endPointerDrag);
@@ -9229,6 +9539,11 @@ function createChart(element, options = {}) {
     onDrawingSelect,
     onDrawingDoubleClick,
     onDrawingEditText,
+    onSelectionChange,
+    getSelectedDrawing,
+    onContextMenu: onContextMenuHandler,
+    onKeyboardShortcut,
+    focus,
     setMagnetMode,
     getMagnetMode,
     setPriceScale,

package/docs/API.md

@@ -557,6 +557,11 @@ 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.
@@ -605,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

package/package.json

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