Bento Charts

This repository hosts the code for bento-charts, a library written in TypeScript for React projects, which wraps Recharts and Leaflet in easy-to-use components compatible with the Bento platform.

The following components are currently available:

• Bar chart
• Pie chart
• Choropleth map
• Point map

Installation

Add bento-charts as a dependency to another project:

npm install bento-charts

To install bento-charts with map support:

npm install bento-charts leaflet react-leaflet

Usage

Wrap your app in the ChartConfigProvider and pass in the Language of your site.

import { ChartConfigProvider } from 'bento-charts';

<ChartConfigProvider Lng={language}>
  <App />
</ChartConfigProvider>

Language can be either 'en' or 'fr'.

You also can provide your own theme and translation dictionary.

<ChartConfigProvider
  Lng={language}
  theme={theme}
  translations={translations}
>
    <App />
</ChartConfigProvider>

refer to theme and translations for more information.

Right now, no properties from ChartConfigProvider are used for any map components, but they may do so in the future.

Usage

Using a Chart

import { BarChart, PieChart } from 'bento-charts';

Refer to Props for information on their props.

Using a Map

Maps can be imported using a command like the following:

import { ChoroplethMap } from 'bento-charts/dist/maps';

Here, note the sub-path on the import - this separation allows us to have the map-related peer dependencies marked as "optional".

The following map components are available:

• ChoroplethMap for showing a choropleth map, coloured by
• PointMap (for showing a list of point coordinates; this uses a different data structure than the other components)

See map component properties for more information.

Release procedure

A commit on the main branch will trigger a build and release of the package to the npm Registry, no need to manually create tags thanks to semantic-release.

Please follow the instructions bellow when writing your commits.

Semantic release

Bento-Charts adheres to the semver versioning convention (Semantic Versioning). This repository uses the semantic-release library to automate the release of semver compliant packages to the npm Registry.

Semantic-release parses the commit messages in the release branch in order to determine the versioning changes. It does not rely on magic to work, but rather on specific commit message formats, which are described bellow.

Commit message guidelines

Semantic-release uses the Conventional Commits specification in order to parse relevant information.

<type>(<scope>): <short summary>
  │       │             │
  │       │             └─⫸ Summary in present tense. Not capitalized. No period at the end.
  │       │
  │       └─⫸ Commit Scope: Optional, what was changed.
  │
  └─⫸ Commit Type: build|ci|docs|feat|fix|perf|refactor|test

Both <type> and <short summary> are mandatory, while <scope> is optional, but recommended for pretty release notes.

Example commit messages

After fixing a dependency issue:

fix(dependencies): resolve peer dependencies issues caused by React version

After adding a new Rechart feature:

feat(charts): add support for mixmarchart

After adding unit tests to the charts

test(charts): add unit tests for mixbarchart

Commit with commitlint

Commitlint is a safeguard for commit message formats, which you can use to help write semver-compliant commits. Husky is a git hooks tool that binds commitlint to the git commit command.

Installation

Run these steps once to setup commitlint + husky.

# Install dev dependencies (commitlint & husky)
npm install
# Install husky git hook
npx husky
# Add commitlint as a hook to husky
echo 'npx --no -- commitlint --edit ${1}' > .husky/commit-msg

Usage

Use the git cli as you normally would to make your commits, commitlint will intercept your commit if it is malformed.

Example:

git commit -m "ci(semantic-release): add commitlint and husky as dev tools to write valid commits"

Local development

For local development in a React/Recharts app that uses bento-charts, you can follow these steps for your setup:

1. build and pack bento-charts

   # Builds package and creates a pack file in the "./packs" dir
   npm run buildpack

2. In the project using bento-charts, modify the bento-charts dependency in package.json so that the version number is now the absolute path to the pack file.

   - "bento-charts": "2.0.0",
   + "bento-charts": "file:~/bento-charts/packs/bento-charts-2.0.0.tgz",

3. Install the dependencies in the project

   npm install

Note: you will need to repeat steps 1 and 3 everytime you want the changes to be applied to the app using bento-charts

Testing

A small web application is included in the test folder to provide an easy manual testing bed for components.

This application can be launched with the following command:

npm test