Refine documentation on selection clearing.

examples/specs/selection_clear_brush.vl.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://vega.github.io/schema/vega-lite/v3.json",
+  "data": {"url": "data/cars.json"},
+  "selection": {
+    "brush": {
+      "type": "interval",
+      "init": {"x": [55, 160], "y": [13, 37]},
+      "clear": "mouseup"
+    }
+  },
+  "mark": "point",
+  "encoding": {
+    "x": {"field": "Horsepower", "type": "quantitative"},
+    "y": {"field": "Miles_per_Gallon", "type": "quantitative"},
+    "color": {
+      "condition": {"selection": "brush", "field": "Cylinders", "type": "ordinal"},
+      "value": "grey"
+    }
+  }
+}

examples/specs/selection_clear_heatmap.vl.json

@@ -0,0 +1,52 @@
+{
+  "data": {
+    "values": [
+      {"actual": "A", "predicted": "A", "count": 13},
+      {"actual": "A", "predicted": "B", "count": 0},
+      {"actual": "A", "predicted": "C", "count": 0},
+      {"actual": "B", "predicted": "A", "count": 0},
+      {"actual": "B", "predicted": "B", "count": 10},
+      {"actual": "B", "predicted": "C", "count": 6},
+      {"actual": "C", "predicted": "A", "count": 0},
+      {"actual": "C", "predicted": "B", "count": 0},
+      {"actual": "C", "predicted": "C", "count": 9}
+    ]
+  },
+  "selection": {
+    "highlight": {"type": "single"}
+  },
+  "mark": "bar",
+  "encoding": {
+    "y": {
+      "field": "actual",
+      "type": "nominal"
+    },
+    "x": {
+      "field": "predicted",
+      "type": "nominal"
+    },
+    "color": {
+      "field": "count",
+      "type": "quantitative",
+      "scale": {"scheme": "plasma"}
+    },
+    "fillOpacity": {
+      "condition": {"selection": "highlight", "value": 1},
+      "value": 0.5
+    }
+  },
+  "config": {
+    "axis": {
+      "zindex": 0
+    },
+    "scale": {
+      "bandPaddingInner": 0,
+      "bandPaddingOuter": 0
+    },
+    "range": {
+      "ramp": {
+        "scheme": "yellowgreenblue"
+      }
+    }
+  }
+}

examples/specs/selection_type_single_mouseover.vl.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://vega.github.io/schema/vega-lite/v3.json",
+  "data": {"url": "data/cars.json"},
+  "selection": {
+    "pts": {"type": "single", "on": "mouseover"}
+  },
+  "mark": "rect",
+  "encoding": {
+    "y": {"field": "Origin", "type": "ordinal"},
+    "x": {"field": "Cylinders", "type": "ordinal"},
+    "color": {
+      "condition": {
+        "selection": "pts",
+        "aggregate": "count", "type": "quantitative"
+      },
+      "value": "grey"
+    }
+  }
+}

site/docs/selection/clear.md

@@ -5,24 +5,25 @@ title: Clearing a selection
 permalink: /docs/clear.html
 ---
 
