Support {bslib} in Rhino

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: rhino
 Title: A Framework for Enterprise Shiny Applications
-Version: 1.8.0
+Version: 1.8.0.9000
 Authors@R:
   c(
     person("Kamil", "Żyła", role = c("aut", "cre"), email = "[email protected]"),

NEWS.md

@@ -1,4 +1,8 @@
-# rhino 1.8.0
+# rhino (development version)
+
+1. Added `sass: custom` configuration option for cleaner integration with `bslib`.
+
+# [rhino 1.8.0](https://github.com/Appsilon/rhino/releases/tag/v1.8.0)
 
 1. All linter functions migrated to `box.linters`. New rhino projects will be configured to use linters from `box.linters`.
 2. Updated GitHub Workflow template triggers.

R/app.R

@@ -107,7 +107,8 @@ load_main <- function(use_source, expect_shiny_module) {
     } else {
       main <- load_main_box()
     }
-    normalize_main(main, expect_shiny_module)
+    main <- normalize_main(main, expect_shiny_module)
+    list(ui = with_head_tags(main$ui), server = main$server)
   }
   load_main_with_autoreload(loader)
 }
@@ -164,6 +165,25 @@ normalize_server <- function(server, is_module = FALSE) {
   }
 }
 
+with_head_tags <- function(ui) {
+  head <- shiny::tags$head(
+    react_support(), # Needs to go before `app.min.js`, which defines the React components.
+    if (fs::file_exists("app/static/js/app.min.js")) {
+      shiny::tags$script(src = "static/js/app.min.js")
+    },
+    if (fs::file_exists("app/static/css/app.min.css")) {
+      shiny::tags$link(rel = "stylesheet", href = "static/css/app.min.css", type = "text/css")
+    },
+    if (fs::file_exists("app/static/favicon.ico")) {
+      shiny::tags$link(rel = "icon", href = "static/favicon.ico", sizes = "any")
+    }
+  )
+  force(ui) # Avoid the pitfalls of lazy evaluation.
+  function(request) {
+    shiny::tagList(head, ui(request))
+  }
+}
+
 load_main_with_autoreload <- function(loader) {
   # There are two key components to make `shiny.autoreload` work:
   # 1. When app files are modified, the autoreload callback updates the `main` module in `app_env`.
@@ -232,24 +252,11 @@ warn_on_error <- function(expr, text) {
 
 make_app <- function(main) {
   shiny::shinyApp(
-    ui = with_head_tags(main$ui),
+    ui = main$ui,
     server = fix_server(main$server)
   )
 }
 
-with_head_tags <- function(ui) {
-  head <- shiny::tags$head(
-    react_support(), # Needs to go before `app.min.js`, which defines the React components.
-    shiny::tags$script(src = "static/js/app.min.js"),
-    shiny::tags$link(rel = "stylesheet", href = "static/css/app.min.css", type = "text/css"),
-    shiny::tags$link(rel = "icon", href = "static/favicon.ico", sizes = "any")
-  )
-  force(ui) # Avoid the pitfalls of lazy evaluation.
-  function(request) {
-    shiny::tagList(head, ui(request))
-  }
-}
-
 # A workaround for issues with server reloading:
 # https://github.com/Appsilon/rhino/issues/157
 #

R/config.R

@@ -29,7 +29,7 @@ positive_integer_validator <- list(
 rhino_config_definition <- list(
   list(
     name = "sass",
-    validator = option_validator("node", "r"),
+    validator = option_validator("node", "r", "custom"),
     required = TRUE
   ),
   list(

R/tools.R

@@ -260,6 +260,13 @@ lint_js <- function(fix = FALSE) {
 #' @export
 build_sass <- function(watch = FALSE) {
   config <- read_config()$sass
+  if (config == "custom") {
+    cli::cli_alert_warning(
+      "Using 'custom' configuration for 'sass'. Exiting without doing anything."
+    )
+    return(invisible())
+  }
+
   if (config == "node") {
     tryCatch(
       build_sass_node(watch = watch),

inst/WORDLIST

@@ -1,7 +1,6 @@
 Addin
 Addins
 Appsilon
-Boxifying
 ESLint
 Init
 JS
@@ -23,6 +22,7 @@ UI
 Webpack
 autoreload
 blogpost
+bslib
 conf
 config
 devtools
@@ -56,6 +56,8 @@ scalable
 shinyapps
 shinymanager
 shinytest
+theming
+tooltips
 ui
 unintuitive
 usethis

pkgdown/_pkgdown.yml

@@ -94,6 +94,8 @@ navbar:
         - text: UI
         - text: Use shiny.fluent
           href: articles/how-to/use-shiny-fluent.html
+        - text: Use bslib
+          href: articles/how-to/use-bslib.html
         - text: -------
         - text: Authentication
         - text: Use shinymanager

vignettes/explanation/rhino-yml.Rmd

@@ -7,26 +7,28 @@ vignette: >
   %\VignetteEncoding{UTF-8}
 ---
 
-<p class="alert alert-warning">
-  This article is a stub. We are working to edit and expand it.
-</p>
-
 # Configure Rhino with `rhino.yml`
+
 Rhino uses its own `rhino.yml` config file where you can set a few options on how it works in your app. Currently available
 options are described below.
 
 ## `rhino.yml` options
+
 ```yaml
-sass: string               # required | one of: "node", "r"
+sass: string               # required | one of: "node", "r", "custom"
 legacy_entrypoint: string  # optional | one of: "app_dir", "source", "box_top_level"
 ```
 
 ### `sass`
-Configures whether [Sass](https://sass-lang.com/) should be built
-using the [R package](https://cran.r-project.org/package=sass)
-or the [Node.js package](https://www.npmjs.com/package/sass).
+
+This option controls the behavior `rhino::build_sass()`:
+* `node`: Build Sass using the [Node.js package](https://www.npmjs.com/package/sass).
+* `r`: Build Sass using the [R package](https://cran.r-project.org/package=sass).
+* `custom`: Do nothing. Useful when bundling custom Sass with `bslib::bs_theme()`.
+
 Read more in [Explanation: Node.js - JavaScript and Sass tools](https://appsilon.github.io/rhino/articles/explanation/node-js-javascript-and-sass-tools.html).
 
 ### `legacy_entrypoint`
+
 This setting is useful when migrating an existing Shiny application to Rhino. For more details see
 [`rhino::app()` details section](https://appsilon.github.io/rhino/reference/app.html#details-1).

vignettes/how-to/use-bslib.Rmd

@@ -0,0 +1,61 @@
+---
+title: "How-to: Use bslib with Rhino"
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{How-to: Use bslib with Rhino}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+# Introduction
+
+The `bslib` R package is a UI toolkit based on Bootstrap.
+Shiny uses it under the hood for its default appearance,
+but it's also possible to use `bslib` directly to gain some benefits:
+1. Additional components (e.g. value boxes, accordions, tooltips).
+2. Customization and theming.
+3. A refined interface (e.g. `bslib::page_sidebar` instead of `shiny::sidebarLayout`).
+4. Access to the latest Bootstrap (v5).
+
+Rhino comes with built-in support for writing custom Sass code in `app/styles/main.scss`.
+This guide explains how to combine `bslib` and custom Sass code.
+
+If you don't want to write any custom Sass,
+you can use `bslib` as you would normally without any additional setup.
+
+# Steps
+
+1. Add `bslib` to project dependencies: `rhino::pkg_install("bslib")`.
+2. Use `sass: custom` configuration option in `rhino.yml`.
+3. Bundle Rhino Sass with `bslib` theme, e.g.:
+
+```r
+theme <- bslib$bs_theme() |>
+  bslib$bs_add_rules(sass$sass_file("app/styles/main.scss"))
+```
+
+You can create the `theme` object in `app/main.R` or in a dedicated file, e.g. `app/view/theme.R`.
+You need to define your UI using one of `bslib::page_*` layout functions,
+and pass the `theme` object as argument.
+
+You don't need to run `rhino::build_sass()`.
+Shiny will build it automatically when needed.
+
+With this setup you can use the `main.scss` file as you would normally,
+but with full access to Bootstrap and variables defined in `bs_theme()`.
+
+## Advanced use cases
+
+For advanced use cases, consider creating a complete [Sass layer](https://rstudio.github.io/sass/reference/sass_layer.html):
+
+```r
+theme <- bslib$bs_bundle(
+  bslib$bs_theme(),
+  sass$sass_layer(
+    functions = sass$sass_file("app/styles/functions.scss"),
+    defaults = sass$sass_file("app/styles/defaults.scss"),
+    mixins = sass$sass_file("app/styles/mixins.scss"),
+    rules = sass$sass_file("app/styles/rules.scss")
+  )
+)
+```