From d88e1ab0a1e3070c6121e020aac1c1ba1e2ebb09 Mon Sep 17 00:00:00 2001 From: Leonidas Zhak <70497898+LeonidasZhak@users.noreply.github.com> Date: Sat, 6 Jun 2026 10:07:59 +0800 Subject: [PATCH] docs: clarify layout CSS length inputs --- NEWS.md | 6 ++++++ R/layout.R | 14 ++++++++++---- man/layout_column_wrap.Rd | 12 ++++++++---- man/layout_columns.Rd | 11 +++++++---- 4 files changed, 31 insertions(+), 12 deletions(-) diff --git a/NEWS.md b/NEWS.md index 44bab132e..e23d35bcc 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,5 +1,11 @@ # bslib (development version) +## Documentation + +* `layout_columns()` and `layout_column_wrap()` now describe their CSS length + inputs with concrete examples, including numeric pixel values, unit-bearing + strings, percentages, and `calc()` expressions. (#1300) + ## Bug fixes * Fixed label-to-options spacing on `shiny::radioButtons()` and `shiny::checkboxGroupInput()` in Bootstrap 5, where a Shiny rule was overriding the bslib fix. (#1308) diff --git a/R/layout.R b/R/layout.R index 5718e9f09..928888104 100644 --- a/R/layout.R +++ b/R/layout.R @@ -13,13 +13,14 @@ #' * A (unit-less) number between 0 and 1. #' * This should be specified as `1/num`, where `num` represents the number #' of desired columns. -#' * A [CSS length unit][htmltools::validateCssUnit()] +#' * A [CSS length][htmltools::validateCssUnit()], such as `"200px"`, +#' `"20rem"`, `"50%"`, or `"calc(100% - 2rem)"` #' * Either the minimum (when `fixed_width=FALSE`) or fixed width #' (`fixed_width=TRUE`). #' * `NULL` #' * Allows power users to set the `grid-template-columns` CSS property #' manually, either via a `style` attribute or a CSS stylesheet. -#' @param fixed_width When `width` is greater than 1 or is a CSS length unit, +#' @param fixed_width When `width` is greater than 1 or is a CSS length, #' e.g. `"200px"`, `fixed_width` indicates whether that `width` value #' represents the absolute size of each column (`fixed_width=TRUE`) or the #' minimum size of a column (`fixed_width=FALSE`). When `fixed_width=FALSE`, @@ -39,6 +40,11 @@ #' Can be any valid [CSS unit][htmltools::validateCssUnit] (e.g., #' `max_height="200px"`). Use these arguments in filling layouts to ensure that a #' layout container doesn't shrink below `min_height` or grow beyond `max_height`. +#' @param gap A CSS length defining the gap (i.e., spacing) between elements +#' provided to `...`. Numeric values are treated as pixel values; character +#' values may use units like `"px"`, `"rem"`, or `"%"`, or CSS functions like +#' `"calc(1rem + 2px)"`. This argument is only applicable when +#' `fillable = TRUE`. #' @inheritParams card #' @inheritParams card_body #' @@ -200,13 +206,13 @@ is_probably_a_css_unit <- function(x) { #' (`fr`) height of the relevant row. If there are more rows than values #' provided, the pattern will repeat. For example, `row_heights = c(1, 2)` #' allows even rows to take up twice as much space as odd rows. -#' * A list of numeric and [CSS length units][htmltools::validateCssUnit()], +#' * A list of numeric values and [CSS lengths][htmltools::validateCssUnit()], #' where each value represents the height of the relevant row. If more rows #' are needed than values provided, the pattern will repeat. For example, #' `row_heights = list("auto", 1)` allows the height of odd rows to be #' driven by its contents and even rows to be #' [`1fr`](https://css-tricks.com/introduction-fr-css-unit/). -#' * A character vector/string of [CSS length units][htmltools::validateCssUnit()]. +#' * A character vector/string of [CSS lengths][htmltools::validateCssUnit()]. #' In this case, the value is supplied directly to `grid-auto-rows`. #' * A [breakpoints()] object, where each breakpoint may be either of the above. #' diff --git a/man/layout_column_wrap.Rd b/man/layout_column_wrap.Rd index 32b483449..7ca987328 100644 --- a/man/layout_column_wrap.Rd +++ b/man/layout_column_wrap.Rd @@ -31,7 +31,8 @@ following: \item This should be specified as \code{1/num}, where \code{num} represents the number of desired columns. } -\item A \link[htmltools:validateCssUnit]{CSS length unit} +\item A \link[htmltools:validateCssUnit]{CSS length}, such as \code{"200px"}, +\code{"20rem"}, \code{"50\%"}, or \code{"calc(100\% - 2rem)"} \itemize{ \item Either the minimum (when \code{fixed_width=FALSE}) or fixed width (\code{fixed_width=TRUE}). @@ -43,7 +44,7 @@ manually, either via a \code{style} attribute or a CSS stylesheet. } }} -\item{fixed_width}{When \code{width} is greater than 1 or is a CSS length unit, +\item{fixed_width}{When \code{width} is greater than 1 or is a CSS length, e.g. \code{"200px"}, \code{fixed_width} indicates whether that \code{width} value represents the absolute size of each column (\code{fixed_width=TRUE}) or the minimum size of a column (\code{fixed_width=FALSE}). When \code{fixed_width=FALSE}, @@ -73,8 +74,11 @@ Can be any valid \link[htmltools:validateCssUnit]{CSS unit} (e.g., \code{max_height="200px"}). Use these arguments in filling layouts to ensure that a layout container doesn't shrink below \code{min_height} or grow beyond \code{max_height}.} -\item{gap}{A \link[htmltools:validateCssUnit]{CSS length unit} defining the -\code{gap} (i.e., spacing) between elements provided to \code{...}. This argument is only applicable when \code{fillable = TRUE}} +\item{gap}{A CSS length defining the gap (i.e., spacing) between elements +provided to \code{...}. Numeric values are treated as pixel values; character +values may use units like \code{"px"}, \code{"rem"}, or \code{"\%"}, or CSS functions like +\code{"calc(1rem + 2px)"}. This argument is only applicable when +\code{fillable = TRUE}.} \item{class}{Additional CSS classes for the returned UI element.} } diff --git a/man/layout_columns.Rd b/man/layout_columns.Rd index 4a82326d1..cdb6ed176 100644 --- a/man/layout_columns.Rd +++ b/man/layout_columns.Rd @@ -44,13 +44,13 @@ above. (\code{fr}) height of the relevant row. If there are more rows than values provided, the pattern will repeat. For example, \code{row_heights = c(1, 2)} allows even rows to take up twice as much space as odd rows. -\item A list of numeric and \link[htmltools:validateCssUnit]{CSS length units}, +\item A list of numeric values and \link[htmltools:validateCssUnit]{CSS lengths}, where each value represents the height of the relevant row. If more rows are needed than values provided, the pattern will repeat. For example, \code{row_heights = list("auto", 1)} allows the height of odd rows to be driven by its contents and even rows to be \href{https://css-tricks.com/introduction-fr-css-unit/}{\verb{1fr}}. -\item A character vector/string of \link[htmltools:validateCssUnit]{CSS length units}. +\item A character vector/string of \link[htmltools:validateCssUnit]{CSS lengths}. In this case, the value is supplied directly to \code{grid-auto-rows}. \item A \code{\link[=breakpoints]{breakpoints()}} object, where each breakpoint may be either of the above. }} @@ -60,8 +60,11 @@ fillable container with an opinionated height (e.g., \code{page_fillable()}).} \item{fillable}{Whether or not each element is wrapped in a fillable container.} -\item{gap}{A \link[htmltools:validateCssUnit]{CSS length unit} defining the -\code{gap} (i.e., spacing) between elements provided to \code{...}. This argument is only applicable when \code{fillable = TRUE}} +\item{gap}{A CSS length defining the gap (i.e., spacing) between elements +provided to \code{...}. Numeric values are treated as pixel values; character +values may use units like \code{"px"}, \code{"rem"}, or \code{"\%"}, or CSS functions like +\code{"calc(1rem + 2px)"}. This argument is only applicable when +\code{fillable = TRUE}.} \item{class}{Additional CSS classes for the returned UI element.}