Add "Modifiers" helper functions

DESCRIPTION

@@ -8,9 +8,11 @@ Authors@R:
            email = "g.adenbuie@gmail.com")
 Description: What the package does (one paragraph).
 License: MIT + file LICENSE
+Imports: 
+    glue,
+    htmltools,
+    rlang,
+    rmarkdown
 Encoding: UTF-8
 LazyData: true
-Imports: 
-    rmarkdown,
-    htmltools
 RoxygenNote: 6.1.1

NAMESPACE

@@ -1,6 +1,14 @@
 # Generated by roxygen2: do not edit by hand
 
+export(bulma_color)
 export(bulma_document)
+export(bulma_helper)
 export(bulma_level)
+export(bulma_modifier)
+export(bulma_responsive)
+export(bulma_responsive_alignment)
+export(bulma_responsive_size)
+export(bulma_typography)
+importFrom(glue,glue)
 importFrom(htmltools,tag)
 importFrom(htmltools,tagList)

R/bulma-package.R

@@ -1,3 +1,4 @@
 #' @keywords internal
 #' @importFrom htmltools tag tagList
+#' @importFrom glue glue
 "_PACKAGE"

R/modifiers.R

@@ -0,0 +1,260 @@
+c_is <- function(x) {
+  str_trim(paste("is-", x, sep = "", collapse = " "))
+}
+
+c_has <- function(x) {
+  str_trim(paste("has-", x, sep = "", collapse = " "))
+}
+
+c_prefix <- function(x = NULL, prefix = NULL) {
+  if (is.null(x)) return(NULL)
+  paste0(prefix, x)
+}
+
+str_trim <- function(x) {
+  gsub("^\\s*|\\s*$", "", x)
+}
+
+# Modifiers :: Syntax -----------------------------------------------------
+
+#' Bulma Modifier Classes
+#'
+#' @param color "primary", "link", "info", "success", "warning", "danger"
+#' @param size "small", "medium", "large"
+#' @param state "outlined", "loading"
+#'
+#' @return String of modifer classes
+#' @examples
+#' bulma_modifier(color = "primary", size = "large", state = "outlined")
+#' @references https://bulma.io/documentation/modifiers/syntax/
+#' @export
+bulma_modifier <- function(color = NULL, size = NULL, state = NULL) {
+  color <- validate_value(color,
+    c("primary", "link", "info", "success", "warning", "danger"), FALSE, "color")
+  size  <- validate_value(size, c("small", "medium", "large"), FALSE, "size")
+  state <- validate_value(state, c("outlined", "loading"), TRUE, "state")
+  c_is(c(color, size, state))
+}
+
+
+# Modifiers :: Helpers ----------------------------------------------------
+
+#' Bulma Helper Classes
+#'
+#' @param float `clearfix` Fixes an element's floating children
+#'
+#'    `pulled-left` Moves an element to the left
+#'
+#'    `pulled-right` Moves an element to the right
+#' @param spacing `marginless` Removes any margin
+#'
+#'   `paddingless` Removes any padding
+#' @param other `overlay` Completely covers the first positioned parent
+#'   `clipped` Adds overflow hidden
+#'
+#'   `radiusless` Removes any radius
+#'
+#'   `shadowless` Removes any shadow
+#'
+#'   `unselectable` Prevents the text from being selectable
+#'
+#'   `invisible` Adds visibility hidden
+#'
+#'   `sr-only`  Hide elements visually but keep the element available to be announced by a screen reader
+#' @return String of modifer classes
+#' @examples
+#' bulma_helper(float = "pulled-left")
+#' bulma_helper(spacing = c("marginless", "paddingless"))
+#' bulma_helper(other = "clipped", float = "pulled-right")
+#' @references https://bulma.io/documentation/modifiers/helpers
+#' @export
+bulma_helper <- function(float = NULL, spacing = NULL, other = NULL) {
+  float <- validate_value(float, c("clearfix", "pulled-left", "pulled-right"), FALSE, "float")
+  spacing <- validate_value(spacing, c("marginless", "paddingless"), TRUE, "spacing")
+  other <- validate_value(other,
+    c("overlay", "clipped", "radiusless", "shadowless", "unselectable", "invisible", "sr-only"),
+    TRUE, "other")
+  c_is(c(float, spacing, other))
+}
+
+
+# Modifiers :: Responsive Helpers -----------------------------------------
+
+#' Bulma Responsive Helper Classes
+#'
+#' @param display One of "block", "flex", "inline", "inline-block", "inline-flex"
+#' @param viewport One of "mobile", "tablet", "touch", "desktop", "widescreen",
+#'   "fullhd". See <https://bulma.io/documentation/modifiers/responsive-helpers/>
+#'   for more information.
+#'
+#' @examples
+#' bulma_responsive("flex", "tablet")
+#' bulma_responsive("flex", "widescreen", only = TRUE)
+#' @references https://bulma.io/documentation/modifiers/responsive-helpers/
+#' @return A string of helper classes
+#' @export
+bulma_responsive <- function(display = NULL, viewport = NULL, only = FALSE) {
+  display <- validate_value(display, c(
+    "block", "flex", "inline", "inline-block", "inline-flex"
+  ), FALSE, "display")
+  viewport <- validate_value(viewport, c(
+    "mobile", "tablet", "touch", "desktop", "widescreen", "fullhd"
+  ), FALSE, "viewport")
+  c_is(paste(display, viewport, if (only) "only", sep = "-"))
+}
+
+
+# Modifiers :: Color ------------------------------------------------------
+
+#' Bulma Color Helper Classes
+#'
+#' @param text One of "white", "black", "light", "dark", "primary", "info",
+#'   "link", "success", "warning", "danger", "black-bis", "black-ter",
+#'   "grey-darker", "grey-dark", "grey", "gre-light", "grey-lighter",
+#'   "white-ter", "white-bis"
+#' @param background One of "white", "black", "light", "dark", "primary",
+#'   "info", "link", "success", "warning", "danger", "black-bis", "black-ter",
+#'   "grey-darker", "grey-dark", "grey", "gre-light", "grey-lighter",
+#'   "white-ter", "white-bis"
+#'
+#' @examples
+#' bulma_color("white", "black")
+#' bulma_color("white", "primary")
+#'
+#' @references https://bulma.io/documentation/modifiers/color-helpers
+#' @return String of modifer classes
+#' @export
+bulma_color <- function(text = NULL, background = NULL) {
+  text <- validate_value(text, bulma::.bulma_colors, FALSE, "text")
+  text <- c_prefix(text, "text-")
+  background <- validate_value(background, bulma::.bulma_colors, FALSE, "background")
+  background <- c_prefix(background, prefix = "background-")
+  c_has(c(text, background))
+}
+
+.bulma_colors <- c("white", "black", "light", "dark", "primary", "info", "link",
+                   "success", "warning", "danger", "black-bis", "black-ter",
+                   "grey-darker", "grey-dark", "grey", "gre-light", "grey-lighter",
+                   "white-ter", "white-bis")
+
+
+# Modifiers :: Typography -------------------------------------------------
+
+#' Bulma Typography Helper Classes
+#'
+#' @param size One of 1 through 7 (large to small)
+#' @param text One of "white", "black", "light", "dark", "primary", "info",
+#'   "link", "success", "warning", "danger", "black-bis", "black-ter",
+#'   "grey-darker", "grey-dark", "grey", "gre-light", "grey-lighter",
+#'   "white-ter", "white-bis"
+#' @param responsive_size See [bulma_responsive_size()].
+#' @param alignment One of "centered", "justified", "left", "right"
+#' @param transformation One (or more) of "capitalized", "lowercase", "uppercase", "italic"
+#' @param weight One of "light", "normal", "semibold", "bold"
+#' @param font_family One of "sans-serif", "monospace", "primary", "secondary", "code".
+#'   (Coming in version 0.7.3.)
+#'
+#' @examples
+#' bulma_color("white", "black")
+#' bulma_color("white", "primary")
+#'
+#' @references https://bulma.io/documentation/modifiers/typography-helpers/
+#' @return String of modifer classes
+#' @export
+bulma_typography <- function(
+  size = NULL,
+  color = NULL,
+  responsive_size = NULL,
+  alignment = NULL,
+  responsive_alignment = NULL,
+  transformation = NULL,
+  weight = NULL,
+  font_family = NULL
+) {
+  size <- validate_value(paste(size), paste(1:7), FALSE, "size")
+  size <- c_prefix(size, prefix = "size-")
+  responsive_size <- use_bulma_responsive(responsive_size, "size", "responsive_size")
+
+  color <- validate_value(color, bulma::.bulma_colors, FALSE, "text")
+  color <- c_prefix(color, prefix = "text-")
+
+
+  alignment <- validate_value(alignment, c("centered", "justified", "left", "right"),
+                             FALSE, "alignment")
+  alignment <- c_prefix(alignment, "text-")
+  responsive_alignment <- use_bulma_responsive(responsive_alignment, "alignment", "responsive_alignment")
+
+  transformation <- validate_value(transformation,
+    c("capitalized", "lowercase", "uppercase", "italic"), TRUE, "transformation")
+
+  weight <- validate_value(weight, c("light", "normal", "semibold", "bold"), FALSE, "weight")
+  weight <- c_prefix(weight, "text-weight-")
+
+  font_family <- validate_value(font_family, c(
+    "sans-serif", "monospace", "primary", "secondary", "code"
+  ), TRUE, "font_family")
+  font_family <- c_prefix(font_family, "family-")
+
+  x <- paste(
+    c_is(c(size, transformation, font_family)),
+    c_has(c(color, alignment, weight)),
+    responsive_size,
+    responsive_alignment
+  )
+  str_trim(x)
+}
+
+#' Bulma Responsive Size Helper Classes
+#'
+#' @inheritParams bulma_typography
+#' @inheritParams bulma_responsive
+#' @examples
+#' bulma_responsive_size()
+#' bulma_responsive_size(2, "tablet")
+#' bulma_responsive_size(viewport = "widescreen")
+#' @return String of modifier classes
+#' @export
+bulma_responsive_size <- function(size = "1", viewport = "desktop") {
+  # TODO: Needs to be vectorized, matching size/viewport arguments
+  size <- validate_value(paste(size), paste(1:7), FALSE, "size")
+  size <- c_prefix(size, "size-")
+  viewport <- validate_value(viewport,
+    c("mobile", "tablet", "touch", "desktop", "widescreen", "fullhd"),
+    FALSE, "viewport")
+  x <- c_is(paste0(size, "-", viewport))
+  class(x) <- c("responsive_size", "bulma", "character")
+  x
+}
+
+use_bulma_responsive <- function(x, var, varname) {
+  if (!is.null(x)) {
+    if (!inherits(x, glue("responsive_{var}"))) {
+      rlang::abort(glue("Please use bulma_responsive_{var}() to prepare `{varname}`."))
+    }
+    x
+  }
+}
+
+#' Bulma Responsive Alignemnt Helper Classes
+#'
+#' @inheritParams bulma_typography
+#' @inheritParams bulma_responsive_size
+#' @examples
+#' bulma_responsive_alignment()
+#' bulma_responsive_alignment("centered", "tablet")
+#' bulma_responsive_alignment(viewport = "widescreen")
+#' @return String of modifier classes
+#' @references https://bulma.io/documentation/modifiers/typography-helpers/#responsive-alignment
+#' @export
+bulma_responsive_alignment <- function(alignment = "left", viewport = "desktop") {
+  # TODO: Needs to be vectorized, matching alignment/viewport arguments
+  alignment <- validate_value(alignment, c("centered", "justified", "left", "right"),
+                              FALSE, "alignment")
+  alignment <- c_prefix(alignment, "text-")
+  viewport <- validate_value(viewport,
+                             c("mobile", "tablet", "touch", "desktop", "widescreen", "fullhd"),
+                             FALSE, "viewport")
+  x <- c_has(paste0(alignment, "-", viewport))
+  class(x) <- c("responsive_alignment", "bulma", "character")
+  x
+}

