Skip to content

Latest commit

 

History

History
286 lines (201 loc) · 9.92 KB

README.md

File metadata and controls

286 lines (201 loc) · 9.92 KB

GitHub Workflow Status (branch) npm bundle size GitHub package.json version

Introduction

As an American assimilating into Norway and the way of life, I'd like to think Norwegians would be proud of me for this one:

Waffles are better than Pies

🧇 > 🥧

There, I said it...and it's true.

Pies and donuts are harder to read, take longer to evaluate the meaning behind the visualization, and tend to take up more space.

Waffle charts can display more in the same amount of space at a larger, easier to read size. It provides a better graphical and textual representation of proportions. Thanks to a 10 x 10 grid, the user can quickly assess the overall portions and then drill down to the 1%.

My personal opinion is that after three values, a bar chart (stackable-bar-chart coming soon) is better at showing the data relations rather than the waffle, which is why I've capped the values to three for this component. It also helps to keep each input prop primitive.

donut         waffle chart

This is a zero-dependency library built with React, Typescript & Vite.

No D3 only HTML, CSS, and JS/TS.

🚀 v2.0.0: Now supporting three quantities!

waffle chart three values square fill

Usage in commercial projects

If you are using this in a commercial project, please consider leaving a donation/tip. Cheers!

ko-fi

Limitations

  • Requires browser support for CSS grid and flexbox.
  • Requires browser support for CSS clamp().

Demo

Live demo via Storybook coming soon.

Supporting reads

API

The chart will render with just the default props.

Prop Type Default Notes
partA number 0 this is the quantity, % is calculated by component
partB number 0 this is the quantity, % is calculated by component
partC number 0 this is the quantity, % is calculated by component
displayPrecision number 0 number of decimals for quantity and percentage
partAlabel string 'A'
partBlabel string 'B'
partClabel string 'C'
rounding 'nearest', 'up', 'down' 'nearest' up for any amount over the whole, down if under a whole
isFilledFromTop boolean false
isFilledFromLeft boolean false
isSquareFill boolean true can fill in linear by row if false
isAnimatedFill boolean true fade in color vs. instant change
showDataDisplay boolean true
showTotal boolean false
partAColor string undefined can take any CSS color (hsl, rgb, hex, ...)
partBColor string undefined can take any CSS color (hsl, rgb, hex, ...)
partCColor string undefined can take any CSS color (hsl, rgb, hex, ...)
totalColor string undefined can take any CSS color (hsl, rgb, hex, ...)

Square vs linear fill

Square (default) fill will fill partA values in a square shape with any remainders above on the next row. Linear will fill the entire row first then move onto the next row. Square fill is slightly more logic, but performance difference shouldn't be noticeable.

waffle chart         linear fill

Directional filling

Toggling the vertical and horizontal fill directions will change the position where partA value fills from. The label will follow the vertical fill setting.

waffle chart vertical fill

Total and Data Display

Toggling these values will show/hide the calculations for total and percentages/counts.

Colors

You can pass in colors via props or just override in :root or some scope above the component for the following:

  • --bg-total: color for total, the fallback is slategray
  • --bg-square: color for partB squares, the fallback is cadetblue
  • --bg-square-valued: color for partA squares, the fallback is palevioletred

The fallbacks were chosen as they satisfy color contrast accessibility for both white and black backgrounds according to WCAG AA standards for Large Text, UI Components, & Graphical Objects.

Fonts and other styling

The component will inherit the font from your app or can be modified by selecting it's class. Additional special stylings can be applied by selecting the right classes.

Installing

Using NPM:

npm i waffle-chart

Using Yarn:

yarn add waffle-chart

Usage

I recommend as a practice to wrap components like this in your own wrapper component that exposes the same API. This way you aren't married to this library and can easily swap it out without breaking consumers of your component.

// Import the CSS at the highest scope possible without coupling e.g. Shared or Vendor or Lib directory.
import 'node_modules/waffle-chart/dist/style.css';
import type { WaffleChartProps } from 'waffle-chart';
import { WaffleChart } from 'waffle-chart';

type Props = WaffleChartProps;

const MyChart: React.FC<Props> = (props: Props) => <WaffleChart {...props}/>

export default MyChart;

For Remix projects just import the style url in the links at the root.tsx.

import waffleChartStylesUrl from 'node_modules/waffle-chart/dist/style.css';

export const links: LinksFunction = () => [
    {
        rel: 'stylesheet',
        href: waffleChartStylesUrl,
    },
];

Updating

npm

npm update

yarn

yarn upgrade waffle-chart@^

Contributing

This package is free for you to clone and change to your needs in accordance with the MIT license terms. If you want to contribute back to this codebase for improvements, please fork it, create an issue and then initiate a pull request that details the changes and problem or enhancement. Thanks! 🍻

Developing

Starting development server:

yarn dev

Testing

Testing methodology follows the testing-library guiding principles and focusing user interactions and integration testing.

Latest coverage report:

Test Files  6 passed (6)
     Tests  13 passed (13)
  Start at  12:41:38
  Duration  2.26s (setup 2ms, collect 1.08s, tests 395ms)

-------------|---------|----------|---------|---------|---------------------------
File         | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s
-------------|---------|----------|---------|---------|---------------------------
All files    |   98.52 |    87.64 |   95.65 |   98.52 |                           
 Chart       |     100 |      100 |     100 |     100 | 
  index.tsx  |     100 |      100 |     100 |     100 | 
 ChartSquare |     100 |      100 |     100 |     100 | 
  index.tsx  |     100 |      100 |     100 |     100 | 
 DataDisplay |     100 |      100 |     100 |     100 | 
  index.tsx  |     100 |      100 |     100 |     100 | 
 Total       |     100 |      100 |     100 |     100 | 
  index.tsx  |     100 |      100 |     100 |     100 | 
 WaffleChart |   97.86 |    84.93 |   94.11 |   97.86 | 
  index.tsx  |   97.86 |    84.93 |   94.11 |   97.86 | 79-80,106,111,116,199,307
-------------|---------|----------|---------|---------|---------------------------

Testing is built and run with:

You'll notice very sparse snapshots for each component and a focus on the integrations.

Run tests once:

yarn test

Run tests and watch for changes:

yarn watch

Check coverage:

yarn coverage

Run Vitest UI:

yarn testui

Building

yarn build

Merging

See Contributing.