fix(imshow): surface facet_row limitations instead of failing silently

imshow with both facet_col and facet_row silently produced the wrong
figure in two cases.

On plotly < 6.7.0 (px.imshow has no facet_row), auto-assignment quietly
dropped the slot, so a 4D array animated its fourth dimension instead of
faceting subplot rows -- with no warning -- and a 5D array failed with an
unrelated "Unassigned dimension(s)" error. The fallback now warns, naming
the dimension and the plotly requirement, and the 5D case raises an error
that explains the real cause.

On any plotly version, px.imshow honours facet_col_wrap even when
facet_row is set: the grid is built but the facet_row subplot titles are
dropped. Every other px function ignores the wrap in that case, so drop
it here too and warn.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TKhPQzJgQr7khmzDPYAXA9

Author: claude

tests/test_accessor.py

@@ -498,12 +498,73 @@ def test_imshow_auto_skips_facet_row_on_old_plotly(
     ) -> None:
         """Test that auto-assignment skips facet_row on old plotly (4th dim animates)."""
         monkeypatch.setattr(plotting, "_imshow_supports_facet_row", lambda: False)
-        fig = self.da_4d.plotly.imshow()
+        with pytest.warns(UserWarning, match=r"'year' is animated instead of faceted"):
+            fig = self.da_4d.plotly.imshow()
         # year (4th dim) falls through to animation_frame instead of facet_row
         assert len(fig.frames) == 3
         # only the facet_col (scenario) produces subplots
         assert len(fig.data) == 2
 
