radiant-charts-core 0.2.0

package/src/series/ScatterSeries.ts

@@ -0,0 +1,305 @@
+import { Group, Circle, Marker, MarkerShape, Text } from '../scene/Shapes';
+import { formatAxisValue } from '../axes/CartesianAxis';
+import { Scale, BandScale, safeBandwidth } from '../scale/Scale';
+import { Animator } from '../core/Animator';
+
+export interface ScatterSeriesOptions {
+  xKey: string;
+  yKey: string;
+  sizeKey?: string;
+  fill?: string;
+  stroke?: string;
+  strokeWidth?: number;
+  marker?: {
+    size?: number;
+    fill?: string;
+  };
+  jitter?: number; // 0 to 1, fraction of bandwidth to jitter (default 0)
+  labels?: import('../RadiantChart').DataLabelOptions;
+  animation?: import('../RadiantChart').AnimationOptions;
+  shadow?: import('../RadiantChart').DropShadow;
+  markerShape?: 'circle' | 'square' | 'cross' | 'diamond' | 'triangle' | 'plus';
+}
+
+/**
+ * Point animation state: start and target values for a single marker.
+ */
+interface PointState {
+  startX: number; targetX: number;
+  startY: number; targetY: number;
+  startRadius: number; targetRadius: number;
+  startOpacity: number; targetOpacity: number;
+}
+
+/**
+ * ScatterSeries: Renders individual points (Scatter or Bubble charts).
+ *
+ * Uses an object-pool / diff strategy: existing Circle shapes are reused and
+ * their target positions are updated in-place, so the scene graph is not torn
+ * down and rebuilt on every update call. This makes streaming / real-time data
+ * significantly cheaper — only shape creation/removal happens at the boundary.
+ */
+export class ScatterSeries {
+  private group = new Group();
+  private xKey: string;
+  private yKey: string;
+  private sizeKey?: string;
+  private fill: string = '#4e79a7';
+  private stroke: string = '#fff';
+  private strokeWidth: number = 1;
+  private markerSize: number = 8;
+  private labelsOpts?: import('../RadiantChart').DataLabelOptions;
+  private animationOpts?: import('../RadiantChart').AnimationOptions;
+  private shadowOpts?: import('../RadiantChart').DropShadow;
+
+  private animator?: Animator;
+
+  /** Pooled marker nodes — one per data point, in data order. Polymorphic so
+   *  the markerShape option can switch between dot/square/cross/etc. */
+  private markers: Marker[] = [];
+  private markerShape: MarkerShape = 'circle';
+  /** Pooled label Text nodes (only populated when labelsOpts.enabled is true). */
+  private labelTexts: Text[] = [];
+  /** Per-marker animation state, parallel to this.markers. */
+  private points: PointState[] = [];
+
+  private jitter: number = 0;
+  /**
+   * Stable per-index jitter offsets so points don't jump laterally when data
+   * updates. Grown on demand; shrunk by truncation to preserve existing offsets.
+   */
+  private jitterOffsets: number[] = [];
+
+  constructor(options: ScatterSeriesOptions) {
+    this.xKey = options.xKey;
+    this.yKey = options.yKey;
+    this.sizeKey = options.sizeKey;
+    this.jitter = options.jitter ?? 0;
+    if (options.fill) this.fill = options.fill;
+    if (options.stroke) this.stroke = options.stroke;
+    if (options.strokeWidth !== undefined) this.strokeWidth = options.strokeWidth;
+    if (options.marker?.size !== undefined) this.markerSize = options.marker.size;
+    this.labelsOpts = options.labels;
+    this.animationOpts = options.animation;
+    this.shadowOpts = options.shadow;
+    if (options.markerShape) this.markerShape = options.markerShape;
+  }
+
+  getGroup() {
+    return this.group;
+  }
+
+  update(
+    data: readonly any[],
+    xScale: Scale<any, number>,
+    yScale: Scale<number, number>,
+    seriesRect: { x: number; y: number; width: number; height: number },
+    animate: boolean = true,
+    options?: ScatterSeriesOptions
+  ) {
+    if (options) {
+      this.xKey = options.xKey;
+      this.yKey = options.yKey;
+      if (options.sizeKey !== undefined) this.sizeKey = options.sizeKey;
+      if (options.fill) this.fill = options.fill;
+      if (options.stroke) this.stroke = options.stroke;
+      if (options.strokeWidth !== undefined) this.strokeWidth = options.strokeWidth;
+      if (options.marker?.size !== undefined) this.markerSize = options.marker.size;
+      if (options.jitter !== undefined) this.jitter = options.jitter;
+      if (options.labels) this.labelsOpts = options.labels;
+      if (options.animation) this.animationOpts = options.animation;
+      if (options.shadow !== undefined) this.shadowOpts = options.shadow;
+      if (options.markerShape) this.markerShape = options.markerShape;
+    }
+
+    // Stop any in-flight animation before reading current positions so the
+    // start values we capture reflect where each point actually is on screen.
+    if (this.animator) this.animator.stop();
+
+    if (data.length === 0) {
+      for (const m of this.markers)    this.group.remove(m);
+      for (const l of this.labelTexts) this.group.remove(l);
+      this.markers    = [];
+      this.labelTexts = [];
+      this.points     = [];
+      return;
+    }
+
+    // ── Jitter offsets: grow if needed, shrink by truncation ─────────────────
+    while (this.jitterOffsets.length < data.length) {
+      this.jitterOffsets.push((Math.random() - 0.5) * 2);
+    }
+    if (this.jitterOffsets.length > data.length) {
+      this.jitterOffsets.length = data.length;
+    }
+
+    // ── Size scale for bubble charts ─────────────────────────────────────────
+    let sizeScale = (_val: number) => this.markerSize / 2;
+    if (this.sizeKey) {
+      const sizes  = data.map(d => d[this.sizeKey!] || 0);
+      const maxSize = Math.max(...sizes);
+      sizeScale = (val: number) => (val / (maxSize || 1)) * this.markerSize;
+    }
+
+    const animType  = this.animationOpts?.type || 'pop';
+    const isInitial = this.points.length === 0;
+    const newPoints: PointState[] = [];
+
+    // ── Diff pass: update existing markers, create new ones ──────────────────
+    data.forEach((datum, i) => {
+      const xVal = datum[this.xKey];
+      const yVal = datum[this.yKey];
+      const sVal = this.sizeKey ? datum[this.sizeKey] : 0;
+
+      // Target pixel position
+      let tx: number;
+      if ('getBandwidth' in xScale) {
+        const bw   = safeBandwidth(xScale);
+        const joff = this.jitterOffsets[i] * (bw * this.jitter / 2);
+        tx = (xScale as BandScale).convert(xVal) + bw / 2 + joff;
+      } else {
+        tx = xScale.convert(xVal);
+      }
+      const ty = yScale.convert(yVal);
+      const tr = sizeScale(sVal);
+
+      let marker: Marker;
+      let sx: number, sy: number, sr: number, so: number;
+
+      if (i < this.markers.length) {
+        // ── Reuse existing marker ────────────────────────────────────────────
+        // Capture current rendered position as the animation start so that a
+        // mid-flight transition begins smoothly from where the dot actually is.
+        marker = this.markers[i];
+        sx = marker.centerX;
+        sy = marker.centerY;
+        sr = marker.radius;
+        so = marker.opacity;
+
+        // Update non-animated style properties
+        marker.fill        = this.fill;
+        marker.stroke      = this.stroke;
+        marker.strokeWidth = this.strokeWidth;
+        marker.shape       = this.markerShape;
+        marker.datum       = datum;
+        marker.seriesId    = this.yKey;
+        marker.shadow      = this.shadowOpts ?? null;
+      } else {
+        // ── Create and pool a new marker (enter transition) ──────────────────
+        marker = new Marker();
+        marker.fill        = this.fill;
+        marker.stroke      = this.stroke;
+        marker.strokeWidth = this.strokeWidth;
+        marker.shape       = this.markerShape;
+        marker.datum       = datum;
+        marker.seriesId    = this.yKey;
+        marker.shadow      = this.shadowOpts ?? null;
+        this.markers.push(marker);
+        this.group.add(marker);
+
+        // Entry start state — new points animate in from their entry position
+        if (isInitial && animType === 'grow') {
+          sx = tx; sy = seriesRect.height; sr = tr; so = 1;
+        } else if (isInitial && animType === 'fade') {
+          sx = tx; sy = ty; sr = tr; so = 0;
+        } else if (isInitial && animType === 'slide') {
+          sx = tx; sy = seriesRect.height + 20; sr = tr; so = 1;
+        } else {
+          // 'pop' (default) — and for new points added to an existing series
+          sx = tx; sy = ty; sr = 0; so = 0;
+        }
+
+        marker.centerX = sx;
+        marker.centerY = sy;
+        marker.radius  = sr;
+        marker.opacity = so;
+      }
+
+      newPoints.push({
+        startX: sx, targetX: tx,
+        startY: sy, targetY: ty,
+        startRadius: sr, targetRadius: tr,
+        startOpacity: so, targetOpacity: 1,
+      });
+    });
+
+    // ── Remove excess markers from the pool ──────────────────────────────────
+    if (this.markers.length > data.length) {
+      for (let i = data.length; i < this.markers.length; i++) {
+        this.group.remove(this.markers[i]);
+      }
+      this.markers.length = data.length;
+    }
+
+    // ── Sync label pool (parallel logic to markers) ───────────────────────────
+    const labelsEnabled = this.labelsOpts?.enabled ?? false;
+
+    if (labelsEnabled) {
+      // Grow label pool
+      while (this.labelTexts.length < data.length) {
+        const lbl = new Text();
+        lbl.textAlign    = 'center';
+        lbl.textBaseline = 'bottom';
+        lbl.x = 0;
+        lbl.y = 0;
+        this.labelTexts.push(lbl);
+        this.group.add(lbl);
+      }
+      // Shrink label pool
+      if (this.labelTexts.length > data.length) {
+        for (let i = data.length; i < this.labelTexts.length; i++) {
+          this.group.remove(this.labelTexts[i]);
+        }
+        this.labelTexts.length = data.length;
+      }
+      // Apply label style (may have changed with options update)
+      this.labelTexts.forEach((lbl, i) => {
+        const yVal = data[i][this.yKey];
+        lbl.text       = formatAxisValue(yVal);
+        lbl.fontSize   = this.labelsOpts?.fontSize   ?? 10;
+        lbl.fontFamily = this.labelsOpts?.fontFamily ?? 'sans-serif';
+        lbl.fontWeight = this.labelsOpts?.fontWeight ?? '600';
+        lbl.rotation   = ((this.labelsOpts?.rotation ?? 0) * Math.PI) / 180;
+        lbl.fill       = this.labelsOpts?.fill ?? this.fill;
+      });
+    } else {
+      // Labels disabled — clear the pool if it had items
+      if (this.labelTexts.length > 0) {
+        for (const l of this.labelTexts) this.group.remove(l);
+        this.labelTexts = [];
+      }
+    }
+
+    this.points = newPoints;
+
+    // ── Animate or snap to target ─────────────────────────────────────────────
+    const applyProgress = (p: number) => {
+      this.points.forEach((pt, i) => {
+        const marker = this.markers[i];
+        if (!marker) return;
+        const cx = pt.startX + (pt.targetX - pt.startX) * p;
+        const cy = pt.startY + (pt.targetY - pt.startY) * p;
+        const cr = pt.startRadius  + (pt.targetRadius  - pt.startRadius)  * p;
+        marker.centerX = cx;
+        marker.centerY = cy;
+        marker.radius  = cr;
+        marker.opacity = pt.startOpacity + (pt.targetOpacity - pt.startOpacity) * p;
+
+        if (labelsEnabled && this.labelTexts[i]) {
+          this.labelTexts[i].translation = { x: cx, y: cy - (cr + 5) };
+        }
+      });
+    };
+
+    if (animate && this.animationOpts?.enabled !== false) {
+      const duration = this.animationOpts?.duration ?? 600;
+      const easing   = Animator.getEasing(
+        this.animationOpts?.easing ?? (animType === 'pop' ? 'back' : 'easeOut')
+      );
+      this.animator = new Animator({ duration, easing, onUpdate: applyProgress });
+      this.animator.start();
+    } else {
+      applyProgress(1);
+    }
+  }
+}

