pointer pool option

docs/interactions/pointer.md

@@ -176,6 +176,7 @@ The following options control the pointer transform:
 - **x2** - the ending horizontal↔︎ target position; bound to the *x* scale
 - **y2** - the ending vertical↕︎ target position; bound to the *y* scale
 - **maxRadius** - the reach, or maximum distance, in pixels; defaults to 40
+- **pool** - if true, pool with other pointer marks, showing only the closest; defaults to true for the [tip mark](../marks/tip.md)
 - **frameAnchor** - how to position the target within the frame; defaults to *middle*
 
 To resolve the horizontal target position, the pointer transform applies the following order of precedence:

docs/marks/tip.md

@@ -201,7 +201,7 @@ Plot.plot({
 :::
 
 :::tip
-When multiple tips are visible simultaneously, some may collide; consider using the pointer interaction to show only the one closest to the pointer, or use multiple tip marks and adjust the **anchor** option for each to minimize occlusion.
+The tip mark defaults the [**pool**](../interactions/pointer.md#pointer-options) option to true, ensuring multiple marks with the *tip* option don’t collide.
 :::
 
 ## Tip options

src/interactions/pointer.d.ts

@@ -17,6 +17,13 @@ export interface PointerOptions {
   /** The vertical target position channel, typically bound to the *y* scale. */
   py?: ChannelValue;
 
+  /**
+   * Whether this mark participates in the pointer pool, which ensures that
+   * only the closest point is shown when multiple pointer marks are present.
+   * Defaults to true for the tip mark.
+   */
+  pool?: boolean;
+
   /**
    * The fallback horizontal target position channel, typically bound to the *x*
    * scale; used if **px** is not specified.

src/interactions/pointer.js

@@ -3,7 +3,7 @@ import {composeRender} from "../mark.js";
 import {isArray} from "../options.js";
 import {applyFrameAnchor} from "../style.js";
 
-const states = new WeakMap();
+const states = new WeakMap(); // ownerSVGElement → per-plot pointer state
 const handledEvents = new WeakSet();
 
 function pointerK(kx, ky, {x, y, px, py, maxRadius = 40, channels, render, ...options} = {}) {
@@ -29,8 +29,11 @@ function pointerK(kx, ky, {x, y, px, py, maxRadius = 40, channels, render, ...op
 
       // Isolate state per-pointer, per-plot; if the pointer is reused by
       // multiple marks, they will share the same state (e.g., sticky modality).
+      // The pool maps renderIndex → {ii, ri, render} for marks competing for
+      // the pointer (e.g., tips); only the closest point is shown.
       let state = states.get(svg);
-      if (!state) states.set(svg, (state = {sticky: false, roots: [], renders: []}));
+      if (!state)
+        states.set(svg, (state = {sticky: false, roots: [], renders: [], pool: this.pool ? new Map() : null}));
 
       // This serves as a unique identifier of the rendered mark per-plot; it is
       // used to record the currently-rendered elements (state.roots) so that we
@@ -53,12 +56,12 @@ function pointerK(kx, ky, {x, y, px, py, maxRadius = 40, channels, render, ...op
       // mark (!), since each facet has its own pointer event listeners; we only
       // want the closest point across facets to be visible.
       const faceted = index.fi != null;
-      let facetState;
+      let facetPool;
       if (faceted) {
-        let facetStates = state.facetStates;
-        if (!facetStates) state.facetStates = facetStates = new Map();
-        facetState = facetStates.get(this);
-        if (!facetState) facetStates.set(this, (facetState = new Map()));
+        let facetPools = state.facetPools;
+        if (!facetPools) state.facetPools = facetPools = new Map();
+        facetPool = facetPools.get(this);
+        if (!facetPool) facetPools.set(this, (facetPool = new Map()));
       }
 
       // The order of precedence for the pointer position is: px & py; the
@@ -72,32 +75,23 @@ function pointerK(kx, ky, {x, y, px, py, maxRadius = 40, channels, render, ...op
       let i; // currently focused index
       let g; // currently rendered mark
       let s; // currently rendered stickiness
-      let f; // current animation frame
 
-      // When faceting, if more than one pointer would be visible, only show
-      // this one if it is the closest. We defer rendering using an animation
-      // frame to allow all pointer events to be received before deciding which
-      // mark to render; although when hiding, we render immediately.
+      // When pooling or faceting, if more than one pointer would be visible,
+      // only show the closest. We defer rendering using an animation frame to
+      // allow all pointer events to be received before deciding which mark to
+      // render; although when hiding, we render immediately.
+      const pool = state.pool ?? facetPool;
       function update(ii, ri) {
-        if (faceted) {
-          if (f) f = cancelAnimationFrame(f);
-          if (ii == null) facetState.delete(index.fi);
-          else {
-            facetState.set(index.fi, ri);
-            f = requestAnimationFrame(() => {
-              f = null;
-              for (const [fi, r] of facetState) {
-                if (r < ri || (r === ri && fi < index.fi)) {
-                  ii = null;
-                  break;
-                }
-              }
-              render(ii);
-            });
-            return;
-          }
-        }
-        render(ii);
+        if (!pool) return void render(ii);
+        if (ii == null) render(ii);
+        pool.set(renderIndex, {ii, ri, render});
+        if (pool.frame !== undefined) cancelAnimationFrame(pool.frame);
+        pool.frame = requestAnimationFrame(() => {
+          pool.frame = undefined;
+          let best = null;
+          for (const [, c] of pool) if (!best || c.ri < best.ri) best = c;
+          for (const [, c] of pool) c.render(c === best ? c.ii : null);
+        });
       }
 
       function render(ii) {
@@ -128,7 +122,7 @@ function pointerK(kx, ky, {x, y, px, py, maxRadius = 40, channels, render, ...op
 
         // Dispatch the value. When simultaneously exiting this facet and
         // entering a new one, prioritize the entering facet.
-        if (!(i == null && facetState?.size > 1)) {
+        if (!(i == null && facetPool?.size > 1)) {
           const value = i == null ? null : isArray(data) ? data[i] : data.get(i);
           context.dispatchValue(value);
         }

src/marks/tip.js

@@ -49,7 +49,8 @@ export class Tip extends Mark {
       textPadding = 8,
       title,
       pointerSize = 12,
-      pathFilter = "drop-shadow(0 3px 4px rgba(0,0,0,0.2))"
+      pathFilter = "drop-shadow(0 3px 4px rgba(0,0,0,0.2))",
+      pool = true
     } = options;
     super(
       data,
@@ -84,6 +85,7 @@ export class Tip extends Mark {
     for (const key in defaults) if (key in this.channels) this[key] = defaults[key]; // apply default even if channel
     this.splitLines = splitter(this);
     this.clipLine = clipper(this);
+    this.pool = pool;
     this.format = typeof format === "string" || typeof format === "function" ? {title: format} : {...format}; // defensive copy before mutate; also promote nullish to empty
   }
   render(index, scales, values, dimensions, context) {