# Chart.js

Chart.js is a comprehensive JavaScript charting library that enables developers to create responsive, interactive HTML5 charts using the Canvas element. It provides a wide variety of chart types including line, bar, radar, doughnut, pie, polar area, bubble, and scatter charts with extensive customization options for colors, animations, tooltips, legends, and data interactions.

## Package Information

- **Package Name**: chart.js
- **Package Type**: npm
- **Language**: JavaScript/TypeScript
- **Installation**: `npm install chart.js`

## Core Imports

```javascript
import { Chart } from "chart.js";
```

Import with auto-registration of all components:

```javascript
import Chart from "chart.js/auto";
```

For tree-shaking, import components selectively:

```javascript
import {
  Chart,
  CategoryScale,
  LinearScale,
  BarElement,
  Title,
  Tooltip,
  Legend,
} from "chart.js";

Chart.register(CategoryScale, LinearScale, BarElement, Title, Tooltip, Legend);
```

CommonJS:

```javascript
const { Chart } = require("chart.js");
```

## Basic Usage

```javascript
import { Chart } from "chart.js/auto";

// Create a basic bar chart
const ctx = document.getElementById('myChart').getContext('2d');
const myChart = new Chart(ctx, {
  type: 'bar',
  data: {
    labels: ['Red', 'Blue', 'Yellow', 'Green', 'Purple', 'Orange'],
    datasets: [{
      label: '# of Votes',
      data: [12, 19, 3, 5, 2, 3],
      backgroundColor: [
        'rgba(255, 99, 132, 0.2)',
        'rgba(54, 162, 235, 0.2)',
        'rgba(255, 205, 86, 0.2)',
        'rgba(75, 192, 192, 0.2)',
        'rgba(153, 102, 255, 0.2)',
        'rgba(255, 159, 64, 0.2)'
      ],
      borderColor: [
        'rgba(255, 99, 132, 1)',
        'rgba(54, 162, 235, 1)',
        'rgba(255, 205, 86, 1)',
        'rgba(75, 192, 192, 1)',
        'rgba(153, 102, 255, 1)',
        'rgba(255, 159, 64, 1)'
      ],
      borderWidth: 1
    }]
  },
  options: {
    scales: {
      y: {
        beginAtZero: true
      }
    }
  }
});
```

## Architecture

Chart.js is built around several key components:

- **Chart Class**: The main class for creating and managing chart instances
- **Controllers**: Chart-type-specific logic for data processing (BarController, LineController, etc.)
- **Elements**: Visual components for rendering (BarElement, LineElement, PointElement, ArcElement) 
- **Scales**: Data-to-pixel conversion and axis rendering (LinearScale, CategoryScale, TimeScale, etc.)
- **Plugins**: Extensible functionality system (Tooltip, Legend, Title, etc.)
- **Registry**: Component registration and management system
- **Platform**: Environment abstraction (DOM, Basic, Custom platforms)

## Capabilities

### Chart Management

Core Chart class functionality for creating, updating, and managing chart instances.

```javascript { .api }
class Chart {
  constructor(item: ChartItem, config: ChartConfiguration);
  
  // Instance methods
  update(mode?: UpdateMode): void;
  render(): void;
  resize(width?: number, height?: number): void;
  destroy(): void;
  toBase64Image(type?: string, quality?: unknown): string;
  
  // Static methods
  static getChart(key: string | CanvasRenderingContext2D | HTMLCanvasElement): Chart;
  static register(...items: ChartComponentLike[]): void;
  static unregister(...items: ChartComponentLike[]): void;
}
```

[Chart Management](./chart-management.md)

### Chart Types

Built-in chart type controllers for different visualization patterns.

```javascript { .api }
// Available chart types
type ChartType = 'line' | 'bar' | 'radar' | 'doughnut' | 'pie' | 'polarArea' | 'bubble' | 'scatter';

// Controllers
class BarController extends DatasetController { }
class LineController extends DatasetController { }
class RadarController extends DatasetController { }
class DoughnutController extends DatasetController { }
class PieController extends DoughnutController { }
class PolarAreaController extends DatasetController { }
class BubbleController extends DatasetController { }
class ScatterController extends LineController { }
```

[Chart Types](./chart-types.md)

