# `LedgerUI.Components.Chart`
[🔗](https://github.com/devaction-labs/ledger_ui/blob/v0.2.0/lib/ledger_ui/components/chart.ex#L1)

Charts drawn by the package itself, as SVG with the `lu-*` look (axis labels, grid lines, legend,
tooltips, light and dark).

The look-alike canvas charts are rendered **on the server**, with the same markup `ledger.js`
builds, so they show without JavaScript; a small hook only adds the hover guide and tooltip:

  * `line_chart/1` (hook `LedgerUI.LineChart`): lines and areas, with head, legend and tooltip.
    The server draws the SVG at `width`; the hook then measures the container (`ResizeObserver`)
    and lays the same geometry out at the real width, so axis text and strokes stay at their CSS
    size on any screen. The lines draw in once on mount (no loop; not with
    `prefers-reduced-motion`).
  * `donut_chart/1` (hook `LedgerUI.DonutChart`): the ring and its plan rows.
  * `waterfall_chart/1`: floating steps and totals.
  * `bar_chart/1`: the column strip (`lu-bars`).
  * `cohort_heatmap/1`: the retention grid.
  * `bar_list/1` and `heatmap/1`: a ranking over tracks and a grid of dots.

`chart/1` is the generic, options-driven chart (an ApexCharts-shaped subset: `line`, `area`,
`bar`, `donut`/`pie`) drawn by the `LedgerUI.Chart` hook into an element LiveView leaves alone.

Cards, headers and segmented controls around a chart are separate components; these functions
render only the chart (and, for `line_chart/1`, its head and legend).

# `bar_chart`

## Attributes

* `values` (`:list`) - One number per bar. Defaults to `[]`.
* `data` (`:list`) - The bars as `{label, value}` tuples or `%{label:, value:}` maps, in place of `values` and `labels`. Defaults to `[]`.
* `max` (`:any`) - The value of a full-height bar (the highest value, or 100 when it is lower, by default). Defaults to `nil`.
* `labels` (`:list`) - Labels in a row under the bars. Defaults to `[]`.
* `titles` (`:list`) - `title` (hover text) of each bar. Defaults to `[]`.
* `highlight` (`:any`) - Index of the highlighted bar, or its label (`:last`, `nil` for none). Defaults to `:last`.
* `shape` (`:string`) - Defaults to `"round"`. Must be one of `"round"`, or `"square"`.
* `height` (`:any`) - CSS height of the strip (`120px`). Defaults to `nil`.
* `width` (`:any`) - CSS width of the strip. Defaults to `nil`.
* `class` (`:any`) - Defaults to `nil`.
* Global attributes are accepted.

# `bar_list`

## Attributes

* `label` (`:string`) - The list's `aria-label`. Defaults to `nil`.
* `max` (`:any`) - The amount of a full track (the largest `amount` by default). Defaults to `nil`.
* `class` (`:any`) - Defaults to `nil`.
* Global attributes are accepted.
## Slots

* `item` (required) - Accepts attributes:

  * `label` (`:string`)
  * `value` (`:string`)
  * `amount` (`:any`)

# `chart`

## Attributes

* `id` (`:string`) (required) - DOM id; also what `push_event` payloads target.
* `options` (`:any`) (required) - ApexCharts-shaped options, a map (encoded to JSON) or an encoded JSON string.
* `formatters` (`:map`) - Options path to built-in formatter name, e.g. `%{"yaxis.labels.formatter" => "thousands"}`. Defaults to `%{}`.
* `table_toggle` (`:any`) - Reserved: a Chart / Table switch (not drawn yet). Defaults to `false`.
* `summary` (`:boolean`) - Reserved: the cursor summary line (not drawn yet). Defaults to `false`.
* `on_cursor` (`:string`) - LiveView event pushed as the cursor moves. Defaults to `nil`.
* `class` (`:any`) - Defaults to `nil`.
* Global attributes are accepted.

# `cohort_heatmap`

## Attributes

* `columns` (`:list`) (required) - Header labels (`M0`, `M1`...).
* `rows` (`:list`) (required) - `[%{label: "Jan", values: [100, 94, nil, ...]}]`; `nil` is an empty cell.
* `thresholds` (`:list`) - Lower bounds of levels 2 to 5. Defaults to `[86, 90, 94, 100]`.
* `suffix` (`:string`) - Defaults to `"%"`.
* `class` (`:any`) - Defaults to `nil`.
* Global attributes are accepted.

# `donut_chart`

## Attributes

* `id` (`:string`) (required)
* `segments` (`:list`) - `[%{name: .., value: number, color: css, display: "$96,900"}]`. Empty: only the container. Defaults to `[]`.
* `center_label` (`:string`) - Defaults to `"TOTAL"`.
* `center_value` (`:string`) - Defaults to `nil`.
* `label` (`:string`) - Defaults to `"Distribuição"`.
* `rows` (`:boolean`) - Draw the plan rows (name, value and share) under the ring. Defaults to `true`.
* `value_format` (`:any`) - Defaults to `&LedgerUI.Components.Chart.money/1`.
* `class` (`:any`) - Defaults to `nil`.
* Global attributes are accepted.

# `heatmap`

## Attributes

* `levels` (`:list`) (required) - One level per cell, 0 to 4, row by row.
* `columns` (`:integer`) - Defaults to `20`.
* `size` (`:integer`) - The cell size in pixels. Defaults to `12`.
* `shape` (`:string`) - Defaults to `"round"`. Must be one of `"round"`, or `"square"`.
* `label` (`:string`) (required) - What the map shows, for assistive technology.
* `titles` (`:list`) - A `title` per cell. Defaults to `nil`.
* `less` (`:string`) - Text before the scale; no scale without it. Defaults to `nil`.
* `more` (`:string`) - Defaults to `nil`.
* `class` (`:any`) - Defaults to `nil`.
* Global attributes are accepted.

# `line_chart`

## Attributes

* `id` (`:string`) (required)
* `labels` (`:list`) - X axis labels, one per point. Defaults to `[]`.
* `series` (`:list`) - `[%{name: .., values: [..], area: bool, dashed: bool, color: css}]`. Without series only the empty container is rendered. Defaults to `[]`.
* `min` (`:any`) - Lowest value of the axis (default: lowest of the data). Defaults to `nil`.
* `max` (`:any`) - Defaults to `nil`.
* `ticks` (`:integer`) - Gaps of the Y axis (`ticks + 1` grid lines). Defaults to `4`.
* `label_every` (`:integer`) - Draw one X label every N points. Defaults to `1`.
* `width` (`:integer`) - Width of the server-rendered SVG (first paint). In the browser the hook re-lays the chart to the measured width of its container, so text and strokes keep their CSS size. Defaults to `640`.
* `height` (`:integer`) - Height of the chart in CSS pixels (the same on the server and after the hook measured). Defaults to `250`.
* `label` (`:string`) - `aria-label` of the SVG. Defaults to `"Gráfico"`.
* `head` (`:string`) - Big figure above the chart (`+$70,320`). Defaults to `nil`.
* `sub` (`:string`) - Muted text after the figure (`since January`). Defaults to `nil`.
* `legend` (`:boolean`) - Legend of the named series (when there is more than one). Defaults to `true`.
* `sub_delta` (`:string`) - A change after the muted text (`+12,4%`), in bold and colored by `sub_delta_tone`. Defaults to `nil`.
* `sub_delta_tone` (`:string`) - Defaults to `"pos"`. Must be one of `"pos"`, or `"neg"`.
* `pin` (`:integer`) - Index whose guide and tooltip stay visible. Defaults to `nil`.
* `axis_format` (`:any`) - Function of a value for the Y labels. Defaults to `&LedgerUI.Components.Chart.kilo/1`.
* `value_format` (`:any`) - Function of a value for the tooltip. Defaults to `&LedgerUI.Components.Chart.money/1`.
* `tip` (`:any`) - Function of an index returning tooltip rows `[[name, value, kind]]`. Defaults to `nil`.
* `tip_title` (`:any`) - Function of an index returning the tooltip title. Defaults to `nil`.
* `class` (`:any`) - Defaults to `nil`.
* Global attributes are accepted.

# `waterfall_chart`

## Attributes

* `id` (`:string`) - Defaults to `nil`.
* `steps` (`:list`) - `[%{name:, value:, label:, color:, total: bool}]`: a step moves the running total, `total` starts from zero. Defaults to `[]`.
* `max` (`:integer`) - Top of the Y axis. Defaults to `30000`.
* `ticks` (`:integer`) - Gaps of the Y axis. Defaults to `3`.
* `label` (`:string`) - `aria-label` of the SVG. Defaults to `"Movimento"`.
* `axis_format` (`:any`) - Defaults to `&LedgerUI.Components.Chart.wf_axis/1`.
* `class` (`:any`) - Defaults to `nil`.
* Global attributes are accepted.

---

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