fix: resize embedded figures once the page finishes loading

A figure whose inline script draws while the page is still being parsed
can be sized to a container whose width changes by the time loading
finishes (e.g. pydata-sphinx-theme's secondary sidebar comes after the
article in the DOM), leaving it clipped until a window resize. Append a
per-figure script to the _repr_html_ fallback and the sphinx-gallery
scraper embeds that calls Plotly.Plots.resize once on window load.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: larsoner

plotly/basedatatypes.py

@@ -825,14 +825,20 @@ def _repr_html_(self):
         if "text/html" in bundle:
             return bundle["text/html"]
         else:
+            import uuid
+
+            from plotly.io._utils import resize_after_load_script
+
+            div_id = str(uuid.uuid4())
             # Size like the html renderers do: "100%" height collapses or
             # overflows in plain-HTML consumers such as sphinx-gallery.
             return self.to_html(
                 full_html=False,
                 include_plotlyjs="cdn",
                 default_width="100%",
                 default_height=525,
-            )
+                div_id=div_id,
+            ) + resize_after_load_script(div_id)
 
     def _repr_mimebundle_(self, include=None, exclude=None, validate=True, **kwargs):
         """

plotly/io/_sg_scraper.py

@@ -6,10 +6,12 @@
 import logging
 import os
 import textwrap
+import uuid
 
 import plotly
 from plotly.basedatatypes import BaseFigure
 from plotly.io._base_renderers import sphinx_gallery_figures
+from plotly.io._utils import resize_after_load_script
 
 plotly.io.renderers.default = "sphinx_gallery_png"
 
@@ -147,17 +149,22 @@ def _inline_html(fig_dict):
     The figure is wrapped in the same div that sphinx-gallery wraps captured
     HTML reprs in, so that themes can style both kinds of embed alike.
     """
+    div_id = str(uuid.uuid4())
     html = plotly.io.to_html(
         fig_dict,
         include_plotlyjs="cdn",
         full_html=False,
         default_width="100%",
         default_height=525,
         validate=False,
+        div_id=div_id,
     )
     html = (
         '<div class="output_subarea output_html rendered_html output_result">\n'
         f"{html}\n"
+        # The figure may draw before the page finishes laying out, ending up
+        # sized to a container whose width then changes.
+        f"{resize_after_load_script(div_id)}\n"
         "</div>"
     )
     return "\n.. raw:: html\n\n" + textwrap.indent(html, "    ") + "\n"

plotly/io/_utils.py

@@ -91,3 +91,22 @@ def plotly_cdn_url(cdn_ver=get_plotlyjs_version()):
     return "https://cdn.plot.ly/plotly-{cdn_ver}.min.js".format(
         cdn_ver=cdn_ver,
     )
+
+
+def resize_after_load_script(div_id):
+    """Script that resizes a plotly div once the page finishes loading.
+
+    A figure drawn while its page is still loading (e.g. one embedded in a
+    sphinx-gallery page) can be sized to a container whose width changes by
+    the time loading finishes, so fix it up once afterwards.
+    """
+    return (
+        '<script>(function() {'
+        "function fit() {"
+        f'var gd = document.getElementById("{div_id}");'
+        "if (window.Plotly && gd) Plotly.Plots.resize(gd);"
+        "}"
+        'if (document.readyState === "complete") fit();'
+        'else window.addEventListener("load", fit);'
+        "})();</script>"
+    )

tests/test_io/test_sg_scraper.py

@@ -140,6 +140,8 @@ def test_scraper(gallery, image_format):
     assert rst.count("plotly-graph-div") == 2
     # The wrapper sphinx-gallery uses for HTML reprs, so themes can style both
     assert rst.count('class="output_subarea') == 2
+    # Fixes up figures drawn while the page was still laying out
+    assert rst.count("Plotly.Plots.resize") == 2
 
     # The thumbnail must be a scraped figure rather than a "no image" default,
     # and one image per figure in order is what makes `thumbnail_number` work
@@ -258,7 +260,10 @@ def test_repr_html_fallback_size(monkeypatch):
     with no set height.
     """
     monkeypatch.setattr(pio.renderers, "default", "sphinx_gallery_png")
-    assert 'style="height:525px; width:100%;"' in go.Figure()._repr_html_()
+    html = go.Figure()._repr_html_()
+    assert 'style="height:525px; width:100%;"' in html
+    # Fixes up figures drawn while the page was still laying out
+    assert "Plotly.Plots.resize" in html
     fig = go.Figure(layout={"height": 400})
     assert 'style="height:400px; width:100%;"' in fig._repr_html_()