# Data display

## Dense data table

Tables are for comparison and dense structured data—not primary navigation.

A table that becomes a tool rather than a comparison belongs on the React
side instead: the shadcn table primitives draw it, TanStack drives the sorting
and the paging, and the page pays for an island.

## Symbol index

`RefIndex` is the searchable half of a generated API reference. The rows are
built at build time from the same `reference.json` the reference pages are a
view of, and the part mounts one island with them, so an MDX page writes one
tag and the reader gets a filter over the whole library.

It is the only Astro part that mounts an island. A filter is the one thing on a
reference page that has to happen in the reader's hands, and the alternative is
every consuming site writing the same island itself.

```astro
---
import RefIndex from '@ambiqai/helia-ui/astro/RefIndex';
import reference from '../../public/reference/api/reference.json';
import { groups } from '../../reference.config.json';
---

<RefIndex reference={reference} base="/my-product/" groups={groups} />
```

Facets are derived, not declared: the data type comes off the name suffix a
kernel library already encodes, the header off the declaring file, and the
group off a config of name patterns. A facet with no values renders no control,
which is why the path filter below exists only because the manifest supplies
it. Search matches the name, the summary, the module and every facet value.

Prerequisites, the buffer-size rule, tolerances and supported paths are not in
any declaration. They come from an overlay keyed by symbol name, which is the
shape a kernel manifest takes, and a row that the overlay covers gains a
disclosure. Two of the fourteen rows below are covered.

The library is invented and so are the routes: the links are the anchors a
generated reference serves, and this site publishes no such reference, so they
are here to be read rather than followed.

## Charts

`ChartPlot` is the React counterpart of the `Chart` Astro part: the same props,
the same frame, the same marks, drawn in the browser instead of at build. Reach
for it when the data is not known until the page runs — a filter, a range the
reader picks, a live feed. When the data is known at build, use the Astro part
instead and the page ships no chart JavaScript at all.

Plot is the default for new charts. The Recharts wrapper below stays for the
shadcn compatibility path: it is the registry component, so a shadcn block or a
generated dashboard that expects `ChartContainer` keeps working.

```tsx
import { ChartPlot } from '@ambiqai/helia-ui/react/chart-plot';
```

## Interactive charts

`ChartInteractive` takes the same props as `ChartPlot` and draws them with
Apache ECharts, which is the interactive layer: a tooltip on hover, a legend
that toggles a series, a zoom on the axis, a brush that hands the selected rows
back through `onSelect`. The title, subtitle, legend and caption are the same
HTML and the same classes as the Plot parts, so the two are one figure with
different behavior; ECharts is given the plot area and nothing else.

Reach for `Chart` first. The Astro part ships inline SVG and zero JavaScript,
and `ChartPlot` redraws the same figure in the browser when the data is not
known until the page runs. `ChartInteractive` costs an island and a charting
library, so it earns its place only when the reader has to do something to the
chart to get the answer — narrow a range, drop a series, select a group.

```tsx
import { ChartInteractive } from '@ambiqai/helia-ui/react/chart-interactive';
```

## Plots

These standard examples use the shadcn chart wrapper over Recharts. Use bars for
direct comparison and scatter plots for tradeoffs between two measures; keep the
framing compact and the number of series restrained.

## A converted MkDocs chart

The worked example behind the
[charts section of the migration guide](https://ambiqai.github.io/helia-ui/migrating-from-mkdocs/#charts).
On the MkDocs side this is two Plotly traces carried as data attributes on an
empty div and drawn by `chart-init.js` at load. Here the series are a typed
module the build can see, the renderer is the package wrapper, and the two
colors are `--chart-1` and `--chart-2` rather than hexes, so the lines follow
the theme.

The series is illustrative and not a measurement of any part.