Implement plot-wise justification (tidyverse#4020)

R/plot-build.R

@@ -464,14 +464,20 @@ table_add_legends <- function(table, legends, theme) {
   zero    <- unit(0, "pt")
   spacing <- lapply(legends, function(x) if (is.zero(x)) zero else spacing)
 
-  panels <- find_panel(table)
+  location <- switch(
+    theme$legend.location %||% "panel",
+    "plot" = plot_extent,
+    find_panel
+  )
+
+  place <- location(table)
 
   # Add right legend
   table <- gtable_add_cols(table, spacing$right, pos = -1)
   table <- gtable_add_cols(table, widths$right,  pos = -1)
   table <- gtable_add_grob(
     table, legends$right, clip = "off",
-    t = panels$t, b = panels$b, l = -1, r = -1,
+    t = place$t, b = place$b, l = -1, r = -1,
     name = "guide-box-right"
   )
 
@@ -480,18 +486,18 @@ table_add_legends <- function(table, legends, theme) {
   table <- gtable_add_cols(table, widths$left,  pos = 0)
   table <- gtable_add_grob(
     table, legends$left, clip = "off",
-    t = panels$t, b = panels$b, l = 1, r = 1,
+    t = place$t, b = place$b, l = 1, r = 1,
     name = "guide-box-left"
   )
 
-  panels <- find_panel(table)
+  place <- location(table)
 
   # Add bottom legend
   table <- gtable_add_rows(table, spacing$bottom, pos = -1)
   table <- gtable_add_rows(table, heights$bottom, pos = -1)
   table <- gtable_add_grob(
     table, legends$bottom, clip = "off",
-    t = -1, b = -1, l = panels$l, r = panels$r,
+    t = -1, b = -1, l = place$l, r = place$r,
     name = "guide-box-bottom"
   )
 
@@ -500,17 +506,28 @@ table_add_legends <- function(table, legends, theme) {
   table <- gtable_add_rows(table, heights$top, pos = 0)
   table <- gtable_add_grob(
     table, legends$top, clip = "off",
-    t = 1, b = 1, l = panels$l, r = panels$r,
+    t = 1, b = 1, l = place$l, r = place$r,
     name = "guide-box-top"
   )
 
   # Add manual legend
-  panels <- find_panel(table)
+  place <- find_panel(table)
   table <- gtable_add_grob(
     table, legends$inside, clip = "off",
-    t = panels$t, b = panels$b, l = panels$l, r = panels$r,
+    t = place$t, b = place$b, l = place$l, r = place$r,
     name = "guide-box-inside"
   )
 
   table
 }
+
+plot_extent <- function(table) {
+  layout <- table$layout
+  data_frame0(
+    t = min(.subset2(layout, "t")),
+    r = max(.subset2(layout, "r")),
+    b = max(.subset2(layout, "b")),
+    l = min(.subset2(layout, "l")),
+    .size = 1L
+  )
+}

R/theme-elements.R

@@ -506,6 +506,8 @@ el_def <- function(class = NULL, inherit = NULL, description = NULL) {
   legend.position.inside = el_def(c("numeric", "integer")),
   legend.direction    = el_def("character"),
   legend.justification = el_def(c("character", "numeric", "integer")),
+  legend.location     = el_def("character"),
+
   legend.box          = el_def("character"),
   legend.box.just     = el_def("character"),
   legend.box.margin   = el_def("margin"),

R/theme.R

@@ -87,6 +87,9 @@
 #' @param legend.justification anchor point for positioning legend inside plot
 #'   ("center" or two-element numeric vector) or the justification according to
 #'   the plot area when positioned outside the plot
+#' @param legend.location Relative placement of legends outside the plot as a
+#'   string. Can be `"panel"` (default) to align legends to the panels or
+#'   `"plot"` to align legends to the plot as a whole.
 #' @param legend.box arrangement of multiple legends ("horizontal" or
 #'   "vertical")
 #' @param legend.box.just justification of each legend within the overall
@@ -349,6 +352,7 @@ theme <- function(line,
                   legend.position.inside,
                   legend.direction,
                   legend.justification,
+                  legend.location,
                   legend.box,
                   legend.box.just,
                   legend.box.margin,