Bullet

Reusable Bullet Chart API class that renders a simple and configurable Bullet Chart.

A bullet chart shows one number against a target and some bands of context, like a compact gauge for "are we on track?". One chart draws one metric, so to show several, create one chart per metric, each in its own element.

The data

The data is a single object, not an array:

Field	What it draws	Typical use
ranges	Full-height background bands, widest at the back and fading by opacity	Poor, fair and good thresholds
measures	Thinner bars on top of the bands	The actual value, and optionally a second one such as a forecast
markers	Vertical lines, optional	The target

Give the values in any order: the chart sorts them. The narrowest measure is the strongest, so a second, longer measure reads as a forecast. The axis runs from 0 to the largest value in any of the three fields, and the first three colours of colorSchema go to the ranges, the measures and the markers, in that order.

What it does not have

The chart draws no label, so put the metric's name in your own markup next to it; a11yTitle only names it for screen readers. It has no tooltip and fires no events.

Example

import { bullet } from '@britecharts/core';

bullet()
    .width(600)
    .height(100)
    .a11yTitle('Revenue against target')
    .numberFormat('$,.0f')
    .render('#revenue', {
        ranges: [1500, 2100, 3500], // bands: poor, fair, good
        measures: [1800, 2200],     // the actual values
        markers: [2600],            // the target
    });

• Bullet
  • bullet(_selection, _data)
    • static
      • .a11yTitle(_x) ⇒ String | null | module
      • .a11yDescription(_x) ⇒ String | null | module
      • .a11yDataTable(_x) ⇒ Boolean | module
      • .colorSchema(_x) ⇒ Array.<String> | module
      • .exportChart(filename, title) ⇒ Promise
      • .isLoading(_flag) ⇒ boolean | module
      • .height(_x) ⇒ Number | module
      • .isReverse(_x) ⇒ Boolean | module
      • .margin(_x) ⇒ margin | module
      • .numberFormat(_x) ⇒ string | module
      • .paddingBetweenAxisAndChart(_x) ⇒ Number | module
      • .startMaxRangeOpacity(_x) ⇒ Number | module
      • .ticks(_x) ⇒ Number | module
      • .width(_x) ⇒ Number | module
      • .render(target, [data]) ⇒ module
    • inner
      • ~BulletChartData : Object

bullet(_selection, _data)

This function creates the graph using the selection as container

Kind: Exported function

Param	Type	Description
_selection	D3Selection	A d3 selection that represents the container(s) where the chart(s) will be rendered
_data	BulletChartData	The data to attach and generate the chart

a11yTitle(_x) ⇒ String | null | module

Gets or Sets the name screen readers announce for the chart. It is set as the svg's aria-label. Unset, the chart is announced as "Bullet chart".

Kind: method of bullet
Returns: String | null | module - Current a11yTitle or Chart module to chain calls
Access: public

Param	Type	Description
_x	String | null	Desired accessible title for the chart

a11yDescription(_x) ⇒ String | null | module

Gets or Sets a longer description screen readers announce after the chart's name, such as what the data shows. It is rendered as the svg's <desc>. Unset, the chart has no description.

Kind: method of bullet
Returns: String | null | module - Current a11yDescription or Chart module to chain calls
Access: public

Param	Type	Description
_x	String | null	Desired accessible description for the chart

a11yDataTable(_x) ⇒ Boolean | module

Gets or Sets whether the chart renders its data as a visually hidden table after its svg, which screen readers can read cell by cell. On by default; set it to false when the app gives the data its own accessible form.

Kind: method of bullet
Returns: Boolean | module - Current a11yDataTable or Chart module to chain calls
Access: public

Param	Type	Description
_x	Boolean	Whether to render the data table

colorSchema(_x) ⇒ Array.<String> | module

Gets or Sets the colorSchema of the chart. The first color from the array will be applied to range bars (the wider bars). The second color from the array will be applied to measure bars (the narrow bars) and the third color will be applied to the marker lines.

Kind: method of bullet
Returns: Array.<String> | module - Current colorSchema or Chart module to chain calls
Access: public

