feat: implement 9 W3.CSS helper components (#2, #5, #12, #15, #17, #19, #20, #21, #26)

.github/workflows/R-CMD-check.yaml

@@ -29,7 +29,7 @@ jobs:
       R_KEEP_PKG_SOURCE: yes
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - uses: r-lib/actions/setup-pandoc@v2
 

DESCRIPTION

@@ -13,7 +13,7 @@ License: MIT + file LICENSE
 Encoding: UTF-8
 LazyData: true
 Roxygen: list(markdown = TRUE)
-RoxygenNote: 7.2.3
+RoxygenNote: 7.3.3
 Depends: 
     R (>= 2.10)
 Imports: 

NAMESPACE

@@ -1,6 +1,7 @@
 # Generated by roxygen2: do not edit by hand
 
 export(w3_actionButton)
+export(w3_alert)
 export(w3_animate_bottom)
 export(w3_animate_fading)
 export(w3_animate_left)
@@ -20,6 +21,8 @@ export(w3_bottombar)
 export(w3_center)
 export(w3_checkbox)
 export(w3_checkboxGroupInput)
+export(w3_code)
+export(w3_codespan)
 export(w3_col)
 export(w3_color)
 export(w3_container)
@@ -30,24 +33,31 @@ export(w3_half)
 export(w3_hide_modal)
 export(w3_hover_border_color)
 export(w3_hover_color)
+export(w3_icon)
 export(w3_left_align)
 export(w3_leftbar)
 export(w3_list)
+export(w3_margin)
 export(w3_modal)
+export(w3_note)
 export(w3_numericInput)
 export(w3_opacity)
 export(w3_padding)
 export(w3_page)
 export(w3_panel)
 export(w3_passwordInput)
+export(w3_progressbar)
 export(w3_quarter)
+export(w3_quote)
 export(w3_radioButton)
 export(w3_rest)
 export(w3_right_align)
 export(w3_rightbar)
+export(w3_round)
 export(w3_selectInput)
 export(w3_show_modal)
 export(w3_spin)
+export(w3_tag)
 export(w3_textInput)
 export(w3_text_color)
 export(w3_third)

R/w3css_alerts.R

@@ -0,0 +1,26 @@
+#' W3.CSS Alerts
+#'
+#' Implementation of W3.CSS Alerts, as described in
+#' [https://www.w3schools.com/w3css/w3css_alerts.asp](https://www.w3schools.com/w3css/w3css_alerts.asp)
+#'
+#' @param ... alert content.
+#' @param level any W3 color name accepted by [w3_color()] (e.g.
+#'   `"red"`, `"yellow"`, `"teal"`, `"deep-orange"`). Controls the
+#'   background color class. Defaults to `"red"`. Validation is delegated
+#'   to [w3_color()] so the full W3 palette is accepted.
+#'
+#' @return an htmltools tag.
+#' @export
+#'
+#' @importFrom htmltools tags
+#'
+#' @examples
+#' w3_alert("Danger!")
+#' w3_alert("Heads up!", level = "yellow")
+#' w3_alert("Looks good!", level = "teal")
+w3_alert <- function(..., level = "red") {
+  tags$div(
+    class = paste("w3-panel", w3_color(level)),
+    tags$p(...)
+  )
+}

R/w3css_code.R

@@ -0,0 +1,27 @@
+#' W3.CSS Code
+#'
+#' Implementation of W3.CSS Code, as described in
+#' [https://www.w3schools.com/w3css/w3css_code.asp](https://www.w3schools.com/w3css/w3css_code.asp).
+#' `w3_code()` renders a `<pre class="w3-code">` block, `w3_codespan()`
+#' renders an inline `<code class="w3-codespan">` span.
+#'
+#' @param ... code content.
+#'
+#' @return an htmltools tag.
+#' @export
+#'
+#' @importFrom htmltools tags
+#'
+#' @examples
+#' w3_code("x <- 1")
+w3_code <- function(...) {
+  tags$pre(class = "w3-code", ...)
+}
+
+#' @rdname w3_code
+#' @export
+#' @examples
+#' w3_codespan("foo")
+w3_codespan <- function(...) {
+  tags$code(class = "w3-codespan", ...)
+}

R/w3css_icons.R

@@ -0,0 +1,31 @@
+#' W3.CSS Icons
+#'
+#' Implementation of W3.CSS Icons, as described in
+#' [https://www.w3schools.com/w3css/w3css_icons.asp](https://www.w3schools.com/w3css/w3css_icons.asp).
+#' Renders an `<i class="fa fa-...">` element; you must include the
+#' corresponding Font Awesome stylesheet in the page (see `shiny::icon()` for
+#' a matching loader).
+#'
+#' @param name icon name (without the `fa-` prefix), e.g. `"home"`,
+#'   `"cloud"`, `"search"`.
+#' @param library icon CSS prefix. `"fa"` (Font Awesome) by default;
+#'   `"w3"` uses the W3 icon set instead (`"w3-icon w3-..."`).
+#' @param ... extra attributes passed to the `<i>` tag.
+#'
+#' @return an htmltools tag.
+#' @export
+#'
+#' @importFrom htmltools tags
+#'
+#' @examples
+#' w3_icon("home")
+#' w3_icon("cloud", library = "fa")
+w3_icon <- function(name, library = c("fa", "w3"), ...) {
+  library <- match.arg(library)
+  cls <- switch(
+    library,
+    fa = sprintf("fa fa-%s", name),
+    w3 = sprintf("w3-icon w3-%s", name)
+  )
+  tags$i(class = cls, ...)
+}

R/w3css_margins.R

@@ -0,0 +1,18 @@
+#' W3.CSS Margins
+#'
+#' Implementation of W3.CSS Margins, as described in
+#' [https://www.w3schools.com/w3css/w3css_margins.asp](https://www.w3schools.com/w3css/w3css_margins.asp).
+#'
+#' @param side one of `"all"` (default), `"top"`, `"right"`, `"bottom"`,
+#'   `"left"`. `"all"` returns the plain `w3-margin` class.
+#'
+#' @return the matching CSS class name.
+#' @export
+#'
+#' @examples
+#' w3_margin()
+#' w3_margin("top")
+w3_margin <- function(side = c("all", "top", "right", "bottom", "left")) {
+  side <- match.arg(side)
+  if (side == "all") "w3-margin" else sprintf("w3-margin-%s", side)
+}

R/w3css_notes.R

@@ -0,0 +1,27 @@
+#' W3.CSS Notes
+#'
+#' Implementation of W3.CSS Notes, as described in
+#' [https://www.w3schools.com/w3css/w3css_notes.asp](https://www.w3schools.com/w3css/w3css_notes.asp)
+#'
+#' @param ... note content.
+#' @param level one of `"yellow"`, `"red"`, `"blue"`, `"green"` — border
+#'   color. Defaults to `"yellow"`.
+#'
+#' @return an htmltools tag.
+#' @export
+#'
+#' @importFrom htmltools tags
+#'
+#' @examples
+#' w3_note("Important: read this first.")
+w3_note <- function(..., level = c("yellow", "red", "blue", "green")) {
+  level <- match.arg(level)
+  tags$div(
+    class = paste(
+      "w3-panel", "w3-leftbar",
+      sprintf("w3-border-%s", level),
+      sprintf("w3-pale-%s", level)
+    ),
+    tags$p(...)
+  )
+}

R/w3css_progressbar.R

@@ -0,0 +1,38 @@
+#' W3.CSS Progress Bars
+#'
+#' Implementation of W3.CSS Progress Bars, as described in
+#' [https://www.w3schools.com/w3css/w3css_progressbar.asp](https://www.w3schools.com/w3css/w3css_progressbar.asp).
+#'
+#' The outer wrapper carries the WAI-ARIA `role="progressbar"` and the
+#' `aria-valuenow / aria-valuemin / aria-valuemax` attributes so screen
+#' readers announce the progress correctly.
+#'
+#' @param value numeric(1) in `[0, 100]`, current progress value.
+#' @param color W3 color name applied to the inner bar (default `"green"`).
+#' @param show_label logical, show the numeric value inside the bar.
+#'
+#' @return an htmltools tag.
+#' @export
+#'
+#' @importFrom htmltools tags
+#'
+#' @examples
+#' w3_progressbar(25)
+#' w3_progressbar(80, color = "blue", show_label = TRUE)
+w3_progressbar <- function(value, color = "green", show_label = FALSE) {
+  stopifnot(is.numeric(value), length(value) == 1L, !is.na(value))
+  value <- max(0, min(100, value))
+  inner <- tags$div(
+    class = paste("w3-container", w3_color(color)),
+    style = sprintf("width:%s%%", value),
+    if (show_label) sprintf("%s%%", value) else NULL
+  )
+  tags$div(
+    class = "w3-light-grey",
+    role = "progressbar",
+    `aria-valuenow` = as.character(value),
+    `aria-valuemin` = "0",
+    `aria-valuemax` = "100",
+    inner
+  )
+}

R/w3css_quotes.R

@@ -0,0 +1,22 @@
+#' W3.CSS Quotes
+#'
+#' Implementation of W3.CSS Quotes, as described in
+#' [https://www.w3schools.com/w3css/w3css_quotes.asp](https://www.w3schools.com/w3css/w3css_quotes.asp)
+#'
+#' @param ... quote content.
+#' @param panel logical, wrap the blockquote in a styled panel. `TRUE` by default.
+#'
+#' @return an htmltools tag.
+#' @export
+#'
+#' @importFrom htmltools tags
+#'
+#' @examples
+#' w3_quote("Be yourself — everyone else is already taken.")
+w3_quote <- function(..., panel = TRUE) {
+  bq <- tags$blockquote(
+    class = if (panel) "w3-panel w3-leftbar w3-light-grey" else NULL,
+    ...
+  )
+  bq
+}

R/w3css_round.R

@@ -0,0 +1,19 @@
+#' W3.CSS Rounded corners
+#'
+#' Implementation of W3.CSS Round, as described in
+#' [https://www.w3schools.com/w3css/w3css_round.asp](https://www.w3schools.com/w3css/w3css_round.asp).
+#'
+#' @param size corner size. One of `"default"`, `"small"`, `"medium"`,
+#'   `"large"`, `"xlarge"`, `"xxlarge"`.
+#'
+#' @return the matching CSS class name.
+#' @export
+#'
+#' @examples
+#' w3_round()
+#' w3_round("small")
+#' w3_round("xxlarge")
+w3_round <- function(size = c("default", "small", "medium", "large", "xlarge", "xxlarge")) {
+  size <- match.arg(size)
+  if (size == "default") "w3-round" else sprintf("w3-round-%s", size)
+}