radiant-charts-core 0.2.0

package/src/series/LineSeries.ts

@@ -0,0 +1,284 @@
+// Radiant Charts - LineSeries
+// Phase 2.1: Standard, Step, and Smooth (Catmull-Rom spline) line variants
+
+import { Group, Path, Marker, PathPoint, Text } from '../scene/Shapes';
+import { formatAxisValue } from '../axes/CartesianAxis';
+import { Scale, BandScale, safeBandwidth } from '../scale/Scale';
+import { Animator } from '../core/Animator';
+
+export interface LineSeriesOptions {
+  xKey: string;
+  yKey: string;
+  title?: string;
+  stroke?: string;
+  strokeWidth?: number;
+  /** 'linear' | 'step' | 'smooth' */
+  interpolation?: 'linear' | 'step' | 'smooth';
+  /** @deprecated use interpolation:'step' */
+  step?: boolean;
+  marker?: {
+    enabled?: boolean;
+    size?: number;
+    fill?: string;
+  };
+  labels?: import('../RadiantChart').DataLabelOptions;
+  animation?: import('../RadiantChart').AnimationOptions;
+  shadow?: import('../RadiantChart').DropShadow;
+  /** When false, the line is severed at any null/NaN datapoint instead of bridging the gap. Default: true. */
+  connectMissingData?: boolean;
+  /** Configurable marker shape. Shape overrides the legacy dot-only renderer. */
+  markerShape?: 'circle' | 'square' | 'cross' | 'diamond' | 'triangle' | 'plus';
+}
+
+/** Catmull-Rom → cubic Bezier control points (maintains C1 continuity) */
+function catmullRomToBezier(
+  pts: { x: number; y: number }[]
+): PathPoint[] {
+  if (pts.length === 0) return [];
+  const result: PathPoint[] = [{ command: 'M', x: pts[0].x, y: pts[0].y }];
+
+  for (let i = 1; i < pts.length; i++) {
+    const p0 = pts[Math.max(i - 2, 0)];
+    const p1 = pts[i - 1];
+    const p2 = pts[i];
+    const p3 = pts[Math.min(i + 1, pts.length - 1)];
+
+    result.push({
+      command: 'C',
+      cp1x: p1.x + (p2.x - p0.x) / 6,
+      cp1y: p1.y + (p2.y - p0.y) / 6,
+      cp2x: p2.x - (p3.x - p1.x) / 6,
+      cp2y: p2.y - (p3.y - p1.y) / 6,
+      x: p2.x,
+      y: p2.y,
+    });
+  }
+  return result;
+}
+
+export class LineSeries {
+  private group = new Group();
+  private xKey: string;
+  private yKey: string;
+  private stroke: string = '#4e79a7';
+  private strokeWidth: number = 2;
+  private interpolation: 'linear' | 'step' | 'smooth';
+  private markerOpts = { enabled: true, size: 6, fill: '' };
+  private labelsOpts?: import('../RadiantChart').DataLabelOptions;
+  private animationOpts?: import('../RadiantChart').AnimationOptions;
+  private shadowOpts?: import('../RadiantChart').DropShadow;
+  private connectMissingData: boolean = true;
+  private markerShape: 'circle' | 'square' | 'cross' | 'diamond' | 'triangle' | 'plus' = 'circle';
+  private animator?: Animator;
+  private linePath: Path = new Path();
+
+  constructor(options: LineSeriesOptions) {
+    this.xKey = options.xKey;
+    this.yKey = options.yKey;
+    // legacy 'step' boolean support
+    const legacy = options.step ? 'step' : 'linear';
+    this.interpolation = options.interpolation ?? legacy;
+    if (options.stroke) this.stroke = options.stroke;
+    if (options.strokeWidth) this.strokeWidth = options.strokeWidth;
+    if (options.marker) this.markerOpts = { ...this.markerOpts, ...options.marker };
+    this.markerOpts.fill = this.markerOpts.fill || this.stroke;
+    this.labelsOpts = options.labels;
+    this.animationOpts = options.animation;
+    this.shadowOpts = options.shadow;
+    this.connectMissingData = options.connectMissingData ?? true;
+    this.markerShape = options.markerShape ?? 'circle';
+  }
+
+  getGroup() { return this.group; }
+
+  update(
+    data: readonly any[],
+    xScale: BandScale | Scale<any, number>,
+    yScale: Scale<number, number>,
+    _seriesRect: { x: number; y: number; width: number; height: number },
+    animate: boolean = true,
+    options?: LineSeriesOptions
+  ) {
+    if (options) {
+      this.xKey = options.xKey;
+      this.yKey = options.yKey;
+      if (options.stroke) this.stroke = options.stroke;
+      if (options.strokeWidth !== undefined) this.strokeWidth = options.strokeWidth;
+      if (options.interpolation) this.interpolation = options.interpolation;
+      if (options.marker) this.markerOpts = { ...this.markerOpts, ...options.marker };
+      if (options.labels) this.labelsOpts = options.labels;
+      if (options.animation) this.animationOpts = options.animation;
+      if (options.shadow !== undefined) this.shadowOpts = options.shadow;
+      if (options.connectMissingData !== undefined) this.connectMissingData = options.connectMissingData;
+      if (options.markerShape) this.markerShape = options.markerShape;
+    }
+
+    this.group.clear();
+    if (data.length === 0) return;
+
+    // Continuous X scales (LinearScale, TimeScale) — used by grid-sync mode —
+    // don't implement getBandwidth(). safeBandwidth() returns 0 for those so
+    // points center directly at the converted X pixel; BandScale still gets
+    // its half-band offset.
+    const pts = data.map(d => {
+      const raw = d[this.yKey];
+      const missing = raw === null || raw === undefined || (typeof raw === 'number' && isNaN(raw));
+      const bw = safeBandwidth(xScale);
+      return {
+        x: (xScale as Scale<any, number>).convert(d[this.xKey]) + bw / 2,
+        y: yScale.convert(missing ? 0 : raw),
+        datum: d,
+        missing,
+      };
+    });
+
+    // ─ Build path ─
+    const path = this.linePath;
+    path.pathData = [];
+    path.stroke = this.stroke;
+    path.strokeWidth = this.strokeWidth;
+    path.shadow = this.shadowOpts ?? null;
+
+    // Split into contiguous non-missing runs when gap-skipping is requested.
+    // Each run becomes its own sub-path (started by an 'M' command) so the
+    // line is visually severed at any null/NaN datum.
+    const runs: typeof pts[] = [];
+    if (this.connectMissingData) {
+      runs.push(pts.filter(p => !p.missing));
+    } else {
+      let current: typeof pts = [];
+      pts.forEach(p => {
+        if (p.missing) {
+          if (current.length > 0) { runs.push(current); current = []; }
+        } else {
+          current.push(p);
+        }
+      });
+      if (current.length > 0) runs.push(current);
+    }
+
+    runs.forEach(run => {
+      if (run.length === 0) return;
+      if (this.interpolation === 'smooth') {
+        path.pathData.push(...catmullRomToBezier(run));
+      } else if (this.interpolation === 'step') {
+        run.forEach((p, i) => {
+          if (i === 0) {
+            path.pathData.push({ command: 'M', x: p.x, y: p.y });
+          } else {
+            const prev = path.pathData[path.pathData.length - 1];
+            path.pathData.push({ command: 'L', x: p.x, y: prev.y });
+            path.pathData.push({ command: 'L', x: p.x, y: p.y });
+          }
+        });
+      } else {
+        run.forEach((p, i) =>
+          path.pathData.push({ command: i === 0 ? 'M' : 'L', x: p.x, y: p.y })
+        );
+      }
+    });
+
+    this.group.add(path);
+
+    // ─ Markers & Labels (wrapped in a group for collective opacity) ─
+    const markersGroup = new Group();
+    this.group.add(markersGroup);
+
+    if (this.markerOpts.enabled || this.labelsOpts?.enabled) {
+      pts.forEach(p => {
+        if (p.missing) return;
+        if (this.markerOpts.enabled) {
+          const marker = new Marker();
+          marker.centerX = p.x;
+          marker.centerY = p.y;
+          marker.radius = (this.markerOpts.size || 6) / 2;
+          marker.shape = this.markerShape;
+          marker.fill = this.markerOpts.fill || this.stroke;
+          marker.stroke = '#fff';
+          marker.strokeWidth = 1.5;
+          marker.shadow = this.shadowOpts ?? null;
+          marker.datum = p.datum;
+          marker.seriesId = this.yKey;
+          markersGroup.add(marker);
+        }
+
+        if (this.labelsOpts?.enabled) {
+          const lbl = new Text();
+          lbl.text = formatAxisValue(p.datum[this.yKey]);
+          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.stroke;
+          
+          const pos = this.labelsOpts.position || 'top';
+          const offset = (this.markerOpts.enabled ? this.markerOpts.size || 6 : 0) / 2 + 5;
+
+          let ax = p.x, ay = p.y;
+          if (pos === 'top') {
+            ay = p.y - offset;
+            lbl.textAlign = 'center'; lbl.textBaseline = 'bottom';
+          } else if (pos === 'bottom') {
+            ay = p.y + offset + 2;
+            lbl.textAlign = 'center'; lbl.textBaseline = 'top';
+          } else if (pos === 'left') {
+            ax = p.x - offset - 4;
+            lbl.textAlign = 'right'; lbl.textBaseline = 'middle';
+          } else if (pos === 'right') {
+            ax = p.x + offset + 4;
+            lbl.textAlign = 'left'; lbl.textBaseline = 'middle';
+          } else {
+            lbl.textAlign = 'center'; lbl.textBaseline = 'middle';
+            if (this.markerOpts.enabled) lbl.fill = '#fff';
+          }
+          lbl.translation = { x: ax, y: ay };
+          lbl.x = 0; lbl.y = 0;
+          markersGroup.add(lbl);
+        }
+      });
+    }
+
+    if (animate && this.animationOpts?.enabled !== false) {
+      this.animator?.stop();
+      const animType = this.animationOpts?.type || 'draw';
+      const duration = this.animationOpts?.duration ?? 800;
+      const easing = Animator.getEasing(this.animationOpts?.easing);
+
+      if (animType === 'draw') {
+        // Approximate path length for drawing effect
+        let length = 0;
+        for (let i = 1; i < pts.length; i++) {
+          length += Math.sqrt(Math.pow(pts[i].x - pts[i-1].x, 2) + Math.pow(pts[i].y - pts[i-1].y, 2));
+        }
+        if (this.interpolation === 'step') length *= 1.5; // padding for steps
+
+        path.lineDash = [length, length];
+        path.lineDashOffset = length;
+        markersGroup.opacity = 0;
+
+        this.animator = new Animator({
+          duration,
+          easing,
+          onUpdate: (p) => {
+            path.lineDashOffset = length * (1 - p);
+            if (p > 0.8) markersGroup.opacity = (p - 0.8) * 5;
+          },
+          onComplete: () => {
+            path.lineDash = undefined;
+            markersGroup.opacity = 1;
+          }
+        });
+      } else {
+        // Default fade
+        this.group.opacity = 0;
+        this.animator = new Animator({
+          duration,
+          easing,
+          onUpdate: (p) => { this.group.opacity = p; }
+        });
+      }
+      this.animator.start();
+    }
+  }
+}
+

