# `Ascii.Pieces.BarChart`
[🔗](https://github.com/houllette/ascii_art/blob/main/lib/ascii/pieces/bar_chart.ex#L1)

Bars easing between three datasets, values riding on top.

A vertical bar chart with a value axis, gridlines and category labels. The
bars ease from one dataset to the next with their values on top. As
upstream draws it, three weeks of visits take turns; give it datasets of
your own and it charts them, one standing still or several in turn.

## Options

Give them to `Ascii.new/2` as `options:`, and new ones while it plays
with `Ascii.put_options/2` (or a Phoenix player's `options`): the bars
ease from what they showed to the new values, so new data as it comes
reads as a change rather than a jump.

  * `title` - the heading, over the chart on the left. Default
    `"visits by day"`.
  * `labels` - the categories under the bars, a bar each, from the left.
    Default the days of the week.
  * `datasets` - each a map of its `name` and its `values`, a number a
    label, up to a billion either way. One dataset stands still; several
    take turns, their names in a legend on the right, the one shown in
    brackets. A dataset without values draws zeros, and no datasets draw
    no bars. Default upstream's three weeks.
  * `cols` - the frame's width, 30 to 200; upstream's 60 by default, for
    more bars than that holds. It is always 19 rows tall. A line longer
    than the width is cut at its edge.

## Colours

In one ink, or a gradient, with `:ink` and `:gradient` (see
`Ascii.Ink`); part by part with `:parts` (see `Ascii.Parts`),
`parts: true` taking the colours suggested here:

  * `title` - the heading.
  * `legend` - the datasets' names, grey; `legend.active`, the one shown,
    in its brackets, blue.
  * `scale` - the numbers up the side, grey.
  * `axis` - the axis, grey.
  * `grid` - the dashed gridlines, grey.
  * `bar` - the bars, blue; `bar.1`, `bar.2` and on, a bar each from the
    left, to colour them one by one.
  * `value` - the numbers riding on the bars.
  * `label` - the categories under them.

## Keys and clicks

It takes none: it shows data, and `Ascii.handle_event/2` ignores every
event. A Phoenix player given `interactive` and `notify` still tells your
LiveView where it was clicked, and on which part (`Ascii.part_at/4`):
`bar.3`, say, for the third bar, or its `label`.

## Screen readers

`Ascii.describe/1` reads its title and data, its options being its
data even as upstream gives them: one dataset's bars, as "signups: mon
12, tue 30, wed 18" (the first eight, then how many more), or each of
several datasets' highest, as "visits by day, 3 datasets in turn: week 1,
highest fri 540; …".

## Example

```elixir
signups = %{name: "this week", values: [12, 30, 18]}
options = %{title: "signups", labels: ~w(mon tue wed), datasets: [signups]}
chart = Ascii.new!("bar-chart", options: options, parts: true)

Ascii.describe(chart)
#=> "signups: mon 12, tue 30, wed 18"

chart = Ascii.put_options!(chart, datasets: [%{signups | values: [12, 30, 41]}])
{frame, _chart} = Ascii.frame(chart, 2.0)
frame.text =~ "41"
#=> true
```

```heex
<Ascii.Phoenix.live_player id="signups" piece="bar-chart" options={%{title: "signups", labels: @days, datasets: [%{name: "this week", values: @counts}]}} parts />
```

Ported from `src/pieces/bar-chart.ts` in bas3line/ascii (MIT).

---

*Consult [api-reference.md](api-reference.md) for complete listing*