feat: add position argument to civilytics_logo() for corner placement

Supports "bottom-right" (default), "bottom-left", "top-right", and
"top-left". The position controls both horizontal alignment of the logo
grob and whether it is placed above or below the plot.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

R/logo.R

@@ -50,12 +50,20 @@ get_png <- function(filename) {
 #'   sizes before composing the plot with the logo. Default `1.1` inflates
 #'   text by ~10 \% to compensate for the viewport shrinkage caused by
 #'   [gridExtra::arrangeGrob()]. Set to `1` to disable.
+#' @param position Character. Corner placement for the logo: `"bottom-right"`
+#'   (default), `"bottom-left"`, `"top-right"`, or `"top-left"`. Controls
+#'   whether the logo is placed above or below the plot.
 #'
 #' @return a grob with a logo attached to it ready to plot
 #' @importFrom ggplot2 theme
 #' @importFrom gridExtra arrangeGrob
 #' @export
-add_logo <- function(plot, logo, margin_param = NULL, font_scale = 1.1) {
+add_logo <- function(plot, logo, margin_param = NULL, font_scale = 1.1,
+                     position = c("bottom-right", "bottom-left",
+                                  "top-right", "top-left")) {
+  position <- match.arg(position)
+  at_top <- grepl("top", position)
+
   # Inflate text sizes to compensate for arrangeGrob viewport shrinkage.
   # All theme text elements use rel() sizing, so scaling the root 'text'
   # element cascades to titles, axis labels, legends, captions, and strips.
@@ -66,19 +74,30 @@ add_logo <- function(plot, logo, margin_param = NULL, font_scale = 1.1) {
     )
   }
 
-  if(has_caption(plot)) {
-    cap_lines <- measure_caption(plot)
+  if (at_top) {
+    # For top placement, tighten the top margin of the plot
     if (!is.null(margin_param)) {
-      plot <- plot + theme(plot.margin = unit(c(7, 7, margin_param, 7), "pt"))
+      plot <- plot + theme(plot.margin = unit(c(margin_param, 7, 7, 7), "pt"))
     } else {
-      plot <- plot + theme(plot.margin = unit(c(7, 7, cap_lines * -52, 7), "pt"))
+      plot <- plot + theme(plot.margin = unit(c(-14, 7, 7, 7), "pt"))
     }
+    arrangeGrob(logo, plot, heights = c(0.1, 0.93),
+                padding = unit(0.1, "line"))
   } else {
-    plot <- plot + theme(plot.margin = unit(c(7, 7, -14, 7), "pt"))
+    # Bottom placement (original behaviour)
+    if(has_caption(plot)) {
+      cap_lines <- measure_caption(plot)
+      if (!is.null(margin_param)) {
+        plot <- plot + theme(plot.margin = unit(c(7, 7, margin_param, 7), "pt"))
+      } else {
+        plot <- plot + theme(plot.margin = unit(c(7, 7, cap_lines * -52, 7), "pt"))
+      }
+    } else {
+      plot <- plot + theme(plot.margin = unit(c(7, 7, -14, 7), "pt"))
+    }
+    arrangeGrob(plot, logo, heights = c(0.93, 0.1),
+                padding = unit(0.1, "line"))
   }
-
-  arrangeGrob(plot, logo, heights = c(0.93, 0.1),
-              padding = unit(0.1, "line"))
 }
 
 #' Measure a ggplot2 object caption
@@ -193,6 +212,9 @@ add_logo_ga <- function(plot_list, logo, nrow = 1, widths = NULL,
 #' @param variant Character. `"light"` (default) uses the dark logo for light
 #'   backgrounds. `"dark"` uses the reverse (light) logo for dark backgrounds
 #'   (pairs with [theme_civilytics_dark()]).
+#' @param position Character. Corner placement for the logo: `"bottom-right"`
+#'   (default), `"bottom-left"`, `"top-right"`, or `"top-left"`. Controls
+#'   horizontal alignment of the logo grob.
 #'
 #' @return A ggplot object (class `"gg"`) containing the logo grob.
 #' @export
@@ -200,11 +222,15 @@ add_logo_ga <- function(plot_list, logo, nrow = 1, widths = NULL,
 #' @examples
 #' logo <- make_logo_grob()                          # wordmark, light
 #' logo <- make_logo_grob("mark", "dark")            # mark, dark
+#' logo <- make_logo_grob(position = "bottom-left")  # left-aligned
 #' class(logo)  # "gg" "ggplot"
 make_logo_grob <- function(type = c("wordmark", "mark"),
-                           variant = c("light", "dark")) {
-  type    <- match.arg(type)
-  variant <- match.arg(variant)
+                           variant = c("light", "dark"),
+                           position = c("bottom-right", "bottom-left",
+                                        "top-right", "top-left")) {
+  type     <- match.arg(type)
+  variant  <- match.arg(variant)
+  position <- match.arg(position)
 
   img_file <- switch(
     paste(type, variant, sep = "_"),
@@ -214,21 +240,28 @@ make_logo_grob <- function(type = c("wordmark", "mark"),
     mark_dark      = "civilytics-mark-reverse.png"
   )
 
-  # Right-align the logo; the mark is compact so it gets a narrower slice.
-  xmin <- if (type == "mark") 0.93 else 0.65
+  align_left <- grepl("left", position)
+
+  if (align_left) {
+    xmin <- 0
+    xmax <- if (type == "mark") 0.07 else 0.35
+  } else {
+    xmin <- if (type == "mark") 0.93 else 0.65
+    xmax <- 1
+  }
 
   ggplot2::ggplot() +
     ggplot2::theme_void() +
     ggplot2::annotation_custom(
       get_png(system.file("img", img_file, package = "civilytics")),
-      xmin = xmin, xmax = 1
+      xmin = xmin, xmax = xmax
     )
 }
 
 #' Add a Civilytics logo to a ggplot (pipe-friendly)
 #'
-#' A convenience wrapper that creates the logo grob and attaches it below the
-#' plot in one call. Designed for use with the base pipe `|>`.
+#' A convenience wrapper that creates the logo grob and attaches it to a
+#' corner of the plot in one call. Designed for use with the base pipe `|>`.
 #'
 #' **Important:** R's `|>` has *higher* precedence than `+`, so you must
 #' wrap the ggplot chain in parentheses before piping:
@@ -245,6 +278,8 @@ make_logo_grob <- function(type = c("wordmark", "mark"),
 #'   [make_logo_grob()].
 #' @param variant Character. `"light"` (default) or `"dark"`. Passed to
 #'   [make_logo_grob()].
+#' @param position Character. Corner placement for the logo: `"bottom-right"`
+#'   (default), `"bottom-left"`, `"top-right"`, or `"top-left"`.
 #' @param margin_param Numeric or `NULL`. Manual margin adjustment passed to
 #'   [add_logo()].
 #' @param font_scale Numeric. Inflate text sizes by this factor to compensate
@@ -266,26 +301,38 @@ make_logo_grob <- function(type = c("wordmark", "mark"),
 #'   civilytics_logo() |>
 #'   grid.draw()
 #'
-#' # Dark theme with mark
-#' (ggplot(mpg, aes(displ, hwy)) +
-#'   geom_point() +
-#'   theme_civilytics_dark()) |>
-#'   civilytics_logo(variant = "dark", type = "mark") |>
-#'   grid.draw()
-#'
-#' # Disable font inflation
+#' # Top-right placement
 #' (ggplot(mpg, aes(displ, hwy)) +
 #'   geom_point() +
 #'   theme_civilytics()) |>
-#'   civilytics_logo(font_scale = 1) |>
+#'   civilytics_logo(position = "top-right") |>
+#'   grid.draw()
+#'
+#' # Bottom-left with mark
+#' (ggplot(mpg, aes(displ, hwy)) +
+#'   geom_point() +
+#'   theme_civilytics()) |>
+#'   civilytics_logo(type = "mark", position = "bottom-left") |>
+#'   grid.draw()
+#'
+#' # Dark theme with mark in top-left
+#' (ggplot(mpg, aes(displ, hwy)) +
+#'   geom_point() +
+#'   theme_civilytics_dark()) |>
+#'   civilytics_logo(variant = "dark", type = "mark",
+#'                   position = "top-left") |>
 #'   grid.draw()
 #' }
 civilytics_logo <- function(plot,
                             type = c("wordmark", "mark"),
                             variant = c("light", "dark"),
+                            position = c("bottom-right", "bottom-left",
+                                         "top-right", "top-left"),
                             margin_param = NULL,
                             font_scale = 1.1) {
-  logo <- make_logo_grob(type = type, variant = variant)
-  add_logo(plot, logo, margin_param = margin_param, font_scale = font_scale)
+  position <- match.arg(position)
+  logo <- make_logo_grob(type = type, variant = variant, position = position)
+  add_logo(plot, logo, margin_param = margin_param, font_scale = font_scale,
+           position = position)
 }