make name a special argument

Author: cpsievert

NEWS.md

@@ -4,8 +4,8 @@
 
 * 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).
 * 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.
+* New "special `plot_ly()` 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")`).
+* Persistent selection may now be enabled 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")`.
@@ -14,6 +14,7 @@
 
 ## CHANGES
 
+* The `name` attribute is now a "special `plot_ly()` argument" and behaves similar to `split` (it ensures a different trace for every unique value supplied). Although this leads to a breaking change (`name` was previously appended to an automatically generated trace name), it leads to a better and more flexible API. Those that wish to have the old behavior back should provide relevant mappings to the `name` attributes (e.g. `plot_ly(mtcars, x = ~wt, y = ~mpg, color = ~factor(vs), name = "a")` would become `plot_ly(mtcars, x = ~wt, y = ~mpg, color = ~factor(vs), name = ~paste(vs, "\na"))`)
 * The `color` argument now maps to `fillcolor`, making it much easier to use polygon fills to encode data values (e.g., choropleth maps). For backwards-compatibilty reasons, when `color` maps to `fillcolor`, `alpha` defaults to 0.5 (instead of 1). For an example, `plot_mapbox(mn_res, color = ~INDRESNAME)` or `plot_mapbox(mn_res, split = ~INDRESNAME, color = ~AREA, showlegend = FALSE, stroke = I("black"))`.
 * The `color` argument no longer automatically add `"markers"` to the `mode` attribute for scatter/scattergl trace types. Those who wish to have the old behavior back, should add `"markers"` to the `mode` explicity (e.g., change `plot_ly(economics, x = ~pce, y = ~pop, color = ~as.numeric(date), mode = "lines")` to `plot_ly(economics, x = ~pce, y = ~pop, color = ~as.numeric(date), mode = "lines+markers")`).
 * The `size` argument now informs a default [error_[x/y].width](https://plot.ly/r/reference/#scatter-error_x-width) (and `span` informs [error_[x/y].thickness](https://plot.ly/r/reference/#scatter-error_x-thickness)). Note you can override the default by specifying directly (e.g. `plot_ly(x = 1:10, y = 1:10, size = I(10), error_x = list(value = 5, width = 0))`).

R/plotly.R

@@ -23,6 +23,9 @@
 #' (e.g. `plot_ly(x = 1:10, y = 1:10, color = I("red"), marker = list(color = "blue"))`).
 #' @param type A character string specifying the trace type (e.g. `"scatter"`, `"bar"`, `"box"`, etc).
 #' If specified, it *always* creates a trace, otherwise 
+#' @param name Values mapped to the trace's name attribute. Since a trace can 
+#' only have one name, this argument acts very much like `split` in that it 
+#' creates one trace for every unique value.
 #' @param color Values mapped to relevant 'fill-color' attribute(s) 
 #' (e.g. [fillcolor](https://plot.ly/r/reference#scatter-fillcolor), 
 #' [marker.color](https://plot.ly/r/reference#scatter-marker-color), 
@@ -124,7 +127,7 @@
 #' 
 #' }
 #' 
-plot_ly <- function(data = data.frame(), ..., type = NULL, 
+plot_ly <- function(data = data.frame(), ..., type = NULL, name,
                     color, colors = NULL, alpha = NULL, 
                     stroke, strokes = NULL, alpha_stroke = 1,
                     size, sizes = c(10, 100), 
@@ -160,6 +163,7 @@ plot_ly <- function(data = data.frame(), ..., type = NULL,
   }
 
   # tack on variable mappings
+  attrs$name <- if (!missing(name)) name
   attrs$color <- if (!missing(color)) color
   attrs$stroke <- if (!missing(stroke)) stroke
   attrs$size <- if (!missing(size)) size
@@ -193,10 +197,10 @@ plot_ly <- function(data = data.frame(), ..., type = NULL,
     # we always deal with a _list_ of traces and _list_ of layouts 
     # since they can each have different data
     layout = list(
-        width = width, 
-        height = height,
-        # sane margin defaults (mainly for RStudio)
-        margin = list(b = 40, l = 60, t = 25, r = 10)
+      width = width, 
+      height = height,
+      # sane margin defaults (mainly for RStudio)
+      margin = list(b = 40, l = 60, t = 25, r = 10)
     ),
     source = source
   )
@@ -424,7 +428,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 +438,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

R/plotly_build.R

@@ -189,7 +189,7 @@ plotly_build.plotly <- function(p, registerFrames = TRUE) {
       dataArrayAttrs, special_attrs(trace), npscales(), "frame",
       # for some reason, text isn't listed as a data array in some traces
       # I'm looking at you scattergeo...
-      ".plotlyGroupIndex", "text", "key", "fillcolor"
+      ".plotlyGroupIndex", "text", "key", "fillcolor", "name"
     )
     tr <- trace[names(trace) %in% allAttrs]
     # TODO: does it make sense to "train" matrices/2D-tables (e.g. z)?
@@ -205,7 +205,7 @@ plotly_build.plotly <- function(p, registerFrames = TRUE) {
       isAsIs <- vapply(builtData, function(x) inherits(x, "AsIs"), logical(1))
       isDiscrete <- vapply(builtData, is.discrete, logical(1))
       # note: can only have one linetype per trace
-      isSplit <- names(builtData) %in% c("split", "linetype", "frame", "fillcolor") |
+      isSplit <- names(builtData) %in% c("split", "linetype", "frame", "fillcolor", "name") |
         !isAsIs & isDiscrete & names(builtData) %in% c("symbol", "color")
       if (any(isSplit)) {
         paste2 <- function(x, y) if (identical(x, y)) x else paste(x, y, sep = br())
@@ -980,7 +980,7 @@ traceify <- function(dat, x = NULL) {
   new_dat <- list()
   for (j in seq_along(lvls)) {
     new_dat[[j]] <- lapply(dat, function(y) recurse(y, n, x %in% lvls[j]))
-    new_dat[[j]]$name <- lvls[j]
+    new_dat[[j]]$name <- new_dat[[j]]$name %||% lvls[j]
   }
   return(new_dat)
 }

R/utils.R

@@ -492,6 +492,10 @@ verify_attr <- function(proposed, schema) {
       proposed[[attr]] <- structure(proposed[[attr]], apiSrc = TRUE)
     }
 
+    if (length(proposed$name) > 0) {
+      proposed$name <- uniq(proposed$name)
+    }
+    
     # do the same for "sub-attributes"
     if (identical(role, "object")) {
       proposed[[attr]] <- verify_attr(proposed[[attr]], schema[[attr]])