R/turbo-frame.R

In tjpalanca/hotwire.R: Hotwire for R

#' @title Turbo Frame
#'
#' @description
#' Turbo Frames allow predefined parts of a page to be updated on request. Any
#' links and forms inside a frame are captured, and the frame contents
#' automatically updated after receiving a response. Regardless of whether the
#' server provides a full document, or just a fragment containing an updated
#' version of the requested frame, only that particular frame will be extracted
#' from the response to replace the existing content.
#'
#' [Documentation](https://turbo.hotwired.dev/handbook/frames)
#'
#' @param id      (str) unique identifier
#' @param src     (str) path for lazy loading of the content
#' @param target  (str) target of any links clicked in this:
#'   * `NULL`   - the frame itself
#'   * `"_top"` - the whole window
#'   * `"<id>"` - a specific frame outside tof the current frame
#' @param loading (str) defines loading behavior
#'   * `eager`  - immediately navigating
#'   * `lazy`   - only hwne element is visible in the viewport
#' @param disabled (flg) navigation will not trigger if present
#' @param autoscroll (str) whether to scroll to that area when it's loaded.
#' @param env        (env) calling environment
#' @param ...        (tag) content of the element
#'
#' @family Turbo
#' @export
turbo_frame <- function(id, ...,
                        src = NULL,
                        target = NULL,
                        loading = c("eager", "lazy"),
                        disabled = FALSE,
                        autoscroll = c("start", "end", "center", "nearest"),
                        env = parent.frame()) {

  assert_string(id)
  assert_string(src, null.ok = TRUE)
  assert_string(target, null.ok = TRUE)
  assert_flag(disabled)
  autoscroll <- match_arg(autoscroll)
  loading <- match_arg(loading)

  tag(
    `_tag_name` = "turbo-frame",
    varArgs = list(
      id   = id,
      src = src,
      target = target,
      loading = loading,
      disabled = if (disabled) NA else NULL,
      autoscroll = if (!is.null(autoscroll)) "true" else NULL,
      `data-autoscroll-block` = autoscroll,
      html_tags(..., env = env)
    )
  ) %>%
    add_class("turbo_frame")

}