Keep plot_spacer invisible when a theme is applied via & or *

Compose.__and__/__mul__ apply themes to items via item += rhs, which
dispatches to ggplot.__iadd__ → theme.__radd__. For a complete theme
that takes the "replace" branch, overwriting the spacer's theme_void()
foundation so the spacer paints a panel.

Override __iadd__ on plot_spacer to merge only plot_background into the
existing theme_void(), and have __add__ delegate via deepcopy → __iadd__
so the merge logic lives in one place.

plot_spacer.__add__ used to silently swallow any non-PlotAddable rhs,
so spacer + plot was a no-op. Match ggplot.__add__'s contract: ggplot
or Compose on the right composes into a Wrap, just like plot + plot.
A theme still contributes only its plot_background fill into the
spacer's theme_void() foundation.

closes #1055

Author: has2k1

plotnine/composition/_plot_spacer.py

@@ -1,9 +1,14 @@
 from __future__ import annotations
 
-from copy import deepcopy
+from typing import TYPE_CHECKING
 
 from plotnine import element_rect, ggplot, theme, theme_void
 
+if TYPE_CHECKING:
+    from typing_extensions import Self
+
+    from plotnine.ggplot import PlotAddable
+
 
 class plot_spacer(ggplot):
     """
@@ -17,6 +22,12 @@ class plot_spacer(ggplot):
 
         The color can also be modified by adding a [](`~plotnine.theme`)
         and setting the [](`~plotnine.themes.themeable.plot_background`).
+    alpha :
+        Opacity of the background fill, between 0 (transparent) and 1
+        (opaque). The default leaves the area transparent.
+
+        The opacity can also be modified by adding a [](`~plotnine.theme`)
+        and setting the [](`~plotnine.themes.themeable.plot_background`).
 
     See Also
     --------
@@ -33,21 +44,26 @@ def __init__(
             | tuple[float, float, float, float]
             | None
         ) = None,
+        alpha: float | None = None,
     ):
         super().__init__()
-        self.theme = theme_void()
-        if fill:
-            self.theme += theme(plot_background=element_rect(fill=fill))
+        self.theme = theme_void() + theme(
+            plot_background=element_rect(fill=fill, alpha=alpha)
+        )
 
-    def __add__(self, rhs) -> plot_spacer:  # pyright: ignore[reportIncompatibleMethodOverride]
+    def __iadd__(self, rhs: PlotAddable | list[PlotAddable] | None) -> Self:
         """
         Add to spacer
 
-        All added objects are no ops except the `plot_background` in
-        in a theme.
+        Only the `plot_background` of a [](`~plotnine.theme`) on the
+        right-hand side is merged into the spacer's own theme; every
+        other addable is dropped so the spacer keeps its blank
+        appearance.
         """
-        self = deepcopy(self)
         if isinstance(rhs, theme):
             fill = rhs.getp(("plot_background", "facecolor"))
-            self.theme += theme(plot_background=element_rect(fill=fill))
+            alpha = rhs.getp(("plot_background", "alpha"))
+            self.theme += theme(
+                plot_background=element_rect(fill=fill, alpha=alpha)
+            )
         return self

tests/baseline_images/test_plot_composition/spacer_first_plus_plot.png

@@ -12,7 +12,7 @@
 )
 from plotnine._utils.yippie import geom as g
 from plotnine._utils.yippie import legend, plot, rotate, tag
-from plotnine.composition import plot_annotation, plot_layout
+from plotnine.composition import plot_annotation, plot_layout, plot_spacer
 
 
 def test_basic_horizontal_align_resize():
@@ -435,3 +435,19 @@ def _make_footer(color):
     )
     p = ((p1 | p2) / p3) + ann
     assert p == "footers"
+
+
+def test_spacer_under_and_theme():
+    # theme_gray is applied to all plots,
+    # for the spacer is only applied to the plot background.
+    p1 = plot.red
+    p2 = plot.green
+    p = (p1 | p2) / (p1 | plot_spacer() | p2) & theme_gray()
+    assert p == "spacer_under_and_theme"
+
+
+def test_spacer_first_plus_plot():
+    # spacer + plot composes into a Wrap, matching ggplot + ggplot.
+    # Putting the spacer on the LHS exercises plot_spacer.__add__.
+    p = plot_spacer() + plot.red
+    assert p == "spacer_first_plus_plot"