Package 'sass'

Description

Converts multiple types of inputs to a single Sass input string for sass().

Usage

as_sass(input)

Arguments

Value

a single character value to be supplied to sass().

References

https://sass-lang.com/documentation/at-rules/import

Examples

# Example of regular Sass input
as_sass("body { color: \"blue\"; }")

# There is support for adding variables
as_sass(
  list(
    list(color = "blue"),
   "body { color: $color; }"
   )
)


# Add a file name
someFile <- tempfile("variables")

# Overwrite color to red
write("$color: \"red\";", someFile)

input <-
  as_sass(
    list(
      list(color = "blue"),
      sass_file(someFile),
      "body { color: $color; }"
      )
   )

input

# The final body color is red
sass(input)

Description

Include font file(s) when defining a Sass variable that represents a CSS font-family property.

Usage

font_google(
  family,
  local = TRUE,
  cache = sass_file_cache(sass_cache_context_dir()),
  wght = NULL,
  ital = NULL,
  display = c("swap", "auto", "block", "fallback", "optional")
)

font_link(family, href)

font_face(
  family,
  src,
  weight = NULL,
  style = NULL,
  display = c("swap", "auto", "block", "fallback", "optional"),
  stretch = NULL,
  variant = NULL,
  unicode_range = NULL
)

font_collection(..., default_flag = TRUE, quote = TRUE)

is_font_collection(x)

Arguments

Details

These helpers must be used the named list approach to variable definitions, for example:

list(
  list("font-variable" = font_google("Pacifico")),
  list("body{font-family: $font-variable}")
)

Value

a sass_layer() holding an htmltools::htmlDependency() which points to the font files.

Font fallbacks

