@forgecharts/sdk 1.1.23

package/src/core/PriceScale.ts

@@ -0,0 +1,133 @@
+import type { PriceRange, ChartColors, PriceScaleOptions } from '@forgecharts/types';
+import { mapRange, computeTicks, roundToPrecision } from '@forgecharts/utils';
+import type { CanvasLayer } from './CanvasLayer';
+
+const AXIS_WIDTH = 70;
+const TIME_SCALE_HEIGHT = 30;
+
+/**
+ * PriceScale — manages the vertical price axis.
+ * Auto-scales to the visible data range and renders price labels.
+ */
+export class PriceScale {
+  private _visibleRange: PriceRange;
+  private readonly _layer: CanvasLayer;
+  private readonly _colors: ChartColors;
+  private readonly _options: Required<PriceScaleOptions>;
+
+  constructor(layer: CanvasLayer, colors: ChartColors, options: PriceScaleOptions = {}) {
+    this._layer = layer;
+    this._colors = colors;
+    this._options = {
+      autoScale: options.autoScale ?? true,
+      invertScale: options.invertScale ?? false,
+      borderVisible: options.borderVisible ?? true,
+      ticksVisible: options.ticksVisible ?? true,
+      mode: options.mode ?? 'normal',
+      width: options.width ?? AXIS_WIDTH,
+    };
+    this._visibleRange = { min: 0, max: 100 };
+  }
+
+  get visibleRange(): PriceRange {
+    return this._visibleRange;
+  }
+
+  get width(): number {
+    return this._options.width;
+  }
+
+  setVisibleRange(range: PriceRange): void {
+    this._visibleRange = range;
+  }
+
+  /**
+   * Converts a price value to a canvas Y coordinate.
+   */
+  priceToY(price: number, canvasHeight: number): number {
+    const plotHeight = canvasHeight - TIME_SCALE_HEIGHT;
+    const { min, max } = this._visibleRange;
+
+    if (this._options.mode === 'logarithmic') {
+      const logMin = Math.log(Math.max(min, 1e-10));
+      const logMax = Math.log(Math.max(max, 1e-10));
+      const logPrice = Math.log(Math.max(price, 1e-10));
+      return mapRange(logPrice, logMax, logMin, 0, plotHeight);
+    }
+
+    return this._options.invertScale
+      ? mapRange(price, max, min, 0, plotHeight)
+      : mapRange(price, max, min, 0, plotHeight);
+  }
+
+  /**
+   * Converts a canvas Y coordinate back to a price value.
+   */
+  yToPrice(y: number, canvasHeight: number): number {
+    const plotHeight = canvasHeight - TIME_SCALE_HEIGHT;
+    const { min, max } = this._visibleRange;
+    return mapRange(y, 0, plotHeight, max, min);
+  }
+
+  render(ctx: CanvasRenderingContext2D, width: number, height: number): void {
+    if (!this._options.ticksVisible) return;
+
+    const axisX = width - this._options.width;
+    const plotHeight = height - TIME_SCALE_HEIGHT;
+
+    // Axis separator
+    if (this._options.borderVisible) {
+      ctx.beginPath();
+      ctx.strokeStyle = this._colors.border;
+      ctx.lineWidth = 1;
+      ctx.moveTo(axisX, 0);
+      ctx.lineTo(axisX, plotHeight);
+      ctx.stroke();
+    }
+
+    // Compute ticks
+    const approxTicks = Math.max(2, Math.floor(plotHeight / 50));
+    const ticks = computeTicks(this._visibleRange.min, this._visibleRange.max, approxTicks);
+
+    ctx.fillStyle = this._colors.text;
+    ctx.font = '11px system-ui, sans-serif';
+    ctx.textAlign = 'left';
+    ctx.textBaseline = 'middle';
+
+    for (const tick of ticks) {
+      if (tick < this._visibleRange.min || tick > this._visibleRange.max) continue;
+
+      const y = this.priceToY(tick, height);
+      if (y < 0 || y > plotHeight) continue;
+
+      // Grid line
+      ctx.beginPath();
+      ctx.strokeStyle = this._colors.grid;
+      ctx.setLineDash([1, 3]);
+      ctx.moveTo(0, y);
+      ctx.lineTo(axisX, y);
+      ctx.stroke();
+      ctx.setLineDash([]);
+
+      // Tick mark
+      ctx.beginPath();
+      ctx.strokeStyle = this._colors.border;
+      ctx.lineWidth = 1;
+      ctx.moveTo(axisX, y);
+      ctx.lineTo(axisX + 4, y);
+      ctx.stroke();
+
+      // Label
+      const label = this._formatPrice(tick);
+      ctx.fillText(label, axisX + 6, y);
+    }
+  }
+
+  // ─── Private ─────────────────────────────────────────────────────────────────
+
+  private _formatPrice(price: number): string {
+    const range = this._visibleRange.max - this._visibleRange.min;
+    const precision = range < 0.01 ? 6 : range < 1 ? 4 : range < 100 ? 2 : 0;
+    return roundToPrecision(price, precision).toFixed(precision);
+  }
+}

