Data Contract

Charts in the Pioneer Charts library utilize a shared based configuration for simplicity and familiarization.

The base interface for all configuration of a chart is centered around the idea that raw data, no matter how complex, can always be expressed as a multi-dimensional array.

PcacData

export class PcacData {
  key: string | number | null = null;
  value: string | number | null = null;
  /**
   * Hides an item while keeping its place in the color order. On a
   * line/area/plot series: its line/area, points and hover effects aren't
   * drawn. On a bar, or a whole bar group: drawn at zero size, keeping its
   * slot. On a pie slice: given no angle.
   */
  hide: boolean = false;
  data: PcacData[] = [];
  /**
   * Line/area/plot charts only, on a point: URL (or data URI) of an
   * image to draw in place of its dot, sized by the config's pointImage.
   */
  image?: string;
}

When a configuration interface is created for a chart, it starts off with a representation of raw data. data: PcacData[]; represent the base of our multi-dimensional array that we discussed above.

PcacChartConfig

export class PcacChartConfig {
  data: PcacData[] = [];
  /** Height in pixels. */
  height: number = 200;
  /** If true, height is a minimum and the chart fills a taller container. */
  heightFull?: boolean = false;
  /** What the chart shows, for screen readers. Defaults to its type ('Bar chart', ...). */
  ariaLabel?: string;
}

/** Every chart with axes (bar, line, area, plot - not pie) extends this instead. */
export class PcacAxisChartConfig extends PcacChartConfig {
  xAxis?: PcacAxisConfig = new PcacAxisConfig();
  yAxis?: PcacAxisConfig = new PcacAxisConfig();
}

Every chart shares these basic configuration parameters, so they live on one base class whose data is the PcacData[] above. Charts with axes add the per-axis xAxis / yAxis objects through PcacAxisChartConfig (see the Axis Styling guide). Configs are classes rather than interfaces so that new gives you every default; a plain object literal (or JSON) works too, but then anything left out is simply unset.

New Chart Config

With a base that represents the shared aspects of every chart and a repeatable contract for raw data, each chart's own config extends one of those bases and adds its chart-specific fields alongside. The vertical bar chart's, for example, is the following; every chart's page documents its fields under API.

export class PcacBarVerticalChartConfig extends PcacAxisChartConfig {
  isStacked: boolean = false;
  thresholds: PcacData[] = [];
  spreadColorsPerGroup: boolean = false;
  colorOverride: string[] = [];
}

Binding Configuration

When adding a chart to your markup, you will typically bind your data and configuration on the [config] input of that chart.

<pcac-bar-vertical-chart [config]="config" />

Type the config as the specific chart's config class. Spreading a new instance is the easy way to pick up every default while overriding only what you need:

// Spread the class's defaults so an object literal only has to name what it changes.
const config: PcacBarVerticalChartConfig = { ...new PcacBarVerticalChartConfig(), data, isStacked: true };

// Or build one with new and assign to it.
const config = new PcacBarVerticalChartConfig();
config.data = data;