feat(annotation): add Ann.Styles.WithText wrapper

Wraps another annotation style (passed positionally) and layers
`pathtext` on top so a label follows the connection path. Adds a
reference test and an attribute_examples entry. Includes a
convert_attribute override for pathtext's `align` so PlotSpec doesn't
coerce the symbolic `(halign, valign)` tuple into the numeric
text-style align.

Author: jkrumbiegel

CHANGELOG.md

@@ -2,7 +2,7 @@
 
 ## Unreleased
 
-- Added `pathtext` recipe for placing text along a path [#5596](https://github.com/MakieOrg/Makie.jl/pull/5596).
+- Added `pathtext` recipe for placing text along a path, plus `Ann.Styles.WithText` to layer path text onto any existing `annotation` style [#5596](https://github.com/MakieOrg/Makie.jl/pull/5596).
 - Added possibility to gather legend entries from multiple axes [#5551](https://github.com/MakieOrg/Makie.jl/pull/5551)
 - Added complete inverse transformation support to `register_projected_positions!` with `apply_inverse_transform`, `apply_inverse_transform_func`, `apply_inverse_float32convert`, and `apply_inverse_model` kwargs. These enable correct projection from non-data spaces back to data space. Includes early-exit optimization to skip redundant transform/inverse pairs when `input_space === output_space`. [#5485](https://github.com/MakieOrg/Makie.jl/pull/5485)
 - Fixed `bracket` not supporting `LaTeXString` text, which would render with dollar signs instead of mathematical notation [#5536](https://github.com/MakieOrg/Makie.jl/pull/5536)

Makie/src/basic_recipes/annotation.jl

@@ -39,6 +39,7 @@ baremodule Ann # bare for cleanest tab-completion behavior
         using Base
 
         using ..Arrows: Arrows
+        using ...Makie: Makie
 
         struct Line end
 
@@ -47,6 +48,32 @@ baremodule Ann # bare for cleanest tab-completion behavior
             tail = nothing
         end
 
+        """
+            Ann.Styles.WithText(style; text, ...)
+
+        Wraps another annotation `style` and additionally draws `text` along the
+        connection path using `pathtext`. The inner `style` is rendered first,
+        then the text is layered on top so it follows the same curve.
+        """
+        struct WithText
+            style::Any
+            text::Any
+            fontsize::Float64
+            align::Any
+            offset::Float64
+            color::Any
+        end
+        function WithText(
+                style;
+                text = "",
+                fontsize = 12.0,
+                align = (:center, :bottom),
+                offset = 4.0,
+                color = Makie.automatic,
+            )
+            return WithText(style, text, Float64(fontsize), align, Float64(offset), color)
+        end
+
     end
 end
 
@@ -1023,6 +1050,20 @@ function annotation_style_plotspecs(::Ann.Styles.Line, path::BezierPath, p1, p2;
     ]
 end
 
+function annotation_style_plotspecs(s::Ann.Styles.WithText, path::BezierPath, p1, p2; color, linewidth)
+    specs = annotation_style_plotspecs(s.style, path, p1, p2; color, linewidth)
+    textcolor = s.color === automatic ? color : s.color
+    push!(
+        specs,
+        PlotSpec(
+            :PathText, path;
+            text = s.text, fontsize = s.fontsize, align = s.align,
+            offset = s.offset, color = textcolor, space = :pixel,
+        ),
+    )
+    return specs
+end
+
 _auto(x::Automatic, default) = default
 _auto(x, default) = x
 
@@ -1087,6 +1128,22 @@ function attribute_examples(::Type{Annotation})
                 fig
                 """
             ),
+            Example(
+                code = raw"""
+                fig = Figure()
+                ax = Axis(fig[1, 1])
+                scatter!(ax, [1, 5], [2, 5], markersize = 10, color = :black)
+                annotation!(ax, [Point2f(1, 2)], [Point2f(5, 5)];
+                    text = [""],
+                    path = Ann.Paths.Arc(height = 0.4),
+                    style = Ann.Styles.WithText(Ann.Styles.LineArrow();
+                        text = rich("H", subscript("2"), "O → ",
+                            rich("products"; color = :crimson)),
+                        fontsize = 14),
+                    color = :steelblue, labelspace = :data, shrink = (5.0, 5.0))
+                fig
+                """
+            ),
         ],
         :path => [
             Example(

Makie/src/basic_recipes/pathtext.jl

@@ -35,6 +35,11 @@ Newlines in `text` are currently not supported.
     mixin_colormap_attributes()...
 end
 
+# Preserve `align` as-is. The default numeric conversion used for `text`/`scatter`
+# is not appropriate for `pathtext`, whose `halign` accepts a `Real` fraction
+# (0–1) along the path and whose `valign` accepts symbolic values.
+convert_attribute(align, ::key"align", ::key"PathText") = Ref{Any}(align)
+
 # -- convert_arguments ---------------------------------------------------------
 
 function convert_arguments(::Type{<:PathText}, path::AbstractVector{<:VecTypes{2}})

ReferenceTests/src/tests/text.jl

@@ -606,6 +606,29 @@ end
     f
 end
 
+@reference_test "pathtext as annotation style" begin
+    f = Figure(size = (500, 300))
+    ax = Axis(f[1, 1]; limits = ((0, 6), (1, 6)))
+    hidedecorations!(ax); hidespines!(ax)
+    scatter!(ax, [1, 5], [2, 5]; markersize = 10, color = :black)
+    annotation!(
+        ax, [Point2f(1, 2)], [Point2f(5, 5)];
+        text = [""],
+        path = Ann.Paths.Arc(height = 0.4),
+        style = Ann.Styles.WithText(
+            Ann.Styles.LineArrow();
+            text = rich(
+                "H", subscript("2"), "O → ",
+                rich("products"; color = :crimson),
+            ),
+            fontsize = 14,
+        ),
+        color = :steelblue, linewidth = 1.5,
+        labelspace = :data, shrink = (5.0, 5.0),
+    )
+    f
+end
+
 @reference_test "pathtext data vs pixel space" begin
     f = Figure(size = (500, 250))
 

docs/src/reference/plots/annotation.md

@@ -35,6 +35,25 @@ hidedecorations!.([ax1, ax2])
 f
 ```
 
+### Text along the connection path
+
+`Ann.Styles.WithText` wraps another annotation style and additionally draws text along the connection path using [`pathtext`](@ref).
+
+```@figure
+f = Figure()
+ax = Axis(f[1, 1])
+A, B = Point2f(1, 2), Point2f(5, 5)
+scatter!(ax, [A, B], markersize = 10, color = :black)
+text!(ax, [A, B], text = ["A", "B"], align = (:right, :top), offset = (-6, -4))
+annotation!(ax, [A], [B];
+    text = [""],
+    path = Ann.Paths.Arc(height = 0.4),
+    style = Ann.Styles.WithText(Ann.Styles.LineArrow();
+        text = "from A to B", fontsize = 14),
+    color = :steelblue, labelspace = :data, shrink = (5.0, 5.0))
+f
+```
+
 ## Attributes
 
 ```@attrdocs