@intoto-dev/bibliotheca-graph v0.26.3

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

Type: GraphSeries

Type: DataPoint

Type: GraphLine

A GraphLine is either a HorizontalLine or a VerticalLine.

Type: HorizontalLine

Type: VerticalLine

Same properties as HorizontalLine but with value and date swapped.

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;

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;

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

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

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;

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;

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;

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;

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[];