# Visual Elements

Core visual components for rendering chart elements. Elements handle the drawing and interaction logic for different visual shapes used in charts.

## Capabilities

### Bar Element

Renders rectangular bars for bar charts.

```javascript { .api }
class BarElement extends Element {
  static id: 'bar';
  static defaults: object;
  static defaultRoutes: object;
  
  // Properties
  x: number;
  y: number;
  base: number;
  horizontal: boolean;
  width: number;
  height: number;
  
  // Methods
  draw(ctx: CanvasRenderingContext2D): void;
  inRange(mouseX: number, mouseY: number, useFinalPosition?: boolean): boolean;
  inXRange(mouseX: number, useFinalPosition?: boolean): boolean;
  inYRange(mouseY: number, useFinalPosition?: boolean): boolean;
  getCenterPoint(useFinalPosition?: boolean): Point;
  getRange(axis: 'x' | 'y'): number;
}

interface BarElementOptions {
  backgroundColor: Color;
  borderColor: Color;
  borderSkipped: 'start' | 'end' | 'middle' | 'bottom' | 'left' | 'top' | 'right' | boolean;
  borderWidth: number;
  borderRadius: number | BorderRadius;
  inflateAmount: number | 'auto';
}
```

**Usage Example:**

```javascript
// Bar element styling
const config = {
  type: 'bar',
  data: { /* data */ },
  options: {
    elements: {
      bar: {
        backgroundColor: 'rgba(75, 192, 192, 0.2)',
        borderColor: 'rgba(75, 192, 192, 1)',
        borderWidth: 2,
        borderRadius: 4,
        borderSkipped: false
      }
    }
  }
};
```

### Line Element

Renders line paths connecting data points.

```javascript { .api }
class LineElement extends Element {
  static id: 'line';
  static defaults: object;
  static defaultRoutes: object;
  
  // Properties
  points: PointElement[];
  segments: LineSegment[];
  first: boolean;
  last: boolean;
  smooth: boolean;
  
  // Methods
  draw(ctx: CanvasRenderingContext2D): void;
  interpolate(point: PointElement, property: string): unknown;
  pathSegment(ctx: CanvasRenderingContext2D, segment: LineSegment, params: SegmentParams): boolean | void;
  path(ctx: CanvasRenderingContext2D): boolean | void;
}

interface LineElementOptions {
  backgroundColor: Color;
  borderCapStyle: CanvasLineCap;
  borderColor: Color;
  borderDash: number[];
  borderDashOffset: number;
  borderJoinStyle: CanvasLineJoin;
  borderWidth: number;
  fill: boolean | string | number | object;
  stepped: boolean | 'before' | 'after' | 'middle';
  tension: number;
}

interface LineSegment {
  start: number;
  end: number;
  loop: boolean;
}

interface SegmentParams {
  move: boolean;
  reverse: boolean;
}
```

**Usage Example:**

```javascript
// Line element styling
const config = {
  type: 'line',
  data: { /* data */ },
  options: {
    elements: {
      line: {
        borderColor: 'rgba(255, 99, 132, 1)',
        borderWidth: 3,
        borderDash: [5, 5],
        borderCapStyle: 'round',
        borderJoinStyle: 'round',
        fill: false,
        tension: 0.4
      }
    }
  }
};
```

### Point Element

Renders individual data points and markers.

```javascript { .api }
class PointElement extends Element {
  static id: 'point';
  static defaults: object;
  static defaultRoutes: object;
  
  // Properties
  x: number;
  y: number;
  size: number;
  
  // Methods
  draw(ctx: CanvasRenderingContext2D, area?: ChartArea): void;
  inRange(mouseX: number, mouseY: number, useFinalPosition?: boolean): boolean;
  inXRange(mouseX: number, useFinalPosition?: boolean): boolean;
  inYRange(mouseY: number, useFinalPosition?: boolean): boolean;
  getCenterPoint(useFinalPosition?: boolean): Point;
  size(options?: PointElementOptions): number;
  resolveElementProperties(chart: Chart, options: PointElementOptions): void;
}

interface PointElementOptions {
  backgroundColor: Color;
  borderColor: Color;
  borderWidth: number;
  hitRadius: number;
  hoverBackgroundColor: Color;
  hoverBorderColor: Color;
  hoverBorderWidth: number;
  hoverRadius: number;
  pointStyle: PointStyle | HTMLImageElement | HTMLCanvasElement;
  radius: number;
  rotation: number;
}

type PointStyle = 'circle' | 'cross' | 'crossRot' | 'dash' | 'line' | 'rect' | 'rectRounded' | 'rectRot' | 'star' | 'triangle';
```

**Usage Example:**

