R/wa_popup.R

In shiny.webawesome: 'shiny' Bindings for 'Web Awesome' Components

# Generated by tools/generate_components.R. Do not edit by hand.
# nolint start: object_usage_linter.

#' Create a `wa-popup` component
#'
#' Generated wrapper for the Web Awesome `wa-popup` component.
#' Generated from Web Awesome metadata.
#'
#' @param ... Child content for the component's default slot.
#' @param id Optional DOM id attribute for HTML, CSS, and JS targeting.
#' @param class Optional CSS class string.
#' @param style Optional inline CSS style string.
#' @param active Boolean. Default: `FALSE`. Activates the positioning
#' logic and shows the popup. When this attribute is removed, the
#' positioning logic is torn down and the popup will be hidden.
#' @param anchor The element the popup will be anchored to. If the anchor
#' lives outside of the popup, you can provide the anchor element `id`, a
#' DOM element reference, or a `VirtualElement`. If the anchor lives
#' inside the popup, use the `anchor` slot instead.
#' @param arrow Boolean. Default: `FALSE`. Attaches an arrow to the popup.
#' The arrow's size and color can be customized using the `--arrow-size`
#' and `--arrow-color` custom properties. For additional customizations,
#' you can also target the arrow using `::part(arrow)` in your stylesheet.
#' @param arrow_padding Number. Default: `10`. The amount of padding
#' between the arrow and the edges of the popup. If the popup has a
#' border-radius, for example, this will prevent it from overflowing the
#' corners.
#' @param arrow_placement Enumerated string. Allowed values: `anchor`,
#' `center`, `end`, `start`. Default: `anchor`. The placement of the
#' arrow. The default is `anchor`, which will align the arrow as close to
#' the center of the anchor as possible, considering available space and
#' `arrow-padding`. A value of `start`, `end`, or `center` will align the
#' arrow to the start, end, or center of the popover instead.
#' @param auto_size Enumerated string. Allowed values: `both`,
#' `horizontal`, `vertical`. When set, this will cause the popup to
#' automatically resize itself to prevent it from overflowing.
#' @param auto_size_padding Number. Default: `0`. The amount of padding,
#' in pixels, to exceed before the auto-size behavior will occur.
#' @param auto_size_boundary The auto-size boundary describes clipping
#' element(s) that overflow will be checked relative to when resizing. By
#' default, the boundary includes overflow ancestors that will cause the
#' element to be clipped. If needed, you can change the boundary by
#' passing a reference to one or more elements to this property.
#' @param boundary Enumerated string. Allowed values: `scroll`,
#' `viewport`. Default: `viewport`. The bounding box to use for flipping,
#' shifting, and auto-sizing.
#' @param dir String. Optional Web Awesome attribute.
#' @param distance Number. Default: `0`. The distance in pixels from which
#' to offset the panel away from its anchor.
#' @param flip Boolean. Default: `FALSE`. When set, placement of the popup
#' will flip to the opposite site to keep it in view. You can use
#' `flipFallbackPlacements` to further configure how the fallback
#' placement is determined.
#' @param flip_fallback_placements String. Default: `""`. If the preferred
#' placement doesn't fit, popup will be tested in these fallback
#' placements until one fits. Must be a string of any number of placements
#' separated by a space, e.g. "top bottom left". If no placement fits, the
#' flip fallback strategy will be used instead.
#' @param flip_fallback_strategy Enumerated string. Allowed values:
#' `best-fit`, `initial`. Default: `best-fit`. When neither the preferred
#' placement nor the fallback placements fit, this value will be used to
#' determine whether the popup should be positioned using the best
#' available fit based on available space or as it was initially
#' preferred.
#' @param flip_padding Number. Default: `0`. The amount of padding, in
#' pixels, to exceed before the flip behavior will occur.
#' @param flip_boundary The flip boundary describes clipping element(s)
#' that overflow will be checked relative to when flipping. By default,
#' the boundary includes overflow ancestors that will cause the element to
#' be clipped. If needed, you can change the boundary by passing a
#' reference to one or more elements to this property.
#' @param hover_bridge Boolean. Default: `FALSE`. When a gap exists
#' between the anchor and the popup element, this option will add a "hover
#' bridge" that fills the gap using an invisible element. This makes
#' listening for events such as `mouseenter` and `mouseleave` more sane
#' because the pointer never technically leaves the element. The hover
#' bridge will only be drawn when the popover is active.
#' @param lang String. Optional Web Awesome attribute.
#' @param placement Enumerated string. Allowed values: `bottom`,
#' `bottom-end`, `bottom-start`, `left`, `left-end`, `left-start`,
#' `right`, `right-end`, `right-start`, `top`, `top-end`, `top-start`.
#' Default: `top`. The preferred placement of the popup. Note that the
#' actual placement will vary as configured to keep the panel inside of
#' the viewport.
#' @param shift Boolean. Default: `FALSE`. Moves the popup along the axis
#' to keep it in view when clipped.
#' @param shift_padding Number. Default: `0`. The amount of padding, in
#' pixels, to exceed before the shift behavior will occur.
#' @param shift_boundary The shift boundary describes clipping element(s)
#' that overflow will be checked relative to when shifting. By default,
#' the boundary includes overflow ancestors that will cause the element to
#' be clipped. If needed, you can change the boundary by passing a
#' reference to one or more elements to this property.
#' @param skidding Number. Default: `0`. The distance in pixels from which
#' to offset the panel along its anchor.
#' @param sync Enumerated string. Allowed values: `both`, `height`,
#' `width`. Syncs the popup's width or height to that of the anchor
#' element.
#' @param anchor_slot The element the popup will be anchored to. If the
#' anchor lives outside of the popup, you can use the `anchor` attribute
#' or property instead.
#'
#' @section Shiny Bindings:
#' None.
#'
#' @return An HTML tag for the component.
#'
#' @export
wa_popup <- function(
  ...,
  id = NULL,
  class = NULL,
  style = NULL,
  active = NULL,
  anchor = NULL,
  arrow = NULL,
  arrow_padding = NULL,
  arrow_placement = NULL,
  auto_size = NULL,
  auto_size_padding = NULL,
  auto_size_boundary = NULL,
  boundary = NULL,
  dir = NULL,
  distance = NULL,
  flip = NULL,
  flip_fallback_placements = NULL,
  flip_fallback_strategy = NULL,
  flip_padding = NULL,
  flip_boundary = NULL,
  hover_bridge = NULL,
  lang = NULL,
  placement = NULL,
  shift = NULL,
  shift_padding = NULL,
  shift_boundary = NULL,
  skidding = NULL,
  sync = NULL,
  anchor_slot = NULL
) {
  children <- list(...)
  children <- c(
    children,
    list(
      .wa_slot(anchor_slot, "anchor")
    )
  )

  if (!is.null(arrow_placement)) {
    arrow_placement <- .wa_match_arg(
      arrow_placement,
      "arrow_placement",
      c(
        "anchor",
        "center",
        "end",
        "start"
      )
    )
  }

  if (!is.null(auto_size)) {
    auto_size <- .wa_match_arg(
      auto_size,
      "auto_size",
      c(
        "both",
        "horizontal",
        "vertical"
      )
    )
  }

  if (!is.null(boundary)) {
    boundary <- .wa_match_arg(
      boundary,
      "boundary",
      c(
        "scroll",
        "viewport"
      )
    )
  }

  if (!is.null(flip_fallback_strategy)) {
    flip_fallback_strategy <- .wa_match_arg(
      flip_fallback_strategy,
      "flip_fallback_strategy",
      c(
        "best-fit",
        "initial"
      )
    )
  }

  if (!is.null(placement)) {
    placement <- .wa_match_arg(
      placement,
      "placement",
      c(
        "bottom",
        "bottom-end",
        "bottom-start",
        "left",
        "left-end",
        "left-start",
        "right",
        "right-end",
        "right-start",
        "top",
        "top-end",
        "top-start"
      )
    )
  }

  if (!is.null(sync)) {
    sync <- .wa_match_arg(
      sync,
      "sync",
      c(
        "both",
        "height",
        "width"
      )
    )
  }

  attrs <- .wa_normalize_attrs(
    list(
      "id" = id,
      "class" = class,
      "style" = style,
      "active" = active,
      "anchor" = anchor,
      "arrow" = arrow,
      "arrow-padding" = arrow_padding,
      "arrow-placement" = arrow_placement,
      "auto-size" = auto_size,
      "auto-size-padding" = auto_size_padding,
      "autoSizeBoundary" = auto_size_boundary,
      "boundary" = boundary,
      "dir" = dir,
      "distance" = distance,
      "flip" = flip,
      "flip-fallback-placements" = flip_fallback_placements,
      "flip-fallback-strategy" = flip_fallback_strategy,
      "flip-padding" = flip_padding,
      "flipBoundary" = flip_boundary,
      "hover-bridge" = hover_bridge,
      "lang" = lang,
      "placement" = placement,
      "shift" = shift,
      "shift-padding" = shift_padding,
      "shiftBoundary" = shift_boundary,
      "skidding" = skidding,
      "sync" = sync
    ),
    boolean_names = c(
      "active",
      "arrow",
      "flip",
      "hover-bridge",
      "shift"
    ),
    boolean_arg_names = c(
      "active" = "active",
      "arrow" = "arrow",
      "flip" = "flip",
      "hover-bridge" = "hover_bridge",
      "shift" = "shift"
    )
  )

  do.call(
    .wa_component,
    c(
      list("wa-popup", .attrs = attrs),
      children
    )
  )
}
# nolint end