Merge branch 'fil/brush-dataless' into fil/brush-across-facets

# Conflicts:
#	docs/interactions/brush.md
#	src/interactions/brush.d.ts

Author: Fil

docs/interactions/brush.md

@@ -80,7 +80,7 @@ Similarly, the **brushY** mark operates on the *y* axis.
 
 ## Input events
 
-The brush dispatches an [*input* event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event) whenever the selection changes. The plot’s value (`plot.value`) is set to a [BrushValue](#brushvalue) object when a selection is active, or null when the selection is cleared. This allows you to use a plot as an [Observable view](https://observablehq.com/@observablehq/views), or to register an *input* event listener to react to the brush.
+The brush dispatches an [*input* event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event) whenever the selection changes. The plot’s value (`plot.value`) is set to a [Region](#region) instance when a selection is active, or null when the selection is cleared. This allows you to use a plot as an [Observable view](https://observablehq.com/@observablehq/views), or to register an *input* event listener to react to the brush.
 
 ```js
 const plot = Plot.plot(options);
@@ -90,32 +90,28 @@ plot.addEventListener("input", (event) => {
 });
 ```
 
-The **filter** function on the brush value tests whether a data point falls inside the selection. Its signature depends on whether the plot uses faceting, and on the brush’s dimension:
+The **contains** method on the region tests whether a data point falls inside the selection:
 
-| Facets            | 1-D brush                     | 2-D brush                      |
-|-------------------|-------------------------------|--------------------------------|
-| *none*            | *filter*(*value*)             | *filter*(*x*, *y*)             |
-| **fx** only       | *filter*(*value*, *fx*)       | *filter*(*x*, *y*, *fx*)       |
-| **fy** only       | *filter*(*value*, *fy*)       | *filter*(*x*, *y*, *fy*)       |
-| **fx** and **fy** | *filter*(*value*, *fx*, *fy*) | *filter*(*x*, *y*, *fx*, *fy*) |
+- 2-D brush: *region*.contains(*x*, *y*) or *region*.contains(*x*, *y*, {*fx*, *fy*})
+- 1-D brush: *region*.contains(*value*) or *region*.contains(*value*, {*fx*}) / *region*.contains(*value*, {*fy*})
+
+For faceted plots, you can optionally pass the facet values as an object; contains then returns true only for points in the brushed facet. For example:
 
 ```js
 plot.addEventListener("input", () => {
-  const filter = plot.value?.filter;
-  const selected = filter
-      ? penguins.filter((d) => filter(d.culmen_length_mm, d.culmen_depth_mm))
-      : penguins;
+  const region = plot.value;
+  const selected = region ? penguins.filter((d) => region.contains(d.culmen_length_mm, d.culmen_depth_mm)) : penguins;
   console.log(selected);
 });
 ```
 
-The facet arguments are optional: if *fx* or *fy* is undefined, the filter skips the facet check for that dimension. For example, if the selected region is [44, 46] × [17, 19] over the "Adelie" facet:
+The facet argument is optional: if omitted, contains skips the facet check. For example, if the selected region is [44, 46] × [17, 19] over the "Adelie" facet:
 
 ```js
-const filter = plot.value?.filter; // f(x, y, fx)
-filter(45, 18) // true
-filter(45, 18, "Adelie") // true
-filter(45, 18, "Gentoo") // false
+const {contains} = plot.value;
+contains(45, 18) // true
+contains(45, 18, {fx: "Adelie"}) // true
+contains(45, 18, {fx: "Gentoo"}) // false
 ```
 
 ## Reactive marks
@@ -159,7 +155,7 @@ To achieve higher contrast, you can place the brush before the reactive marks; r
 
 ## Faceting
 
-The brush mark supports [faceting](../features/facets.md). When the plot uses **fx** or **fy** facets, each facet gets its own brush. The dispatched value includes the **fx** and **fy** facet values of the brushed facet, and the **filter** function also filters on the relevant facet values.
+The brush mark supports [faceting](../features/facets.md). When the plot uses **fx** or **fy** facets, each facet gets its own brush. The dispatched value includes the **fx** and **fy** facet values of the brushed facet; optionally pass `{fx, fy}` as the last argument to **contains** to restrict matching to the brushed facet.
 
 :::plot hidden
 ```js
@@ -225,7 +221,7 @@ The dispatched value still includes **fx** (and **fy**), indicating the facet wh
 
 ## Projections
 
-For plots with a [geographic projection](../features/projections.md), the brush operates in screen space. The brush value’s **x1**, **y1**, **x2**, **y2** bounds are expressed in pixels from the top-left corner of the frame, and the **filter** function takes the data's coordinates (typically longitude and latitude) and projects them to test against the brush extent.
+For plots with a [geographic projection](../features/projections.md), the brush operates in screen space. The brush value’s **x1**, **y1**, **x2**, **y2** bounds are expressed in pixels from the top-left corner of the frame. Use **contains** with pixel coordinates to test against the brush extent.
 
 <div v-if="land && cities.length">
 
@@ -262,17 +258,17 @@ Plot.plot({
 })
 ```
 
-## BrushValue {#brushvalue}
+## Region {#region}
 
-The brush value dispatched on [_input_ events](#input-events). When the brush is cleared, the value is null; otherwise it's an object with the following properties:
+The brush value dispatched on [_input_ events](#input-events). When the brush is cleared, the value is null; otherwise it's a `Region` instance with the following properties:
 
 - **x1** - the lower *x* bound of the selection (in data space, or pixels if projected)
 - **x2** - the upper *x* bound of the selection
 - **y1** - the lower *y* bound of the selection
 - **y2** - the upper *y* bound of the selection
 - **fx** - the *fx* facet value, if applicable
 - **fy** - the *fy* facet value, if applicable
-- **filter** - a function to test whether a point is inside the selection
+- **contains** - a method to test whether a point is inside the selection; see [input events](#input-events)
 - **pending** - `true` during interaction; absent when committed
 
 By convention, *x1* < *x2* and *y1* < *y2*. The brushX value does not include *y1* and *y2*; similarly, the brushY value does not include *x1* and *x2*. Values are automatically rounded to the optimal precision that distinguishes neighboring pixels.
@@ -342,7 +338,7 @@ brush.move({x1: 40, x2: 52, y1: 15, y2: 20, fx: "Chinstrap"})
 brush.move(null)
 ```
 
-For projected plots, the coordinates are in pixels (consistent with the [BrushValue](#brushvalue)), so you need to project the two corners of the brush beforehand. In the future Plot might expose its *projection* to facilitate this. Please upvote [this issue](https://github.com/observablehq/plot/issues/1191) to help prioritize this feature.
+For projected plots, the coordinates are in pixels (consistent with the [Region](#region)), so you need to project the two corners of the brush beforehand. In the future Plot might expose its *projection* to facilitate this. Please upvote [this issue](https://github.com/observablehq/plot/issues/1191) to help prioritize this feature.
 
 ## brushX(*options*) {#brushX}
 
@@ -354,7 +350,7 @@ Returns a new horizontal brush mark that selects along the *x* axis. The availab
 
 - **interval** - an interval to snap the brush to on release; a number for quantitative scales (_e.g._, `100`), a time interval name for temporal scales (_e.g._, `"month"`), or an object with *floor* and *offset* methods
 
-When an **interval** is set, the selection snaps to interval boundaries on release, and the filter rounds values before testing, for consistency with binned marks using the same interval. (Use the same interval in the bin transform so the brush aligns with bin edges.)
+When an **interval** is set, the selection snaps to interval boundaries on release. (Use the same interval in the bin transform so the brush aligns with bin edges.)
 
 :::plot defer hidden
 ```js

src/index.js

@@ -53,7 +53,7 @@ export {window, windowX, windowY} from "./transforms/window.js";
 export {select, selectFirst, selectLast, selectMaxX, selectMaxY, selectMinX, selectMinY} from "./transforms/select.js";
 export {stackX, stackX1, stackX2, stackY, stackY1, stackY2} from "./transforms/stack.js";
 export {treeNode, treeLink} from "./transforms/tree.js";
-export {Brush, brush, brushX, brushY} from "./interactions/brush.js";
+export {Brush, Region, brush, brushX, brushY} from "./interactions/brush.js";
 export {pointer, pointerX, pointerY} from "./interactions/pointer.js";
 export {formatIsoDate, formatNumber, formatWeekday, formatMonth} from "./format.js";
 export {scale} from "./scales.js";

src/interactions/brush.d.ts

@@ -4,11 +4,12 @@ import type {Rendered} from "../transforms/basic.js";
 
 /**
  * The brush value dispatched on input events. When the brush is cleared, the
- * value is null; otherwise it contains the selection bounds (in data space,
- * or pixels if projected) and a filter function to test whether a data point
- * is inside the brush. By convention *x1* < *x2* and *y1* < *y2*.
+ * value is null; otherwise it is a Region containing the selection bounds (in
+ * data space, or pixels if the plot has a projection) and methods to test
+ * whether a data point is inside the brush. By convention *x1* < *x2* and
+ * *y1* < *y2*.
  */
-export interface BrushValue {
+export class Region {
   /** The lower *x* value of the brushed region. */
   x1?: number | Date;
   /** The upper *x* value of the brushed region. */
@@ -21,18 +22,18 @@ export interface BrushValue {
   fx?: any;
   /** The *fy* facet value, if applicable. */
   fy?: any;
-  /**
-   * A function to test whether a point falls inside the brush selection.
-   * The signature depends on the dimensions and active facets: for brushX
-   * and brushY, filter on the value *v* with *(v)*, *(v, fx)*, *(v, fy)*,
-   * or *(v, fx, fy)*  *(x, y)*; for a 2D brush, use *(x, y)*, *(x, y, fx)*,
-   * *(x, y, fy)*, or *(x, y, fx, fy)*. When faceted, returns true only for
-   * points in the brushed facet. For projected plots, *x* and *y* are
-   * typically longitude and latitude.
-   */
-  filter: (...args: any[]) => boolean;
   /** True during interaction, absent when committed. */
   pending?: true;
+
+  /**
+   * Tests whether a point falls inside the brush selection.
+   *
+   * For a 2-D brush, pass (x, y) or (x, y, {fx, fy}) for faceted plots.
+   * For a 1-D brush (brushX or brushY), pass (value) or (value, {fx, fy}).
+   * The facet argument is optional; if specified, returns true only for points
+   * in the brushed facet.
+   */
+  contains(x: any, y?: any, facets?: {fx?: any; fy?: any}): boolean;
 }
 
 /** Options for the brush mark. */
@@ -57,7 +58,7 @@ export interface BrushOptions {
  * selections when a new brush starts.
  *
  * The brush dispatches an input event when the selection changes. The selection
- * is available as plot.value as a **BrushValue**, or null when the selection is
+ * is available as plot.value as a **Region**, or null when the selection is
  * cleared. Use the **inactive**, **context**, and **focus** methods to create
  * reactive marks that respond to the brush state.
  */

src/interactions/brush.js

@@ -12,6 +12,37 @@ import {composeRender, Mark} from "../mark.js";
 import {constant, keyword, maybeInterval} from "../options.js";
 import {pixelRound} from "../precision.js";
 
+export class Region {
+  constructor({x1, x2, y1, y2, fx, fy, pending} = {}) {
+    if (x1 !== undefined) this.x1 = x1;
+    if (x2 !== undefined) this.x2 = x2;
+    if (y1 !== undefined) this.y1 = y1;
+    if (y2 !== undefined) this.y2 = y2;
+    if (fx !== undefined) this.fx = fx;
+    if (fy !== undefined) this.fy = fy;
+    if (pending !== undefined) this.pending = pending;
+  }
+  contains(x, y, facets) {
+    if (this.x1 === undefined || this.y1 === undefined) {
+      // 1D: second arg is facets
+      facets = y;
+      if (this.x1 === undefined) {
+        y = x;
+        x = undefined;
+      } else {
+        y = undefined;
+      }
+    }
+    if (x !== undefined && !(this.x1 <= x && x <= this.x2)) return false;
+    if (y !== undefined && !(this.y1 <= y && y <= this.y2)) return false;
+    if (facets) {
+      if ("fx" in facets && "fx" in this && facets.fx !== this.fx) return false;
+      if ("fy" in facets && "fy" in this && facets.fy !== this.fy) return false;
+    }
+    return true;
+  }
+}
+
 export class Brush extends Mark {
   constructor({dimension = "xy", interval, sync = false} = {}) {
     super(undefined, {}, {}, {});
@@ -91,15 +122,13 @@ export class Brush extends Mark {
               if (event.sourceEvent) {
                 const [px, py] = pointer(event, this);
                 const facet = target?.__data__;
-                const filter = filterFromBrush(dim, interval, x, y, facet, context.projection, px, px, py, py);
-                value = {
+                value = new Region({
                   ...(dim !== "y" && {x1: invertX(px), x2: invertX(px)}),
                   ...(dim !== "x" && {y1: invertY(py), y2: invertY(py)}),
                   ...(fx && facet && {fx: facet.x}),
                   ...(fy && facet && {fy: facet.y}),
-                  filter,
                   pending: true
-                };
+                });
               }
               context.dispatchValue(value);
             }
@@ -136,15 +165,15 @@ export class Brush extends Mark {
             }
 
             const facet = target?.__data__;
-            const filter = filterFromBrush(dim, interval, x, y, facet, context.projection, px1, px2, py1, py2);
-            context.dispatchValue({
-              ...(dim !== "y" && {x1, x2}),
-              ...(dim !== "x" && {y1, y2}),
-              ...(fx && facet && {fx: facet.x}),
-              ...(fy && facet && {fy: facet.y}),
-              filter,
-              ...(type !== "end" && {pending: true})
-            });
+            context.dispatchValue(
+              new Region({
+                ...(dim !== "y" && {x1, x2}),
+                ...(dim !== "x" && {y1, y2}),
+                ...(fx && facet && {fx: facet.x}),
+                ...(fy && facet && {fy: facet.y}),
+                ...(type !== "end" && {pending: true})
+              })
+            );
           }
         });
     }
@@ -193,57 +222,6 @@ export function brushY({interval} = {}) {
   return new Brush({dimension: "y", interval});
 }
 
-function filterFromBrush(dim, interval, xScale, yScale, facet, projection, px1, px2, py1, py2) {
-  switch (dim) {
-    case "x":
-    case "y": {
-      const floor = interval ? (d) => interval.floor(d) : (d) => d;
-      const [scale, pv1, pv2] = dim === "x" ? [xScale, px1, px2] : [yScale, py1, py2];
-      let p;
-      return filterSignature1D((d) => ((p = scale(floor(d))), pv1 <= p && p < pv2), facet?.x, facet?.y);
-    }
-    case "xy": {
-      let px, py;
-      const stream = projection?.stream({
-        point(x, y) {
-          px = x;
-          py = y;
-        }
-      }) ?? {
-        point: (x, y) => {
-          px = xScale(x);
-          py = yScale(y);
-        }
-      };
-      return filterSignature2D(
-        (dx, dy) => (stream.point(dx, dy), px1 <= px && px < px2 && py1 <= py && py < py2),
-        facet?.x,
-        facet?.y
-      );
-    }
-  }
-}
-
-function filterSignature2D(test, currentFx, currentFy) {
-  return currentFx === undefined
-    ? currentFy === undefined
-      ? (x, y) => test(x, y)
-      : (x, y, fy) => (fy === undefined || fy === currentFy) && test(x, y)
-    : currentFy === undefined
-    ? (x, y, fx) => (fx === undefined || fx === currentFx) && test(x, y)
-    : (x, y, fx, fy) => (fx === undefined || fx === currentFx) && (fy === undefined || fy === currentFy) && test(x, y);
-}
-
-function filterSignature1D(test, currentFx, currentFy) {
-  return currentFx === undefined
-    ? currentFy === undefined
-      ? (v) => test(v)
-      : (v, fy) => (fy === undefined || fy === currentFy) && test(v)
-    : currentFy === undefined
-    ? (v, fx) => (fx === undefined || fx === currentFx) && test(v)
-    : (v, fx, fy) => (fx === undefined || fx === currentFx) && (fy === undefined || fy === currentFy) && test(v);
-}
-
 function intervalRound(interval, v) {
   const lo = interval.floor(v);
   const hi = interval.offset(lo);

test/brush-test.ts

@@ -74,10 +74,10 @@ it("brush dispatches value on programmatic brush move", async () => {
   const lastValue = values[values.length - 1];
   assert.ok(lastValue, "last value should not be null");
   assert.ok(!("pending" in lastValue), "committed value should not be pending");
-  assert.ok(typeof lastValue.filter === "function", "value should have a filter function");
+  assert.ok(typeof lastValue.contains === "function", "value should have a contains method");
 
   // Check filtered elements
-  const filtered = data.filter((d) => lastValue.filter(d.x, d.y));
+  const filtered = data.filter((d) => lastValue.contains(d.x, d.y));
   assert.ok(filtered.length > 0, "should have filtered some elements");
   assert.ok(filtered.length < data.length, "should not include all elements");
 });
@@ -106,7 +106,7 @@ it("brush faceted filter restricts to the brushed facet", async () => {
 
   // Filter WITH facet (correct)
   const filteredWithFacet = penguins.filter((d: any) =>
-    lastValue.filter(d.culmen_length_mm, d.culmen_depth_mm, d.species)
+    lastValue.contains(d.culmen_length_mm, d.culmen_depth_mm, {fx: d.species})
   );
 
   // Filter mistakenly WITHOUT facet
@@ -127,6 +127,12 @@ it("brush faceted filter restricts to the brushed facet", async () => {
   // All filtered points should belong to a single species
   const species = new Set(filteredWithFacet.map((d: any) => d.species));
   assert.equal(species.size, 1, `all filtered points should be one species, got: ${[...species]}`);
+
+  // Passing {fx: undefined} should match no points, since undefined !== "Adelie"
+  const filteredUndefinedFacet = penguins.filter((d: any) =>
+    lastValue.contains(d.culmen_length_mm, d.culmen_depth_mm, {fx: undefined})
+  );
+  assert.equal(filteredUndefinedFacet.length, 0, "fx: undefined should match no points");
 });
 
 it("brush programmatic move on second facet selects the correct facet", async () => {
@@ -152,7 +158,9 @@ it("brush programmatic move on second facet selects the correct facet", async ()
   assert.ok(lastValue.fx !== undefined, "value should include fx");
   assert.equal(lastValue.fx, "Chinstrap", "fx should be Chinstrap (the second facet)");
 
-  const filtered = penguins.filter((d: any) => lastValue.filter(d.culmen_length_mm, d.culmen_depth_mm, d.species));
+  const filtered = penguins.filter((d: any) =>
+    lastValue.contains(d.culmen_length_mm, d.culmen_depth_mm, {fx: d.species})
+  );
   assert.ok(filtered.length > 0, "should select some points");
 
   const species = new Set(filtered.map((d: any) => d.species));
@@ -321,10 +329,10 @@ it("brushX value has x1/x2 but no y1/y2", async () => {
   assert.ok("x2" in lastValue, "value should have x2");
   assert.ok(!("y1" in lastValue), "value should not have y1");
   assert.ok(!("y2" in lastValue), "value should not have y2");
-  assert.ok(typeof lastValue.filter === "function", "value should have a filter function");
+  assert.ok(typeof lastValue.contains === "function", "value should have a contains method");
 
-  // 1D filter takes a single argument
-  const filtered = data.filter((d) => lastValue.filter(d.x));
+  // 1D contains takes a single argument
+  const filtered = data.filter((d) => lastValue.contains(d.x));
   assert.ok(filtered.length > 0, "should select some points");
   assert.ok(filtered.length < data.length, "should not include all points");
 });
@@ -359,10 +367,10 @@ it("brushY value has y1/y2 but no x1/x2", async () => {
   assert.ok("y2" in lastValue, "value should have y2");
   assert.ok(!("x1" in lastValue), "value should not have x1");
   assert.ok(!("x2" in lastValue), "value should not have x2");
-  assert.ok(typeof lastValue.filter === "function", "value should have a filter function");
+  assert.ok(typeof lastValue.contains === "function", "value should have a contains method");
 
-  // 1D filter takes a single argument
-  const filtered = data.filter((d) => lastValue.filter(d.y));
+  // 1D contains takes a single argument
+  const filtered = data.filter((d) => lastValue.contains(d.y));
   assert.ok(filtered.length > 0, "should select some points");
   assert.ok(filtered.length < data.length, "should not include all points");
 });