@intoto-dev/bibliotheca-graph

<Graph /> component

Live Demo

Graph allows the user to visualize data in a graph format. It has multiple variations of how to visualise the data which is provided. It supports displaying tooltip information, line charts, bar charts, missing data, predictions, threshold ranges, and mean level.

Installation

Add Graph to your project with the following command:

npm i @intoto-dev/bibliotheca-graph

Basic Usage

There are two properties on the graph component which are mandatory. series is a list of lines or bars to be displayed and their options (more details below). t is the translation function to be used to translate messages and text used in the component, more information below.

import { Graph } from '@intoto-dev/bibliotheca-graph';

const series = []; // Array of series data
const t = translationLibrary; // Load in your preferred translation library

<Graph
  series={series}
  t={t}
/>

What are series?

Series is an array containing information about the data which needs to be plotted in the graph. Each item describes a line or bar, their name, and the data they contain.

This is an example of a series, which is very bare bones and has no options whatsoever. You can use this as a starting point for your own series. Refer to the live demos for some examples of how to make nicer looking series.

const series = [
  {
    key: 'identifier',
    data: [
      { value: 1, date: '2022-05-06T09:00:00.000Z' },
      { value: 2, date: '2022-05-06T09:01:00.000Z' },
      // ... etc
    ],
  },
];

Note that dates are in ISO 8601 format and can contain (and should contain) timezone information. This information is used to render the data points when they happened locally, and not relative to the user. For instance: a data point recorded at 12:00:00 in UTC+0:00 is also shown as 12:00:00 when the user viewing the data is in UTC+02:00. Graph handles the shifting in date for you.

Translation function

The function you provide to t is used to translate messages and text. It gets a string as the first argument and expects a string to be returned. It would look like so in TypeScript:

const t = (key: string) => 'Translated string';

A great library to use for this is i18next, or more specifically in React: react-i18next.

The most basic implementation (also found in Storybook examples) is:

const t = (key: string) => {
    switch (key) {
      case 'updated_at':
        return 'Updated {time} ago';
      case 'missing':
        return 'Missing data';
      case 'mean_level':
        return 'Mean-level';
      default:
        return 'Prediction';
    }
};

This includes all possible translation keys and an example of how {time} is used in updated_at.

API

React Component: <Graph />

import { Graph } from '@intoto-dev/bibliotheca-graph';

Property	Description	Type	Default
series *	List of series to be displayed in the graph.	GraphSeries[]
t *	Translation function.	(key: string) => string
height	Height of the graph in pixels.	number	200
tooltip	Whether to show a tooltip when hovering over a point.	boolean	true
stacked	Whether to display the series in a stacked manner. Default is merged into a single Y-axis (multiple lines in a graph).	boolean	false
navigation	Whether to display the navigation bar. This allows zooming of large data sets.	boolean	false
lang	Language to used for the graph. This is mainly for date formatting.	'en' or 'nb'	en
locale	The date-fns locale to use for date formatting.	Locale	en-US
showCurrent	Draws a line at the current time and shows the current value of the first series at that point.	boolean	false
lines	A list of extra lines to be drawn in the graph. Useful for mean-level and "now" (helpers available)	GraphLine[]	[]
onTooltipValueChange	Callback for when the tooltip value changes. Used for external communication.	(value: number) => void

Type: GraphSeries

Property	Description	Type	Default
key *	Unique identifier for the series.	string
data *	List of data points to be displayed in the series.	DataPoint[]
type	Type of series to be displayed.	'line' or 'bar'	'line'
name	How the series is called and displayed in the legend.	string
color	Hexadecimal color code line / bar in the series.	string
threshold	The level (value) where the threshold is broken.	number
thresholdColor	Hexadecimal color code for the threshold line (normal will be other color).	string
thresholdDirection	Direction of where the threshold is calculated from.	'up' or 'down'	'up'
domain	Domain of the series (min and max values). This automatically calculated from the data, but can be overwritten.	[number, number]
labelWidth	Width of the label in pixels on the Y-Axis.	number	44
axisHeight	Height of the axis in pixels on the Y-Axis. Defaults to the graph's height.	number
barWidth	Width of the bar in a bar chart. This is automatically calculated, but can be overwritten.	number
barPadding	Padding between bars in a bar chart. This is automatically calculated, but can be overwritten.	number
barOpacity	Opacity of the bar in a bar chart.	number	1
unit	Unit to be appended to the values in the series.	string
formatValue	Format function for the values in the series.	(value: number) => string or number	(value: number) => value
curve	Curve to be used for drawing the line. A list of curves can be found in the visx/curves library.	CurveFactory	curveNatural
area	Whether to draw a gradient filled area from the drawn line to the bottom.	boolean	false
bottom	The value which is considered the bottom for the area. Automatically calculated as the lowest value in data.	number
tooltipExtra	Pass a React Component or Function Component which accepts point as a property to render extra content in the tooltip on hover.	FunctionComponent<{ point: DatePoint }> or ComponentClass<{ point: DatePoint }>

Type: DataPoint

