Chart

The cartesian workhorse: bar, line, area, scatter, histogram, and waterfall series on one canvas — grouped or stacked, vertical or horizontal, straight or smoothed. Datasets push over Sync as natural JSON and every datum is tappable, so a bar chart can double as a live voting panel, a queue selector, or a preset picker. Histogram series bin raw samples client-side; waterfall series accumulate signed deltas with hand-off connectors.

Type

"chart"

Recommended Size

Plots read best wide: [3, 4] or larger. In a flow grid the chart auto-sizes to a 16:10 landscape cell.

Relevant Fields

Inherits all shared fields. Key fields:

ChartConfig

All fields optional with sensible defaults.

Axes & Chrome

Series Presentation

Streaming

Statistical Series

Interaction

If datumAction is omitted, a tap falls back to the control's own action.

Sync Payload Structure

The chart receives its dataset via Sync. The payload can be a natural JSON object (no string-encoding needed) or an encoded string — both work:

{
  "categories": ["Mon", "Tue", "Wed", "Thu", "Fri"],
  "series": [
    { "name": "CPU", "type": "line", "color": "#667eea", "values": [42, 51, 38, 66, 47] },
    { "name": "Jobs", "type": "bar", "values": [4, 7, 2, 9, 5] }
  ]
}

Shorthands: {"values": [1, 2, 3]} or a bare [1, 2, 3] render one anonymous series.

Series Fields

*One of values or points per series.

Histogram & Waterfall

{ "series": [ { "type": "histogram", "values": [42.1, 38.9, 44.6, 51.2, 40.3] } ] }

The chart bins the samples (chartConfig.bins, default √n) into contiguous bars; tap payloads carry {"binStart", "binEnd", "count"}.

{ "categories": ["Start", "Sales", "Refunds", "Costs", "Net"],
  "series": [ { "type": "waterfall", "values": [1200, 480, -160, -390, 0], "totals": [0, 4] } ] }

Deltas step from each running level with dashed connectors; totals indices render as full bars from zero — with value 0 they checkpoint the running level (a "Net" bar), with a nonzero value they anchor it (an opening balance, as with Start above). Tap payloads carry {"delta"|"total", "level"}. Both are single-series statisticals — give each its own chart rather than mixing them with other series types.

Streaming Append

Servers streaming one reading per tick don't resend history — push an append op and the device merges it into the stored dataset, trimmed to maxPoints:

{ "append": { "CPU": 63.2, "GPU": 41.0 }, "category": "12:05" }

Forms: {"CPU": 63.2} (per-series by name — unknown names create new series), [63.2, 41.0] (positional), or a bare number (first series). The optional category string appends an x label alongside.

Examples

Live multi-series telemetry

{
  "type": "chart",
  "id": "cpu-chart",
  "position": [0, 0],
  "span": [3, 4],
  "label": "CPU / GPU",
  "chartConfig": { "showLegend": true, "smooth": true, "maxPoints": 60 },
  "defaultValue": "{\"series\":[{\"name\":\"CPU\",\"type\":\"area\",\"values\":[42,51,38,64,55]},{\"name\":\"GPU\",\"type\":\"line\",\"values\":[20,34,28,41,36]}]}",
  "sync": [{ "method": "meshsocket", "type": "listen", "event": "broadcast", "filter": { "msg_type": "telemetry" }, "valuePath": "chart" }]
}

Tappable bar chart (voting panel)

{
  "type": "chart",
  "id": "poll",
  "position": [0, 0],
  "span": [3, 4],
  "label": "Vote for lunch",
  "chartConfig": {
    "showValues": true,
    "barCornerRadius": 6,
    "datumAction": { "method": "meshsocket", "mode": "broadcast", "event": "broadcast", "payload": { "msg_type": "vote", "choice": "{{value}}" } }
  },
  "defaultValue": "{\"categories\":[\"Pizza\",\"Sushi\",\"Tacos\"],\"series\":[{\"values\":[3,5,2]}]}",
  "sync": [{ "method": "meshsocket", "type": "listen", "event": "broadcast", "filter": { "msg_type": "poll_update" }, "valuePath": "results" }]
}

Static horizontal bars

{
  "type": "chart",
  "id": "storage",
  "position": [0, 0],
  "span": [2, 4],
  "label": "Storage by volume",
  "chartConfig": { "horizontal": true, "showValues": true, "showGrid": false },
  "defaultValue": "{\"categories\":[\"System\",\"Media\",\"Docs\"],\"series\":[{\"values\":[128,412,64]}]}"
}

Behavior

• Dataset changes animate smoothly (bars grow, lines morph) via the control's animation profile
• Tap near a datum to select it: bars highlight the whole column, points ring; the header shows the reading
• scrub: true swaps tap-selection for a drag crosshair with haptic ticks per datum
• Append pushes ride the same coalesced sync path as sparklines — high-rate streams stay smooth

Notes

• The control's value is the dataset JSON — selection never overwrites it, so state readback round-trips
• For quartile/density views of a distribution use Box Plot; the histogram series here shows binned frequency shape
• For a single fast-scrolling series, Sparkline is lighter

Related

• Sparkline — single-series micro trend
• Box Plot — quartile/violin distributions
• Pie Chart — part-of-whole / wheel / radial menu
• Heatmap — 2-D matrix color map
• Radar — multivariate profile
• Sync — how datasets arrive
• Actions — how datumAction fires