@density/chart-line-chart

Line Chart

Chart for displaying information using lines on a 2d grid where the bottom axis is time npm

Using this chart

This chart has a single default export. This exported function takes two arguments: a dom element, and an object full of properties. When called, this chart will render the chart inside the given DOM element. See the below example.

import lineChart from '@density/chart-line-chart';
// or: const lineChart = require('@density/chart-line-chart').default;

const element = document.getElementById('chart-container');
const props = {
  xAxis: exampleAxis({
    prop1: 'value',
    prop2: 'value',
  }),
  yAxis: exampleAxis({
    prop1: 'value',
    prop2: 'value',
  }),
  /* and more... see the 'chart props' section below */
};

// Make your chart
const updateData = lineChart(element);

// Give it new data
updateData(props);

Examples

Take a look at the story for a number of example charts.

Helper library

In addition, if you'd like to render a chart in a context where the DOM is abstracted away from you, such as a React or Angular app, then check out our companion helper library.

How this chart is structured

.
├── index.js        # Contains main chart code. Other javascript files may be present.
├── package.json
├── story.js        # Contains a react-storyboard story. Use it to present different states of your chart in the parent project.
└── styles.scss     # Contains all chart styles.

Chart props

• xAxis: Axis and yAxis: Axis - defines the horizontal and vertical axes used to render the chart. See below for a definition of what makes an Axis.

• xAxisStart: Number | String | moment (optional) - The first value to use on the x axis of the chart. If a Number, it's interpreted as epoch milliseconds. If a String, it's parsed as an ISO timestamp. And, if a moment, it's used as is for chart calculations. If unspecified, it defaults to the first value in the default dataset.

• xAxisEnd: Number | String | moment (optional) - The last value to use on the x axis of the chart. If a Number, it's interpreted as epoch milliseconds. If a String, it's parsed as an ISO timestamp. And, if a moment, it's used as is for chart calculations. If unspecified, it defaults to the last value in the default dataset.

• yAxisStart: Number (optional) - The smallest value to render on the y axis. If unspecified, defaults to the smallest value in the default dataset.

• yAxisEnd: Number (optional) - The largest value to render on the y axis. If unspecified, defaults to the largest value in the default dataset.

• overlayShowPoint: Boolean (optional) - When the user hovers over the graph, should a point be drawn along the default dataset's path? Defaults to true.

• overlayPointRadius: Number (optional) - The radius of the point to render in pixels when the user hovers over the graph. This value is only used if overlayShowPoint is true. Defaults to 4.5.

• overlays: [Overlay] (optional) - An array of overlays to show when the user hovers over the chart. See the overlay documentation below to learn more about how overlays are rendered.

• data: [Dataset] - A number of datasets to render on the chart. See the below documentation on datasets to learn more about the format of a dataset.

Chart subcomponents

The line chart accepts a number of different modules to control how different core chart components are rendered. Currently, there are three types of modules that this chart knows how to work with: Datasets, Axes, and Overlays.

Dataset

A Dataset is a collection of points to render on the graph and a number of associated properties that define how that data should be rendered. A line chart can accept multiple different datasets, potentially each with different rendering parameters.

[
  {
    name: 'default',
    type: dataWaterline,
    data: [
      { timestamp: '2018-04-12T03:55:00.000Z', value: 0 },
      { timestamp: '2018-04-12T03:50:00.000Z', value: 3 },
      { timestamp: '2018-04-12T03:45:00.000Z', value: 1 },
      { timestamp: '2018-04-12T03:40:00.000Z', value: 5 },
    ],
  }
]

Props

• name: String (optional) - An optional name to give to the dataset. This value defaults to default.
• type: DatasetRenderer (optional) - A function to render the dataset to the chart.
• data: [{timestamp: String | Number | moment, value: Number}] - A collection of data to render to the chart. These values are passed through the renderer (type property) to draw them to the screen. timestamp is interpreted as epoch milliseconds if a Number, ISO time if a String, and used explicitly if a moment.
• renderAfterLastDatapoint: Boolean (optional) - Should the data line be continued after the final datapoint until the end of the graph? Defaults to false.

• verticalBaselineOffset: Number (optional) - The number of pixels of dead space below the bottom-most value in the y-direction. Defaults to 0.

Naming datasets, and the default name

Each dataset rendered to the chart has a name associated with it. The special value default is given to the main dataset in the chart. This dataset is then used for determining bounds of each axis (if not specified explicitly), drawing the overlay point / any custom overlays, and in general anything that requires data in order to function.

Note on dataset order

Datasets must be ordered from oldest to newest. If not, the chart will throw an error.

Dataset Renderers

A dataset renderer is a special function that takes a dataset as a first parameter, and a DOM element as it's second parameter. Its job is to render the contents of the dataset passed to it into the DOM within the DOM element passed to it.

