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

Five bar styles filling at uneven paces, percent at right.

Five progress bar styles stacked. Each fills at its own uneven pace, easing
into short stalls the way real jobs do, holds at 100%, restarts. As
upstream draws it, the bars play runs of their own; give it `values` and
it shows your jobs' progress instead, for a dashboard or a terminal UI.

## 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`): it starts
afresh with them, and values given are drawn as they are, so each new
reading shows at once.

  * `values` - a percentage for each bar, 0 to 100 (outside it, held to
    it): one bar for each, up to 32, shown as given rather than played.
    Default `[]`: upstream's five bars, each filling at its own pace.
  * `labels` - each bar's label, in order, cut to 9 characters; a bar
    without one has none. Default `["fetching", "unpacking", "indexing",
    "building", "linking"]`.
  * `style` - one of the five styles, 0 to 4, for every bar: 0 `[===>  ]`,
    1 a smooth bar of eighth blocks, 2 `[###...]`, 3 lamps that light in
    whole steps, 4 a heavy line running on into a light one. Default
    `nil`: each bar its own, in turn.
  * `cols` - the frame's width, 24 to 200; the bars take all but 20 of
    it. Default 48. The frame is two rows a bar and one more.

## 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:

  * `label` - a bar's label.
  * `frame` - a bar's ends where its style has them (brackets, or
    edges), grey.
  * `bar` - its filled cells (and the arrow head, the part filled cell, a
    half step), blue; `bar.done` when it reads 100%, green.
  * `track` - its empty cells, grey.
  * `value`, `unit` - the percent, its `%` grey.

## Keys and clicks

It takes none: it shows progress, 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`): which bar's label, say.

## Screen readers

`Ascii.describe/1` reads each bar's label and percent, as the bars
show them: "progress: copying 42%, verifying 100%"; past eight bars,
"and N more". Playing its own runs, it gives the piece's name and note.

## Example

```elixir
options = %{values: [42, 100], labels: ["copying", "verifying"], style: 1}
bars = Ascii.new!("progress-bar", options: options, parts: true)
{frame, _bars} = Ascii.frame(bars, 0.0)
{frame.cols, frame.rows}
#=> {48, 5}

Ascii.describe(bars)
#=> "progress: copying 42%, verifying 100%"

bars = Ascii.put_options!(bars, values: [80, 100])
Ascii.describe(bars)
#=> "progress: copying 80%, verifying 100%"
```

```heex
<Ascii.Phoenix.live_player id="jobs" piece="progress-bar" options={%{values: @progress, labels: @jobs}} parts />
```

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

---

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