Tooltips and selection

Hit-test API

Move over the chart. The page asks what is at the pointer and prints the answer: which series, which point by its index in the uploaded array, and whether the pointer is on the mark or only near it. With `nearest` off, only a mark answers.

83 of 136

The call

plot.hitTest(x: number, y: number, nearest?: boolean): Hit | null

What is at a pixel, relative to the canvas: the chart under it and the datum it resolves to, or null when no chart is there.

With nearest, any pixel inside a plot has an answer -- the datum drawn closest to it, which is what a tooltip wants. Without it only a pixel actually on a drawn element answers, which is what a menu wants.

series and index are how a page attaches its own data to a point: the index into the array it uploaded is the index it gets back. There is no per-point payload and there will not be one -- an object per point is the thing this library exists to avoid.

Answered from the last drawn frame, so a plot that has not rendered yet reports null.

calls/hit-test-api

const { x, y } = readings(120);
plot.setCharts({
  charts: [
    {
      kind: "scatter",
      series: [{ x: plot.uploadBuffer(x), y: plot.uploadBuffer(y), label: "readings" }],
      legend: false,
    },
  ],
});
return {
  pointer(px, py) {
    // In logical pixels from the canvas' top left. With `nearest` a
    // point close by answers; without it only the mark itself does.
    const hit = plot.hitTest(px, py, nearest);
    if (hit === null) return "nothing here";
    const where = hit.on ? "on" : "nearest to";
    return `${where} series ${hit.series}, point ${hit.index}, at (${fixed(hit.x)}, ${fixed(hit.y)})`;
  },
};

Also called

2 in the code above, in the order it makes them

plot.setCharts(document: ChartDocument): readonly ChartHandle[]

Draw a document of charts, and get a handle for each one.

The handles come back in document order and are what names a chart afterwards: chartView, setChartView, chartPicked, and the chart on a hover, a hit or any other event. A page linking two charts holds two handles rather than allocating ids.

Replaces the charts and the series each one reads.

Throws rather than drawing a partial document, and a throw leaves the previous document in place. What it refuses: a misspelled key, a handle that names something other than a buffer, a range whose ends are the wrong way round, and a column on a chart kind that cannot read it. All four would otherwise be a chart that draws something subtly wrong, or nothing, with nothing said.

Setting a document again is the way to change one: there is no per-chart edit, and the compile is cheap because the data does not move. The buffers are named by handle, so a live chart writes to them with writeBuffer and never sets a document at all.

plot.uploadBuffer(values: Float32Array | Float64Array): BufferHandle

Upload a block of scalars and return a handle naming it.

A buffer keeps the precision it arrived in. Use Float64Array for time and for anything where f32's twenty-four bits of mantissa would lose something real: a millisecond timestamp narrowed to f32 rounds every sample into a five-minute bucket, and it does that silently.