// Example Dataset Renderer
function dataExample({data}) {
  return ({xScale, yScale}, element) => {
    const selection = element.selectAll('path').data(data);
    selection.enter()
      .append('path')
    .merge(selection)
      .attr('d', d => d.reduce((acc, i) => {
        // Draw lines to each datapoint in the dataset
        return `${acc} L${xScale(moment.utc(i.timestamp).valueOf())},${yScale(i.value)}`
      }, ''));
    selection.exit().remove();
  }
}

Implemented Dataset Renderers

dataWaterline

Renders a filled polygon reflecting the datapoints with a border on top. Datapoints are drawn by first moving horizontally and then vertically, rather than drawing a line directly point-to-point. It's called a waterline because I needed a spiffy name and it looks a bit like a low-poly wave in the default color scheme.

Props

• (requires a data prop, just like every dataset renderer)
• color: String (optional) - the fill color of the polygon underneath the top border. Defaults to rgba(65, 152, 255, 0.2).
• borderColor: String (optional) - the stroke color of the top border of the waterline. Defaults to rgb(65, 152, 255).

Axis

An Axis contains all the code required to render either the x or y axis on the chart. Each axis is a function that returns a second, closed over function--very similar to a chart. The upper-level function is called by the user so that they can pass configuration parameters to an axis, and the lower level function is called by the chart to pass more non-user-provided configuration parameters and an element to render the axis within. Effectively, an axis looks like this:

export function exampleAxis({color}) {
  color = color || 'royalblue';
  return ({scale}, element) => {
    // Add an axis:
    element.call(d3.axisBottom(scale));

    // Do some custom drawing:
    const selection = element.selectAll('rect').data([10, 20, 30]);
    selection.enter()
      .append('rect')
        .attr('width', 10)
        .attr('height', 10)
        .attr('fill', color)
    .merge(selection)
      .attr('x', d => d)
      .attr('y', d => d)
    selection.exit().remove()
  };
}

// Axis Usage
const lineChart = LineChart(document.body);
lineChart({
  xAxis: exampleAxis({color: 'red'}),
});

Implemented Axes

exampleAxis

The above demo axis is implemented in this package too - import { exampleAxis } from '@density/chart-line-chart/axes';

xAxisDailyTick

This axis renders a time-based x axis using the builtin d3.axisBottom. After rendering, it's styled to match the density aesthetic - a 14px font, in Sailec, and in grayCinder.

import { xAxisDailyTick } from '@density/chart-line-chart/axes';

Props

• formatter: (Number) => String (optional) - A mapping function that accepts the epoch millisecond utc timestamp and returns the axis label for that timestamp.

• bottomOffset: Number (optional) - The distance between the axis and the bottom of the chart graph. Defaults to 15px.

• Pick one of the two below to generate the tick values show on the axis:

  • tickResolutionInMs: Number (optional) - Specify a number of milliseconds of distance to put between each tick value.

  • tickValues: Array (optional) - A list of values that can optionally be passed to explicitly define the location of ticks on the axis. This is passed to the .tickValues method on the d3.axisBottom, and will be mapped through the formatter function if specified.

  • If neither of the above are passed, tickResolutionInMs is used with its default of 1 hour between ticks.

yAxisMinMax

This axis renders a y axis with by default two ticks - one at the maximum value and one at the minimum value. It can be customized to add ticks at arbitrary points, and to style those ticks in a number of ways.

import { yAxisMinMax } from '@density/chart-line-chart/axes';

Props

• formatter: ({value, hasRule, hasShadow}) => String (optional) - A mapping function that accepts a point to render and returns the string value to render for that given point. Defaults to d => d.value.toString().

• leftOffset: Number (optional) - The distance between the axis and the left of the chart graph. Defaults to 20px.

• showMaximumPoint: Boolean (optional) - Should the minimum point on the axis be rendered? Defaults to false.

• showMaximumPoint: Boolean (optional) - Should the maximum point on the axis be rendered? Defaults to false.

• points: [{value: Number, hasRule: Boolean, hasShadow: Boolean}] - A number of additional points to render on the axis. Each value is the location on the axis to draw that point, each hasRule flag indicates if a dotted rule should be drawn across the chart at the location of the point, and the hasShadow flag determines if a shadow should be drawn below a line.

• axisRuleLineDashWidth: Number - The width in pixels of each rule dash. Defaults to 4.
• axisRuleLineDashSpacing: Number - The distance in pixels between each rule dash. Defaults to 10.

Overlay

An overlay is any sort of element that appears on top of the chart when the user hovers over the chart. In a similar fashion to an axis, an overlay presents itself in the form of a function that is called by the user with configuration parameters. However, overlays are much more managed than axes - they are called as part a data join. Therefore, an overlay is expected to return an object from its top-level function that contains three subkeys: enter, merge, and exit. Each is similar to the nested-function inside of an axis: it takes a number of chart-specific configuration values and an selection to render within. Each function is called in its respective life cycle step: enter when a new overlay is drawn, merge when the overlay should be updated, and exit when the overlay should be removed.

