Charts and data

AlkChart 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 AlkChart from '@alkemist/ui/AlkChart.astro';

<AlkChart
  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
/>

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.

<AlkChart
  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
/>

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

<AlkChart
  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
/>

See all presets together on the test page.

Props and defaults

The exported prop type is AlkChartProps.

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 changes and container-width changes redraw the chart and reset its view. 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 includes a CSV download and a table of its actual source rows. Tables show at most 100 rows, state the full count, and link to the complete file. CSV values are inserted as text, and tooltips use Vega-Tooltip’s default escaping.

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 AlkChart prop.