#' Create custom color overrides
#'
#' @description
#' Creates a list of color overrides that can be applied to a built-in flavor.
#' This is the recommended way to customize map colors while keeping the
#' proper rendering rules (zoom handling, polygon simplification, etc.).
#'
#' @param background Background color
#' @param earth Land/earth color
#' @param water Water color
#' @param park Park/green space color (also called park_a or park_b)
#' @param wood Forest/woodland color (also called wood_a or wood_b)
#' @param hospital Hospital area color
#' @param industrial Industrial area color
#' @param school School/university area color
#' @param beach Beach color
#' @param glacier Glacier color
#' @param highway Highway road color
#' @param major Major road color
#' @param minor Minor road color
#' @param city_label City label color
#' @param state_label State/region label color
#' @param country_label Country label color
#' @param ocean_label Ocean label color
#' @param ... Additional color properties
#'
#' @return A list of color overrides to pass to \code{\link{addProtomaps}}.
#'
#' @examples
#' # Simple earth and water colors
#' pmColors(earth = "#d3d3d3", water = "#1a3a5c")
#'
#' # Dark theme with custom colors
#' pmColors(
#'   background = "#1a1a2e",
#'   earth = "#1a1a2e",
#'   water = "#16213e",
#'   park = "#1f4037",
#'   highway = "#4a4a6a"
#' )
#'
#' # Minimal grayscale
#' pmColors(
#'   background = "#ffffff",
#'   earth = "#f5f5f5",
#'   water = "#e0e0e0"
#' )
#'
#' @seealso \code{\link{addProtomaps}}, \code{\link{protomaps_colors}}
#' @export
pmColors <- function(background = NULL,
                      earth = NULL,
                      water = NULL,
                      park = NULL,
                      wood = NULL,
                      hospital = NULL,
                      industrial = NULL,
                      school = NULL,
                      beach = NULL,
                      glacier = NULL,
                      highway = NULL,
                      major = NULL,
                      minor = NULL,
                      city_label = NULL,
                      state_label = NULL,
                      country_label = NULL,
                      ocean_label = NULL,
                      ...) {

  # Start with extra args, add named params, remove NULLs
  colors <- c(
    list(...),
    list(
      background = background, earth = earth, water = water,
      hospital = hospital, industrial = industrial, school = school,
      beach = beach, glacier = glacier, highway = highway, major = major,
      city_label = city_label, state_label = state_label,
      country_label = country_label, ocean_label = ocean_label,
      # Expand paired colors
      park_a = park, park_b = park,
      wood_a = wood, wood_b = wood,
      minor_a = minor, minor_b = minor
    )
  )
  colors[!vapply(colors, is.null, logical(1))]
}


#' Protomaps Color Properties Reference
#'
#' @description
#' Reference documentation for all available color properties that can be
#' customized using \code{\link{pmColors}}.
#'
#' @section Base Colors:
#' \describe{
#'   \item{\code{background}}{Map background color}
#'   \item{\code{earth}}{Land/terrain color}
#'   \item{\code{water}}{Water bodies color}
#' }
#'
#' @section Land Use Colors:
#' \describe{
#'   \item{\code{park_a}, \code{park_b}}{Park colors (use \code{park} in pmColors)}
#'   \item{\code{wood_a}, \code{wood_b}}{Forest/woodland colors (use \code{wood} in pmColors)}
#'   \item{\code{hospital}}{Hospital areas}
#'   \item{\code{industrial}}{Industrial zones}
#'   \item{\code{school}}{Schools and universities}
#'   \item{\code{beach}}{Beach areas}
#'   \item{\code{zoo}}{Zoo areas}
#'   \item{\code{aerodrome}}{Airport areas}
#'   \item{\code{glacier}}{Glacier areas}
#' }
#'
#' @section Road Colors:
#' \describe{
#'   \item{\code{highway}}{Highway/motorway color}
#'   \item{\code{major}}{Major road color}
#'   \item{\code{minor_a}, \code{minor_b}}{Minor road colors (use \code{minor} in pmColors)}
#'   \item{\code{railway}}{Railway lines}
#'   \item{\code{pier}}{Pier/dock structures}
#' }
#'
#' @section Label Colors:
#' \describe{
#'   \item{\code{city_label}}{City name labels}
#'   \item{\code{state_label}}{State/region labels}
#'   \item{\code{country_label}}{Country name labels}
#'   \item{\code{ocean_label}}{Ocean/sea labels}
#'   \item{\code{roads_label_major}}{Major road name labels}
#'   \item{\code{roads_label_minor}}{Minor road name labels}
#' }
#'
#' @section Landcover Colors (optional object):
#' These are specified as a nested object:
#' \describe{
#'   \item{\code{grassland}}{Grassland areas}
#'   \item{\code{barren}}{Barren land}
#'   \item{\code{urban_area}}{Urban zones}
#'   \item{\code{farmland}}{Agricultural areas}
#'   \item{\code{forest}}{Forest areas}
#'   \item{\code{scrub}}{Scrubland}
#' }
#'
#' @name protomaps_colors
#' @seealso \code{\link{pmColors}}, \code{\link{addProtomaps}}
NULL