hyperprop-charting-library 0.1.54 → 0.1.55

package/dist/index.js

@@ -190,7 +190,8 @@ var DEFAULT_OPTIONS = {
   },
   labels: DEFAULT_LABELS_OPTIONS,
   dashPatterns: DEFAULT_DASH_PATTERNS,
-  indicators: []
+  indicators: [],
+  drawings: []
 };
 var mergeChartOptions = (baseOptions, options = {}) => ({
   ...baseOptions,
@@ -881,6 +882,7 @@ function createChart(element, options = {}) {
   let generatedPriceLineId = 1;
   let generatedOrderLineId = 1;
   let generatedIndicatorId = 1;
+  let generatedDrawingId = 1;
   const indicatorRegistry = /* @__PURE__ */ new Map();
   for (const indicator of BUILTIN_INDICATORS) {
     indicatorRegistry.set(indicator.id, indicator);
@@ -903,7 +905,41 @@ function createChart(element, options = {}) {
       }
     };
   };
+  const normalizeDrawingState = (drawing) => ({
+    id: drawing.id ?? `drawing-${generatedDrawingId++}`,
+    type: drawing.type,
+    points: drawing.points.map((point) => ({
+      index: Number(point.index) || 0,
+      price: Number(point.price) || 0,
+      ...point.time ? { time: point.time } : {}
+    })),
+    visible: drawing.visible ?? true,
+    color: drawing.color ?? "#94a3b8",
+    style: drawing.style ?? "dotted",
+    width: Math.max(1, Number(drawing.width) || 1),
+    locked: drawing.locked ?? false,
+    ...drawing.label === void 0 ? {} : { label: drawing.label }
+  });
+  const serializeDrawing = (drawing) => ({
+    id: drawing.id,
+    type: drawing.type,
+    points: drawing.points.map((point) => ({ ...point })),
+    visible: drawing.visible,
+    color: drawing.color,
+    style: drawing.style,
+    width: drawing.width,
+    locked: drawing.locked,
+    ...drawing.label === void 0 ? {} : { label: drawing.label }
+  });
   let indicators = (options.indicators ?? []).map((indicator) => normalizeIndicatorState(indicator));
+  let drawings = (options.drawings ?? []).map((drawing) => normalizeDrawingState(drawing));
+  let activeDrawingTool = null;
+  let draftDrawing = null;
+  let drawingsChangeHandler = null;
+  let drawingSelectHandler = null;
+  const emitDrawingsChange = () => {
+    drawingsChangeHandler?.(drawings.map((drawing) => serializeDrawing(drawing)));
+  };
   const orderWidgetWidthById = /* @__PURE__ */ new Map();
   const orderPriceTagWidthById = /* @__PURE__ */ new Map();
   let xCenter = 0;
@@ -1957,6 +1993,55 @@ function createChart(element, options = {}) {
     const yFromPrice = (price) => {
       return chartBottom - (price - yMin) / yRange * chartHeight;
     };
+    const xFromDrawingPoint = (point) => chartLeft + (point.index + 0.5 - xStart) / xSpan * chartWidth;
+    const drawDrawingHandle = (x, y, color) => {
+      ctx.save();
+      ctx.setLineDash([]);
+      ctx.fillStyle = mergedOptions.backgroundColor;
+      ctx.strokeStyle = color;
+      ctx.lineWidth = 2;
+      ctx.beginPath();
+      ctx.arc(x, y, 5, 0, Math.PI * 2);
+      ctx.fill();
+      ctx.stroke();
+      ctx.restore();
+    };
+    const drawDrawing = (drawing, draft = false) => {
+      if (!drawing.visible) {
+        return;
+      }
+      ctx.save();
+      ctx.strokeStyle = drawing.color;
+      ctx.lineWidth = drawing.width;
+      ctx.globalAlpha = draft ? 0.72 : 1;
+      applyDashPattern(drawing.style, dashPatterns.dotted, dashPatterns.dashed);
+      if (drawing.type === "horizontal-line") {
+        const point = drawing.points[0];
+        if (point) {
+          const y = clamp(yFromPrice(point.price), chartTop + 1, chartBottom - 1);
+          ctx.beginPath();
+          ctx.moveTo(crisp(chartLeft), crisp(y));
+          ctx.lineTo(crisp(chartRight), crisp(y));
+          ctx.stroke();
+        }
+      } else if (drawing.type === "trendline") {
+        const first = drawing.points[0];
+        const second = drawing.points[1];
+        if (first && second) {
+          const firstX = xFromDrawingPoint(first);
+          const firstY = yFromPrice(first.price);
+          const secondX = xFromDrawingPoint(second);
+          const secondY = yFromPrice(second.price);
+          ctx.beginPath();
+          ctx.moveTo(firstX, firstY);
+          ctx.lineTo(secondX, secondY);
+          ctx.stroke();
+          drawDrawingHandle(firstX, firstY, drawing.color);
+          drawDrawingHandle(secondX, secondY, drawing.color);
+        }
+      }
+      ctx.restore();
+    };
     if (watermark.visible && watermark.imageSrc.trim().length > 0) {
       ensureWatermarkImage(watermark.imageSrc.trim());
       if (watermarkImageReady && watermarkImage) {
@@ -2128,6 +2213,10 @@ function createChart(element, options = {}) {
         );
       });
     }
+    drawings.forEach((drawing) => drawDrawing(drawing));
+    if (draftDrawing) {
+      drawDrawing(draftDrawing, true);
+    }
     const crosshair = { ...DEFAULT_CROSSHAIR_OPTIONS, ...mergedOptions.crosshair ?? {} };
     if (crosshair.visible && crosshairPoint) {
       const cx = clamp(crosshairPoint.x, chartLeft, chartRight);
@@ -2964,6 +3053,66 @@ function createChart(element, options = {}) {
     const ratio = clamp((drawState.chartBottom - y) / drawState.chartHeight, 0, 1);
     return drawState.yMin + ratio * (drawState.yMax - drawState.yMin);
   };
+  const drawingPointFromCanvas = (x, y) => {
+    if (!drawState) {
+      return null;
+    }
+    const ratio = clamp((x - drawState.chartLeft) / drawState.chartWidth, 0, 1);
+    const index = drawState.xStart + ratio * drawState.xSpan - 0.5;
+    const nearestIndex = Math.round(index);
+    const time = getTimeForIndex(nearestIndex);
+    return {
+      index,
+      price: roundToPricePrecision(priceFromCanvasY(y)),
+      ...time ? { time: time.toISOString() } : {}
+    };
+  };
+  const canvasXFromDrawingPoint = (point) => {
+    if (!drawState) return 0;
+    return drawState.chartLeft + (point.index + 0.5 - drawState.xStart) / drawState.xSpan * drawState.chartWidth;
+  };
+  const canvasYFromDrawingPrice = (price) => {
+    if (!drawState) return 0;
+    const range = drawState.yMax - drawState.yMin || 1;
+    return drawState.chartBottom - (price - drawState.yMin) / range * drawState.chartHeight;
+  };
+  const distanceToSegment = (x, y, x1, y1, x2, y2) => {
+    const dx = x2 - x1;
+    const dy = y2 - y1;
+    const lengthSq = dx * dx + dy * dy;
+    if (lengthSq === 0) return Math.hypot(x - x1, y - y1);
+    const t = clamp(((x - x1) * dx + (y - y1) * dy) / lengthSq, 0, 1);
+    return Math.hypot(x - (x1 + t * dx), y - (y1 + t * dy));
+  };
+  const getDrawingHit = (x, y) => {
+    for (let index = drawings.length - 1; index >= 0; index -= 1) {
+      const drawing = drawings[index];
+      if (!drawing?.visible) continue;
+      if (drawing.type === "horizontal-line") {
+        const point = drawing.points[0];
+        if (!point) continue;
+        const lineY = canvasYFromDrawingPrice(point.price);
+        if (Math.abs(y - lineY) <= 7) {
+          return { drawing, target: "line" };
+        }
+      } else if (drawing.type === "trendline") {
+        const first = drawing.points[0];
+        const second = drawing.points[1];
+        if (!first || !second) continue;
+        const x1 = canvasXFromDrawingPoint(first);
+        const y1 = canvasYFromDrawingPrice(first.price);
+        const x2 = canvasXFromDrawingPoint(second);
+        const y2 = canvasYFromDrawingPrice(second.price);
+        if (Math.hypot(x - x1, y - y1) <= 8 || Math.hypot(x - x2, y - y2) <= 8) {
+          return { drawing, target: "handle" };
+        }
+        if (distanceToSegment(x, y, x1, y1, x2, y2) <= 6) {
+          return { drawing, target: "line" };
+        }
+      }
+    }
+    return null;
+  };
   const indexFromCanvasX = (x) => {
     if (!drawState) {
       return null;
@@ -3016,6 +3165,53 @@ function createChart(element, options = {}) {
     }
     return "outside";
   };
+  const handleDrawingToolPointerDown = (x, y) => {
+    if (!activeDrawingTool || !drawState) {
+      return false;
+    }
+    const point = drawingPointFromCanvas(x, y);
+    if (!point) {
+      return false;
+    }
+    if (activeDrawingTool === "horizontal-line") {
+      drawings.push(
+        normalizeDrawingState({
+          type: "horizontal-line",
+          points: [point],
+          color: "#38bdf8",
+          style: "dotted",
+          width: 1
+        })
+      );
+      emitDrawingsChange();
+      draw();
+      return true;
+    }
+    if (activeDrawingTool === "trendline") {
+      if (draftDrawing?.type === "trendline") {
+        const completed = normalizeDrawingState({
+          ...serializeDrawing(draftDrawing),
+          points: [draftDrawing.points[0], point]
+        });
+        drawings.push(completed);
+        draftDrawing = null;
+        activeDrawingTool = null;
+        emitDrawingsChange();
+        draw();
+        return true;
+      }
+      draftDrawing = normalizeDrawingState({
+        type: "trendline",
+        points: [point, point],
+        color: "#2563eb",
+        style: "solid",
+        width: 2
+      });
+      draw();
+      return true;
+    }
+    return false;
+  };
   let isDragging = false;
   let dragMode = null;
   let lastPointerX = 0;
@@ -3141,6 +3337,25 @@ function createChart(element, options = {}) {
     if (region === "outside") {
       return;
     }
+    if (region === "plot" && !activeDrawingTool) {
+      const drawingHit = getDrawingHit(point.x, point.y);
+      if (drawingHit) {
+        drawingSelectHandler?.({
+          drawing: serializeDrawing(drawingHit.drawing),
+          target: drawingHit.target,
+          x: point.x,
+          y: point.y
+        });
+        setCrosshairPoint(null);
+        canvas.style.cursor = "pointer";
+        return;
+      }
+    }
+    if (region === "plot" && handleDrawingToolPointerDown(point.x, point.y)) {
+      setCrosshairPoint(null);
+      canvas.style.cursor = "crosshair";
+      return;
+    }
     isDragging = true;
     dragMode = region;
     activePointerId = event.pointerId;
@@ -3172,6 +3387,18 @@ function createChart(element, options = {}) {
         pointerDownInfo.moved = true;
       }
     }
+    if (draftDrawing && activeDrawingTool === "trendline") {
+      const nextPoint = drawingPointFromCanvas(point.x, point.y);
+      if (nextPoint) {
+        draftDrawing = {
+          ...draftDrawing,
+          points: [draftDrawing.points[0], nextPoint]
+        };
+        canvas.style.cursor = "crosshair";
+        draw();
+        return;
+      }
+    }
     if (orderDragState) {
       if (activePointerId !== null && event.pointerId !== activePointerId) {
         return;
@@ -3242,9 +3469,14 @@ function createChart(element, options = {}) {
         setCrosshairPoint(null);
         return;
       }
+      if (!activeDrawingTool && getDrawingHit(point.x, point.y)) {
+        canvas.style.cursor = "pointer";
+        setCrosshairPoint(null);
+        return;
+      }
       const hoverRegion = getHitRegion(point.x, point.y);
       if (hoverRegion === "plot") {
-        canvas.style.cursor = doubleClickEnabled ? "default" : "crosshair";
+        canvas.style.cursor = activeDrawingTool ? "crosshair" : doubleClickEnabled ? "default" : "crosshair";
         setCrosshairPoint(point);
         emitCrosshairMove(point.x, point.y, "plot");
       } else if (hoverRegion === "x-axis") {
@@ -3643,6 +3875,56 @@ function createChart(element, options = {}) {
     indicators = indicators.filter((indicator) => indicator.id !== id);
     draw();
   };
+  const setActiveDrawingTool = (tool) => {
+    activeDrawingTool = tool;
+    draftDrawing = null;
+    canvas.style.cursor = tool ? "crosshair" : "default";
+    draw();
+  };
+  const getActiveDrawingTool = () => activeDrawingTool;
+  const getDrawings = () => drawings.map((drawing) => serializeDrawing(drawing));
+  const setDrawings = (nextDrawings) => {
+    drawings = nextDrawings.map((drawing) => normalizeDrawingState(drawing));
+    draftDrawing = null;
+    emitDrawingsChange();
+    draw();
+  };
+  const addDrawing = (drawing) => {
+    const next = normalizeDrawingState(drawing);
+    drawings.push(next);
+    emitDrawingsChange();
+    draw();
+    return next.id;
+  };
+  const updateDrawing = (id, patch) => {
+    drawings = drawings.map(
+      (drawing) => drawing.id === id ? normalizeDrawingState({
+        ...serializeDrawing(drawing),
+        ...patch,
+        id,
+        points: patch.points ?? drawing.points
+      }) : drawing
+    );
+    emitDrawingsChange();
+    draw();
+  };
+  const removeDrawing = (id) => {
+    drawings = drawings.filter((drawing) => drawing.id !== id);
+    emitDrawingsChange();
+    draw();
+  };
+  const clearDrawings = () => {
+    drawings = [];
+    draftDrawing = null;
+    emitDrawingsChange();
+    draw();
+  };
+  const onDrawingsChange = (handler) => {
+    drawingsChangeHandler = handler;
+  };
+  const onDrawingSelect = (handler) => {
+    drawingSelectHandler = handler;
+  };
   const destroy = () => {
     if (smoothingRafId !== null) {
       cancelAnimationFrame(smoothingRafId);
@@ -3686,6 +3968,16 @@ function createChart(element, options = {}) {
     getViewport,
     setViewport,
     onViewportChange,
+    setActiveDrawingTool,
+    getActiveDrawingTool,
+    setDrawings,
+    getDrawings,
+    addDrawing,
+    updateDrawing,
+    removeDrawing,
+    clearDrawings,
+    onDrawingsChange,
+    onDrawingSelect,
     setDoubleClickEnabled,
     setDoubleClickAction,
     registerIndicator,

package/docs/API.md

@@ -68,6 +68,7 @@ Top-level options:
 - `labels?: LabelsOptions` (TradingView-style price-scale/indicator label controls)
 - `dashPatterns?: Partial<DashPatternOptions>` (controls dotted/dashed spacing)
 - `indicators?: IndicatorInstanceOptions[]` (initial indicator instances, built-in includes `"volume"`)
+- `drawings?: DrawingObjectOptions[]` (initial user drawings/tool objects)
 
 ### `AxisOptions`
 
@@ -405,6 +406,39 @@ Volume style inputs:
 - `scaleType` (`"sqrt"` default, or `"log"` / `"linear"`)
 - `clampPercentile` (`0..1`, default `1`; e.g. `0.95` to reduce outlier crush)
 
+### `DrawingObjectOptions`
+
+Drawings are user-created chart tools, separate from indicators. They are interactive chart objects like horizontal lines and trendlines.
+
+- `id?: string`
+- `type: "horizontal-line" | "trendline"`
+- `points: DrawingPoint[]`
+- `visible?: boolean`
+- `color?: string`
+- `style?: "solid" | "dotted" | "dashed"`
+- `width?: number`
+- `label?: string`
+
+`DrawingPoint`:
+
+```ts
+type DrawingPoint = {
+  index: number;   // fractional candle index
+  price: number;
+  time?: string;   // ISO timestamp for reference/persistence
+};
+```
+
+Tool workflow:
+
+```ts
+chart.setActiveDrawingTool("horizontal-line"); // next plot click creates a line
+chart.setActiveDrawingTool("trendline");       // first click starts, second click commits
+chart.setActiveDrawingTool(null);              // back to normal cursor/pan
+```
+
+Use `getDrawings()` / `setDrawings()` for persistence.
+
 ---
 
 ## `ChartInstance` Methods
@@ -429,6 +463,15 @@ Volume style inputs:
 - `panY(priceDelta: number): void` (positive = move viewport up)
 - `fitContent(): void` (x-only fit, keeps y zoom)
 - `resetViewport(): void` (fit x + reset y auto-scale)
+- `setActiveDrawingTool(tool: "horizontal-line" | "trendline" | null): void`
+- `getActiveDrawingTool(): "horizontal-line" | "trendline" | null`
+- `setDrawings(drawings: DrawingObjectOptions[]): void`
+- `getDrawings(): DrawingObjectOptions[]`
+- `addDrawing(drawing: DrawingObjectOptions): string`
+- `updateDrawing(id: string, patch: Partial<DrawingObjectOptions>): void`
+- `removeDrawing(id: string): void`
+- `clearDrawings(): void`
+- `onDrawingsChange(handler: ((drawings: DrawingObjectOptions[]) => void) | null): void`
 - `setDoubleClickEnabled(enabled: boolean): void`
 - `setDoubleClickAction(action: "reset" | "placeLimitOrder"): void`
 - `registerIndicator(plugin: IndicatorPlugin): void`

package/docs/RECIPES.md

@@ -85,6 +85,34 @@ chart.addPriceLine({
 });
 ```
 
+## Add chart drawing tools
+
+Drawing tools are separate from indicators. Indicators compute/render data series; drawings are user-created objects that can be persisted.
+
+```ts
+// Let the next click create a horizontal line.
+chart.setActiveDrawingTool("horizontal-line");
+
+// First click starts a trendline, second click commits it.
+chart.setActiveDrawingTool("trendline");
+
+// Back to normal cursor/pan mode.
+chart.setActiveDrawingTool(null);
+```
+
+Persist drawings:
+
+```ts
+chart.onDrawingsChange((drawings) => {
+  localStorage.setItem("chart-drawings", JSON.stringify(drawings));
+});
+
+const saved = localStorage.getItem("chart-drawings");
+if (saved) {
+  chart.setDrawings(JSON.parse(saved));
+}
+```
+
 ## Tighten dotted spacing globally
 
 ```ts

package/package.json

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