npm package: @moxa/chart
Description: This document provides development guidelines for the Chart Library based on [ECharts](https://echarts.apache.org/).
Latest version: 1.2.0

# Moxa Chart - Developer Guide

This document provides development guidelines for the Chart Library based on [ECharts](https://echarts.apache.org/).

## Architecture Overview

The Chart Library is designed with a modular architecture that follows these key principles:

- **Core Base Class**: All chart types extend from a shared `CoreChart` class
- **Type Safety**: Comprehensive TypeScript interfaces for all configuration options
- **Component Reusability**: Shared components and utilities across chart types
- **Adaptable Data Layer**: Flexible data adapters for various input formats

## Project Structure

```
libs/chart/
├── .storybook/               # Storybook configuration
├── src/
│   ├── lib/
│   │   ├── adapters/         # Data adapters for different formats
│   │   ├── charts/           # Chart implementations
│   │   │   ├── bar-chart/    # Bar chart implementation
│   │   │   └── line-chart/   # Line chart implementation
│   │   ├── components/       # Reusable UI components
│   │   │   └── tooltip/      # Tooltip component
│   │   ├── core/             # Core chart functionality
│   │   │   └── core-chart.ts # Base chart class
│   │   ├── types/            # TypeScript type definitions
│   │   │   ├── animation.type.ts
│   │   │   ├── axis.type.ts
│   │   │   ├── chart.type.ts
│   │   │   ├── data.type.ts
│   │   │   ├── grid.type.ts
│   │   │   ├── legend.type.ts
│   │   │   └── tooltip.type.ts
│   │   └── utils/            # Utility functions
│   └── stories/              # Storybook stories
├── package.json              # Package configuration
├── project.json              # Nx project configuration
├── tsconfig.json             # TypeScript configuration
└── vite.config.ts            # Vite configuration
```

## Development Workflow

### Setting Up the Development Environment

1. Install dependencies:

   ```bash
   npm install
   ```

2. Build the library:

   ```bash
   nx build chart
   ```

3. Start Storybook for development:
   ```bash
   nx storybook chart
   ```

### Creating a New Chart Type

To add a new chart type, follow these steps:

1. Create a new directory under `src/lib/charts/` for your chart type (e.g., `pie-chart/`)
2. Create the following files:
   - `[chart-name].type.ts` - Type definitions specific to this chart
   - `[chart-name].ts` - The chart implementation class
   - `index.ts` - Export file
   - `[chart-name].stories.ts` - Storybook examples

Example implementation for a new chart type:

```typescript
// pie-chart.type.ts
import { ChartData } from '../../types';

export interface PieChartData extends ChartData {
  values: number[];
  labels?: string[];
  radius?: string | number | string[] | number[];
}

// pie-chart.ts
import { EChartsOption } from 'echarts';
import { CoreChart } from '../../core';
import { PieChartData } from './pie-chart.type';

export class PieChart extends CoreChart {
  private data: PieChartData;

  constructor(domElement: HTMLElement, data: PieChartData) {
    super(domElement);
    this.data = data;
  }

  render(): void {
    const option: EChartsOption = {
      title: { text: this.data.title },
      series: [
        {
          type: 'pie',
          radius: this.data.radius || '50%',
          data: this.data.values.map((value, index) => ({
            value,
            name: this.data.labels?.[index] || `Item ${index + 1}`,
          })),
        },
      ],
    };
    this.setOption(option);
  }

  updateData(newData: PieChartData): void {
    this.data = newData;
    this.render();
  }
}

// index.ts
export * from './pie-chart';
export * from './pie-chart.type';
```

3. Add your new chart to the main exports in `src/lib/charts/index.ts`

### Extending Existing Components

When modifying existing components:

1. Maintain backward compatibility
2. Add new properties to the corresponding type definitions
3. Update the rendering logic in the chart class
4. Add Storybook examples for new features

## Core Class Architecture

The `CoreChart` class provides the foundation for all chart types:

```typescript
// Brief overview of core-chart.ts
export class CoreChart {
  chart: ECharts;

  constructor(domElement: HTMLElement, theme = 'light') {
    this.chart = echarts.init(domElement, theme);
  }

  setOption(option: echarts.EChartsOption): void {
    this.chart.setOption(option);
  }

  resize(): void {
    this.chart.resize();
  }

  dispose(): void {
    this.chart.dispose();
  }
}
```

When extending this class, always call the parent constructor and implement the `render()` method.

## Type System

The type system is designed to be extensible:

- `ChartData` - Base interface for all chart data
- Specific chart types extend this base interface
- Helper types for various chart components (axis, legend, etc.)

When adding new properties, add them to the appropriate type definition file.

## Testing Guidelines

Create comprehensive tests for all components:

1. Unit tests for individual functions
2. Integration tests for chart rendering
3. Visual regression tests using Storybook

Run tests with:

```bash
nx test chart
```

## Build and Release Process

1. Update version in `package.json`
2. Build the library:
   ```bash
   nx build chart
   ```
3. Test the build:
   ```bash
   nx test chart
   ```
4. Create a pull request with your changes
5. After approval and merge, the CI/CD pipeline will publish the new version

## Development Commands

- `nx build chart` - Build the library
- `nx test chart` - Run unit tests
- `nx storybook chart` - Start Storybook for development
- `nx build-storybook chart` - Build Storybook to `dist/storybook/chart`
- `nx lint chart` - Run lint checks