#' Create a Polygon Symbolizer
#'
#' @description
#' Creates a polygon symbolizer for rendering filled polygon features.
#'
#' @param fill Character. Fill color for the polygon. Can be a CSS color
#'   string or a function specification.
#' @param stroke Character. Stroke (outline) color. Default is NULL (no stroke).
#' @param width Numeric. Stroke width in pixels. Default is 1.
#' @param opacity Numeric. Fill opacity from 0 to 1. Default is 1.
#' @param pattern Character. Fill pattern. One of NULL, "hatch", or "dot".
#' @param ... Additional symbolizer options.
#'
#' @return A list representing the symbolizer configuration.
#'
#' @examples
#' # Simple blue fill
#' pmPolygonSymbolizer(fill = "steelblue")
#'
#' # With stroke
#' pmPolygonSymbolizer(fill = "#f0f0f0", stroke = "#333", width = 2)
#'
#' @export
pmPolygonSymbolizer <- function(fill = "#cccccc",
                                 stroke = NULL,
                                 width = 1,
                                 opacity = 1,
                                 pattern = NULL,
                                 ...) {
  opts <- list(fill = fill, ...)

  if (!is.null(stroke)) opts$stroke <- stroke
  if (width != 1) opts$width <- width
  if (opacity != 1) opts$opacity <- opacity
  if (!is.null(pattern)) opts$pattern <- pattern

  list(
    type = "polygon",
    options = opts
  )
}


#' Create a Line Symbolizer
#'
#' @description
#' Creates a line symbolizer for rendering line features.
#'
#' @param color Character. Line color. Default is "#000000".
#' @param width Numeric or function. Line width in pixels. Can be a fixed
#'   value or a zoom-dependent specification.
#' @param dash List or NULL. Dash pattern as a vector of numbers, e.g.,
#'   \code{c(4, 2)} for 4px dash, 2px gap.
#' @param dashColor Character. Color for dashes if using dash pattern.
#' @param dashWidth Numeric. Width of dashes.
#' @param lineCap Character. Line cap style: "butt", "round", or "square".
#' @param lineJoin Character
#' . Line join style: "miter", "round", or "bevel".
#' @param opacity Numeric. Line opacity from 0 to 1. Default is 1.
#' @param ... Additional symbolizer options.
#'
#' @return A list representing the symbolizer configuration.
#'
#' @examples
#' # Simple black line
#' pmLineSymbolizer(color = "black", width = 2)
#'
#' # Dashed line
#' pmLineSymbolizer(color = "gray", width = 1, dash = c(4, 2))
#'
#' @export
pmLineSymbolizer <- function(color = "#000000",
                              width = 1,
                              dash = NULL,
                              dashColor = NULL,
                              dashWidth = NULL,
                              lineCap = NULL,
                              lineJoin = NULL,
                              opacity = 1,
                              ...) {
  opts <- list(color = color, width = width, ...)

  if (!is.null(dash)) opts$dash <- dash
  if (!is.null(dashColor)) opts$dashColor <- dashColor
  if (!is.null(dashWidth)) opts$dashWidth <- dashWidth
  if (!is.null(lineCap)) opts$lineCap <- lineCap
  if (!is.null(lineJoin)) opts$lineJoin <- lineJoin
  if (opacity != 1) opts$opacity <- opacity

  list(
    type = "line",
    options = opts
  )
}


#' Create a Circle Symbolizer
#'
#' @description
#' Creates a circle symbolizer for rendering point features as circles.
#'
#' @param radius Numeric. Circle radius in pixels. Default is 4.
#' @param fill Character. Fill color for the circle. Default is "#000000".
#' @param stroke Character. Stroke (outline) color. Default is NULL.
#' @param width Numeric. Stroke width in pixels. Default is 1.
#' @param opacity Numeric. Fill opacity from 0 to 1. Default is 1.
#' @param ... Additional symbolizer options.
#'
#' @return A list representing the symbolizer configuration.
#'
#' @examples
#' # Simple red circle
#' pmCircleSymbolizer(radius = 6, fill = "red")
#'
#' # Circle with stroke
#' pmCircleSymbolizer(radius = 8, fill = "white", stroke = "black", width = 2)
#'
#' @export
pmCircleSymbolizer <- function(radius = 4,
                                fill = "#000000",
                                stroke = NULL,
                                width = 1,
                                opacity = 1,
                                ...) {
  opts <- list(radius = radius, fill = fill, ...)

  if (!is.null(stroke)) opts$stroke <- stroke
  if (width != 1) opts$width <- width
  if (opacity != 1) opts$opacity <- opacity

  list(
    type = "circle",
    options = opts
  )
}


