bulma/R/modifiers.R

# 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/
#' @seealso Bulma modifiers
#' @return String of modifier classes
#' @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
#' @seealso Bulma modifiers
#' @return String of modifier classes
#' @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
#' @seealso Bulma modifiers
#' @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_viewport(viewport)
  c_is(paste(display, viewport, if (only) "only", sep = "-"))
}

validate_viewport <- function(viewport, var_name = "viewport") {
  validate_value(viewport, bulma_constants("viewports") , FALSE, var_name)
}

# 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", "grey-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", "grey-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
#' @seealso Bulma modifiers
#' @export
bulma_color <- function(text = NULL, background = NULL) {
  text <- validate_color(text, "text")
  background <- validate_color(background, "background")
  c_has(c(text, background))
}

validate_color <- function(color, var_name = "text", prefix = paste0(var_name, "-"), several.ok = FALSE) {
  color <- validate_value(color, bulma_constants("colors"), several.ok, var_name)
  c_prefix(color, prefix)
}

# 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", "grey-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
#' @seealso Bulma modifiers
#' @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_color(color, "color", "text-")

  alignment <- validate_alignment(alignment)
  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)
}

validate_alignment <- function(alignment, var_name = "alignment", prefix = "text-") {
  alignment <- validate_value(alignment, bulma_constants("alignment"), FALSE, var_name)
  c_prefix(alignment, prefix)
}

#' 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
#' @seealso Bulma modifiers
#' @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_viewport(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
#' @seealso Bulma modifiers
#' @export
bulma_responsive_alignment <- function(alignment = "left", viewport = "desktop") {
  # TODO: Needs to be vectorized, matching alignment/viewport arguments
  alignment <- validate_alignment(alignment)
  viewport <- validate_viewport(viewport)
  x <- c_has(paste0(alignment, "-", viewport))
  class(x) <- c("responsive_alignment", "bulma", "character")
  x
}