dataless brush

[Fil]

A brush mark that renders a 2D rectangular brush, enabling selection and filtering. The brush mark has aria-label="brush". The mark does not take data; instead, it offers a mechanism to filter other marks while brushing, as well as any dataset.

The brush dispatches input events with the selection bounds {x1, x2, y1, y2} in data space and a filter function to test whether a point falls within the selection.

Brushes support faceted plots: each facet gets its own brush, starting one clears the others, and the value includes fx/fy as relevant (with support in the filter function).

Three reactive mark options transforms — brush.inactive, brush.context, brush.focus — allow marks to respond to state by showing/hiding points inside or outside the selection. Reactive marks re-render as the brush moves, with pointerEvents set to "none" by default so they don't obstruct interaction if they are above the brush (which achieves better contrast in general).

The brush supports geographic projections: in that case, though, the {x1, x2, y1, y2} coordinates are returned in pixel space; but the filter projects lon/lat automatically for hit-testing.

A pending flag distinguishes brushing events (user gesture) from committed selections when the brush gesture ends and the user releases the pointer. This is to allow workflows where we don't want to rerender continuously during brushing (e.g. to avoid costly calls to a database backend).

The brush has a move property that allows the selection to be modified programmatically.

Data-less 1D brushes (brushX, brushY) are supported too, with interval snapping (#2364); their aria-label is brush-x/brush-y.

Alternatives considered:

• Instead of brush.move we could imagine supporting a plot.value = {} setter. I've investigated this, and the code I came up with felt brittle. Furthermore, it seems more discoverable to use brush.move, and for advanced applications people will want to create the brush outside of Plot anyway. Another thing that this makes unclear, is what happens when the brush mark is reused. (But we can still add this later if necessary.)
• a .done instead of the .pending flag (with opposite logic); it feels equivalent, no preference.

Additional PRs:

• Support (options) - control the brush's appearance; brush(data, options) #2363
• Data-based brush — support both (options) and (data, options?) signatures; when data is passed, return filtered data as value.data. brush(data, options) #2363
• neutralize tip interaction — a mechanism to suppress tips during brushing (tip+brush combination #2361)
• cross-facet brushing & filtering — cross-facet brushing #2369 ; to be adapted after brushX and brushY #2364
• pixel precision inverse — round inverted values to the minimal precision that distinguishes half-pixels; for example: numbers as integers, dates as days. Needs a bit of research. Also we want uniform precision for linear/utc scales. pixelRound #2371

(I've made these as separate PRs to help review… but maybe it's fine to review the final boss #2370)

Ideas for related future PRs:

• Z aware interactions — per Plot PR z-aware pointer #1671; consider z option for reactive marks (this is not just for the brush interaction, but also for pointer); see Pointer, but that filters everything with a matching z value #1574 A key channel #1436 and https://observablehq.com/@observablehq/plot-pointer-driven-marks
• Intersection algorithm — support complex shapes (lines); currently only point-in-rect
• ordinal scales — support for ordinal scales (e.g., brush the “alphabet” bar chart)
• Plot.lasso — very similar to Plot.brush, maybe with a lot of shared code (see #730 for an earlier prototype).
• coincident points — Pointing at coincident points #1621

AI disclosure: I used @claude to help me generate the unit tests and maintain an action plan.

closes #5
supersedes #71
supersedes #1653
needs #2038