package/src/core/Series.ts

@@ -0,0 +1,132 @@
+import type { OHLCV, SeriesOptions, Viewport, Rect, ChartColors } from '@forgecharts/types';
+import type { ISeries } from '../types/ISeries';
+import type { IRenderer } from '../types/IRenderer';
+import { CandlestickRenderer } from '../renderers/CandlestickRenderer';
+import { LineRenderer } from '../renderers/LineRenderer';
+import { HistogramRenderer } from '../renderers/HistogramRenderer';
+
+/**
+ * Series holds a dataset (OHLCV[]) and delegates pixel-level rendering
+ * to the appropriate IRenderer implementation.
+ */
+export class Series implements ISeries {
+  private _data: OHLCV[] = [];
+  private _options: SeriesOptions;
+  private readonly _renderer: IRenderer;
+
+  /**
+   * Optional callback invoked after `setData()` or `update()` mutates the dataset.
+   * Used by `PixiChart` to mark the PriceSeries layer dirty without polling.
+   */
+  onDataChanged?: () => void;
+
+  constructor(options: SeriesOptions, colors: ChartColors) {
+    this._options = options;
+    this._renderer = Series._createRenderer(options, colors);
+  }
+
+  // ─── ISeries implementation ──────────────────────────────────────────────────
+
+  setData(data: readonly OHLCV[]): void {
+    this._data = [...data].sort((a, b) => a.time - b.time);
+    this.onDataChanged?.();
+  }
+
+  /**
+   * Apply a real-time OHLCV tick to the series.
+   *
+   * Rules (mirrors TradingView / Binance behaviour):
+   *  - time normalisation : if > 1e12 it is milliseconds → convert to seconds
+   *  - same candle (time === last.time):
+   *      open   → unchanged (preserved from first tick of this candle)
+   *      high   → max(prev.high, incoming.high, incoming.close)
+   *      low    → min(prev.low,  incoming.low,  incoming.close)
+   *      close  → incoming.close
+   *      volume → incoming.volume
+   *  - new candle (time > last.time) → append
+   *  - out-of-order (time < last.time) → silently ignored
+   */
+  update(bar: OHLCV): void {
+    // ── 1. Normalise timestamp: ms → s ────────────────────────────────────────
+    const t = bar.time > 1e12 ? Math.floor(bar.time / 1000) : bar.time;
+
+    // ── 2. First bar ever ────────────────────────────────────────────────────
+    if (this._data.length === 0) {
+      this._data.push({ ...bar, time: t });
+      this.onDataChanged?.();
+      return;
+    }
+
+    const last = this._data[this._data.length - 1]!;
+
+    if (t === last.time) {
+      // ── 3a. Same candle: replace last element (OHLCV properties are readonly)
+      //    open stays untouched — never replace the candle's original open
+      this._data[this._data.length - 1] = {
+        time:   last.time,
+        open:   last.open,
+        high:   Math.max(last.high,  bar.high,  bar.close),
+        low:    Math.min(last.low,   bar.low,   bar.close),
+        close:  bar.close,
+        volume: bar.volume,
+      };
+    } else if (t > last.time) {
+      // ── 3b. New candle: append ───────────────────────────────────────────────
+      this._data.push({ ...bar, time: t });
+    }
+    // ── 3c. Out-of-order (t < last.time): silently discard ──────────────────
+
+    this.onDataChanged?.();
+  }
+
+  data(): readonly OHLCV[] {
+    return this._data;
+  }
+
+  applyOptions(options: Partial<SeriesOptions>): void {
+    this._options = { ...this._options, ...options } as SeriesOptions;
+  }
+
+  options(): SeriesOptions {
+    return this._options;
+  }
+
+  // ─── Rendering (called by Chart) ────────────────────────────────────────────
+
+  render(ctx: CanvasRenderingContext2D, viewport: Viewport, rect: Rect): void {
+    if (this._data.length === 0) return;
+    const visible = this._options.visible ?? true;
+    if (!visible) return;
+
+    const visibleData = this._getVisibleData(viewport);
+    if (visibleData.length === 0) return;
+
+    this._renderer.draw(ctx, visibleData, viewport, rect, this._options);
+  }
+
+  // ─── Private helpers ─────────────────────────────────────────────────────────
+
+  private _getVisibleData(viewport: Viewport): OHLCV[] {
+    const { from, to } = viewport.timeRange;
+    // Small margin so partial bars at edges are included
+    return this._data.filter((b) => b.time >= from - 1 && b.time <= to + 1);
+  }
+
+  private static _createRenderer(options: SeriesOptions, colors: ChartColors): IRenderer {
+    switch (options.type) {
+      case 'candlestick':
+      case 'heikinashi':
+      case 'bar':
+        return new CandlestickRenderer(colors);
+      case 'line':
+      case 'area':
+        return new LineRenderer(colors);
+      case 'histogram':
+        return new HistogramRenderer(colors);
+      default: {
+        const _exhaustive: never = options;
+        throw new Error(`[ForgeCharts] Unknown series type: ${JSON.stringify(_exhaustive)}`);
+      }
+    }
+  }
+}

