sass_layer {sass}

Bundling Sass layers

Description

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.

Usage

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(core)

# 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))
sass(sass_bundle(core, red_layer, sass_layer(green)))

# 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
core_slim <- sass_bundle_remove(core_layers, "red")
sass(core_slim)


# 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()

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)