package/src/tooltip/TooltipContext.ts

@@ -0,0 +1,22 @@
+// Radiant Charts — Tooltip React Context
+// Provides the TooltipStore to the React component tree.
+
+import { createContext, useContext } from 'react';
+import { TooltipStore } from './TooltipStore';
+
+export const TooltipStoreContext = createContext<TooltipStore | null>(null);
+
+/**
+ * Internal hook to read the TooltipStore from context.
+ * Throws if used outside of a TooltipStoreContext provider.
+ */
+export function useTooltipStore(): TooltipStore {
+  const store = useContext(TooltipStoreContext);
+  if (!store) {
+    throw new Error(
+      'useTooltipStore must be used within a RadiantChart or Chart component. ' +
+      'Make sure your component is wrapped in a chart provider.'
+    );
+  }
+  return store;
+}

package/src/tooltip/TooltipStore.ts

@@ -0,0 +1,169 @@
+// Radiant Charts — Tooltip State Store
+// Framework-agnostic pub/sub store consumable by React (useSyncExternalStore) and the canvas engine.
+
+import { TooltipState, TooltipOptions, TooltipDatumEntry, DEFAULT_TOOLTIP_STATE } from './types';
+
+type Listener = () => void;
+
+export class TooltipStore {
+  private _state: TooltipState = { ...DEFAULT_TOOLTIP_STATE };
+  private _listeners = new Set<Listener>();
+  private _options: TooltipOptions = {};
+  private _showTimer: ReturnType<typeof setTimeout> | null = null;
+  private _hideTimer: ReturnType<typeof setTimeout> | null = null;
+  private _pendingActivation: (() => void) | null = null;
+
+  // ── Public API ──────────────────────────────────────────────────────────────
+
+  getState(): TooltipState {
+    return this._state;
+  }
+
+  getOptions(): TooltipOptions {
+    return this._options;
+  }
+
+  setOptions(options: TooltipOptions) {
+    this._options = options;
+  }
+
+  subscribe(listener: Listener): () => void {
+    this._listeners.add(listener);
+    return () => { this._listeners.delete(listener); };
+  }
+
+  /**
+   * Activate the tooltip with the given entries and position.
+   * Respects delay.show if configured.
+   */
+  activate(
+    entries: TooltipDatumEntry[],
+    pointer: { x: number; y: number },
+    anchor: { x: number; y: number },
+    local: { x: number; y: number },
+    sharedLabel: string | null,
+  ) {
+    if (this._options.enabled === false) return;
+
+    this._clearHideTimer();
+
+    const doActivate = () => {
+      this._setState({
+        active: true,
+        pointerX: pointer.x,
+        pointerY: pointer.y,
+        anchorX: anchor.x,
+        anchorY: anchor.y,
+        localX: local.x,
+        localY: local.y,
+        entries,
+        sharedLabel,
+      });
+    };
+
+    const showDelay = this._options.delay?.show ?? 0;
+    if (showDelay > 0) {
+      this._clearShowTimer();
+      this._pendingActivation = doActivate;
+      this._showTimer = setTimeout(() => {
+        this._pendingActivation?.();
+        this._pendingActivation = null;
+        this._showTimer = null;
+      }, showDelay);
+    } else {
+      doActivate();
+    }
+  }
+
+  /**
+   * Deactivate the tooltip. Respects delay.hide if configured.
+   */
+  deactivate() {
+    this._clearShowTimer();
+    this._pendingActivation = null;
+
+    const hideDelay = this._options.delay?.hide ?? 0;
+    if (hideDelay > 0 && this._state.active) {
+      this._hideTimer = setTimeout(() => {
+        this._doDeactivate();
+        this._hideTimer = null;
+      }, hideDelay);
+    } else {
+      this._doDeactivate();
+    }
+  }
+
+  /**
+   * Update only the pointer position (for follow-pointer mode).
+   */
+  updatePointer(x: number, y: number) {
+    if (!this._state.active) return;
+    this._setState({
+      ...this._state,
+      pointerX: x,
+      pointerY: y,
+    });
+  }
+
+  /**
+   * Notify subscribers that the chart has resized.
+   * The portal will recompute its position on next paint.
+   */
+  notifyResize() {
+    if (this._state.active) {
+      this._notify();
+    }
+  }
+
+  /**
+   * Force-hide the tooltip regardless of state.
+   */
+  hide() {
+    this._clearShowTimer();
+    this._clearHideTimer();
+    this._pendingActivation = null;
+    this._doDeactivate(true);
+  }
+
+  /**
+   * Clean up timers and listeners.
+   */
+  destroy() {
+    this.hide();
+    this._listeners.clear();
+  }
+
+  // ── Private ─────────────────────────────────────────────────────────────────
+
+  private _setState(next: TooltipState) {
+    this._state = next;
+    this._notify();
+  }
+
+  private _notify() {
+    for (const listener of this._listeners) {
+      listener();
+    }
+  }
+
+  private _doDeactivate(force = false) {
+    if (!this._state.active && !force) return;
+    this._setState({
+      ...DEFAULT_TOOLTIP_STATE,
+    });
+  }
+
+  private _clearShowTimer() {
+    if (this._showTimer !== null) {
+      clearTimeout(this._showTimer);
+      this._showTimer = null;
+    }
+  }
+
+  private _clearHideTimer() {
+    if (this._hideTimer !== null) {
+      clearTimeout(this._hideTimer);
+      this._hideTimer = null;
+    }
+  }
+}

