feat!(bs_theme): Rename preset from name (#641)

R/bs-theme-preset.R

@@ -1,16 +1,16 @@
 resolve_bs_preset <- function(
-  name = NULL,
+  preset = NULL,
   bootswatch = NULL,
   version = version_default()
 ) {
-  if (is.null(name) && is.null(bootswatch)) return(NULL)
+  if (is.null(preset) && is.null(bootswatch)) return(NULL)
 
-  assert_preset_scalar_string(name)
+  assert_preset_scalar_string(preset)
   assert_preset_scalar_string(bootswatch)
-  assert_preset_only_one_name_arg(name, bootswatch)
+  assert_preset_only_one_name_arg(preset, bootswatch)
 
   version <- switch_version(version, five = "5", four = "4", three = "3")
-  preset_name <- name %||% bootswatch
+  preset_name <- preset %||% bootswatch
 
   if (preset_name %in% c("default", "bootstrap")) {
     # "default" means no preset bundle, just bare default Bootstrap
@@ -89,18 +89,18 @@ assert_preset_scalar_string <- function(var, .frame = rlang::caller_env()) {
   rlang::abort(msg, .frame = .frame)
 }
 
-assert_preset_only_one_name_arg <- function(name, bootswatch, .frame = rlang::caller_env()) {
-  both_provided <- !is.null(name) && !is.null(bootswatch)
+assert_preset_only_one_name_arg <- function(preset, bootswatch, .frame = rlang::caller_env()) {
+  both_provided <- !is.null(preset) && !is.null(bootswatch)
 
   if (!both_provided) {
     return(invisible())
   }
 
   msg <- c(
-    "Only one of `name` or `bootswatch` may be provided, and `name` is preferred.",
+    "Only one of `preset` or `bootswatch` may be provided, and `name` is preferred.",
     "i" = "Did you mean one of the following options?",
-    "*" = sprintf('`name = "%s"`', name),
-    "*" = sprintf('`name = "%s"`', bootswatch),
+    "*" = sprintf('`preset = "%s"`', preset),
+    "*" = sprintf('`preset = "%s"`', bootswatch),
     "*" = sprintf('`bootswatch = "%s"`', bootswatch)
   )
   rlang::abort(msg, .frame = .frame)

R/bs-theme.R

@@ -57,7 +57,7 @@
 #' @param version The major version of Bootstrap to use (see [versions()]
 #'   for possible values). Defaults to the currently recommended version
 #'   for new projects (currently Bootstrap 5).
-#' @param name The name of a theme preset, either a built-in theme provided by
+#' @param preset The name of a theme preset, either a built-in theme provided by
 #'   bslib or a Bootswatch theme (see [builtin_themes()] and
 #'   [bootswatch_themes()] for possible values). This argument takes precedence
 #'   over the `bootswatch` argument and only one `theme` or `bootswatch` can be
@@ -119,13 +119,13 @@
 #' theme <- bs_add_rules(theme, ".my-class { color: $my-class-color }")
 #'
 #' @export
-bs_theme <- function(version = version_default(), name = NULL, ...,
+bs_theme <- function(version = version_default(), preset = NULL, ...,
                      bg = NULL, fg = NULL, primary = NULL, secondary = NULL,
                      success = NULL, info = NULL, warning = NULL, danger = NULL,
                      base_font = NULL, code_font = NULL, heading_font = NULL,
                      font_scale = NULL, bootswatch = NULL) {
 
-  preset <- resolve_bs_preset(name, bootswatch, version = version)
+  preset <- resolve_bs_preset(preset, bootswatch, version = version)
 
   bundle <- bs_bundle(
     bs_theme_init(version, subclass = preset$class),
@@ -152,7 +152,7 @@ bs_theme <- function(version = version_default(), name = NULL, ...,
 #' @rdname bs_theme
 #' @param theme a [bs_theme()] object.
 #' @export
-bs_theme_update <- function(theme, ..., name = NULL, bg = NULL, fg = NULL,
+bs_theme_update <- function(theme, ..., preset = NULL, bg = NULL, fg = NULL,
                             primary = NULL, secondary = NULL, success = NULL,
                             info = NULL, warning = NULL, danger = NULL,
                             base_font = NULL, code_font = NULL, heading_font = NULL,
@@ -161,7 +161,7 @@ bs_theme_update <- function(theme, ..., name = NULL, bg = NULL, fg = NULL,
 
   theme_has_preset <- any(grepl("^bs_(builtin|bootswatch)_", class(theme)))
 
-  preset <- resolve_bs_preset(name, bootswatch, version = theme_version(theme))
+  preset <- resolve_bs_preset(preset, bootswatch, version = theme_version(theme))
 
   if (!is.null(preset)) {
     if (theme_has_preset) {
@@ -198,14 +198,14 @@ bs_theme_update <- function(theme, ..., name = NULL, bg = NULL, fg = NULL,
 
 #' @rdname bs_global_theme
 #' @export
-bs_global_theme_update <- function(..., name = NULL, bg = NULL, fg = NULL,
+bs_global_theme_update <- function(..., preset = NULL, bg = NULL, fg = NULL,
                                    primary = NULL,  secondary = NULL, success = NULL,
                                    info = NULL, warning = NULL, danger = NULL,
                                    base_font = NULL, code_font = NULL, heading_font = NULL, bootswatch = NULL) {
   theme <- assert_global_theme("bs_theme_global_update()")
   bs_global_set(bs_theme_update(
     theme, ...,
-    name = name,
+    preset = preset,
     bootswatch = bootswatch,
     bg = bg, fg = fg,
     primary = primary,

tests/testthat/_snaps/bs-theme-preset.md

@@ -1,22 +1,22 @@
 # new_theme_preset(): throws an error if both `name` and `bootswatch` are provided
 
     Code
-      resolve_bs_preset(name = "name", bootswatch = "bootswatch")
+      resolve_bs_preset(preset = "name", bootswatch = "bootswatch")
     Error <rlang_error>
-      Only one of `name` or `bootswatch` may be provided, and `name` is preferred.
+      Only one of `preset` or `bootswatch` may be provided, and `name` is preferred.
       i Did you mean one of the following options?
-      * `name = "name"`
-      * `name = "bootswatch"`
+      * `preset = "name"`
+      * `preset = "bootswatch"`
       * `bootswatch = "bootswatch"`
 
 # new_theme_preset(): throws an error if `name` or `bootswatch` are not scalar strings
 
     Code
-      resolve_bs_preset(name = c("a", "b"))
+      resolve_bs_preset(preset = c("a", "b"))
     Error <rlang_error>
-      The preset theme `name` must be a single character string.
-      x Bad: `name = c("flatly", "darkly")`
-      v Good: `name = "flatly"`
+      The preset theme `preset` must be a single character string.
+      x Bad: `preset = c("flatly", "darkly")`
+      v Good: `preset = "flatly"`
 
 ---
 
@@ -30,7 +30,7 @@
 # new_theme_preset(): throws an error if `name` or `bootswatch` don't match existing presets
 
     Code
-      resolve_bs_preset(name = "not_a_preset", version = 4)
+      resolve_bs_preset(preset = "not_a_preset", version = 4)
     Error <rlang_error>
       'not_a_preset' is not a known preset theme name for Bootstrap version 4.
       i You can list available preset themes:

tests/testthat/test-bs-theme-preset.R

@@ -1,39 +1,39 @@
 describe("new_theme_preset()", {
   it("returns NULL if both `name` and `bootswatch` are missing", {
-    expect_null(resolve_bs_preset(name = NULL, bootswatch = NULL))
+    expect_null(resolve_bs_preset(preset = NULL, bootswatch = NULL))
   })
 
   it("throws an error if both `name` and `bootswatch` are provided", {
     expect_snapshot(
       error = TRUE,
-      resolve_bs_preset(name = "name", bootswatch = "bootswatch")
+      resolve_bs_preset(preset = "name", bootswatch = "bootswatch")
     )
   })
 
   it("throws an error if `name` or `bootswatch` are not scalar strings", {
     expect_snapshot(
       error = TRUE,
-      resolve_bs_preset(name = c("a", "b"))
+      resolve_bs_preset(preset = c("a", "b"))
     )
     expect_snapshot(
       error = TRUE,
       resolve_bs_preset(bootswatch = c("a", "b"))
     )
 
-    expect_error(resolve_bs_preset(name = 1))
+    expect_error(resolve_bs_preset(preset = 1))
     expect_error(resolve_bs_preset(bootswatch = 1))
 
-    expect_error(resolve_bs_preset(name = TRUE))
+    expect_error(resolve_bs_preset(preset = TRUE))
     expect_error(resolve_bs_preset(bootswatch = TRUE))
 
-    expect_error(resolve_bs_preset(name = NA_character_))
+    expect_error(resolve_bs_preset(preset = NA_character_))
     expect_error(resolve_bs_preset(bootswatch = NA_character_))
   })
 
   it("throws an error if `name` or `bootswatch` don't match existing presets", {
     expect_snapshot(
       error = TRUE,
-      resolve_bs_preset(name = "not_a_preset", version = 4)
+      resolve_bs_preset(preset = "not_a_preset", version = 4)
     )
     expect_snapshot(
       error = TRUE,
@@ -42,34 +42,34 @@ describe("new_theme_preset()", {
   })
 
   it("throws an error for unknown bootstrap version", {
-    expect_error(resolve_bs_preset(name = "cerulean", version = "2"))
+    expect_error(resolve_bs_preset(preset = "cerulean", version = "2"))
     expect_error(resolve_bs_preset(bootswatch = "cerulean", version = "99"))
 
     expect_warning(resolve_bs_preset(bootswatch = "cerulean", version = "4-3"))
   })
 
   it("returns a 'default' preset if name or bootswatch is 'default' or 'bootstrap'", {
     expect_equal(
-      resolve_bs_preset(name = "default"),
+      resolve_bs_preset(preset = "default"),
       resolve_bs_preset(bootswatch = "default")
     )
 
     expect_equal(
-      resolve_bs_preset(name = "bootstrap"),
+      resolve_bs_preset(preset = "bootstrap"),
       resolve_bs_preset(bootswatch = "bootstrap")
     )
 
     expect_equal(
-      resolve_bs_preset(name = "default"),
-      resolve_bs_preset(name = "bootstrap")
+      resolve_bs_preset(preset = "default"),
+      resolve_bs_preset(preset = "bootstrap")
     )
 
     expect_equal(
-      unclass(resolve_bs_preset(name = "default")),
+      unclass(resolve_bs_preset(preset = "default")),
       list(version = version_default(), name = "default")
     )
 
-    expect_identical(class(resolve_bs_preset(name = "default")), "bs_preset")
+    expect_identical(class(resolve_bs_preset(preset = "default")), "bs_preset")
   })
 
   it("returns a BS5 Bootswatch theme preset", {
@@ -104,23 +104,23 @@ describe("new_theme_preset()", {
 
   it("returns a bootswatch theme preset if `name` is used instead of `bootswatch`", {
     expect_equal(
-      resolve_bs_preset(name = "darkly", version = 5),
+      resolve_bs_preset(preset = "darkly", version = 5),
       resolve_bs_preset(bootswatch = "darkly", version = 5)
     )
 
     expect_equal(
-      resolve_bs_preset(name = "cosmo", version = 4),
+      resolve_bs_preset(preset = "cosmo", version = 4),
       resolve_bs_preset(bootswatch = "cosmo", version = 4)
     )
 
     expect_equal(
-      resolve_bs_preset(name = "readable", version = 3),
+      resolve_bs_preset(preset = "readable", version = 3),
       resolve_bs_preset(bootswatch = "readable", version = 3)
     )
   })
 
   it("returns the builtin shiny theme preset", {
-    shiny <- resolve_bs_preset(name = "shiny", version = 5)
+    shiny <- resolve_bs_preset(preset = "shiny", version = 5)
 
     expect_s3_class(shiny, "bs_preset")
     expect_s3_class(shiny, "bs_preset_builtin")
@@ -131,7 +131,7 @@ describe("new_theme_preset()", {
 })
 
 test_that("bs_preset_bundle() returns `NULL` for default or empty preset", {
-  expect_null(bs_preset_bundle(resolve_bs_preset(name = "default")))
+  expect_null(bs_preset_bundle(resolve_bs_preset(preset = "default")))
   expect_null(bs_preset_bundle(resolve_bs_preset(bootswatch = "default")))
   expect_null(bs_preset_bundle(NULL))
 })