Bundling Sass layers — sass

Sass layers provide a way to package Sass variables, rules, functions, and mixins in a structured and composable way that follows best Sass practices. Most importantly, when multiple sass_layer() are combined into a sass_bundle(), variable defaults for later layers are placed before earlier layers, effectively 'new' defaults through all the 'old' defaults.

sass_layer(
  functions = NULL,
  defaults = NULL,
  mixins = NULL,
  rules = NULL,
  html_deps = NULL,
  file_attachments = character(0),
  declarations = NULL,
  tags = NULL
)

sass_layer_file(file)

sass_bundle(...)

sass_bundle_remove(bundle, name)

is_sass_bundle(x)

Arguments

functions: as_sass() input intended for Sass functions. Functions are placed before defaults so that variable definitions may make use of functions.
defaults: as_sass() input intended for variable defaults. These variable defaults after placed after functions but before mixins. When multiple layers are combined in a sass_bundle(), defaults are merged in reverse order; that is, sass_bundle(layer1, layer2) will include layer2$defaults before layer1$defaults.
mixins: as_sass() input intended for Sass mixins. Mixins are placed after defaults, but before rules.
rules: as_sass() input intended for Sass rules. Rules are placed last (i.e., after functions, defaults, and mixins).
html_deps: An HTML dependency (or a list of them). This dependency gets attached to the return value of sass()/as_sass().
file_attachments: A named character vector, representing file assets that are referenced (using relative paths) from the sass in this layer. The vector names should be a relative path, and the corresponding vector values should be absolute paths to files or directories that exist; at render time, each value will be copied to the relative path indicated by its name. (For directories, the contents of the source directory will be copied into the destination directory; the directory itself will not be copied.) You can also omit the name, in which case that file or directory will be copied directly into the output directory.
declarations: Deprecated, use functions or mixins instead.
tags: Deprecated. Preserve meta information using a key in sass_bundle(KEY = val). preserve simple metadata as layers are merged.
file: file path to a .scss file.
...: A collection of sass_layer()s and/or objects that as_sass() understands. Arguments should be provided in reverse priority order: defaults, declarations, and rules in later layers will take precedence over those of previous layers. Non-layer values will be converted to layers by calling sass_layer(rules = ...).
bundle: Output value from sass_layer() or sass_bundle()
name: If a Sass layer name is contained in name, the matching Sass layer will be removed from the bundle
x: object to inspect

Functions

sass_layer(): Compose the parts of a single Sass layer. Object returned is a sass_bundle() with a single Sass layer
sass_layer_file(): Read in a .scss file with parse special /*-- scss:(functions|defaults|rules|mixins) --*/ comments as relevant sections of a sass_layer().
sass_bundle(): Collect sass_bundle() and/or sass_layer() objects. Unnamed Sass bundles will be concatenated together, preserving their internal name structures. Named Sass bundles will be condensed into a single Sass layer for easier removal from the returned Sass bundle.
sass_bundle_remove(): Remove a whole sass_layer() from a sass_bundle() object.
is_sass_bundle(): Check if x is a Sass bundle object

Examples

blue <- list(color = "blue !default")
red <- list(color = "red !default")
green <- list(color = "green !default")

# a sass_layer() by itself is not very useful, it just defines some
# SASS to place before (defaults) and after (rules)
core <- sass_layer(defaults = blue, rules = "body { color: $color; }")
core
#> /* Sass Bundle */
#> $color: blue !default;
#> body { color: $color; }
#> /* *** */
sass(core)
#> /* CSS */
#> body {
#>   color: blue;
#> }
#> 

# However, by stacking sass_layer()s, we have ability to place
# SASS both before and after some other sass (e.g., core)
# Here we place a red default _before_ the blue default and export the
# color SASS variable as a CSS variable _after_ the core
red_layer <- sass_layer(red, rules = ":root{ --color: #{$color}; }")
sass(sass_bundle(core, red_layer))
#> /* CSS */
#> body {
#>   color: red;
#> }
#> 
#> :root {
#>   --color: red;
#> }
#> 
sass(sass_bundle(core, red_layer, sass_layer(green)))
#> /* CSS */
#> body {
#>   color: red;
#> }
#> 
#> :root {
#>   --color: red;
#> }
#> 

# Example of merging layers and removing a layer
# Remember to name the layers that are removable
core_layers <- sass_bundle(core, red = red_layer, green = sass_layer(green))
core_layers # pretty printed for console
#> /* Sass Bundle: red, green */
#> $color: red !default;
#> $color: green !default;
#> $color: blue !default;
#> body { color: $color; }
#> :root{ --color: #{$color}; }
#> /* *** */
core_slim <- sass_bundle_remove(core_layers, "red")
sass(core_slim)
#> /* CSS */
#> body {
#>   color: green;
#> }
#> 


# File attachment example: Create a checkboard pattern .png, then
# use it from a sass layer

tmp_png <- tempfile(fileext = ".png")
grDevices::png(filename = tmp_png, width = 20, height = 20,
  bg = "transparent", antialias = "none")
par(mar = rep_len(0,4), xaxs = "i", yaxs = "i")
plot.new()
rect(c(0,0.5), c(0,0.5), c(0.5,1), c(0.5,1), col = "#00000044", border=NA)
dev.off()
#> agg_png 
#>       2 

layer <- sass_layer(
  rules = ".bg-check { background-image: url(images/demo_checkboard_bg.png) }",
  file_attachments = c("images/demo_checkboard_bg.png" = tmp_png)
)

output_path <- tempfile(fileext = ".css")
sass(layer, output = output_path, write_attachments = TRUE)
#> [1] "/tmp/RtmpXei65c/file2b4b795a50db.css"