feat(imshow): support facet_row for subplot rows (plotly>=6.7)

[FBumann]

Summary

px.imshow gained facet_row support in plotly 6.7.0 (plotly/plotly.py#5445). This PR ports it into xarray_plotly.imshow.

• Add facet_row to the imshow slot order: ("y", "x", "facet_col", "facet_row", "animation_frame") — now consistent with all other plot types
• New facet_row parameter on plotting.imshow() and DataArray.plotly.imshow()
• Global color bounds (zmin/zmax) apply across the full facet grid, as before
• Docs: fixed the slot table in dimensions.ipynb (it already listed facet_row aspirationally) and added a heatmap-grid example

Compatibility

The plotly requirement stays at >=5.0.0:

	plotly >= 6.7.0	plotly < 6.7.0
4D auto-assignment	4th dim → facet_row	4th dim → animation_frame (unchanged)
Explicit facet_row="dim"	facet grid	informative ValueError suggesting upgrade

Auto-assignment only fills facet_row when the installed plotly supports it, so existing code keeps working on older plotly versions.

Test plan

• New tests: 4D/5D slot auto-assignment, explicit facet_row, facet grid + animation, shared color bounds across facets, old-plotly fallback and error paths (pytest: 154 passed)
• ruff, ruff format, mypy clean
• facet_row tests are skipped automatically when plotly <6.7.0 is installed

🤖 Generated with Claude Code

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR adds facet_row support to the imshow plotting function. The implementation includes runtime detection of Plotly version support (>= 6.7.0), conditional error handling with informative messages, updates to the public accessor API, configuration changes to default slot ordering, and comprehensive test coverage with documentation examples.

Changes

imshow facet_row feature

Layer / File(s)	Summary
Core facet_row implementation in imshow xarray_plotly/plotting.py	Adds inspect module for signature detection, introduces _imshow_supports_facet_row() helper that checks Plotly version at runtime, extends imshow signature to accept facet_row parameter, validates support and raises ValueError with upgrade guidance if unsupported, adjusts transpose order to include facet_row when present, and passes it to px.imshow via kwargs dict.
Public accessor API and configuration xarray_plotly/accessor.py, xarray_plotly/config.py	DataArrayPlotlyAccessor.imshow method signature updated with facet_row parameter and documented Plotly >= 6.7.0 requirement; call to plotting.imshow passes through the facet_row value; DEFAULT_SLOT_ORDERS["imshow"] updated to include "facet_row" between "facet_col" and "animation_frame".
Slot assignment unit tests tests/test_common.py	New test cases verify that 4D and 5D DataArrays correctly assign facet_row and animation_frame dimensions via assign_slots for imshow plots; SLOT_ORDERS["imshow"] expectation updated to include facet_row in the sequence.
Accessor imshow faceting integration tests tests/test_accessor.py	Test imports updated to pull plotting and _imshow_supports_facet_row; new pytest skip marker requires_imshow_facet_row gates facet_row tests on version support; new TestImshowFaceting class validates subplot counts, annotations, shared color bounds, combined animation behavior, and error handling when facet_row is unsupported or used on old Plotly; confirms backward compatibility with facet_row=None.
Documentation and examples docs/examples/dimensions.ipynb	"Available Slots" table updated to reflect corrected slot order y, x, facet_col, facet_row, animation_frame for imshow; new code example in "Faceting" section demonstrates heatmap gridding with facet_row="metric" on 3D data with inline note requiring Plotly >= 6.7.0.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 A plotly heatmap now facets with grace,
With rows to partition and grid to embrace,
Version-gated kindly for Plotly's new way,
Tests guard every path, from old to today! 📊

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: adding facet_row support to imshow with the version requirement, matching the primary objective of the PR.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/imshow-facet-row

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}