Here's a basic example:

function overlayExample({color}) {
  return {
    enter: (data, selection) => {
      selection.append('rect')
        .attr('width', 10)
        .attr('height', 10)
        .attr('fill', color)
    },
    merge: ({mouseX, mouseY}, selection) => {
      selection.select('rect')
      .attr('x', mouseX)
      .attr('y', mouseY)
    },
    exit: (props, selection) => {
      selection.remove()
    },
  };
}

// Overlay Usage
const lineChart = LineChart(document.body);
lineChart({
  overlays: [
    overlayExample({ color: 'red' }),
  ],
});

Implemented Overlays

overlayTwoPopups

This overlay renders a small popup with a drop shadow above and below the chart when the user hovers over the chart on a system with a mouse or touches the chart on a system with a touchscreen.

import { overlayTwoPopups } from '@density/chart-line-chart/overlays';

Props

• topPopupFormatter: {enter: (config, selection) => any, merge: (config, selection) => any, exit: (config, selection) => any} (optional)

A set of three functions that collectively describe the formatting of content of the the upper overlay popup, inspired by a d3 data join.

When the popup is rendered for the first time, enter is called with a d3 selection - within this selection, you have access to modify the DOM with d3 and can set up the structure required for your overlay to function. This is only called once.

When the overlay needs to be re-rendered (due to a mouse movement, for example), merge is called. Just like enter, it's passed a d3 selection, but in addition it's also passed a number of configuration parameters (these are values that may be helpful in drawing the overlay contents, such as the overlay width and height, the data item that is currently hovered-over, the mouse position, etc... A complete list is below.). It's merge's job to take the content rendered by enter and update the dom to reflect the new data in the configuration parameters.

Finally, when the mouse cursor is moved out of the bounds of the chart, the exit function is called - this function should clean up any resources or dom elements that the top overlay has created in enter or merge.

Here's a simple example of a formatter that could be passed to topPopupFormatter. This formatter renders a plain text label on the upper popup that indicates the current y value that is being hovered over:

{
  enter: selection => {
    // Create a new `text` node to render the label within
    selection.append('text')
      .attr('text-anchor', 'middle')
      .attr('font-weight', '500')
  },
  merge: ({topOverlayWidth, item}, selection) => {
    // Update the node to contain the value of the currently hovered-over item
    selection.select('text')
      .attr('transform', `translate(${topOverlayWidth / 2},26)`)
      .text(item.value);
  },
  // Remove all nodes within the selection
  exit: selection => selection.remove(),
}

There are a few stock formatters:

/*
 * `overlayTwoPopupsPlainTextFormatter`: renders the given value centered within the overlay. Accepts
 * a function to map the `config` argument passed to the value to render on the overlay, and the
 * string `top` or `bottom` to pick which overlay's width to use for centering purposes.
 */

// For example:
import { overlayTwoPopupsPlainTextFormatter } from '@density/chart-line-chart/overlays';
const formatter = overlayTwoPopupsPlainTextFormatter( ({item}) => `${item.value}`, 'top' );
// Now use `formatter` as the value for `topPopupFormatter` or `bottomPopupFormatter`!

/*
 * `overlayTwoPopupsPersonIconTextFormatter`: renders a "person" icon and the given value within the
 * overlay. Accepts a function to map the `config` argument passed to the value to render on an
 * overlay, and the string `top` or `bottom` to pick which overlay's width to use for performing
 * icon-positioning calculations.
 */

// For example:
import { overlayTwoPopupsPersonIconTextFormatter } from '@density/chart-line-chart/overlays';
const formatter = overlayTwoPopupsPersonIconTextFormatter( ({item}) => `${item.value}`, 'top' );
// Now use `formatter` as the value for `topPopupFormatter` or `bottomPopupFormatter`!

---

• bottomPopupFormatter: {enter: (config, selection) => any, merge: (config, selection) => any, exit: (config, selection) => any} (optional)

A set of formatter functions that can be used to render the contents within the bottom popover. See the above documentation for topPopupFormatter for an explaination of enter, merge, and exit.

• bottomOverlayTopMargin: Number - The spacing between the top of the bottom overlay and bottom of the chart in pixels.

• topOverlayBottomMargin: Number - The spacing between the bottom of the top overlay and top of the chart in pixels.

• topOverlayWidth: Number - The width of the top overlay, in pixels.
• topOverlayHeight: Number - The height of the top overlay, in pixels.
• bottomOverlayWidth: Number - The width of the bottom overlay, in pixels.
• bottomOverlayHeight: Number - The height of the bottom overlay, in pixels.