By default, font_google() downloads, caches, and serves the relevant font file(s) locally. By locally serving files, there's a guarantee that the font can render in any client browser, even when the client doesn't have internet access. However, when importing font files remotely (i.e., font_google(..., local = FALSE) or font_link()), it's a good idea to provide fallback font(s) in case the remote link isn't working (e.g., maybe the end user doesn't have an internet connection). To provide fallback fonts, use font_collection(), for example:

pacifico <- font_google("Pacifico", local = FALSE)
as_sass(list(
  list("font-variable" = font_collection(pacifico, "system-ui")),
  list("body{font-family: $font-variable}")
))

Default flags

These font helpers encourage best practice of adding a !default to Sass variable definitions, but the flag may be removed via font_collection() if desired.

as_sass(list("font-variable" = pacifico))
#> $font-variable: Pacifico !default;
as_sass(list("font-variable" = font_collection(pacifico, default_flag = F)))
#> $font-variable: Pacifico;

Serving non-Google fonts locally

Non-Google fonts may also be served locally with font_face(), but it requires downloading font file(s) and pointing src to the right location on disk. If you want src to be a relative file path (you almost certainly do), then you'll need to mount that resource path using something like shiny::addResourcePath() (for a shiny app) or servr::httd() (for static HTML).

References

https://developers.google.com/fonts/docs/css2

https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face

https://developer.mozilla.org/en-US/docs/Learn/CSS/Styling_text/Web_fonts

Examples

library(htmltools)

my_font <- list("my-font" = font_google("Pacifico"))
hello <- tags$body(
  "Hello",
  tags$style(
    sass(
      list(
        my_font,
        list("body {font-family: $my-font}")
      )
    )
  )
)

if (interactive()) {
  browsable(hello)
}

# Three different yet equivalent ways of importing a remotely-hosted Google Font
a <- font_google("Crimson Pro", wght = "200..900", local = FALSE)
b <- font_link(
  "Crimson Pro",
  href = "https://fonts.googleapis.com/css2?family=Crimson+Pro:[email protected]"
)
url <- "https://fonts.gstatic.com/s/crimsonpro/v13/q5uDsoa5M_tv7IihmnkabARboYF6CsKj.woff2"
c <- font_face(
  family = "Crimson Pro",
  style = "normal",
  weight = "200 900",
  src = paste0("url(", url, ") format('woff2')")
)

Description

Intended for use with sass()'s output argument for temporary file generation that is cache and options aware. In particular, this ensures that new redundant file(s) aren't generated on a sass() cache hit, and that the file's extension is suitable for the sass_options()'s output_style.

Usage

output_template(
  basename = "sass",
  dirname = basename,
  fileext = NULL,
  path = tempdir()
)

Arguments

Value

A function with two arguments: options and suffix. When called inside sass() with caching enabled, the caching key is supplied to suffix.

Examples

sass("body {color: red}", output = output_template())

func <- output_template(basename = "foo", dirname = "bar-")
func(suffix = "baz")

Description

Compile Sass to CSS using LibSass.

Usage

sass(
  input = NULL,
  options = sass_options_get(),
  output = NULL,
  write_attachments = NA,
  cache = sass_cache_get(),
  cache_key_extra = NULL
)

Arguments

Value

If output = NULL, the function returns a string value of the compiled CSS. If output is specified, the compiled CSS is written to a file and the filename is returned.

Caching

By default, caching is enabled, meaning that sass() avoids the possibly expensive re-compilation of CSS whenever the same options and input are requested. Unfortunately, in some cases, options and input alone aren't enough to determine whether new CSS output must be generated. For example, changes in local file imports that aren't captured through sass_file()/sass_import(), may lead to a false-positive cache hit. For this reason, developers are encouraged to capture such information in cache_key_extra (possibly with packageVersion('myPackage') if shipping Sass with a package), and users may want to disable caching altogether during local development by calling options(sass.cache=FALSE).

In some cases when developing and modifying .scss files, sass() might not detect changes, and keep using cached .css files instead of rebuilding them. To be safe, if you are developing a theme with sass, it's best to turn off caching by calling options(sass.cache=FALSE).

If caching is enabled, sass() will attempt to bypass the compilation process by reusing output from previous sass() calls that used equivalent inputs. This mechanism works by computing a cache key from each sass() call's input, option, and cache_key_extra arguments. If an object with that hash already exists within the cache directory, its contents are used instead of performing the compilation. If it does not exist, then compilation is performed and usual and the results are stored in the cache.

If a file that is included using sass_file() changes on disk (i.e. its last-modified time changes), its previous cache entries will effectively be invalidated (not removed from disk, but they'll no longer be matched). However, if a file imported using sass_file() itself imports other sass files using ⁠@import⁠, changes to those files are invisible to the cache and you can end up with stale results. To avoid this problem when developing sass code, it's best to disable caching with options(sass.cache=FALSE).

By default, the maximum size of the cache is 40 MB. If it grows past that size, the least-recently-used objects will be evicted from the cache to keep it under that size. Also by default, the maximum age of objects in the cache is one week. Older objects will be evicted from the cache.

To clear the default cache, call sass_cache_get()$reset().

See Also

https://sass-lang.com/guide

Examples

# Raw Sass input
sass("foo { margin: 122px * .3; }")

# List of inputs, including named variables
sass(list(
  list(width = "122px"),
  "foo { margin: $width * .3; }"
))

# Compile a .scss file
example_file <- system.file("examples/example-full.scss", package = "sass")
sass(sass_file(example_file))

# Import a file
tmp_file <- tempfile()
writeLines("foo { margin: $width * .3; }", tmp_file)
sass(list(
  list(width = "122px"),
  sass_file(tmp_file)
))

## Not run: 
# ======================
# Caching examples
# ======================
# Very slow to compile
fib_sass <- "@function fib($x) {
  @if $x <= 1 {
    @return $x
  }
  @return fib($x - 2) + fib($x - 1);
}

body {
  width: fib(27);
}"

# The first time this runs it will be very slow
system.time(sass(fib_sass))

# But on subsequent calls, it should be very fast
system.time(sass(fib_sass))

# sass() can be called with cache=NULL; it will be slow
system.time(sass(fib_sass, cache = NULL))

# Clear the cache
sass_cache_get()$reset()

## End(Not run)

## Not run: 
# Example of disabling cache by setting the default cache to NULL.

# Disable the default cache (save the original one first, so we can restore)
old_cache <- sass_cache_get()
sass_cache_set(NULL)
# Will be slow, because no cache
system.time(sass(fib_sass))

# Restore the original cache
sass_cache_set(old_cache)

## End(Not run)

Description

When caching is enabled, this function returns a sass_file_cache() object that sass()'s cache argument uses (by default) for caching Sass compilation. When caching is disabled (either by setting the sass.cache option to FALSE, NULL, or via shiny::devmode()), this function returns NULL (effectively telling sass() to not cache by default).

Usage

sass_cache_get()

Details

When caching is enabled, then this function returns a sass_file_cache() object that (by default) uses sass_cache_context_dir() for its directory. The directory can also be customized by providing the sass.cache option with either a filepath (as a string) or a full-blown sass_file_cache() object.

See Also

sass_cache_get_dir(), sass()

Description

This creates a file cache which is to be used by sass for caching generated .css files.

Usage

sass_file_cache(dir, max_size = 40 * 1024^2, max_age = Inf)

Arguments

Value

A FileCache object.

See Also

sass_cache_get(), sass_cache_context_dir(), FileCache

Examples

## Not run: 
# Create a cache with the default settings
cache <- sass_file_cache(sass_cache_context_dir())

# Clear the cache
cache$reset()

## End(Not run)

Description

Create an import statement to be used within your Sass file. See https://sass-lang.com/documentation/at-rules/import for more details.

Usage

sass_import(input, quote = TRUE)

sass_file(input)

Arguments

Details

sass_file() adds extra checks to make sure an appropriate file path exists given the input value.

Note that the LibSass compiler expects .sass files to use the Sass Indented Syntax.

Value

Fully defined Sass import string.

Examples

sass_import("foo")
sass_import("$foo", FALSE)

tmp_scss_file <- tempfile(fileext = ".scss")
writeLines("$color: red; body{ color: $color; }", tmp_scss_file)
sass_file(tmp_scss_file)
sass(sass_file(tmp_scss_file))

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

• 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)

