debounce the turnOn callback

NEWS.md

@@ -2,14 +2,15 @@
 
 ## NEW FEATURES & IMPROVEMENTS
 
-* Upgraded to plotly.js v1.38.1. A _huge_ amount of features and improvements have been made since v1.29.2 (i.e., the version included in the last CRAN release of the R package - v4.7.1). Highlights include a complete re-write of `scattergl` to make it nearly feature complete with `scatter`, localization of text rendering (i.e., international translations), and two new trace types (`violin` & `table`). Read more about the v1.32.0 release [here](https://codeburst.io/notes-from-the-latest-plotly-js-release-b035a5b43e21) and the complete list of changes [here](https://github.com/plotly/plotly.js/releases).
+* Upgraded to plotly.js v1.38.2. A _huge_ amount of features and improvements have been made since v1.29.2 (i.e., the version included in the last CRAN release of the R package - v4.7.1). Highlights include a complete re-write of `scattergl` to make it nearly feature complete with `scatter`, localization of text rendering (i.e., international translations), and two new trace types (`violin` & `table`). Read more about the v1.32.0 release [here](https://codeburst.io/notes-from-the-latest-plotly-js-release-b035a5b43e21) and the complete list of changes [here](https://github.com/plotly/plotly.js/releases).
 * Support for **sf** (simple feature) data structures was added to `plot_ly()`, `plot_mapbox()`, and `plot_geo()` (via the new `add_sf()` function). See [this blog post](https://blog.cpsievert.me/2018/03/30/visualizing-geo-spatial-data-with-sf-and-plotly) for an overview.
 * New "special arguments" `stroke`, `strokes`, `alpha_stroke`, `span`, and `spans` were added for easier control over the stroke (i.e., outline) appearance of various (filled) graphical marks. For an overview, see the **sf** blog post linked to in the bullet point above and the new package demos (list all demos with `demo(package = "plotly")`).
-* The selection (i.e., linked-brushing) mode can now switch from 'transient' to 'persistent' by holding the 'shift' key. It's still possible to _force_ persistent selection by setting `persistent = TRUE` in `highlight()`, but `persistent = FALSE` (the default) is now recommended since it allows one to switch between [persistent/transient selection](https://plotly-book.cpsievert.me/linking-views-without-shiny.html#transient-versus-persistent-selection) in the browser, rather than at the command line.
 * The new `partial_bundle()` function makes it easy to leverage [partial bundles of plotly.js](https://github.com/plotly/plotly.js#partial-bundles) for reduced file sizes and faster render times.
 * The `config()` function gains a `locale` argument for easily changing localization defaults (see #1270). This makes it possible localize date axes, and in some cases, modebar buttons (see #1270)
 * One may now inform `ggplotly()` about the relevant **shiny** output size via `session$clientData`. This ensures `ggplotly()` sizing is closer to **ggplot2** sizing, even on window resize. For an example, run `plotly_example("shiny", "ggplotly_sizing")`.
 * Instead of an error, `ggplotly(NULL, "message")` and `plotly_build(NULL, "message")` now returns `htmltools::div("message")`, making it easier to relay messages in shiny when data isn't yet ready to plot (see #1116)
+* The selection (i.e., linked-brushing) mode can now switch from 'transient' to 'persistent' by holding the 'shift' key. It's still possible to _force_ persistent selection by setting `persistent = TRUE` in `highlight()`, but `persistent = FALSE` (the default) is now recommended since it allows one to switch between [persistent/transient selection](https://plotly-book.cpsievert.me/linking-views-without-shiny.html#transient-versus-persistent-selection) in the browser, rather than at the command line.
+* The `highlight()` function gains a `debounce` argument for throttling the rate at which `on` events may be fired. This is mainly useful for improving user experience when `highlight(on = "plotly_hover")` and mousing over relevant markers at a rapid rate (see #1277)
 * The `animation_button()` function gains a `label` argument, making it easier to control the label of an animation button generated through the `frame` API (see #1205).
 
 ## CHANGES

R/highlight.R

@@ -43,6 +43,9 @@
 #' @param opacityDim a number between 0 and 1 used to reduce the
 #' opacity of non-selected traces (by multiplying with the existing opacity).
 #' @param selected attributes of the selection, see [attrs_selected()].
+#' @param debounce amount of time to wait before firing an event (in milliseconds). 
+#' This is especially useful when `on = "plotly_hover"` to avoid firing too many events
+#' when users clickly move the mouse over relevant graphical marks.
 #' @param ... currently not supported.
 #' @export
 #' @author Carson Sievert
@@ -80,7 +83,8 @@ highlight <- function(p, on = "plotly_click", off,
                       dynamic = FALSE, color = NULL,
                       selectize = FALSE, defaultValues = NULL,
                       opacityDim = getOption("opacityDim", 0.2), 
-                      selected = attrs_selected(), ...) {
+                      selected = attrs_selected(), debounce = 1,
+                      ...) {
 
   # currently ... is not-supported and will catch 
   # some arguments we supported at one point 
@@ -154,7 +158,8 @@ highlight <- function(p, on = "plotly_click", off,
     selectize = selectize,
     defaultValues = defaultValues,
     opacityDim = opacityDim,
-    selected = selected
+    selected = selected,
+    debounce = debounce
   )
 
   p

R/plotly.R

@@ -424,7 +424,8 @@ typedArrayPolyfill <- function() {
 # and bundle size at print time.
 plotlyMainBundle <- function() {
   htmltools::htmlDependency(
-    "plotly-main", "1.38.1",
+    "plotly-main", 
+    version = "1.38.2",
     src = depPath("plotlyjs"),
     script = "plotly-latest.min.js",
     all_files = FALSE
@@ -433,7 +434,8 @@ plotlyMainBundle <- function() {
 
 plotlyHtmlwidgetsCSS <- function() {
   htmltools::htmlDependency(
-    "plotly-htmlwidgets-css", "1.38.1",
+    "plotly-htmlwidgets-css", 
+    version = plotlyMainBundle()$version,
     src = depPath("plotlyjs"),
     stylesheet = "plotly-htmlwidgets.css",
     all_files = FALSE

inst/htmlwidgets/plotly.js

@@ -460,7 +460,7 @@ HTMLWidgets.widget({
       selection.on("change", selectionChange);
 
       // Set a crosstalk variable selection value, triggering an update
-      graphDiv.on(x.highlight.on, function turnOn(e) {
+      var turnOn = function(e) {
         if (e) {
           var selectedKeys = pointsToKeys(e.points);
           // Keys are group names, values are array of selected keys from group.
@@ -470,7 +470,9 @@ HTMLWidgets.widget({
             }
           }
         }
-      });
+      };
+
+      graphDiv.on(x.highlight.on, debounce(turnOn, x.highlight.debounce));
 
       graphDiv.on(x.highlight.off, function turnOff(e) {
         // remove any visual clues
@@ -878,3 +880,25 @@ function removeBrush(el) {
     outlines[i].remove();
   }
 }
+
+
+// https://davidwalsh.name/javascript-debounce-function
+
+// Returns a function, that, as long as it continues to be invoked, will not
+// be triggered. The function will be called after it stops being called for
+// N milliseconds. If `immediate` is passed, trigger the function on the
+// leading edge, instead of the trailing.
+function debounce(func, wait, immediate) {
+	var timeout;
+	return function() {
+		var context = this, args = arguments;
+		var later = function() {
+			timeout = null;
+			if (!immediate) func.apply(context, args);
+		};
+		var callNow = immediate && !timeout;
+		clearTimeout(timeout);
+		timeout = setTimeout(later, wait);
+		if (callNow) func.apply(context, args);
+	};
+};