Render figure-level text objects.

This fixes issues such as mpld3#296
and maybe more, about figure-level text (such as fig.suptitle) not appearing.

It requires the corresponding mplexporter PR to land first, and only
then I should also update the submodule commit to that here:
mpld3/mplexporter#70

It also sets up support for figure-level transforms, which we'll need to
support more figure-level objects in the future.

I put the compiled js files in a separate commit for ease of reviewing.

This, too, was co-developed with gpt-5.1-codex, but I was heavily
involved. Here is how it summarizes the changes:

- Export figure-level text (suptitle + fig.text) into the mpld3 figure JSON (texts array) via the vendored exporter/renderer, rather than shoving it into an axes.
- JS core updated to handle figure-level coordinates/text: Coordinates can work with a figure, Figure renders figuretexts into a dedicated group, and Text can draw without an axes.
- Added tests asserting figure-level texts are exported and included in the figure dict; rebuilt the JS bundle accordingly.

Author: lucasb-eyer

mpld3/mpld3renderer.py

@@ -104,6 +104,7 @@ def open_figure(self, fig, props):
                                 height=props['figheight'] * props['dpi'],
                                 axes=[],
                                 data={},
+                                texts=[],
                                 id=get_id(fig))
 
     def close_figure(self, fig):
@@ -246,6 +247,21 @@ def draw_text(self, text, position, coordinates, style,
                     id=get_id(mplobj))
         self.axes_json['texts'].append(text)
 
+    def draw_figure_text(self, text, position, coordinates, style,
+                         text_type=None, mplobj=None):
+        text = dict(text=text,
+                    position=tuple(position),
+                    coordinates=coordinates,
+                    h_anchor=TEXT_HA_DICT[style['halign']],
+                    v_baseline=TEXT_VA_DICT[style['valign']],
+                    rotation=-style['rotation'],
+                    fontsize=style['fontsize'],
+                    color=style['color'],
+                    alpha=style['alpha'],
+                    zorder=style['zorder'],
+                    id=get_id(mplobj))
+        self.figure_json['texts'].append(text)
+
     def draw_image(self, imdata, extent, coordinates, style, mplobj=None):
         image = dict(data=imdata, extent=extent, coordinates=coordinates)
         image.update(style)

mpld3/tests/test_elements.py

@@ -4,7 +4,7 @@
 import numpy as np
 import matplotlib.pyplot as plt
 from .. import fig_to_dict, fig_to_html
-from numpy.testing import assert_equal
+from numpy.testing import assert_equal, assert_almost_equal
 
 
 def test_line():
@@ -137,6 +137,30 @@ def test_image():
     assert_equal(image['coordinates'], "data")
 
 
+def test_figure_texts_are_exported():
+    fig, ax = plt.subplots()
+    fig.suptitle("Hello title", x=0.25, y=0.9, ha="left")
+    fig.text(0.1, 0.05, "Footer", ha="center", va="center")
+
+    rep = fig_to_dict(fig)
+    texts = rep['texts']
+
+    assert_equal(len(texts), 2)
+
+    title = texts[0]
+    footer = texts[1]
+
+    assert_equal(title['text'], "Hello title")
+    assert_equal(title['coordinates'], "figure")
+    assert_almost_equal(title['position'][0], 0.25)
+    assert_almost_equal(title['position'][1], 0.9)
+
+    assert_equal(footer['text'], "Footer")
+    assert_equal(footer['coordinates'], "figure")
+    assert_almost_equal(footer['position'][0], 0.1)
+    assert_almost_equal(footer['position'][1], 0.05)
+
+
 def test_ticks():
     plt.xticks([1,2,3])
     rep = fig_to_html(plt.gcf())

mpld3/tests/test_figure.py

@@ -14,7 +14,7 @@ def test_basic_figure():
     plt.close(fig)
 
     assert_equal(list(sorted(rep.keys())),
-                 ['axes', 'data', 'height', 'id', 'plugins', 'width'])
+                 ['axes', 'data', 'height', 'id', 'plugins', 'texts', 'width'])
     assert_equal(rep['width'], size[0] * dpi)
     assert_equal(rep['height'], size[1] * dpi)
     assert_equal(rep['data'], {})

src/core/coordinates.js

@@ -3,17 +3,14 @@
 /*   `trans` is one of ["data", "figure", "axes", "display"]           */
 mpld3.Coordinates = mpld3_Coordinates;
 
