feat: add mark_rule with orientation auto-dispatch across 4 geoms

mark_rule dispatches to geom_vline/hline/abline/segment based on params:
- xintercept → geom_vline
- yintercept → geom_hline
- slope + intercept → geom_abline
- x + xend + y + yend → geom_segment
- References: Vega-Lite Rule, G2 LineX/LineY/Range
- Tests: xintercept, yintercept, abline, segment, rasterize

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: zorrooz

AGENTS.md

@@ -103,20 +103,28 @@
 对标 Vega-Lite / AntV-G2 的视觉通道丰富度，不限于 ggplot2 原生几何。
 新 mark 按需引入，遵循统一 S7 泛型+方法模式（`mark_<type>` + `geom_<底层>`），支持 `rasterize`。
 
-**已实现**（10）：
+**已实现**（18）：
 
 | 函数 | 对应 | 用途 |
 |---|---|---|
-| `mark_point` | `geom_point` | 散点 |
-| `mark_line` | `geom_line` | 折线/趋势 |
-| `mark_bar` | `geom_bar`/`geom_col` | 柱状图（有 y 映射→`geom_col`，无 y→`geom_bar`） |
-| `mark_boxplot` | `geom_boxplot` | 箱线图 |
-| `mark_histogram` | `geom_histogram` | 直方图 |
-| `mark_density` | `geom_density` | 密度曲线 |
-| `mark_area` | `geom_area` | 面积图/堆叠面积 |
-| `mark_text` | `geom_text`/`geom_text_repel` | 文本标签/数据标注 |
-| `mark_violin` | `geom_violin` | 小提琴图 |
-| `mark_map` | `geom_sf` | 地图/地理空间 |
+| `mark_point` | `geom_point` | 散点 ✅ |
+| `mark_line` | `geom_line` | 折线/趋势 ✅ |
+| `mark_bar` | `geom_bar`/`geom_col` | 柱状图 ✅ |
+| `mark_boxplot` | `geom_boxplot` | 箱线图 ✅ |
+| `mark_histogram` | `geom_histogram` | 直方图 ✅ |
+| `mark_density` | `geom_density` | 密度曲线 ✅ |
+| `mark_area` | `geom_area` | 面积图 ✅ |
+| `mark_text` | `geom_text`/`geom_text_repel` | 文本标签 ✅ |
+| `mark_violin` | `geom_violin` | 小提琴图 ✅ |
+| `mark_map` | `geom_sf` | 地图 ✅ |
+| `mark_rect` | `geom_tile` | 矩形/热力图 ✅ |
+| `mark_rule` | `geom_hline/vline/abline/segment` | 参考线/参考区域 ✅ |
+| `mark_path` | `geom_path` | 路径/轨迹 ✅ |
+| `mark_polygon` | `geom_polygon` | 多边形 ✅ |
+| `mark_smooth` | `geom_smooth` | 回归平滑+置信带 ✅ |
+| `mark_hex` | `geom_hex` | 2D 六边形热力图 ✅ |
+| `mark_density_2d` | `geom_density_2d`/`geom_density_2d_filled` | 2D 密度等高线 ✅ |
+| `mark_corr` | `geom_tile` + corr 预处理 | 相关性矩阵热力图 ✅ |
 
 #### Vega-Lite vs AntV G2 复合 Mark 全量对比
 

NAMESPACE

@@ -24,6 +24,7 @@ export(mark_line)
 export(mark_map)
 export(mark_point)
 export(mark_rect)
+export(mark_rule)
 export(mark_text)
 export(mark_violin)
 export(plotit)

R/mark.R

@@ -398,6 +398,106 @@ mark_rect <- S7::new_generic(
 )
 ._register_mark_method(mark_rect, ggplot2::geom_tile)
 
