Styling, export and integration

Declarative chart configuration API

110 of 136

One document per canvas

Charts are described, not built call by call. setCharts takes a document: the charts on the canvas, each with its kind, its series and its settings. Data is uploaded once as buffers and named in the document by handle, so setting a document again is cheap and a chart never holds a copy of the numbers.

export function draw(plot: Plot, time: Float64Array, pressure: Float32Array): void {
  // Data goes in once, as buffers. The document names them by handle.
  const t = plot.uploadBuffer(time);
  const p = plot.uploadBuffer(pressure);

  const document: ChartDocument = {
    charts: [
      {
        kind: "line",
        title: "Manifold pressure",
        series: [{ x: t, y: p, label: "kPa" }],
        x: { title: "Time", scale: "time" },
        y: { title: "kPa" },
        crosshair: true,
      },
    ],
  };
  // Returns a handle per chart, in document order.
  const [chart] = plot.setCharts(document);
  void chart;
}

Setting a document replaces the one before. To change a chart, change the document and set it again; to follow live data, write into the buffers and the charts follow without being set again.

A setting a kind cannot read is refused

kind decides which fields a chart takes, so the editor offers a gauge only what a gauge reads. The engine checks the same way when the document arrives: a field it does not know, or one the kind does not read, is an error naming it, and the previous document stays on screen.

export function refused(plot: Plot): void {
  const document: ChartDocument = {
    // @ts-expect-error a gauge takes values, not an x and a y
    charts: [{ kind: "gauge", series: [{ x: plot.uploadBuffer(new Float32Array(1)) }] }],
  };
  // The engine refuses it too, naming the field, rather than drawing nothing.
  void document;
}

Every kind, with every field it takes and a running example, is in the chart reference.