hyperprop-charting-library 0.1.66 → 0.1.68

package/dist/index.js

@@ -102,7 +102,8 @@ var DEFAULT_PRICE_LINE_OPTIONS = {
   labelBackgroundColor: "#0b1220",
   labelTextColor: "#60a5fa",
   labelBorderRadius: 3,
-  showLabel: true
+  showLabel: true,
+  pinOutOfRange: false
 };
 var DEFAULT_ORDER_LINE_OPTIONS = {
   visible: true,
@@ -136,7 +137,8 @@ var DEFAULT_ORDER_LINE_OPTIONS = {
   connectorThickness: 1,
   connectorAnchorPaddingRight: 10,
   fillToPrice: Number.NaN,
-  fillColor: "rgba(37,99,235,0.18)"
+  fillColor: "rgba(37,99,235,0.18)",
+  pinOutOfRange: false
 };
 var DEFAULT_OPTIONS = {
   width: 720,
@@ -169,6 +171,7 @@ var DEFAULT_OPTIONS = {
   candleColorEpsilon: -1,
   autoScaleSmoothing: 0.16,
   autoScaleIgnoreLatestCandle: true,
+  pinOutOfRangeLines: false,
   doubleClickEnabled: true,
   doubleClickAction: "reset",
   crosshair: DEFAULT_CROSSHAIR_OPTIONS,
@@ -1477,12 +1480,27 @@ function createChart(element, options = {}) {
     const scaleWidth = Math.max(0, Math.floor(width - getRightAxisLabelX(chartRight)));
     return Math.max(contentWidth, scaleWidth);
   };
+  const getLineY = (price, yFromPrice, chartTop, chartBottom, pinOutOfRange = mergedOptions.pinOutOfRangeLines) => {
+    const y = yFromPrice(price);
+    if (!Number.isFinite(y)) {
+      return null;
+    }
+    const minY = chartTop + 1;
+    const maxY = chartBottom - 1;
+    if (y < minY || y > maxY) {
+      return pinOutOfRange ? clamp(y, minY, maxY) : null;
+    }
+    return y;
+  };
   const drawPriceLine = (line, yFromPrice, chartLeft, chartTop, chartRight, chartBottom) => {
     const mergedLine = { ...DEFAULT_PRICE_LINE_OPTIONS, ...line };
     if (!mergedLine.visible || !Number.isFinite(mergedLine.price)) {
       return;
     }
-    const lineY = clamp(yFromPrice(mergedLine.price), chartTop + 1, chartBottom - 1);
+    const lineY = getLineY(mergedLine.price, yFromPrice, chartTop, chartBottom, mergedLine.pinOutOfRange);
+    if (lineY === null) {
+      return;
+    }
     const color = mergedLine.color;
     ctx.save();
     ctx.strokeStyle = color;
@@ -1528,10 +1546,16 @@ function createChart(element, options = {}) {
     if (!mergedLine.visible || !Number.isFinite(renderPrice)) {
       return;
     }
-    const lineY = clamp(yFromPrice(renderPrice), chartTop + 1, chartBottom - 1);
+    const lineY = getLineY(renderPrice, yFromPrice, chartTop, chartBottom, mergedLine.pinOutOfRange);
+    if (lineY === null) {
+      return;
+    }
     const color = line.color ?? (mergedLine.type === "takeProfit" ? "rgba(45,212,191,0.86)" : mergedLine.type === "stop" ? "rgba(245,158,11,0.86)" : "rgba(59,130,246,0.8)");
     if (Number.isFinite(mergedLine.fillToPrice)) {
-      const fillY = clamp(yFromPrice(mergedLine.fillToPrice), chartTop + 1, chartBottom - 1);
+      const fillY = getLineY(mergedLine.fillToPrice, yFromPrice, chartTop, chartBottom, true);
+      if (fillY === null) {
+        return;
+      }
       const topY = Math.min(lineY, fillY);
       const heightY = Math.max(1, Math.abs(lineY - fillY));
       ctx.save();
@@ -1549,21 +1573,29 @@ function createChart(element, options = {}) {
     ctx.stroke();
     ctx.restore();
     if (Number.isFinite(mergedLine.connectorToPrice)) {
-      const connectorY = clamp(yFromPrice(mergedLine.connectorToPrice), chartTop + 1, chartBottom - 1);
-      const connectorX = chartRight - Math.max(6, mergedLine.connectorAnchorPaddingRight);
-      ctx.save();
-      ctx.strokeStyle = mergedLine.connectorColor ?? color;
-      ctx.lineWidth = Math.max(1, mergedLine.connectorThickness);
-      applyDashPattern(
-        mergedLine.connectorStyle,
-        dashPatterns.connectorDotted,
-        dashPatterns.connectorDashed
+      const connectorY = getLineY(
+        mergedLine.connectorToPrice,
+        yFromPrice,
+        chartTop,
+        chartBottom,
+        mergedLine.pinOutOfRange
       );
-      ctx.beginPath();
-      ctx.moveTo(crisp(connectorX), crisp(lineY));
-      ctx.lineTo(crisp(connectorX), crisp(connectorY));
-      ctx.stroke();
-      ctx.restore();
+      if (connectorY !== null) {
+        const connectorX = chartRight - Math.max(6, mergedLine.connectorAnchorPaddingRight);
+        ctx.save();
+        ctx.strokeStyle = mergedLine.connectorColor ?? color;
+        ctx.lineWidth = Math.max(1, mergedLine.connectorThickness);
+        applyDashPattern(
+          mergedLine.connectorStyle,
+          dashPatterns.connectorDotted,
+          dashPatterns.connectorDashed
+        );
+        ctx.beginPath();
+        ctx.moveTo(crisp(connectorX), crisp(lineY));
+        ctx.lineTo(crisp(connectorX), crisp(connectorY));
+        ctx.stroke();
+        ctx.restore();
+      }
     }
     const qtyText = mergedLine.qty === void 0 ? "" : String(mergedLine.qty);
     const typeTextMap = {
@@ -2096,7 +2128,11 @@ function createChart(element, options = {}) {
       if (drawing.type === "horizontal-line") {
         const point = drawing.points[0];
         if (point) {
-          const y = clamp(yFromPrice(point.price), chartTop + 1, chartBottom - 1);
+          const y = getLineY(point.price, yFromPrice, chartTop, chartBottom);
+          if (y === null) {
+            ctx.restore();
+            return;
+          }
           const handleX = chartRight - 64;
           ctx.beginPath();
           ctx.moveTo(crisp(chartLeft), crisp(y));
@@ -2108,6 +2144,20 @@ function createChart(element, options = {}) {
             drawDrawingLabel(drawing.label, midX, y, drawing.color);
           }
         }
+      } else if (drawing.type === "vertical-line") {
+        const point = drawing.points[0];
+        if (point) {
+          const x = xFromDrawingPoint(point);
+          ctx.beginPath();
+          ctx.moveTo(crisp(x), crisp(chartTop));
+          ctx.lineTo(crisp(x), crisp(chartBottom));
+          ctx.stroke();
+          const handleY = (chartTop + chartBottom) / 2;
+          drawDrawingHandle(x, handleY, drawing.color);
+          if (drawing.label) {
+            drawDrawingLabel(drawing.label, x, chartTop + 16, drawing.color);
+          }
+        }
       } else if (drawing.type === "trendline") {
         const first = drawing.points[0];
         const second = drawing.points[1];
@@ -2128,6 +2178,36 @@ function createChart(element, options = {}) {
             drawDrawingLabel(drawing.label, midX, midY, drawing.color);
           }
         }
+      } else if (drawing.type === "ray") {
+        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);
+          const dx = secondX - firstX;
+          const dy = secondY - firstY;
+          let endX = secondX;
+          let endY = secondY;
+          const len = Math.hypot(dx, dy);
+          if (len > 0) {
+            const far = Math.abs(chartRight - chartLeft) + Math.abs(chartBottom - chartTop) + 2e3;
+            endX = firstX + dx / len * far;
+            endY = firstY + dy / len * far;
+          }
+          ctx.beginPath();
+          ctx.moveTo(firstX, firstY);
+          ctx.lineTo(endX, endY);
+          ctx.stroke();
+          drawDrawingHandle(firstX, firstY, drawing.color);
+          drawDrawingHandle(secondX, secondY, drawing.color);
+          if (drawing.label) {
+            const midX = (firstX + secondX) / 2;
+            const midY = (firstY + secondY) / 2;
+            drawDrawingLabel(drawing.label, midX, midY, drawing.color);
+          }
+        }
       } else if (drawing.type === "fib-retracement") {
         const first = drawing.points[0];
         const second = drawing.points[1];
@@ -2536,13 +2616,19 @@ function createChart(element, options = {}) {
       if (!labels.visible || !Number.isFinite(label.price) || label.text.length === 0) {
         return;
       }
+      if (getLineY(label.price, yFromPrice, chartTop, chartBottom, label.pinOutOfRange) === null) {
+        return;
+      }
       priceAxisLabels.push(label);
     };
-    const drawReferenceLine = (price, color, style = "dotted") => {
+    const drawReferenceLine = (price, color, style = "dotted", pinOutOfRange = mergedOptions.pinOutOfRangeLines) => {
       if (!Number.isFinite(price)) {
         return;
       }
-      const y = clamp(yFromPrice(price), chartTop + 1, chartBottom - 1);
+      const y = getLineY(price, yFromPrice, chartTop, chartBottom, pinOutOfRange);
+      if (y === null) {
+        return;
+      }
       ctx.save();
       ctx.strokeStyle = color;
       ctx.lineWidth = 1;
@@ -2569,22 +2655,23 @@ function createChart(element, options = {}) {
     let tickerColor = null;
     if ((ticker.visible ?? true) && lastPoint) {
       tickerPrice = ticker.smoothing && smoothedTickerPrice !== null ? smoothedTickerPrice : lastPoint.c;
-      const tickerY = yFromPrice(tickerPrice);
-      const lineY = clamp(tickerY, chartTop + 1, chartBottom - 1);
+      const lineY = getLineY(tickerPrice, yFromPrice, chartTop, chartBottom);
       const lastDirection = ticker.smoothing && smoothedTickerPrice !== null ? smoothedTickerPrice >= lastPoint.o ? "up" : "down" : getCandleDirectionByIndex(data.length - 1);
       tickerColor = ticker.color ?? (lastDirection === "up" ? mergedOptions.upColor : mergedOptions.downColor);
       const tickerThickness = Math.max(1, ticker.thickness ?? 1);
       const tickerStyle = ticker.style ?? "solid";
-      ctx.save();
-      ctx.strokeStyle = tickerColor;
-      ctx.lineWidth = tickerThickness;
-      applyDashPattern(tickerStyle, dashPatterns.dotted, dashPatterns.dashed);
-      ctx.beginPath();
-      ctx.moveTo(crisp(chartLeft), crisp(lineY));
-      ctx.lineTo(crisp(chartRight), crisp(lineY));
-      ctx.stroke();
-      ctx.setLineDash([]);
-      ctx.restore();
+      if (lineY !== null) {
+        ctx.save();
+        ctx.strokeStyle = tickerColor;
+        ctx.lineWidth = tickerThickness;
+        applyDashPattern(tickerStyle, dashPatterns.dotted, dashPatterns.dashed);
+        ctx.beginPath();
+        ctx.moveTo(crisp(chartLeft), crisp(lineY));
+        ctx.lineTo(crisp(chartRight), crisp(lineY));
+        ctx.stroke();
+        ctx.setLineDash([]);
+        ctx.restore();
+      }
     }
     if ((ticker.visible ?? true) && labels.showLastPrice && tickerPrice !== null && tickerColor !== null) {
       const tickerSubtexts = [
@@ -2694,13 +2781,14 @@ function createChart(element, options = {}) {
         }
         const labelTextWidth = Math.max(primaryWidth, subtextWidth);
         const labelWidth = getRightAxisLabelWidth(chartRight, labelTextWidth);
+        const labelLineY = getLineY(label.price, yFromPrice, chartTop, chartBottom, label.pinOutOfRange);
         return {
           ...label,
           subtexts,
           subtextFontSize,
           height: labelHeight,
           width: labelWidth,
-          targetY: clamp(yFromPrice(label.price), chartTop + 1, chartBottom - 1) - labelHeight / 2,
+          targetY: (labelLineY ?? yFromPrice(label.price)) - labelHeight / 2,
           y: 0
         };
       }).sort((a, b) => a.targetY - b.targetY || b.priority - a.priority);
@@ -3262,6 +3350,17 @@ function createChart(element, options = {}) {
         if (Math.abs(y - lineY) <= 7) {
           return { drawing, target: "line" };
         }
+      } else if (drawing.type === "vertical-line") {
+        const point = drawing.points[0];
+        if (!point) continue;
+        const lineX = canvasXFromDrawingPoint(point);
+        const handleY = drawState ? (drawState.chartTop + drawState.chartBottom) / 2 : 0;
+        if (Math.hypot(x - lineX, y - handleY) <= 8) {
+          return { drawing, target: "handle", pointIndex: 0 };
+        }
+        if (Math.abs(x - lineX) <= 7) {
+          return { drawing, target: "line" };
+        }
       } else if (drawing.type === "trendline") {
         const first = drawing.points[0];
         const second = drawing.points[1];
@@ -3279,6 +3378,31 @@ function createChart(element, options = {}) {
         if (distanceToSegment(x, y, x1, y1, x2, y2) <= 6) {
           return { drawing, target: "line" };
         }
+      } else if (drawing.type === "ray") {
+        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) {
+          return { drawing, target: "handle", pointIndex: 0 };
+        }
+        if (Math.hypot(x - x2, y - y2) <= 8) {
+          return { drawing, target: "handle", pointIndex: 1 };
+        }
+        const dx = x2 - x1;
+        const dy = y2 - y1;
+        const lengthSq = dx * dx + dy * dy;
+        if (lengthSq > 0) {
+          const t = Math.max(0, ((x - x1) * dx + (y - y1) * dy) / lengthSq);
+          const projX = x1 + t * dx;
+          const projY = y1 + t * dy;
+          if (Math.hypot(x - projX, y - projY) <= 6) {
+            return { drawing, target: "line" };
+          }
+        }
       } else if (drawing.type === "fib-retracement") {
         const first = drawing.points[0];
         const second = drawing.points[1];
@@ -3380,6 +3504,21 @@ function createChart(element, options = {}) {
       draw();
       return true;
     }
+    if (activeDrawingTool === "vertical-line") {
+      const defaults = getDrawingToolDefaults("vertical-line");
+      drawings.push(
+        normalizeDrawingState({
+          type: "vertical-line",
+          points: [point],
+          color: defaults.color ?? "#38bdf8",
+          style: defaults.style ?? "solid",
+          width: defaults.width ?? 1
+        })
+      );
+      emitDrawingsChange();
+      draw();
+      return true;
+    }
     if (activeDrawingTool === "trendline") {
       if (draftDrawing?.type === "trendline") {
         const completed = normalizeDrawingState({
@@ -3404,6 +3543,30 @@ function createChart(element, options = {}) {
       draw();
       return true;
     }
+    if (activeDrawingTool === "ray") {
+      if (draftDrawing?.type === "ray") {
+        const completed = normalizeDrawingState({
+          ...serializeDrawing(draftDrawing),
+          points: [draftDrawing.points[0], point]
+        });
+        drawings.push(completed);
+        draftDrawing = null;
+        activeDrawingTool = null;
+        emitDrawingsChange();
+        draw();
+        return true;
+      }
+      const defaults = getDrawingToolDefaults("ray");
+      draftDrawing = normalizeDrawingState({
+        type: "ray",
+        points: [point, point],
+        color: defaults.color ?? "#2563eb",
+        style: defaults.style ?? "solid",
+        width: defaults.width ?? 2
+      });
+      draw();
+      return true;
+    }
     if (activeDrawingTool === "fib-retracement") {
       if (draftDrawing?.type === "fib-retracement") {
         const completed = normalizeDrawingState({
@@ -3700,7 +3863,7 @@ function createChart(element, options = {}) {
       setCrosshairPoint(null);
       return;
     }
-    if (draftDrawing && (activeDrawingTool === "trendline" || activeDrawingTool === "fib-retracement")) {
+    if (draftDrawing && (activeDrawingTool === "trendline" || activeDrawingTool === "ray" || activeDrawingTool === "fib-retracement")) {
       const nextPoint = drawingPointFromCanvas(point.x, point.y);
       if (nextPoint) {
         draftDrawing = {

package/docs/API.md

@@ -57,6 +57,7 @@ Top-level options:
 - `candleColorEpsilon` (default `-1` = auto from `priceDecimals`; set `0` to disable tolerance)
 - `autoScaleSmoothing` (default `0.16`)
 - `autoScaleIgnoreLatestCandle` (default `true`)
+- `pinOutOfRangeLines` (default `false`; when `true`, horizontal price/order/reference lines outside the visible price range are pinned to the top/bottom chart edge)
 - `doubleClickEnabled` (default `true`)
 - `doubleClickAction` (`"reset"` | `"placeLimitOrder"`, default `"reset"`)
 - `crosshair?: CrosshairOptions`
@@ -226,6 +227,7 @@ createChart(root, {
 - `labelTextColor` (default `#0f172a`)
 - `labelBorderRadius` (default `3`)
 - `showLabel` (default `true`)
+- `pinOutOfRange?: boolean` (default `false`; overrides `ChartOptions.pinOutOfRangeLines` for this line)
 
 ### `OrderActionButton`
 
@@ -269,6 +271,7 @@ Common optional fields:
 - `widgetPosition?: "left" | "center" | "right"` (default `"left"`)
 - `widgetPaddingRight?: number` (default `10`, extra right margin when `widgetPosition` is `"right"`)
 - `draggable?: boolean` (default `false`)
+- `pinOutOfRange?: boolean` (default `false`; overrides `ChartOptions.pinOutOfRangeLines` for this order/position line)
 
 Legacy single action button:
 
@@ -411,7 +414,11 @@ Volume style inputs:
 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"`
+- `type: "horizontal-line" | "vertical-line" | "trendline" | "ray" | "fib-retracement"`
+  - `horizontal-line` / `vertical-line`: single-point, full-width/full-height line (one click to place)
+  - `trendline`: two-point segment (click start, click end)
+  - `ray`: two-point line that extends infinitely past the second point
+  - `fib-retracement`: two-point retracement with levels/bands
 - `points: DrawingPoint[]`
 - `visible?: boolean`
 - `color?: string`
@@ -433,7 +440,10 @@ Tool workflow:
 
 ```ts
 chart.setActiveDrawingTool("horizontal-line"); // next plot click creates a line
+chart.setActiveDrawingTool("vertical-line");   // next plot click creates a vertical line
 chart.setActiveDrawingTool("trendline");       // first click starts, second click commits
+chart.setActiveDrawingTool("ray");             // first click starts, second click commits (extends past p2)
+chart.setActiveDrawingTool("fib-retracement"); // first click starts, second click commits
 chart.setActiveDrawingTool(null);              // back to normal cursor/pan
 ```
 
@@ -463,8 +473,8 @@ Use `getDrawings()` / `setDrawings()` for persistence.
 - `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`
+- `setActiveDrawingTool(tool: DrawingToolType | null): void` (`DrawingToolType` = `"horizontal-line" | "vertical-line" | "trendline" | "ray" | "fib-retracement"`)
+- `getActiveDrawingTool(): DrawingToolType | null`
 - `setDrawings(drawings: DrawingObjectOptions[]): void`
 - `getDrawings(): DrawingObjectOptions[]`
 - `addDrawing(drawing: DrawingObjectOptions): string`

package/docs/RECIPES.md

@@ -85,16 +85,35 @@ chart.addPriceLine({
 });
 ```
 
+## Pin out-of-range lines to the chart edge
+
+By default, horizontal price/order/drawing lines outside the visible price range are hidden instead of being pinned to the top or bottom edge. Opt in globally or per line when you want marker-style behavior for important levels.
+
+```ts
+const chart = createChart(rootEl, {
+  pinOutOfRangeLines: true
+});
+
+chart.addPriceLine({
+  price: 6400,
+  label: "Liquidation",
+  pinOutOfRange: true
+});
+```
+
 ## 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.
+// Single-click tools: the next plot click creates the drawing.
 chart.setActiveDrawingTool("horizontal-line");
+chart.setActiveDrawingTool("vertical-line");
 
-// First click starts a trendline, second click commits it.
+// Two-click tools: first click starts, second click commits.
 chart.setActiveDrawingTool("trendline");
+chart.setActiveDrawingTool("ray");            // extends infinitely past the second point
+chart.setActiveDrawingTool("fib-retracement");
 
 // Back to normal cursor/pan mode.
 chart.setActiveDrawingTool(null);

package/package.json

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