Fix Matplotlib gallery, styling, axes, and label compatibility [mpl compatibility]

CHANGELOG.md

@@ -69,6 +69,8 @@ in the README).
   that don't use them are byte-identical.
 
 ### Fixed
+- Improved Matplotlib compatibility for pie and vector-field plots, multiline
+  layout, authored styles, axes helpers/autoscaling, and browser Y-axis titles.
 - A mark-level `animation=xy.animation(...)` no longer resets the chart-level
   policy fields it does not mention. It was a complete spec spread over the
   chart's, so `xy.animation(duration=90)` on a mark silently reset `match`,

benchmarks/test_codspeed_pyplot.py

@@ -360,7 +360,10 @@ def test_build_styled_panel_pyplot(benchmark, panel_data):
     """
     x, actual, target, sample = panel_data
     payload_bytes = benchmark(_pyplot_styled_panel_payload, x, actual, target, sample)
-    assert payload_bytes == _raw_styled_panel_payload(x, actual, target, sample)
+    raw_payload_bytes = _raw_styled_panel_payload(x, actual, target, sample)
+    # Pyplot preserves Matplotlib's axes-title y/pad geometry as two float32
+    # values. The raw title= API intentionally uses its fixed legacy fallback.
+    assert payload_bytes == raw_payload_bytes + 2 * np.dtype(np.float32).itemsize
 
 
 # -- export pair ----------------------------------------------------------------

js/src/00_header.ts

@@ -30,9 +30,13 @@
 // v8: legend/colorbar geometry, extra colormap names, and match-fill strokes
 // add wire values an older v7 client would accept but silently misrender.
 // v9: explicit minor axis ticks/styles, log nonpositive behavior,
-// scalar-normalization scale, colorbar padding/explicit-axes placement, and
-// contour-line overlays. A v8 client silently misrenders these values.
-export const PROTOCOL = 9;
+// `axis.tick_sides`/`axis.tick_label_sides`, scalar-normalization scale,
+// colorbar padding/explicit-axes placement, and contour-line overlays add wire
+// values a cached v8 client would accept but silently misrender.
+// v10: `title_options` carries independent left/center/right title artists,
+// including axes-fraction y and pixel padding. A v9 client would silently omit
+// non-center slots and their placement, so v10 rejects it before rendering.
+export const PROTOCOL = 10;
 
 // HTTP binary frame v1 (spec/design/wire-protocol.md §7; Python side in
 // python/xy/_framing.py). The chart spec's PROTOCOL

js/src/51_annotations.ts

@@ -23,6 +23,7 @@ const XY_ANNOTATION_SHAPE_STYLE_KEYS = new Set([
   "curve",
   "angle_a",
   "angle_b",
+  "elbow",
   "gap_start",
   "gap_end",
   "start_offset",
@@ -106,7 +107,14 @@ function xyArrowGeometry(x0, y0, x1, y1, style) {
   // Tangent INTO each endpoint (head/tail orientation).
   const dir1 = cx === null ? toward(p0[0], p0[1], p1[0], p1[1]) : toward(cx, cy, p1[0], p1[1]);
   const dir0 = cx === null ? toward(p1[0], p1[1], p0[0], p0[1]) : toward(cx, cy, p0[0], p0[1]);
-  return { p0, p1, control: cx === null ? null : [cx, cy], dir0, dir1 };
+  return {
+    p0,
+    p1,
+    control: cx === null ? null : [cx, cy],
+    elbow: Boolean(style.elbow),
+    dir0,
+    dir1,
+  };
 }
 
 // The shaft as a point list (quadratic Bézier sampled when curved).
@@ -115,6 +123,7 @@ function xyArrowShaftPoints(geom, samples = 24) {
   const [x1, y1] = geom.p1;
   if (!geom.control) return [[x0, y0], [x1, y1]];
   const [cx, cy] = geom.control;
+  if (geom.elbow) return [[x0, y0], [cx, cy], [x1, y1]];
   const points = [];
   for (let i = 0; i <= samples; i++) {
     const t = i / samples;
@@ -555,20 +564,41 @@ Object.assign(ChartView.prototype, {
     const annotations = Array.isArray(this.spec.annotations) ? this.spec.annotations : [];
     if (!annotations.length) return;
     const p = this.plot;
-    ctx.save();
-    ctx.beginPath();
-    ctx.rect(p.x, p.y, p.w, p.h);
-    ctx.clip();
     for (const [annotationIndex, ann] of annotations.entries()) {
+      ctx.save();
+      let targetX = NaN;
+      let targetY = NaN;
+      if (ann.kind === "arrow") {
+        targetX = this._dataPxX(Number(ann.x1));
+        targetY = this._dataPxY(Number(ann.y1));
+      } else if (ann.kind === "callout") {
+        targetX = this._dataPxX(Number(ann.x));
+        targetY = this._dataPxY(Number(ann.y));
+      }
+      const connectorTargetInBounds =
+        Number.isFinite(targetX) && Number.isFinite(targetY) &&
+        targetX >= p.x && targetX <= p.x + p.w &&
+        targetY >= p.y && targetY <= p.y + p.h;
+      if (!connectorTargetInBounds) {
+        ctx.beginPath();
+        ctx.rect(p.x, p.y, p.w, p.h);
+        ctx.clip();
+      }
       const style = ann && typeof ann.style === "object" ? ann.style : {};
       if (ann.kind === "band") {
         const vertical = ann.axis === "x";
         const a = vertical ? this._dataPxX(Number(ann.start)) : this._dataPxY(Number(ann.start));
         const b = vertical ? this._dataPxX(Number(ann.end)) : this._dataPxY(Number(ann.end));
-        if (!Number.isFinite(a) || !Number.isFinite(b)) continue;
+        if (!Number.isFinite(a) || !Number.isFinite(b)) {
+          ctx.restore();
+          continue;
+        }
         const lo = Math.max(vertical ? p.x : p.y, Math.min(a, b));
         const hi = Math.min(vertical ? p.x + p.w : p.y + p.h, Math.max(a, b));
-        if (hi <= lo) continue;
+        if (hi <= lo) {
+          ctx.restore();
+          continue;
+        }
         ctx.save();
         ctx.globalAlpha = this._styleNumber(style, "opacity", 0.14);
         ctx.fillStyle = this._annotationPaint(style, [0.39, 0.45, 0.55, 1]);
@@ -581,9 +611,18 @@ Object.assign(ChartView.prototype, {
       } else if (ann.kind === "rule") {
         const vertical = ann.axis === "x";
         const pos = vertical ? this._dataPxX(Number(ann.value)) : this._dataPxY(Number(ann.value));
-        if (!Number.isFinite(pos)) continue;
-        if (vertical && (pos < p.x - 1 || pos > p.x + p.w + 1)) continue;
-        if (!vertical && (pos < p.y - 1 || pos > p.y + p.h + 1)) continue;
+        if (!Number.isFinite(pos)) {
+          ctx.restore();
+          continue;
+        }
+        if (vertical && (pos < p.x - 1 || pos > p.x + p.w + 1)) {
+          ctx.restore();
+          continue;
+        }
+        if (!vertical && (pos < p.y - 1 || pos > p.y + p.h + 1)) {
+          ctx.restore();
+          continue;
+        }
         const crisp = Math.round(pos) + 0.5;
         ctx.save();
         ctx.globalAlpha = this._styleNumber(style, "opacity", 1);
@@ -634,8 +673,8 @@ Object.assign(ChartView.prototype, {
           ann
         );
       }
+      ctx.restore();
     }
-    ctx.restore();
   },
 
   _drawAnnotationLabels(updateLabels) {

python/xy/_arrowgeom.py

@@ -4,7 +4,8 @@
 sync. Style keys: ``curve`` (matplotlib arc3 rad — quadratic bulge as a
 fraction of chord length), ``angle_a``/``angle_b`` (matplotlib angle3/angle
 departure/arrival angles, degrees, y-up screen space — the control point is
-the ray intersection), ``gap_start``/``gap_end`` (px trims along the path
+the ray intersection), ``elbow`` (use that intersection as the sharp corner
+for ``connectionstyle="angle"``), ``gap_start``/``gap_end`` (px trims along the path
 tangents for label/point clearance), ``start_offset`` (an "x,y" px shift of
 the start point — matplotlib's relpos: the arrow leaves the label's box
 CENTER, not its anchor), ``label_clear`` (a "left,right,up,down" px
@@ -85,7 +86,14 @@ def toward(px: float, py: float, qx: float, qy: float) -> tuple[float, float]:
     # Tangent INTO each endpoint (head/tail orientation).
     dir1 = toward(*control, *p1) if control else toward(*p0, *p1)
     dir0 = toward(*control, *p0) if control else toward(*p1, *p0)
-    return {"p0": p0, "p1": p1, "control": control, "dir0": dir0, "dir1": dir1}
+    return {
+        "p0": p0,
+        "p1": p1,
+        "control": control,
+        "elbow": bool(style.get("elbow")),
+        "dir0": dir0,
+        "dir1": dir1,
+    }
 
 
 def shaft_points(geom: dict[str, Any], samples: int = 24) -> list[tuple[float, float]]:
@@ -95,6 +103,8 @@ def shaft_points(geom: dict[str, Any], samples: int = 24) -> list[tuple[float, f
     if control is None:
         return [(x0, y0), (x1, y1)]
     cx, cy = control
+    if geom.get("elbow"):
+        return [(x0, y0), (cx, cy), (x1, y1)]
     points = []
     for index in range(samples + 1):
         t = index / samples

python/xy/_figure.py

@@ -10,7 +10,7 @@
 
 import math
 import warnings
-from collections.abc import Mapping
+from collections.abc import Mapping, Sequence
 from os import PathLike
 from typing import Any, Optional, TypeAlias, Union
 
@@ -112,6 +112,10 @@ def __init__(
         # padding + hidden axes gives an edge-to-edge sparkline for dashboards.
         self.padding = self._padding(padding, "padding")
         self.title = self._optional_text(title, "title")
+        # Optional renderer-owned title slots. Declarative charts keep using
+        # ``title``; the pyplot shim fills this with Matplotlib's independent
+        # left/center/right title artists.
+        self.title_options: list[dict[str, Any]] = []
         self.x_label = self._optional_text(x_label, "x_label")
         self.y_label = self._optional_text(y_label, "y_label")
         self.axis_options: dict[str, dict[str, Any]] = {
@@ -254,6 +258,8 @@ def set_axis(
         tick_label_anchor: Optional[str] = None,
         tick_label_min_gap: Optional[float] = None,
         side: Optional[str] = None,
+        tick_sides: Optional[Any] = None,
+        tick_label_sides: Optional[Any] = None,
         style: Optional[dict[str, Any]] = None,
         minor_style: Optional[dict[str, Any]] = None,
         nonpositive: Optional[str] = None,
@@ -287,6 +293,28 @@ def set_axis(
             raise ValueError("x axis side must be 'top' or 'bottom'")
         elif axis_dim == "y" and side not in {"left", "right"}:
             raise ValueError("y axis side must be 'left' or 'right'")
+        if tick_sides is not None:
+            if isinstance(tick_sides, (str, bytes)) or not isinstance(tick_sides, Sequence):
+                raise ValueError(f"{axis_id} axis tick_sides must be a sequence")
+            allowed_tick_sides = ("bottom", "top") if axis_dim == "x" else ("left", "right")
+            tick_sides = list(tick_sides)
+            if any(value not in allowed_tick_sides for value in tick_sides):
+                raise ValueError(
+                    f"{axis_id} axis tick_sides must contain only {list(allowed_tick_sides)}"
+                )
+            tick_sides = [value for value in allowed_tick_sides if value in tick_sides]
+        if tick_label_sides is not None:
+            if isinstance(tick_label_sides, (str, bytes)) or not isinstance(
+                tick_label_sides, Sequence
+            ):
+                raise ValueError(f"{axis_id} axis tick_label_sides must be a sequence")
+            allowed_label_sides = ("bottom", "top") if axis_dim == "x" else ("left", "right")
+            tick_label_sides = list(tick_label_sides)
+            if any(value not in allowed_label_sides for value in tick_label_sides):
+                raise ValueError(
+                    f"{axis_id} axis tick_label_sides must contain only {list(allowed_label_sides)}"
+                )
+            tick_label_sides = [value for value in allowed_label_sides if value in tick_label_sides]
         values = (
             None
             if tick_values is None
@@ -338,6 +366,8 @@ def set_axis(
             if tick_label_min_gap is None
             else self._nonnegative_scalar(tick_label_min_gap, f"{axis_id} axis tick_label_min_gap"),
             "side": side,
+            "tick_sides": tick_sides,
+            "tick_label_sides": tick_label_sides,
             "style": styles.compile_axis_style(style, f"{axis_id} axis style"),
             "minor_style": styles.compile_axis_style(minor_style, f"{axis_id} minor axis style"),
             "nonpositive": nonpositive,
@@ -1273,6 +1303,10 @@ def _axis_spec(self, axis_id: str, range_: tuple[float, float]) -> dict[str, Any
             "range": list(range_),
             "side": opts.get("side", "bottom" if axis == "x" else "left"),
         }
+        if opts.get("tick_sides") is not None:
+            spec["tick_sides"] = list(opts["tick_sides"])
+        if opts.get("tick_label_sides") is not None:
+            spec["tick_label_sides"] = list(opts["tick_label_sides"])
         if label_position is not None:
             spec["label_position"] = label_position
         if label_offset is not None:

python/xy/_payload.py

@@ -287,6 +287,19 @@ def axis_range(axis_id: str) -> tuple[float, float]:
                 "ranges": {axis_id: list(axis["range"]) for axis_id, axis in axis_specs.items()}
             },
         }
+        if self.title_options:
+            spec["title_options"] = [
+                {
+                    **{key: value for key, value in entry.items() if key not in {"y", "pad"}},
+                    "geometry": pw.ship_scalar(
+                        np.asarray(
+                            (entry.get("y", 1.0), entry.get("pad", 8.0)),
+                            dtype=np.float64,
+                        )
+                    ),
+                }
+                for entry in self.title_options
+            ]
         if self.palette is not None:
             # Chart-level categorical cycle (`xy.theme(palette=...)`). Every
             # trace already bakes its own color and every categorical channel