Add bs_add_functions() and bs_add_mixins() (#311)

* Deprecate bs_add_declarations(); add bs_add_functions() and bs_add_mixins(); avoid use of sass_layer(declarations).

Follow up to rstudio/sass#80

* Document (GitHub Actions)

* update news

* Update R/bs-theme-layers.R

* Document (GitHub Actions)

Co-authored-by: cpsievert <[email protected]>

Author: cpsievert

DESCRIPTION

@@ -22,7 +22,7 @@ Imports:
     grDevices,
     htmltools (>= 0.5.1),
     jsonlite,
-    sass (>= 0.3.1.9001),
+    sass (>= 0.3.1.9002),
     digest (>= 0.6.25),
     jquerylib (>= 0.1.3),
     rlang,

NAMESPACE

@@ -5,6 +5,8 @@ export(bootstrap)
 export(bootstrap_sass)
 export(bootswatch_themes)
 export(bs_add_declarations)
+export(bs_add_functions)
+export(bs_add_mixins)
 export(bs_add_rules)
 export(bs_add_variables)
 export(bs_bundle)

NEWS.md

@@ -9,8 +9,9 @@
 * Closed #227: `bs_themer()` now overlays a spinner during Sass compilation (#243).
 * Closed #278: `{bslib}` now includes `rmarkdown::html_document` templates demonstrating example usage with `{bslib}` and `{thematic}` (#288).
 * Closed #231: Upgraded from Bootstrap 4.5.3 to 4.6.0 (#254).
-* Closed #237: <blockquote> tags now have border-left/padding styles with version = 4 (to mirror the version = 3 behavior) (#239).
+* Closed #237: `<blockquote>` tags now have border-left/padding styles with `version = 4` (to mirror the `version = 3` behavior) (#239).
 * Closed #279: Warnings about low color contrasts are now suppressed by default, unless `shiny::devmode()` is enabled. To enable/disable these warnings, set the new `options(bslib.color_contrast_warnings = )` to `TRUE`/`FALSE` (#287).
+* Added new `bs_add_functions()`/`bs_add_mixins()` and deprecated `bs_add_declarations()` to reflect `sass::sass_layer()`'s new ability to place `functions` _before_ variable `defaults`. As a result, variable definitions may now use functions defined with `bs_add_functions()`. (#311)
 
 ## Bug fixes
 

R/bs-theme-layers.R

@@ -77,7 +77,6 @@ bs_add_variables <- function(theme, ..., .where = "defaults", .default_flag = id
 
   vars <- rlang::list2(...)
   if (any(names2(vars) == "")) stop("Variables must be named.", call. = FALSE)
-  .where <- match.arg(.where, c("defaults", "declarations", "rules"))
 
   # Workaround to the problem of 'blue' winning in the scenario of:
   # bs_add_variables("body-bg" = "blue")
@@ -126,11 +125,22 @@ bs_add_rules <- function(theme, rules) {
   bs_bundle(theme, sass_layer(rules = rules))
 }
 
-#' @describeIn bs_bundle Add Sass [functions](https://sass-lang.com/documentation/at-rules/function) and [mixins](https://sass-lang.com/documentation/at-rules/mixin)
-#' @param declarations Sass functions and mixins.
+#' @describeIn bs_bundle Add additional [Sass
+#'   functions](https://rstudio.github.io/sass/articles/sass.html#functions-1)
+#' @param functions A character vector or [sass::sass_file()] containing
+#'   functions definitions.
 #' @export
-bs_add_declarations <- function(theme, declarations) {
-  bs_bundle(theme, sass_layer(declarations = declarations))
+bs_add_functions <- function(theme, functions) {
+  bs_bundle(theme, sass_layer(functions = functions))
+}
+
+#' @describeIn bs_bundle Add additional [Sass
+#'   mixins](https://rstudio.github.io/sass/articles/sass.html#mixins-1)
+#' @param mixins A character vector or [sass::sass_file()] containing
+#'   mixin definitions.
+#' @export
+bs_add_mixins <- function(theme, mixins) {
+  bs_bundle(theme, sass_layer(mixins = mixins))
 }
 
 #' @describeIn bs_bundle Add additional [sass::sass_bundle()] objects to an existing `theme`.

R/bs-theme-preview.R

@@ -591,7 +591,7 @@ bs_get_variables <- function(theme, varnames) {
   css <- sass_partial(
     cssvars,
     # Add declarations to the current theme
-    bs_bundle(theme, sass_layer(declarations = sassvars)),
+    bs_bundle(theme, sass_layer(mixins = sassvars)),
   )
 
   # Search the output for the block of properties we just generated, using the

R/bs-theme.R

@@ -256,7 +256,7 @@ bootstrap_bundle <- function(version) {
       # Don't name this "core" bundle so it can't easily be removed
       sass_layer(
         defaults = bs4_sass_files(c("deprecated", "functions", "variables")),
-        declarations = bs4_sass_files("mixins")
+        mixins = bs4_sass_files("mixins")
       ),
       # Returns a _named_ list of bundles (i.e., these should be easily removed)
       !!!rule_bundles(
@@ -285,7 +285,7 @@ bootstrap_bundle <- function(version) {
     three = sass_bundle(
       sass_layer(
         defaults = bs3_sass_files("variables"),
-        declarations = bs3_sass_files("mixins")
+        mixins = bs3_sass_files("mixins")
       ),
       # Should match https://github.com/twbs/bootstrap-sass/blob/master/assets/stylesheets/_bootstrap.scss
       !!!rule_bundles(
@@ -332,7 +332,7 @@ bootstrap_javascript <- function(version) {
 bs3compat_bundle <- function() {
   sass_layer(
     defaults = sass_file(system_file("bs3compat", "_defaults.scss", package = "bslib")),
-    declarations = sass_file(system_file("bs3compat", "_declarations.scss", package = "bslib")),
+    mixins = sass_file(system_file("bs3compat", "_declarations.scss", package = "bslib")),
     rules = sass_file(system_file("bs3compat", "_rules.scss", package = "bslib")),
     # Gyliphicon font files
     file_attachments = c(

R/deprecated.R

@@ -117,3 +117,10 @@ bootstrap_sass <- function(rules = list(), theme = bs_theme_get(), ...) {
   theme$rules <- ""
   sass_partial(rules, theme)
 }
+
+#' @rdname deprecated
+#' @export
+bs_add_declarations <- function(theme, declarations) {
+  .Deprecated("bs_add_mixins")
+  bs_bundle(theme, sass_layer(declarations = declarations))
+}

man/bs_bundle.Rd

@@ -49,7 +49,7 @@ test_that("Theme adding works as intended", {
 
   # Can also override variables via declarations
   bs_global_add_variables(
-    .where = "declarations",
+    .where = "mixins",
     "primary" = "$secondary",
     "body-color" = "color-contrast($primary)"
   )