Description

Specify compiler options for sass(). To customize options, either provide sass_options() directly to a sass() call or set options globally via sass_options_set(). When shiny::devmode() is enabled, sass_options_get() defaults source_map_embed and source_map_contents to TRUE.

Usage

sass_options(
  precision = 5,
  output_style = "expanded",
  indented_syntax = FALSE,
  include_path = "",
  source_comments = FALSE,
  indent_type = "space",
  indent_width = 2,
  linefeed = "lf",
  output_path = "",
  source_map_file = "",
  source_map_root = "",
  source_map_embed = FALSE,
  source_map_contents = FALSE,
  omit_source_map_url = FALSE
)

sass_options_get(...)

sass_options_set(...)

Arguments

Value

List of Sass compiler options to be used with sass(). For sass_options_set(), any previously set global options are returned.

Examples

x <- "foo { margin: 122px * .001; }"
sass(x)

# Provide options directly to sass()
sass(x, options = sass_options(precision = 1, output_style = "compact"))

# Or set some option(s) globally
old_options <- sass_options_set(precision = 1)
sass(x)

# Specify local options  while also respecting global options
sass(x, options = sass_options_get(output_style = "compact"))

# Restore original state
sass_options_set(old_options)

Description

Replaces the rules for a sass_layer() object with new rules, and compile it. This is useful when (for example) you want to compile a set of rules using variables derived from a theme, but you do not want the resulting CSS for the entire theme – just the CSS for the specific rules passed in.

Usage

sass_partial(
  rules,
  bundle,
  options = sass_options_get(),
  output = NULL,
  write_attachments = NA,
  cache = sass_cache_get(),
  cache_key_extra = NULL
)

Arguments

Examples

theme <- sass_layer(
  defaults = sass_file(system.file("examples/variables.scss", package = "sass")),
  rules = sass_file(system.file("examples/rules.scss", package = "sass"))
)

# Compile the theme
sass(theme)

# Sometimes we want to use the variables from the theme to compile other sass
my_rules <- ".someclass { background-color: $bg; color: $fg; }"
sass_partial(my_rules, theme)