@forgecharts/sdk 1.1.23

package/src/api/drawing tools/lines menu/regressionTrend.ts

@@ -0,0 +1,157 @@
+import type { Drawing, OHLCV } from '@forgecharts/types';
+import type { CoordTransform } from '../../../core/CoordTransform';
+
+// ─── OLS linear regression ────────────────────────────────────────────────────
+
+type RegressionParams = {
+  slope: number;
+  intercept: number;
+  stdDev: number;
+};
+
+/**
+ * Ordinary least-squares regression on the close prices of a candle slice.
+ *
+ * x = candle index (0 … N-1)
+ * y = close price
+ *
+ * m = (N·Σxy − Σx·Σy) / (N·Σx² − (Σx)²)
+ * b = (Σy − m·Σx) / N
+ */
+function calcOLS(closes: readonly number[]): RegressionParams | null {
+  const N = closes.length;
+  if (N < 2) return null;
+
+  let sumX = 0, sumY = 0, sumXY = 0, sumX2 = 0;
+  for (let i = 0; i < N; i++) {
+    const y = closes[i]!;
+    sumX  += i;
+    sumY  += y;
+    sumXY += i * y;
+    sumX2 += i * i;
+  }
+
+  const denom = N * sumX2 - sumX * sumX;
+  if (denom === 0) return null;
+
+  const slope     = (N * sumXY - sumX * sumY) / denom;
+  const intercept = (sumY - slope * sumX) / N;
+
+  // Standard deviation of residuals
+  let sumRes2 = 0;
+  for (let i = 0; i < N; i++) {
+    const residual = closes[i]! - (slope * i + intercept);
+    sumRes2 += residual * residual;
+  }
+  const stdDev = Math.sqrt(sumRes2 / N);
+
+  return { slope, intercept, stdDev };
+}
+
+// ─── Candle slice helper ──────────────────────────────────────────────────────
+
+/**
+ * Returns candles whose timestamps fall within [tStart, tEnd] (inclusive).
+ * Assumes the input array is sorted ascending by time (Series guarantees this).
+ */
+function sliceByTime(candles: readonly OHLCV[], tStart: number, tEnd: number): readonly OHLCV[] {
+  let lo = 0, hi = candles.length - 1, start = candles.length;
+  // Binary search for first index >= tStart
+  while (lo <= hi) {
+    const mid = (lo + hi) >>> 1;
+    if (candles[mid]!.time < tStart) lo = mid + 1;
+    else { start = mid; hi = mid - 1; }
+  }
+  // Walk forward to find last index <= tEnd
+  let end = start - 1;
+  for (let i = start; i < candles.length && candles[i]!.time <= tEnd; i++) end = i;
+  if (end < start) return [];
+  return candles.slice(start, end + 1);
+}
+
+// ─── Renderer ─────────────────────────────────────────────────────────────────
+
+export function renderRegressionTrend(
+  ctx: CanvasRenderingContext2D,
+  d: Drawing,
+  t: CoordTransform,
+  candles: readonly OHLCV[],
+): void {
+  const p0 = d.points[0];
+  const p1 = d.points[1];
+  if (!p0 || !p1) return;
+
+  const tStart = Math.min(p0.time, p1.time);
+  const tEnd   = Math.max(p0.time, p1.time);
+
+  const slice = sliceByTime(candles, tStart, tEnd);
+  const N = slice.length;
+  if (N < 2) return;
+
+  const closes = slice.map(c => c.close);
+  const reg = calcOLS(closes);
+  if (!reg) return;
+
+  const { slope, intercept, stdDev } = reg;
+
+  // Regression price at the first and last candle of the slice
+  const regPriceStart = intercept;                 // index 0
+  const regPriceEnd   = slope * (N - 1) + intercept; // index N-1
+
+  // Pixel x from actual candle timestamps; y from regression-derived prices
+  const x0 = t.timeToX(slice[0]!.time);
+  const x1 = t.timeToX(slice[N - 1]!.time);
+  const y0 = t.priceToY(regPriceStart);
+  const y1 = t.priceToY(regPriceEnd);
+
+  const color = d.color ?? '#2196f3';
+
+  // ── Regression line ───────────────────────────────────────────────────────
+  ctx.beginPath();
+  ctx.moveTo(x0, y0);
+  ctx.lineTo(x1, y1);
+  ctx.stroke();
+
+  // ── Deviation bands ───────────────────────────────────────────────────────
+  if (stdDev === 0) return; // flat data — no meaningful channel
+
+  const mult       = d.deviationMultiplier ?? 2;
+  const bandOffset = stdDev * mult; // price units
+
+  const yUp0 = t.priceToY(regPriceStart + bandOffset);
+  const yUp1 = t.priceToY(regPriceEnd   + bandOffset);
+  const yDn0 = t.priceToY(regPriceStart - bandOffset);
+  const yDn1 = t.priceToY(regPriceEnd   - bandOffset);
+
+  ctx.save();
+  ctx.setLineDash([4, 3]);
+  ctx.globalAlpha = 0.65;
+
+  // Upper band
+  ctx.beginPath();
+  ctx.moveTo(x0, yUp0);
+  ctx.lineTo(x1, yUp1);
+  ctx.stroke();
+
+  // Lower band
+  ctx.beginPath();
+  ctx.moveTo(x0, yDn0);
+  ctx.lineTo(x1, yDn1);
+  ctx.stroke();
+
+  ctx.setLineDash([]);
+
+  // Fill between bands
+  ctx.globalAlpha = 0.07;
+  ctx.fillStyle = color;
+  ctx.beginPath();
+  ctx.moveTo(x0, yUp0);
+  ctx.lineTo(x1, yUp1);
+  ctx.lineTo(x1, yDn1);
+  ctx.lineTo(x0, yDn0);
+  ctx.closePath();
+  ctx.fill();
+
+  ctx.restore();
+}
+

