From 182d948cad6bacc7f3662bd696ce6a7d37b655fd Mon Sep 17 00:00:00 2001 From: Garrick Aden-Buie Date: Thu, 30 Jan 2025 11:05:27 -0500 Subject: [PATCH 1/3] docs: Discuss bs5 + bootswatch navbar themes --- R/navbar_options.R | 71 ++++++++++++++++++++++++++++++++++++++++++- man/navbar_options.Rd | 69 +++++++++++++++++++++++++++++++++++++++-- 2 files changed, 137 insertions(+), 3 deletions(-) diff --git a/R/navbar_options.R b/R/navbar_options.R index 6ab9253d9..806a1db2a 100644 --- a/R/navbar_options.R +++ b/R/navbar_options.R @@ -5,7 +5,76 @@ #' This helper should be used to create the list of options expected by #' `navbar_options` in [page_navbar()] and [navset_bar()]. #' -#' ## Changelog +#' ## Navbar style with Bootstrap 5 and Bootswatch themes +#' +#' In \pkg{bslib} v0.9.0, the default navbar colors for Bootswatch themes with +#' Bootstrap 5 changed. Prior to v0.9.0, bslib pre-selected navbar background +#' colors in light and dark mode; after v0.9.0 the default navbar colors are +#' less opinionated by default and follow light or dark mode (see +#' [input_dark_mode()]). +#' +#' You can use `navbar_options()` to adjust the colors of the navbar when using +#' a Bootswatch preset theme with Bootstrap 5. For example, the [Bootswatch +#' documentation for the Flatly theme](https://bootswatch.com/flatly/) shows +#' 4 navbar variations. Inspecting the source code for the first example reveals +#' the following markup: +#' +#' ```html +#' +#' ``` +#' +#' Note that this navbar uses the `bg-primary` class for a dark navy background. +#' The navbar's white text is controlled by the `data-bs-theme="dark"` +#' attribute, which is used by Bootstrap for light text on a _dark_ background. +#' In \pkg{bslib}, you can achieve this look with: +#' +#' ```r +#' ui <- page_navbar( +#' theme = bs_theme(5, "flatly"), +#' navbar_options = navbar_options(class = "bg-primary", theme = "dark") +#' ) +#' ``` +#' +#' This particular combination of `class = "bg-primary"` and `theme = "dark"` +#' works well for most Bootswatch presets. +#' +#' Another variation from the Flatly documentation features a navar with dark +#' text on a light background: +#' +#' ```r +#' ui <- page_navbar( +#' theme = bs_theme(5, "flatly"), +#' navbar_options = navbar_options(class = "bg-light", theme = "light") +#' ) +#' ``` +#' +#' The above options set navbar foreground and background colors that are always +#' the same in both light and dark modes. To customize the navbar colors used in +#' light or dark mode, you can use the `$navbar-light-bg` and `$navbar-dark-bg` +#' Sass variables. When provided, bslib will automatically choose to use +#' light or dark text as the foreground color. +#' +#' ```r +#' ui <- page_navbar( +#' theme = bs_theme(5, "flatly"), +#' navbar_light_bg = "#18BC9C", # flatly's success color (teal) +#' navbar_dark_bg = "#2C3E50" # flatly's primary color (navy) +#' ) +#' ``` +#' +#' Finally, you can also use the `$navbar-bg` Sass variable to set the navbar +#' background color for both light and dark modes: +#' +#' ```r +#' ui <- page_navbar( +#' theme = bs_theme(5, "flatly"), +#' navbar_bg = "#E74C3C" # flatly's danger color (red) +#' ) +#' ``` +#' +#' @section Changelog: #' #' This function was introduced in \pkg{bslib} v0.9.0, replacing the `position`, #' `bg`, `inverse`, `collapsible` and `underline` arguments of [page_navbar()] diff --git a/man/navbar_options.Rd b/man/navbar_options.Rd index c9a60c55d..fc143a8c3 100644 --- a/man/navbar_options.Rd +++ b/man/navbar_options.Rd @@ -48,7 +48,72 @@ This helper should be used to create the list of options expected by \code{navbar_options} in \code{\link[=page_navbar]{page_navbar()}} and \code{\link[=navset_bar]{navset_bar()}}. } \details{ -\subsection{Changelog}{ +\subsection{Navbar style with Bootstrap 5 and Bootswatch themes}{ + +In \pkg{bslib} v0.9.0, the default navbar colors for Bootswatch themes with +Bootstrap 5 changed. Prior to v0.9.0, bslib pre-selected navbar background +colors in light and dark mode; after v0.9.0 the default navbar colors are +less opinionated by default and follow light or dark mode (see +\code{\link[=input_dark_mode]{input_dark_mode()}}). + +You can use \code{navbar_options()} to adjust the colors of the navbar when using +a Bootswatch preset theme with Bootstrap 5. For example, the \href{https://bootswatch.com/flatly/}{Bootswatch documentation for the Flatly theme} shows +4 navbar variations. Inspecting the source code for the first example reveals +the following markup: + +\if{html}{\out{
}}\preformatted{ +}\if{html}{\out{
}} + +Note that this navbar uses the \code{bg-primary} class for a dark navy background. +The navbar's white text is controlled by the \code{data-bs-theme="dark"} +attribute, which is used by Bootstrap for light text on a \emph{dark} background. +In \pkg{bslib}, you can achieve this look with: + +\if{html}{\out{
}}\preformatted{ui <- page_navbar( + theme = bs_theme(5, "flatly"), + navbar_options = navbar_options(class = "bg-primary", theme = "dark") +) +}\if{html}{\out{
}} + +This particular combination of \code{class = "bg-primary"} and \code{theme = "dark"} +works well for most Bootswatch presets. + +Another variation from the Flatly documentation features a navar with dark +text on a light background: + +\if{html}{\out{
}}\preformatted{ui <- page_navbar( + theme = bs_theme(5, "flatly"), + navbar_options = navbar_options(class = "bg-light", theme = "light") +) +}\if{html}{\out{
}} + +The above options set navbar foreground and background colors that are always +the same in both light and dark modes. To customize the navbar colors used in +light or dark mode, you can use the \verb{$navbar-light-bg} and \verb{$navbar-dark-bg} +Sass variables. When provided, bslib will automatically choose to use +light or dark text as the foreground color. + +\if{html}{\out{
}}\preformatted{ui <- page_navbar( + theme = bs_theme(5, "flatly"), + navbar_light_bg = "#18BC9C", # flatly's success color (teal) + navbar_dark_bg = "#2C3E50" # flatly's primary color (navy) +) +}\if{html}{\out{
}} + +Finally, you can also use the \verb{$navbar-bg} Sass variable to set the navbar +background color for both light and dark modes: + +\if{html}{\out{
}}\preformatted{ui <- page_navbar( + theme = bs_theme(5, "flatly"), + navbar_bg = "#E74C3C" # flatly's danger color (red) +) +}\if{html}{\out{
}} +} +} +\section{Changelog}{ + This function was introduced in \pkg{bslib} v0.9.0, replacing the \code{position}, \code{bg}, \code{inverse}, \code{collapsible} and \code{underline} arguments of \code{\link[=page_navbar]{page_navbar()}} @@ -57,7 +122,7 @@ removed in a future version of \pkg{bslib}. Note that the deprecated \code{inverse} argument of \code{\link[=page_navbar]{page_navbar()}} and \code{\link[=navset_bar]{navset_bar()}} was replaced with the \code{theme} argument of \code{navbar_options()}. } -} + \examples{ navbar_options(position = "static-top", bg = "#2e9f7d", underline = FALSE) From 39e1eb8230bf70294baf4652805d14d140b325a3 Mon Sep 17 00:00:00 2001 From: Garrick Aden-Buie Date: Thu, 30 Jan 2025 11:08:57 -0500 Subject: [PATCH 2/3] docs: Update NEWS item --- NEWS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/NEWS.md b/NEWS.md index 4a8d10068..80718350d 100644 --- a/NEWS.md +++ b/NEWS.md @@ -6,7 +6,7 @@ Related to the above change, `navset_bar()` now defaults to using `underline = TRUE` so that both `page_navbar()` and `navset_bar()` use the same set of default `navbar_options()`. - In `navbar_options()`, `inverse` is replaced by `theme`, which takes values `"light"` (dark text on a **light** background), `"dark"` (light text on a **dark** background), or `"auto"` (follow page settings). (#1146) + In `navbar_options()`, `inverse` is replaced by `theme`, which takes values `"light"` (dark text on a **light** background), `"dark"` (light text on a **dark** background), or `"auto"` (follow page settings, the default). This change affects that default navbar foreground and background colors for Bootswatch preset themes with Bootstrap 5. Detailed instructions for customizing the navbar appearance, especially for Bootswatch themes, can be found in `?navbar_options`. (#1146) ## New features From 3d0d26dc369825a4c2d68e0af96b4e5c014e567e Mon Sep 17 00:00:00 2001 From: Garrick Aden-Buie Date: Thu, 30 Jan 2025 12:00:53 -0500 Subject: [PATCH 3/3] docs: fix `bs_theme()` calls --- R/navbar_options.R | 16 +++++++++++----- man/navbar_options.Rd | 16 +++++++++++----- 2 files changed, 22 insertions(+), 10 deletions(-) diff --git a/R/navbar_options.R b/R/navbar_options.R index 806a1db2a..aa13e6062 100644 --- a/R/navbar_options.R +++ b/R/navbar_options.R @@ -58,9 +58,12 @@ #' #' ```r #' ui <- page_navbar( -#' theme = bs_theme(5, "flatly"), -#' navbar_light_bg = "#18BC9C", # flatly's success color (teal) -#' navbar_dark_bg = "#2C3E50" # flatly's primary color (navy) +#' theme = bs_theme( +#' 5, +#' preset = "flatly", +#' navbar_light_bg = "#18BC9C", # flatly's success color (teal) +#' navbar_dark_bg = "#2C3E50" # flatly's primary color (navy) +#' ) #' ) #' ``` #' @@ -69,8 +72,11 @@ #' #' ```r #' ui <- page_navbar( -#' theme = bs_theme(5, "flatly"), -#' navbar_bg = "#E74C3C" # flatly's danger color (red) +#' theme = bs_theme( +#' 5, +#' preset = "flatly", +#' navbar_bg = "#E74C3C" # flatly's danger color (red) +#' ) #' ) #' ``` #' diff --git a/man/navbar_options.Rd b/man/navbar_options.Rd index fc143a8c3..fc8e26a5a 100644 --- a/man/navbar_options.Rd +++ b/man/navbar_options.Rd @@ -96,9 +96,12 @@ Sass variables. When provided, bslib will automatically choose to use light or dark text as the foreground color. \if{html}{\out{
}}\preformatted{ui <- page_navbar( - theme = bs_theme(5, "flatly"), - navbar_light_bg = "#18BC9C", # flatly's success color (teal) - navbar_dark_bg = "#2C3E50" # flatly's primary color (navy) + theme = bs_theme( + 5, + preset = "flatly", + navbar_light_bg = "#18BC9C", # flatly's success color (teal) + navbar_dark_bg = "#2C3E50" # flatly's primary color (navy) + ) ) }\if{html}{\out{
}} @@ -106,8 +109,11 @@ Finally, you can also use the \verb{$navbar-bg} Sass variable to set the navbar background color for both light and dark modes: \if{html}{\out{
}}\preformatted{ui <- page_navbar( - theme = bs_theme(5, "flatly"), - navbar_bg = "#E74C3C" # flatly's danger color (red) + theme = bs_theme( + 5, + preset = "flatly", + navbar_bg = "#E74C3C" # flatly's danger color (red) + ) ) }\if{html}{\out{
}} }