Charts and data

Chart renders a CSV file as a line, bar, scatter, pie, donut, or heatmap. The chart engine loads when the figure approaches the viewport. Vega-Lite supplies the chart specification and Vega supplies the runtime; Alkemist adds the reusable figure, theme, loading state, table, and source download. Vega-Lite data model.

Start with a file

Place a CSV in your Astro site’s public directory, then name the fields and explain their meaning. This example uses a deterministic teaching fixture, not measured research data.

import Chart from '@alkemdotdev/alkemist-components/chart';

<Chart
  src="/test/oscillation.csv"
  type="line"
  x="time"
  y="position"
  xLabel="Time (s)"
  yLabel="Position (m)"
  title="A damped oscillator"
  description="An analytic trajectory with unit initial displacement and zero initial velocity."
  sample
/>

---
import Chart from "@alkemdotdev/alkemist-components/chart";
---

<Chart
  id={""}
  src={"/test/oscillation.csv"}
  type={"line"}
  x={"time"}
  y={"position"}
  title={"A damped oscillator"}
  description={"Synthetic data with damping ratio 0.12."}
  xLabel={"Time (s)"}
  yLabel={"Position (m)"}
  xType={"quantitative"}
  color={""}
  colorLabel={""}
  value={""}
  valueLabel={""}
  ink={"cobalt"}
  height={280}
  grid={true}
  zoom={true}
  horizontal={false}
  stacked={false}
  caption={""}
  sample={true}
  parameters={false}
/>

Shift + scroll zooms; dragging pans. Line charts zoom along x; scatter plots zoom both axes. The Reset view button restores the initial extent. The modifier keeps ordinary page scrolling available. Scale-bound selections are provided by Vega-Lite.

Supported presets

For the circular presets, x and y name the category and amount columns; they are not Cartesian axes. Zero amounts are allowed, but at least one amount must be positive. Aggregation is currently the author’s responsibility: prepare one row per category for a pie, one row per category/group for a bar, and one row per grid cell for a heatmap.

<Chart
  src="/test/materials.csv"
  type="bar"
  x="material"
  y="value"
  title="Prototype parts"
  description="Invented counts by material."
  xLabel="Material"
  yLabel="Component count"
  horizontal
  sample
/>

<Chart
  src="/test/materials.csv"
  type="donut"
  x="material"
  y="value"
  title="Prototype composition"
  description="The same eight invented counts."
  yLabel="Component count"
  sample
/>

<Chart
  src="/test/field.csv"
  type="heatmap"
  x="x"
  y="y"
  value="value"
  title="An analytic field"
  description="625 samples of a dimensionless function."
  xLabel="x (dimensionless)"
  yLabel="y (dimensionless)"
  valueLabel="Field value"
  sample
/>

Try the presets

Use the Bar, Donut, and Heatmap presets in the playground above. Open the data table to inspect the rows in each chart. Download the materials CSV and field CSV into public/test/ to run the snippets in your site.

See all presets together on the test page.

Props and defaults

The exported prop type is ChartProps.

The default x type is numeric for line/scatter, categorical for bar/pie/donut, and ordinal for heatmaps. For dated series, set xType="temporal" and use unambiguous ISO dates. Quantitative fields must contain finite numbers. Empty numeric and temporal cells remain missing values; invalid numeric or date text produces an explicit error. A numeric or date column with no present values also produces an error. Heatmap coordinate columns containing only numbers are parsed numerically so their order is numeric rather than lexical.

Consistent inks, readable data

Category colors use the same eight ink values on both whiteboard and blackboard. An explicit domain preserves the first-seen category order from the file when the theme changes. This does not assign a universal color to every possible category name: two differently ordered source files can assign different colors to their first category.

Axes, labels, and legends use the board’s neutral foreground and Ubuntu fonts. Grid lines use the board’s neutral rule color. Heatmaps use a separate, fixed continuous cobalt ramp and labeled value scale, because ordered measurements need an ordered ramp rather than eight categorical swatches. The palette is not certified as distinguishable for every form of color vision; labels, tooltips, and the table remain essential.

Theme, parameter, and container-width changes redraw the chart while preserving a compatible zoom window. Reset view explicitly restores the full plotted domain. Resizing is briefly debounced, then the chart recomputes tick density and legend layout for the new width. Replaced and removed views are finalized so their listeners do not remain attached. Vega view lifecycle.

Source data stays available

Every chart keeps an original CSV link. Data and export reveals a table of the prepared rows supplied to the plot, with 25 rows per page and Previous/Next controls. Preparation includes validated numeric and date values and any chart-specific filtering; it does not filter rows to the current zoom window.

Download plotted CSV exports those prepared rows. Spreadsheet formula prefixes in string cells are escaped; actual negative numeric measurements remain numbers. Download SVG and Download PNG export the current plot, including its theme and visible zoom window, without the surrounding controls. SVG is useful for vector editing; PNG is a 2× raster image. Export failures are reported beside the controls. The underlying APIs are Vega’s view exports.

CSV cells are rendered as text, and tooltips use Vega-Tooltip’s escaping. Tables and CSV stay available when inspecting a chart in Focus. Try the live figures lab or Look closer.

This first version loads the complete file into browser memory. It has no streaming, worker parsing, automatic reduction, automatic field selection, or server-rendered chart fallback. Keep datasets modest. A remote CSV must allow browser access through CORS. When JavaScript is unavailable, the CSV download remains usable; a fetch, validation, or rendering failure produces an error and Retry chart button, never invented replacement data.

Still planned

Area and step charts, histograms, error bars, regression, maps, linked selections, domain and formatting controls, full Vega/Vega-Lite specifications, and inference-assisted authoring remain future Alkemist APIs. Many underlying techniques exist in the Vega-Lite example gallery; an upstream example is not yet a supported Chart prop.