radiant-charts-core 0.2.0

package/src/axes/CartesianAxis.ts

@@ -0,0 +1,305 @@
+// Radiant Charts - CartesianAxis
+// Phase 1.2 + 5.2: Smart formatting, dashed grid lines, data-ink optimization
+// Phase 6: Dynamic axis sizing & configurable label offsets
+
+import { Group, Line, Text } from '../scene/Shapes';
+import { Scale } from '../scale/Scale';
+import { Theme } from '../core/ThemeManager';
+
+export interface AxisOptions {
+  position: 'top' | 'bottom' | 'left' | 'right';
+  title?: string;
+  /** Show horizontal grid lines (default true for left/right axes) */
+  gridLines?: boolean;
+  /** Length (px) of the small tick mark on the X-axis. Default: 4 */
+  tickLength?: number;
+  /** Gap (px) between tick end and label start. Default: 2 */
+  labelGap?: number;
+  fontSize?: number;
+  fontFamily?: string;
+  rotation?: number;
+  /** 'start' | 'center' | 'end' — only applicable for categorical (Band) scales */
+  labelAlignment?: 'start' | 'center' | 'end';
+}
+
+/** Phase 5.2 – Smart axis label formatting */
+export function formatAxisValue(val: unknown): string {
+  if (val instanceof Date) {
+    // Default Date formatting — short M/D/YY. Time scales with sub-day intervals
+    // can override this via AxisConfig.label.formatter.
+    return `${val.getMonth() + 1}/${val.getDate()}/${String(val.getFullYear()).slice(-2)}`;
+  }
+  if (typeof val !== 'number') return String(val);
+  const abs = Math.abs(val);
+  if (abs > 1e11 && abs < 1e14) { // Likely epoch milliseconds (between 1973 and 5138)
+    const d = new Date(val);
+    if (!isNaN(d.getTime())) {
+      return `${d.getMonth() + 1}/${d.getDate()}/${String(d.getFullYear()).slice(-2)}`;
+    }
+  }
+  if (abs >= 1e9) return (val / 1e9).toFixed(1).replace(/\.0$/, '') + 'B';
+  if (abs >= 1e6) return (val / 1e6).toFixed(1).replace(/\.0$/, '') + 'M';
+  if (abs >= 1e3) return (val / 1e3).toFixed(1).replace(/\.0$/, '') + 'K';
+  if (val % 1 !== 0) {
+    // For small decimals (common in KDE / probability densities), preserve
+    // significant digits — `toFixed(1)` would collapse 0.005 to "0.0".
+    if (abs > 0 && abs < 1) {
+      return Number(val.toPrecision(3)).toString();
+    }
+    return val.toFixed(1);
+  }
+  return String(val);
+}
+
+/**
+ * Measures the required space for this axis given the current ticks and theme,
+ * using the provided canvas context for accurate text measurement.
+ */
+export interface AxisSpaceInfo {
+  /** Total pixels the axis needs perpendicular to its direction */
+  size: number;
+}
+
+export class CartesianAxis {
+  private group = new Group();
+  public scale: Scale<any, number>;
+  private options: AxisOptions;
+  private theme: Theme | null = null;
+  private _measuredLabelMaxW: number = 0;
+  private _layoutMaxWidth: number = 0;
+
+  constructor(scale: Scale<any, number>, options: AxisOptions) {
+    this.scale = scale;
+    this.options = options;
+  }
+
+  setLayoutMaxWidth(max: number) {
+    this._layoutMaxWidth = max;
+  }
+
+  getGroup() { return this.group; }
+
+  setTheme(theme: Theme) { this.theme = theme; }
+
+  updateOptions(options: Partial<AxisOptions>) {
+    this.options = { ...this.options, ...options };
+  }
+
+  /**
+   * Measures the exact space required for this axis perpendicular to its length.
+   */
+  getRequiredSpace(ctx: CanvasRenderingContext2D): AxisSpaceInfo {
+    const { position, rotation = 0 } = this.options;
+    const fontFamily = this.options.fontFamily || this.theme?.fontFamily || 'sans-serif';
+    const fontSize = this.options.fontSize ?? 10;
+    const tickLength = this.options.tickLength ?? 4;
+    const labelGap = this.options.labelGap ?? 2;
+
+    const tickCount: number | undefined = (this as any)._tickCount;
+    const labelFormatter: ((p: { value: any; index: number }) => string) | undefined = (this as any)._labelFormatter;
+
+    const ticks = this.scale.ticks ? this.scale.ticks(tickCount) : [];
+    ctx.font = `${fontSize}px ${fontFamily}`;
+
+    const rad = (rotation * Math.PI) / 180;
+    const absCos = Math.abs(Math.cos(rad));
+    const absSin = Math.abs(Math.sin(rad));
+
+    if (position === 'bottom' || position === 'top') {
+      let maxH = fontSize;
+      if (rotation !== 0) {
+        for (let i = 0; i < ticks.length; i++) {
+          const tick = ticks[i];
+          const text = labelFormatter
+            ? labelFormatter({ value: tick, index: i })
+            : formatAxisValue(tick);
+          const w = ctx.measureText(text).width;
+          const h = w * absSin + fontSize * absCos;
+          if (h > maxH) maxH = h;
+        }
+      }
+      let totalH = tickLength + labelGap + maxH + 4; // added 4px buffer
+      if (this.options.title) totalH += 6 + 12; // increased gap and space
+      return { size: Math.ceil(totalH) };
+    }
+
+    // left / right
+    let maxW = 0;
+    for (let i = 0; i < ticks.length; i++) {
+      const tick = ticks[i];
+      const text = labelFormatter
+        ? labelFormatter({ value: tick, index: i })
+        : formatAxisValue(tick);
+      const w = ctx.measureText(text).width;
+      const effectiveW = rotation !== 0 ? (w * absCos + fontSize * absSin) : w;
+      if (effectiveW > maxW) maxW = effectiveW;
+    }
+    this._measuredLabelMaxW = Math.ceil(maxW);
+    let totalW = labelGap + this._measuredLabelMaxW + 8; // increased from 6 to 8 for better label padding
+    if (this.options.title) totalW += 8 + 14; // increased title buffer to ensure no clipping
+
+    // Force a minimum width of 32px for side axes if they have labels,
+    // preventing the chart from collapsing to 0px and causing rendering artifacts.
+    if (ticks.length > 0) {
+      totalW = Math.max(totalW, 32);
+    }
+
+    return { size: Math.ceil(totalW) };
+  }
+
+  update(length: number, gridLength: number = 0, showLabels: boolean = true, innerPad: number = 0, gridOffset: number = 0) {
+    this.group.clear();
+    const { position, rotation = 0 } = this.options;
+
+    const textColor = this.theme?.subtextColor ?? '#6b7280';
+    const gridColor = this.theme?.gridColor ?? 'rgba(107,114,128,0.12)';
+    const axisColor = this.theme?.axisColor ?? '#d1d5db';
+    const fontFamily = this.options.fontFamily || this.theme?.fontFamily || 'sans-serif';
+    const fontSize = this.options.fontSize ?? 10;
+    const tickLength = this.options.tickLength ?? 4;
+    const labelGap = this.options.labelGap ?? 2;
+
+    if (position === 'bottom' || position === 'top') {
+      this.scale.range = [innerPad, length - innerPad];
+    } else {
+      this.scale.range = [length - innerPad, innerPad];
+    }
+
+    if (!showLabels) return;
+
+    if (position === 'bottom' || position === 'top') {
+      const axisLine = new Line();
+      axisLine.x1 = 0; axisLine.y1 = 0; axisLine.x2 = length; axisLine.y2 = 0;
+      axisLine.stroke = axisColor; axisLine.strokeWidth = 1;
+      this.group.add(axisLine);
+    }
+
+    const tickCount: number | undefined = (this as any)._tickCount;
+    const labelFormatter: ((p: { value: any; index: number }) => string) | undefined = (this as any)._labelFormatter;
+    const gridStyleArr: ReadonlyArray<{ stroke?: string; lineDash?: readonly number[] }> | undefined = (this as any)._gridStyle;
+
+    const ticks = this.scale.ticks ? this.scale.ticks(tickCount) : [];
+    const showGrid = this.options.gridLines !== false;
+    const { labelAlignment = 'center' } = this.options;
+
+    const getBW = (this.scale as any).getBandwidth?.bind(this.scale);
+
+    const isXAxis = position === 'bottom' || position === 'top';
+    const isYAxis = position === 'left' || position === 'right';
+    const labelMinGap = fontSize * 0.5;
+    let lastLabelPos = isXAxis ? -Infinity : Infinity;
+
+    ticks.forEach((tick, tIdx) => {
+      let pos = this.scale.convert(tick);
+
+      if (getBW) {
+        const bw = getBW();
+        const [br0, br1] = this.scale.range;
+        const stepSign = br1 >= br0 ? 1 : -1;
+        if (labelAlignment === 'center') pos += (stepSign * bw) / 2;
+        else if (labelAlignment === 'end') pos += stepSign * bw;
+      }
+
+      const labelText = labelFormatter
+        ? labelFormatter({ value: tick, index: tIdx })
+        : formatAxisValue(tick);
+
+      if (isXAxis && rotation === 0) {
+        const estWidth = fontSize * 0.6 * labelText.length;
+        const labelLeft = pos - estWidth / 2;
+        if (labelLeft < lastLabelPos + labelMinGap) {
+          if (position === 'bottom') {
+            const tickLine = new Line();
+            tickLine.x1 = pos; tickLine.y1 = 0; tickLine.x2 = pos; tickLine.y2 = tickLength;
+            tickLine.stroke = axisColor; tickLine.strokeWidth = 1;
+            this.group.add(tickLine);
+          }
+          return;
+        }
+        lastLabelPos = pos + estWidth / 2;
+      }
+
+      if (isYAxis) {
+        if (Math.abs(pos - lastLabelPos) < fontSize + 2) {
+          return;
+        }
+        lastLabelPos = pos;
+      }
+
+      const label = new Text();
+      label.text = labelText;
+      label.fontSize = fontSize;
+      label.fill = textColor;
+      label.fontFamily = fontFamily;
+      
+      const rad = (rotation * Math.PI) / 180;
+      label.rotation = rad;
+
+      if (position === 'bottom') {
+        const tickLine = new Line();
+        tickLine.x1 = pos; tickLine.y1 = 0; tickLine.x2 = pos; tickLine.y2 = tickLength;
+        tickLine.stroke = axisColor; tickLine.strokeWidth = 1;
+        this.group.add(tickLine);
+
+        label.translation = { x: pos, y: tickLength + labelGap };
+        label.x = 0; label.y = 0;
+
+        if (rotation === 0) {
+          label.textAlign = 'center';
+          label.textBaseline = 'top';
+        } else {
+          label.textAlign = rotation > 0 ? 'left' : 'right';
+          label.textBaseline = 'middle';
+        }
+        this.group.add(label);
+
+      } else if (position === 'left' || position === 'right') {
+        const isRight = position === 'right';
+        const sign = isRight ? 1 : -1;
+
+        label.textAlign = isRight ? 'left' : 'right';
+        label.textBaseline = 'middle';
+        label.maxWidth = this._layoutMaxWidth > 0 ? (this._layoutMaxWidth - labelGap - 8) : undefined;
+        label.translation = { x: sign * labelGap, y: pos };
+        label.x = 0; label.y = 0;
+        this.group.add(label);
+
+        if (showGrid && gridLength > 0 && position === 'left') {
+          const gridLine = new Line();
+          gridLine.x1 = gridOffset; gridLine.y1 = pos;
+          gridLine.x2 = gridLength; gridLine.y2 = pos;
+          const gs = gridStyleArr && gridStyleArr.length > 0 ? gridStyleArr[tIdx % gridStyleArr.length] : undefined;
+          gridLine.stroke = gs?.stroke ?? gridColor;
+          gridLine.strokeWidth = 1;
+          gridLine.lineDash = gs?.lineDash ? [...gs.lineDash] : [4, 6];
+          this.group.add(gridLine);
+        }
+      }
+    });
+
+    if (this.options.title) {
+      const titleLabel = new Text();
+      titleLabel.text = this.options.title;
+      titleLabel.fontSize = 11;
+      titleLabel.fill = textColor;
+      titleLabel.fontFamily = fontFamily;
+      if (position === 'bottom') {
+        titleLabel.x = length / 2;
+        titleLabel.y = tickLength + labelGap + this._measuredLabelMaxW + 12;
+        titleLabel.textAlign = 'center';
+      } else if (position === 'left') {
+        titleLabel.x = -(labelGap + (this._layoutMaxWidth || this._measuredLabelMaxW) + 14);
+        titleLabel.y = length / 2;
+        titleLabel.rotation = -Math.PI / 2;
+        titleLabel.textAlign = 'center';
+      } else if (position === 'right') {
+        titleLabel.x = labelGap + (this._layoutMaxWidth || this._measuredLabelMaxW) + 14;
+        titleLabel.y = length / 2;
+        titleLabel.rotation = Math.PI / 2;
+        titleLabel.textAlign = 'center';
+      }
+      this.group.add(titleLabel);
+    }
+  }
+}
+

