Add support for Makie's new Annotation recipe (#663)

```julia
smallest_largest = sort(penguins, :body_mass_g)[[1, end], :]
smallest_largest.x_offset = [-80, 20]
smallest_largest.y_offset = [-20, -80]

base_mapping = mapping(:bill_length_mm, :bill_depth_mm, color = :species)

penguin_layer = data(penguins) * base_mapping * visual(Scatter, alpha = 0.4)

text_layer = data(smallest_largest) *
    mapping(
        # from
        :x_offset,
        :y_offset,
        # to
        :bill_length_mm,
        :bill_depth_mm,
        color = :species,
        text = :body_mass_g => x -> verbatim("$(x)g"),
    ) *
    visual(Annotation, style = Ann.Styles.LineArrow())

draw(penguin_layer + text_layer)
```

<img width="585" alt="image"
src="https://github.com/user-attachments/assets/5118f309-2893-4b07-865a-db057547b861"
/>

Author: jkrumbiegel

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+## v0.10.8 - 2025-06-06
+
+- Added support for the Makie's new `Annotation` recipe [#663](https://github.com/MakieOrg/AlgebraOfGraphics.jl/pull/663).
+
 ## v0.10.7 - 2025-05-27
 
 - Fixed facet labels in paginated plots with a `Layout` scale in which categories were also relabeled using the `categories = pairs` mechanism [#661](https://github.com/MakieOrg/AlgebraOfGraphics.jl/pull/661).

Project.toml

@@ -1,7 +1,7 @@
 name = "AlgebraOfGraphics"
 uuid = "cbdf2221-f076-402e-a563-3d30da359d67"
 authors = ["Pietro Vertechi", "Julius Krumbiegel"]
-version = "0.10.7"
+version = "0.10.8"
 
 [deps]
 Accessors = "7d9f7c33-5ae7-4f3b-8dc6-eff91059b697"
@@ -50,7 +50,7 @@ GridLayoutBase = "0.6, 0.7, 0.8, 0.9, 0.10, 0.11"
 Isoband = "0.1"
 KernelDensity = "0.6"
 Loess = "0.5.1, 0.6.1"
-Makie = "0.22.5"
+Makie = "0.22.10"
 NaturalSort = "1"
 PlotUtils = "1"
 PolygonOps = "0.1.1"

docs/src/tutorials/intro-iv.md

@@ -160,23 +160,31 @@ draw(spec_nonnumeric)
 
 ### `verbatim`
 
-As you already know, string columns are treated as categorical by AlgebraOfGraphics. But sometimes we may want to just pass strings as they are to Makie's plotting functions. The main situation where this happens is when we are adding `Text` plots because the `Text` plot type expects a vector of string-like objects as its `text` attribute.
+As you already know, string columns are treated as categorical by AlgebraOfGraphics. But sometimes we may want to just pass strings as they are to Makie's plotting functions. The main situation where this happens is when we are adding `Annotation` or `Text` plots because they expect a vector of string-like objects as their `text` attribute.
 
 For example, we can label a couple of our penguins with their body weight, by making a subset dataframe, and applying both a string formatting function and the `verbatim` function to the `body_mass_g` column:
 
 ```@example tut
 smallest_largest = sort(penguins, :body_mass_g)[[1, end], :]
+smallest_largest.x_offset = [-80, 20]
+smallest_largest.y_offset = [-20, -80]
 
 base_mapping = mapping(:bill_length_mm, :bill_depth_mm, color = :species)
 
-penguin_layer = data(penguins) * base_mapping * visual(Scatter, alpha = 0.2)
+penguin_layer = data(penguins) * base_mapping * visual(Scatter, alpha = 0.4)
 
 text_layer = data(smallest_largest) *
-    base_mapping *
     mapping(
+        # from
+        :x_offset,
+        :y_offset,
+        # to
+        :bill_length_mm,
+        :bill_depth_mm,
+        color = :species,
         text = :body_mass_g => x -> verbatim("$(x)g"),
     ) *
-    visual(Makie.Text, fontsize = 20)
+    visual(Annotation, style = Ann.Styles.LineArrow())
 
 draw(penguin_layer + text_layer)
 ```

src/aesthetics.jl

@@ -478,4 +478,39 @@ function aesthetic_mapping(::Type{Stairs}, N::Int)
         :color => AesColor,
         :linestyle => AesLineStyle,
     ])
-end
+end
+
+aesthetic_mapping(::Type{Annotation}, ::Normal, ::Normal) = aesthetic_mapping(Annotation, 2)
+aesthetic_mapping(::Type{Annotation}, ::Normal, ::Normal, ::Normal, ::Normal) = aesthetic_mapping(Annotation, 4)
+
+
+function aesthetic_mapping(::Type{Annotation}, N::Int)
+    @assert N in (2, 4)
+    positionals = if N == 4
+        [
+            1 => :labelspace => dictionary([
+                :data => AesX,
+                :relative_pixel => AesAnnotationOffsetX,
+            ]),
+            2 => :labelspace => dictionary([
+                :data => AesY,
+                :relative_pixel => AesAnnotationOffsetY,
+            ]),
+            3 => AesX,
+            4 => AesY,
+        ]
+    else
+        [
+            1 => AesX,
+            2 => AesY,
+        ]
+    end
+
+    dictionary([
+        positionals...,
+        :color => AesColor,
+        :textcolor => AesColor,
+    ])
+end
+
+mandatory_attributes(::Type{Annotation}) = dictionary([:labelspace => :relative_pixel])

