diff --git a/DESCRIPTION b/DESCRIPTION index f48b1d1..c95f676 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,6 +1,6 @@ Package: bslibdash Type: Package -Title: Bootstrap 5 Dashboard Framework for Shiny Apps +Title: 'Bootstrap' 5 Dashboard Framework for 'shiny' Apps Version: 0.7.5 Authors@R: c( person("Alexandros", "Kouretsis", email = "alexandros@appsilon.com", role = c("aut", "cre")), @@ -8,10 +8,12 @@ Authors@R: c( person("Dominik", "Rafacz", email = "dominik.rafacz_ext@novartis.com", role = "aut"), person("Novartis Open Source Initiative", role = "cph") ) -Description: Build modern Bootstrap 5 dashboards in Shiny with 'bslib'. Provides a dashboard page shell - and reusable components that integrate with 'bslib' themes and follow Bootstrap design patterns. The - API is inspired by 'shinydashboard', where the underlying concepts are shared, helping existing apps - migrate with minimal changes while supporting a cleaner, more flexible dashboard design style. +Description: Provides a dashboard layer for 'shiny' applications built on 'bslib' and + 'Bootstrap' 5. Includes a dashboard page shell, sidebar navigation, cards, value boxes, + header drop-down menus and feedback components that inherit the active 'bslib' theme and + follow 'Bootstrap' design patterns. Function names mirror those of the 'shinydashboard' + package wherever the underlying concepts are shared, allowing existing applications to + migrate with minimal changes. License: MIT + file LICENSE URL: https://github.com/Novartis/bslibdash, https://opensource.nibr.com/bslibdash/ BugReports: https://github.com/Novartis/bslibdash/issues diff --git a/R/body.R b/R/body.R index acafb79..cba2fbb 100644 --- a/R/body.R +++ b/R/body.R @@ -1,6 +1,8 @@ #' Dashboard body #' #' @param ... Body content, usually `tabItems()`. +#' @return `dashboardBody()` returns an [htmltools::div()] tag that may be passed +#' to [dashboardPage()]. #' @examples #' dashboardBody( #' tabItems( @@ -26,6 +28,8 @@ dashboardBody <- function(...) { #' @param id Shared Shiny id for the sidebar menu and body tabset. Use the same #' value in `sidebarMenu(id)`, `tabItems(id)`, and #' `updateTabItems(inputId)`. Defaults to `"sidebarMenu"`. +#' @return `tabItems()` returns an [htmltools::div()] tag containing a hidden +#' [shiny::tabsetPanel()]. #' @examples #' tabItems( #' tabItem(tabName = "overview", shiny::p("Overview content")), @@ -38,6 +42,8 @@ tabItems <- function(..., id = "sidebarMenu") { } #' @param tabName The name of a tab. +#' @return `tabItem()` returns an [htmltools::tagList()] that may be passed to +#' `tabItems()`. #' @examples #' tabItem( #' tabName = "overview", diff --git a/R/brand_bs_theme.R b/R/brand_bs_theme.R index 073f417..9acd340 100644 --- a/R/brand_bs_theme.R +++ b/R/brand_bs_theme.R @@ -23,7 +23,7 @@ #' ) #' } #' -#' @return A `bslib` theme object. +#' @return Returns a [bslib::bs_theme()] object. #' @examples #' theme <- brand_bs_theme() #' class(theme) diff --git a/R/cards.R b/R/cards.R index 07aa165..e52a1d7 100644 --- a/R/cards.R +++ b/R/cards.R @@ -26,6 +26,9 @@ #' @param id Optional card id. Use to target the card with [updateBox()]. #' Provide distinct ids when rendering otherwise-identical cards on the same page. #' +#' @return `box()` returns a [bslib::card()] tag, wrapped in a [shiny::column()] +#' when `width` is an integer between `1` and `12`. +#' #' @examples #' box( #' "Card body", @@ -205,6 +208,8 @@ box <- function(..., #' `bslib::layout_column_wrap()` fallback is used, but prefer calling #' `bslib::layout_column_wrap()` directly for new code. #' +#' @return An [htmltools::div()] tag containing the supplied cards. +#' #' @examples #' boxLayout( #' box("Revenue", title = "KPI"), @@ -266,6 +271,8 @@ boxLayout <- function(..., .list = NULL, type = c("group", "deck", "columns")) { #' @param action Action to trigger. #' @param options List of new options for `action = "update"`. #' @param session Shiny session. +#' @return `updateBox()` and `updateCard()` return nothing. These functions are +#' called for their side-effects. #' @rdname box #' @export updateBox <- function(id, diff --git a/R/feedbacks.R b/R/feedbacks.R index 22935c5..48874bd 100644 --- a/R/feedbacks.R +++ b/R/feedbacks.R @@ -20,6 +20,9 @@ #' `"message"`, `"warning"`, `"error"`). #' @param session Shiny session object. #' +#' @return The notification ID (string) returned by [shiny::showNotification()], +#' which can be used with [shiny::removeNotification()]. +#' #' @examples #' if (interactive()) { #' shiny::shinyApp( diff --git a/R/grid.R b/R/grid.R index 514a340..d0e0fb4 100644 --- a/R/grid.R +++ b/R/grid.R @@ -4,6 +4,8 @@ #' @param ... Elements to include within the column. #' @param offset The number of columns to offset this column. #' +#' @return A [shiny::column()] tag that may be included in a Shiny UI. +#' #' @examples #' shiny::fluidRow( #' column(8, shiny::p("Main content")), diff --git a/R/icons.R b/R/icons.R index 36e3bb4..9bd4cd1 100644 --- a/R/icons.R +++ b/R/icons.R @@ -7,7 +7,7 @@ #' @param color Icon color applied to a wrapping span. #' @param css Named list of CSS properties applied to the icon tag. #' -#' @return An icon `htmltools` tag. +#' @return An HTML tag object that can be included in a Shiny UI. #' @examples #' if (interactive()) { #' icon("user") diff --git a/R/inputs.R b/R/inputs.R index b69efac..23bab83 100644 --- a/R/inputs.R +++ b/R/inputs.R @@ -10,6 +10,10 @@ #' @param size Button size. #' @param flat Whether to apply a flat style. #' +#' @return Returns a UI element for an action button. The server value received +#' for the input corresponding to `inputId` will be an integer that increments +#' with each click. +#' #' @examples #' actionButton( #' inputId = "refresh", diff --git a/R/layout.R b/R/layout.R index fd98820..0ad2cfa 100644 --- a/R/layout.R +++ b/R/layout.R @@ -38,7 +38,8 @@ dashboard_header_set_title <- function(tag, title) { #' @param footer Optional slot for [dashboardFooter()]. #' @param theme A `bslib` theme. Defaults to [brand_bs_theme()]. #' -#' @return A Shiny UI definition. +#' @return A [bslib::page()] tag that may be passed to the `ui` argument of +#' [shiny::shinyApp()]. #' @examples #' ui <- dashboardPage( #' header = dashboardHeader(title = "bslibdash dashboard"), @@ -84,6 +85,7 @@ dashboardPage <- function(header, #' #' @inheritParams shiny::tabsetPanel #' @param .list Optional list of tab panels. +#' @return A [shiny::tabsetPanel()] tag that may be included in a Shiny UI. #' @examples #' tabsetPanel( #' id = "tabs", @@ -113,6 +115,9 @@ tabsetPanel <- function(..., #' @param right Right-side footer content. #' @param fixed Whether to mark footer as fixed. #' +#' @return A `