npm package: @meanpug/charting
Description: A comprehensive charting library built on Apache ECharts with theming and API integration
Author: MeanPug
Latest version: 1.0.0

# @meanpug/charting

A comprehensive charting library built on Apache ECharts with theming and API integration.

## Installation

```bash
npm install @meanpug/charting echarts
```

Note: `echarts` is a peer dependency and must be installed separately.

## Features

- 🎨 **8 Pre-configured Chart Types** - Bar, Line, Pie, Scatter, Area, Radar, Heatmap, and Gauge
- 🎭 **Built-in Theming System** - Light, Dark, and Custom themes included
- 🔌 **API Integration** - Utilities for fetching and rendering data from APIs
- 📊 **TypeScript Support** - Full type definitions included
- ⚡ **Tree-shakeable** - ES modules for optimal bundle size
- 🎯 **Type-safe** - Comprehensive TypeScript types for all functions

## Quick Start

```typescript
import { createBarChart } from '@meanpug/charting';

// Create a simple bar chart
const chart = createBarChart('chart-container', {
  title: { text: 'Monthly Sales' },
  xAxis: ['Jan', 'Feb', 'Mar', 'Apr', 'May'],
  series: [
    { name: 'Sales', data: [120, 200, 150, 80, 70] }
  ]
});
```

## Available Chart Types

### Bar Charts
```typescript
import { createBarChart, createHorizontalBarChart, createStackedBarChart } from '@meanpug/charting';

createBarChart(container, config);
createHorizontalBarChart(container, config);
createStackedBarChart(container, config);
```

### Line Charts
```typescript
import { createLineChart, createSmoothLineChart, createMultiAxisLineChart } from '@meanpug/charting';

createLineChart(container, config);
createSmoothLineChart(container, config);
createMultiAxisLineChart(container, config);
```

### Pie Charts
```typescript
import { createPieChart, createDonutChart, createRoseChart } from '@meanpug/charting';

createPieChart(container, config);
createDonutChart(container, config);
createRoseChart(container, config);
```

### Other Chart Types
- **Scatter/Bubble**: `createScatterChart`, `createBubbleChart`
- **Area**: `createAreaChart`, `createStackedAreaChart`
- **Radar**: `createRadarChart`
- **Heatmap**: `createHeatmapChart`
- **Gauge**: `createGaugeChart`

## Theming

The library includes three built-in themes:

### Using Built-in Themes

```typescript
import { createBarChart } from '@meanpug/charting';

// Use custom theme (default)
const chart = createBarChart(container, config, 'custom');

// Use light theme
const chart = createBarChart(container, config, 'light');

// Use dark theme
const chart = createBarChart(container, config, 'dark');
```

### Apply Theme to Existing Chart

```typescript
import { applyTheme } from '@meanpug/charting';

applyTheme(chart, 'dark');
```

### Custom Theme

```typescript
import { createBarChart, getTheme } from '@meanpug/charting';

const customTheme = {
  color: ['#3e51cd', '#ea3933', '#FFC300'],
  backgroundColor: '#ffffff',
  textStyle: { color: '#333' }
  // ... more theme properties
};

const chart = createBarChart(container, config);
applyTheme(chart, customTheme);
```

## API Data Integration

Fetch data from an API and render charts:

```typescript
import { fetchDataAndRender, updateChartFromApi, createLineChart } from '@meanpug/charting';

// Fetch and render in one step
await fetchDataAndRender(
  'chart-container',
  'https://api.example.com/data',
  createLineChart
);

// Update existing chart from API
await updateChartFromApi(
  chart,
  'https://api.example.com/data',
  (data) => ({
    xAxis: data.labels,
    series: data.series
  })
);
```

## Configuration

All chart functions accept a `ChartConfig` object:

```typescript
interface ChartConfig {
  title?: { text: string; [key: string]: any };
  xAxis?: any[];
  yAxis?: any;
  series: SeriesData[];
  legend?: boolean | any;
  tooltip?: boolean | any;
  grid?: any;
  rotateLabels?: number;
}
```

## Examples

### Multi-Series Line Chart

```typescript
import { createLineChart } from '@meanpug/charting';

const chart = createLineChart('container', {
  title: { text: 'Temperature Trends' },
  xAxis: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'],
  series: [
    { name: 'Max Temp', data: [25, 27, 26, 28, 30, 29, 28] },
    { name: 'Min Temp', data: [15, 16, 15, 17, 18, 17, 16] }
  ]
}, 'custom');
```

### Donut Chart with Custom Colors

```typescript
import { createDonutChart } from '@meanpug/charting';

const chart = createDonutChart('container', {
  title: { text: 'Market Share' },
  series: [
    { name: 'Products', data: [
      { name: 'Product A', value: 335 },
      { name: 'Product B', value: 234 },
      { name: 'Product C', value: 154 }
    ]}
  ]
}, 'custom');
```

### Radar Chart

```typescript
import { createRadarChart } from '@meanpug/charting';

const chart = createRadarChart('container', {
  title: { text: 'Performance Metrics' },
  series: [
    {
      name: 'Metrics',
      data: [85, 90, 75, 88, 92],
      indicators: [
        { name: 'Speed', max: 100 },
        { name: 'Accuracy', max: 100 },
        { name: 'Efficiency', max: 100 },
        { name: 'Quality', max: 100 },
        { name: 'Reliability', max: 100 }
      ]
    }
  ]
});
```

## TypeScript

Full TypeScript support with type definitions:

```typescript
import { 
  ChartConfig, 
  SeriesData, 
  Theme, 
  EChartsInstance 
} from '@meanpug/charting';
```

## Browser Support

Supports all modern browsers that Apache ECharts supports:
- Chrome
- Firefox
- Safari
- Edge
- Opera

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

MIT

## Links

- [GitHub Repository](https://github.com/meanpug/meanpug-charting)
- [Issue Tracker](https://github.com/meanpug/meanpug-charting/issues)
- [Apache ECharts Documentation](https://echarts.apache.org/)