package/src/api/drawing tools/lines menu/schiffPitchfork.ts

@@ -0,0 +1,18 @@
+import type { Drawing } from '@forgecharts/types';
+import type { CoordTransform } from '../../../core/CoordTransform';
+import { getPF3, drawPitchforkLines } from '../../drawingUtils';
+import { renderTrendline } from './trendline';
+
+export function renderSchiffPitchfork(
+  ctx: CanvasRenderingContext2D,
+  d: Drawing,
+  t: CoordTransform,
+): void {
+  const pf = getPF3(d, t);
+  if (!pf) { renderTrendline(ctx, d, t); return; }
+  const { x0, y0, x1, y1, x2, y2 } = pf;
+  const midX = (x1 + x2) / 2, midY = (y1 + y2) / 2;
+  const pivX = (x0 + midX) / 2;
+  const pivY = (y0 + midY) / 2;
+  drawPitchforkLines(ctx, t, pivX, pivY, midX, midY, x1, y1, x2, y2);
+}

package/src/api/drawing tools/lines menu/trendAngle.ts

@@ -0,0 +1,64 @@
+import type { Drawing } from '@forgecharts/types';
+import type { CoordTransform } from '../../../core/CoordTransform';
+import { renderTrendline } from './trendline';
+
+export function renderTrendAngle(
+  ctx: CanvasRenderingContext2D,
+  d: Drawing,
+  t: CoordTransform,
+): void {
+  const p0 = d.points[0];
+  const p1 = d.points[1];
+  if (!p0 || !p1) return;
+
+  const x0 = t.timeToX(p0.time), y0 = t.priceToY(p0.price);
+  const x1 = t.timeToX(p1.time), y1 = t.priceToY(p1.price);
+
+  const angleRad = Math.atan2(-(y1 - y0), x1 - x0);
+  const angleDeg = (angleRad * 180 / Math.PI).toFixed(2);
+  const color    = d.color ?? '#2196f3';
+
+  // Main trendline
+  renderTrendline(ctx, d, t);
+
+  ctx.save();
+  ctx.strokeStyle = color;
+  ctx.fillStyle   = color;
+
+  // Dotted horizontal baseline from p0 to p1's x-position
+  ctx.beginPath();
+  ctx.setLineDash([3, 3]);
+  ctx.moveTo(x0, y0);
+  ctx.lineTo(x1, y0);
+  ctx.stroke();
+  ctx.setLineDash([]);
+
+  // Arc at p0 sweeping from baseline to the trendline
+  const ARC_R = Math.min(36, Math.abs(x1 - x0) * 0.35);
+  if (ARC_R > 6) {
+    const goingRight = x1 >= x0;
+    const startAngle = goingRight ? 0 : Math.PI;
+    const lineAngle  = Math.atan2(y1 - y0, x1 - x0);
+    ctx.beginPath();
+    ctx.lineWidth = 1;
+    if (goingRight) {
+      ctx.arc(x0, y0, ARC_R, startAngle, lineAngle, lineAngle < 0);
+    } else {
+      ctx.arc(x0, y0, ARC_R, startAngle, lineAngle, lineAngle > Math.PI);
+    }
+    ctx.stroke();
+  }
+
+  // Angle label near p0, just outside the arc
+  const labelR    = ARC_R + 6;
+  const halfAngle = Math.atan2(y1 - y0, x1 - x0) / 2;
+  const lx = x0 + labelR * Math.cos(halfAngle);
+  const ly = y0 + labelR * Math.sin(halfAngle);
+
+  ctx.font = '11px -apple-system, BlinkMacSystemFont, sans-serif';
+  ctx.textAlign    = x1 >= x0 ? 'left' : 'right';
+  ctx.textBaseline = y1 <= y0 ? 'top' : 'bottom';
+  ctx.fillText(`${angleDeg}\u00b0`, lx + (x1 >= x0 ? 2 : -2), ly);
+
+  ctx.restore();
+}