package/src/core/Animator.ts

@@ -0,0 +1,119 @@
+// Radiant Charts - Animator
+// Phase 6.1: Supports prefers-reduced-motion for accessibility
+
+function prefersReducedMotion(): boolean {
+  if (typeof window === 'undefined') return false;
+  return window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+}
+
+export class Animator {
+  private startTime: number = 0;
+  private duration: number;
+  private easing: (t: number) => number;
+  private onUpdate: (progress: number) => void;
+  private onComplete?: () => void;
+  private requestId: number | null = null;
+
+  // Easing presets
+  static linear = (t: number): number => t;
+
+  static easeInQuad = (t: number): number => t * t;
+  static easeOutQuad = (t: number): number => t * (2 - t);
+  static easeInOutQuad = (t: number): number =>
+    t < 0.5 ? 2 * t * t : -1 + (4 - 2 * t) * t;
+
+  static easeInCubic = (t: number): number => t * t * t;
+  static easeOutCubic = (t: number): number => (--t) * t * t + 1;
+  static easeInOutCubic = (t: number): number =>
+    t < 0.5 ? 4 * t * t * t : (t - 1) * (2 * t - 2) * (2 * t - 2) + 1;
+
+  static easeInQuart = (t: number): number => t * t * t * t;
+  static easeOutQuart = (t: number): number => 1 - (--t) * t * t * t;
+  static easeInOutQuart = (t: number): number =>
+    t < 0.5 ? 8 * t * t * t * t : 1 - 8 * (--t) * t * t * t;
+
+  static easeOutBack = (t: number): number => {
+    const c1 = 1.70158, c3 = c1 + 1;
+    return 1 + c3 * Math.pow(t - 1, 3) + c1 * Math.pow(t - 1, 2);
+  };
+
+  static easeOutBounce = (t: number): number => {
+    const n1 = 7.5625;
+    const d1 = 2.75;
+    if (t < 1 / d1) return n1 * t * t;
+    if (t < 2 / d1) return n1 * (t -= 1.5 / d1) * t + 0.75;
+    if (t < 2.5 / d1) return n1 * (t -= 2.25 / d1) * t + 0.9375;
+    return n1 * (t -= 2.625 / d1) * t + 0.984375;
+  };
+
+  static easeOutElastic = (t: number): number => {
+    const c4 = (2 * Math.PI) / 3;
+    return t === 0 ? 0 : t === 1 ? 1 : Math.pow(2, -10 * t) * Math.sin((t * 10 - 0.75) * c4) + 1;
+  };
+
+  static getEasing(name?: string): (t: number) => number {
+    switch (name) {
+      case 'linear': return Animator.linear;
+      case 'easeIn': return Animator.easeInQuad;
+      case 'easeOut': return Animator.easeOutQuad;
+      case 'easeInOut': return Animator.easeInOutQuad;
+      case 'easeInCubic': return Animator.easeInCubic;
+      case 'easeOutCubic': return Animator.easeOutCubic;
+      case 'easeInOutCubic': return Animator.easeInOutCubic;
+      case 'easeInQuart': return Animator.easeInQuart;
+      case 'easeOutQuart': return Animator.easeOutQuart;
+      case 'easeInOutQuart': return Animator.easeInOutQuart;
+      case 'bounce': return Animator.easeOutBounce;
+      case 'elastic': return Animator.easeOutElastic;
+      case 'back': return Animator.easeOutBack;
+      default: return Animator.easeOutQuart;
+    }
+  }
+
+  constructor(options: {
+    duration?: number;
+    easing?: (t: number) => number;
+    onUpdate: (progress: number) => void;
+    onComplete?: () => void;
+  }) {
+    this.duration = options.duration ?? 420;
+    this.easing = options.easing ?? Animator.easeOutQuart;
+    this.onUpdate = options.onUpdate;
+    this.onComplete = options.onComplete;
+  }
+
+  start() {
+    this.stop();
+
+    // Phase 6.1 – Skip animation for users who prefer reduced motion
+    if (prefersReducedMotion()) {
+      this.onUpdate(1);
+      this.onComplete?.();
+      return;
+    }
+
+    this.startTime = performance.now();
+    this.loop();
+  }
+
+  stop() {
+    if (this.requestId !== null) {
+      cancelAnimationFrame(this.requestId);
+      this.requestId = null;
+    }
+  }
+
+  private loop = () => {
+    const now = performance.now();
+    const progress = Math.min((now - this.startTime) / this.duration, 1);
+    this.onUpdate(this.easing(progress));
+
+    if (progress < 1) {
+      this.requestId = requestAnimationFrame(this.loop);
+    } else {
+      this.requestId = null;
+      this.onComplete?.();
+    }
+  };
+}
+