[Bug]: near_points(add_dist=True) adds a column named dist, the docs promise dist_ #2506

Component

Server (server.*)

Severity

P2 - Medium (workaround exists)

Shiny Version

1.8.0 (also present on main at 232d2d9)

Python Version

3.12.13

Minimal Reproducible Example

import pandas as pd
from shiny.plotutils import near_points

df = pd.DataFrame({"x": [1.0, 2.0], "y": [1.0, 2.0]})

# no pointer event yet
print(list(near_points(df, None, "x", "y", add_dist=True).columns))
# ['x', 'y', 'dist']        docs say 'dist_'

coord = {
    "x": 1.0, "y": 1.0,
    "coords_css": {"x": 10.0, "y": 10.0},
    "coords_img": {"x": 10.0, "y": 10.0},
    "img_css_ratio": {"x": 1.0, "y": 1.0},
    "mapping": {"x": "x", "y": "y"},
    "domain": {"left": 0.0, "right": 3.0, "bottom": 0.0, "top": 3.0},
    "range": {"left": 0.0, "right": 30.0, "bottom": 30.0, "top": 0.0},
    "log": {"x": None, "y": None},
}
print(list(near_points(df, coord, "x", "y", add_dist=True, all_rows=True).columns))
# ['x', 'y', 'dist', 'selected_']        docs say 'dist_'

Behavior

Current: near_points(add_dist=True) adds a column named dist.

Expected: a column named dist_, which is what the documentation promises.

The docstring of add_dist says it twice (shiny/plotutils.py:203-206):

If True, add a column named dist_ that contains the distance from the coordinate to the point, in pixels. When no pointer event has yet occurred, the value of dist_ will be numpy.NaN.

The code writes dist in both branches, shiny/plotutils.py:228 and :281:

new_df["dist"] = np.nan
...
new_df["dist"] = dists

Three things point at the column name being the bug rather than the docs:

1. The other column this same function adds keeps the trailing underscore: new_df["selected_"] = False. The underscore convention exists to avoid colliding with a user column of the same name, and dist is a far more likely user column name than dist_.
2. Shiny for R, which this function is a port of, writes dist_ (R/image-interact.R): df$dist_ <- NA_real_ and df$dist_ <- dists, with the same @param addDist wording.
3. Nothing inside py-shiny reads the column, so the name only matters at the public boundary.

Workaround today is to read dist and ignore the documentation.

Error Messages (if any)

(no error, the column is silently named differently from the documented name)

Environment

• OS: macOS 15
• Browser: not applicable, reproduced in a plain Python session
• Dependencies: shiny 1.8.0, pandas 2.3.3, numpy 2.3.4, Python 3.12.13

Additional context

Renaming the column is a breaking change for anyone who already reads dist, so this needs a maintainer call on the path:

• rename to dist_, matching the docs, the R implementation and the neighbouring selected_;
• or keep dist and fix the docstring, dropping parity with R.

I have the one line fix plus a regression test ready and I am happy to open a PR for whichever direction you prefer.