# charts.bar-chart

A complete vertical bar chart as data, grouped or stacked: the plot area, a
category x axis, a number y axis, gridlines, one rectangle per bar with its
series, category, value and colour, and a legend. Nothing is drawn; any
renderer turns it into pixels, and every language produces the same numbers.

It is assembled from `charts.scale` (band and linear scales), `charts.ticks`,
`charts.format`, `charts.stack`, `charts.shape` (bar rectangles),
`charts.axis`, `charts.layout` and `charts.palette`.

## Modes

- `grouped`: the series sit side by side in each category. Categories are
  bands of the x axis with 20% inner and 10% outer padding; inside a category
  each series gets a sub-band with 5% padding between them. A single series
  uses the whole category band.
- `stacked`: the series are stacked in each category with a diverging stack
  (`charts.stack`): positive values stack upwards from zero, negative values
  downwards, so a negative value never hides inside a positive stack.

Bars always grow from zero, so zero is always on the y axis. The domain is
widened to nice numbers with about one tick per 50 pixels; if every value is
zero the axis runs from 0 to 1 so it still has a height.

## Rectangles

Bar edges are rounded to 2 decimal places first and the widths and heights
are the differences of the rounded edges (`charts.shape` barRects). That is
why neighbouring bars can be 37.87 and 37.86 wide: each edge is where it
should be to the hundredth of a pixel, and bars that share an edge share it
exactly, with no hairline gaps.

## Layout, colours, legend

The same fixed rules as `charts.line-chart`: 7 pixels per character, a legend
only for more than one series (at the top, 18-pixel rows), margins top 12 or
the legend's height plus 16, right 20, bottom 30, left sized to the widest y
label; 6-pixel ticks; Okabe-Ito colours in series order, given once per
series in `colors` and again on every bar. `bars` lists series by series, each
in category order.

Category names and series names must each be unique. No categories, no
series, a series of the wrong length or a chart too small for its margins is
an error.