brush, pointer

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Observable Plot - Changelog
 
+## 0.4.2
+
+*Not yet released. These are forthcoming changes in the main branch.*
+
+Plot now supports [interaction marks](./README.md#interactions)! An interaction mark defines an interactive selection represented as a subset of the mark’s data. For example, the [brush mark](./README.md#brush) allows rectangular selection by clicking and dragging; you can use a brush to select points of interest from a scatterplot and show them in a table. The interactive selection is exposed as *plot*.value. When the selection changes during interaction, the plot emits *input* events. This allows plots to be [Observable views](https://observablehq.com/@observablehq/introduction-to-views), but you can also [listen to *input* events](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget) directly.
+
 ## 0.4.1
 
 Released February 17, 2022.

README.md

@@ -1227,6 +1227,38 @@ Plot.vector(wind, {x: "longitude", y: "latitude", length: "speed", rotate: "dire
 
 Returns a new vector with the given *data* and *options*. If neither the **x** nor **y** options are specified, *data* is assumed to be an array of pairs [[*x₀*, *y₀*], [*x₁*, *y₁*], [*x₂*, *y₂*], …] such that **x** = [*x₀*, *x₁*, *x₂*, …] and **y** = [*y₀*, *y₁*, *y₂*, …].
 
+## Interactions
+
+Interactions are special marks that handle user input and define interactive selections. When a plot has an interaction mark, the returned *plot*.value represents the current selection as an array subset of the interaction mark’s data. As the user modifies the selection through interaction with the plot, *input* events are emitted. This design is compatible with [Observable’s viewof operator](https://observablehq.com/@observablehq/introduction-to-views), but you can also listen to *input* events directly via the [EventTarget interface](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget).
+
+### Brush
+
+[Source](./src/marks/brush.js) · [Examples](https://observablehq.com/@observablehq/plot-brush) · Selects points within a single contiguous rectangular region, such as nearby dots in a scatterplot.
+
+#### Plot.brush(*data*, *options*)
+
+```js
+Plot.brush(penguins, {x: "culmen_depth_mm", y: "culmen_length_mm"})
+```
+
+Returns a new brush with the given *data* and *options*. If neither the **x** nor **y** options are specified, *data* is assumed to be an array of pairs [[*x₀*, *y₀*], [*x₁*, *y₁*], [*x₂*, *y₂*], …] such that **x** = [*x₀*, *x₁*, *x₂*, …] and **y** = [*y₀*, *y₁*, *y₂*, …].
+
+#### Plot.brushX(*data*, *options*)
+
+```js
+Plot.brushX(penguins, {x: "culmen_depth_mm"})
+```
+
+Equivalent to [Plot.brush](#plotbrushdata-options) except that if the **x** option is not specified, it defaults to the identity function and assumes that *data* = [*x₀*, *x₁*, *x₂*, …].
+
+#### Plot.brushY(*data*, *options*)
+
+```js
+Plot.brushY(penguins, {y: "culmen_length_mm"})
+```
+
+Equivalent to [Plot.brush](#plotbrushdata-options) except that if the **y** option is not specified, it defaults to the identity function and assumes that *data* = [*y₀*, *y₁*, *y₂*, …].
+
 ## Decorations
 
 Decorations are static marks that do not represent data. Currently this includes only [Plot.frame](#frame), although internally Plot’s axes are implemented as decorations and may in the future be exposed here for more flexible configuration.

src/index.js

@@ -3,17 +3,20 @@ export {Area, area, areaX, areaY} from "./marks/area.js";
 export {Arrow, arrow} from "./marks/arrow.js";
 export {BarX, BarY, barX, barY} from "./marks/bar.js";
 export {boxX, boxY} from "./marks/box.js";
+export {Brush, brush, brushX, brushY} from "./marks/brush.js";
 export {Cell, cell, cellX, cellY} from "./marks/cell.js";
 export {Dot, dot, dotX, dotY} from "./marks/dot.js";
 export {Frame, frame} from "./marks/frame.js";
 export {Image, image} from "./marks/image.js";
 export {Line, line, lineX, lineY} from "./marks/line.js";
 export {Link, link} from "./marks/link.js";
+export {Pointer, pointer, pointerX, pointerY} from "./marks/pointer.js";
 export {Rect, rect, rectX, rectY} from "./marks/rect.js";
 export {RuleX, RuleY, ruleX, ruleY} from "./marks/rule.js";
 export {Text, text, textX, textY} from "./marks/text.js";
 export {TickX, TickY, tickX, tickY} from "./marks/tick.js";
 export {Vector, vector} from "./marks/vector.js";
+export {selection} from "./selection.js";
 export {valueof} from "./options.js";
 export {filter, reverse, sort, shuffle} from "./transforms/basic.js";
 export {bin, binX, binY} from "./transforms/bin.js";

src/marks/brush.js

@@ -0,0 +1,87 @@
+import {brush as brusher, brushX as brusherX, brushY as brusherY, create, select} from "d3";
+import {identity, maybeTuple} from "../options.js";
+import {Mark} from "../plot.js";
+import {selection, selectionEquals} from "../selection.js";
+import {applyDirectStyles, applyIndirectStyles} from "../style.js";
+
+const defaults = {
+  ariaLabel: "brush",
+  fill: "#777",
+  fillOpacity: 0.3,
+  stroke: "#fff"
+};
+
+export class Brush extends Mark {
+  constructor(data, {x, y, ...options} = {}) {
+    super(
+      data,
+      [
+        {name: "x", value: x, scale: "x", optional: true},
+        {name: "y", value: y, scale: "y", optional: true}
+      ],
+      options,
+      defaults
+    );
+    this.activeElement = null;
+  }
+  render(index, {x, y}, {x: X, y: Y}, dimensions) {
+    const {ariaLabel, ariaDescription, ariaHidden, ...options} = this;
+    const {marginLeft, width, marginRight, marginTop, height, marginBottom} = dimensions;
+    const brush = this;
+    const g = create("svg:g")
+        .call(applyIndirectStyles, {ariaLabel, ariaDescription, ariaHidden}, dimensions)
+        .call((X && Y ? brusher : X ? brusherX : brusherY)()
+          .extent([[marginLeft, marginTop], [width - marginRight, height - marginBottom]])
+          .on("start brush end", function(event) {
+            const {type, selection: extent} = event;
+            // For faceting, when starting a brush in a new facet, clear the
+            // brush and selection on the old facet. In the future, we might
+            // allow independent brushes across facets by disabling this?
+            if (type === "start" && brush.activeElement !== this) {
+              if (brush.activeElement !== null) {
+                select(brush.activeElement).call(event.target.clear, event);
+                brush.activeElement[selection] = null;
+              }
+              brush.activeElement = this;
+            }
+            let S = null;
+            if (extent) {
+              S = index;
+              if (X) {
+                let [x0, x1] = Y ? [extent[0][0], extent[1][0]] : extent;
+                if (x.bandwidth) x0 -= x.bandwidth();
+                S = S.filter(i => x0 <= X[i] && X[i] <= x1);
+              }
+              if (Y) {
+                let [y0, y1] = X ? [extent[0][1], extent[1][1]] : extent;
+                if (y.bandwidth) y0 -= y.bandwidth();
+                S = S.filter(i => y0 <= Y[i] && Y[i] <= y1);
+              }
+            }
+            if (!selectionEquals(this[selection], S)) {
+              this[selection] = S;
+              this.dispatchEvent(new Event("input", {bubbles: true}));
+            }
+          }))
+        .call(g => g.selectAll(".selection")
+          .attr("shape-rendering", null) // reset d3-brush
+          .call(applyIndirectStyles, options, dimensions)
+          .call(applyDirectStyles, options))
+      .node();
+    g[selection] = null;
+    return g;
+  }
+}
+
+export function brush(data, {x, y, ...options} = {}) {
+  ([x, y] = maybeTuple(x, y));
+  return new Brush(data, {...options, x, y});
+}
+
+export function brushX(data, {x = identity, ...options} = {}) {
+  return new Brush(data, {...options, x});
+}
+
+export function brushY(data, {y = identity, ...options} = {}) {
+  return new Brush(data, {...options, y});
+}