rstudio · cpsievert · Mar 6, 2023 · Mar 6, 2023 · Mar 6, 2023 · Mar 6, 2023
diff --git a/.gitignore b/.gitignore
@@ -19,10 +19,6 @@ inst/yarn.lock
 
 inst/rmarkdown/templates/*/skeleton/skeleton.html
 
-vignettes/navbar-global
-vignettes/navbar-global-fillable
-vignettes/navbar-local-scroll
-vignettes/navbar-local-fill
-vignettes/page-scroll
-vignettes/page-fill
-vignettes/page-fill-double
+vignettes/*.html
+# rendered examples that appear in iframes
+vignettes/examples
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -60,6 +60,7 @@ Collate:
     'card.R'
     'deprecated.R'
     'files.R'
+    'fill.R'
     'imports.R'
     'layout.R'
     'nav-items.R'
@@ -89,9 +90,11 @@ Config/Needs/website:
     crosstalk,
     dplyr,
     DT,
+    ggplot2,
     glue,
     htmlwidgets,
     leaflet,
+    lorem,
     plotly,
     purrr,
     rprojroot,

diff --git a/NAMESPACE b/NAMESPACE
@@ -1,5 +1,9 @@
 # Generated by roxygen2: do not edit by hand
 
+S3method(is_fill,default)
+S3method(is_fill,htmlwidget)
+S3method(is_fillable,default)
+S3method(is_fillable,htmlwidget)
 S3method(print,bslib_fragment)
 S3method(print,bslib_page)
 export(accordion)
@@ -11,6 +15,9 @@ export(accordion_panel_remove)
 export(accordion_panel_set)
 export(accordion_panel_update)
 export(as.card_item)
+export(as_fill)
+export(as_fill_carrier)
+export(as_fillable)
 export(bootstrap)
 export(bootstrap_sass)
 export(bootswatch_themes)
@@ -63,6 +70,9 @@ export(font_google)
 export(font_link)
 export(is.card_item)
 export(is_bs_theme)
+export(is_fill)
+export(is_fill_carrier)
+export(is_fillable)
 export(layout_column_wrap)
 export(layout_sidebar)
 export(nav)
@@ -86,6 +96,7 @@ export(navs_tab)
 export(navs_tab_card)
 export(page)
 export(page_fill)
+export(page_fillable)
 export(page_fixed)
 export(page_fluid)
 export(page_navbar)
@@ -98,6 +109,7 @@ export(sidebar_close)
 export(sidebar_open)
 export(theme_bootswatch)
 export(theme_version)
+export(undo_fill)
 export(value_box)
 export(version_default)
 export(versions)

diff --git a/NEWS.md b/NEWS.md
@@ -1,19 +1,35 @@
 # bslib 0.4.2.9000
 
+This major release adds [sidebar layouts](https://rstudio.github.io/bslib/articles/sidebars.html), [accordions](https://rstudio.github.io/bslib/articles/sidebars.html#sidebar-accordions), and makes many improvements to support for [filling layouts](https://rstudio.github.io/bslib/articles/filling.html).
+
+Although `{bslib}` is still maturing, and will continue to receiving new UI features, we now see it as a viable replacement for `{shinydashboard}`. 
+
 ## Breaking changes
 
-* `page_fill()` now produces a `<body>` tag with `display:flex` (instead of `display:block`). It also no longer fills the windows height on mobile (i.e., narrow screens) by default. If this breaks existing behavior, consider using `shiny::fillPage(theme = bslib::bs_theme(), ...)` instead of `page_fill()`. (#479)
-* `page_navbar()` (and consequently `shiny::navbarPage()`) no longer implicitly wrap `header` and `footer` in an additional `shiny::fluidRow()` container for Bootstrap 5+ (i.e., `theme = bs_theme()`). Similarly, `navs_bar()` no longer does this (for any version of Bootstrap). If this breaks existing behavior, consider wrapping the `header` and `footer` value(s) with `shiny::fluidRow()`). (#479)
+* `card_body()` now provides the same behavior as `card_body_fill()` (i.e., it is both a fillable container and fill item) by default. And, now, since `card_body()` can do everything `card_body_fill()` can do, `card_body_fill()` has been deprecated. The main benefit of this change is that `card(full_screen = TRUE, ...)` with output(s) passed to `...` "just works" in an intuitive way. To revert to the previous behavior, set `fillable = FALSE` and `fill = FALSE` in calls to `card_body()` and set `wrapper = function(x) card_body(x, fillable = FALSE, fill = FALSE)` in calls to `card()`. (#498)
+* `layout_column_wrap()`'s `fill` argument now controls whether or not the _layout container_ is allowed to grow/shrink to fit a fillable container (e.g., `page_fillable()`). It also gains a new `fillable` argument for controlling whether _UI elements_ are allowed to fill their row height. This is more consistent with the meaning of `fill` in other functions, like `card()`, `card_body()`, `layout_sidebar()`, etc. (#498)
+* `page_fill()` (now called `page_fillable()`) had several breaking changes (listed below). If this breaks existing behavior, consider using `shiny::fillPage(theme = bslib::bs_theme(), ...)` instead of `page_fill()`. 
+  * `page_fill()` now produces a `<body>` tag with `display:flex` (instead of `display:block`).
+  * `page_fill()` no longer fills the windows height on mobile (i.e., narrow screens) by default (set `fill_mobile = TRUE` to restore the old behavior). 
+  * `page_fill()` now adds `padding` and `gap` by default, set `padding = 0` and `gap = 0` to restore the old behavior.
+* `page_navbar()` (and consequently `shiny::navbarPage()`) no longer implicitly wrap `header` and `footer` in an additional `shiny::fluidRow()` container for Bootstrap 5+ (i.e., `theme = bs_theme()`) usage. Similarly, `navs_bar()` no longer does this (for any version of Bootstrap). If this breaks existing behavior, consider wrapping the `header` and `footer` value(s) with `shiny::fluidRow()`). (#479)
 * Defaults for the following Bootstrap 5 Sass variables were changed to `null`: `$accordion-button-active-bg`, `$accordion-button-active-color`, and `$accordion-icon-active-color`. To restore the old behavior, do `bs_add_variables(theme, "accordion-button-active-bg" = "tint-color($component-active-bg, 90%)", "accordion-button-active-color" = "shade-color($primary, 10%)", "accordion-icon-active-color" = "$accordion-button-active-color", .where = "declarations")`. (#475)
 
 ## New features
 
 * Added a `sidebar()` API for creating sidebar layouts in various contexts. See [the article](https://rstudio.github.io/bslib/articles/sidebars.html) to learn more. (#479)
-* Adds a new `accordion()` API. See `help(accordion)` for examples and details. Note also `accordion()` is designed to [work well inside a `sidebar()`](https://rstudio.github.io/bslib/articles/sidebars.html#accordions). (#475)
+* Adds a new `accordion()` API. See `help(accordion)` for examples and details. Note also `accordion()` is designed to [work well inside a `sidebar()`](https://rstudio.github.io/bslib/articles/sidebars.html#sidebar-accordions). (#475)
 * `page_navbar()`, `navs_tab_card()`, and ` navs_pill_card()` gain a `sidebar` argument for putting a `sidebar()` on every page/tab/pill. (#479)
 * `page_navbar()` gains a `fillable` argument to make the content of particular page(s) fit the window/card. (#479)
-* `page_fill()` is now considered a `fillable` container, meaning that `fill` items like `card()`, `layout_column_wrap()`, and `layout_sidebar()` now grow/shrink to fit the window's height when they appear as a direct child of `page_fill()`. (#479)
-* `page_navbar()` and `page_fill()` gain `fill_mobile` arguments to control whether the page should grow/shrink to fit the viewport on mobile. (#479)
+* `page_fillable()` (aka, `page_fill()`) is now considered a `fillable` container, meaning that `fill` items like `card()`, `layout_column_wrap()`, and `layout_sidebar()` now grow/shrink to fit the window's height when they appear as a direct child of `page_fillable()`. (#479)
+* `page_navbar()` and `page_fillable()` gain `fill_mobile` arguments to control whether the page should grow/shrink to fit the viewport on mobile. (#479)
+* `card()`, `value_box()`, and `card_image()` gain `max_height` and `fill` arguments. (#498)
+* Added new `as_fill()`, `as_fillable()`, `as_fill_carrier()`, `is_fill()`, and `is_fillable()` for testing and coercing potential to fill. (#498)
+
+## Deprecations
+
+* `card_body_fill()` has been deprecated in favor of `card_body()`. (#498)
+* `page_fill()` has been deprecated in favor of `page_fillable()`. (#498)
 
 
 # bslib 0.4.2

diff --git a/R/card.R b/R/card.R
@@ -8,20 +8,22 @@
 #'   tag][htmltools::tags] (which includes card items such as [card_body()].
 #'   Named arguments become HTML attributes on returned UI element.
 #' @param full_screen If `TRUE`, an icon will appear when hovering over the card
-#'   body. Clicking the icon expands the card to fit viewport size. Consider
-#'   pairing this feature with [card_body_fill()] to get output that responds to
-#'   changes in the size of the card.
+#'   body. Clicking the icon expands the card to fit viewport size.
 #' @param height Any valid [CSS unit][htmltools::validateCssUnit] (e.g.,
-#'   `height="200px"`).
+#'   `height="200px"`). Doesn't apply when a card is made `full_screen`
+#'   (in this case, consider setting a `height` in [card_body()]).
+#' @param max_height Any valid [CSS unit][htmltools::validateCssUnit] (e.g.,
+#'   `max_height="200px"`). Doesn't apply when a card is made `full_screen`
+#'   (in this case, consider setting a `max_height` in [card_body()]).
+#' @param fill Whether or not to allow the card to grow/shrink to fit a
+#'   fillable container with an opinionated height (e.g., `page_fillable()`).
 #' @param class Additional CSS classes for the returned UI element.
 #' @param wrapper A function (which returns a UI element) to call on unnamed
 #'   arguments in `...` which are not already card item(s) (like
 #'   [card_header()], [card_body()], etc.). Note that non-card items are grouped
 #'   together into one `wrapper` call (e.g. given `card("a", "b",
 #'   card_body("c"), "d")`, `wrapper` would be called twice, once with `"a"` and
-#'   `"b"` and once with `"d"`). Consider setting `wrapper` to [card_body_fill]
-#'   if the entire card wants responsive sizing or `NULL` to avoid wrapping
-#'   altogether
+#'   `"b"` and once with `"d"`).
 #'
 #' @return A [htmltools::div()] tag.
 #'
@@ -50,7 +52,7 @@
 #'   )
 #' }
 #'
-card <- function(..., full_screen = FALSE, height = NULL, class = NULL, wrapper = card_body) {
+card <- function(..., full_screen = FALSE, height = NULL, max_height = NULL, fill = TRUE, class = NULL, wrapper = card_body) {
 
   args <- rlang::list2(...)
   argnames <- rlang::names2(args)
@@ -60,13 +62,16 @@ card <- function(..., full_screen = FALSE, height = NULL, class = NULL, wrapper
 
   tag <- div(
     class = "card bslib-card",
-    style = css(height = validateCssUnit(height)),
+    style = css(
+      height = validateCssUnit(height),
+      max_height = validateCssUnit(max_height)
+    ),
     !!!attribs,
     !!!children,
     if (full_screen) full_screen_toggle()
   )
 
-  tag <- bindFillRole(tag, container = TRUE, item = TRUE)
+  tag <- bindFillRole(tag, container = TRUE, item = fill)
   tag <- tagAppendAttributes(tag, class = class)
 
   as_fragment(
@@ -113,8 +118,14 @@ as_card_items <- function(children, wrapper) {
 #' @param ... Unnamed arguments can be any valid child of an [htmltools
 #'   tag][htmltools::tags]. Named arguments become HTML attributes on returned
 #'   UI element.
-#' @param fill whether to allow the `card_body()` to grow and shrink to fit its
-#'   `card()`.
+#' @param min_height,max_height,max_height_full_screen Any valid [CSS length
+#'   unit][htmltools::validateCssUnit()].
+#' @param fillable Whether or not the card item should be a fillable (i.e.
+#'   flexbox) container.
+#' @param fill Whether to allow this element to grow/shrink to fit its `card()`
+#'   container.
+#' @param gap A [CSS length unit][htmltools::validateCssUnit()] defining the
+#'   `gap` (i.e., spacing) between elements provided to `...`.
 #' @inheritParams card
 #'
 #' @return An [htmltools::div()] tag.
@@ -126,43 +137,38 @@ as_card_items <- function(children, wrapper) {
 #'   columns inside a card).
 #'
 #' @describeIn card_body A general container for the "main content" of a [card()].
-card_body <- function(..., fill = FALSE, height = NULL, class = NULL) {
-  card_body_(
-    fill_item = fill,
-    height = height,
-    class = class,
-    ...
-  )
-}
+card_body <- function(..., fillable = TRUE, min_height = NULL, max_height = NULL, max_height_full_screen = max_height, height = NULL, gap = NULL, fill = TRUE, class = NULL) {
 
-#' @describeIn card_body Similar to `card_body(fill = TRUE)`, but also marks the
-#'   return element as a "fill container" (via [htmltools::bindFillRole()]) so
-#'   that its immediate children are allowed to grow and shrink to fit.
-#' @param gap A [CSS length unit][htmltools::validateCssUnit()] defining the
-#'   `gap` (i.e., spacing) between elements provided to `...`.
-#' @param max_height,max_height_full_screen,min_height Any valid [CSS length unit][htmltools::validateCssUnit()].
-#' @export
-card_body_fill <- function(..., gap = NULL, max_height = NULL, max_height_full_screen = max_height, min_height = NULL, class = NULL) {
-
-  register_runtime_package_check("`card_body_fill()`", "shiny", "1.7.3.9001")
-  register_runtime_package_check("`card_body_fill()`", "htmlwidgets", "1.5.4.9001")
+  if (fillable) {
+    register_runtime_package_check("`card_body()`", "shiny", "1.7.4")
+    register_runtime_package_check("`card_body()`", "htmlwidgets", "1.6.0")
+  }
 
-  card_body_(
-    fill_item = TRUE,
-    fill_container = TRUE,
-    class = class,
-    style = htmltools::css(
-      gap = validateCssUnit(gap),
+  tag <- div(
+    class = "card-body",
+    style = css(
       min_height = validateCssUnit(min_height),
       "--bslib-card-body-max-height" = validateCssUnit(max_height),
       "--bslib-card-body-max-height-full-screen" = validateCssUnit(max_height_full_screen),
       margin_top = "auto",
-      margin_bottom = "auto"
+      margin_bottom = "auto",
+      # .card-body already adds `flex: 1 1 auto` so make sure to override it
+      flex = if (fill) "1 1 auto" else "0 0 auto",
+      gap = validateCssUnit(gap),
+      height = validateCssUnit(height)
     ),
     ...
   )
+
+  tag <- bindFillRole(tag, item = fill, container = fillable)
+
+  # Make sure user has the opportunity to override the classes added by bindFillRole()
+  tag <- tagAppendAttributes(tag, class = class)
+
+  as.card_item(tag)
 }
 
+
 #' @describeIn card_body Similar to `card_header()` but without the border and background color.
 #' @param container a function to generate an HTML element.
 #' @export
@@ -172,26 +178,6 @@ card_title <- function(..., container = htmltools::h5) {
   )
 }
 
-card_body_ <- function(..., fill_item = FALSE, fill_container = FALSE, height = NULL, class = NULL, container = htmltools::div) {
-
-  tag <- container(
-    class = "card-body",
-    style = css(
-      height = validateCssUnit(height),
-      # .card-body already adds `flex: 1 1 auto` so make sure to override it
-      flex = if (fill_item) "1 1 auto" else "0 0 auto"
-    ),
-    ...
-  )
-
-  tag <- bindFillRole(tag, item = fill_item, container = fill_container)
-
-  # Make sure user has the opportunity to override the classes added by bindFillRole()
-  tag <- tagAppendAttributes(tag, class = class)
-
-  as.card_item(tag)
-}
-
 
 #' @describeIn card_body A header (with border and background color) for the `card()`. Typically appears before a `card_body()`.
 #' @param container a function that generates an [htmltools tag][htmltools::tags].
@@ -222,7 +208,7 @@ card_footer <- function(..., class = NULL) {
 #' @export
 card_image <- function(
   file, ..., href = NULL, border_radius = c("top", "bottom", "all", "none"),
-  mime_type = NULL, class = NULL, height = NULL, width = NULL, container = card_body_fill) {
+  mime_type = NULL, class = NULL, height = NULL, fill = TRUE, width = NULL, container = card_body) {
 
   src <- NULL
   if (length(file) > 0) {
@@ -248,7 +234,7 @@ card_image <- function(
     ...
   )
 
-  image <- bindFillRole(image, item = TRUE)
+  image <- bindFillRole(image, item = fill)
   image <- tagAppendAttributes(image, class = class)
 
   if (!is.null(href)) {

diff --git a/R/deprecated.R b/R/deprecated.R
@@ -124,3 +124,18 @@ bs_add_declarations <- function(theme, declarations) {
   .Deprecated("bs_add_mixins")
   bs_bundle(theme, sass_layer(declarations = declarations))
 }
+
+
+#' @rdname deprecated
+#' @export
+card_body_fill <- function(...) {
+  .Deprecated("card_body", old = "card_body_fill")
+  card_body(...)
+}
+
+#' @rdname deprecated
+#' @export
+page_fill <- function(...) {
+  .Deprecated("page_fillable", old = "page_fill")
+  page_fillable(...)
+}