Skip to main content

@britecharts/wrappers

@britecharts/wrappers is a package that simplifies the use of Britecharts' components with frontend frameworks.

Usage​

@britecharts/wrappers components expose a simple API to allow its use in frontend frameworks. This API contains three methods: create, update, and destroy.

To use them, you will pass a configuration object following the Britecharts core component API and a container:

import { BarWrapper } from '@britecharts/wrappers';

const container = document.querySelector('.container');
const data = [
    {
        name: 'Vibrant',
        value: 2,
    },
    {
        name: 'Opalescent',
        value: 4,
    },
    {
        name: 'Shining',
        value: 3,
    },
];
const configuration = {
    width: 400,
    margin: {left: 10},
};

const barInstance = BarWrapper.create(container, data, configuration);

//...

BarWrapper.update(container, newData, {}, barInstance);

The wrappers include a lightweight configuration and container validation.

A configuration value of undefined or null means "not set" and the chart keeps its own default. Any other value is applied, including the falsy ones: false, 0 and '' reach the chart, so a setting can be turned back off with { isLoading: false }.

In theory, you shouldn't be using this wrappers by themselves, but you might prefer this API (more OO-like) for your vanilla JavaScript projects.

API​

The API of the wrappers has only three methods: create, update and destroy. Note that each component wrapper's configuration options is a reflection of Britecharts charts' APIs.

Create​

Creates a new Britechart chart and returns its instance.

Signature: <Wrapper>.create(HTMLElement, <ChartDataShape>, <ConfigurationObject>) => BritechartChart

Example:

const barInstance = BarWrapper.create(container, data, configuration);

Update​

Updates a chart with new data or configuration.

Signature: <Wrapper>.update(HTMLElement, <ChartDataShape>, <ConfigurationObject>, BritechartChart) => BritechartChart

Example:

BarWrapper.update(container, newData, {}, barInstance);

Destroy​

Removes the chart's svg from the container, so the container can be used again (a create after a destroy draws exactly one chart). It only removes that svg: never the container itself, which a framework may own, nor anything else inside it.

Signature: <Wrapper>.destroy(HTMLElement) => void

Example:

BarWrapper.destroy(container);

TooltipWrapper.destroy has its own contract: it removes the tooltip from inside the element and never an svg, because a tooltip is created inside the chart it decorates and destroyed against the element around it.

Availability​

The following components haven't been adapted yet from Britecharts:

  • Brush charts
  • Heatmaps

Feel free to send a PR if you want them included.

Installation​

To install run:

yarn add @britecharts/core @britecharts/wrappers

Or, with npm:

npm i --save @britecharts/core @britecharts/wrappers

Roadmap​

Our idea for the short term is to update this package to use TypeScript natively. Let us know if you want to help with it.