#' Create a Paint Rule
#'
#' @description
#' Creates a paint rule that specifies how to render features from a
#' particular data layer. Paint rules control the visual appearance of
#' polygon, line, and point features.
#'
#' @param dataLayer Character. The name of the data layer in the vector
#'   tile source (e.g., "water", "earth", "roads").
#' @param symbolizer A symbolizer object created with one of the symbolizer
#'   functions (e.g., \code{\link{pmPolygonSymbolizer}},
#'   \code{\link{pmLineSymbolizer}}).
#' @param minzoom Numeric. Minimum zoom level at which this rule applies.
#'   Default is NULL (applies at all zoom levels).
#' @param maxzoom Numeric. Maximum zoom level at which this rule applies.
#'   Default is NULL (applies at all zoom levels).
#' @param filter Character. A JavaScript expression string that filters
#'   features. The expression has access to \code{zoom} and \code{feature}
#'   variables. Default is NULL (no filter).
#'
#' @return A list representing the paint rule configuration.
#'
#' @examples
#' # Render water polygons in blue
#' pmPaintRule("water", pmPolygonSymbolizer(fill = "steelblue"))
#'
#' # Render roads with zoom-dependent visibility
#' pmPaintRule("roads", pmLineSymbolizer(color = "gray", width = 2),
#'             minzoom = 10)
#'
#' # Filter to only show highways
#' pmPaintRule("roads",
#'             pmLineSymbolizer(color = "orange", width = 4),
#'             filter = "feature.props.kind === 'highway'")
#'
#' @export
pmPaintRule <- function(dataLayer,
                         symbolizer,
                         minzoom = NULL,
                         maxzoom = NULL,
                         filter = NULL) {
  rule <- list(
    dataLayer = dataLayer,
    symbolizer = symbolizer
  )

  if (!is.null(minzoom)) rule$minzoom <- minzoom
  if (!is.null(maxzoom)) rule$maxzoom <- maxzoom
  if (!is.null(filter)) rule$filter <- filter

  rule
}


#' Create a Label Rule
#'
#' @description
#' Creates a label rule that specifies how to render text labels for
#' features from a particular data layer. Label rules control text
#' placement and styling, with automatic collision detection.
#'
#' @param dataLayer Character. The name of the data layer in the vector
#'   tile source (e.g., "places", "roads").
#' @param symbolizer A text symbolizer object created with one of
#'   \code{\link{pmTextSymbolizer}}, \code{\link{pmCenteredTextSymbolizer}},
#'   \code{\link{pmLineLabelSymbolizer}}, or \code{\link{pmShieldSymbolizer}}.
#' @param minzoom Numeric. Minimum zoom level at which this rule applies.
#'   Default is NULL (applies at all zoom levels).
#' @param maxzoom Numeric. Maximum zoom level at which this rule applies.
#'   Default is NULL (applies at all zoom levels).
#' @param filter Character. A JavaScript expression string that filters
#'   features. Default is NULL (no filter).
#'
#' @return A list representing the label rule configuration.
#'
#' @examples
#' # Label cities
#' pmLabelRule("places",
#'             pmCenteredTextSymbolizer(font = "14px Arial",
#'                                      fill = "black",
#'                                      stroke = "white",
#'                                      width = 2))
#'
#' # Label streets along their paths
#' pmLabelRule("roads",
#'             pmLineLabelSymbolizer(font = "11px Arial",
#'                                   fill = "#333"),
#'             minzoom = 14)
#'
#' @export
pmLabelRule <- function(dataLayer,
                         symbolizer,
                         minzoom = NULL,
                         maxzoom = NULL,
                         filter = NULL) {
  rule <- list(
    dataLayer = dataLayer,
    symbolizer = symbolizer
  )

  if (!is.null(minzoom)) rule$minzoom <- minzoom
  if (!is.null(maxzoom)) rule$maxzoom <- maxzoom
  if (!is.null(filter)) rule$filter <- filter

  rule
}