-The `clear` selection transformation clears all selections made on the visualization:
-
-- For `single` and `multi` selections, it will clear all selected values.
-- For `interval` selections, it will clear all selected values and return the visualization to its original scale domain.
+The `clear` property identifies which events must fire to empty a selection of all selected values (the [`empty`](https://vega.github.io/vega-lite/docs/selection.html#selection-properties) can be used to further determine the behavior of empty selections).
 
 It can take one of the following values:
 
-- `false` -- disables clear behavior; there will be no trigger that resets the visualization to its initial configuration.
-- A [Vega event stream definition](https://vega.github.io/vega/docs/event-streams/) to indicate which events should trigger clearing of the visualization.
+- `false` -- disables clear behavior; there will be no event trigger that empties a selection.
+- A [Vega event stream definition](https://vega.github.io/vega/docs/event-streams/) to indicate which events should trigger clearing the selection.
 
-Vega-Lite automatically adds a clear transform to all selections by default. The default is `clear: mouseout` if you're `on: mouseover`, else `clear: dblclick`.
+Vega-Lite automatically adds the clear property to all selections by default. If the selection is triggered by mouse hovers (i.e., `"on": "mouseover"), then`"clear": "mouseout"`is used. For all other selection triggers,`"clear": "dblclick"` is used.
 
 ## Examples
 
-Mousing out of the visualization will clear your highlighted value.
+The following visualization demonstrates the default clearing behavior: select a square on click and clear out the selection on double click.
+
+<div class="vl-example" data-name="selection_clear_heatmap"></div>
+
+The following example clears the brush when the mouse button is released.
 
-<div id="paintbrush_nearest_clear" class="vl-example" data-name="interactive_stocks_nearest_index"></div>
+<div class="vl-example" data-name="selection_clear_brush"></div>
 
-Click and drag to shift the current position of the scales, then double click to reset the scales to their initial configuration.
+Note, in the above example, clearing out the selection does _not_ reset it to its initial value. Instead, when the mouse button is released, the selection is emptied of all values. This behavior is subtly different to when the selection is [bound to scales](https://vega.github.io/vega-lite/docs/bind.html#scale-binding) -- clearing the selection out now resets the view to use the initial scale domains. Try it out below: pan and zoom the plot, and then double click.
 
-<div id="selection_resolution_clear" class="vl-example" data-name="selection_resolution_global"></div>
+<div class="vl-example" data-name="selection_translate_scatterplot_drag"></div>

site/docs/selection/selection.md

@@ -57,9 +57,9 @@ While selection types provide useful defaults, it can often be useful to overrid
 
 {% include table.html props="on,init,empty,resolve,mark" source="IntervalSelection" %}
 
-For instance, with the `on` property, a single rectangle in the heatmap below can now be selected on double-click instead.
+For instance, with the `on` property, a single rectangle in the heatmap below can now be selected on mouse hover instead.
 
-<div class="vl-example" data-name="selection_type_single_dblclick"></div>
+<div class="vl-example" data-name="selection_type_single_mouseover"></div>
 
 {:#interval-mark}
 

src/selection.ts

@@ -50,16 +50,16 @@ export interface BaseSelectionDef {
   fields?: string[];
 
   /**
-   * By default, all data values are considered to lie within an empty selection.
+   * By default, `all` data values are considered to lie within an empty selection.
    * When set to `none`, empty selections contain no data values.
    */
   empty?: 'all' | 'none';
 }
 
 export interface SingleSelectionConfig extends BaseSelectionDef {
   /**
-   * Controls clearing selections. Clears all selected values. Can be an
-   * [EventStream](https://vega.github.io/vega/docs/event-streams/) or `false`.
+   * Clears the selection, emptying it of all values. Can be an
+   * [EventStream](https://vega.github.io/vega/docs/event-streams/) or `false` to disable.
    *
    * __Default value:__ `mouseout` if `on: mouseover` else `dblclick`.
    *
@@ -92,8 +92,8 @@ export interface SingleSelectionConfig extends BaseSelectionDef {
 
 export interface MultiSelectionConfig extends BaseSelectionDef {
   /**
-   * Controls clearing selections. Clears all selected values. Can be an
-   * [EventStream](https://vega.github.io/vega/docs/event-streams/) or `false`.
+   * Clears the selection, emptying it of all values. Can be an
+   * [EventStream](https://vega.github.io/vega/docs/event-streams/) or `false` to disable.
    *
    * __Default value:__ `mouseout` if `on: mouseover` else `dblclick`.
    *
@@ -169,9 +169,8 @@ export interface BrushConfig {
 
 export interface IntervalSelectionConfig extends BaseSelectionDef {
   /**
-   * Controls clearing selections. Clears all selected values and returns the visualization
-   * to its original scale domains. Can be an
-   * [EventStream](https://vega.github.io/vega/docs/event-streams/) or `false`.
+   * Clears the selection, emptying it of all values. Can be an
+   * [EventStream](https://vega.github.io/vega/docs/event-streams/) or `false` to disable.
    *
    * __Default value:__ `mouseout` if `on: mouseover` else `dblclick`.
    *