package/src/api/drawing tools/lines menu/trendline.ts

@@ -0,0 +1,16 @@
+import type { Drawing } from '@forgecharts/types';
+import type { CoordTransform } from '../../../core/CoordTransform';
+
+export function renderTrendline(
+  ctx: CanvasRenderingContext2D,
+  d: Drawing,
+  t: CoordTransform,
+): void {
+  const p0 = d.points[0];
+  const p1 = d.points[1];
+  if (!p0 || !p1) return;
+  ctx.beginPath();
+  ctx.moveTo(t.timeToX(p0.time), t.priceToY(p0.price));
+  ctx.lineTo(t.timeToX(p1.time), t.priceToY(p1.price));
+  ctx.stroke();
+}

package/src/api/drawing tools/lines menu/vertical.ts

@@ -0,0 +1,16 @@
+import type { Drawing } from '@forgecharts/types';
+import type { CoordTransform } from '../../../core/CoordTransform';
+
+export function renderVertical(
+  ctx: CanvasRenderingContext2D,
+  d: Drawing,
+  t: CoordTransform,
+): void {
+  const p0 = d.points[0];
+  if (!p0) return;
+  const x = t.timeToX(p0.time);
+  ctx.beginPath();
+  ctx.moveTo(x, 0);
+  ctx.lineTo(x, t.plotHeight);
+  ctx.stroke();
+}

package/src/api/drawing tools/pointers menu/crosshair.ts

@@ -0,0 +1,17 @@
+/**
+ * Crosshair pointer tool.
+ *
+ * Hides the native cursor (`cursor: none`) and activates the SDK-drawn
+ * dashed crosshair lines (vertical + horizontal) via `Chart.setCrosshairEnabled(true)`.
+ * No PointerOverlay is rendered for this mode.
+ */
+
+export const CROSSHAIR_LABEL = 'Cross';
+export const CROSSHAIR_STYLE = 'none' as const;
+
+/** Descriptor used by the toolbar and tool-selection logic. */
+export const crosshairTool = {
+  type:        'crosshair' as const,
+  label:       CROSSHAIR_LABEL,
+  cursorStyle: CROSSHAIR_STYLE,
+} as const;

package/src/api/drawing tools/pointers menu/cursor.ts

@@ -0,0 +1,16 @@
+/**
+ * Cursor (Arrow) pointer tool.
+ *
+ * The default interaction mode — shows the native OS arrow cursor.
+ * No custom overlay is rendered; the SDK crosshair is disabled.
+ */
+
+export const CURSOR_LABEL  = 'Arrow';
+export const CURSOR_STYLE  = 'default' as const;
+
+/** Descriptor used by the toolbar and tool-selection logic. */
+export const cursorTool = {
+  type:        'cursor' as const,
+  label:       CURSOR_LABEL,
+  cursorStyle: CURSOR_STYLE,
+} as const;

