diff --git a/R/accordion.R b/R/accordion.R index 4f2696719..68def9eaf 100644 --- a/R/accordion.R +++ b/R/accordion.R @@ -1,5 +1,8 @@ #' Create a vertically collapsing accordion #' +#' @description +#' `r lifecycle::badge("experimental")` +#' #' @param ... Named arguments become attributes on the `
` #' element. Unnamed arguments should be `accordion_panel()`s. #' @param id If provided, you can use `input$id` in your server logic to @@ -18,7 +21,7 @@ #' #' @export #' @seealso [accordion_panel_set()] -#' @examplesIf interactive() +#' @examplesIf rlang::is_interactive() #' #' items <- lapply(LETTERS, function(x) { #' accordion_panel(paste("Section", x), paste("Some narrative for section", x)) @@ -161,6 +164,9 @@ accordion_panel <- function(title, ..., value = title, icon = NULL) { #' Dynamically update accordions #' +#' @description +#' `r lifecycle::badge("experimental")` +#' #' Dynamically (i.e., programmatically) update/modify [`accordion()`]s in a #' Shiny app. These functions require an `id` to be provided to the #' `accordion()` and must also be called within an active Shiny session. diff --git a/R/breakpoints.R b/R/breakpoints.R index 193689818..5c8c238db 100644 --- a/R/breakpoints.R +++ b/R/breakpoints.R @@ -1,16 +1,21 @@ #' Define breakpoint values #' -#' A generic constructor for responsive breakpoints. +#' @description +#' `r lifecycle::badge("experimental")` #' +#' A generic constructor for responsive breakpoints. #' @param sm Values to apply at the `sm` breakpoint. #' @param md Values to apply at the `md` breakpoint. #' @param lg Values to apply at the `lg` breakpoint. #' @param ... Other breakpoints (e.g., `xl`). #' +#' @seealso [layout_columns()] #' @references #' +#' @examples +#' breakpoints(sm = c(4, 4, 4), md = c(3, 3, 6), lg = c(-2, 8, -2)) +#' #' @export -#' @seealso [layout_columns()] breakpoints <- function(..., sm = NULL, md = NULL, lg = NULL) { breaks <- dropNulls( rlang::list2(..., sm = sm, md = md, lg = lg) diff --git a/R/card.R b/R/card.R index 9cb984a25..0ad0a8e3b 100644 --- a/R/card.R +++ b/R/card.R @@ -1,5 +1,8 @@ #' A Bootstrap card component #' +#' @description +#' `r lifecycle::badge("experimental")` +#' #' A general purpose container for grouping related UI elements together with a #' border and optional padding. To learn more about [card()]s, see [this #' article](https://rstudio.github.io/bslib/articles/cards.html). diff --git a/R/input-dark-mode.R b/R/input-dark-mode.R index bd9b7be99..6c80e4e3e 100644 --- a/R/input-dark-mode.R +++ b/R/input-dark-mode.R @@ -1,5 +1,8 @@ #' Dark mode input control #' +#' @description +#' `r lifecycle::badge("experimental")` +#' #' Creates a button that toggles between dark and light modes, specifically for #' toggling between light and dark [Bootstrap color #' modes](https://getbootstrap.com/docs/5.3/customize/color-modes/) -- a new diff --git a/R/input-switch.R b/R/input-switch.R index dd370b3bd..2502581dd 100644 --- a/R/input-switch.R +++ b/R/input-switch.R @@ -1,5 +1,8 @@ #' Switch input control #' +#' @description +#' `r lifecycle::badge("experimental")` +#' #' Create an on-off style switch control for specifying logical values. #' #' @examplesIf interactive() diff --git a/R/layout.R b/R/layout.R index 5c174ee43..68b927514 100644 --- a/R/layout.R +++ b/R/layout.R @@ -1,5 +1,8 @@ #' A grid-like, column-first, layout #' +#' @description +#' `r lifecycle::badge("experimental")` +#' #' Wraps a 1d sequence of UI elements into a 2d grid. The number of columns (and #' rows) in the grid dependent on the column `width` as well as the size of the #' display. For more explanation and illustrative examples, see [here](https://rstudio.github.io/bslib/articles/cards.html#multiple-cards) diff --git a/R/page.R b/R/page.R index a06df3730..e90e1697b 100644 --- a/R/page.R +++ b/R/page.R @@ -28,7 +28,8 @@ page <- function(..., title = NULL, theme = bs_theme(), lang = NULL) { ) } -#' @rdname page +#' @describeIn page A \pkg{bslib} wrapper for [shiny::fluidPage()], a fluid +#' Bootstrap-based page layout that extends to the full viewport width. #' @inheritParams shiny::fluidPage #' @export page_fluid <- function(..., title = NULL, theme = bs_theme(), lang = NULL) { @@ -38,7 +39,9 @@ page_fluid <- function(..., title = NULL, theme = bs_theme(), lang = NULL) { ) } -#' @rdname page +#' @describeIn page A \pkg{bslib} wrapper for [shiny::fixedPage()], a fixed +#' Bootstrap-based page layout where the page content container is centered +#' horizontally and its width is constrained. #' @inheritParams shiny::fixedPage #' @export page_fixed <- function(..., title = NULL, theme = bs_theme(), lang = NULL) { @@ -48,7 +51,8 @@ page_fixed <- function(..., title = NULL, theme = bs_theme(), lang = NULL) { ) } -#' @rdname page +#' @describeIn page `r lifecycle::badge("experimental")` A Bootstrap-based page +#' layout whose contents fill the full height and width of the browser window. #' @param padding Padding to use for the body. This can be a numeric vector #' (which will be interpreted as pixels) or a character vector with valid CSS #' lengths. The length can be between one and four. If one, then that value @@ -87,6 +91,9 @@ validateCssPadding <- function(padding = NULL) { #' A sidebar page (i.e., dashboard) #' +#' @description +#' `r lifecycle::badge("experimental")` +#' #' Create a dashboard layout with a full-bleed header (`title`) and [sidebar()]. #' #' @inheritParams layout_sidebar @@ -103,7 +110,7 @@ validateCssPadding <- function(padding = NULL) { #' @seealso [card()] for wrapping outputs in the 'main' content area. #' @seealso [value_box()] for highlighting values. #' -#' @examplesIf interactive() +#' @examplesIf rlang::is_interactive() #' #' library(shiny) #' library(ggplot2) diff --git a/R/popover.R b/R/popover.R index c3e7928a6..461ff4e2e 100644 --- a/R/popover.R +++ b/R/popover.R @@ -1,5 +1,8 @@ #' Add a popover to a UI element #' +#' @description +#' `r lifecycle::badge("experimental")` +#' #' Display additional information when clicking on a UI element (typically a #' button). #' diff --git a/R/sidebar.R b/R/sidebar.R index d341daea0..f7af50c6d 100644 --- a/R/sidebar.R +++ b/R/sidebar.R @@ -1,7 +1,10 @@ #' Sidebar layouts #' -#' @description Create a collapsing sidebar layout by providing a `sidebar()` -#' object to the `sidebar` argument of: +#' @description +#' `r lifecycle::badge("experimental")` +#' +#' Create a collapsing sidebar layout by providing a `sidebar()` object to the +#' `sidebar` argument of: #' #' * [page_sidebar()] #' * Creates a "page-level" sidebar. diff --git a/R/tooltip.R b/R/tooltip.R index 25e8257d3..2d19df46a 100644 --- a/R/tooltip.R +++ b/R/tooltip.R @@ -1,5 +1,8 @@ #' Add a tooltip to a UI element #' +#' @description +#' `r lifecycle::badge("experimental")` +#' #' Display additional information when focusing (or hovering over) a UI element. #' #' @param trigger A UI element (i.e., [htmltools tag][htmltools::tags]) to serve diff --git a/R/value-box.R b/R/value-box.R index 86be43680..d060b5bff 100644 --- a/R/value-box.R +++ b/R/value-box.R @@ -1,5 +1,8 @@ #' Value box #' +#' @description +#' `r lifecycle::badge("experimental")` +#' #' An opinionated ([card()]-powered) box, designed for displaying a `value` and #' `title`. Optionally, a `showcase` can provide for context for what the #' `value` represents (for example, it could hold a [bsicons::bs_icon()], or diff --git a/README.Rmd b/README.Rmd index aa95c38ae..d60c2bb31 100644 --- a/README.Rmd +++ b/README.Rmd @@ -4,7 +4,9 @@ output: github_document -[![CRAN status](https://www.r-pkg.org/badges/version/bslib)](https://cran.r-project.org/package=bslib) [![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html) [![R build status](https://github.com/rstudio/bslib/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/rstudio/bslib/actions) +[![CRAN status](https://www.r-pkg.org/badges/version/bslib)](https://cran.r-project.org/package=bslib) +[![bslib status badge](https://rstudio.r-universe.dev/badges/bslib)](https://rstudio.r-universe.dev/bslib) +[![R build status](https://github.com/rstudio/bslib/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/rstudio/bslib/actions) diff --git a/README.md b/README.md index 73cfefab0..90875586f 100644 --- a/README.md +++ b/README.md @@ -3,8 +3,8 @@ [![CRAN status](https://www.r-pkg.org/badges/version/bslib)](https://cran.r-project.org/package=bslib) -[![Lifecycle: -experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html) +[![bslib status +badge](https://rstudio.r-universe.dev/badges/bslib)](https://rstudio.r-universe.dev/bslib) [![R build status](https://github.com/rstudio/bslib/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/rstudio/bslib/actions) diff --git a/man/accordion.Rd b/man/accordion.Rd index 8886984e3..f64e8e6f3 100644 --- a/man/accordion.Rd +++ b/man/accordion.Rd @@ -44,10 +44,10 @@ when \code{multiple=TRUE}.} \item{icon}{A \link[htmltools:builder]{htmltools::tag} child (e.g., \code{\link[bsicons:bs_icon]{bsicons::bs_icon()}}) which is positioned just before the \code{title}.} } \description{ -Create a vertically collapsing accordion +\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}} } \examples{ -\dontshow{if (interactive()) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} +\dontshow{if (rlang::is_interactive()) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} items <- lapply(LETTERS, function(x) { accordion_panel(paste("Section", x), paste("Some narrative for section", x)) diff --git a/man/accordion_panel_set.Rd b/man/accordion_panel_set.Rd index 308e2ae24..c9a2b22f4 100644 --- a/man/accordion_panel_set.Rd +++ b/man/accordion_panel_set.Rd @@ -63,6 +63,8 @@ element. Unnamed arguments should be \code{accordion_panel()}s.} \item{icon}{A \link[htmltools:builder]{htmltools::tag} child (e.g., \code{\link[bsicons:bs_icon]{bsicons::bs_icon()}}) which is positioned just before the \code{title}.} } \description{ +\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}} + Dynamically (i.e., programmatically) update/modify \code{\link[=accordion]{accordion()}}s in a Shiny app. These functions require an \code{id} to be provided to the \code{accordion()} and must also be called within an active Shiny session. diff --git a/man/breakpoints.Rd b/man/breakpoints.Rd index 444c6c991..faff491eb 100644 --- a/man/breakpoints.Rd +++ b/man/breakpoints.Rd @@ -16,7 +16,13 @@ breakpoints(..., sm = NULL, md = NULL, lg = NULL) \item{lg}{Values to apply at the \code{lg} breakpoint.} } \description{ +\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}} + A generic constructor for responsive breakpoints. +} +\examples{ +breakpoints(sm = c(4, 4, 4), md = c(3, 3, 6), lg = c(-2, 8, -2)) + } \references{ \url{https://getbootstrap.com/docs/5.3/layout/breakpoints/} diff --git a/man/card.Rd b/man/card.Rd index eedf41511..65498bae1 100644 --- a/man/card.Rd +++ b/man/card.Rd @@ -45,6 +45,8 @@ together into one \code{wrapper} call (e.g. given \code{card("a", "b", card_body A \code{\link[htmltools:builder]{htmltools::div()}} tag. } \description{ +\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}} + A general purpose container for grouping related UI elements together with a border and optional padding. To learn more about \code{\link[=card]{card()}}s, see \href{https://rstudio.github.io/bslib/articles/cards.html}{this article}. } diff --git a/man/input_dark_mode.Rd b/man/input_dark_mode.Rd index d1229e689..7b1bead5c 100644 --- a/man/input_dark_mode.Rd +++ b/man/input_dark_mode.Rd @@ -33,6 +33,8 @@ value received for the input corresponding to \code{id} will be a string value with the current color mode (\code{"light"} or \code{"dark"}). } \description{ +\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}} + Creates a button that toggles between dark and light modes, specifically for toggling between light and dark \href{https://getbootstrap.com/docs/5.3/customize/color-modes/}{Bootstrap color modes} -- a new feature added in \href{https://getbootstrap.com/docs/5.3/migration/#color-modes}{Bootstrap 5.3}. diff --git a/man/input_switch.Rd b/man/input_switch.Rd index 91c144370..3e9762bcc 100644 --- a/man/input_switch.Rd +++ b/man/input_switch.Rd @@ -30,6 +30,8 @@ received for the input corresponding to \code{id} will be a logical (\code{TRUE}/\code{FALSE}) value. } \description{ +\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}} + Create an on-off style switch control for specifying logical values. } \examples{ diff --git a/man/layout_column_wrap.Rd b/man/layout_column_wrap.Rd index dca6ec147..fbd589d86 100644 --- a/man/layout_column_wrap.Rd +++ b/man/layout_column_wrap.Rd @@ -67,6 +67,8 @@ devices (or narrow windows).} \item{class}{Additional CSS classes for the returned UI element.} } \description{ +\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}} + Wraps a 1d sequence of UI elements into a 2d grid. The number of columns (and rows) in the grid dependent on the column \code{width} as well as the size of the display. For more explanation and illustrative examples, see \href{https://rstudio.github.io/bslib/articles/cards.html#multiple-cards}{here} diff --git a/man/page.Rd b/man/page.Rd index 97de936c3..dbd5d2a66 100644 --- a/man/page.Rd +++ b/man/page.Rd @@ -126,6 +126,19 @@ These functions are small wrappers around shiny's page constructors (i.e., \item The return value is rendered as an static HTML page when printed interactively at the console. } } +\section{Functions}{ +\itemize{ +\item \code{page_fluid()}: A \pkg{bslib} wrapper for \code{\link[shiny:fluidPage]{shiny::fluidPage()}}, a fluid +Bootstrap-based page layout that extends to the full viewport width. + +\item \code{page_fixed()}: A \pkg{bslib} wrapper for \code{\link[shiny:fixedPage]{shiny::fixedPage()}}, a fixed +Bootstrap-based page layout where the page content container is centered +horizontally and its width is constrained. + +\item \code{page_fillable()}: \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}} A Bootstrap-based page +layout whose contents fill the full height and width of the browser window. + +}} \seealso{ \code{\link[=page_sidebar]{page_sidebar()}} diff --git a/man/page_sidebar.Rd b/man/page_sidebar.Rd index 2c4f5e46f..93b8cb761 100644 --- a/man/page_sidebar.Rd +++ b/man/page_sidebar.Rd @@ -42,10 +42,12 @@ This will be used as the lang in the \code{} tag, as in \code{= "3.4") withAutoprint else force)(\{ # examplesIf} library(shiny) library(ggplot2) diff --git a/man/popover.Rd b/man/popover.Rd index caf1fc2ac..e9cebce15 100644 --- a/man/popover.Rd +++ b/man/popover.Rd @@ -49,6 +49,8 @@ it's hidden behind a tab).} used).} } \description{ +\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}} + Display additional information when clicking on a UI element (typically a button). } diff --git a/man/sidebar.Rd b/man/sidebar.Rd index b1d59f79a..d54be27a3 100644 --- a/man/sidebar.Rd +++ b/man/sidebar.Rd @@ -125,8 +125,10 @@ main content area.} used).} } \description{ -Create a collapsing sidebar layout by providing a \code{sidebar()} -object to the \code{sidebar} argument of: +\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}} + +Create a collapsing sidebar layout by providing a \code{sidebar()} object to the +\code{sidebar} argument of: \itemize{ \item \code{\link[=page_sidebar]{page_sidebar()}} \itemize{ diff --git a/man/tooltip.Rd b/man/tooltip.Rd index b58120952..c4337a26b 100644 --- a/man/tooltip.Rd +++ b/man/tooltip.Rd @@ -42,6 +42,8 @@ it's hidden behind a tab).} used).} } \description{ +\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}} + Display additional information when focusing (or hovering over) a UI element. } \section{Functions}{ diff --git a/man/value_box.Rd b/man/value_box.Rd index a433152c4..f4f26df6a 100644 --- a/man/value_box.Rd +++ b/man/value_box.Rd @@ -111,6 +111,8 @@ Accepted values in the second category are \code{"auto"}, \code{"min-content"}, }} } \description{ +\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}} + An opinionated (\code{\link[=card]{card()}}-powered) box, designed for displaying a \code{value} and \code{title}. Optionally, a \code{showcase} can provide for context for what the \code{value} represents (for example, it could hold a \code{\link[bsicons:bs_icon]{bsicons::bs_icon()}}, or