```javascript
// Point element styling
const config = {
  type: 'line',
  data: { /* data */ },
  options: {
    elements: {
      point: {
        backgroundColor: 'rgba(255, 206, 86, 1)',
        borderColor: 'rgba(255, 206, 86, 1)',
        borderWidth: 2,
        radius: 6,
        pointStyle: 'circle',
        hoverRadius: 8,
        hoverBorderWidth: 3
      }
    }
  }
};
```

### Arc Element

Renders arc/sector shapes for pie and doughnut charts.

```javascript { .api }
class ArcElement extends Element {
  static id: 'arc';
  static defaults: object;
  static defaultRoutes: object;
  
  // Properties
  x: number;
  y: number;
  startAngle: number;
  endAngle: number;
  innerRadius: number;
  outerRadius: number;
  circumference: number;
  
  // Methods
  draw(ctx: CanvasRenderingContext2D): void;
  inRange(mouseX: number, mouseY: number, useFinalPosition?: boolean): boolean;
  inXRange(mouseX: number, useFinalPosition?: boolean): boolean;
  inYRange(mouseY: number, useFinalPosition?: boolean): boolean;
  getCenterPoint(useFinalPosition?: boolean): Point;
  getAngle(): number;
  tooltipPosition(): Point;
}

interface ArcElementOptions {
  angle: number;
  backgroundColor: Color;
  borderAlign: 'center' | 'inner';
  borderColor: Color;
  borderJoinStyle: CanvasLineJoin;
  borderRadius: number | ArcBorderRadius;
  borderWidth: number;
  offset: number;
  spacing: number;
  circular: boolean;
}

interface ArcBorderRadius {
  outerStart?: number;
  outerEnd?: number;
  innerStart?: number;
  innerEnd?: number;
}
```

**Usage Example:**

```javascript
// Arc element styling
const config = {
  type: 'doughnut',
  data: { /* data */ },
  options: {
    elements: {
      arc: {
        backgroundColor: 'rgba(153, 102, 255, 0.2)',
        borderColor: 'rgba(153, 102, 255, 1)',
        borderWidth: 2,
        borderAlign: 'center',
        spacing: 2,
        borderRadius: 4
      }
    }
  }
};
```

### Base Element Interface

Common interface implemented by all elements.

```javascript { .api }
interface Element {
  // Properties
  readonly chart: Chart;
  active: boolean;
  options: ElementOptions;
  
  // Core methods
  draw(ctx: CanvasRenderingContext2D, area?: ChartArea): void;
  
  // Hit detection methods
  inRange(mouseX: number, mouseY: number, useFinalPosition?: boolean): boolean;
  inXRange(mouseX: number, useFinalPosition?: boolean): boolean;
  inYRange(mouseY: number, useFinalPosition?: boolean): boolean;
  
  // Position methods
  getCenterPoint(useFinalPosition?: boolean): Point;
  getRange?(axis: 'x' | 'y'): number;
  
  // Lifecycle methods  
  tooltipPosition?(useFinalPosition?: boolean): Point;
  hasValue?(): boolean;
  getProps?(props: string[], final?: boolean): { [key: string]: unknown };
}
```

### Element Factory

Helper for creating element instances.

```javascript { .api }
interface ElementFactory {
  create<T extends Element>(type: string, scope: object, values: object): T;
  update<T extends Element>(element: T, properties: object, active: boolean): void;
}
```

## Element Registration

Elements must be registered before use in charts.

```javascript { .api }
import {
  Chart,
  BarElement,
  LineElement,
  PointElement,
  ArcElement
} from 'chart.js';

// Register elements
Chart.register(
  BarElement,
  LineElement,
  PointElement,
  ArcElement
);
```

## Animation Properties

Elements support property animation during chart updates.

```javascript { .api }
interface AnimatableElement {
  // Properties that can be animated
  x?: number;
  y?: number;
  width?: number;
  height?: number;
  radius?: number;
  innerRadius?: number;
  outerRadius?: number;
  startAngle?: number;
  endAngle?: number;
  backgroundColor?: Color;
  borderColor?: Color;
  borderWidth?: number;
}
```

**Usage Example:**

```javascript
// Custom animation configuration
const config = {
  type: 'bar',
  data: { /* data */ },
  options: {
    animation: {
      duration: 2000,
      easing: 'easeInOutQuart'
    },
    animations: {
      x: {
        type: 'number',
        easing: 'linear',
        duration: 1000,
        from: 0
      },
      y: {
        type: 'number',
        easing: 'easeInOutCubic',
        duration: 1500,
        delay: 500
      }
    }
  }
};
```

## Types

```javascript { .api }
interface Point {
  x: number;
  y: number;
}

interface BorderRadius {
  topLeft: number;
  topRight: number;
  bottomLeft: number;
  bottomRight: number;
}

interface ChartArea {
  left: number;
  top: number;
  right: number;
  bottom: number;
  width: number;
  height: number;
}

type Color = string | CanvasGradient | CanvasPattern;

interface ElementOptions {
  [key: string]: unknown;
}
```