# FlowFuse `ui-chart` Manual (EVOLV Reference)

Source: https://dashboard.flowfuse.com/nodes/widgets/ui-chart.html

## Chart Types

| Type | X-Axis Options | Notes |
|------|---------------|-------|
| Line | timescale, linear, categorical | Interpolation: linear, step, bezier, cubic, cubic-mono |
| Bar | categorical | Grouped (side-by-side) or stacked |
| Scatter | timescale, linear, categorical | Configurable point shape & radius |
| Pie / Doughnut | radial | Nested series for multi-layer |
| Histogram | auto-binned | Numerical bins or categorical counting |

## Properties

| Property | Type | Dynamic | Notes |
|----------|------|---------|-------|
| `group` | ref | No | Parent ui-group |
| `width` | int | No | Columns |
| `height` | int | No | Row units |
| `label` | string | No | Chart title |
| `chartType` | string | No | `"line"`, `"bar"`, `"scatter"`, `"pie"`, `"histogram"` |
| `showLegend` | bool | No | Show series legend |
| `action` | string | Yes | `"append"` or `"replace"` |
| `pointShape` | string | No | Point marker shape (scatter/line) |
| `xAxisLimit` | int | No | Max data points to keep |
| `textColor` | color | No | Override text color |
| `gridColor` | color | No | Override grid lines |
| `xAxisType` | string | No | `"time"`, `"linear"`, `"category"` |

## Series Configuration

| Source | How It Works |
|--------|-------------|
| `msg.topic` | Default — each unique topic creates a series |
| `key` | Uses a named property from data object |
| `JSON` | Array of keys for multi-series from single msg |
| (blank) | Auto-generates timestamp for x |

## Input Format

### Simple (recommended for EVOLV)
```js
{ topic: "PS West Level", payload: 2.34, timestamp: Date.now() }
```

### Object with x/y mapping
```js
{ payload: { time: 1700000000000, value: 2.34 } }
// Configure x → "time", y → "value"
```

### Nested access
X/Y keys support dot notation: `"nested.value"` → `payload.nested.value`

## Dynamic Properties

| Property | Path | Notes |
|----------|------|-------|
| Action | `msg.action` | `"append"` or `"replace"` |
| Chart Options | `msg.ui_update.chartOptions` | eCharts config merge |
| CSS Class | `msg.class` | Add custom class |

## eCharts Customization (`msg.ui_update.chartOptions`)

Deep-merges with existing config. Accumulates across messages.

```js
msg.ui_update = {
  chartOptions: {
    yAxis: { position: "right", name: "Level (m)" },
    grid: { top: 60, right: 40 },
    title: { text: "Basin Levels", textStyle: { fontSize: 14 } }
  }
};
```

**Series colors** — must provide all series configs together:
```js
msg.ui_update = {
  chartOptions: {
    series: [
      { name: "PS West", type: "line", lineStyle: { color: "#2196f3" }, itemStyle: { color: "#2196f3" } },
      { name: "PS North", type: "line", lineStyle: { color: "#ff9800" }, itemStyle: { color: "#ff9800" } }
    ]
  }
};
```

## Data Actions

| Action | How | Effect |
|--------|-----|--------|
| Append | `msg.action = "append"` (default) | Add points to existing data |
| Replace | `msg.action = "replace"` | Clear then add |
| Clear | `msg.payload = []` | Remove all data |

## Time Formatting Tokens

`{HH}:{mm}:{ss}` → `12:00:00`
`{yyyy}-{M}-{d}` → `2020-1-1`
Tokens: `{yyyy}`, `{MM}`, `{dd}`, `{HH}`, `{H}`, `{hh}`, `{h}`, `{mm}`, `{m}`, `{ss}`, `{s}`, `{eeee}` (day name)

## EVOLV Key Rules

1. Send minimal `{ topic, payload, timestamp }` — chart auto-uses topic for series.
2. Set `category: "topic"`, `categoryType: "msg"` in node config — blank category causes editor validation errors.
3. For timeseries: leave x-key blank → auto-timestamp. Supply ms timestamps if custom.
4. For multi-station overlay charts: each station sends with a different `msg.topic`.
5. Use `msg.action = "append"` (default) for streaming data; `"replace"` for snapshot updates.
6. Keep one topic per chart for simple KPIs; use multi-topic for comparison views.
7. Prefer explicit output-slot routing: `node.send([msgForChart, msgForText, ...]); return null;`

## Common Failure Modes

- Payload is not numeric (string/object without y-key config)
- Function node returns to wrong output index
- Topic churn creates unexpected series fragmentation
- Chart has stale data policy mismatch (`append` vs `replace`)
- Blank `category` field causes red node on deploy