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

* Add ability to hover, select, and filter points upon `draw()`

Also expose `hoveredPoint` via `scatterplot.get('hoveredPoint')`

* Document new `draw()` options

Author: flekschas

CHANGELOG.md

@@ -1,5 +1,7 @@
-## Next
+## 1.7.0
 
+- Add `preventFilterReset` option to `draw()` to allow re-drawing while keeping the current point filter. [#136](https://github.com/flekschas/regl-scatterplot/pull/136)
+- Add ability to hover, select, and filter points immediately when calling `draw(points, { hover: 0, select: [1, 2], filter: [0, 2, 3] })`. Immediately hovering, selecting, or filtering points avoids a filter that can occur when first drawing points and then hovering, selecting, or filtering points subsequently.
 - Add missing `filteredPoints` type definition. [#139](https://github.com/flekschas/regl-scatterplot/pull/139)
 - Add missing `selectedPoints` type definition.
 - Fix drawing a single connecting line between points [#125](https://github.com/flekschas/regl-scatterplot/issues/125)

README.md

@@ -299,6 +299,10 @@ Note that repeatedly calling this method without specifying `points` will not cl
   - `transition` [default: `false`]: if `true` and if the current number of points equals `points.length`, the current points will be transitioned to the new points
   - `transitionDuration` [default: `500`]: the duration in milliseconds over which the transition should occur
   - `transitionEasing` [default: `cubicInOut`]: the easing function, which determines how intermediate values of the transition are calculated
+  - `preventFilterReset` [default: `false`]: if `true` and if the number of new points is the same as the current number of points, the current point filter will not be reset
+  - `hover` [default: `undefined`]: a shortcut for [`hover()`](#scatterplot.hover). This option allows to programmatically hover a point by specifying a point index
+  - `select` [default: `undefined`]: a shortcut for [`select()`](#scatterplot.select). This option allows to programmatically select points by specifying a list of point indices
+  - `filter` [default: `undefined`]: a shortcut for [`filter()`](#scatterplot.filter). This option allows to programmatically filter points by specifying a list of point indices
 
 **Returns:** a Promise object that resolves once the points have been drawn or transitioned.
 
@@ -336,12 +340,21 @@ scatterplot.draw([[0.6, 0.6, 0, 0.6]], { transition: true });
 // Alternatively, call `scatterplot.clear()`
 scatterplot.draw([]);
 
-// Finally, you can also specify the point data in a column-oriented format. The
+// You can also specify the point data in a column-oriented format. The
 // following call will draw three points: (1,3), (2,2), and (3,1)
 scatterplot.draw({
   x: [1, 2, 3],
   y: [3, 2, 1],
 });
+
+// Finally, you can also specify which point will be hovered, which points will
+// be selected, and which points will be filtered. These options are useful to
+// avoid a flicker which would occur if `hover()`, `select()`, and `filter()`
+// are called after `draw()`.
+scatterplot.draw(
+  { x: [1, 2, 3], y: [3, 2, 1] },
+  { hover: 0, selected: [0, 1], filter: [0, 2] }
+);
 ```
 
 <a name="scatterplot.clear" href="#scatterplot.clear">#</a> scatterplot.<b>clear</b>()
@@ -368,7 +381,7 @@ Select some points, such that they get visually highlighted. This will trigger a
 
 **Arguments:**
 
-- `points` is an array of point indices.
+- `points` is an array of point indices referencing the points that you want to select.
 - `options` [optional] is an object with the following properties:
   - `preventEvent`: if `true` the `select` will not be published.
 
@@ -426,7 +439,7 @@ Programmatically hover a point, such that it gets visually highlighted. This wil
 
 **Arguments:**
 
-- `points` is an array of point indices.
+- `point` is the point index referring to the point you want to hover.
 - `options` [optional] is an object with the following properties:
   - `showReticleOnce`: if `true` the reticle will be shown once, even if `showReticle === false`.
   - `preventEvent`: if `true` the `pointover` and `pointout` will not be published.

src/index.js

@@ -463,6 +463,7 @@ const createScatterplot = (
   let maxValueZ = 0;
   let maxValueW = 0;
 
+  /** @type{number|undefined} */
   let hoveredPoint;
   let isMouseInCanvas = false;
 
@@ -751,7 +752,7 @@ const createScatterplot = (
   };
 
   /**
-   * @param {number | number[]} point
+   * @param {number} point
    * @param {import('./types').ScatterplotMethodOptions['hover']} options
    */
   const hover = (
@@ -2068,7 +2069,7 @@ const createScatterplot = (
     select(filteredSelectedPoints, { preventEvent });
 
     // Unset any potentially hovered point
-    hover(-1, { preventEvent });
+    if (!filteredPointsSet.has(hoveredPoint)) hover(-1, { preventEvent });
 
     return new Promise((resolve) => {
       const finish = () => {
@@ -2308,6 +2309,18 @@ const createScatterplot = (
 
             setPoints(points);
 
+            if (options.hover !== undefined) {
+              hover(options.hover, { preventEvent: true });
+            }
+
+            if (options.select !== undefined) {
+              select(options.select, { preventEvent: true });
+            }
+
+            if (options.filter !== undefined) {
+              filter(options.filter, { preventEvent: true });
+            }
+
             if (drawPointConnections) {
               setPointConnections(points).then(() => {
                 pubSub.publish('pointConnectionsDraw');
@@ -2907,6 +2920,7 @@ const createScatterplot = (
     if (property === 'opacityInactiveMax') return opacityInactiveMax;
     if (property === 'opacityInactiveScale') return opacityInactiveScale;
     if (property === 'points') return searchIndex.points;
+    if (property === 'hoveredPoint') return hoveredPoint;
     if (property === 'selectedPoints') return [...selectedPoints];
     if (property === 'filteredPoints')
       return isPointsFiltered

src/types.d.ts

@@ -148,6 +148,7 @@ export type Properties = {
   isDestroyed: boolean;
   isPointsDrawn: boolean;
   isPointsFiltered: boolean;
+  hoveredPoint: number;
   filteredPoints: number[];
   selectedPoints: number[];
 } & Settable;
@@ -159,6 +160,9 @@ export interface ScatterplotMethodOptions {
     transitionDuration: number;
     transitionEasing: (t: number) => number;
     preventFilterReset: boolean;
+    hover: number;
+    select: number | number[];
+    focus: number | number[];
   }>;
   hover: Partial<{
     showReticleOnce: boolean;

tests/index.js

@@ -2414,6 +2414,50 @@ test(
   })
 );
 
+test(
+  'test hover, select, and filter options of `draw()`',
+  catchError(async (t) => {
+    const scatterplot = createScatterplot({
+      canvas: createCanvas(200, 200),
+      width: 200,
+      height: 200,
+    });
+
+    const points = [
+      [0, 0],
+      [1, 1],
+      [1, -1],
+      [-1, -1],
+      [-1, 1],
+    ];
+
+    await scatterplot.draw(points, {
+      hover: 0,
+      select: [1, 2],
+      filter: [0, 2, 3],
+    });
+
+    await wait(50);
+
+    t.equal(
+      scatterplot.get('hoveredPoint'),
+      0,
+      'should be hovering the first point'
+    );
+
+    t.equal(
+      scatterplot.get('selectedPoints'),
+      [2],
+      'should have selected the third point'
+    );
+
+    t.ok(
+      isSameElements(scatterplot.get('filteredPoints'), [0, 2, 3]),
+      'should have filtered down to points 0, 2, and 3'
+    );
+  })
+);
+
 test(
   'zooming with transition',
   catchError(async (t) => {