Merge branch 'dev'

Author: zorrooz

AGENTS.md

@@ -15,12 +15,16 @@ export(label_caption)
 export(label_legend)
 export(label_subtitle)
 export(label_title)
+export(mark_area)
 export(mark_bar)
 export(mark_boxplot)
 export(mark_density)
 export(mark_histogram)
 export(mark_line)
+export(mark_map)
 export(mark_point)
+export(mark_text)
+export(mark_violin)
 export(plotit)
 export(project_cartesian)
 export(project_map)

NAMESPACE

@@ -197,6 +197,169 @@ mark_density <- S7::new_generic(
 )
 ._register_mark_method(mark_density, ggplot2::geom_density)
 
+# ---- mark_area ----
+#' Area layer
+#'
+#' Adds a filled area layer. Use for stacked area charts, stream graphs,
+#' or error bands.
+#'
+#' @param plot A plotit object
+#' @param mapping Optional new aesthetics
+#' @param data Optional data for this layer
+#' @param position Position adjustment.
+#' @param rasterize If `TRUE`, rasterize via `ggrastr::rasterise()`.
+#' @param rasterize_dpi DPI for rasterization (default 300).
+#' @param rasterize_dev Graphics device for rasterization (default `"cairo"`).
+#' @param ... Other arguments passed to `geom_area`
+#' @return Modified plotit object
+#' @examples
+#' plotit(ggplot2::economics, encode(x = date, y = unemploy)) |>
+#'   mark_area(alpha = 0.5)
+#' @export
+mark_area <- S7::new_generic(
+  "mark_area", "plot",
+  function(plot, mapping = NULL, data = NULL, position = NULL, ...,
+           rasterize = FALSE, rasterize_dpi = 300, rasterize_dev = "cairo") {
+    S7::S7_dispatch()
+  }
+)
+._register_mark_method(mark_area, ggplot2::geom_area)
+
+# ---- mark_text ----
+#' Text layer
+#'
+#' Adds a text label layer. For automatic label placement with collision
+#' avoidance, install the optional \pkg{ggrepel} package and set
+#' `repel = TRUE`.
+#'
+#' @param plot A plotit object
+#' @param mapping Optional new aesthetics (e.g. `encode(label = ...)`)
+#' @param data Optional data for this layer
+#' @param position Position adjustment.
+#' @param repel If `TRUE`, use `ggrepel::geom_text_repel` instead of
+#'   `geom_text`. Requires the \pkg{ggrepel} package.
+#' @param rasterize If `TRUE`, rasterize via `ggrastr::rasterise()`.
+#' @param rasterize_dpi DPI for rasterization (default 300).
+#' @param rasterize_dev Graphics device for rasterization (default `"cairo"`).
+#' @param ... Other arguments passed to `geom_text` or `geom_text_repel`
+#' @return Modified plotit object
+#' @examples
+#' plotit(mtcars, encode(x = wt, y = mpg, label = rownames(mtcars))) |>
+#'   mark_text(size = 3)
+#' @export
+mark_text <- S7::new_generic(
+  "mark_text", "plot",
+  function(plot, mapping = NULL, data = NULL, position = NULL, ...,
+           repel = FALSE,
+           rasterize = FALSE, rasterize_dpi = 300, rasterize_dev = "cairo") {
+    S7::S7_dispatch()
+  }
+)
+
+#' @export
+S7::method(mark_text, plotit_class) <- function(
+    plot, mapping = NULL, data = NULL, position = NULL, ...,
+    repel = FALSE,
+    rasterize = FALSE, rasterize_dpi = 300, rasterize_dev = "cairo") {
+  if (repel) {
+    if (!requireNamespace("ggrepel", quietly = TRUE)) {
+      cli::cli_abort("{.arg repel = TRUE} requires the {.pkg ggrepel} package.")
+    }
+    geom_fun <- ggrepel::geom_text_repel
+  } else {
+    geom_fun <- ggplot2::geom_text
+  }
+  if (!is.null(mapping) && !is.null(mapping$colour)) {
+    plot <- ._clear_default_color(plot, mapping)
+  }
+  ._mark_impl(
+    plot, mapping, data, position, geom_fun,
+    rasterize, rasterize_dpi, rasterize_dev, ...
+  )
+}
+
+# ---- mark_violin ----
+#' Violin layer
+#'
+#' Adds a violin plot layer showing the kernel density estimate of the data
+#' at each position.
+#'
+#' @param plot A plotit object
+#' @param mapping Optional new aesthetics
+#' @param data Optional data for this layer
+#' @param position Position adjustment.
+#' @param rasterize If `TRUE`, rasterize via `ggrastr::rasterise()`.
+#' @param rasterize_dpi DPI for rasterization (default 300).
+#' @param rasterize_dev Graphics device for rasterization (default `"cairo"`).
+#' @param ... Other arguments passed to `geom_violin`
+#' @return Modified plotit object
+#' @examples
+#' plotit(iris, encode(x = Species, y = Sepal.Length)) |>
+#'   mark_violin(draw_quantiles = 0.5)
+#' @export
+mark_violin <- S7::new_generic(
+  "mark_violin", "plot",
+  function(plot, mapping = NULL, data = NULL, position = NULL, ...,
+           rasterize = FALSE, rasterize_dpi = 300, rasterize_dev = "cairo") {
+    S7::S7_dispatch()
+  }
+)
+._register_mark_method(mark_violin, ggplot2::geom_violin)
+
+# ---- mark_map ----
+#' Map layer
+#'
+#' Adds a geographic map layer for \pkg{sf} spatial data frames.
+#' Requires the \pkg{sf} package.
+#'
+#' @param plot A plotit object
+#' @param mapping Optional new aesthetics
+#' @param data Optional sf data frame for this layer
+#' @param position Position adjustment.
+#' @param rasterize If `TRUE`, rasterize via `ggrastr::rasterise()`.
+#' @param rasterize_dpi DPI for rasterization (default 300).
+#' @param rasterize_dev Graphics device for rasterization (default `"cairo"`).
+#' @param ... Other arguments passed to `geom_sf`
+#' @return Modified plotit object
+#' @examples
+#' \dontrun{
+#' nc <- sf::st_read(system.file("shape/nc.shp", package = "sf"), quiet = TRUE)
+#' plotit(nc, encode(geometry = geometry)) |> mark_map()
+#' }
+#' @export
+mark_map <- S7::new_generic(
+  "mark_map", "plot",
+  function(plot, mapping = NULL, data = NULL, position = NULL, ...,
+           rasterize = FALSE, rasterize_dpi = 300, rasterize_dev = "cairo") {
+    S7::S7_dispatch()
+  }
+)
+
+#' @export
+S7::method(mark_map, plotit_class) <- function(
+    plot, mapping = NULL, data = NULL, position = NULL, ...,
+    rasterize = FALSE, rasterize_dpi = 300, rasterize_dev = "cairo") {
+  if (!requireNamespace("sf", quietly = TRUE)) {
+    cli::cli_abort("{.fn mark_map} requires the {.pkg sf} package.")
+  }
+  layer_data <- data %||% plot@gg$data
+  if (!inherits(layer_data, "sf")) {
+    cli::cli_abort(c(
+      "{.fn mark_map} requires {.pkg sf} spatial data.",
+      "i" = "Use {.fn plotit} with an {.cls sf} data frame."
+    ))
+  }
+  # geom_sf does not support position adjustment; ignore dodge
+  if (!is.null(mapping) && !is.null(mapping$colour)) {
+    plot <- ._clear_default_color(plot, mapping)
+  }
+  geom <- ggplot2::geom_sf(mapping = mapping, data = data, ...)
+  .add_geom(plot, geom,
+    rasterize = rasterize, rasterize_dpi = rasterize_dpi,
+    rasterize_dev = rasterize_dev
+  )
+}
+
 # ---- mark_bar (hand-written: geom_col vs geom_bar dispatch) ----
 #' Bar layer
 #'

