[Feature] AxisPointer snapping
- Dominant language
- TypeScript
- Stars
- 67.3k
- Forks
- 19.8k
- Avg merge
- 15h 17m
- Merged PRs (30d)
- 5
Description
### What problem does this feature solve?
# The Problem
In the current implementation, axisPointer snaps to the nearest data for different axis separately. This may cause the snapped data to be far away from the mouse position and lack the flexibility to configure which value to snap to for series like candlestick.
#11684 was trying to fix this but there were still some consensus required and was closed because too much conflicts. And this issue is going to discuss more details about it.
# Case Studies
## Case 1: two `snap: true` axes
For coordinates having two axes like rectangular coordinates and polar coordinates, the Cartesian distance should be compared to calculate the nearest data. If coordinates have two `snap: true` axes, it should snap to the data with the smallest Cartesian distance.
For example, in current implementation, [this scatter chart](https://echarts.apache.org/examples/en/view.html?c=scatter-nutrients-matrix&edit=1&reset=1&version=5.3.0), the snapped points are those of the same x and y value with the mouse position, but they are in fact quite far away from the mouse position.

A better snapping policy would be to snap the nearest point to the mouse position because the user's attention is more focus on the position near the mouse point (especially for this case because the mouse position is also the center of the cross of the axisPointer).
Line series with both `'value'` axes can be considered the same as this case.
Axes with `type: 'cagetory'` should be treated as if they have been set `snap: true` implicitly.
### Proposed API
```js
xAxis: {
axisPointer: {
snap: true
}
},
yAxis: {
axisPointer: {
snap: true
}
}
```
## Case 2: one `snap: true` axis but fix to data

Developers should be given the ability to snap the xAxis and use the corresponding y value to snap yAxis to. In this case, it means the axisPointer cross should be displayed at `['Tue', 230]` instead of `['Tue', 135]`.
### Proposed API
```js
xAxis: {
axisPointer: {
snap: true
}
},
yAxis: {
axisPointer: {
snap: 'data'
}
}
```
## Case 3: series with multiple dimension data
There are cases where there are **multiple dimensions** in one piece of data, e.g., candlestick series, boxplot series, custom series and so on. The series should have the ability to define which dimension to be used to snap. We might also provide the ability for developers to override the default policy of the series.
### Proposed API
```js
xAxis: {
axisPointer: {
snap: true
}
},
yAxis: {
axisPointer: {
snap: 'data.close' // 'close' is a dimension name in the dataset
}
}
```
## Case 4: multiple series
For **multiple series** situations, e.g., two line series sharing the same `xAxis`, developers should be provided the ability to choose between *snapping to a certain series* (similar to the case of candlestick series) or *snapping to the nearest series* (like [this highcharts demo](https://jsfiddle.net/gh/get/library/pure/highcharts/highcharts/tree/master/samples/highcharts/tooltip/bordercolor-default/).
### Proposed API
To snap to a certain series:
```js
xAxis: {
axisPointer: {
snap: true
}
},
yAxis: {
axisPointer: {
snap: 'firstSeries' // or, 'firstSeries.data.close'. 'firstSeries' is a series name
}
}
```
To snap to the nearest series:
```js
xAxis: {
axisPointer: {
snap: true
}
},
yAxis: {
axisPointer: {
snap: 'data'
}
}
```
## Misc
`axisPointer` of coordinates other than cartesian may require more test cases. For example, polar axes don't support snapping and the axisPointer always look like this no matter where the mouse position is.

### What does the proposed API look like?
```js
xAxis: {
axisPointer: {
snap: true // or 'data', 'data.close', 'firstSeries.data.close'
}
}
```
Contributor guide
Research direction
Start by reviewing the existing axisPointer snapping behavior and the discussion in closed issue #11684. Compare the proposed API against the four case studies, including multi-dimensional and multiple-series data and non-Cartesian coordinates. Done means the snapping policy and API are agreed and the documented cases are covered.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- data-visualization
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100