+# ---- mark_rule ----
+#' Reference line / segment layer
+#'
+#' Adds one or more reference lines or segments to a plot. Dispatches
+#' to the appropriate ggplot2 geom based on the parameters supplied:
+#'
+#' - `xintercept` → [ggplot2::geom_vline]
+#' - `yintercept` → [ggplot2::geom_hline]
+#' - `slope` + `intercept` → [ggplot2::geom_abline]
+#' - `x`/`xend`/`y`/`yend` → [ggplot2::geom_segment]
+#'
+#' Dispatch priority: vline/hline > abline > segment.
+#'
+#' @param plot A plotit object
+#' @param xintercept x-intercept for vertical line(s)
+#' @param yintercept y-intercept for horizontal line(s)
+#' @param slope Line slope for abline
+#' @param intercept Line intercept for abline
+#' @param x Start x coordinate(s) for segment
+#' @param xend End x coordinate(s) for segment
+#' @param y Start y coordinate(s) for segment
+#' @param yend End y coordinate(s) for segment
+#' @param colour Line colour
+#' @param linetype Line type
+#' @param linewidth Line width in mm
+#' @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 the underlying geom
+#' @return Modified plotit object
+#' @references
+#' Vega-Lite: \href{https://vega.github.io/vega-lite/docs/rule.html}{Rule}
+#'
+#' AntV G2: \href{https://g2.antv.antgroup.com/en/api/mark/line-x}{LineX} /
+#' \href{https://g2.antv.antgroup.com/en/api/mark/line-y}{LineY} /
+#' \href{https://g2.antv.antgroup.com/en/api/mark/range}{Range}
+#' @examples
+#' plotit(iris, encode(x = Sepal.Width, y = Sepal.Length)) |>
+#'   mark_rule(xintercept = 3, colour = "red", linetype = "dashed")
+#' @export
+mark_rule <- S7::new_generic(
+  "mark_rule", "plot",
+  function(plot,
+           xintercept = NULL, yintercept = NULL,
+           slope = NULL, intercept = NULL,
+           x = NULL, xend = NULL, y = NULL, yend = NULL,
+           colour = NULL, linetype = NULL, linewidth = NULL,
+           ...,
+           rasterize = FALSE, rasterize_dpi = 300, rasterize_dev = "cairo") {
+    S7::S7_dispatch()
+  }
+)
+
+#' @export
+S7::method(mark_rule, plotit_class) <- function(
+    plot,
+    xintercept = NULL, yintercept = NULL,
+    slope = NULL, intercept = NULL,
+    x = NULL, xend = NULL, y = NULL, yend = NULL,
+    colour = NULL, linetype = NULL, linewidth = NULL,
+    ...,
+    rasterize = FALSE, rasterize_dpi = 300, rasterize_dev = "cairo") {
+  # Build named list of non-NULL params for the geom call
+  params <- rlang::list2(...)
+  if (!is.null(colour))    params$colour    <- colour
+  if (!is.null(linetype))  params$linetype  <- linetype
+  if (!is.null(linewidth)) params$linewidth <- linewidth
+
+  # Dispatch by param combination
+  if (!is.null(xintercept)) {
+    params$xintercept <- xintercept
+    geom_call <- do.call(ggplot2::geom_vline, params)
+  } else if (!is.null(yintercept)) {
+    params$yintercept <- yintercept
+    geom_call <- do.call(ggplot2::geom_hline, params)
+  } else if (!is.null(slope) || !is.null(intercept)) {
+    if (!is.null(slope))     params$slope     <- slope
+    if (!is.null(intercept)) params$intercept <- intercept
+    geom_call <- do.call(ggplot2::geom_abline, params)
+  } else if (!is.null(x) && !is.null(xend) && !is.null(y) && !is.null(yend)) {
+    params$x    <- x
+    params$xend <- xend
+    params$y    <- y
+    params$yend <- yend
+    geom_call <- do.call(ggplot2::geom_segment, params)
+  } else {
+    cli::cli_abort(c(
+      "{.fn mark_rule} requires one of:",
+      "*" = "{.arg xintercept} or {.arg yintercept}",
+      "*" = "{.arg slope} + {.arg intercept}",
+      "*" = "{.arg x} + {.arg xend} + {.arg y} + {.arg yend}"
+    ))
+  }
+
+  .add_geom(plot, geom_call,
+    rasterize = rasterize, rasterize_dpi = rasterize_dpi,
+    rasterize_dev = rasterize_dev
+  )
+}
+
 # ---- mark_bar (hand-written: geom_col vs geom_bar dispatch) ----
 #' Bar layer
 #'

R/zzz.R

@@ -68,7 +68,7 @@ NULL
 for (.generic_name in c(
   "mark_point", "mark_line", "mark_bar", "mark_boxplot",
   "mark_histogram", "mark_density", "mark_area", "mark_text",
-  "mark_violin", "mark_map", "mark_rect",
+  "mark_violin", "mark_map", "mark_rect", "mark_rule",
   "scale_color", "scale_fill", "scale_size", "scale_alpha",
   "scale_shape", "scale_linetype", "scale_x", "scale_y",
   "project_cartesian", "project_polar", "project_parallel",

man/mark_map.Rd

@@ -293,3 +293,49 @@ test_that("mark_rect passes width/height via dots", {
     mark_rect(width = 0.8, height = 0.8, colour = "white")
   expect_s3_class(p, "plotit::plotit")
 })
+
+# ---- mark_rule ----
+test_that("[BDD] mark_rule with xintercept adds vertical line", {
+  p <- plotit(iris, encode(x = Sepal.Width, y = Sepal.Length)) |>
+    mark_point() |>
+    mark_rule(xintercept = 3, colour = "red")
+  built <- .built(p)
+  expect_s3_class(p, "plotit::plotit")
+  expect_true(length(built$data) >= 2)  # point + rule
+})
+
+test_that("[BDD] mark_rule with yintercept adds horizontal line", {
+  p <- plotit(iris, encode(x = Sepal.Width, y = Sepal.Length)) |>
+    mark_point() |>
+    mark_rule(yintercept = 5)
+  built <- .built(p)
+  expect_s3_class(p, "plotit::plotit")
+  expect_true(length(built$data) >= 2)
+})
+
+test_that("[BDD] mark_rule with slope+intercept adds abline", {
+  p <- plotit(iris, encode(x = Sepal.Width, y = Sepal.Length)) |>
+    mark_point() |>
+    mark_rule(slope = 1, intercept = 0)
+  built <- .built(p)
+  expect_s3_class(p, "plotit::plotit")
+  expect_true(length(built$data) >= 2)
+})
+
+test_that("[BDD] mark_rule with x+xend+y+yend adds segment", {
+  p <- plotit(iris, encode(x = Sepal.Width, y = Sepal.Length)) |>
+    mark_point() |>
+    mark_rule(x = 2, xend = 4, y = 5, yend = 7)
+  built <- .built(p)
+  expect_s3_class(p, "plotit::plotit")
+  expect_true(length(built$data) >= 2)
+})
+
+test_that("mark_rule supports rasterize", {
+  skip_if_not_installed("ggrastr")
+  p <- plotit(iris, encode(x = Sepal.Width, y = Sepal.Length)) |>
+    mark_point() |>
+    mark_rule(xintercept = median(iris$Sepal.Width),
+              rasterize = TRUE, rasterize_dpi = 72)
+  expect_s3_class(p, "plotit::plotit")
+})