Bring composite-legend system and weather docs to main

DESCRIPTION

@@ -39,7 +39,8 @@ Suggests:
     ggrepel,
     ggtext,
     scales,
-    reactable
+    reactable,
+    patchwork
 Config/Needs/website: sf, geofacet, ggtext, quarto, kcuilla/reactablefmtr
 Config/testthat/edition: 3
 Depends:

NAMESPACE

@@ -15,7 +15,10 @@ export(geom_pop)
 export(ggpop_markers)
 export(icon_grid)
 export(key_legend)
+export(legend_box)
 export(legend_canvas)
+export(legend_composite)
+export(legend_ratios)
 export(legend_strip)
 export(marker_legend)
 export(process_data)
@@ -32,7 +35,10 @@ importFrom(ggplot2,draw_key_point)
 importFrom(ggplot2,ggplot)
 importFrom(ggplot2,ggplot_add)
 importFrom(ggplot2,ggplot_build)
+importFrom(ggplot2,ggsave)
 importFrom(ggplot2,last_plot)
+importFrom(ggplot2,margin)
+importFrom(ggplot2,theme)
 importFrom(ggplot2,theme_void)
 importFrom(ggplot2,zeroGrob)
 importFrom(grDevices,as.raster)

NEWS.md

@@ -7,10 +7,23 @@
 - `ggpop_markers()` lists the bundled marker names (and the names found in an `icon_path` folder) - the companion to `fa_icons()` (#383).
 - `marker_legend()` builds a standalone composite legend of icon markers - multiple columns, mixed icon sources (Font Awesome, bundled markers, or your own SVGs), and room for extra annotations - for cases that ggplot2's built-in guides cannot express. For an ordinary data-driven legend, keep using `legend_icons = TRUE` with `scale_legend_icon()` (#385).
 - `marker_legend()` gains a `label_colour` argument (default `"black"`) to control the text colour of both entry labels and the title (#385).
+- `key_legend()` gains a `label_fontface` argument (default `"plain"`) controlling the title and entry-label font face; does not affect the `"point"`-type `"*"` glyph, which stays bold regardless (#393).
+- `legend_canvas()` gains a `label_fontface` argument, passed through to both the grid (`marker_legend()`) and group/symbol (`key_legend()`) sections so the whole composite legend can be set bold/italic/plain from one place (#393).
+- `legend_canvas()` gains a `label_scale` argument - an extra multiplier applied on top of `scale` to the label text sizes only (grid, group, and symbol labels), leaving marker and spacing sizes untouched. Use it to enlarge or shrink every label relative to the markers from one place (#393).
+- `legend_canvas()`'s `scale` now multiplies **every** length uniformly, including `group_width`, `group_gap`, `symbol_right_gap`, and `symbol_key_width` (previously these four were the only lengths left unscaled). This lets the whole legend be written as plain multiples of one base module with `scale` sizing the result. Note: this changes the rendered size of those sections when `scale` is not `1` - divide those four values by your `scale` to reproduce earlier output (#393).
+- `legend_box()` draws a border tightly around a composite legend's actual rendered content. `legend_canvas()` positions sections from nominal geometry, but text labels overflow their anchor points by a font/output-size-dependent amount, so a geometry-derived box clips them; `legend_box()` renders the legend once at the intended output size, measures the true content extent, and fits the border to it (#393).
+- `legend_composite()` builds a bordered three-section legend (icon grid + colour tiles + typed-symbol key) in one call, wrapping `legend_canvas()` + `legend_box()`. Every layout length is a multiple of one `module`, every text size a multiple of one `text` base, and icons one `marker` size; the fixed proportion ladder is `legend_ratios()` (overridable). Supply the content and strip size and it applies the ladder, centres the content, and fits the border (#393).
+- `legend_composite()` gains a `base_width` argument (default `27`): its base sizes are calibrated for a `base_width`-inch strip and multiplied by `width / base_width`, so passing any `width` reproduces the same legend proportions at that physical size - the template now generalises to any figure width, not just the 27-inch one it was tuned on. Set `base_width = width` to size in absolute units instead (#393).
+- `legend_composite()` now warns (class `"ggpop_swatch_aspect_warning"`) when a small `content_range` relative to `width` stretches the group colour swatches into wide banners while the fixed-size icons stay put. The message points to raising `content_range` or reducing `width` so sparse legends stay compact instead of stretched (#393).
+- `legend_ratios()` returns the default proportion ladder used by `legend_composite()` as a named list, for inspection or partial override (#393).
 
 ## Bug Fixes
 
 - `geom_pop()` and `geom_icon_point()` now bake the mapped colour directly into each icon at draw time instead of relying on `ggimage`'s tinting. The previous approach depended on the installed `magick`/ImageMagick build producing an RGBA bitmap; when it did not, icons rendered black even though the legend showed the correct colours. Colours (including custom `scale_colour_*()` scales) and per-group transparency are now applied deterministically (#380).
+- `legend_canvas()`'s default `x_margin` and `y_margin` were asymmetric (`c(0.10, 1.00)` and `c(0.6, 1.1)` respectively), pushing composite legend content visibly off-centre. Both defaults are now symmetric (`c(1.00, 1.00)` and `c(1.1, 1.1)`), and new `align = c("center", "left", "right")` and `valign = c("center", "top", "bottom")` arguments offer a convenient way to bias the padding without hand-tuning `x_margin`/`y_margin` directly (#393).
+- `legend_canvas()` sized the canvas height from the grid's row count alone, so a `group_section` or `symbol_section` with more entries than the grid has rows extended below the fitted border and was clipped. The auto `ylim` now encloses whichever section runs deepest, so taller colour-tile or symbol blocks are always contained (#393).
+- `legend_strip()` silently rendered only the last panel (stretched to the full width) when the main plot was a `patchwork` combination of several `ggplot`s, because `ggplot2::ggplotGrob()` cannot see a patchwork's individual panels. It now detects `patchwork` mains and converts them with `patchwork::patchworkGrob()` instead, rendering every panel correctly (requires the `patchwork` package, now listed in `Suggests`).
+- `marker_legend()`'s title was always drawn `"plain"` regardless of `label_fontface`, so a bold-labelled legend still showed a plain title. The title now follows `label_fontface`, matching the entry labels (#393).
 
 # ggpop 1.7.1
 

R/key_legend.R

@@ -48,6 +48,10 @@
 #' @param label_inside When \code{TRUE}, centres the label inside the key
 #'   symbol instead of beside it.  Only takes effect for \code{swatch} rows
 #'   (default \code{FALSE}).
+#' @param label_fontface Font face for the title and entry labels (default
+#'   \code{"plain"}).  Common values: \code{"plain"}, \code{"bold"},
+#'   \code{"italic"}.  Does not affect the \code{"point"}-type \code{"*"}
+#'   glyph, which is always bold.
 #' @param title_color Colour of the section title.  Inherits
 #'   \code{label_color} when \code{NULL} (the default).
 #' @param swatch_height Height of swatch rectangles as a fraction of
@@ -97,6 +101,7 @@ key_legend <- function(
   label_size    = 2.8,
   label_color   = "black",
   label_inside  = FALSE,
+  label_fontface = "plain",
   title_color   = NULL,
   swatch_height = 0.45,
   point_size    = 1.6
@@ -105,20 +110,21 @@ key_legend <- function(
 
   structure(
     list(
-      entries       = entries,
-      x             = x,
-      y_start       = y_start,
-      title         = title,
-      title_frac    = title_frac,
-      row_spacing   = row_spacing,
-      key_width     = key_width,
-      label_gap     = label_gap,
-      label_size    = label_size,
-      label_color   = label_color,
-      label_inside  = label_inside,
-      title_color   = title_color %||% label_color,
-      swatch_height = swatch_height,
-      point_size    = point_size
+      entries        = entries,
+      x              = x,
+      y_start        = y_start,
+      title          = title,
+      title_frac     = title_frac,
+      row_spacing    = row_spacing,
+      key_width      = key_width,
+      label_gap      = label_gap,
+      label_size     = label_size,
+      label_color    = label_color,
+      label_inside   = label_inside,
+      label_fontface = label_fontface,
+      title_color    = title_color %||% label_color,
+      swatch_height  = swatch_height,
+      point_size     = point_size
     ),
     class = "ggpop_key_legend"
   )
@@ -188,14 +194,15 @@ build_key_legend_layers <- function(obj) {
   layers    <- list()
 
   tc <- obj$title_color %||% lc
+  ff <- obj$label_fontface %||% "plain"
   if (!is.null(obj$title)) {
     layers <- c(layers, list(
       ggplot2::annotate(
         "text",
         x = x_sym_mid, y = rs * tf,
         label = obj$title,
         hjust = 0.5, vjust = 0.5,
-        size = ls, colour = tc
+        size = ls, colour = tc, fontface = ff
       )
     ))
   }
@@ -255,14 +262,14 @@ build_key_legend_layers <- function(obj) {
         "text",
         x = x + kw / 2, y = y,
         label = lbl, hjust = 0.5, vjust = 0.5,
-        size = row_ls, colour = lc, lineheight = row_lh
+        size = row_ls, colour = lc, lineheight = row_lh, fontface = ff
       )
     } else {
       ggplot2::annotate(
         "text",
         x = x_label, y = y,
         label = lbl, hjust = 0, vjust = 0.5,
-        size = row_ls, colour = lc, lineheight = row_lh
+        size = row_ls, colour = lc, lineheight = row_lh, fontface = ff
       )
     }