protomapr/vignettes/custom-styling.Rmd

---
title: "Custom Map Styling"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Custom Map Styling}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  eval = FALSE
)
```

*Note: Code examples are not evaluated in this vignette. Copy and run them in your R console to see the interactive maps.*

## Introduction

protomapr provides extensive customization options for map styling. This vignette shows how to create a minimal basemap with custom colors and filtered labels.

## Simple Color Customization

Use `pmColors()` to override specific colors while keeping proper rendering:

```{r}
library(leaflet)
library(protomapr)

leaflet() %>%
  setView(lng = -122.4, lat = 37.8, zoom = 12) %>%
  addProtomaps(
    url = protomaps_url(),
    colors = pmColors(earth = "#f5f5f5", water = "#1a3a5c")
  )
```

## Creating a Minimal Basemap

This example creates a clean, minimal map with:

- Uniform gray land (no parks, forests, or other land use distinctions)
- Dark blue water
- No roads or buildings
- Hierarchical city labels based on importance
- Styled water and island labels

```{r}
leaflet() %>%
  setView(lng = -122.4, lat = 37.8, zoom = 8) %>%
  addProtomaps(
    url = protomaps_url(),
    colors = pmColors(
      # Base colors - all land features same gray
      background = "#d3d3d3",
      earth = "#d3d3d3",
      water = "#1a3a5c",

      # Land use - all matching background
      park = "#d3d3d3",
      wood = "#d3d3d3",
      scrub_a = "#d3d3d3",
      scrub_b = "#d3d3d3",
      glacier = "#d3d3d3",
      sand = "#d3d3d3",
      beach = "#d3d3d3",
      hospital = "#d3d3d3",
      school = "#d3d3d3",
      industrial = "#d3d3d3",
      pedestrian = "#d3d3d3",
      zoo = "#d3d3d3",
      military = "#d3d3d3",
      aerodrome = "#d3d3d3",

      # Hide roads
      highway = "#d3d3d3",
      major = "#d3d3d3",
      medium = "#d3d3d3",
      minor = "#d3d3d3",
      link = "#d3d3d3",
      other = "#d3d3d3",
      railway = "#d3d3d3",
      boundary = "#d3d3d3",
      pier = "#d3d3d3",
      buildings = "#d3d3d3"
    ),
    labelRules = list(
      # States/regions - large italic
      pmLabelRule("places", pmCenteredTextSymbolizer(
        font = "italic 20px sans-serif",
        fill = "#666",
        stroke = "white",
        width = 2
      ), filter = "feature.props.kind === 'region'"),

      # Major metros (min_zoom <= 4: LA, SF, San Diego, Phoenix, Vegas)
      pmLabelRule("places", pmCenteredTextSymbolizer(
        font = "600 18px sans-serif",
        fill = "#111",
        stroke = "white",
        width = 2
      ), filter = "feature.props.kind === 'locality' && feature.props.min_zoom <= 4"),

      # Large cities (min_zoom 5-6: Fresno, Sacramento, Long Beach, etc.)
      pmLabelRule("places", pmCenteredTextSymbolizer(
        font = "600 14px sans-serif",
        fill = "#222",
        stroke = "white",
        width = 2
      ), filter = "feature.props.kind === 'locality' && feature.props.min_zoom > 4 && feature.props.min_zoom <= 6"),

      # Medium cities (min_zoom 7)
      pmLabelRule("places", pmCenteredTextSymbolizer(
        font = "600 12px sans-serif",
        fill = "#333",
        stroke = "white",
        width = 2
      ), filter = "feature.props.kind === 'locality' && feature.props.min_zoom === 7"),

      # Small towns (min_zoom >= 8)
      pmLabelRule("places", pmCenteredTextSymbolizer(
        font = "500 10px sans-serif",
        fill = "#444",
        stroke = "white",
        width = 1
      ), filter = "feature.props.kind === 'locality' && feature.props.min_zoom >= 8"),

      # Water labels
      pmLabelRule("water", pmCenteredTextSymbolizer(
        font = "italic 11px sans-serif",
        fill = "#0d2840",
        stroke = "#d3d3d3",
        width = 1,
        lineHeight = 1.5
      )),

      # Natural features
      pmLabelRule("natural", pmCenteredTextSymbolizer(
        font = "italic 11px sans-serif",
        fill = "#444",
        stroke = "white",
        width = 1,
        lineHeight = 1.5
      )),

      # Earth features (islands)
      pmLabelRule("earth", pmCenteredTextSymbolizer(
        font = "italic 11px sans-serif",
        fill = "#444",
        stroke = "white",
        width = 1,
        lineHeight = 1.5
      ))
    )
  )
```

## Understanding Label Filters

Labels are filtered using JavaScript expressions on feature properties:

### Place Properties

| Property | Description | Example Values |
|----------|-------------|----------------|
| `kind` | Feature type | "country", "region", "locality" |
| `kind_detail` | Specific type | "city", "town", "village", "state" |
| `min_zoom` | Importance (lower = more important) | LA=2, SF=3, Fresno=5 |
| `population_rank` | Population size | Higher = larger |

### Filter Examples

```{r}
# Only states/regions
filter = "feature.props.kind === 'region'"

# Only cities (not towns/villages)
filter = "feature.props.kind_detail === 'city'"

# Major cities only
filter = "feature.props.kind === 'locality' && feature.props.min_zoom <= 4"

# Medium-sized cities
filter = "feature.props.kind === 'locality' && feature.props.min_zoom > 4 && feature.props.min_zoom <= 6"
```

## Symbolizer Options

### Text Symbolizers

```{r}
pmCenteredTextSymbolizer(
  font = "600 14px sans-serif",  # CSS font (weight size family)
  fill = "#222",                  # Text color
  stroke = "white",               # Halo color
  width = 2,                      # Halo width
  lineHeight = 1.5                # Line spacing for multi-word labels
)
```

### Font Specifications

Fonts follow CSS syntax: `"[weight] [style] size family"`

```{r}
# Bold
font = "600 14px sans-serif"
font = "bold 14px Arial"

# Italic
font = "italic 12px sans-serif"

# Bold italic
font = "italic 600 14px sans-serif"
```

## Layer Reference

| Layer | Description |
|-------|-------------|
| `earth` | Land polygons, islands |
| `water` | Water bodies |
| `places` | City/region labels |
| `natural` | Natural features |
| `landuse` | Parks, forests, etc. |
| `roads` | Streets and highways |
| `buildings` | Building footprints |

See `?protomaps_layers` for complete documentation.