Add gq_tmap_legend() helper — check tmap upstream first

[NewGraphEnvironment]

Problem

Every tmap composition requires manually assembling tm_add_legend() calls with parallel vectors of colors, labels, widths, and shapes pulled individually from gq_style(). For maps with 10+ layers across polygons, lines, and points, this is repetitive and error-prone. We make these maps constantly.

Current pattern (3 separate calls per map):

tm_add_legend(type = "polygons",
  labels = c("Lake", "Wetland"),
  fill = c(gq_style(reg, "lake")$fill$color, gq_style(reg, "wetland")$fill$color))
tm_add_legend(type = "lines", ...)
tm_add_legend(type = "symbols", ...)

Proposed Solution

gq_tmap_legend() helper that takes a list of layer specs and returns legend elements. Build in gq first, prove with real maps, then propose upstream to tmap if maintainers are receptive.

tmap Prior Art (researched 2026-03-10)

No structured legend builder exists anywhere in tmap. tm_add_legend() requires manual parallel vectors, one call per geometry type.

Key tmap issues:

• #1179 (closed Aug 2025): tm_comp_group() doesn't work with tm_add_legend(). Workaround: tm_components("tm_legend", stack = "horizontal")
• #1226: Text legends crash in interactive mode
• #1224: Missing legends for certain column names
• #1203: Bivariate legend customization limitations
• #1036: Side-positioned legend titles (open feature request)

Maintainer (Martijn Tennekes) is active, merges doc/improvement PRs, careful about backwards compat. No open PRs for structured legend specs — nobody has formally requested it yet.

Design Considerations

• Mixed symbol types (polygons, lines, points) grouped automatically
• Simple + classified layers in the same legend
• field override for alternative data sources
• Filtering classified layers to values present in the data
• Custom lty, shape overrides (railway twodash, falls square, etc.)
• Labels from registry or user-supplied

Start simple, expand as patterns emerge from real maps. If tmap upstream is receptive, contribute the pattern there and keep gq thin.