Moxa Chart - Developer Guide

This document provides development guidelines for the Chart Library based on ECharts.

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:

   npm install

2. Build the library:

   nx build chart

3. Start Storybook for development:

   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:

// 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:

// 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:

nx test chart

Build and Release Process

1. Update version in package.json
2. Build the library:

   nx build chart

3. Test the build:

   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