To explain a bit more about the xDetails() / yDetails() thing; they are needed for grobX() and grobY() to return sensible values. If we make a grob builder that returns a grob that does not implement these methods, you get a crappy plot:

library(grid)
devtools::load_all("~/packages/ggrepel")
#> ℹ Loading ggrepel
#> Loading required package: ggplot2

custom_text <- function(label, x, y, hjust, vjust, gp = gpar(), 
                        default.units = "npc", ..., colours = rainbow(10)) {
  txt <- textGrob(
    label, x, y, hjust = hjust, vjust = vjust, 
    gp = gp, default.units = default.units
  )
  grob <- fillStrokeGrob(
    txt, gp = gpar(
      col = "black", lwd = 1,
      fill = linearGradient(colours)
    )
  )
  grob
}

ggplot(mtcars, aes(wt, mpg, label = rownames(mtcars))) +
  geom_point(colour = 'red') +
  expand_limits(x = c(1, 7), y = c(12, 24)) +
  geom_text_repel(grob = custom_text, max.overlaps = Inf, fontface = "bold")

^{Created on 2024-01-13 with reprex v2.0.2}

But if you implement these methods correctly, that should again give sensible output:

xDetails.GridFillStroke <- function(x, theta) {
  xDetails(x$path, theta)
}
yDetails.GridFillStroke <- function(x, theta) {
  yDetails(x$path, theta)
}

last_plot()

^{Created on 2024-01-13 with reprex v2.0.2}

Thank you so much for writing this up! I like it a lot, and I'd be excited to eventually review/merge this someday when you let me know that gridtext is ready. (Sorry, but I have not yet read your code, so I'll study it later when I have more time.)

Could I ask about the magic behind xDetails.GridFillStroke? I'm not familiar with the magical naming conventions and I get confused because I don't know the full list names that will be searched for. I guess the function needs to be named in exactly this way because the object system is searching for a function with this specific name? Is there a nice reference (website or book) to get started learning about this naming convention? So many years later, I still I find grid to be mysterious.

An aside: Since I'm not an expert with grid, your comment regarding stringWidth() reminds me that there may be a possibility that the way I call convertWidth(x, "native", valueOnly = TRUE) in ggrepel is totally wrong. Maybe it's OK for now (since it seems to work well enough for many people), but I don't want my silly mistakes to prohibit developers like yourself from making cool new features like this PR.

Thanks for the response!

Could I ask about the magic behind xDetails.GridFillStroke?

It is just the S3 OOP convention that {function_name}.{class_name} is a method for the class_name class, so that xDetails.GridFillStroke is a xDetails method for the GridFillStroke class. It's used in a bunch of packages, not just grid. It is used right here in ggrepel even:

a possibility that the way I call convertWidth(x, "native", valueOnly = TRUE) in ggrepel is totally wrong.

I don't think it is wrong, at the time this is used the device dimensions are already known. There might be a small performance benefit to consistenly use absolute values that don't differ between the x and y-direction, but it shouldn't be huge.

Thank you for the link to the S3 OOP book! This is exactly what I need.

For ggrepel I just copied what I saw in the source code for ggplot2, but I didn't fully understand how it works.

I was wondering where the name GridFillStroke comes from and I found my answer in this file:

https://svn.r-project.org/R/trunk/src/library/grid/R/path.R

It is defined in the grid package (which is included in base R). Specifically, we can see the definition in the file path.R by setting cl="GridFillStroke" in these functions:

fillStrokeGrob.grob <- function(x, rule=c("winding", "evenodd"),
                                name=NULL, gp=gpar(), vp=NULL, ...) {
    fillStroke <- grob(path=x, rule=match.arg(rule),
                       name=name, gp=gp, vp=vp, cl="GridFillStroke")
    fillStroke
}

fillStrokeGrob.GridPath <- function(x, name=NULL, vp=NULL, ...) {
    fillStroke <- grob(path=x$grob, rule=x$rule,
                       name=name, gp=x$gp, vp=vp, cl="GridFillStroke")
    fillStroke
}

Now that I understand where GridFillStroke is coming from, I have a better understanding of how your code works. This is great!