package/src/core/TimeScale.ts

@@ -0,0 +1,175 @@
+import type { TimeRange, ChartColors, TimeScaleOptions, Timeframe } from '@forgecharts/types';
+import { mapRange, computeTicks } from '@forgecharts/utils';
+import { formatTimestampLabel } from '@forgecharts/utils';
+import type { CanvasLayer } from './CanvasLayer';
+
+const AXIS_HEIGHT = 30;
+
+/**
+ * TimeScale — manages the horizontal time axis.
+ * Handles pan/zoom of the visible time range and renders tick labels.
+ */
+export class TimeScale {
+  private _visibleRange: TimeRange;
+  private readonly _layer: CanvasLayer;
+  private readonly _colors: ChartColors;
+  private readonly _options: Required<TimeScaleOptions>;
+  private _activeTimeframe: Timeframe = '1h';
+  /** IANA timezone for axis labels. Falls back to UTC when unset. */
+  timezone: string | undefined = undefined;
+
+  constructor(layer: CanvasLayer, colors: ChartColors, options: TimeScaleOptions = {}) {
+    this._layer = layer;
+    this._colors = colors;
+    this._options = {
+      timeVisible: options.timeVisible ?? true,
+      secondsVisible: options.secondsVisible ?? false,
+      borderVisible: options.borderVisible ?? true,
+      ticksVisible: options.ticksVisible ?? true,
+      height: options.height ?? AXIS_HEIGHT,
+    };
+
+    const now = Math.floor(Date.now() / 1000);
+    this._visibleRange = { from: now - 86400, to: now };
+  }
+
+  get visibleRange(): TimeRange {
+    return this._visibleRange;
+  }
+
+  get height(): number {
+    return this._options.height;
+  }
+
+  get activeTimeframe(): Timeframe {
+    return this._activeTimeframe;
+  }
+
+  setVisibleRange(range: TimeRange): void {
+    this._visibleRange = range;
+  }
+
+  setTimeframe(tf: Timeframe): void {
+    this._activeTimeframe = tf;
+  }
+
+  /**
+   * Converts a Unix timestamp to a canvas X coordinate.
+   */
+  timeToX(time: number, canvasWidth: number): number {
+    const plotWidth = canvasWidth - this._priceScaleWidth();
+    return mapRange(time, this._visibleRange.from, this._visibleRange.to, 0, plotWidth);
+  }
+
+  /**
+   * Converts a canvas X coordinate back to a Unix timestamp.
+   */
+  xToTime(x: number, canvasWidth: number): number {
+    const plotWidth = canvasWidth - this._priceScaleWidth();
+    return mapRange(x, 0, plotWidth, this._visibleRange.from, this._visibleRange.to);
+  }
+
+  /**
+   * Zooms around a pivot X coordinate by a scale factor.
+   */
+  zoom(factor: number, pivotX: number, canvasWidth: number = this._layer.width): void {
+    const pivotTime = this.xToTime(pivotX, canvasWidth);
+    const span = this._visibleRange.to - this._visibleRange.from;
+    const newSpan = Math.max(60, span * factor);
+    const ratio = (pivotTime - this._visibleRange.from) / span;
+    const newFrom = pivotTime - ratio * newSpan;
+    this._visibleRange = { from: newFrom, to: newFrom + newSpan };
+  }
+
+  /**
+   * Scrolls by a delta in seconds.
+   */
+  scroll(deltaSeconds: number): void {
+    this._visibleRange = {
+      from: this._visibleRange.from + deltaSeconds,
+      to: this._visibleRange.to + deltaSeconds,
+    };
+  }
+
+  render(ctx: CanvasRenderingContext2D, width: number, height: number): void {
+    if (!this._options.ticksVisible) return;
+
+    const axisY = height - this._options.height;
+    const plotWidth = width - this._priceScaleWidth();
+
+    // Axis separator line
+    if (this._options.borderVisible) {
+      ctx.beginPath();
+      ctx.strokeStyle = this._colors.border;
+      ctx.lineWidth = 1;
+      ctx.moveTo(0, axisY);
+      ctx.lineTo(plotWidth, axisY);
+      ctx.stroke();
+    }
+
+    // Compute tick spacing — aim for a tick every ~100px
+    const approxTicks = Math.max(2, Math.floor(plotWidth / 100));
+    const span = this._visibleRange.to - this._visibleRange.from;
+    const rawStep = span / approxTicks;
+    const step = this._niceTimeStep(rawStep);
+
+    const startTime = Math.ceil(this._visibleRange.from / step) * step;
+
+    ctx.fillStyle = this._colors.text;
+    ctx.font = '11px system-ui, sans-serif';
+    ctx.textAlign = 'center';
+    ctx.textBaseline = 'middle';
+
+    for (let t = startTime; t <= this._visibleRange.to; t += step) {
+      const x = this.timeToX(t, width);
+      if (x < 0 || x > plotWidth) continue;
+
+      // Tick mark
+      ctx.beginPath();
+      ctx.strokeStyle = this._colors.border;
+      ctx.lineWidth = 1;
+      ctx.moveTo(x, axisY);
+      ctx.lineTo(x, axisY + 4);
+      ctx.stroke();
+
+      // Grid line
+      ctx.beginPath();
+      ctx.strokeStyle = this._colors.grid;
+      ctx.setLineDash([1, 3]);
+      ctx.moveTo(x, 0);
+      ctx.lineTo(x, axisY);
+      ctx.stroke();
+      ctx.setLineDash([]);
+
+      // Label
+      const label = formatTimestampLabel(t, step, this.timezone);
+      ctx.fillText(label, x, axisY + this._options.height / 2);
+    }
+  }
+
+  // ─── Private helpers ─────────────────────────────────────────────────────────
+
+  private _priceScaleWidth(): number {
+    return 70; // reserved for price scale — keep in sync with PriceScale
+  }
+
+  private _niceTimeStep(rawSeconds: number): number {
+    const nice = [
+      1, 5, 10, 30, 60, 300, 600, 900, 1800, 3600, 7200, 14400, 21600, 43200,
+      86400,           // 1 day
+      7   * 86400,     // 1 week
+      14  * 86400,     // 2 weeks
+      30  * 86400,     // ~1 month
+      91  * 86400,     // ~quarter
+      182 * 86400,     // ~half year
+      365 * 86400,     // ~1 year
+    ];
+    for (const s of nice) {
+      if (s >= rawSeconds) return s;
+    }
+    return 365 * 86400 * Math.ceil(rawSeconds / (365 * 86400));
+  }
+}
+
+// Re-export computeTicks so renderers can use it without an extra import
+export { computeTicks };