or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

chart-management.mdchart-types.mdindex.mdplugins.mdscales.mdutilities.mdvisual-elements.md
tile.json

visual-elements.mddocs/

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.

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:

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

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:

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

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:

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

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:

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

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.

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.

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.

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:

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

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;
}