src/algebra/layers.jl

@@ -290,7 +290,7 @@ function hardcoded_or_mapped_aes(processedlayer, key::Union{Int,Symbol}, aes_map
     hardcoded = hardcoded_mapping(key)
     hardcoded !== nothing && return hardcoded
     if !haskey(aes_mapping, key)
-        throw(ArgumentError("ProcessedLayer with plot type $(processedlayer.plottype) did not have $(repr(key)) in its AestheticMapping. The mapping was $aes_mapping"))
+        throw(ArgumentError("ProcessedLayer with plot type $(processedlayer.plottype) did not have $(repr(key)) in its AestheticMapping. That means AlgebraOfGraphics does not know how to handle this attribute in its scale system. Note that you can use any array-valued attribute in a `mapping` if you bypass the scale system using the `=> verbatim` helper. The available mapping dictionary was:\n $(sprint(print, aes_mapping))"))
     end
     return aes_mapping[key]
 end
@@ -602,7 +602,7 @@ function values_to_markersizes(data, sizerange, extrema)
     end
 end
 
-function full_rescale(data, aes::Type{<:Union{AesX,AesY,AesZ,AesDeltaX,AesDeltaY,AesDeltaZ}}, scale::ContinuousScale)
+function full_rescale(data, aes::Type{<:Union{AesX,AesY,AesZ,AesDeltaX,AesDeltaY,AesDeltaZ,AesAnnotationOffsetX,AesAnnotationOffsetY}}, scale::ContinuousScale)
     return data
 end
 

src/guides/legend.jl

@@ -441,7 +441,7 @@ function legend_elements(T::Type{LinesFill}, attributes, scale_args::MixedArgume
     ]
 end
 
-function legend_elements(T::Type{Makie.Text}, attributes, scale_args::MixedArguments)
+function legend_elements(T::Type{<:Union{Makie.Text,Annotation}}, attributes, scale_args::MixedArguments)
     [PolyElement(
         color = _get(T, scale_args, attributes, :color),
     )]

src/scales.jl

@@ -28,6 +28,8 @@ struct AesContourColor <: Aesthetic end # this is just so the third contour argu
 struct AesPlaceholder <: Aesthetic end # choropleth for example takes as first arg only geometries which avoid scales, but for now we still have to give an aes to 1, so this can serve for that purpose
 struct AesABIntercept <: Aesthetic end
 struct AesABSlope <: Aesthetic end
+struct AesAnnotationOffsetX <: Aesthetic end
+struct AesAnnotationOffsetY <: Aesthetic end
 
 # helper to dissociate scales belonging to the same Aesthetic type
 struct ScaleID

test/reference_tests.jl

@@ -1443,3 +1443,46 @@ reftest("rainclouds") do
     legend!(f[2, 2], fg2)
     f
 end
+
+reftest("annotation", true) do
+    f = Figure(size = (600, 450))
+    text = string.(range('A', length = 5)) => verbatim
+    spec1 = mapping(1:5, 1:5) *
+        (
+            visual(Annotation) * mapping(; text) +
+            visual(Scatter)
+        )
+    draw!(f[1, 1], spec1)
+    spec2 = mapping(1:5, 1:5, color = 1:5) *
+        (
+            visual(Annotation) * mapping(; text) +
+            visual(Scatter)
+        )
+    draw!(f[1, 2], spec2)
+    spec3 = mapping(1:5, 1:5, color = 1:5 => nonnumeric) *
+        (
+            visual(Annotation) * mapping(; text) +
+            visual(Scatter)
+        )
+    fg = draw!(f[2, 1][1, 1], spec3)
+    legend!(f[2, 1][1, 2], fg)
+    spec4 = mapping(
+        [30, 15, 0],
+        [100, 50, 30],
+        1:3,
+        1:3;
+        text = ["A", "B", "C"] => verbatim,
+    ) * visual(Annotation) +
+        mapping(1:5, 1:5) * visual(Scatter) +
+        mapping(50, -50, 3, 3, text = "point" => verbatim) *
+            visual(Annotation, style = Ann.Styles.LineArrow(), path = Ann.Paths.Arc(height = -0.3)) +
+        mapping(
+            [4, 4.5],
+            [3, 4],
+            4:5,
+            4:5;
+            text = ["D", "E"] => verbatim,
+        ) * visual(Annotation; labelspace = :data)
+    draw!(f[2, 2], spec4)
+    f
+end