feat: add ability to hover, select, and filter points upon draw()

[flekschas]

This PR adds the ability to hover, select, and filter points at the time when draw() is called.

Description

What was changed in this pull request?

I added three new properties to the draw options: hover, select, and filter. Those options allow to immediately hover, select, or filter points as they are drawn. E.g.:

const points = [[0, 0], [0.5, 0.5], [1, 1]];
scatterplit.draw(points, { hover: 0, select: [0, 2], filter: [0, 1] });

In the above example, upon drawing the three points, the first point is hovered and selected and the last point is filtered out. While we also attempted to select the last point it's not going to be selected because we filter it out.

For convenience, this PR also expose hoveredPoint via scatterplot.get('hoveredPoint').

Why is it necessary?

Previously, one had to filter after the draw call which leds to flickering as shown in the gif.

const points = generatePoints(numPoints);

const filter = points.x.map((x, i) => [x, i]).filter(([x]) => x < 0).map(([x, i]) => i);

const filterSet = new Set(Array.from({ length: filter.length }, (_, i) => i));
const select = [];
for (let i = 0; i < 20; i++) {
  const idx = Math.floor(Math.random() * filterSet.size);
  select.push(filter[idx]);
  filterSet.delete(idx);
}

const hover = select[Math.floor(Math.random() * select.length)];

scatterplot.draw(points).then(() => {
  // Since we first have to wait until the points are drawn before we can hover, select, and filter
  // there's a split second where all points are shown
  scatterplot.filter(filter);
  scatterplot.select(select);
  scatterplot.hover(hover);
});

Now, one can directly hover, select, and filter at the time of drawing the points, which avoid the flickering.

const points = generatePoints(numPoints);

const filter = points.x.map((x, i) => [x, i]).filter(([x]) => x < 0).map(([x, i]) => i);

const filterSet = new Set(Array.from({ length: filter.length }, (_, i) => i));
const select = [];
for (let i = 0; i < 20; i++) {
  const idx = Math.floor(Math.random() * filterSet.size);
  select.push(filter[idx]);
  filterSet.delete(idx);
}

const hover = select[Math.floor(Math.random() * select.length)];

scatterplot.draw(points, { hover, select, filter });

Checklist

• Provided a concise title as a semantic commit message (e.g. "fix: correctly handle undefined properties")
• CHANGELOG.md updated
• Tests added or updated
• Documentation in README.md added or updated
• Example(s) added or updated
• Screenshot, gif, or video attached for visual changes

[flekschas]

@insertmike Since we've talked about avoiding the flicker upon drawing new points and filtering them down, what do you think of this addition?

[insertmike]

Good idea! @flekschas As the filter Issue occurred, I can imagine how it would as well for the added options, such as hover and select.

For convenience, this PR also expose hoveredPoint via scatterplot.get('hoveredPoint').

I think we should expose this in the README doc too. Otherwise we risk letting it die in the README. Except if this is built automatically by the build script (haven't looked at).

Lastly, I don't want to be pushy, we should take our time, but Is it possible to give an estimate on when we will make a release?

[insertmike]

nit; The addition of the properties could benefit from more descriptive names such as hoveredPoints, selectedPoints, and focusedPoints to enhance clarity. I will let you decide here, as you know the codebase consistency better

[flekschas]

I will keep these prop names as is as they match the function names and internally the draw() function literally calls hover(), select(), or focus() instead of directly setting the state.

[insertmike]

I think these 2 should always expect an array, it introduces additional complexity and potential vulnerabilities in the codebase. If it's selectedPoints, then it's clear for the users that they need to submit: [0] for example.

[flekschas]

Both methods already support this signature. The complexity overhead is neglectable

[flekschas]

think we should expose this in the README doc too. Otherwise we risk letting it die in the README. Except if this is built automatically by the build script (haven't looked at).

Good call! I updated the README to reflect the new draw() signature