HTML tooltip misplaced by exactly the scroll delta: forward/inverse pointer transformers share one srcCoords cache key

[fidalgodev]

Version: zrender 6.1.0 (via echarts 6.1.0, renderer: 'svg'; the bug is renderer-independent)

Summary

When an echarts HTML tooltip uses tooltip.appendTo / appendToBody, and the page (or an inner scroll container) scrolls between chart init and the first tooltip show, every tooltip is placed exactly the scroll delta too low. On touch devices this makes tooltips appear near the bottom of the screen (or off-screen) for any chart the user has to scroll to.

The root cause is in zrender/src/core/dom.ts: preparePointerTransformer shares one saved.srcCoords cache-validity key between the forward (trans) and inverse (invTrans) transformers of the same element, so the inverse transformer is effectively never invalidated.

Reproduction

<div style="height: 250vh">
  <div id="chart" style="width: 400px; height: 300px; margin-top: 150vh"></div>
</div>
<script src="https://cdn.jsdelivr.net/npm/echarts@6.1.0/dist/echarts.min.js"></script>
<script>
  const chart = echarts.init(document.getElementById('chart'), null, { renderer: 'svg' });
  chart.setOption({
    tooltip: { trigger: 'item', appendToBody: true }, // or appendTo
    series: [{ type: 'pie', data: [{ name: 'a', value: 1 }, { name: 'b', value: 2 }] }],
  });
</script>

1. Load the page at scroll position 0 (the chart is below the fold; the tooltip's DOM content — and, critically, the inverse transformer — is built now, at init).
2. Scroll down to the chart.
3. Hover / tap a slice.

Expected: tooltip next to the pointer.
Actual: tooltip appears window.scrollY px below the pointer (usually off-screen). The same happens with an inner overflow: auto scroller and an appendTo target inside it — the offset is then the container's scrollTop.

Root cause

preparePointerTransformer (src/core/dom.ts):

const transformerName: 'invTrans' | 'trans' = inverse ? 'invTrans' : 'trans';
const transformer = saved[transformerName];
const oldSrcCoords = saved.srcCoords;          // <-- shared between both directions
...
return (oldCoordTheSame && transformer)
    ? transformer
    : (
        saved.srcCoords = srcCoords,           // <-- refreshed by either direction
        saved[transformerName] = ...
    );

Sequence for the chart's viewport root element:

1. TooltipHTMLContent's constructor calls makeStyleCoord → transformLocalCoord → builds and caches invTrans with the element's mount-time marker rects, and stores those rects in saved.srcCoords.
2. Every later pointer event goes through clientToLocal → transformCoordWithViewport (forward). After any scroll the rects changed, so the trans transformer is rebuilt with fresh rects — and saved.srcCoords is overwritten with them.
3. The tooltip then positions itself via transformLocalCoord, which calls the inverse on the same element. Its staleness check compares current rects against the srcCoords that step 2 just refreshed — they match, so the mount-time invTrans is returned and is never rebuilt.

The stale inverse maps chart-local → viewport using the chart's mount-time position, so the final tooltip coordinate is correct + (scroll delta since mount). I verified this numerically in an instrumented Playwright run: with an inner scroller at scrollTop = 715, the tooltip's translate3d Y was correct + 715 to the half-pixel, while the forward event transform (fresh) and the container transform (fresh) were both exact. Only Y is affected when only vertical scrolling occurs, and charts sitting at the top of the page (tappable without scrolling) never show the bug — which makes it easy to miss.

Suggested fix

Give each direction its own cache-validity key:

 function preparePointerTransformer(markers: HTMLDivElement[], saved: SavedInfo, inverse?: boolean) {
     const transformerName: 'invTrans' | 'trans' = inverse ? 'invTrans' : 'trans';
+    const srcCoordsName: 'invSrcCoords' | 'srcCoords' = inverse ? 'invSrcCoords' : 'srcCoords';
     const transformer = saved[transformerName];
-    const oldSrcCoords = saved.srcCoords;
+    const oldSrcCoords = saved[srcCoordsName];
     ...
     return (oldCoordTheSame && transformer)
         ? transformer
         : (
-            saved.srcCoords = srcCoords,
+            saved[srcCoordsName] = srcCoords,
             saved[transformerName] = inverse
                 ? buildTransformer(destCoords, srcCoords)
                 : buildTransformer(srcCoords, destCoords)
         );
 }

(plus invSrcCoords?: number[] on SavedInfo). Each transformer then validates against the geometry it was actually built from; steady-state caching behavior is unchanged. We're shipping exactly this as a pnpm patch downstream and it fixes the misplacement with no regressions across our chart suite. Happy to open a PR if useful.