### Scales

Data-to-pixel conversion and axis rendering for different data types.

```javascript { .api }
// Available scale types
type ScaleType = 'linear' | 'logarithmic' | 'category' | 'time' | 'timeseries' | 'radialLinear';

// Base scale interface
interface Scale {
  getPixelForValue(value: unknown): number;
  getValueForPixel(pixel: number): unknown;
  getLabelForValue(value: unknown): string;
  getDecimalForPixel(pixel: number): number;
}
```

[Scales](./scales.md)

### Visual Elements

Core visual components for rendering chart elements.

```javascript { .api }
// Element classes
class BarElement extends Element { }
class LineElement extends Element { }
class PointElement extends Element { }
class ArcElement extends Element { }

// Base element interface
interface Element {
  draw(ctx: CanvasRenderingContext2D): void;
  inRange(mouseX: number, mouseY: number): boolean;
  inXRange(mouseX: number): boolean; 
  inYRange(mouseY: number): boolean;
  getCenterPoint(): Point;
}
```

[Visual Elements](./visual-elements.md)

### Plugins

Built-in and extensible plugin system for additional functionality.

```javascript { .api }
// Built-in plugins
const Title: Plugin;
const Legend: Plugin;
const Tooltip: Plugin;
const SubTitle: Plugin;
const Filler: Plugin;
const Decimation: Plugin;
const Colors: Plugin;

// Plugin interface
interface Plugin {
  id: string;
  beforeInit?(chart: Chart, args: EmptyObject, options: O): void;
  afterInit?(chart: Chart, args: EmptyObject, options: O): void;
  beforeUpdate?(chart: Chart, args: UpdateArgs, options: O): void;
  afterUpdate?(chart: Chart, args: UpdateArgs, options: O): void;
  // ... more lifecycle hooks
}
```

[Plugins](./plugins.md)

### Utilities

Helper functions for common operations, calculations, and canvas manipulation.

```javascript { .api }
// Color utilities
function color(value: string | CanvasGradient | CanvasPattern): Color;
function getHoverColor(color: Color): Color;

// Core utilities  
function isArray(value: unknown): value is unknown[];
function isObject(value: unknown): value is object;
function valueOrDefault<T>(value: T | undefined, defaultValue: T): T;

// Canvas utilities
function clearCanvas(ctx: CanvasRenderingContext2D): void;
function drawPoint(ctx: CanvasRenderingContext2D, options: PointOptions, x: number, y: number): void;
```

[Utilities](./utilities.md)

## Types

```javascript { .api }
interface ChartConfiguration<TType extends ChartType = ChartType, TData = DefaultDataPoint<TType>, TLabel = unknown> {
  type: TType;
  data: ChartData<TType, TData, TLabel>;
  options?: ChartOptions<TType>;
  plugins?: Plugin[];
}

interface ChartData<TType extends ChartType = ChartType, TData = DefaultDataPoint<TType>, TLabel = unknown> {
  labels?: TLabel[];
  datasets: ChartDataset<TType, TData>[];
}

interface ChartOptions<TType extends ChartType = ChartType> {
  responsive?: boolean;
  maintainAspectRatio?: boolean;
  aspectRatio?: number;
  resizeDelay?: number;
  devicePixelRatio?: number;
  hover?: HoverOptions<TType>;
  events?: Event[];
  onClick?: (event: ChartEvent, elements: ActiveElement[], chart: Chart) => void;
  plugins?: PluginOptionsByType<TType>;
  scales?: ScaleOptionsByType<TType>;
  elements?: ElementOptionsByType<TType>;
  layout?: LayoutOptions;
  animation?: AnimationOptions<TType>;
  animations?: AnimationOptions<TType>;
  transitions?: TransitionsSpec<TType>;
}

type UpdateMode = 'resize' | 'reset' | 'none' | 'hide' | 'show' | 'default' | 'active';

interface Point {
  x: number;
  y: number;
}

interface Color {
  r: number;
  g: number;
  b: number;
  a: number;
}

type ChartItem =
  | string
  | CanvasRenderingContext2D
  | HTMLCanvasElement
  | { canvas: HTMLCanvasElement }
  | ArrayLike<CanvasRenderingContext2D | HTMLCanvasElement>;
```