-function mpld3_Coordinates(trans, ax) {
+function mpld3_Coordinates(trans, ax, fig) {
     this.trans = trans;
-    if (typeof(ax) === "undefined") {
-        this.ax = null;
-        this.fig = null;
-        if (this.trans !== "display")
-            throw "ax must be defined if transform != 'display'";
-    } else {
-        this.ax = ax;
-        this.fig = ax.fig;
-    }
+    this.ax = (typeof(ax) === "undefined") ? null : ax;
+    this.fig = (typeof(fig) === "undefined") ? (this.ax ? this.ax.fig : null) : fig;
+    if (this.ax === null && this.fig === null && this.trans !== "display")
+        throw "ax or fig must be defined if transform != 'display'";
+    if (this.ax === null && this.trans !== "display" && this.trans !== "figure")
+        throw "ax must be defined if transform != 'display' and transform != 'figure'";
     this.zoomable = (this.trans === "data");
     this.x = this["x_" + this.trans];
     this.y = this["y_" + this.trans];
@@ -46,8 +43,8 @@ mpld3_Coordinates.prototype.y_axes = function(y) {
     return this.ax.height * (1 - y);
 }
 mpld3_Coordinates.prototype.x_figure = function(x) {
-    return x * this.fig.width - this.ax.position[0];
+    return this.ax ? x * this.fig.width - this.ax.position[0] : x * this.fig.width;
 }
 mpld3_Coordinates.prototype.y_figure = function(y) {
-    return (1 - y) * this.fig.height - this.ax.position[1];
+    return this.ax ? (1 - y) * this.fig.height - this.ax.position[1] : (1 - y) * this.fig.height;
 }

src/core/figure.js

@@ -12,6 +12,7 @@ mpld3_Figure.prototype.requiredProps = ["width", "height"];
 mpld3_Figure.prototype.defaultProps = {
     data: {},
     axes: [],
+    texts: [],
     plugins: [{type: "reset"}, {type: "zoom"}, {type: "boxzoom"}]
 };
 
@@ -33,6 +34,11 @@ function mpld3_Figure(figid, props) {
     for (var i = 0; i < this.props.axes.length; i++)
         this.axes.push(new mpld3_Axes(this, this.props.axes[i]));
 
+    // Figure-level texts (e.g. suptitle, fig.text)
+    this.figuretexts = [];
+    for (var j = 0; j < this.props.texts.length; j++)
+        this.figuretexts.push(new mpld3.Text(this, this.props.texts[j]));
+
     // Connect the plugins to the figure
     this.plugins = [];
     this.pluginsByType = {};
@@ -91,6 +97,12 @@ mpld3_Figure.prototype.draw = function() {
         this.axes[i].draw();
     }
 
+    this.figureTextGroup = this.canvas.append("g")
+        .attr("class", "mpld3-figure-texts");
+    for (var k = 0; k < this.figuretexts.length; k++) {
+        this.figuretexts[k].draw();
+    }
+
     // disable zoom by default; plugins or toolbar items might change this.
     this.disableZoom();
 

src/elements/text.js

@@ -20,18 +20,23 @@ function mpld3_Text(ax, props) {
     mpld3_PlotElement.call(this, ax, props);
     this.text = this.props.text;
     this.position = this.props.position;
-    this.coords = new mpld3_Coordinates(this.props.coordinates, this.ax);
+    this.coords = new mpld3_Coordinates(this.props.coordinates, this.ax, this.fig);
 };
 
 mpld3_Text.prototype.draw = function() {
-    if (this.props.coordinates == "data") {
-        if (this.coords.zoomable) {
-            this.obj = this.ax.paths.append("text");
+    if (this.ax) {
+        if (this.props.coordinates == "data") {
+            if (this.coords.zoomable) {
+                this.obj = this.ax.paths.append("text");
+            } else {
+                this.obj = this.ax.staticPaths.append("text");
+            }
         } else {
-            this.obj = this.ax.staticPaths.append("text");
+            this.obj = this.ax.baseaxes.append("text");
         }
     } else {
-        this.obj = this.ax.baseaxes.append("text");
+        var target = this.fig.figureTextGroup || this.fig.canvas;
+        this.obj = target.append("text");
     }
 
     this.obj