Enhance responsive iframe embedding: add max width for notebook display and improve scaling logic for interactive widgets

Author: CSSFrancis

anyplotlib/_repr_utils.py

@@ -24,6 +24,11 @@
 from html import escape
 from uuid import uuid4
 
+# Maximum display width (px) for the non-resizable notebook embed.
+# Figures wider than this are scaled down proportionally via CSS transform.
+# 860 px fits comfortably in a standard JupyterLab / VS Code notebook cell.
+MAX_NOTEBOOK_WIDTH = 860
+
 
 # ---------------------------------------------------------------------------
 # Trait serialisation
@@ -204,8 +209,9 @@ def build_standalone_html(widget, *, resizable: bool = True) -> str:
 
 
 def repr_html_iframe(widget, *, resizable: bool = False,
+                     max_width: int = MAX_NOTEBOOK_WIDTH,
                      max_height: int = 800) -> str:
-    """Return a centred ``<iframe srcdoc=...>`` embedding *widget*.
+    """Return a centred, responsive ``<iframe srcdoc=...>`` embedding *widget*.
 
     Parameters
     ----------
@@ -215,9 +221,13 @@ def repr_html_iframe(widget, *, resizable: bool = False,
         Passed to :func:`build_standalone_html`.  Default ``False`` for
         documentation embeds — hides the resize handle and sizes the iframe
         exactly to the widget.
+    max_width : int
+        Maximum display width in pixels.  Figures wider than this are scaled
+        down proportionally via ``transform:scale()`` so they never overflow
+        the notebook cell.  Default ``MAX_NOTEBOOK_WIDTH`` (860 px).
     max_height : int
-        Upper bound on iframe height in pixels (only applied when
-        ``resizable=True`` and auto-sizing is used).
+        Upper bound on iframe height in pixels (only used when
+        ``resizable=True``).
     """
     inner_html = build_standalone_html(widget, resizable=resizable)
     escaped    = escape(inner_html, quote=True)
@@ -226,19 +236,54 @@ def repr_html_iframe(widget, *, resizable: bool = False,
     w, h = _widget_px(widget)
 
     if not resizable:
-        # Fixed size — iframe is exactly the widget's natural dimensions.
-        # Centred via a block wrapper with auto margins.
+        # ── Responsive fixed-size embed ────────────────────────────────────
+        # The iframe always renders at its native resolution so the widget
+        # is pixel-perfect on wide screens.  On narrower cells a CSS
+        # transform:scale() shrinks it proportionally — CSS transforms
+        # correctly route pointer events so interaction still works.
+        #
+        # The static scale (baked into the style attribute) renders correctly
+        # before JS runs.  requestAnimationFrame defers the first JS
+        # measurement until after layout is complete so offsetWidth is
+        # always valid; the !avail guard prevents a not-yet-reflowed parent
+        # from collapsing the wrapper.
+        init_scale = min(1.0, max_width / w)
+        init_w     = round(w * init_scale)
+        init_h     = round(h * init_scale)
+        scale_css  = f"{init_scale:.6f}".rstrip("0").rstrip(".")
+
+        js = (
+            f"(function(){{"
+            f"var wrap=document.getElementById('vw-{uid}'),"
+            f"ifr=wrap.querySelector('iframe'),"
+            f"nw={w},nh={h};"
+            f"function r(){{"
+            f"var avail=wrap.parentElement?wrap.parentElement.offsetWidth:0;"
+            f"if(!avail)return;"
+            f"var s=Math.min(1,avail/nw);"
+            f"wrap.style.width=Math.round(nw*s)+'px';"
+            f"wrap.style.height=Math.round(nh*s)+'px';"
+            f"ifr.style.transform='scale('+s+')';"
+            f"}}"
+            f"requestAnimationFrame(r);window.addEventListener('resize',r);"
+            f"}})()"
+        )
+
         return (
-            f'<div style="display:block;text-align:center;line-height:0;">'
-            f'<iframe id="vw-{uid}" srcdoc="{escaped}" frameborder="0" '
-            f'scrolling="no" '
-            f'style="width:{w}px;height:{h}px;border:none;overflow:hidden;'
-            f'display:inline-block;max-width:100%;">'
+            f'<div style="display:block;text-align:center;line-height:0;margin:8px 0;">'
+            f'<div id="vw-{uid}" style="display:inline-block;overflow:hidden;'
+            f'position:relative;width:{init_w}px;height:{init_h}px;">'
+            f'<iframe srcdoc="{escaped}" frameborder="0" scrolling="no" '
+            f'style="width:{w}px;height:{h}px;border:none;overflow:hidden;display:block;'
+            f'transform-origin:top left;transform:scale({scale_css});'
+            f'position:absolute;top:0;left:0;">'
             f'</iframe>'
             f'</div>'
+            f'<script>{js}</script>'
+            f'</div>'
         )
     else:
-        # Resizable — fill container width, auto-resize height after render.
+        # ── Resizable embed (fills cell width, auto-sizes height) ──────────
         return (
             f'<iframe id="vw-{uid}" srcdoc="{escaped}" frameborder="0" '
             f'style="width:100%;height:{h}px;border:none;overflow:hidden;" '

anyplotlib/figure.py

@@ -73,6 +73,31 @@ class Figure(anywidget.AnyWidget):
     # Bidirectional JS event bus: JS writes interaction events here, Python reads them.
     event_json  = traitlets.Unicode("{}").tag(sync=True)
     _esm = _ESM_SOURCE
+    # Static CSS injected by anywidget alongside _esm.
+    # .apl-scale-wrap  — outer container; width:100% means it always fills
+    #                    the cell without any JS width updates.
+    # .apl-outer       — the figure root; will-change:transform pre-promotes
+    #                    it to a GPU compositing layer so transform:scale()
+    #                    changes cost zero layout/paint passes.
+    _css = """\
+.apl-scale-wrap {
+    display: block;
+    width: 100%;
+    overflow: visible;
+    position: relative;
+    line-height: 0;
+}
+.apl-outer {
+    display: inline-block;
+    position: relative;
+    user-select: none;
+    z-index: 1;
+    isolation: isolate;
+    will-change: transform;
+    transform-origin: top left;
+    vertical-align: top;
+}
+"""
 
     def __init__(self, nrows=1, ncols=1, figsize=(640, 480),
                  width_ratios=None, height_ratios=None,

anyplotlib/figure_esm.js

@@ -83,9 +83,16 @@ function render({ model, el }) {
   }
 
   // ── outer DOM ────────────────────────────────────────────────────────────
+  // Static layout styles live in the _css traitlet (.apl-scale-wrap /
+  // .apl-outer).  Only the two dynamic properties — transform and
+  // marginBottom — are ever written here at runtime.
+  const scaleWrap = document.createElement('div');
+  scaleWrap.classList.add('apl-scale-wrap');
+  el.appendChild(scaleWrap);
+
   const outerDiv = document.createElement('div');
-  outerDiv.style.cssText = 'position:relative;display:inline-block;user-select:none;z-index:1;isolation:isolate;';
-  el.appendChild(outerDiv);
+  outerDiv.classList.add('apl-outer');
+  scaleWrap.appendChild(outerDiv);
 
   const gridDiv = document.createElement('div');
   gridDiv.style.cssText = `display:grid;gap:4px;background:${theme.bg};padding:8px;border-radius:4px;`;
@@ -2801,75 +2808,53 @@ function render({ model, el }) {
     for(const p of panels.values()) _redrawPanel(p);
   }
 
-  // ── cell-aware layout: redraw when the notebook cell changes size ─────────
-  // We observe `el` (the anywidget mount point) directly. The notebook sets
-  // its width; we never write to it, so there is no feedback loop.
-  // Only triggers when the cell is narrower than the current widget — we
-  // never upscale beyond the stored fig_width / fig_height.
+  // ── cell-aware CSS scaling ────────────────────────────────────────────────
+  // When the notebook cell (or any container) is narrower than the figure's
+  // native size, apply CSS transform:scale() to outerDiv so it shrinks
+  // proportionally without re-rendering canvases or writing to the model.
+  // Full canvas resolution is preserved; CSS transforms correctly route
+  // pointer events so all interactive features (drag, zoom, pan) keep working.
+  // Also called after layout/resize changes so the scale stays in sync.
+  function _applyScale() {
+    const cellW = el.getBoundingClientRect().width;
+    if (!cellW) return;
+    // offsetWidth is the pre-transform layout width — unaffected by any
+    // currently applied transform, so it always reflects the native figure size.
+    const nativeW = outerDiv.offsetWidth;
+    const nativeH = outerDiv.offsetHeight;
+    if (!nativeW) return;
+    const s = Math.min(1.0, cellW / nativeW);
+    // transform-origin:top left (set in _css) means scale(s) shrinks the
+    // figure from the top-left corner.  With width:100% on scaleWrap the
+    // scaled figure (nativeW*s ≤ cellW) always fits — no overflow, no
+    // clipping, no cross-browser layout-box vs visual-box discrepancies.
+    outerDiv.style.transform = s < 1 ? `scale(${s})` : '';
+    // transform:scale does not affect layout — outerDiv still occupies
+    // nativeH px in the flow even when visually shorter.  A negative
+    // marginBottom compensates exactly, pulling subsequent content up by
+    // the difference without ever touching scaleWrap's own dimensions.
+    // This eliminates any ResizeObserver feedback loop.
+    outerDiv.style.marginBottom = (s < 1 && nativeH)
+      ? Math.round(nativeH * (s - 1)) + 'px'
+      : '';
+  }
+
   if (typeof ResizeObserver !== 'undefined') {
-    let _roTimer = null;
-    let _roActive = false;            // prevent re-entry
     let _lastCellW = 0;
-
-    const _ro = new ResizeObserver(entries => {
-      if (_roActive || isResizing || _suppressLayoutUpdate) return;
+    new ResizeObserver(entries => {
+      // React only to width changes to avoid a feedback loop: our own
+      // scaleWrap height updates would otherwise re-trigger the observer.
       const cellW = entries[0].contentRect.width;
-      if (!cellW || cellW === _lastCellW) return;
+      if (cellW === _lastCellW) return;
       _lastCellW = cellW;
-
-      // Measure the widget's natural width (what it would like to be)
-      const gridW = gridDiv.scrollWidth || gridDiv.getBoundingClientRect().width;
-      if (!gridW || cellW >= gridW - 2) return;  // fits — nothing to do
-
-      clearTimeout(_roTimer);
-      _roTimer = setTimeout(() => {
-        if (_roActive || isResizing || _suppressLayoutUpdate) return;
-
-        // Re-read the cell width inside the timeout (may have changed)
-        const availW = el.getBoundingClientRect().width;
-        if (!availW) return;
-
-        let layout;
-        try { layout = JSON.parse(model.get('layout_json')); } catch(_) { return; }
-
-        const curW = layout.fig_width || model.get('fig_width');
-        const curH = layout.fig_height || model.get('fig_height');
-        if (!curW || availW >= curW) return;   // already fits
-
-        const scale = availW / curW;
-        const nfw = Math.max(200, Math.round(curW * scale));
-        const nfh = Math.max(100, Math.round(curH * scale));
-
-        _roActive = true;
-        _suppressLayoutUpdate = true;
-        _cachedLayout = layout;        // reuse cached layout for the resize
-        _applyFigResize(nfw, nfh);
-
-        // Persist the new size into the model so it survives kernel restarts
-        try {
-          layout.fig_width  = nfw;
-          layout.fig_height = nfh;
-          for (const spec of layout.panel_specs) {
-            const p = panels.get(spec.id);
-            if (p) { spec.panel_width = p.pw; spec.panel_height = p.ph; }
-          }
-          model.set('layout_json', JSON.stringify(layout));
-        } catch(_) {}
-        _suppressLayoutUpdate = false;
-        model.set('fig_width',  nfw);
-        model.set('fig_height', nfh);
-        model.save_changes();
-
-        _roActive = false;
-      }, 150);
-    });
-
-    _ro.observe(el);
+      requestAnimationFrame(_applyScale);
+    }).observe(el);
+    requestAnimationFrame(_applyScale);
   }
 
   // ── model listeners ───────────────────────────────────────────────────────
-  model.on('change:layout_json', () => { applyLayout(); redrawAll(); });
-  model.on('change:fig_width change:fig_height', () => { applyLayout(); redrawAll(); });
+  model.on('change:layout_json', () => { applyLayout(); redrawAll(); requestAnimationFrame(_applyScale); });
+  model.on('change:fig_width change:fig_height', () => { applyLayout(); redrawAll(); requestAnimationFrame(_applyScale); });
 
   // Python→JS targeted widget update (source:"python" in event_json).
   // Applies changed fields directly to the widget in overlay_widgets and

docs/_sg_html_scraper.py

@@ -129,19 +129,26 @@ def _iframe_html(src: str, w: int, h: int) -> str:
     # Inline JS: re-scale whenever the window is resized.
     # Uses the wrapper's parent width as the available space so the figure
     # always fills (but never overflows) the content column.
+    #
+    # requestAnimationFrame defers the first call until after the browser has
+    # finished its initial layout pass, so offsetWidth is always non-zero.
+    # The !avail guard ensures a partially-laid-out parent (offsetWidth==0)
+    # never collapses the wrapper — the CSS-baked initial scale stays intact
+    # until a valid measurement is available.
     js = (
         f"(function(){{"
         f"var wrap=document.getElementById('{uid}'),"
         f"ifr=wrap.querySelector('iframe'),"
         f"nw={w},nh={h};"
         f"function r(){{"
-        f"var avail=wrap.parentElement?wrap.parentElement.offsetWidth:nw;"
+        f"var avail=wrap.parentElement?wrap.parentElement.offsetWidth:0;"
+        f"if(!avail)return;"
         f"var s=Math.min(1,avail/nw);"
         f"wrap.style.width=Math.round(nw*s)+'px';"
         f"wrap.style.height=Math.round(nh*s)+'px';"
         f"ifr.style.transform='scale('+s+')';"
         f"}}"
-        f"r();window.addEventListener('resize',r);"
+        f"requestAnimationFrame(r);window.addEventListener('resize',r);"
         f"}})()"
     )