#' Create a Text Symbolizer
#'
#' @description
#' Creates a text symbolizer for rendering text labels.
#'
#' @param font Character. Font specification (e.g., "12px sans-serif").
#' @param fill Character. Text fill color. Default is "#000000".
#' @param stroke Character. Text stroke (halo) color. Default is NULL.
#' @param width Numeric. Stroke width for text halo. Default is 0.
#' @param labelProps List. Properties to use for label text, in order of
#'   preference. Default is \code{list("name")}.
#' @param textTransform Character. Text transformation: "uppercase",
#'   "lowercase", or NULL.
#' @param ... Additional symbolizer options.
#'
#' @return A list representing the symbolizer configuration.
#'
#' @examples
#' # Simple text label
#' pmTextSymbolizer(font = "12px Arial", fill = "black")
#'
#' # Text with halo
#' pmTextSymbolizer(font = "14px sans-serif", fill = "black",
#'                  stroke = "white", width = 2)
#'
#' @export
pmTextSymbolizer <- function(font = "12px sans-serif",
                              fill = "#000000",
                              stroke = NULL,
                              width = 0,
                              labelProps = NULL,
                              textTransform = NULL,
                              ...) {
  opts <- list(font = font, fill = fill, ...)

  if (!is.null(stroke)) opts$stroke <- stroke
  if (width > 0) opts$width <- width
  if (!is.null(labelProps)) opts$labelProps <- labelProps
  if (!is.null(textTransform)) opts$textTransform <- textTransform

  list(
    type = "text",
    options = opts
  )
}


#' Create a Centered Text Symbolizer
#'
#' @description
#' Creates a centered text symbolizer for rendering text labels centered
#' on point features.
#'
#' @param font Character. Font specification (e.g., "12px sans-serif").
#' @param fill Character. Text fill color. Default is "#000000".
#' @param stroke Character. Text stroke (halo) color. Default is NULL.
#' @param width Numeric. Stroke width for text halo. Default is 0.
#' @param lineHeight Numeric. Line height multiplier for multi-line labels.
#'   Default is NULL (uses library default). Use values like 1.0-1.2 for
#'   tighter spacing.
#' @param labelProps List. Properties to use for label text, in order of
#'   preference. Default is \code{list("name")}.
#' @param ... Additional symbolizer options.
#'
#' @return A list representing the symbolizer configuration.
#'
#' @examples
#' pmCenteredTextSymbolizer(font = "14px Arial", fill = "black")
#'
#' # Tighter line spacing for multi-word labels
#' pmCenteredTextSymbolizer(font = "11px sans-serif", fill = "#444",
#'                          lineHeight = 1.1)
#'
#' @export
pmCenteredTextSymbolizer <- function(font = "12px sans-serif",
                                      fill = "#000000",
                                      stroke = NULL,
                                      width = 0,
                                      lineHeight = NULL,
                                      labelProps = NULL,
                                      ...) {
  opts <- list(font = font, fill = fill, ...)

  if (!is.null(stroke)) opts$stroke <- stroke
  if (width > 0) opts$width <- width
  if (!is.null(lineHeight)) opts$lineHeight <- lineHeight
  if (!is.null(labelProps)) opts$labelProps <- labelProps

  list(
    type = "centeredText",
    options = opts
  )
}


#' Create a Line Label Symbolizer
#'
#' @description
#' Creates a line label symbolizer for rendering text labels along line
#' features (e.g., street names).
#'
#' @param font Character. Font specification (e.g., "12px sans-serif").
#' @param fill Character. Text fill color. Default is "#000000".
#' @param stroke Character. Text stroke (halo) color. Default is NULL.
#' @param width Numeric. Stroke width for text halo. Default is 0.
#' @param labelProps List. Properties to use for label text.
#' @param ... Additional symbolizer options.
#'
#' @return A list representing the symbolizer configuration.
#'
#' @examples
#' pmLineLabelSymbolizer(font = "11px Arial", fill = "#333",
#'                       stroke = "white", width = 2)
#'
#' @export
pmLineLabelSymbolizer <- function(font = "12px sans-serif",
                                   fill = "#000000",
                                   stroke = NULL,
                                   width = 0,
                                   labelProps = NULL,
                                   ...) {
  opts <- list(font = font, fill = fill, ...)

  if (!is.null(stroke)) opts$stroke <- stroke
  if (width > 0) opts$width <- width
  if (!is.null(labelProps)) opts$labelProps <- labelProps

  list(
    type = "lineLabel",
    options = opts
  )
}


#' Create a Shield Symbolizer
#'
#' @description
#' Creates a shield symbolizer for rendering labeled badges or shields
#' (e.g., highway route markers).
#'
#' @param font Character. Font specification for shield text.
#' @param fill Character. Text fill color. Default is "#000000".
#' @param background Character. Shield background color. Default is "#ffffff".
#' @param stroke Character. Shield border color. Default is "#000000".
#' @param padding Numeric. Padding inside the shield in pixels. Default is 2.
#' @param labelProps List. Properties to use for shield text.
#' @param ... Additional symbolizer options.
#'
#' @return A list representing the symbolizer configuration.
#'
#' @examples
#' pmShieldSymbolizer(font = "10px Arial", fill = "black",
#'                    background = "white", stroke = "black")
#'
#' @export
pmShieldSymbolizer <- function(font = "10px sans-serif",
                                fill = "#000000",
                                background = "#ffffff",
                                stroke = "#000000",
                                padding = 2,
                                labelProps = NULL,
                                ...) {
  opts <- list(
    font = font,
    fill = fill,
    background = background,
    stroke = stroke,
    padding = padding,
    ...
  )

  if (!is.null(labelProps)) opts$labelProps <- labelProps

  list(
    type = "shield",
    options = opts
  )
}