research: time-series UI library — comparative analysis and ADR

[vredchenko]

Context

The SmartEM frontend needs time-series visualization (sparklines in matrix cells, drill-down line charts, and a time slider) for the model-weight display tracked in DiamondLightSource/smartem-frontend#67. Before installing any charting library in apps/smartem, we want a thorough comparative analysis written up as an ADR — partly because the choice has bundle-size and ergonomic consequences for a long-lived dashboard, and partly because picking visualization tooling at DLS has wider implications than this one consumer.

This is the tracking issue for that analysis. The implementation work blocks on the ADR landing.

Why an ADR

• Charting library choice tends to become a de-facto standard for follow-on work in the same codebase. Picking one casually creates lock-in.
• DLS already has @diamondlightsource/davidia for visualization. Choosing differently needs to be defended on concrete grounds, not vague preference.
• Other DLS projects (PATo, Evo, DII, future facility frontends) have similar needs. A documented analysis lets them lift the conclusion or revisit specific axes for their own constraints.
• A finished ADR can feed back into sci-react-ui — either as an upstream component contribution or as guidance on which lib sci-react-ui should peer-depend on.

Constraints driving the SmartEM use case

• Backend serves historical weight data over HTTP REST (already implemented; no need for a live-push architecture).
• Live updates will use SSE, not WebSocket — relevant when comparing libraries that assume a WS push model.
• Strong preference for decoupling backend from frontend at the visualization layer.
• Strong preference for using an existing solid library over hand-rolling primitives.
• Concrete rendering needs:
  • Sparkline-in-cell — small, axis-less inline chart (~100 points after downsampling) embedded in a (model × metric) matrix cell.
  • Drill-down line chart — full-size, with axes, tooltips, and theme integration. Up to ~5,000 points after downsampling; raw series can reach tens of thousands of points per (model, metric) combination.
  • Time slider / range selector — either built-in or composable with MUI Slider.
  • Theme integration with MUI v7 (the workspace's design system).

Candidate libraries to evaluate

Mandatory and non-negotiable:

• @diamondlightsource/davidia — DLS's existing visualization platform. React + TypeScript client built on @h5web/lib + Three.js + d3, with a FastAPI backend and WebSocket / messagepack push. Recommended for live-streaming use cases. The ADR has to address: architecture fit (we already have REST data in the React app, no plot server), bundle weight (h5web + Three.js add several MB), domain fit (davidia targets HDF5 / n-d arrays; our data is flat tabular weights), and component surface (does it expose a sparkline-grade primitive or only the connected pipeline?).

Other candidates suggested by colleagues familiar with DLS visualization needs:

• Observable Plot — declarative grammar-of-graphics-style API. Recommended by Guilherme (PATo maintainer) as a strong choice for "more complex, flexible needs". In production use on Evo.
• Nivo — declarative React charts, broad set of plot types, simpler API surface. Also recommended by Guilherme for simpler plots. Known limitation: two y-axes with one inverted is awkward (encountered when prototyping image-quality indicators). Not blocking for our weights view but worth confirming.
• Visx — Airbnb's d3 + React building blocks. Used in PATo, modified locally because no off-the-shelf option covered everything ~4 years ago. Lower-level than the alternatives; more code, more flexibility.

Additional candidates surfaced by initial research:

• @mui/x-charts — already a dependency in smartem-frontend/apps/legacy. MUI-native, MIT, ~250 KB. Provides SparkLineChart + LineChart + composable axes.
• plotly.js / react-plotly.js — built-in rangeslider (matters for the time-slider scope). Heavy bundle (~3 MB). MIT.
• uPlot — minimal canvas-based renderer, fastest for ≥10k points. MIT. Tiny API surface.
• Recharts — popular declarative React charts. MIT.
• ECharts / echarts-for-react — feature-rich, includes dataZoom (slider). Apache.

Add anything the analysis surfaces.

Comparison axes

Evaluate every candidate against:

• Sparkline-in-cell support — does the lib give us a small, axis-less inline chart, or do we hand-roll one on its primitives?
• Drill-down full-size line chart with tooltips, axis formatting, theme integration.
• Range-slider / time-slider for the matrix-snapshot use case (built-in vs compose with MUI Slider).
• Performance ceiling — comfortable point count without manual downsampling, behaviour at tens of thousands of points.
• Bundle size impact (gzipped + brotli). Document raw and tree-shaken.
• Theme integration with MUI v7.
• Streaming model — does the library assume a push channel (WS), and does that match our SSE-over-REST setup?
• Licence and maintenance health (recent releases, open-issue trend, breaking-change cadence).
• DLS reuse story — could picking this lib enable upstreaming a <Heatmap> / <TimeSeries> to sci-react-ui, or contribute back to davidia?
• TypeScript types quality.
• SSR friendliness (not blocking — the workspace is SPA — but worth noting for other consumers).

Process

1. Open a draft ADR PR against this repo at docs/decision-records/decisions/0018-time-series-ui-library.md (next available number after 0017-smartem-frontend-monorepo-restructure.md). Use the COPYME template (Status / Context / Decision / Consequences).
2. Fill in the comparison matrix. Run small throwaway spike branches against the more promising candidates if a paper assessment can't conclude — verify sparkline-in-cell rendering with realistic data shapes is the cheapest spike to run.
3. Land a concrete recommendation. If we don't pick davidia, the ADR has to defend that on the axes above, not vague preference.
4. Once the ADR is merged, smartem-frontend#67 PR 67b2 (time-series implementation) can begin.

Audience

Written for a DLS-wide engineering audience, not just for SmartEM. The aim is that PATo, Evo, DII, future facility frontends, and sci-react-ui maintainers can lift the analysis or its conclusion without re-deriving it. Cross-link the resulting ADR from any DLS visualization conversation.

Out of scope here

• Implementation of the time-series view in apps/smartem — tracked at smartem-frontend#67.
• Server-side downsampling / aggregation strategy — separate decision.
• Replacement of any chart library already in production use elsewhere at DLS — this ADR is forward-looking guidance for new work.