Property	Description	Type	Default
value *	Value of the data point	number
date *	Date of the data point (ISO 8601)	string
missing	Whether the data point needs to be marked as missing	boolean	false
prediction	Whether the data point is a prediction	boolean	false
minValue	When the data point is a prediction, this is the smallest predicted value	number
maxValue	When the data point is a prediction, this is the largest predicted value	number

Type: GraphLine

A GraphLine is either a HorizontalLine or a VerticalLine.

Type: HorizontalLine

Property	Description	Type	Default
name *	Name of the line. Also the name which will be displayed in the legend	string
color *	The color of the line	string
value *	The value on the Y-axis where the line needs to be drawn	number
width	Stroke width of the line	number	1
dasharray	Stroke dash array of the line	string	'5,3'
opacity	Stroke opacity	number	1
indicator	Whether to show the name of the line in the legend, also show a small indication arrow head on the axis	boolean	false

Type: VerticalLine

Same properties as HorizontalLine but with value and date swapped.

Property	Description	Type	Default
date *	The date on the X-axis where the line needs to be drawn	Date

Helper: isMissing

import { isMissing } from '@intoto-dev/bibliotheca-graph';

Given a DataPoint object, returns whether the data point is considered missing or not. This is a type guard way of being sure of the MissingDataPoint interface.

function isMissing(dataPoint: DataPoint): boolean;

Property	Description	Type	Default
dataPoint *	Data point to check	DataPoint

Helper: isPredicted

import { isPredicted } from '@intoto-dev/bibliotheca-graph';

Given a DataPoint object, returns whether the data point is a prediction or not. This is a type guard way of being sure of the PredictedDataPoint interface.

function isPredicted(dataPoint: DataPoint): boolean;

Property	Description	Type	Default
dataPoint *	Data point to check	DataPoint

Helper: createYScale

import { createYScale } from '@intoto-dev/bibliotheca-graph';

Creates a d3 and visx compatible scale for the Y-Axis based and the series data and desired height.

function createYScale(series: GraphSeries, height: number, padding: number): ScaleLinear<number, number>;

Property	Description	Type	Default
series *	Series to create the Y-scale from	GraphSeries[]
height *	Height in pixels of the graph's Y-axis	number
padding	Padding in pixels added to the bottom and top of the Y-axis	number	0

Helper: createXScale

import { createXScale } from '@intoto-dev/bibliotheca-graph';

Creates a d3 and visx compatible scale for the X-Axis based on provided dates and the desired width.

function createXScale(dates: GraphSeries, width: number): ScaleTime<number, number>;

Property	Description	Type	Default
dates *	Dates which make up the X-axis. Needs a minimum of two dates.	Date[]
width *	Width in pixels of the graph's X-axis	number

Helper: shiftDate

import { shiftDate } from '@intoto-dev/bibliotheca-graph';

Get the date from an ISO 8601 compatible date string and shifts the time so that it will display the same time as stated in the date string instead of the relative time (which is default in browsers).

function shiftDate(date: string, direction?: 1 | -1): string;

Property	Description	Type	Default
date *	Date string in ISO 8601 format	string
direction	The direction the time is shifted to. Pass -1 to shift the opposite direction of the timezone offset.	1 or -1	1

Helper: getTimezoneOffset

import { getTimezoneOffset } from '@intoto-dev/bibliotheca-graph';

Gets the timezone offset (same as Date.getTimezoneOffset()) given an ISO 8601 compatible date string. The result is the amount of minutes the offset is from UTC.

function getTimezoneOffset(date: string): number;

Property	Description	Type	Default
date *	Date string in ISO 8601 format	string

Helper: createMeanLevelLine

import { createMeanLevelLine } from '@intoto-dev/bibliotheca-graph';

Creates a HorizontalLine which is a line which is drawn at the mean level of the series. Creates an object to use in the lines property.

function createMeanLevelLine(name: string, value: number): HorizontalLine;

Property	Description	Type	Default
name *	Name of the line which will also be used in the legend.	string
value *	The mean level in mASL.	number

Helper: createMeanLevelLine

import { createNowLine } from '@intoto-dev/bibliotheca-graph';

Creates a VerticalLine which is a line which is drawn at the given date. Creates an object to use in the lines property.

function createNowLine(date: Date): VerticalLine;

Property	Description	Type	Default
date *	The date where the 'now' line will be drawn.	Date

React Hook: useDimensions

import { useDimensions } from '@intoto-dev/bibliotheca-graph';

A React hook which returns a ref binding function and a Dimensions object containing { width: number; height: number }. Use the ref binding function on the element you want to know the dimensions of.

function SomeComponent() {
  const [ref, dimensions] = useDimensions();
  
  return (
    <html>
      <body>
        <main ref={ref}>
          My size is {dimensions.width} x {dimensions.height} 
        </main>
      </body>
    </html>
  );
}

React Hook: useSeriesDates

import { useSeriesDates } from '@intoto-dev/bibliotheca-graph';

A React hook which gets and sorts dates which are present in a list of series.

function useSeriesDates(series: GraphSeries[]): Date[];

Property	Description	Type	Default
series *	Series to get all the dates from	GraphSeries[]