R/utils.R

@@ -1,7 +1,40 @@
-div_with_class <- function(..., class = "") {
-  htmltools::tags$div(..., class = class)
+
+apply_tag <- function(ll, tag, class = NULL, extra_attributes = NULL) {
+  lapply(ll, function(x) htmltools::tag(tag, c(x, class = class, extra_attributes)))
+}
+
+dots2list <- function(...) {
+  # Convert dots to list, but return first element if the first element is a list
+  # and the length of ... is 1
+  x <- list(...)
+  if (length(x) == 1 && is.list(x[[1]])) return(x[[1]])
+  x
+}
+
+tag_function <- function(.tag = "div") {
+  function(...) htmltools::tag(.tag, list(...))
 }
 
-apply_tag <- function(..., tag, class = NULL, extra_attributes = NULL) {
-  lapply(list(...), function(x) htmltools::tag(tag, c(x, class = class, extra_attributes)))
+validate_value <- function(value = NULL, choices, several.ok = TRUE, value_name = "") {
+  if (!is.null(value)) {
+    value_name <- if (nchar(value_name) > 0) glue("`{value_name}` - ") else ""
+    if (!several.ok && length(value) > 1) {
+      msg <- glue("{value_name}Using the first of {length(value)} values: {value[1]}")
+      rlang::warn(msg)
+      value <- value[1]
+    }
+    not_in_choices <- setdiff(value, choices)
+    if (length(not_in_choices)) {
+      msg <- glue("{value_name}Ignoring invalid choices: ",
+                  "\"{paste(not_in_choices, collapse = '\", \"')}\"")
+      rlang::warn(msg)
+      value <- intersect(value, choices)
+    }
+    if (length(value)) {
+      value
+    } else {
+      rlang::abort(glue("{value_name}Must be one of the following valid choices: ",
+                        "\"{paste(choices, collapse = '\", \"')}\""))
+    }
+  }
 }

man/bulma-package.Rd

@@ -0,0 +1,15 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/bulma-package.R
+\docType{package}
+\name{bulma-package}
+\alias{bulma}
+\alias{bulma-package}
+\title{bulma: What the Package Does (One Line, Title Case)}
+\description{
+What the package does (one paragraph).
+}
+\author{
+\strong{Maintainer}: Garrick Aden-Buie \email{g.adenbuie@gmail.com}
+
+}
+\keyword{internal}

man/bulma_color.Rd

@@ -0,0 +1,33 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/modifiers.R
+\name{bulma_color}
+\alias{bulma_color}
+\title{Bulma Color Helper Classes}
+\usage{
+bulma_color(text = NULL, background = NULL)
+}
+\arguments{
+\item{text}{One of "white", "black", "light", "dark", "primary", "info",
+"link", "success", "warning", "danger", "black-bis", "black-ter",
+"grey-darker", "grey-dark", "grey", "gre-light", "grey-lighter",
+"white-ter", "white-bis"}
+
+\item{background}{One of "white", "black", "light", "dark", "primary",
+"info", "link", "success", "warning", "danger", "black-bis", "black-ter",
+"grey-darker", "grey-dark", "grey", "gre-light", "grey-lighter",
+"white-ter", "white-bis"}
+}
+\value{
+String of modifer classes
+}
+\description{
+Bulma Color Helper Classes
+}
+\examples{
+bulma_color("white", "black")
+bulma_color("white", "primary")
+
+}
+\references{
+https://bulma.io/documentation/modifiers/color-helpers
+}

man/bulma_helper.Rd

@@ -0,0 +1,46 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/modifiers.R
+\name{bulma_helper}
+\alias{bulma_helper}
+\title{Bulma Helper Classes}
+\usage{
+bulma_helper(float = NULL, spacing = NULL, other = NULL)
+}
+\arguments{
+\item{float}{`clearfix` Fixes an element's floating children
+
+   `pulled-left` Moves an element to the left
+
+   `pulled-right` Moves an element to the right}
+
+\item{spacing}{`marginless` Removes any margin
+
+  `paddingless` Removes any padding}
+
+\item{other}{`overlay` Completely covers the first positioned parent
+  `clipped` Adds overflow hidden
+
+  `radiusless` Removes any radius
+
+  `shadowless` Removes any shadow
+
+  `unselectable` Prevents the text from being selectable
+
+  `invisible` Adds visibility hidden
+
+  `sr-only`  Hide elements visually but keep the element available to be announced by a screen reader}
+}
+\value{
+String of modifer classes
+}
+\description{
+Bulma Helper Classes
+}
+\examples{
+bulma_helper(float = "pulled-left")
+bulma_helper(spacing = c("marginless", "paddingless"))
+bulma_helper(other = "clipped", float = "pulled-right")
+}
+\references{
+https://bulma.io/documentation/modifiers/helpers
+}

man/bulma_modifier.Rd

@@ -0,0 +1,27 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/modifiers.R
+\name{bulma_modifier}
+\alias{bulma_modifier}
+\title{Bulma Modifier Classes}
+\usage{
+bulma_modifier(color = NULL, size = NULL, state = NULL)
+}
+\arguments{
+\item{color}{"primary", "link", "info", "success", "warning", "danger"}
+
+\item{size}{"small", "medium", "large"}
+
+\item{state}{"outlined", "loading"}
+}
+\value{
+String of modifer classes
+}
+\description{
+Bulma Modifier Classes
+}
+\examples{
+bulma_modifier(color = "primary", size = "large", state = "outlined")
+}
+\references{
+https://bulma.io/documentation/modifiers/syntax/
+}

man/bulma_responsive.Rd

@@ -0,0 +1,28 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/modifiers.R
+\name{bulma_responsive}
+\alias{bulma_responsive}
+\title{Bulma Responsive Helper Classes}
+\usage{
+bulma_responsive(display = NULL, viewport = NULL, only = FALSE)
+}
+\arguments{
+\item{display}{One of "block", "flex", "inline", "inline-block", "inline-flex"}
+
+\item{viewport}{One of "mobile", "tablet", "touch", "desktop", "widescreen",
+"fullhd". See <https://bulma.io/documentation/modifiers/responsive-helpers/>
+for more information.}
+}
+\value{
+A string of helper classes
+}
+\description{
+Bulma Responsive Helper Classes
+}
+\examples{
+bulma_responsive("flex", "tablet")
+bulma_responsive("flex", "widescreen", only = TRUE)
+}
+\references{
+https://bulma.io/documentation/modifiers/responsive-helpers/
+}

man/bulma_responsive_alignment.Rd

@@ -0,0 +1,29 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/modifiers.R
+\name{bulma_responsive_alignment}
+\alias{bulma_responsive_alignment}
+\title{Bulma Responsive Alignemnt Helper Classes}
+\usage{
+bulma_responsive_alignment(alignment = "left", viewport = "desktop")
+}
+\arguments{
+\item{alignment}{One of "centered", "justified", "left", "right"}
+
+\item{viewport}{One of "mobile", "tablet", "touch", "desktop", "widescreen",
+"fullhd". See <https://bulma.io/documentation/modifiers/responsive-helpers/>
+for more information.}
+}
+\value{
+String of modifier classes
+}
+\description{
+Bulma Responsive Alignemnt Helper Classes
+}
+\examples{
+bulma_responsive_alignment()
+bulma_responsive_alignment("centered", "tablet")
+bulma_responsive_alignment(viewport = "widescreen")
+}
+\references{
+https://bulma.io/documentation/modifiers/typography-helpers/#responsive-alignment
+}

man/bulma_responsive_size.Rd

@@ -0,0 +1,26 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/modifiers.R
+\name{bulma_responsive_size}
+\alias{bulma_responsive_size}
+\title{Bulma Responsive Size Helper Classes}
+\usage{
+bulma_responsive_size(size = "1", viewport = "desktop")
+}
+\arguments{
+\item{size}{One of 1 through 7 (large to small)}
+
+\item{viewport}{One of "mobile", "tablet", "touch", "desktop", "widescreen",
+"fullhd". See <https://bulma.io/documentation/modifiers/responsive-helpers/>
+for more information.}
+}
+\value{
+String of modifier classes
+}
+\description{
+Bulma Responsive Size Helper Classes
+}
+\examples{
+bulma_responsive_size()
+bulma_responsive_size(2, "tablet")
+bulma_responsive_size(viewport = "widescreen")
+}

man/bulma_typography.Rd

@@ -0,0 +1,43 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/modifiers.R
+\name{bulma_typography}
+\alias{bulma_typography}
+\title{Bulma Typography Helper Classes}
+\usage{
+bulma_typography(size = NULL, color = NULL, responsive_size = NULL,
+  alignment = NULL, responsive_alignment = NULL,
+  transformation = NULL, weight = NULL, font_family = NULL)
+}
+\arguments{
+\item{size}{One of 1 through 7 (large to small)}
+
+\item{responsive_size}{See [bulma_responsive_size()].}
+
+\item{alignment}{One of "centered", "justified", "left", "right"}
+
+\item{transformation}{One (or more) of "capitalized", "lowercase", "uppercase", "italic"}
+
+\item{weight}{One of "light", "normal", "semibold", "bold"}
+
+\item{font_family}{One of "sans-serif", "monospace", "primary", "secondary", "code".
+(Coming in version 0.7.3.)}
+
+\item{text}{One of "white", "black", "light", "dark", "primary", "info",
+"link", "success", "warning", "danger", "black-bis", "black-ter",
+"grey-darker", "grey-dark", "grey", "gre-light", "grey-lighter",
+"white-ter", "white-bis"}
+}
+\value{
+String of modifer classes
+}
+\description{
+Bulma Typography Helper Classes
+}
+\examples{
+bulma_color("white", "black")
+bulma_color("white", "primary")
+
+}
+\references{
+https://bulma.io/documentation/modifiers/typography-helpers/
+}