bmad-elsabro 1.0.0

package/renderer/lib/chart-utils.ts

@@ -0,0 +1,472 @@
+/**
+ * Chart Utilities
+ *
+ * Utilities for processing token analytics data and creating chart configurations.
+ * Provides data transformation, formatting, and SVG path generation for charts.
+ *
+ * Features:
+ * - Line chart data processing
+ * - Bar chart data processing
+ * - Pie/donut chart calculations
+ * - Time series formatting
+ * - Number formatting
+ * - Color palette generation
+ *
+ * @module renderer/lib/chart-utils
+ */
+
+/**
+ * Chart data point
+ */
+export interface ChartDataPoint {
+  label: string;
+  value: number;
+  color?: string;
+  metadata?: Record<string, any>;
+}
+
+/**
+ * Time series data point
+ */
+export interface TimeSeriesPoint {
+  date: string;
+  timestamp: number;
+  value: number;
+}
+
+/**
+ * Line chart path configuration
+ */
+export interface LineChartPath {
+  path: string;
+  points: Array<{ x: number; y: number }>;
+  minValue: number;
+  maxValue: number;
+}
+
+/**
+ * Bar chart configuration
+ */
+export interface BarChartConfig {
+  bars: Array<{
+    label: string;
+    value: number;
+    height: number;
+    color: string;
+  }>;
+  maxValue: number;
+}
+
+/**
+ * Donut chart segment
+ */
+export interface DonutSegment {
+  label: string;
+  value: number;
+  percentage: number;
+  startAngle: number;
+  endAngle: number;
+  color: string;
+  path: string;
+}
+
+/**
+ * Color palette for different token modes
+ */
+export const TOKEN_MODE_COLORS = {
+  'ultra-save': '#10b981', // green-500
+  'balanced': '#3b82f6',   // blue-500
+  'power': '#f97316',      // orange-500
+} as const;
+
+/**
+ * Format number with thousand separators
+ *
+ * @param value - Number to format
+ * @returns Formatted string
+ */
+export function formatNumber(value: number): string {
+  return value.toLocaleString('en-US');
+}
+
+/**
+ * Format number with K/M/B suffix
+ *
+ * @param value - Number to format
+ * @returns Formatted string with suffix
+ */
+export function formatCompactNumber(value: number): string {
+  if (value >= 1_000_000_000) {
+    return `${(value / 1_000_000_000).toFixed(1)}B`;
+  }
+  if (value >= 1_000_000) {
+    return `${(value / 1_000_000).toFixed(1)}M`;
+  }
+  if (value >= 1_000) {
+    return `${(value / 1_000).toFixed(1)}K`;
+  }
+  return value.toString();
+}
+
+/**
+ * Format cost as USD currency
+ *
+ * @param value - Cost value
+ * @returns Formatted currency string
+ */
+export function formatCurrency(value: number): string {
+  return new Intl.NumberFormat('en-US', {
+    style: 'currency',
+    currency: 'USD',
+    minimumFractionDigits: 2,
+    maximumFractionDigits: 4,
+  }).format(value);
+}
+
+/**
+ * Format date for display
+ *
+ * @param date - Date string or timestamp
+ * @returns Formatted date string
+ */
+export function formatDate(date: string | number): string {
+  const d = typeof date === 'string' ? new Date(date) : new Date(date);
+  return d.toLocaleDateString('en-US', {
+    month: 'short',
+    day: 'numeric',
+  });
+}
+
+/**
+ * Format date with time
+ *
+ * @param date - Date string or timestamp
+ * @returns Formatted date and time string
+ */
+export function formatDateTime(date: string | number): string {
+  const d = typeof date === 'string' ? new Date(date) : new Date(date);
+  return d.toLocaleString('en-US', {
+    month: 'short',
+    day: 'numeric',
+    hour: '2-digit',
+    minute: '2-digit',
+  });
+}
+
+/**
+ * Convert analytics date data to time series
+ *
+ * @param byDate - Date-indexed analytics data
+ * @returns Array of time series points
+ */
+export function dateDataToTimeSeries(
+  byDate: Record<string, { tokens: number; count: number }>
+): TimeSeriesPoint[] {
+  return Object.entries(byDate)
+    .map(([date, data]) => ({
+      date,
+      timestamp: new Date(date).getTime(),
+      value: data.tokens,
+    }))
+    .sort((a, b) => a.timestamp - b.timestamp);
+}
+
+/**
+ * Generate SVG path for line chart
+ *
+ * @param data - Time series data
+ * @param width - Chart width
+ * @param height - Chart height
+ * @param options - Additional options
+ * @returns Line chart path configuration
+ */
+export function generateLineChartPath(
+  data: TimeSeriesPoint[],
+  width: number,
+  height: number,
+  options: {
+    padding?: number;
+    smooth?: boolean;
+  } = {}
+): LineChartPath {
+  const { padding = 20, smooth = true } = options;
+
+  if (data.length === 0) {
+    return {
+      path: '',
+      points: [],
+      minValue: 0,
+      maxValue: 0,
+    };
+  }
+
+  // Calculate min/max values
+  const values = data.map((d) => d.value);
+  const minValue = Math.min(...values);
+  const maxValue = Math.max(...values);
+  const valueRange = maxValue - minValue || 1;
+
+  // Calculate chart dimensions
+  const chartWidth = width - padding * 2;
+  const chartHeight = height - padding * 2;
+
+  // Map data points to coordinates
+  const points = data.map((point, index) => {
+    const x = padding + (index / (data.length - 1 || 1)) * chartWidth;
+    const y = padding + chartHeight - ((point.value - minValue) / valueRange) * chartHeight;
+    return { x, y };
+  });
+
+  // Generate path
+  let path = '';
+  if (points.length > 0) {
+    path = `M ${points[0].x} ${points[0].y}`;
+
+    if (smooth && points.length > 2) {
+      // Use quadratic bezier curves for smooth lines
+      for (let i = 1; i < points.length; i++) {
+        const prev = points[i - 1];
+        const curr = points[i];
+        const controlX = (prev.x + curr.x) / 2;
+        path += ` Q ${controlX} ${prev.y}, ${curr.x} ${curr.y}`;
+      }
+    } else {
+      // Use straight lines
+      for (let i = 1; i < points.length; i++) {
+        path += ` L ${points[i].x} ${points[i].y}`;
+      }
+    }
+  }
+
+  return {
+    path,
+    points,
+    minValue,
+    maxValue,
+  };
+}
+
+/**
+ * Generate bar chart configuration
+ *
+ * @param data - Chart data points
+ * @param maxHeight - Maximum bar height
+ * @returns Bar chart configuration
+ */
+export function generateBarChart(
+  data: ChartDataPoint[],
+  maxHeight: number
+): BarChartConfig {
+  if (data.length === 0) {
+    return { bars: [], maxValue: 0 };
+  }
+
+  const maxValue = Math.max(...data.map((d) => d.value));
+
+  const bars = data.map((point) => ({
+    label: point.label,
+    value: point.value,
+    height: maxValue > 0 ? (point.value / maxValue) * maxHeight : 0,
+    color: point.color || '#3b82f6',
+  }));
+
+  return { bars, maxValue };
+}
+
+/**
+ * Generate donut chart segments
+ *
+ * @param data - Chart data points
+ * @param options - Donut configuration
+ * @returns Array of donut segments
+ */
+export function generateDonutChart(
+  data: ChartDataPoint[],
+  options: {
+    radius?: number;
+    innerRadius?: number;
+    centerX?: number;
+    centerY?: number;
+  } = {}
+): DonutSegment[] {
+  const {
+    radius = 80,
+    innerRadius = 50,
+    centerX = 100,
+    centerY = 100,
+  } = options;
+
+  if (data.length === 0) {
+    return [];
+  }
+
+  const total = data.reduce((sum, d) => sum + d.value, 0);
+  if (total === 0) {
+    return [];
+  }
+
+  let currentAngle = -90; // Start at top
+
+  return data.map((point, index) => {
+    const percentage = (point.value / total) * 100;
+    const angleDelta = (point.value / total) * 360;
+    const startAngle = currentAngle;
+    const endAngle = currentAngle + angleDelta;
+
+    // Calculate arc path
+    const startRadians = (startAngle * Math.PI) / 180;
+    const endRadians = (endAngle * Math.PI) / 180;
+
+    const x1 = centerX + radius * Math.cos(startRadians);
+    const y1 = centerY + radius * Math.sin(startRadians);
+    const x2 = centerX + radius * Math.cos(endRadians);
+    const y2 = centerY + radius * Math.sin(endRadians);
+
+    const ix1 = centerX + innerRadius * Math.cos(startRadians);
+    const iy1 = centerY + innerRadius * Math.sin(startRadians);
+    const ix2 = centerX + innerRadius * Math.cos(endRadians);
+    const iy2 = centerY + innerRadius * Math.sin(endRadians);
+
+    const largeArcFlag = angleDelta > 180 ? 1 : 0;
+
+    const path = [
+      `M ${x1} ${y1}`,
+      `A ${radius} ${radius} 0 ${largeArcFlag} 1 ${x2} ${y2}`,
+      `L ${ix2} ${iy2}`,
+      `A ${innerRadius} ${innerRadius} 0 ${largeArcFlag} 0 ${ix1} ${iy1}`,
+      'Z',
+    ].join(' ');
+
+    currentAngle = endAngle;
+
+    return {
+      label: point.label,
+      value: point.value,
+      percentage,
+      startAngle,
+      endAngle,
+      color: point.color || TOKEN_MODE_COLORS.balanced,
+      path,
+    };
+  });
+}
+
+/**
+ * Get color for token mode
+ *
+ * @param mode - Token mode name
+ * @returns Hex color code
+ */
+export function getModeColor(mode: string): string {
+  return TOKEN_MODE_COLORS[mode as keyof typeof TOKEN_MODE_COLORS] || TOKEN_MODE_COLORS.balanced;
+}
+
+/**
+ * Generate gradient colors
+ *
+ * @param count - Number of colors needed
+ * @param baseColor - Base color for gradient
+ * @returns Array of color strings
+ */
+export function generateGradientColors(count: number, baseColor?: string): string[] {
+  const colors = [
+    '#3b82f6', // blue-500
+    '#10b981', // green-500
+    '#f59e0b', // amber-500
+    '#ef4444', // red-500
+    '#8b5cf6', // violet-500
+    '#ec4899', // pink-500
+    '#14b8a6', // teal-500
+    '#f97316', // orange-500
+  ];
+
+  if (count <= colors.length) {
+    return colors.slice(0, count);
+  }
+
+  // If we need more colors, repeat the palette
+  const result: string[] = [];
+  for (let i = 0; i < count; i++) {
+    result.push(colors[i % colors.length]);
+  }
+  return result;
+}
+
+/**
+ * Calculate percentage change between two values
+ *
+ * @param current - Current value
+ * @param previous - Previous value
+ * @returns Percentage change
+ */
+export function calculatePercentageChange(current: number, previous: number): number {
+  if (previous === 0) {
+    return current > 0 ? 100 : 0;
+  }
+  return ((current - previous) / previous) * 100;
+}
+
+/**
+ * Format percentage with sign
+ *
+ * @param percentage - Percentage value
+ * @returns Formatted percentage string
+ */
+export function formatPercentage(percentage: number): string {
+  const sign = percentage > 0 ? '+' : '';
+  return `${sign}${percentage.toFixed(1)}%`;
+}
+
+/**
+ * Group time series data by period
+ *
+ * @param data - Time series data
+ * @param period - Grouping period ('day', 'week', 'month')
+ * @returns Grouped data
+ */
+export function groupByPeriod(
+  data: TimeSeriesPoint[],
+  period: 'day' | 'week' | 'month'
+): TimeSeriesPoint[] {
+  if (data.length === 0) {
+    return [];
+  }
+
+  const grouped = new Map<string, { total: number; count: number; timestamp: number }>();
+
+  data.forEach((point) => {
+    const date = new Date(point.timestamp);
+    let key: string;
+
+    switch (period) {
+      case 'day':
+        key = date.toISOString().split('T')[0];
+        break;
+      case 'week':
+        // Get ISO week number
+        const weekStart = new Date(date);
+        weekStart.setDate(date.getDate() - date.getDay());
+        key = weekStart.toISOString().split('T')[0];
+        break;
+      case 'month':
+        key = `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, '0')}`;
+        break;
+    }
+
+    if (!grouped.has(key)) {
+      grouped.set(key, { total: 0, count: 0, timestamp: date.getTime() });
+    }
+
+    const group = grouped.get(key)!;
+    group.total += point.value;
+    group.count += 1;
+  });
+
+  return Array.from(grouped.entries())
+    .map(([date, data]) => ({
+      date,
+      timestamp: data.timestamp,
+      value: data.total,
+    }))
+    .sort((a, b) => a.timestamp - b.timestamp);
+}