package/src/api/drawing tools/pointers menu/demonstration.ts

@@ -0,0 +1,35 @@
+/**
+ * Demonstration pointer tool.
+ *
+ * Hides the native cursor and renders a PointerOverlay with:
+ *   - dashed crosshair lines (vertical + horizontal)
+ *   - a large semi-transparent circle centred on the cursor
+ *
+ * Useful for screen-sharing / presentations where the cursor position
+ * needs to be clearly visible to an audience.
+ *
+ * The SDK crosshair (`Chart.setCrosshairEnabled`) is NOT active in this mode;
+ * all visuals come from the SVG overlay.
+ */
+
+export const DEMONSTRATION_LABEL  = 'Demonstration';
+export const DEMONSTRATION_STYLE  = 'none' as const;
+
+/** Radius (px) of the large highlight circle drawn around the cursor. */
+export const DEMONSTRATION_RADIUS = 44;
+
+/** Fill colour of the demonstration circle. */
+export const DEMONSTRATION_FILL   = 'rgba(255, 200, 50, 0.18)';
+
+/** Stroke colour of the demonstration circle. */
+export const DEMONSTRATION_STROKE = 'rgba(255, 200, 50, 0.7)';
+
+/** Colour used for the dashed crosshair lines. */
+export const DEMONSTRATION_COLOR  = 'var(--crosshair-overlay, rgba(255,255,255,0.75))';
+
+/** Descriptor used by the toolbar and tool-selection logic. */
+export const demonstrationTool = {
+  type:        'demonstration' as const,
+  label:       DEMONSTRATION_LABEL,
+  cursorStyle: DEMONSTRATION_STYLE,
+} as const;

package/src/api/drawing tools/pointers menu/dot.ts

@@ -0,0 +1,26 @@
+/**
+ * Dot pointer tool.
+ *
+ * Hides the native cursor and renders a PointerOverlay with:
+ *   - dashed crosshair lines (vertical + horizontal)
+ *   - a small filled circle at the cursor intersection
+ *
+ * The SDK crosshair (`Chart.setCrosshairEnabled`) is NOT active in this mode;
+ * all visuals come from the SVG overlay.
+ */
+
+export const DOT_LABEL  = 'Dot';
+export const DOT_STYLE  = 'none' as const;
+
+/** Radius (px) of the filled dot drawn at the crosshair intersection. */
+export const DOT_RADIUS = 3;
+
+/** Colour used for both the crosshair lines and the dot fill. */
+export const DOT_COLOR  = 'var(--crosshair-overlay, rgba(255,255,255,0.75))';
+
+/** Descriptor used by the toolbar and tool-selection logic. */
+export const dotTool = {
+  type:        'dot' as const,
+  label:       DOT_LABEL,
+  cursorStyle: DOT_STYLE,
+} as const;

package/src/api/drawing tools/shapes menu/rectangle.ts

@@ -0,0 +1,24 @@
+import type { Drawing } from '@forgecharts/types';
+import type { CoordTransform } from '../../../core/CoordTransform';
+
+export function renderRectangle(
+  ctx: CanvasRenderingContext2D,
+  d: Drawing,
+  t: CoordTransform,
+): void {
+  const p0 = d.points[0];
+  const p1 = d.points[1];
+  if (!p0 || !p1) return;
+  const rx = Math.min(t.timeToX(p0.time), t.timeToX(p1.time));
+  const ry = Math.min(t.priceToY(p0.price), t.priceToY(p1.price));
+  const rw = Math.abs(t.timeToX(p1.time) - t.timeToX(p0.time));
+  const rh = Math.abs(t.priceToY(p1.price) - t.priceToY(p0.price));
+  ctx.save();
+  ctx.fillStyle = d.fillColor ?? (d.color ?? '#2196f3');
+  ctx.globalAlpha *= d.fillOpacity ?? 0.1;
+  ctx.fillRect(rx, ry, rw, rh);
+  ctx.restore();
+  ctx.beginPath();
+  ctx.rect(rx, ry, rw, rh);
+  ctx.stroke();
+}

package/src/api/drawing tools/shapes menu/text.ts

