radiant-charts-core 0.2.0

package/src/series/AreaSeries.ts

@@ -0,0 +1,315 @@
+// Radiant Charts - AreaSeries
+// Phase 2.3: Standard, stacked, step, and smooth curve 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 AreaSeriesOptions {
+  xKey: string;
+  yKey: string;
+  title?: string;
+  fill?: string;
+  stroke?: string;
+  strokeWidth?: number;
+  fillOpacity?: number;
+  stacked?: boolean;
+  /** When true, the stack is rescaled so each column sums to 100% — yielding a 100% stacked area chart. */
+  normalized?: boolean;
+  interpolation?: 'linear' | 'step' | 'smooth';
+  marker?: { enabled?: boolean; shape?: 'circle' | 'square' | 'cross' | 'diamond' | 'triangle' | 'plus'; size?: number; fill?: string; stroke?: string; strokeWidth?: number };
+  /** When false, the area path is severed at any null/NaN datapoint instead of bridging the gap. Default: true. */
+  connectMissingData?: boolean;
+  labels?: import('../RadiantChart').DataLabelOptions;
+  animation?: import('../RadiantChart').AnimationOptions;
+  shadow?: import('../RadiantChart').DropShadow;
+}
+
+function catmullRomBezier(pts: { x: number; y: number }[]): PathPoint[] {
+  if (pts.length === 0) return [];
+  const out: 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)];
+    out.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 out;
+}
+
+export class AreaSeries {
+  private group = new Group();
+  private xKey: string;
+  private yKey: string;
+  fill: string = '#4e79a7';
+  private stroke: string = '#4e79a7';
+  private strokeWidth: number = 2;
+  private fillOpacity: number = 0.25;
+  private stacked: boolean = false;
+  private normalized: boolean = false;
+  private connectMissingData: boolean = true;
+  private interpolation: 'linear' | 'step' | 'smooth';
+  private markerOpts = { enabled: false, size: 6, fill: '' };
+  private labelsOpts?: import('../RadiantChart').DataLabelOptions;
+  private animationOpts?: import('../RadiantChart').AnimationOptions;
+  private shadowOpts?: import('../RadiantChart').DropShadow;
+  private animator?: Animator;
+  private path = new Path();
+  private markers: Marker[] = [];
+  private points: {
+    x: number;
+    targetY: number; startY: number; currentY: number;
+    targetBottomY: number; startBottomY: number; currentBottomY: number;
+    label?: Text;
+    datum: any;
+    /** True when the underlying y value is null / NaN — used to break the path. */
+    missing?: boolean;
+  }[] = [];
+
+  constructor(options: AreaSeriesOptions) {
+    this.xKey = options.xKey;
+    this.yKey = options.yKey;
+    this.stacked = options.stacked ?? false;
+    this.normalized = options.normalized ?? false;
+    this.connectMissingData = options.connectMissingData ?? true;
+    this.interpolation = options.interpolation ?? 'linear';
+    if (options.fill) this.fill = options.fill;
+    if (options.stroke) this.stroke = options.stroke;
+    if (options.strokeWidth !== undefined) this.strokeWidth = options.strokeWidth;
+    if (options.fillOpacity !== undefined) this.fillOpacity = options.fillOpacity;
+    if (options.marker) this.markerOpts = { ...this.markerOpts, ...options.marker };
+    this.markerOpts.fill = this.markerOpts.fill || this.fill;
+    this.labelsOpts = options.labels;
+    this.animationOpts = options.animation;
+    this.shadowOpts = options.shadow;
+  }
+
+  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,
+    stackedOffsets?: number[],
+    options?: AreaSeriesOptions,
+    columnTotals?: number[],
+  ) {
+    if (options) {
+      this.xKey = options.xKey;
+      this.yKey = options.yKey;
+      if (options.fill) this.fill = options.fill;
+      if (options.stroke) this.stroke = options.stroke;
+      if (options.strokeWidth !== undefined) this.strokeWidth = options.strokeWidth;
+      if (options.fillOpacity !== undefined) this.fillOpacity = options.fillOpacity;
+      if (options.stacked !== undefined) this.stacked = options.stacked;
+      if (options.normalized !== undefined) this.normalized = options.normalized;
+      if (options.connectMissingData !== undefined) this.connectMissingData = options.connectMissingData;
+      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;
+    }
+
+    const isInitial = this.points.length === 0;
+    this.group.clear();
+    if (data.length === 0) return;
+
+    this.path = new Path();
+    this.path.fill = this.fill;
+    this.path.stroke = this.stroke;
+    this.path.strokeWidth = this.strokeWidth;
+    this.path.opacity = this.fillOpacity;
+    this.path.shadow = this.shadowOpts ?? null;
+    this.group.add(this.path);
+
+    const newPts: typeof this.points = [];
+    this.markers = [];
+
+    data.forEach((datum, i) => {
+      const x = xScale.convert(datum[this.xKey]) + safeBandwidth(xScale) / 2;
+      let yVal = datum[this.yKey];
+      const isMissing = yVal === null || yVal === undefined || (typeof yVal === 'number' && isNaN(yVal));
+
+      let targetY: number, targetBottomY: number;
+      if (this.stacked && stackedOffsets) {
+        const off = stackedOffsets[i] ?? 0;
+        const total = columnTotals?.[i] ?? 0;
+        if (this.normalized && total > 0) {
+          // Normalize the running offset and current value into a 0..100 stack.
+          const normOff = (off / total) * 100;
+          const normVal = ((yVal ?? 0) / total) * 100;
+          targetBottomY = yScale.convert(normOff);
+          targetY = yScale.convert(normOff + normVal);
+        } else {
+          targetBottomY = yScale.convert(off);
+          targetY = yScale.convert(off + (yVal ?? 0));
+        }
+      } else {
+        targetY = yScale.convert(yVal ?? 0);
+        targetBottomY = yScale.convert(0);
+      }
+
+      const startY = isInitial ? yScale.convert(0) : (this.points[i]?.currentY ?? yScale.convert(0));
+      const startBottomY = isInitial ? yScale.convert(0) : (this.points[i]?.currentBottomY ?? yScale.convert(0));
+      
+      let label: Text | undefined;
+      if (this.labelsOpts?.enabled) {
+        label = new Text();
+        this.group.add(label);
+      }
+
+      newPts.push({ x, targetY, startY, currentY: startY, targetBottomY, startBottomY, currentBottomY: startBottomY, label, datum, missing: isMissing });
+
+      if (this.markerOpts.enabled) {
+        const m = new Marker();
+        m.shape = (this.markerOpts as any).shape || 'circle';
+        m.centerX = x; m.centerY = targetY;
+        m.radius = (this.markerOpts.size || 6) / 2;
+        m.fill = this.markerOpts.fill;
+        if ((this.markerOpts as any).stroke) m.stroke = (this.markerOpts as any).stroke;
+        if ((this.markerOpts as any).strokeWidth !== undefined) m.strokeWidth = (this.markerOpts as any).strokeWidth;
+        m.shadow = this.shadowOpts ?? null;
+        m.datum = datum; m.seriesId = this.yKey;
+        this.markers.push(m);
+        this.group.add(m);
+      }
+    });
+
+    this.points = newPts;
+
+    if (animate && this.animationOpts?.enabled !== false) {
+      this.animator?.stop();
+      const animType = this.animationOpts?.type || 'grow';
+      const duration = this.animationOpts?.duration ?? 500;
+      const easing = Animator.getEasing(this.animationOpts?.easing);
+
+      if (animType === 'fade') {
+        this.group.opacity = 0;
+        this.animator = new Animator({
+          duration, easing,
+          onUpdate: (p) => { 
+            this.buildPath(1);
+            this.group.opacity = p * this.fillOpacity;
+            if (this.labelsOpts?.enabled) this.renderLabels();
+          }
+        });
+      } else {
+        // Default grow
+        this.animator = new Animator({
+          duration,
+          easing,
+          onUpdate: (p) => {
+            this.buildPath(p);
+            if (this.labelsOpts?.enabled) this.renderLabels();
+          },
+        });
+      }
+      this.animator.start();
+    } else {
+      this.points.forEach((p, i) => {
+        p.label = newPts[i].label; // sync new label node
+        p.targetY = newPts[i].targetY; p.targetBottomY = newPts[i].targetBottomY;
+        p.startY = p.currentY; p.startBottomY = p.currentBottomY;
+      });
+      this.buildPath(1);
+      if (this.labelsOpts?.enabled) this.renderLabels();
+    }
+  }
+
+  private renderLabels() {
+    this.points.forEach(p => {
+      if (!p.label) return;
+      const lbl = p.label;
+      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;
+      lbl.textAlign = 'center';
+      lbl.textBaseline = 'bottom';
+      lbl.translation = { x: p.x, y: p.currentY - 8 };
+      lbl.x = 0;
+      lbl.y = 0;
+    });
+  }
+
+  private buildPath(progress: number) {
+    // Update interpolated coordinates first so contiguous-segment splitting
+    // below can read currentY / currentBottomY directly.
+    this.points.forEach((p, i) => {
+      p.currentY = p.startY + (p.targetY - p.startY) * progress;
+      p.currentBottomY = p.startBottomY + (p.targetBottomY - p.startBottomY) * progress;
+      if (this.markers[i]) this.markers[i].centerY = p.currentY;
+    });
+
+    // Split the points into contiguous, non-missing runs when gap-skipping
+    // is requested. A run is rendered as one closed sub-path so the visual
+    // area is severed at any null/NaN.
+    const runs: typeof this.points[] = [];
+    if (this.connectMissingData) {
+      runs.push(this.points);
+    } else {
+      let current: typeof this.points = [];
+      this.points.forEach(p => {
+        if (p.missing) {
+          if (current.length > 0) { runs.push(current); current = []; }
+        } else {
+          current.push(p);
+        }
+      });
+      if (current.length > 0) runs.push(current);
+    }
+
+    const allPath: PathPoint[] = [];
+    runs.forEach(run => {
+      const topPts = run.map(p => ({ x: p.x, y: p.currentY }));
+      if (topPts.length === 0) return;
+
+      let topPath: PathPoint[];
+      if (this.interpolation === 'smooth') {
+        topPath = catmullRomBezier(topPts);
+      } else if (this.interpolation === 'step') {
+        topPath = [];
+        topPts.forEach((p, i) => {
+          if (i === 0) { topPath.push({ command: 'M', x: p.x, y: p.y }); }
+          else {
+            const prev = topPath[topPath.length - 1];
+            topPath.push({ command: 'L', x: p.x, y: prev.y });
+            topPath.push({ command: 'L', x: p.x, y: p.y });
+          }
+        });
+      } else {
+        topPath = topPts.map((p, i) => ({ command: (i === 0 ? 'M' : 'L') as 'M' | 'L', x: p.x, y: p.y }));
+      }
+
+      // Trace the run's bottom in reverse to close the polygon.
+      const bottomPath: PathPoint[] = [];
+      for (let i = run.length - 1; i >= 0; i--) {
+        bottomPath.push({ command: 'L', x: run[i].x, y: run[i].currentBottomY });
+      }
+      // Close this run by returning to its first top point so each sub-path
+      // is independently fillable.
+      bottomPath.push({ command: 'L', x: topPts[0].x, y: topPts[0].y });
+
+      allPath.push(...topPath, ...bottomPath);
+    });
+
+    this.path.pathData = allPath;
+    this.path.closed = true;
+  }
+}
+