+    def test_imshow_auto_facet_row_warning_mentions_plotly_version(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """Test that the fallback warning points at the plotly requirement."""
+        monkeypatch.setattr(plotting, "_imshow_supports_facet_row", lambda: False)
+        with pytest.warns(UserWarning, match=r"facet_row for imshow requires plotly>=6\.7\.0"):
+            self.da_4d.plotly.imshow()
+
+    def test_imshow_no_animation_slot_left_on_old_plotly(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """Test the 5D case on old plotly: no slot left to absorb facet_row."""
+        monkeypatch.setattr(plotting, "_imshow_supports_facet_row", lambda: False)
+        da = xr.DataArray(
+            np.random.rand(2, 2, 2, 2, 2),
+            dims=["lat", "lon", "scenario", "year", "time"],
+        )
+        with pytest.raises(ValueError, match=r"already fills the animation slot"):
+            da.plotly.imshow()
+
+    @requires_imshow_facet_row
+    def test_imshow_facet_col_wrap_ignored_with_facet_row(self) -> None:
+        """Test that facet_col_wrap is dropped so facet_row titles survive."""
+        with pytest.warns(UserWarning, match=r"facet_col_wrap is ignored"):
+            fig = self.da_4d.plotly.imshow(facet_col_wrap=2)
+        facet_titles = {a.text for a in fig.layout.annotations if "=" in (a.text or "")}
+        assert facet_titles == {
+            "scenario=low",
+            "scenario=high",
+            "year=2020",
+            "year=2021",
+            "year=2022",
+        }
+
+    def test_imshow_facet_col_wrap_kept_without_facet_row(self) -> None:
+        """Test that facet_col_wrap still applies when there is no facet_row."""
+        fig = self.da_3d.plotly.imshow(facet_col_wrap=2)
+        assert len(fig.data) == 3
+        # Wrapping at 2 columns stacks the 3 facets over two rows of subplots.
+        domains = {tuple(fig.layout[k].domain) for k in fig.layout if k.startswith("yaxis")}
+        assert len(domains) == 2
+
+    @requires_imshow_facet_row
+    def test_imshow_facet_grid_places_data_in_right_subplot(self) -> None:
+        """Test that each (facet_col, facet_row) pair lands in its own subplot."""
+        values = np.zeros((2, 3, 4, 5))
+        for col in range(2):
+            for row in range(3):
+                values[col, row] = col * 10 + row
+        da = xr.DataArray(
+            values,
+            dims=["scenario", "year", "lat", "lon"],
+            coords={"scenario": ["low", "high"], "year": [2020, 2021, 2022]},
+        )
+        fig = da.plotly.imshow(x="lon", y="lat", facet_col="scenario", facet_row="year")
+        assert len(fig.data) == 6
+        # Every subplot holds exactly one constant value, and all six differ.
+        constants = {float(np.unique(trace.z)[0]) for trace in fig.data}
+        assert constants == {0.0, 1.0, 2.0, 10.0, 11.0, 12.0}
+
 
 class TestColorsParameter:
     """Tests for the unified colors parameter."""

xarray_plotly/accessor.py

@@ -360,8 +360,10 @@ def imshow(
             y: Dimension for y-axis (rows). Default: first dimension.
             facet_col: Dimension for subplot columns. Default: third dimension.
             facet_row: Dimension for subplot rows. Default: fourth dimension.
-                Requires plotly>=6.7.0; on older versions this slot is skipped
-                during auto-assignment.
+                Requires plotly>=6.7.0; on older versions an auto-assigned
+                dimension animates instead (with a warning) and an explicitly
+                named one raises `ValueError`. `facet_col_wrap` is ignored
+                when `facet_row` is set.
             animation_frame: Dimension for animation. Default: fifth dimension.
             robust: If True, use 2nd/98th percentiles for color bounds (handles outliers).
             colors: Color scale name (e.g., "Viridis", "RdBu"). See module docs.

xarray_plotly/plotting.py

@@ -31,6 +31,8 @@
 )
 
 if TYPE_CHECKING:
+    from collections.abc import Hashable
+
     import plotly.graph_objects as go
     from xarray import DataArray
 
@@ -669,6 +671,45 @@ def _imshow_supports_facet_row() -> bool:
     return "facet_row" in inspect.signature(px.imshow).parameters
 
 
+def _handle_unsupported_facet_row(slots: dict[str, Hashable], *, explicit: bool) -> None:
+    """Resolve an imshow ``facet_row`` slot that the installed plotly cannot draw.
+
+    ``px.imshow`` gained ``facet_row`` in plotly 6.7.0.  On older versions an
+    explicit request is an error, while an auto-assigned dimension falls back
+    to animating (with a warning, so the missing subplot rows are not a
+    silent surprise).  If the animation slot is already taken there is nowhere
+    to fall back to, so that case raises as well.
+
+    Args:
+        slots: Slot assignment from :func:`assign_slots` (mutated in place).
+        explicit: Whether the user named the ``facet_row`` dimension.
+    """
+    import plotly
+
+    dim = slots["facet_row"]
+    msg = f"facet_row for imshow requires plotly>=6.7.0 (installed: {plotly.__version__})."
+
+    if explicit:
+        raise ValueError(msg)
+
+    if slots.get("animation_frame") is not None:
+        msg = (
+            f"{msg} Dimension {dim!r} cannot be faceted across subplot rows, and "
+            f"{slots['animation_frame']!r} already fills the animation slot. "
+            f"Upgrade plotly, or reduce a dimension with .sel(), .isel() or .mean()."
+        )
+        raise ValueError(msg)
+
+    warnings.warn(
+        f"{msg} Dimension {dim!r} is animated instead of faceted across "
+        f"subplot rows; upgrade plotly to facet it.",
+        UserWarning,
+        stacklevel=4,
+    )
+    slots["animation_frame"] = dim
+    slots["facet_row"] = None
+
+
 def imshow(
     darray: DataArray,
     *,
@@ -709,10 +750,11 @@ def imshow(
         Dimension for subplot columns. Default: third dimension.
     facet_row
         Dimension for subplot rows. Default: fourth dimension.
-        Requires plotly>=6.7.0; on older versions this slot is skipped
-        during auto-assignment (the fourth dimension animates instead).
-        Note: ``facet_col_wrap`` is ignored by plotly when ``facet_row``
-        is set.
+        Requires plotly>=6.7.0; on older versions an auto-assigned
+        dimension animates instead and a ``UserWarning`` is emitted, while
+        an explicitly named one raises ``ValueError``.
+        Note: ``facet_col_wrap`` is ignored (with a warning) when
+        ``facet_row`` is set, matching the other plot types.
     animation_frame
         Dimension for animation. Default: fifth dimension.
     robust
@@ -736,11 +778,6 @@ def imshow(
     """
     px_kwargs = resolve_colors(colors, px_kwargs)
 
-    # On plotly < 6.7.0, px.imshow has no facet_row: skip auto-assignment so
-    # dimensions fall through to animation_frame instead.
-    if facet_row is auto and not _imshow_supports_facet_row():
-        facet_row = None
-
     slots = assign_slots(
         list(darray.dims),
         "imshow",
@@ -751,14 +788,22 @@ def imshow(
         animation_frame=animation_frame,
     )
 
+    if slots.get("facet_row") is not None and not _imshow_supports_facet_row():
+        _handle_unsupported_facet_row(slots, explicit=facet_row is not auto)
+
     facet_row_kwargs: dict[str, Any] = {}
     if slots.get("facet_row") is not None:
-        if not _imshow_supports_facet_row():
-            import plotly
-
-            msg = f"facet_row for imshow requires plotly>=6.7.0 (installed: {plotly.__version__})."
-            raise ValueError(msg)
         facet_row_kwargs["facet_row"] = slots["facet_row"]
+        # px.imshow honours facet_col_wrap even when facet_row is set, which
+        # builds the grid but silently drops the facet_row titles.  Every other
+        # px function ignores the wrap in that case; match them.
+        if px_kwargs.pop("facet_col_wrap", None) is not None:
+            warnings.warn(
+                "facet_col_wrap is ignored when facet_row is set; "
+                "px.imshow would otherwise drop the facet_row subplot titles.",
+                UserWarning,
+                stacklevel=3,
+            )
 
     # Transpose to: y (rows), x (cols), facet_col, facet_row, animation_frame
     transpose_order = [