fix(heatmap): add eventData handler for proper click event data

[ubertidavide]

Description

When interacting with heatmaps, the standard plotly_click event previously lacked properly formatted 2D matrix indices and explicit z values. This made it difficult for downstream wrappers (such as Streamlit or Marimo) to identify the exact clicked cell natively.

Architecture Note: plotly_click vs plotly_heatmapclick

While introducing a trace-specific event like plotly_heatmapclick (similar to plotly_treemapclick or plotly_sunburstclick) was originally discussed in #7685, doing so for heatmaps is an anti-pattern. Heatmaps are Cartesian trace types that reside on standard 2D Cartesian subplots. Introducing trace-specific click events on Cartesian subplots breaks consistency across Cartesian traces. The correct architectural approach is to rely on the standard plotly_click event and delegate trace-specific payload formatting to a dedicated eventData handler.

Summary of Changes

This PR introduces the missing eventData handler for the heatmap trace:

• pointNumber and pointIndex are properly exposed as a 2D array [row, col].
• z values are explicitly attached to the event payload.

This PR completes and supersedes #7686 (which was stalled). Unlike #7686, this implementation cleanly exposes the 2D pointNumber: [row, col] matrix indices and z values via eventData without modifying hover.js (avoiding category axis regressions), and includes complete Jasmine unit tests.

Closes #7685.

Testing

• Added regression tests in test/jasmine/tests/heatmap_test.js to verify that standard plotly_click events emit 2D pointNumber and z values.
• Ran Jasmine test suite (npm run test-jasmine -- test/jasmine/tests/heatmap_test.js) with 51/51 specs passing successfully.

[camdecoster]

Thanks for the PR! Our team will review and follow up.

[ubertidavide]

I've force-pushed an update to src/traces/heatmap/event_data.js:

• Standard Cartesian Fields Added: In the initial commit, standard Cartesian properties (x, y, xaxis, yaxis) were omitted. Because defining a trace-level eventData handler bypasses the fallback in helpers.js, x and y were evaluated as undefined during multicategory hover tests.
• Fix: Added the standard Cartesian field extraction chain (xVal / x / xLabelVal, yVal / y / yLabelVal, xa, ya), matching the pattern used in bar/event_data.js and image/event_data.js.
  All Jasmine tests (in particular hover_label_test.js that have the one that failed) are now passing completely with zero failures

[ubertidavide]

Added draftlogs/7920_fix.md to satisfy the CHANGELOG requirement for CI (check-draftlog).

[emilykl]

Hi @ubertidavide, thanks for the contribution!

The original issue doesn't contain steps for reproducing the bug, which makes it hard to verify a fix.

Can you provide a JavaScript code snippet which demonstrates the bug?

[ubertidavide]

Hi @emilykl,

Here is a minimal reproduction showing the issue and how registering eventData resolves it.

Background

When receiving click/select events on a heatmap, event points can be constructed from raw point objects where pt.z is supplied directly (rather than pt.zLabelVal from hover text formatting).

Because heatmap traces lacked a registered eventData module (src/traces/heatmap/event_data.js), Plotly fell back to default cartesian logic in components/fx/helpers.js. The default fallback only checked pt.zLabelVal, which caused:

• pt.z to evaluate as undefined whenever zLabelVal wasn't populated (e.g. in selection mode or raw point payloads).
• pt.pointIndex to be omitted for 2D matrix points.

Other trace types (like bar, image, treemap, etc.) define an explicit eventData handler to handle point normalization properly.

---

Minimal Reproducible Example

const gd = document.createElement('div');
document.body.appendChild(gd);

Plotly.newPlot(gd, [{
    type: 'heatmap',
    z: [[10, 20], [30, 40]],
    x: ['ColA', 'ColB'],
    y: ['RowA', 'RowB']
}]);

gd.on('plotly_click', function(data) {
    const pt = data.points[0];
    console.log('pointNumber:', pt.pointNumber);
    console.log('pointIndex:', pt.pointIndex);
    console.log('z:', pt.z);
});

---

Behavior Summary

When event data is extracted from point targets containing pt.z:

Property	Without heatmap/event_data.js	With PR #7920
pointNumber	[row, col]	[row, col]
pointIndex	undefined	[row, col]
z (when pt.z passed)	undefined	20
x	'ColB'	'ColB'
y	'RowA'	'RowA'

---

Implementation Note

Adding src/traces/heatmap/event_data.js aligns heatmaps with src/traces/bar/event_data.js and src/traces/image/event_data.js. It ensures both pt.zLabelVal and pt.z are mapped to out.z, and sets out.pointIndex, while preserving standard cartesian properties (x, y, xaxis, yaxis).