package/src/series/PieSeries.ts

@@ -0,0 +1,203 @@
+// Radiant Charts - PieSeries
+// Phase 2.4: Pie, Donut, Half-Donut / Semi-Circle with entrance animation
+
+import { Group, Arc, Text } from '../scene/Shapes';
+import { Animator } from '../core/Animator';
+
+export interface PieSeriesOptions {
+  angleKey: string;
+  labelKey: string;
+  innerRadius?: number;
+  outerRadius?: number;
+  fills?: string[];
+  strokes?: string[];
+  /** Start angle in degrees (default -90 = top). Use 180 for half-donut */
+  startAngle?: number;
+  /** End angle in degrees (default 270 = full circle). Use 360 for half-donut */
+  endAngle?: number;
+  /** Gap between slices in radians */
+  padAngle?: number;
+  labels?: import('../RadiantChart').DataLabelOptions;
+  animation?: import('../RadiantChart').AnimationOptions;
+}
+
+const DEG = Math.PI / 180;
+
+export class PieSeries {
+  private group = new Group();
+  private angleKey: string;
+  private labelKey: string;
+  private innerRadius: number = 0;
+  private outerRadius?: number;
+  private fills: string[] = ['#4e79a7','#f28e2c','#e15759','#76b7b2','#59a14f','#edc948','#b07aa1','#ff9da7','#9c755f','#bab0ac'];
+  private strokes: string[] = ['#fff'];
+  private startAngleDeg: number = -90;
+  private endAngleDeg: number = 270;
+  private padAngle: number = 0.008;
+  private labelsOpts?: import('../RadiantChart').DataLabelOptions;
+  private animationOpts?: import('../RadiantChart').AnimationOptions;
+  private animator?: Animator;
+  private slices: { arc: Arc, targetStart: number, targetEnd: number, label?: Text }[] = [];
+
+  constructor(options: PieSeriesOptions) {
+    this.angleKey = options.angleKey;
+    this.labelKey = options.labelKey;
+    if (options.innerRadius !== undefined) this.innerRadius = options.innerRadius;
+    if (options.outerRadius !== undefined) this.outerRadius = options.outerRadius;
+    if (options.fills) this.fills = options.fills;
+    if (options.strokes) this.strokes = options.strokes;
+    if (options.startAngle !== undefined) this.startAngleDeg = options.startAngle;
+    if (options.endAngle !== undefined) this.endAngleDeg = options.endAngle;
+    if (options.padAngle !== undefined) this.padAngle = options.padAngle;
+    this.labelsOpts = options.labels;
+    this.animationOpts = options.animation;
+  }
+
+  getGroup() { return this.group; }
+
+  update(data: readonly any[], seriesRect: { x: number; y: number; width: number; height: number }, animate: boolean = true, options?: PieSeriesOptions) {
+    if (options) {
+      this.angleKey = options.angleKey;
+      this.labelKey = options.labelKey;
+      if (options.innerRadius !== undefined) this.innerRadius = options.innerRadius;
+      if (options.outerRadius !== undefined) this.outerRadius = options.outerRadius;
+      if (options.fills) this.fills = options.fills;
+      if (options.strokes) this.strokes = options.strokes;
+      if (options.startAngle !== undefined) this.startAngleDeg = options.startAngle;
+      if (options.endAngle !== undefined) this.endAngleDeg = options.endAngle;
+      if (options.padAngle !== undefined) this.padAngle = options.padAngle;
+      if (options.labels) this.labelsOpts = options.labels;
+      if (options.animation) this.animationOpts = options.animation;
+    }
+    this.group.clear();
+    if (!data || data.length === 0) return;
+
+    const total = data.reduce((s, d) => s + (d[this.angleKey] || 0), 0);
+    if (total === 0) return;
+
+    const cx = seriesRect.x + seriesRect.width / 2;
+    const cy = seriesRect.y + seriesRect.height / 2;
+    const marginFactor = this.labelsOpts?.enabled !== false ? 0.72 : 0.88;
+    const outerR = this.outerRadius ?? (Math.min(seriesRect.width, seriesRect.height) / 2 * marginFactor);
+    // innerRadius ≤ 1.0 is treated as a fraction of outerR (e.g. 0.5 → 50% of outerR)
+    const innerR = this.innerRadius > 0 && this.innerRadius <= 1.0 ? this.innerRadius * outerR : this.innerRadius;
+
+    const startRad = this.startAngleDeg * DEG;
+    const totalArcRad = (this.endAngleDeg - this.startAngleDeg) * DEG;
+
+    this.slices = [];
+    let currentAngle = startRad;
+
+    data.forEach((datum, i) => {
+      const val = datum[this.angleKey] || 0;
+      const sliceAngle = (val / total) * totalArcRad - this.padAngle;
+
+      const slice = new Arc();
+      slice.centerX = cx;
+      slice.centerY = cy;
+      slice.innerRadius = innerR;
+      slice.outerRadius = outerR;
+      slice.startAngle = currentAngle;
+      slice.endAngle = currentAngle + sliceAngle;
+      slice.fill = this.fills[i % this.fills.length];
+      slice.stroke = this.strokes[i % this.strokes.length];
+      slice.strokeWidth = 2;
+      slice.datum = datum;
+      slice.seriesId = this.angleKey;
+      this.group.add(slice);
+
+      let labelNode: Text | undefined;
+      // Label
+      if (this.labelsOpts?.enabled !== false) {
+        const labelAngle = currentAngle + sliceAngle / 2;
+        const pos = this.labelsOpts?.position || 'outside';
+        const isInside = pos === 'inside' || pos === 'center';
+        
+        const labelR = isInside ? innerR + (outerR - innerR) / 2 : outerR + 18;
+        const lx = cx + Math.cos(labelAngle) * labelR;
+        const ly = cy + Math.sin(labelAngle) * labelR;
+        
+        labelNode = new Text();
+        labelNode.text = String(datum[this.labelKey] ?? '');
+        labelNode.fontSize = this.labelsOpts?.fontSize || 10;
+        labelNode.fontFamily = this.labelsOpts?.fontFamily || 'sans-serif';
+        labelNode.fontWeight = this.labelsOpts?.fontWeight || 'normal';
+        labelNode.rotation = ((this.labelsOpts?.rotation || 0) * Math.PI) / 180;
+        labelNode.fill = this.labelsOpts?.fill || (isInside ? '#fff' : '#6b7280');
+        
+        // Dynamically adjust text alignment and max width to prevent container overflow
+        const cos = Math.cos(labelAngle);
+        labelNode.textAlign = isInside ? 'center' : (cos > 0.05 ? 'start' : cos < -0.05 ? 'end' : 'center');
+        labelNode.textBaseline = 'middle';
+        labelNode.translation = { x: lx, y: ly };
+        labelNode.x = 0;
+        labelNode.y = 0;
+        
+        // Anti-collision: truncate long labels that would bleed off-canvas
+        if (!isInside) {
+          const availableWidth = cos > 0 
+            ? seriesRect.x + seriesRect.width - lx - 10
+            : lx - seriesRect.x - 10;
+          labelNode.maxWidth = Math.max(40, Math.min(availableWidth, seriesRect.width / 3));
+        }
+
+        if (isInside && sliceAngle < 0.1) labelNode.text = '';
+        this.group.add(labelNode);
+      }
+
+      this.slices.push({ arc: slice, targetStart: currentAngle, targetEnd: currentAngle + sliceAngle, label: labelNode });
+      currentAngle += sliceAngle + this.padAngle;
+    });
+
+    if (animate && this.animationOpts?.enabled !== false) {
+      this.animator?.stop();
+      const animType = this.animationOpts?.type || 'grow';
+      const duration = this.animationOpts?.duration ?? 600;
+      const easing = Animator.getEasing(this.animationOpts?.easing || (animType === 'grow' ? 'back' : 'easeOut'));
+
+      if (animType === 'grow') {
+        this.slices.forEach(s => { s.arc.outerRadius = 0; if (s.label) s.label.opacity = 0; });
+        this.animator = new Animator({
+          duration, easing,
+          onUpdate: (p) => {
+            this.slices.forEach(s => { 
+              s.arc.outerRadius = outerR * p; 
+              if (s.label && p > 0.8) s.label.opacity = (p - 0.8) * 5;
+            });
+          }
+        });
+      } else if (animType === 'radial') {
+        this.slices.forEach(s => { s.arc.endAngle = s.arc.startAngle; if (s.label) s.label.opacity = 0; });
+        this.animator = new Animator({
+          duration, easing,
+          onUpdate: (p) => {
+            this.slices.forEach(s => {
+              const fullAngle = s.targetEnd - s.targetStart;
+              s.arc.endAngle = s.targetStart + fullAngle * p;
+              if (s.label && p > 0.8) s.label.opacity = (p - 0.8) * 5;
+            });
+          }
+        });
+      } else {
+        this.group.opacity = 0;
+        this.animator = new Animator({
+          duration, easing,
+          onUpdate: (p) => { this.group.opacity = p; }
+        });
+      }
+      this.animator.start();
+    }
+  }
+
+  getLegendData(theme: any, data: readonly any[]): import('../core/Legend').LegendItem[] {
+    if (!data) return [];
+    return data.map((d, i) => ({
+      id: `${this.angleKey}-${i}`,
+      label: String(d[this.labelKey] ?? `Item ${i + 1}`),
+      fill: this.fills[i % this.fills.length],
+      markerType: 'square'
+    }));
+  }
+}
+
+