package/src/tooltip/__tests__/TooltipStore.test.ts

@@ -0,0 +1,176 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { TooltipStore } from '../TooltipStore';
+import { TooltipDatumEntry } from '../types';
+
+function makeEntry(overrides?: Partial<TooltipDatumEntry>): TooltipDatumEntry {
+  return {
+    seriesIndex: 0,
+    seriesId: 's0',
+    seriesType: 'line',
+    title: 'Series 0',
+    color: '#6366f1',
+    datum: { x: 'Jan', y: 42 },
+    dataIndex: 0,
+    xValue: 'Jan',
+    yValue: 42,
+    ...overrides,
+  };
+}
+
+const POINTER = { x: 100, y: 200 };
+const ANCHOR = { x: 110, y: 210 };
+const LOCAL = { x: 50, y: 60 };
+
+describe('TooltipStore', () => {
+  let store: TooltipStore;
+
+  beforeEach(() => {
+    store = new TooltipStore();
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    store.destroy();
+    vi.useRealTimers();
+  });
+
+  // ── Basic activate/deactivate ──────────────────────────
+
+  it('starts inactive', () => {
+    const s = store.getState();
+    expect(s.active).toBe(false);
+    expect(s.entries).toEqual([]);
+  });
+
+  it('activates with entries and positions', () => {
+    const entry = makeEntry();
+    store.activate([entry], POINTER, ANCHOR, LOCAL, 'Jan');
+    const s = store.getState();
+    expect(s.active).toBe(true);
+    expect(s.entries).toHaveLength(1);
+    expect(s.entries[0].yValue).toBe(42);
+    expect(s.pointerX).toBe(100);
+    expect(s.anchorX).toBe(110);
+    expect(s.localX).toBe(50);
+    expect(s.sharedLabel).toBe('Jan');
+  });
+
+  it('deactivates', () => {
+    store.activate([makeEntry()], POINTER, ANCHOR, LOCAL, null);
+    store.deactivate();
+    expect(store.getState().active).toBe(false);
+    expect(store.getState().entries).toEqual([]);
+  });
+
+  it('does not activate when enabled=false', () => {
+    store.setOptions({ enabled: false });
+    store.activate([makeEntry()], POINTER, ANCHOR, LOCAL, null);
+    expect(store.getState().active).toBe(false);
+  });
+
+  // ── Subscribe / Notify ─────────────────────────────────
+
+  it('notifies subscribers on activate', () => {
+    const listener = vi.fn();
+    store.subscribe(listener);
+    store.activate([makeEntry()], POINTER, ANCHOR, LOCAL, null);
+    expect(listener).toHaveBeenCalledTimes(1);
+  });
+
+  it('unsubscribe stops notifications', () => {
+    const listener = vi.fn();
+    const unsub = store.subscribe(listener);
+    unsub();
+    store.activate([makeEntry()], POINTER, ANCHOR, LOCAL, null);
+    expect(listener).toHaveBeenCalledTimes(0);
+  });
+
+  // ── Delay ──────────────────────────────────────────────
+
+  it('show delay defers activation', () => {
+    store.setOptions({ delay: { show: 200 } });
+    store.activate([makeEntry()], POINTER, ANCHOR, LOCAL, null);
+    expect(store.getState().active).toBe(false);
+
+    vi.advanceTimersByTime(200);
+    expect(store.getState().active).toBe(true);
+  });
+
+  it('hide delay defers deactivation', () => {
+    store.setOptions({ delay: { hide: 150 } });
+    store.activate([makeEntry()], POINTER, ANCHOR, LOCAL, null);
+    store.deactivate();
+    expect(store.getState().active).toBe(true);
+
+    vi.advanceTimersByTime(150);
+    expect(store.getState().active).toBe(false);
+  });
+
+  it('activating during show delay resets the timer', () => {
+    store.setOptions({ delay: { show: 200 } });
+    store.activate([makeEntry({ yValue: 1 })], POINTER, ANCHOR, LOCAL, null);
+    vi.advanceTimersByTime(100);
+    expect(store.getState().active).toBe(false);
+
+    store.activate([makeEntry({ yValue: 2 })], POINTER, ANCHOR, LOCAL, null);
+    vi.advanceTimersByTime(100);
+    expect(store.getState().active).toBe(false);
+
+    vi.advanceTimersByTime(100);
+    expect(store.getState().active).toBe(true);
+  });
+
+  // ── updatePointer ──────────────────────────────────────
+
+  it('updatePointer changes pointerX/Y when active', () => {
+    store.activate([makeEntry()], POINTER, ANCHOR, LOCAL, null);
+    store.updatePointer(300, 400);
+    expect(store.getState().pointerX).toBe(300);
+    expect(store.getState().pointerY).toBe(400);
+  });
+
+  it('updatePointer is no-op when inactive', () => {
+    const listener = vi.fn();
+    store.subscribe(listener);
+    store.updatePointer(300, 400);
+    expect(listener).not.toHaveBeenCalled();
+  });
+
+  // ── notifyResize ───────────────────────────────────────
+
+  it('notifyResize notifies when active', () => {
+    store.activate([makeEntry()], POINTER, ANCHOR, LOCAL, null);
+    const listener = vi.fn();
+    store.subscribe(listener);
+    store.notifyResize();
+    expect(listener).toHaveBeenCalledTimes(1);
+  });
+
+  it('notifyResize is silent when inactive', () => {
+    const listener = vi.fn();
+    store.subscribe(listener);
+    store.notifyResize();
+    expect(listener).not.toHaveBeenCalled();
+  });
+
+  // ── hide (force) ───────────────────────────────────────
+
+  it('hide force-deactivates', () => {
+    store.activate([makeEntry()], POINTER, ANCHOR, LOCAL, null);
+    store.hide();
+    expect(store.getState().active).toBe(false);
+  });
+
+  // ── destroy ────────────────────────────────────────────
+
+  it('destroy clears listeners and timers', () => {
+    const listener = vi.fn();
+    store.subscribe(listener);
+    store.setOptions({ delay: { show: 100 } });
+    store.activate([makeEntry()], POINTER, ANCHOR, LOCAL, null);
+    store.destroy();
+
+    vi.advanceTimersByTime(200);
+    expect(listener).not.toHaveBeenCalled();
+  });
+});