Param	Type	Description
_x	Array.<String>	Desired colorSchema for the graph

exportChart(filename, title) ⇒ Promise

Exports the chart and fires a download: an svg file when the filename ends in .svg, and a png otherwise

Kind: method of bullet
Returns: Promise - Promise that resolves if the chart image was loaded and downloaded successfully
Access: public

Param	Type	Description
filename	String	Name of the downloaded file, whose extension picks the format
title	String	Title to add at the top of the exported picture

isLoading(_flag) ⇒ boolean | module

Gets or Sets the loading state of the chart

Kind: method of bullet
Returns: boolean | module - Current loading state flag or Chart module to chain calls
Access: public

Param	Type	Description
_flag	boolean	Desired value for the loading state

Example

chart.isLoading(true)

height(_x) ⇒ Number | module

Gets or Sets the height of the chart

Kind: method of bullet
Returns: Number | module - Current height or Chart module to chain calls
Access: public

Param	Type	Description
_x	Number	Desired height for the chart

isReverse(_x) ⇒ Boolean | module

Gets or Sets the isReverse status of the chart. If true, the elements will be rendered in reverse order.

Kind: method of bullet
Returns: Boolean | module - Current height or Chart module to chain calls
Access: public

Param	Type	Default	Description
_x	Boolean	false	Desired height for the chart

margin(_x) ⇒ margin | module

Gets or Sets the margin of the chart

Kind: method of bullet
Returns: margin | module - Current margin or Chart module to chain calls
Access: public

Param	Type	Description
_x	Object	Margin object to get/set

numberFormat(_x) ⇒ string | module

Gets or Sets the number format of the bar chart

Kind: method of bullet
Returns: string | module - Current numberFormat or Chart module to chain calls
Access: public

Param	Type	Description
_x	string	= ',f' Desired numberFormat for the chart. See examples here

paddingBetweenAxisAndChart(_x) ⇒ Number | module

Space between axis and chart

Kind: method of bullet
Returns: Number | module - Current value of paddingBetweenAxisAndChart or Chart module to chain calls
Access: public

Param	Type	Default	Description
_x	Number	5	Space between y axis and chart

startMaxRangeOpacity(_x) ⇒ Number | module

Gets or Sets the starting point of the capacity range.

Kind: method of bullet
Returns: Number | module - current startMaxRangeOpacity or Chart module to chain calls
Access: public

Param	Type	Default	Description
_x	Number	0.5	Desired startMaxRangeOpacity for chart

Example

bulletChart.startMaxRangeOpacity(0.8)

ticks(_x) ⇒ Number | module

Gets or Sets the number of ticks of the x axis on the chart

Kind: method of bullet
Returns: Number | module - Current ticks or Chart module to chain calls
Access: public

Param	Type	Description
_x	Number	= 5 Desired horizontal ticks

width(_x) ⇒ Number | module

Gets or Sets the width of the chart

Kind: method of bullet
Returns: Number | module - Current width or Chart module to chain calls
Access: public

Param	Type	Description
_x	Number	Desired width for the chart

render(target, [data]) ⇒ module

Draws the chart into a target: a CSS selector, an element or a d3 selection, as select(target).datum(data).call(chart) does. A selector draws into the first element it matches. Without data, the chart redraws with the data it last drew there.

Kind: method of bullet
Returns: module - The chart module, to chain calls
Throws:

• Error When the target matches no element

Access: public

Param	Type	Description
target	String | Element | D3Selection	Where to draw the chart
[data]	Object	The data to draw

Example

bullet().width(600).render('#chart', data);

exports~BulletChartData : Object

Kind: inner typedef of bullet
Properties

Name	Type	Description
ranges	Array.<Number>	Background bands, such as poor, fair and good thresholds
measures	Array.<Number>	Bars for the actual values, such as a result and a forecast
[markers]	Array.<Number>	Marker lines for the targets

Example

{
     ranges: [130, 160, 250],
     measures: [150, 180],
     markers: [175]
}