R/mark.R

@@ -35,18 +35,18 @@ S7::method(format, plotit_composite) <- function(x, ...) ""
 # pkgdown evaluates @examples via evaluate::evaluate(), which calls
 # pkgdown_print(value) as the output_handler `value` callback.  S7 objects
 # hit pkgdown_print.default() → print.S7_object() → str.S7_object(), which
-# dumps the full ggproto tree.  Intercept with a S3 method that renders the
-# plot to the device so evaluate records it, then returns invisible to suppress
-# the text dump.
+# dumps the full ggproto tree.  Intercept with S3 methods that render the
+# plot to the device so evaluate records it, then return invisible to
+# suppress the text dump.
 #' @exportS3Method pkgdown::pkgdown_print
 pkgdown_print.plotit <- function(x, visible = TRUE) {
-  x <- ._sync_labels(x)
-  print(x@gg)
-  invisible()
+  if (!visible) return(invisible())
+  ._print_render(x)
 }
 
 #' @exportS3Method pkgdown::pkgdown_print
 pkgdown_print.plotit_composite <- function(x, visible = TRUE) {
+  if (!visible) return(invisible())
   ._apply_annotations(x) |> print()
   invisible()
 }
@@ -105,12 +105,20 @@ print.plotit <- function(x, ...) {
 # ---- knit_print ----
 # S3 methods for knitr to capture plotit plots in vignettes / R Markdown.
 # Renders the underlying ggplot to knitr's active device.
-#' @exportS3Method knitr::knit_print
-knit_print.plotit <- function(x, ...) {
+
+# Shared knit_print / pkgdown_print path: sync labels, render, suppress text.
+#' @noRd
+#' @keywords internal
+._print_render <- function(x) {
   x <- ._sync_labels(x)
   ._render_plotit(x)
 }
 
+#' @exportS3Method knitr::knit_print
+knit_print.plotit <- function(x, ...) {
+  ._print_render(x)
+}
+
 #' @exportS3Method knitr::knit_print
 knit_print.plotit_composite <- function(x, ...) {
   x@gg <- ._apply_annotations(x)

R/output.R

@@ -144,16 +144,22 @@ NULL
   }
 }
 
+# Internal helper: strip NULL entries from a list so that `breaks = NULL`
+# and friends do not coerce downstream ggplot2 scales into guide = "none".
+#' Strip NULL entries from a list.
+#' @noRd
+#' @keywords internal
+._strip_nulls <- function(args) {
+  args[!vapply(args, is.null, logical(1L))]
+}
+
 # Pick the right scale function for colour/fill given trans + range
 .scale_colour_fun <- function(aes, trans, range, ..., force_reverse = FALSE) {
   discrete <- trans == "discrete"
   binned <- trans == "binned"
   reverse <- trans == "reverse" || force_reverse
 
-  # Collect args passed through `...` and strip NULLs so that `breaks = NULL`
-  # does not coerce ggplot2 scales into guide = "none".
-  extra_args <- list(...)
-  extra_args <- extra_args[!vapply(extra_args, is.null, logical(1L))]
+  extra_args <- ._strip_nulls(list(...))
 
   if (is.character(range) && length(range) >= 2) {
     do.call(._scale_custom, c(list(aes, range, discrete, binned, reverse), extra_args))
@@ -192,7 +198,7 @@ NULL
       alpha = ggplot2::scale_alpha_continuous
     )
   }
-  args <- list(...)
+  args <- ._strip_nulls(list(...))
   # Explicit defaults per AGENTS.md <U+00A7>3.3.4
   if (is.null(range) && !binned && !discrete) {
     range <- switch(aes,
@@ -210,7 +216,7 @@ NULL
 # Pick shape/linetype scale function
 .scale_discrete_fun <- function(aes, trans, range, ...) {
   reverse <- trans == "reverse"
-  args <- list(...)
+  args <- ._strip_nulls(list(...))
   if (reverse && !is.null(range)) range <- rev(range)
   if (!is.null(range)) {
     args$values <- range
@@ -289,8 +295,9 @@ NULL
   if (discrete && reverse && is.null(limits)) {
     args$limits <- rev
   }
-  args <- args[!vapply(args, is.null, logical(1))]
-  plot@gg <- plot@gg + do.call(scale_fun, c(args, list(...)))
+  args <- ._strip_nulls(args)
+  extra_args <- ._strip_nulls(list(...))
+  plot@gg <- plot@gg + do.call(scale_fun, c(args, extra_args))
   plot
 }
 

R/scale.R

@@ -67,7 +67,8 @@ NULL
 # Registered here (loaded last) so all S7 generics exist.
 for (.generic_name in c(
   "mark_point", "mark_line", "mark_bar", "mark_boxplot",
-  "mark_histogram", "mark_density",
+  "mark_histogram", "mark_density", "mark_area", "mark_text",
+  "mark_violin", "mark_map",
   "scale_color", "scale_fill", "scale_size", "scale_alpha",
   "scale_shape", "scale_linetype", "scale_x", "scale_y",
   "project_cartesian", "project_polar", "project_parallel",

R/zzz.R

@@ -79,17 +79,17 @@ compose_grid(p1, p2, tag_levels = "A") |>
 Every plotit chart follows a consistent pipeline:
 
 ```
-data |> plotit(encode(...)) |> mark_*() |> scale_*() |> label_*() |> project_*() |> split_*() |> style() |> export()
+data |> plotit(encode(...)) |> mark_*() |> scale_*() |> split_*() |> project_*() |> label_*() |> style() |> export()
 ```
 
 | Step | Verb | Role |
 |:---|:---|:---|
 | 1. Initialise | `plotit()` + `encode()` | Bind data and aesthetic mappings |
 | 2. Layer | `mark_*()` | Add geometric layers (points, lines, bars, …) |
 | 3. Scale | `scale_*()` | Control how data maps to visual properties |
-| 4. Label | `label_*()` | Set titles, axis labels, legend titles |
+| 4. Facet | `split_*()` | Split into small multiples |
 | 5. Coordinate | `project_*()` | Choose coordinate system (cartesian, polar, map) |
-| 6. Facet | `split_*()` | Split into small multiples |
+| 6. Label | `label_*()` | Set titles, axis labels, legend titles |
 | 7. Theme | `style()` | Apply a complete theme |
 | 8. Export | `export()` | Render to file |
 
@@ -107,10 +107,14 @@ compose_*(p1, p2, ...) |> label_*() |> style() |> export()
 |:---|:---|:---|
 | `mark_point()` | `geom_point()` | Scatter plots |
 | `mark_line()` | `geom_line()` | Lines and trends |
+| `mark_area()` | `geom_area()` | Filled area / stream graph |
 | `mark_bar()` | `geom_bar()` / `geom_col()` | Bar charts |
+| `mark_text()` | `geom_text()` / `ggrepel` | Text labels and annotations |
 | `mark_boxplot()` | `geom_boxplot()` | Box-and-whisker plots |
 | `mark_histogram()` | `geom_histogram()` | Histograms |
-| `mark_density()` | `geom_density()` | Kernel density estimates |
+| `mark_density()` | `geom_density()` | 1D kernel density |
+| `mark_violin()` | `geom_violin()` | Violin plots |
+| `mark_map()` | `geom_sf()` | Geographic maps |
 
 ### `scale_*` — Data-to-visual mapping
 
@@ -167,6 +171,13 @@ compose_*(p1, p2, ...) |> label_*() |> style() |> export()
 | `style_default()` | Restore plotit's built-in theme |
 | `export()` | Render to file (pdf, png, svg, …) |
 
+### Custom extensions
+
+| Function | Description |
+|:---|:---|
+| `make_mark()` | Register a custom mark from any ggplot2 geom |
+| `make_theme()` | Create a reusable theme preset function |
+
 ## Documentation
 
 Full documentation is available at [zorrooz.github.io/plotit](https://zorrooz.github.io/plotit/).