@@ -0,0 +1,30 @@
+import type { Drawing } from '@forgecharts/types';
+import type { CoordTransform } from '../../../core/CoordTransform';
+
+export function renderText(
+  ctx: CanvasRenderingContext2D,
+  d: Drawing,
+  t: CoordTransform,
+): void {
+  const p0 = d.points[0];
+  if (!p0) return;
+  const label = d.text ?? 'Text';
+  const x  = t.timeToX(p0.time);
+  const y  = t.priceToY(p0.price);
+  const fs = d.fontSize ?? 13;
+  ctx.font = `${fs}px -apple-system, BlinkMacSystemFont, sans-serif`;
+  const metrics = ctx.measureText(label);
+  const pad  = 4;
+  const boxW = metrics.width + pad * 2;
+  const boxH = fs + pad * 2;
+  ctx.save();
+  ctx.fillStyle = d.color ?? '#2196f3';
+  ctx.globalAlpha *= 0.15;
+  ctx.fillRect(x, y - boxH, boxW, boxH);
+  ctx.restore();
+  ctx.font = `${fs}px -apple-system, BlinkMacSystemFont, sans-serif`;
+  ctx.fillStyle = d.color ?? '#2196f3';
+  ctx.textAlign = 'left';
+  ctx.textBaseline = 'bottom';
+  ctx.fillText(label, x + pad, y);
+}

package/src/api/drawingUtils.ts

@@ -0,0 +1,82 @@
+import type { Drawing } from '@forgecharts/types';
+import type { CoordTransform } from '../core/CoordTransform';
+
+// ─── Handle appearance ────────────────────────────────────────────────────────
+export const HANDLE_HALF   = 5;
+export const HANDLE_FILL   = '#2196f3';
+export const HANDLE_STROKE = 'rgba(255,255,255,0.9)';
+
+// ─── Ray exit helper ──────────────────────────────────────────────────────────
+export function rayExit(
+  plotW: number,
+  plotH: number,
+  px: number,
+  py: number,
+  dx: number,
+  dy: number,
+): { x: number; y: number } {
+  if (dx === 0 && dy === 0) return { x: px, y: py };
+  let tMin = Infinity;
+  if (dx > 0)      tMin = Math.min(tMin, (plotW - px) / dx);
+  else if (dx < 0) tMin = Math.min(tMin, -px / dx);
+  if (dy > 0)      tMin = Math.min(tMin, (plotH - py) / dy);
+  else if (dy < 0) tMin = Math.min(tMin, -py / dy);
+  return tMin === Infinity
+    ? { x: px, y: py }
+    : { x: px + dx * tMin, y: py + dy * tMin };
+}
+
+// ─── Timeframe seconds map ────────────────────────────────────────────────────
+export const TF_SECS: Record<string, number> = {
+  '1s': 1, '5s': 5, '10s': 10, '30s': 30,
+  '1m': 60, '3m': 180, '5m': 300, '15m': 900, '30m': 1800,
+  '1h': 3600, '2h': 7200, '4h': 14400, '6h': 21600, '12h': 43200,
+  '1d': 86400, '3d': 259200, '1w': 604800, '1M': 2592000,
+};
+
+export function formatDuration(seconds: number): string {
+  if (seconds < 60)  return `${seconds}s`;
+  if (seconds < 3600) { const m = Math.floor(seconds / 60); return `${m}m`; }
+  const h = Math.floor(seconds / 3600);
+  const m = Math.round((seconds % 3600) / 60);
+  return m > 0 ? `${h}h ${m}m` : `${h}h`;
+}
+
+// ─── Pitchfork helpers ────────────────────────────────────────────────────────
+export type PF3 = {
+  x0: number; y0: number;
+  x1: number; y1: number;
+  x2: number; y2: number;
+};
+
+export function getPF3(d: Drawing, t: CoordTransform): PF3 | null {
+  const p0 = d.points[0], p1 = d.points[1], p2 = d.points[2];
+  if (!p0 || !p1 || !p2) return null;
+  return {
+    x0: t.timeToX(p0.time), y0: t.priceToY(p0.price),
+    x1: t.timeToX(p1.time), y1: t.priceToY(p1.price),
+    x2: t.timeToX(p2.time), y2: t.priceToY(p2.price),
+  };
+}
+
+export function drawPitchforkLines(
+  ctx: CanvasRenderingContext2D,
+  t: CoordTransform,
+  pivotX: number, pivotY: number,
+  midX: number,  midY: number,
+  x1: number,    y1: number,
+  x2: number,    y2: number,
+): void {
+  const dx = midX - pivotX, dy = midY - pivotY;
+  const medExit = rayExit(t.plotWidth, t.plotHeight, midX, midY, dx, dy);
+  ctx.beginPath(); ctx.moveTo(pivotX, pivotY); ctx.lineTo(medExit.x, medExit.y); ctx.stroke();
+  const upExit = rayExit(t.plotWidth, t.plotHeight, x1, y1, dx, dy);
+  ctx.beginPath(); ctx.moveTo(x1, y1); ctx.lineTo(upExit.x, upExit.y); ctx.stroke();
+  const dnExit = rayExit(t.plotWidth, t.plotHeight, x2, y2, dx, dy);
+  ctx.beginPath(); ctx.moveTo(x2, y2); ctx.lineTo(dnExit.x, dnExit.y); ctx.stroke();
+  ctx.save(); ctx.globalAlpha = 0.4;
+  ctx.beginPath(); ctx.moveTo(pivotX, pivotY); ctx.lineTo(x1, y1); ctx.stroke();
+  ctx.beginPath(); ctx.moveTo(x1, y1);         ctx.lineTo(x2, y2); ctx.stroke();
+  ctx.beginPath(); ctx.moveTo(x2, y2);         ctx.lineTo(pivotX, pivotY); ctx.stroke();
+  ctx.restore();
+}

