Cran review fixes 0.7.5

DESCRIPTION

@@ -1,17 +1,19 @@
 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")),
     person("Ardalan", "Mirshani", email = "ardalan.mirshani@novartis.com", role = "aut"),
     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

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",

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)

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,

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(

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")),

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

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",

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 `<footer>` tag that may be passed to [dashboardPage()], or `NULL` if
+#'   `left` and `right` are both `NULL`.
+#'
 #' @examples
 #' dashboardFooter(
 #'   left = "Copyright (c) 2026",
@@ -152,6 +157,9 @@ dashboardFooter <- function(left = NULL, right = NULL, fixed = FALSE) {
 #' @param .list Optional list of right-side header UI elements, merged with
 #'   `...`.
 #'
+#' @return A `<nav>` tag that may be passed to [dashboardPage()], or `NULL` if
+#'   `disable = TRUE`.
+#'
 #' @examples
 #' dashboardHeader(
 #'   title = "Operations",

R/sidebar.R

@@ -6,6 +6,9 @@
 #'   pixels; CSS strings such as `"18rem"` are passed through.
 #' @param collapsed Whether the sidebar starts collapsed on desktop.
 #'
+#' @return `dashboardSidebar()` returns an `<aside>` tag that may be passed to
+#'   [dashboardPage()], or `NULL` if `disable = TRUE`.
+#'
 #' @examples
 #' dashboardSidebar(
 #'   sidebarMenu(
@@ -52,6 +55,9 @@ dashboardSidebar <- function(...,
 #'   `updateTabItems(inputId)`. Defaults to `"sidebarMenu"`.
 #' @param .list Optional list of items.
 #'
+#' @return `sidebarMenu()` returns an [htmltools::div()] tag that may be passed
+#'   to `dashboardSidebar()`.
+#'
 #' @examples
 #' sidebarMenu(
 #'   id = "sidebarMenu",
@@ -86,6 +92,9 @@ sidebarMenu <- function(...,
 #' @param startExpanded Whether children start expanded.
 #' @param condition Optional display condition stored as a data attribute.
 #'
+#' @return `menuItem()` returns a menu item that may be passed to
+#'   `sidebarMenu()`.
+#'
 #' @examples
 #' menuItem(
 #'   "Reports",
@@ -188,6 +197,9 @@ menuItem <- function(text,
 #' @param icon Icon tag or icon name.
 #' @param selected Whether the item starts selected.
 #'
+#' @return `menuSubItem()` returns a menu item that may be passed to
+#'   `menuItem()`.
+#'
 #' @examples
 #' menuSubItem(
 #'   "Daily report",
@@ -213,6 +225,8 @@ menuSubItem <- function(text,
 #' Dashboard sidebar menu header
 #'
 #' @param title Header title.
+#' @return `sidebarHeader()` returns an [htmltools::div()] tag that may be passed
+#'   to `sidebarMenu()`.
 #' @examples
 #' sidebarHeader("Administration")
 #' @rdname dashboardSidebar

R/sidebar_user.R

@@ -12,8 +12,7 @@
 #'   icon is used.
 #' @param subtitle Optional secondary text shown beneath the name.
 #'
-#' @return An htmltools `<div>` tag intended to be passed into
-#'   `dashboardSidebar()`.
+#' @return An [htmltools::div()] tag that may be passed to [dashboardSidebar()].
 #' @examples
 #' dashboardSidebar(
 #'   sidebarUserPanel(

R/useful-items.R

@@ -5,6 +5,9 @@
 #' @param color Bootstrap status color.
 #' @param rounded Whether the badge is rounded.
 #'
+#' @return An [htmltools::span()] tag that may be included in a Shiny UI (e.g.
+#'   inside a `menuItem()` label).
+#'
 #' @examples
 #' badge("NEW", color = "success", position = "right", rounded = TRUE)
 #'
@@ -34,6 +37,9 @@ badge <- function(..., position = c("left", "right"), color, rounded = FALSE) {
 #' @param width The width of the accordion.
 #' @param .list Optional list of accordion items.
 #'
+#' @return `accordion()` returns a [bslib::accordion()] tag that may be included
+#'   in a Shiny UI.
+#'
 #' @examples
 #' accordion(
 #'   id = "filters",
@@ -73,6 +79,9 @@ accordion <- function(..., id, width = 12, .list = NULL) {
 #'   and header are tinted with the matching subtle status hue, aligned with
 #'   `box(status = ...)`.
 #'
+#' @return `accordionItem()` returns a [bslib::accordion_panel()] tag that may be
+#'   passed to `accordion()`.
+#'
 #' @examples
 #' accordionItem(
 #'   title = "Advanced settings",

R/widgets-boxes.R

@@ -14,6 +14,9 @@
 #'   Use `NULL` when placing the box inside an existing column.
 #' @param href Optional URL to link to.
 #'
+#' @return A [bslib::value_box()] tag, wrapped in a [shiny::column()] unless
+#'   `width` is `NULL`.
+#'
 #' @examples
 #' valueBox(
 #'   value = "128",
@@ -79,6 +82,8 @@ valueBox <- function(value,
 #' @param width The width of the box in Bootstrap grid columns (`1`-`12`).
 #'   Use `NULL` when placing the output inside an existing column.
 #'
+#' @return A [shiny::uiOutput()] container to be filled by [renderValueBox()].
+#'
 #' @examples
 #' valueBoxOutput("tickets")
 #'
@@ -100,6 +105,9 @@ valueBoxOutput <- function(outputId, width = 4) {
 #' @param env The parent environment for the reactive expression.
 #' @param quoted Is `expr` a quoted expression.
 #'
+#' @return A [shiny::renderUI()] function that may be assigned to an `output`
+#'   slot paired with [valueBoxOutput()].
+#'
 #' @examples
 #' if (interactive()) {
 #' shiny::shinyApp(
@@ -140,6 +148,9 @@ renderValueBox <- function(expr, env = parent.frame(), quoted = FALSE) {
 #' @param href Optional URL to link to.
 #' @param fill Whether to fill the entire box background with `color`.
 #'
+#' @return An [htmltools::div()] tag, wrapped in a [shiny::column()] unless
+#'   `width` is `NULL`.
+#'
 #' @examples
 #' infoBox(
 #'   title = "CPU",
@@ -220,6 +231,8 @@ infoBox <- function(title,
 #' @param width The width of the box in Bootstrap grid columns (`1`-`12`).
 #'   Use `NULL` when placing the output inside an existing column.
 #'
+#' @return A [shiny::uiOutput()] container to be filled by [renderInfoBox()].
+#'
 #' @examples
 #' infoBoxOutput("system_status")
 #'
@@ -241,6 +254,9 @@ infoBoxOutput <- function(outputId, width = 4) {
 #' @param env The parent environment for the reactive expression.
 #' @param quoted Is `expr` a quoted expression.
 #'
+#' @return A [shiny::renderUI()] function that may be assigned to an `output`
+#'   slot paired with [infoBoxOutput()].
+#'
 #' @examples
 #' if (interactive()) {
 #' shiny::shinyApp(
@@ -276,6 +292,9 @@ renderInfoBox <- function(expr, env = parent.frame(), quoted = FALSE) {
 #' @param side Whether to place tabs on the `"left"` or `"right"` side of the
 #'   header.
 #'
+#' @return A [bslib::navset_card_tab()] tag, wrapped in a [shiny::column()]
+#'   unless `width` is `NULL`.
+#'
 #' @examples
 #' # Basic tab box with a title in the card header
 #' tabBox(

R/widgets-menu.R

@@ -10,6 +10,9 @@
 #' @param .list Optional list of menu item tags.
 #' @param href Optional URL for the "More" footer link.
 #'
+#' @return `dropdownMenu()` returns an [htmltools::div()] tag that may be passed
+#'   to [dashboardHeader()].
+#'
 #' @examples
 #' dropdownMenu(
 #'   type = "notifications",
@@ -108,6 +111,9 @@ dropdownMenu <- function(...,
 #' @param color Bootstrap status color used for item accents.
 #' @param inputId Optional id to make the item behave like an action button.
 #'
+#' @return `messageItem()` returns a dropdown item that may be passed to
+#'   `dropdownMenu()`.
+#'
 #' @examples
 #' messageItem(
 #'   from = "Ops bot",
@@ -181,6 +187,9 @@ messageItem <- function(from,
 #' @param text Item text.
 #' @param status Bootstrap status color used for the icon.
 #'
+#' @return `notificationItem()` returns a dropdown item that may be passed to
+#'   `dropdownMenu()`.
+#'
 #' @examples
 #' notificationItem(
 #'   text = "3 new alerts",
@@ -226,6 +235,9 @@ notificationItem <- function(text,
 #' @param value Percent completion value.
 #' @param color Bootstrap status color used for item accents.
 #'
+#' @return `taskItem()` returns a dropdown item that may be passed to
+#'   `dropdownMenu()`.
+#'
 #' @examples
 #' taskItem(
 #'   text = "Data refresh",
@@ -278,6 +290,9 @@ taskItem <- function(text, value = 0, color = "info", href = NULL, inputId = NUL
 #'
 #' @param outputId Output variable name.
 #'
+#' @return A [shiny::uiOutput()] container to be filled by
+#'   [renderDropdownMenu()].
+#'
 #' @examples
 #' dropdownMenuOutput("alerts_menu")
 #'
@@ -297,6 +312,9 @@ dropdownMenuOutput <- function(outputId) {
 #' @param env The parent environment for the reactive expression.
 #' @param quoted Is `expr` a quoted expression.
 #'
+#' @return A [shiny::renderUI()] function that may be assigned to an `output`
+#'   slot paired with [dropdownMenuOutput()].
+#'
 #' @examples
 #' if (interactive()) {
 #' shiny::shinyApp(