wickchart-compare 0.1.0

package/README.md

@@ -0,0 +1,48 @@
+# wickchart-compare
+
+Normalized multi-asset overlays for [wickchart](https://github.com/benyblack/wickchart),
+as an opt-in plugin layer — the core stays compare-free. Zero dependencies,
+zero core changes: the lines draw through the public layer API against their
+own invisible scale, so the price axis is never distorted.
+
+Two kinds of entries:
+
+- **Percent lines** — a close series rebased to 0% (TradingView-style
+  compare overlay), drawn as a colored line over the main pane.
+- **Derived lines** — `ratio` (a/b) or `diff` (a−b) of two series,
+  the `formula="BTC/ETH"` use case, rebased the same way; the legend chip
+  shows the raw ratio/diff value.
+
+```js
+npm install wickchart wickchart-compare   // the plugin is a separate package
+
+import 'wickchart';                          // the chart itself
+import { attachCompare } from 'wickchart-compare';
+
+const chart = document.querySelector('wick-chart');
+const cmp = attachCompare(chart);
+
+cmp.setSeries([
+  { label: 'ETH', data: ethBars },                              // OHLC or {time, value}
+  { label: 'SOL', data: solBars, color: '#22d3ee', width: 2 },
+  { label: 'BTC/ETH', op: 'ratio', a: btcBars, b: ethBars },    // derived
+  { label: 'BTC−ETH', op: 'diff', a: btcBars, b: ethBars },
+]);
+cmp.setRebase('visible');  // 0% at the window's left edge, re-normalized as
+                           // you pan (TV-style); 'first' = dataset start;
+                           // or an epoch-ms anchor
+cmp.clear();               // remove all lines
+cmp.detach();
+```
+
+- **Time alignment**: every series is sampled onto the main chart's bar
+  times (last known value at-or-before each bar), so timeframes can mix and
+  gaps break the line instead of bridging.
+- **Legend**: a chip row under the core legend shows each series with its
+  live value (`ETH +3.24%`, `BTC/ETH 1543.2`), recomputed every frame.
+- **Scale**: rebased values share one invisible scale inset 8% from the
+  pane's top/bottom edges; the main chart's price scale is untouched.
+- Series are validated and capped at 6; invalid entries are dropped, never
+  thrown.
+
+Peer dependency: wickchart ≥ 1.4.0 (the plugin layer API).

package/compare.mjs

@@ -0,0 +1,200 @@
+/**
+ * wickchart-compare — normalized multi-asset overlays as a wickchart plugin
+ * layer: percent-rebased close series (compare="ETH"-style lines) and
+ * derived ratio / diff lines (formula="BTC/ETH"-style), drawn over the main
+ * pane against their own invisible scale so the price axis is untouched.
+ * Everything builds on the public layer API (addLayer) — zero core changes.
+ *
+ *   import { attachCompare } from 'wickchart-compare';
+ *   const cmp = attachCompare(chart);
+ *   cmp.setSeries([
+ *     { label: 'ETH', data: ethBars },                    // % line (closes)
+ *     { label: 'BTC/ETH', op: 'ratio', a: btcBars, b: ethBars },
+ *     { label: 'BTC−ETH', op: 'diff', a: btcBars, b: ethBars },
+ *   ]);
+ *   cmp.setRebase('visible');   // 0% at the window's left edge (TV-style);
+ *                               // 'first' (dataset start) or an epoch ms
+ *   cmp.clear();  cmp.detach();
+ *
+ * A legend row under the core legend shows every series with its live value
+ * (+3.2% for percent lines, the raw ratio/diff for derived ones). Series are
+ * time-aligned onto the main chart's bars, so any timeframes can mix.
+ */
+
+import { normalizeSeries, computeLine, timeWindow, DEFAULT_COLORS } from './core.mjs';
+
+const FONT = '600 10px ui-sans-serif, system-ui, sans-serif';
+const PAD_FRAC = 0.08; // keep rebased lines off the pane's top/bottom edges
+
+const isNum = (v) => typeof v === 'number' && Number.isFinite(v);
+
+/** Compact value formatting for legend chips (ratio/diff raw values). */
+function fmtV(v) {
+  const a = Math.abs(v);
+  return a >= 1000 ? v.toFixed(0) : a >= 100 ? v.toFixed(1) : a >= 1 ? v.toFixed(3) : v.toFixed(4);
+}
+
+const normRebase = (r) => (r === 'visible' || r === 'first' || isNum(r) ? r : 'first');
+
+export function attachCompare(chart, opts = {}) {
+  return new CompareLayer(chart, opts);
+}
+
+export class CompareLayer {
+  constructor(chart, opts = {}) {
+    if (!chart || typeof chart.addLayer !== 'function') {
+      throw new TypeError('attachCompare(chart): the chart element is required');
+    }
+    this._chart = chart;
+    this._defs = normalizeSeries(opts.series);
+    this._rebase = normRebase(opts.rebase);
+    this._layer = { id: 'wick-compare', draw: (api) => this._render(api) };
+    chart.addLayer(this._layer);
+  }
+
+  /* ---------------- public API ---------------- */
+
+  /** Replace the compare entries (validated; invalid entries are dropped). */
+  setSeries(list) {
+    this._defs = normalizeSeries(list);
+    this._redraw();
+    return this;
+  }
+
+  /** Rebase mode: 'visible' | 'first' | epoch-ms number. */
+  setRebase(r) {
+    this._rebase = normRebase(r);
+    this._redraw();
+    return this;
+  }
+
+  get rebase() {
+    return this._rebase;
+  }
+
+  get count() {
+    return this._defs.length;
+  }
+
+  clear() {
+    this._defs = [];
+    this._redraw();
+    return this;
+  }
+
+  detach() {
+    try {
+      this._chart.removeLayer('wick-compare');
+    } catch (_) {}
+    this._chart = null;
+  }
+
+  /* ---------------- render ---------------- */
+
+  _redraw() {
+    if (this._chart && typeof this._chart.requestDraw === 'function') this._chart.requestDraw();
+  }
+
+  _colorOf(def, pal, i) {
+    if (def.color === 'up' || def.color === 'down' || def.color === 'accent') return pal[def.color];
+    if (def.color) return def.color;
+    return DEFAULT_COLORS[i % DEFAULT_COLORS.length];
+  }
+
+  _render(api) {
+    const { ctx, layout, palette: pal, data } = api;
+    if (!data.length || !this._defs.length) return;
+    const main = layout.main;
+    const t0 = api.xToTime(0);
+    const t1 = api.xToTime(layout.plotRight);
+    if (!isNum(t0) || !isNum(t1) || t1 <= t0) return;
+    const win = timeWindow(data, t0, t1);
+    if (!win) return;
+
+    // one rebased line per entry, aligned onto the main chart's bar times
+    const times = [];
+    for (let i = win[0]; i <= win[1]; i++) times.push(data[i].time);
+    const lines = this._defs.map((def) => computeLine(def, times, this._rebase));
+
+    // shared invisible scale: the union of all rebased values in view
+    let min = Infinity;
+    let max = -Infinity;
+    for (const line of lines) {
+      for (const p of line) {
+        if (p && isNum(p.pct)) {
+          if (p.pct < min) min = p.pct;
+          if (p.pct > max) max = p.pct;
+        }
+      }
+    }
+    if (!isNum(min) || !isNum(max)) return;
+    const pad = main.h * PAD_FRAC;
+    const span = max - min || 1;
+    const yOf = (pct) => main.y0 + pad + ((max - pct) / span) * (main.h - 2 * pad);
+
+    ctx.save();
+    ctx.beginPath();
+    ctx.rect(0, main.y0, layout.plotRight + 1, main.h);
+    ctx.clip();
+    ctx.globalAlpha = 0.9;
+
+    lines.forEach((line, si) => {
+      const color = this._colorOf(this._defs[si], pal, si);
+      ctx.strokeStyle = color;
+      ctx.lineWidth = this._defs[si].width || 1.5;
+      ctx.beginPath();
+      let started = false;
+      for (const p of line) {
+        if (!p || !isNum(p.pct)) {
+          started = false; // gap in the series — break the stroke
+          continue;
+        }
+        const x = api.timeToX(p.t);
+        const y = yOf(p.pct);
+        if (!isNum(x) || !isNum(y)) continue;
+        if (!started) {
+          ctx.moveTo(x, y);
+          started = true;
+        } else {
+          ctx.lineTo(x, y);
+        }
+      }
+      ctx.stroke();
+    });
+    ctx.restore();
+    ctx.globalAlpha = 1;
+
+    this._legend(ctx, api, lines, pal);
+  }
+
+  /** One chip per series: color square + label + live value. */
+  _legend(ctx, api, lines, pal) {
+    ctx.save();
+    ctx.font = FONT;
+    ctx.textAlign = 'left';
+    ctx.textBaseline = 'middle';
+    const xMax = api.layout.plotRight - 40;
+    let x = 10;
+    const y = api.layout.main.y0 + 28;
+    for (let si = 0; si < this._defs.length; si++) {
+      const def = this._defs[si];
+      const last = [...lines[si]].reverse().find((p) => p && isNum(p.pct));
+      if (!last) continue;
+      if (x > xMax) break; // out of room — later chips are skipped this frame
+      const color = this._colorOf(def, pal, si);
+      const value = def.op === 'percent'
+        ? `${last.pct >= 0 ? '+' : ''}${last.pct.toFixed(2)}%`
+        : fmtV(last.raw);
+      const text = `${def.label} ${value}`;
+      ctx.fillStyle = color;
+      ctx.fillRect(x, y - 2, 6, 6);
+      ctx.strokeStyle = pal.bg;
+      ctx.lineWidth = 3;
+      ctx.strokeText(text, x + 10, y);
+      ctx.fillStyle = color;
+      ctx.fillText(text, x + 10, y);
+      x += 16 + ctx.measureText(text).width;
+    }
+    ctx.restore();
+  }
+}

package/core.mjs

@@ -0,0 +1,141 @@
+/**
+ * wickchart-compare — pure compare model: normalization, time alignment and
+ * rebasing math. No DOM, no canvas; everything is unit-testable plain data
+ * in / data out.
+ */
+
+export const MAX_SERIES = 6;
+
+/** Fill/stroke tints cycled per series — read on dark and light themes. */
+export const DEFAULT_COLORS = ['#f0b90b', '#a78bfa', '#16c784', '#22d3ee', '#ea3943', '#4c8dff'];
+
+const HEX = /^#(?:[0-9a-f]{3}|[0-9a-f]{6})$/i;
+const OPS = new Set(['ratio', 'diff']);
+const isNum = (v) => typeof v === 'number' && Number.isFinite(v);
+
+const toMs = (t) => (t < 1e12 ? t * 1000 : t);
+
+/**
+ * Close/value pairs [[ms, v], …] sorted by time; null when nothing valid.
+ * Accepts OHLC bars ({ time, close }) and plain series ({ time, value }).
+ */
+function closes(bars) {
+  if (!Array.isArray(bars) || !bars.length) return null;
+  const out = [];
+  for (const b of bars) {
+    if (!b || typeof b !== 'object') continue;
+    const t = Number(b.time);
+    const v = Number(b.close != null ? b.close : b.value);
+    if (!isNum(t) || !isNum(v)) continue;
+    out.push([toMs(t), v]);
+  }
+  if (!out.length) return null;
+  out.sort((x, y) => x[0] - y[0]);
+  return out;
+}
+
+/** Last sample at or before t (binary search); null when t precedes the first. */
+export function sampleAt(samples, t) {
+  let lo = 0;
+  let hi = samples.length - 1;
+  if (t < samples[0][0]) return null;
+  while (lo < hi) {
+    const mid = (lo + hi + 1) >> 1;
+    if (samples[mid][0] <= t) lo = mid;
+    else hi = mid - 1;
+  }
+  return samples[lo][1];
+}
+
+/** Align b onto a's timestamps: ratio (a/b) or diff (a−b) per shared time. */
+function mergeOp(a, b, op) {
+  const out = [];
+  for (const [t, va] of a) {
+    const vb = sampleAt(b, t);
+    if (vb == null || vb === 0) continue; // no denominator before b starts
+    out.push([t, op === 'ratio' ? va / vb : va - vb]);
+  }
+  return out;
+}
+
+/**
+ * Validate + clamp a list of raw compare entries. Invalid entries are
+ * dropped (never throw) — same contract as normalizeDrawings /
+ * normalizeSessions in the other plugins.
+ *
+ * Entry shape:
+ *   { label, data, color?, width? }            → percent line (close series)
+ *   { label, a, b, op: 'ratio'|'diff', … }     → derived line
+ * color: hex or 'up'/'down'/'accent' (resolved against the palette at draw).
+ * An invalid `op` falls through to the percent path.
+ */
+export function normalizeSeries(list) {
+  if (!Array.isArray(list)) return [];
+  const out = [];
+  for (const raw of list) {
+    if (!raw || typeof raw !== 'object') continue;
+    if (out.length >= MAX_SERIES) break;
+    const label = typeof raw.label === 'string' ? raw.label.trim().slice(0, 24) : '';
+    if (!label) continue;
+    const op = OPS.has(raw.op) ? raw.op : null;
+    let samples = null;
+    if (op) samples = mergeOp(closes(raw.a), closes(raw.b), op);
+    else samples = closes(raw.data);
+    if (!samples || !samples.length) continue;
+    const color = typeof raw.color === 'string' && (['up', 'down', 'accent'].includes(raw.color) || HEX.test(raw.color))
+      ? raw.color
+      : null;
+    const width = isNum(raw.width) ? Math.min(4, Math.max(1, raw.width)) : null;
+    out.push({ label, op: op || 'percent', samples, color, width });
+  }
+  return out;
+}
+
+/** [firstIndex, lastIndex] of data (sorted by time) inside [t0, t1]. */
+export function timeWindow(data, t0, t1) {
+  const n = data.length;
+  if (!n || t1 < data[0].time || t0 > data[n - 1].time) return null;
+  let lo = 0;
+  let hi = n - 1;
+  while (lo < hi) {
+    const mid = (lo + hi) >> 1;
+    if (data[mid].time < t0) lo = mid + 1;
+    else hi = mid;
+  }
+  const i0 = lo;
+  if (data[i0].time > t1) return null; // window falls inside a data gap
+  hi = n - 1;
+  while (lo < hi) {
+    const mid = (lo + hi + 1) >> 1;
+    if (data[mid].time <= t1) lo = mid;
+    else hi = mid - 1;
+  }
+  return [i0, lo];
+}
+
+/**
+ * Rebased points for one entry over the main chart's bar times.
+ * rebase: 'visible' → 0% at the first sampled time in the window;
+ *         'first'   → 0% at the entry's own first sample;
+ *         number    → 0% sampled at that epoch (falls back to first sample).
+ * Returns [{ t, pct, raw } | null] — null where the series has no sample yet.
+ */
+export function computeLine(entry, times, rebase) {
+  const { samples } = entry;
+  const raws = [];
+  for (const t of times) {
+    const v = sampleAt(samples, t);
+    raws.push(v == null ? null : { t, raw: v });
+  }
+  let anchor;
+  if (typeof rebase === 'number' && isNum(rebase)) {
+    const at = sampleAt(samples, rebase);
+    anchor = at == null ? samples[0][1] : at;
+  } else if (rebase === 'visible') {
+    const first = raws.find((r) => r);
+    anchor = first ? first.raw : samples[0][1];
+  } else {
+    anchor = samples[0][1];
+  }
+  return raws.map((r) => (r && anchor !== 0 ? { t: r.t, pct: (r.raw / anchor - 1) * 100, raw: r.raw } : null));
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "wickchart-compare",
+  "version": "0.1.0",
+  "description": "Normalized multi-asset compare overlays for wickchart — percent-rebased series and derived ratio/diff lines (BTC/ETH-style) with a live legend. Opt-in plugin, zero dependencies.",
+  "type": "module",
+  "main": "compare.mjs",
+  "module": "compare.mjs",
+  "exports": {
+    ".": "./compare.mjs",
+    "./core": "./core.mjs"
+  },
+  "files": [
+    "compare.mjs",
+    "core.mjs",
+    "README.md"
+  ],
+  "keywords": [
+    "chart",
+    "charting",
+    "compare",
+    "overlay",
+    "spread",
+    "ratio",
+    "trading",
+    "web-component",
+    "wickchart",
+    "canvas",
+    "crypto"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "wickchart": ">=1.4.0"
+  },
+  "peerDependenciesMeta": {
+    "wickchart": {
+      "optional": true
+    }
+  }
+}