# `PUI.Chart`

uPlot-backed chart components for Phoenix LiveView.

`PUI.Chart` ships three layers:

1. `<.chart>` is the low-level transport component that sends serializable chart
   config to a LiveView hook.
2. `<.bar_chart>` provides preconfigured categorical bar charts.
3. `<.line_chart>` provides preconfigured line charts with linear, stepped, and
   spline paths.

The companion hooks expose `this.uPlot`, `this.chart`, `this.data`, and
`this.opts` so downstream hooks can extend the base chart behavior without
rebuilding the LiveView component contract.

## Basic usage

    <.bar_chart
      id="monthly-sales"
      categories={~w(Jan Feb Mar Apr)}
      series={[
        %{label: "Revenue", data: [12.4, 18.7, 15.2, 22.1], suffix: " jt"}
      ]}
    />

    <.line_chart
      id="servers"
      curve="stepped"
      labels={["00:00", "06:00", "12:00", "18:00"]}
      series={[
        %{label: "Server A", data: [42, 45, 43, 46], suffix: "°C"},
        %{label: "Server B", data: [38, 40, 39, 41], suffix: "°C"}
      ]}
    />

    <.chart
      id="custom-chart"
      phx-hook="PUI.Chart"
      height={280}
      config=%{
        data: [
          [1, 2, 3, 4],
          [12, 18, 15, 20]
        ],
        series: [
          %{label: "Traffic", stroke: "var(--chart-1)"}
        ],
        options: %{
          scales: %{x: %{time: false}, y: %{auto: true}}
        }
      }
    />

## Attributes

`chart/1`

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `id` | `string` | generated | Unique DOM id for the chart root |
| `phx-hook` | global attr | `"PUI.Chart"` | Hook name used to render/update the chart |
| `height` | `integer` | `320` | Reserved chart height in pixels |
| `class` | `string` | `""` | Additional classes for the outer chart wrapper |
| `config` | `map` | required | Serializable chart payload consumed by the hook |
| `rest` | `global` | — | Additional HTML attributes |

`bar_chart/1`

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `categories` | `list` | required | Labels shown on the x-axis |
| `series` | `list` | required | Series maps with `label` and `data` |
| `bar_width` | `float` | `0.72` | Relative bar width passed to `uPlot.paths.bars/1` |
| `max_bar_width` | `integer` | `64` | Maximum rendered bar width in pixels |
| `bar_radius` | `integer` | `1` | Top corner radius in pixels for rendered bars |
| `grid` | `boolean` | `true` | Toggles the y-axis grid |
| `tooltip` | `map` | `%{}` | Tooltip configuration merged into defaults |
| `legend` | `boolean` | `false` | Toggles the built-in uPlot legend |
| `options` | `map` | `%{}` | Additional serialized chart options |

`line_chart/1`

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `x` | `list` | generated | Explicit x-axis values |
| `labels` | `list` | `[]` | Optional categorical x-axis labels for non-time charts |
| `series` | `list` | required | Series maps with `label` and `data` |
| `curve` | `string` | `"linear"` | One of `"linear"`, `"stepped"`, or `"spline"` |
| `time` | `boolean` | `false` | Enables uPlot's time scale for the x-axis |
| `area` | `boolean` | `false` | Adds area fills beneath line series |
| `sparkline` | `boolean` | `false` | Uses the dedicated sparkline hook with compact chrome-free defaults |
| `grid` | `boolean` | `true` | Toggles the y-axis grid |
| `tooltip` | `map` | `%{}` | Tooltip configuration merged into defaults |
| `legend` | `boolean` | `false` | Toggles the built-in uPlot legend |
| `options` | `map` | `%{}` | Additional serialized chart options |

# `bar_chart`

## Attributes

* `id` (`:string`) - Defaults to `nil`.
* `height` (`:integer`) - Defaults to `320`.
* `class` (`:string`) - Defaults to `""`.
* `card` (`:boolean`) - Defaults to `true`.
* `categories` (`:list`) (required)
* `series` (`:list`) (required)
* `bar_width` (`:float`) - Defaults to `0.72`.
* `max_bar_width` (`:integer`) - Defaults to `64`.
* `bar_radius` (`:float`) - Defaults to `0.1`.
* `grid` (`:boolean`) - Defaults to `true`.
* `tooltip` (`:map`) - Defaults to `%{}`.
* `legend` (`:boolean`) - Defaults to `false`.
* `options` (`:map`) - Defaults to `%{}`.
* Global attributes are accepted.

# `chart`

## Attributes

* `id` (`:string`) - Defaults to `nil`.
* `height` (`:integer`) - Defaults to `320`.
* `class` (`:string`) - Defaults to `""`.
* `card` (`:boolean`) - Defaults to `true`.
* `config` (`:map`) (required)
* Global attributes are accepted.

# `line_chart`

## Attributes

* `id` (`:string`) - Defaults to `nil`.
* `height` (`:integer`) - Defaults to `320`.
* `class` (`:string`) - Defaults to `""`.
* `card` (`:boolean`) - Defaults to `true`.
* `x` (`:list`) - Defaults to `nil`.
* `labels` (`:list`) - Defaults to `[]`.
* `series` (`:list`) (required)
* `curve` (`:string`) - Defaults to `"linear"`. Must be one of `"linear"`, `"stepped"`, or `"spline"`.
* `time` (`:boolean`) - Defaults to `false`.
* `area` (`:boolean`) - Defaults to `false`.
* `sparkline` (`:boolean`) - Defaults to `false`.
* `grid` (`:boolean`) - Defaults to `true`.
* `tooltip` (`:map`) - Defaults to `%{}`.
* `legend` (`:boolean`) - Defaults to `false`.
* `options` (`:map`) - Defaults to `%{}`.
* Global attributes are accepted.

---

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