package/src/core/CanvasLayer.ts

@@ -0,0 +1,77 @@
+/**
+ * CanvasLayer — a single <canvas> element inside the chart container.
+ * Each layer has an independent bitmap; layers are stacked via CSS z-index.
+ * Physical pixels are pre-scaled by devicePixelRatio for crisp rendering.
+ */
+export type CanvasLayerOptions = {
+  readonly width: number;
+  readonly height: number;
+  readonly dpr: number;
+  readonly zIndex: number;
+};
+
+export class CanvasLayer {
+  readonly canvas: HTMLCanvasElement;
+  readonly context: CanvasRenderingContext2D;
+
+  private _width: number;
+  private _height: number;
+  private _dpr: number;
+
+  constructor(container: HTMLElement, options: CanvasLayerOptions) {
+    this._width = options.width;
+    this._height = options.height;
+    this._dpr = options.dpr;
+
+    this.canvas = document.createElement('canvas');
+    this.canvas.style.position = 'absolute';
+    this.canvas.style.inset = '0';
+    this.canvas.style.zIndex = String(options.zIndex);
+    this.canvas.style.pointerEvents = options.zIndex === 3 ? 'auto' : 'none';
+
+    const ctx = this.canvas.getContext('2d');
+    if (!ctx) throw new Error('[ForgeCharts] Failed to acquire 2D canvas context');
+    this.context = ctx;
+
+    this._applyDpr();
+    container.appendChild(this.canvas);
+  }
+
+  get width(): number {
+    return this._width;
+  }
+
+  get height(): number {
+    return this._height;
+  }
+
+  get dpr(): number {
+    return this._dpr;
+  }
+
+  resize(width: number, height: number, dpr: number): void {
+    const physW = Math.round(width * dpr);
+    const physH = Math.round(height * dpr);
+    // Setting canvas.width/height always clears the bitmap, so skip if nothing changed.
+    if (physW === this.canvas.width && physH === this.canvas.height && dpr === this._dpr) {
+      return;
+    }
+    this._width = width;
+    this._height = height;
+    this._dpr = dpr;
+    this._applyDpr();
+  }
+
+  destroy(): void {
+    this.canvas.remove();
+  }
+
+  private _applyDpr(): void {
+    const { canvas, context, _width: w, _height: h, _dpr: dpr } = this;
+    canvas.width = Math.round(w * dpr);
+    canvas.height = Math.round(h * dpr);
+    canvas.style.width = `${w}px`;
+    canvas.style.height = `${h}px`;
+    context.setTransform(dpr, 0, 0, dpr, 0, 0);
+  }
+}