ggplot2-python 4.0.2.9000__py3-none-any.whl

ggplot2_py/guide_legend.py

@@ -0,0 +1,1061 @@
+"""
+Legend guide building functions — faithful port of R's GuideLegend.
+
+Each legend is built as an independent :class:`~gtable_py.Gtable` with
+its own viewport-based layout.  Multiple legends are combined via
+:func:`package_legend_box` into a composite guide-box gtable.
+
+R references
+------------
+* ``ggplot2/R/guide-legend.R`` — GuideLegend class
+* ``ggplot2/R/guides-.R``      — Guides$package_box
+* ``ggplot2/R/guide-.R``       — Guide$add_title
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Any, Callable, Dict, List, Optional, Sequence, Tuple
+
+import numpy as np
+
+from grid_py import (
+    GList,
+    GTree,
+    Gpar,
+    Unit,
+    Viewport,
+    null_grob,
+    rect_grob,
+    text_grob,
+    unit_c,
+)
+from grid_py._grob import grob_tree
+
+from gtable_py import (
+    Gtable,
+    gtable_add_cols,
+    gtable_add_grob,
+    gtable_add_padding,
+    gtable_add_row_space,
+    gtable_add_rows,
+    gtable_col,
+    gtable_height,
+    gtable_width,
+)
+
+__all__ = [
+    "build_legend_decor",
+    "build_legend_labels",
+    "measure_legend_grobs",
+    "arrange_legend_layout",
+    "assemble_legend",
+    "add_legend_title",
+    "package_legend_box",
+]
+
+# ---------------------------------------------------------------------------
+# Constants  (R defaults from ggplot2 theme)
+# ---------------------------------------------------------------------------
+
+_DEFAULT_KEY_WIDTH_CM: float = 0.5     # legend.key.width  default ~1.2 lines
+_DEFAULT_KEY_HEIGHT_CM: float = 0.5    # legend.key.height default ~1.2 lines
+_DEFAULT_SPACING_X_CM: float = 0.15    # legend.key.spacing.x
+_DEFAULT_SPACING_Y_CM: float = 0.0     # legend.key.spacing.y (vertical: 0)
+_DEFAULT_PADDING_CM: float = 0.15      # legend.margin
+_DEFAULT_LABEL_SIZE: float = 6.0       # legend.text size (pt)
+_DEFAULT_TITLE_SIZE: float = 7.0       # legend.title size (pt)
+
+
+def _text_width_cm(text: str, fontsize: float = 10.0) -> float:
+    """Measure text width in cm using Cairo font metrics.
+
+    Replaces the old ``len(text) * 0.18`` character-count heuristic with
+    actual font measurement, matching R's ``width_cm(label_grob)`` pattern
+    (utilities-grid.R:67-77).
+    """
+    from grid_py._size import calc_string_metric
+    m = calc_string_metric(text, Gpar(fontsize=fontsize))
+    return m["width"] * 2.54  # inches → cm
+
+
+def _text_height_cm(text: str, fontsize: float = 10.0) -> float:
+    """Measure text height in cm using Cairo font metrics.
+
+    Matches R's ``height_cm(label_grob)`` pattern.
+    """
+    from grid_py._size import calc_string_metric
+    m = calc_string_metric(text, Gpar(fontsize=fontsize))
+    return (m["ascent"] + m["descent"]) * 2.54  # inches → cm
+
+
+# ---------------------------------------------------------------------------
+# build_legend_decor
+# ---------------------------------------------------------------------------
+
+def build_legend_decor(
+    entry: Dict[str, Any],
+    draw_key_fn: Callable,
+    layers: Any,
+    key_width_cm: float = _DEFAULT_KEY_WIDTH_CM,
+    key_height_cm: float = _DEFAULT_KEY_HEIGHT_CM,
+    theme: Any = None,
+) -> List[Any]:
+    """Build legend key glyphs for one merged entry.
+
+    For each break index, calls *draw_key_fn* with the aesthetic data for
+    that break, then wraps the resulting grob in a ``GTree`` whose viewport
+    is sized ``key_width_cm x key_height_cm``.
+
+    Mirrors ``GuideLegend$build_decor`` in R (guide-legend.R:396-431).
+
+    Parameters
+    ----------
+    entry : dict
+        Merged legend entry with keys ``aes_mapped``, ``breaks``, ``labels``.
+    draw_key_fn : callable
+        The geom's ``draw_key`` function (e.g. ``draw_key_point``).
+    layers : list
+        Plot layers (used to detect geom params).
+    key_width_cm, key_height_cm : float
+        Key glyph dimensions in cm.
+
+    Returns
+    -------
+    list of grob
+        One glyph GTree per break.
+    """
+    from ggplot2_py.plot import _safe_colour
+
+    aes_mapped = entry["aes_mapped"]
+    n_breaks = len(entry["breaks"])
+
+    # Resolve layer params (first layer only, like R).
+    # R (guide-legend.R:396-410): ``build_decor`` passes per-break
+    # ``data`` (from the scale) *merged* with the layer's fixed
+    # ``aes_params`` (e.g. ``fill='red'`` when the user wrote
+    # ``geom_point(shape=21, fill='red')``).  If we only forward
+    # the mapped aesthetics, a legend key for a shape=21 layer with
+    # ``fill='red'`` shows up as a black disc instead of a red ring.
+    layer_params: Dict[str, Any] = {}
+    layer_aes_params: Dict[str, Any] = {}
+    geom_default_aes: Dict[str, Any] = {}
+    if layers:
+        for layer in layers:
+            geom = getattr(layer, "geom", None)
+            if geom is not None:
+                # R (guide-legend.R:408): data passed to draw_key is the
+                # decoration's data, which was populated with the
+                # geom's ``default_aes`` resolved through the active
+                # theme — NOT hardcoded black/grey.  We mirror that by
+                # evaluating FromTheme markers in default_aes now.
+                raw = getattr(geom, "default_aes", None)
+                if raw is not None:
+                    try:
+                        from ggplot2_py.geom import _eval_from_theme
+                        resolved = _eval_from_theme(raw, theme)
+                        geom_default_aes = dict(resolved.items()) if hasattr(resolved, "items") else dict(resolved)
+                    except Exception:
+                        geom_default_aes = {}
+                layer_params = getattr(layer, "computed_geom_params", {})
+                if not layer_params:
+                    layer_params = getattr(geom, "default_params", {})
+                    if callable(layer_params):
+                        layer_params = layer_params()
+                layer_aes_params = dict(getattr(layer, "aes_params", {}) or {})
+                break
+
+    # Key size passed to draw_key as mm (R multiplies by 10 from cm)
+    key_size = (key_width_cm * 10, key_height_cm * 10)
+
+    # Key background grob (R: element_grob(elements$key))
+    key_bg = rect_grob(
+        gp=Gpar(fill="white", col="grey90", lwd=0.5),
+        name="legend.key.bg",
+    )
+
+    key_glyphs = []
+    for i in range(n_breaks):
+        # Build the aesthetic data dict for this break
+        data: Dict[str, Any] = {}
+        for aes_name, mapped_vals in aes_mapped.items():
+            val = mapped_vals[i] if i < len(mapped_vals) else None
+            if aes_name in ("colour", "color"):
+                data["colour"] = _safe_colour(val)
+            elif aes_name == "fill":
+                data["fill"] = _safe_colour(val)
+            elif aes_name == "shape":
+                data["shape"] = int(val) if val is not None else 19
+            elif aes_name == "size":
+                try:
+                    data["size"] = float(val) if val is not None else 1.5
+                    if np.isnan(data["size"]):
+                        data["size"] = 1.5
+                except (TypeError, ValueError):
+                    data["size"] = 1.5
+            elif aes_name == "linetype":
+                data["linetype"] = val
+            elif aes_name == "linewidth":
+                data["linewidth"] = val
+            elif aes_name == "alpha":
+                data["alpha"] = val
+            else:
+                data[aes_name] = val
+
+        # Merge layer fixed aes_params on top of any mapped aesthetics.
+        # R (guide-legend.R:404) slices the decoration's ``data`` which
+        # already contains fixed params via ``Layer$compute_aesthetics``.
+        # Fixed params win when both are present (matches R's
+        # ``data <- vec_slice(dec$data, i)`` behaviour where fixed
+        # values are written into the data frame).
+        for k, v in layer_aes_params.items():
+            if k in ("colour", "color"):
+                data["colour"] = _safe_colour(v)
+            elif k == "fill":
+                data["fill"] = _safe_colour(v)
+            elif k == "shape" and v is not None:
+                try:
+                    data["shape"] = int(v)
+                except (TypeError, ValueError):
+                    data["shape"] = v
+            elif v is not None:
+                data[k] = v
+
+        # Seed defaults from the geom's theme-resolved default_aes.
+        # R (guide-legend.R:404-408): per-break ``data`` already
+        # contains the geom's theme defaults; e.g. GeomDensity's
+        # ``fill = from_theme(fill %||% NA)`` resolves to NA, so the
+        # legend key is *transparent* — not black.  Only the
+        # ultra-fallbacks below kick in when the geom provides
+        # nothing (no layer/no default_aes).
+        for _dk, _dv in geom_default_aes.items():
+            data.setdefault(_dk, _dv)
+
+        data.setdefault("colour", None)   # R: NA (no border by default)
+        data.setdefault("fill", None)     # R: NA (no fill by default)
+        data.setdefault("size", 1.5)
+        data.setdefault("alpha", None)
+        data.setdefault("stroke", 0.5)
+        data.setdefault("shape", 19)
+        data.setdefault("linetype", 1)
+        data.setdefault("linewidth", 0.5)
+
+        # Call the draw_key function.
+        # draw_key_fn may be a bound method (from ggproto) or a plain function.
+        # Try plain call first; if TypeError (too many args from bound self),
+        # extract the underlying function.
+        try:
+            glyph = draw_key_fn(data, layer_params, key_size)
+        except TypeError:
+            # Likely a bound method — get the underlying function
+            fn = getattr(draw_key_fn, "__func__", draw_key_fn)
+            glyph = fn(data, layer_params, key_size)
+
+        # --- set_key_size (R: guide-legend.R:626-641) ---
+        # Compute glyph physical size from aesthetics: (size + linewidth) / 10
+        # This converts mm to cm, matching R's set_key_size().
+        glyph_w = getattr(glyph, "_width", None)
+        glyph_h = getattr(glyph, "_height", None)
+        if glyph_w is None or glyph_h is None:
+            _size = data.get("size", 0) or 0
+            _lwd = data.get("linewidth", 0) or 0
+            _stroke = data.get("stroke", 0) or 0
+            try:
+                _size = float(_size) if not (isinstance(_size, float) and np.isnan(_size)) else 0
+            except (TypeError, ValueError):
+                _size = 0
+            try:
+                _lwd = float(_lwd) if not (isinstance(_lwd, float) and np.isnan(_lwd)) else 0
+            except (TypeError, ValueError):
+                _lwd = 0
+            try:
+                _stroke = float(_stroke) if not (isinstance(_stroke, float) and np.isnan(_stroke)) else 0
+            except (TypeError, ValueError):
+                _stroke = 0
+            measured_cm = (_size + _lwd + _stroke) / 10.0
+            if glyph_w is None:
+                glyph_w = measured_cm
+            if glyph_h is None:
+                glyph_h = measured_cm
+
+        # Effective key size = max(default, measured glyph size)
+        eff_w = max(key_width_cm, glyph_w, 0)
+        eff_h = max(key_height_cm, glyph_h, 0)
+
+        # Wrap in a GTree with a justified viewport (R: build_decor lines 417-428)
+        vp = Viewport(
+            x=0.5, y=0.5, just="centre",
+            width=Unit(eff_w, "cm"),
+            height=Unit(eff_h, "cm"),
+        )
+        key_grob = GTree(
+            children=GList(key_bg, glyph),
+            vp=vp,
+            name=f"key-{i}",
+        )
+        # Store measured size on grob (R: attr(grob, "width") <- width)
+        key_grob._width = eff_w
+        key_grob._height = eff_h
+        key_glyphs.append(key_grob)
+
+    return key_glyphs
+
+
+# ---------------------------------------------------------------------------
+# build_legend_labels
+# ---------------------------------------------------------------------------
+
+def build_legend_labels(
+    entry: Dict[str, Any],
+    label_size: float = _DEFAULT_LABEL_SIZE,
+    label_colour: str = "grey20",
+    theme: Any = None,
+    text_position: str = "right",
+) -> List[Any]:
+    """Build text grobs for legend labels.
+
+    Mirrors ``GuideLegend$build_labels`` (guide-legend.R:433-450)::
+
+        element_grob(elements$text, label = lab,
+                     margin_x = TRUE, margin_y = TRUE)
+
+    That call produces a ``titleGrob`` whose ``grobWidth`` / ``grobHeight``
+    include the theme element's margins.  ``measure_grobs`` subsequently
+    uses those widths to size the label column, which is why R leaves
+    visible space between each key and its label.  A bare ``text_grob``
+    (no margin) shrinks the column to the glyph box and the label text
+    ends up kissing the key rectangle.
+
+    Parameters
+    ----------
+    entry : dict
+        Merged legend entry.
+    label_size : float
+        Font size in points (used only as a fallback when *theme* is
+        not provided).
+    label_colour : str
+        Font colour (fallback when *theme* is not provided).
+    theme : Theme or None
+        When given, labels are produced via
+        ``element_render(theme, "legend.text", ...)`` so that the
+        theme's ``legend.text`` element (fontsize, colour, hjust, vjust,
+        angle, margin) drives rendering — matching R exactly.
+
+    Returns
+    -------
+    list of grob
+        One ``_TitleGrob`` (or ``text_grob``) per label.
+    """
+    labels = entry.get("labels", [])
+    if not labels:
+        return [null_grob()]
+
+    # Preferred path: route through element_render so the resulting
+    # _TitleGrob carries legend.text's margin.
+    if theme is not None:
+        from ggplot2_py.theme_elements import (
+            element_render as _el_render,
+            calc_element as _calc,
+            Margin as _Margin,
+        )
+        # R (guide-legend.R:336-349 setup_elements):
+        #   margin <- position_margin(text_position, base_margin, gap)
+        #   elements$text <- calc_element("legend.text", ...with injected margin)
+        # gap = legend.key.spacing (5.5pt default).  The gap is added to
+        # the side of the margin OPPOSITE to ``text_position`` so that
+        # it sits between the key and the label.
+        text_el = _calc("legend.text", theme)
+        gap_pt = 0.0
+        try:
+            from grid_py import convert_width as _cw
+            spacing = _calc("legend.key.spacing.x", theme) or _calc(
+                "legend.key.spacing", theme
+            )
+            if spacing is not None:
+                gap_pt = float(np.sum(_cw(spacing, "pt", valueOnly=True)))
+        except Exception:
+            gap_pt = 5.5  # R default fallback (not a Python invention)
+
+        base_margin = getattr(text_el, "margin", None)
+        if isinstance(base_margin, _Margin):
+            mt, mr, mb, ml = (
+                float(base_margin.t), float(base_margin.r),
+                float(base_margin.b), float(base_margin.l),
+            )
+            mu = base_margin.unit_str
+            # Convert gap_pt to base_margin's unit if not pt
+            if mu != "pt":
+                from grid_py import Unit as _U, convert_width as _cw
+                gap_val = float(np.sum(_cw(_U(gap_pt, "pt"), mu, valueOnly=True)))
+            else:
+                gap_val = gap_pt
+        else:
+            mt = mr = mb = ml = 0.0
+            mu = "pt"
+            gap_val = gap_pt
+
+        # R position_margin(position, margin, gap):
+        #   right  → margin[4] (left)   += gap
+        #   left   → margin[2] (right)  += gap
+        #   top    → margin[3] (bottom) += gap
+        #   bottom → margin[1] (top)    += gap
+        if text_position == "right":
+            ml += gap_val
+        elif text_position == "left":
+            mr += gap_val
+        elif text_position == "top":
+            mb += gap_val
+        elif text_position == "bottom":
+            mt += gap_val
+
+        injected = _Margin(t=mt, r=mr, b=mb, l=ml, unit=mu)
+        return [
+            _el_render(
+                theme, "legend.text",
+                label=str(lab),
+                margin=injected,
+                margin_x=True, margin_y=True,
+            )
+            for lab in labels
+        ]
+
+    # Fallback: legacy plain text_grob (no margin).  Callers that don't
+    # thread the theme down will lose the key↔label gap, which is
+    # acceptable as a pre-theme-init emergency default.
+    grobs = []
+    for lab in labels:
+        grobs.append(text_grob(
+            label=str(lab),
+            x=0.0,
+            y=0.5,
+            just=("left", "centre"),
+            gp=Gpar(fontsize=label_size, col=label_colour),
+            name=f"guide.label.{lab}",
+        ))
+    return grobs
+
+
+# ---------------------------------------------------------------------------
+# measure_legend_grobs
+# ---------------------------------------------------------------------------
+
+def measure_legend_grobs(
+    decor: List[Any],
+    labels: List[Any],
+    n_breaks: int,
+    nrow: int,
+    ncol: int,
+    key_width_cm: float = _DEFAULT_KEY_WIDTH_CM,
+    key_height_cm: float = _DEFAULT_KEY_HEIGHT_CM,
+    spacing_x: float = _DEFAULT_SPACING_X_CM,
+    spacing_y: float = _DEFAULT_SPACING_Y_CM,
+    text_position: str = "right",
+    byrow: bool = False,
+    label_size: float = _DEFAULT_LABEL_SIZE,
+) -> Dict[str, List[float]]:
+    """Measure keys and labels, compute gtable widths/heights with spacing.
+
+    Mirrors ``GuideLegend$measure_grobs`` (guide-legend.R:452-501).
+
+    The returned widths/heights include interleaved spacing columns/rows
+    between key and label cells.  For ``text_position="right"`` (default)
+    the column pattern is: [key_w, label_w, gap, key_w, label_w, gap, ...]
+    (last gap stripped).
+
+    Parameters
+    ----------
+    decor : list of grob
+        Legend key glyphs.
+    labels : list of grob
+        Legend label grobs.
+    n_breaks : int
+        Number of legend breaks.
+    nrow, ncol : int
+        Legend grid dimensions.
+    key_width_cm, key_height_cm : float
+        Default key dimensions in cm.
+    spacing_x, spacing_y : float
+        Gap between columns / rows in cm.
+    text_position : str
+        Where labels go relative to keys: "right", "left", "top", "bottom".
+    byrow : bool
+        Fill matrix by row?
+
+    Returns
+    -------
+    dict
+        ``{"widths": [...], "heights": [...]}`` in cm.
+    """
+    # Pad to fill the nrow x ncol matrix
+    pad = nrow * ncol - n_breaks
+
+    # Key sizes: read dynamic _width/_height from decor grobs (set by set_key_size
+    # in build_legend_decor), then take column-max / row-max.
+    # Mirrors R's measure_legend_keys / get_key_size (guide-legend.R:595-624).
+    key_w_per_entry = []
+    key_h_per_entry = []
+    for i in range(n_breaks):
+        if i < len(decor):
+            kw = getattr(decor[i], "_width", key_width_cm) or key_width_cm
+            kh = getattr(decor[i], "_height", key_height_cm) or key_height_cm
+        else:
+            kw, kh = key_width_cm, key_height_cm
+        key_w_per_entry.append(max(kw, key_width_cm))
+        key_h_per_entry.append(max(kh, key_height_cm))
+    # Pad with zeros
+    key_w_per_entry.extend([0.0] * pad)
+    key_h_per_entry.extend([0.0] * pad)
+
+    # Arrange into matrix and take column-max / row-max
+    if byrow:
+        kw_matrix = _fill_matrix(key_w_per_entry, nrow, ncol, byrow=True)
+        kh_matrix = _fill_matrix(key_h_per_entry, nrow, ncol, byrow=True)
+    else:
+        kw_matrix = _fill_matrix(key_w_per_entry, nrow, ncol, byrow=False)
+        kh_matrix = _fill_matrix(key_h_per_entry, nrow, ncol, byrow=False)
+
+    key_widths = [max(kw_matrix[r][c] for r in range(nrow)) for c in range(ncol)]
+    key_heights = [max(kh_matrix[r][c] for c in range(ncol)) for r in range(nrow)]
+
+    # Label sizes: R (guide-legend.R:470-477) does:
+    #   label_widths  = apply(matrix(width_cm(grobs$labels),  ...), 2, max)
+    #   label_heights = apply(matrix(height_cm(grobs$labels), ...), 1, max)
+    # where ``grobs$labels`` are titleGrobs with margins, so ``width_cm``
+    # returns glyph_width + margin_left + margin_right.  When the label
+    # has no titleGrob wrapping, fall back to bare text width.
+    from grid_py import convert_width as _cw, convert_height as _ch, grob_width as _gw, grob_height as _gh
+    def _measure_label_w(g) -> float:
+        try:
+            u = _gw(g)
+            return float(np.sum(_cw(u, "cm", valueOnly=True)))
+        except Exception:
+            return 0.0
+    def _measure_label_h(g) -> float:
+        try:
+            u = _gh(g)
+            return float(np.sum(_ch(u, "cm", valueOnly=True)))
+        except Exception:
+            return 0.0
+
+    label_w_per_entry = []
+    label_h_per_entry = []
+    for lab_grob in labels:
+        w = _measure_label_w(lab_grob)
+        h = _measure_label_h(lab_grob)
+        if w <= 0:
+            # Last-resort fallback: measure the bare label text.
+            label_text = ""
+            if hasattr(lab_grob, "label"):
+                label_text = str(lab_grob.label)
+            elif hasattr(lab_grob, "_label"):
+                label_text = str(lab_grob._label)
+            w = (_text_width_cm(label_text, fontsize=label_size)
+                 if label_text else 0.3)
+        if h <= 0:
+            h = key_height_cm
+        label_w_per_entry.append(w)
+        label_h_per_entry.append(h)
+
+    # Pad to fill the nrow x ncol matrix
+    label_w_per_entry.extend([0.0] * pad)
+    label_h_per_entry.extend([0.0] * pad)
+
+    # Arrange into matrix and take column-max / row-max
+    if byrow:
+        # Fill by row
+        label_w_matrix = _fill_matrix(label_w_per_entry, nrow, ncol, byrow=True)
+        label_h_matrix = _fill_matrix(label_h_per_entry, nrow, ncol, byrow=True)
+    else:
+        label_w_matrix = _fill_matrix(label_w_per_entry, nrow, ncol, byrow=False)
+        label_h_matrix = _fill_matrix(label_h_per_entry, nrow, ncol, byrow=False)
+
+    label_widths = [max(label_w_matrix[r][c] for r in range(nrow))
+                    for c in range(ncol)]
+    label_heights = [max(label_h_matrix[r][c] for c in range(ncol))
+                     for r in range(nrow)]
+
+    # Interleave widths: [key_w, label_w, hgap] per column, strip last hgap
+    if text_position == "right":
+        width_lists = _interleave(key_widths, label_widths, spacing_x)
+    elif text_position == "left":
+        width_lists = _interleave(label_widths, key_widths, spacing_x)
+    else:
+        # top/bottom: labels and keys share same column
+        width_lists = _interleave(
+            [max(kw, lw) for kw, lw in zip(key_widths, label_widths)],
+            None, spacing_x)
+
+    # Interleave heights: [key_h, vgap] per row, strip last vgap
+    if text_position == "top":
+        height_lists = _interleave(label_heights, key_heights, spacing_y)
+    elif text_position == "bottom":
+        height_lists = _interleave(key_heights, label_heights, spacing_y)
+    else:
+        # left/right: labels and keys share same row
+        height_lists = _interleave(
+            [max(kh, lh) for kh, lh in zip(key_heights, label_heights)],
+            None, spacing_y)
+
+    return {"widths": width_lists, "heights": height_lists}
+
+
+# ---------------------------------------------------------------------------
+# arrange_legend_layout
+# ---------------------------------------------------------------------------
+
+def arrange_legend_layout(
+    n_breaks: int,
+    nrow: int,
+    ncol: int,
+    text_position: str = "right",
+    byrow: bool = False,
+) -> Dict[str, List[int]]:
+    """Compute cell positions for keys and labels in the legend gtable.
+
+    Mirrors ``GuideLegend$arrange_layout`` (guide-legend.R:503-531).
+
+    Parameters
+    ----------
+    n_breaks, nrow, ncol : int
+        Number of breaks and legend grid dimensions.
+    text_position : str
+        "right", "left", "top", or "bottom".
+    byrow : bool
+        Fill by row?
+
+    Returns
+    -------
+    dict
+        ``{"key_row": [...], "key_col": [...],
+           "label_row": [...], "label_col": [...]}``
+        1-based indices into the gtable.
+    """
+    break_seq = list(range(1, n_breaks + 1))
+
+    if byrow:
+        row = [math.ceil(b / ncol) for b in break_seq]
+        col = [((b - 1) % ncol) + 1 for b in break_seq]
+    else:
+        row = [((b - 1) % nrow) + 1 for b in break_seq]
+        col = [math.ceil(b / nrow) for b in break_seq]
+
+    # Account for spacing rows/cols in between keys (every other row/col is a gap)
+    key_row = [r * 2 - 1 for r in row]
+    key_col = [c * 2 - 1 for c in col]
+
+    # Offset for key-label gaps depending on text_position
+    if text_position == "right":
+        key_col = [kc + (c - 1) for kc, c in zip(key_col, col)]
+        lab_col = [kc + 1 for kc in key_col]
+        lab_row = list(key_row)
+    elif text_position == "left":
+        key_col = [kc + c for kc, c in zip(key_col, col)]
+        lab_col = [kc - 1 for kc in key_col]
+        lab_row = list(key_row)
+    elif text_position == "top":
+        key_row = [kr + r for kr, r in zip(key_row, row)]
+        lab_row = [kr - 1 for kr in key_row]
+        lab_col = list(key_col)
+    elif text_position == "bottom":
+        key_row = [kr + (r - 1) for kr, r in zip(key_row, row)]
+        lab_row = [kr + 1 for kr in key_row]
+        lab_col = list(key_col)
+    else:
+        # Default to "right"
+        key_col = [kc + (c - 1) for kc, c in zip(key_col, col)]
+        lab_col = [kc + 1 for kc in key_col]
+        lab_row = list(key_row)
+
+    return {
+        "key_row": key_row,
+        "key_col": key_col,
+        "label_row": lab_row,
+        "label_col": lab_col,
+    }
+
+
+# ---------------------------------------------------------------------------
+# assemble_legend
+# ---------------------------------------------------------------------------
+
+def assemble_legend(
+    decor: List[Any],
+    labels: List[Any],
+    title_grob: Any,
+    layout: Dict[str, List[int]],
+    sizes: Dict[str, List[float]],
+    title_position: str = "top",
+    padding_cm: float = _DEFAULT_PADDING_CM,
+    bg_colour: Optional[str] = "white",
+) -> Gtable:
+    """Assemble a complete legend as a Gtable.
+
+    Mirrors ``GuideLegend$assemble_drawing`` (guide-legend.R:533-591)
+    plus ``Guide$add_title`` (guide-.R:924-951).
+
+    Parameters
+    ----------
+    decor : list of grob
+        Key glyphs from :func:`build_legend_decor`.
+    labels : list of grob
+        Label grobs from :func:`build_legend_labels`.
+    title_grob : grob
+        Legend title grob.
+    layout : dict
+        Cell positions from :func:`arrange_legend_layout`.
+    sizes : dict
+        Widths/heights from :func:`measure_legend_grobs`.
+    title_position : str
+        Where to place the title: "top", "right", "bottom", "left".
+    padding_cm : float
+        Padding around the legend in cm.
+    bg_colour : str or None
+        Background fill colour.
+
+    Returns
+    -------
+    Gtable
+        Self-contained legend gtable.
+    """
+    widths = Unit(sizes["widths"], "cm")
+    heights = Unit(sizes["heights"], "cm")
+
+    gt = Gtable(widths=widths, heights=heights, name="legend")
+
+    # Add key glyphs
+    if decor:
+        for idx, grob in enumerate(decor):
+            kr = layout["key_row"][idx]
+            kc = layout["key_col"][idx]
+            gt = gtable_add_grob(
+                gt, grob,
+                t=kr, l=kc, b=kr, r=kc,
+                clip="off",
+                name=f"key-{kr}-{kc}",
+            )
+
+    # Add labels
+    if labels:
+        for idx, grob in enumerate(labels):
+            lr = layout["label_row"][idx]
+            lc = layout["label_col"][idx]
+            gt = gtable_add_grob(
+                gt, grob,
+                t=lr, l=lc, b=lr, r=lc,
+                clip="off",
+                name=f"label-{lr}-{lc}",
+            )
+
+    # Add title  (mirrors Guide$add_title, guide-.R:924-951)
+    gt = add_legend_title(gt, title_grob, title_position)
+
+    # Add padding  (mirrors gtable_add_padding)
+    pad = Unit([padding_cm] * 4, "cm")
+    gt = gtable_add_padding(gt, pad)
+
+    # Add background
+    if bg_colour is not None:
+        bg = rect_grob(
+            gp=Gpar(fill=bg_colour, col="grey85", lwd=0.5),
+            name="legend.background",
+        )
+        nrow_gt = gt.nrow
+        ncol_gt = gt.ncol
+        gt = gtable_add_grob(
+            gt, bg,
+            t=1, l=1, b=nrow_gt, r=ncol_gt,
+            z=-math.inf,
+            clip="off",
+            name="background",
+        )
+
+    return gt
+
+
+# ---------------------------------------------------------------------------
+# add_legend_title
+# ---------------------------------------------------------------------------
+
+def add_legend_title(
+    gt: Gtable,
+    title_grob: Any,
+    position: str = "top",
+    hjust: float = 0.0,
+    vjust: float = 0.5,
+) -> Gtable:
+    """Add a title to a legend gtable.
+
+    When the title's rendered size exceeds the existing table along the
+    long axis, padding columns (rows) are inserted on one or both sides
+    so the title stays within the legend background.  ``hjust`` / ``vjust``
+    control how the excess splits between the two sides.
+
+    Parameters
+    ----------
+    gt : Gtable
+        Legend gtable under construction.
+    title_grob : grob
+        Title grob.
+    position : str
+        "top", "right", "bottom", or "left".
+    hjust, vjust : float
+        Title justification (0 = left/top, 1 = right/bottom).
+
+    Returns
+    -------
+    Gtable
+        With title added.
+    """
+    if title_grob is None:
+        return gt
+
+    from grid_py import (
+        grob_height as _gh,
+        grob_width as _gw,
+        convert_width as _cw,
+        convert_height as _ch,
+    )
+
+    def _cm_total(u: Any, axis: str) -> float:
+        """Resolve a (possibly composite) unit to a total cm value."""
+        try:
+            fn = _cw if axis == "x" else _ch
+            arr = fn(u, "cm", valueOnly=True)
+            return float(np.sum(arr))
+        except Exception:
+            return 0.0
+
+    if position == "top":
+        gt = gtable_add_rows(gt, _gh(title_grob), pos=0)
+        gt = gtable_add_grob(
+            gt, title_grob,
+            t=1, l=1, r=gt.ncol, b=1,
+            z=-math.inf, clip="off", name="title",
+        )
+    elif position == "bottom":
+        gt = gtable_add_rows(gt, _gh(title_grob), pos=-1)
+        gt = gtable_add_grob(
+            gt, title_grob,
+            t=gt.nrow, l=1, r=gt.ncol, b=gt.nrow,
+            z=-math.inf, clip="off", name="title",
+        )
+    elif position == "left":
+        gt = gtable_add_cols(gt, _gw(title_grob), pos=0)
+        gt = gtable_add_grob(
+            gt, title_grob,
+            t=1, l=1, r=1, b=gt.nrow,
+            z=-math.inf, clip="off", name="title",
+        )
+    elif position == "right":
+        gt = gtable_add_cols(gt, _gw(title_grob), pos=-1)
+        gt = gtable_add_grob(
+            gt, title_grob,
+            t=1, l=gt.ncol, r=gt.ncol, b=gt.nrow,
+            z=-math.inf, clip="off", name="title",
+        )
+
+    # If the title overflows the existing table along its orientation axis,
+    # pad both sides so it stays inside the legend background.  The split
+    # between the two pad cells is controlled by hjust / vjust.
+    if position in ("top", "bottom"):
+        title_width_cm = _cm_total(_gw(title_grob), "x")
+        table_width_cm = sum(_cm_total(Unit(w, "cm") if isinstance(w, (int, float)) else w, "x")
+                             for w in gt.widths) if hasattr(gt, "widths") else _cm_total(gt.widths, "x")
+        extra = max(0.0, title_width_cm - table_width_cm)
+        if extra > 1e-6:
+            left_pad = hjust * extra
+            right_pad = (1.0 - hjust) * extra
+            if left_pad > 1e-6:
+                gt = gtable_add_cols(gt, Unit(left_pad, "cm"), pos=0)
+            if right_pad > 1e-6:
+                gt = gtable_add_cols(gt, Unit(right_pad, "cm"), pos=-1)
+    else:
+        title_height_cm = _cm_total(_gh(title_grob), "y")
+        table_height_cm = sum(_cm_total(Unit(h, "cm") if isinstance(h, (int, float)) else h, "y")
+                              for h in gt.heights) if hasattr(gt, "heights") else _cm_total(gt.heights, "y")
+        extra = max(0.0, title_height_cm - table_height_cm)
+        if extra > 1e-6:
+            top_pad = vjust * extra
+            bottom_pad = (1.0 - vjust) * extra
+            if top_pad > 1e-6:
+                gt = gtable_add_rows(gt, Unit(top_pad, "cm"), pos=0)
+            if bottom_pad > 1e-6:
+                gt = gtable_add_rows(gt, Unit(bottom_pad, "cm"), pos=-1)
+
+    return gt
+
+
+# ---------------------------------------------------------------------------
+# package_legend_box
+# ---------------------------------------------------------------------------
+
+def package_legend_box(
+    legends: List[Gtable],
+    position: str = "right",
+    spacing_cm: float = 0.2,
+) -> Gtable:
+    """Combine multiple legends into a single guide-box Gtable.
+
+    Mirrors ``Guides$package_box`` (guides-.R:592-757).
+
+    For ``position="right"`` or ``"left"`` (vertical), legends are stacked
+    in a ``gtable_col``.  For ``"top"`` / ``"bottom"`` (horizontal), they
+    are placed side by side in a ``gtable_row``.
+
+    Parameters
+    ----------
+    legends : list of Gtable
+        Individual legend gtables.
+    position : str
+        Legend box position relative to the plot.
+    spacing_cm : float
+        Spacing between legends in cm.
+
+    Returns
+    -------
+    Gtable
+        Combined guide-box.
+    """
+    if not legends:
+        return Gtable(name="guide-box")
+
+    if len(legends) == 1:
+        legends[0].name = "guide-box"
+        return legends[0]
+
+    direction = "horizontal" if position in ("top", "bottom") else "vertical"
+
+    if direction == "vertical":
+        # Stack vertically
+        # Compute common width = max of all legends
+        max_width_cm = 0.0
+        heights_cm = []
+        for lg in legends:
+            w = _gtable_total_cm(lg.widths)
+            h = _gtable_total_cm(lg.heights)
+            max_width_cm = max(max_width_cm, w)
+            heights_cm.append(h)
+
+        guides = gtable_col(
+            name="guides",
+            grobs=legends,
+            width=Unit(max_width_cm, "cm"),
+            heights=Unit(heights_cm, "cm"),
+        )
+        guides = gtable_add_row_space(guides, Unit(spacing_cm, "cm"))
+    else:
+        # Place side by side
+        max_height_cm = 0.0
+        widths_cm = []
+        for lg in legends:
+            w = _gtable_total_cm(lg.widths)
+            h = _gtable_total_cm(lg.heights)
+            max_height_cm = max(max_height_cm, h)
+            widths_cm.append(w)
+
+        from gtable_py import gtable_row, gtable_add_col_space
+        guides = gtable_row(
+            name="guides",
+            grobs=legends,
+            height=Unit(max_height_cm, "cm"),
+            widths=Unit(widths_cm, "cm"),
+        )
+        guides = gtable_add_col_space(guides, Unit(spacing_cm, "cm"))
+
+    guides.name = "guide-box"
+    return guides
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+def _fill_matrix(
+    values: List[float], nrow: int, ncol: int, byrow: bool = False
+) -> List[List[float]]:
+    """Fill a flat list into a nrow x ncol matrix.
+
+    Parameters
+    ----------
+    values : list of float
+        Flat values (length >= nrow * ncol).
+    nrow, ncol : int
+        Matrix dimensions.
+    byrow : bool
+        Fill by row if True, else by column (R default).
+
+    Returns
+    -------
+    list of list of float
+        ``matrix[row][col]``.
+    """
+    matrix = [[0.0] * ncol for _ in range(nrow)]
+    for idx, val in enumerate(values[: nrow * ncol]):
+        if byrow:
+            r = idx // ncol
+            c = idx % ncol
+        else:
+            r = idx % nrow
+            c = idx // nrow
+        matrix[r][c] = val
+    return matrix
+
+
+def _interleave(
+    a: List[float],
+    b: Optional[List[float]],
+    gap: float,
+) -> List[float]:
+    """Interleave two lists with a gap, stripping the trailing gap.
+
+    If *b* is ``None``, just interleave *a* with *gap*.
+
+    Examples
+    --------
+    >>> _interleave([1, 2], [3, 4], 0.1)
+    [1, 3, 0.1, 2, 4, 0.1]  # then strip last → [1, 3, 0.1, 2, 4]
+    """
+    result: List[float] = []
+    if b is not None:
+        for i in range(len(a)):
+            result.append(a[i])
+            result.append(b[i] if i < len(b) else 0.0)
+            result.append(gap)
+    else:
+        for i in range(len(a)):
+            result.append(a[i])
+            result.append(gap)
+
+    # Strip trailing gap
+    if result and result[-1] == gap:
+        result = result[:-1]
+    return result
+
+
+def _gtable_total_cm(unit: Optional[Unit]) -> float:
+    """Sum a Unit vector, returning cm as a float.
+
+    Falls back to simple sum of values for "cm" units; returns a
+    reasonable estimate for mixed/null units.
+    """
+    if unit is None or len(unit) == 0:
+        return 0.0
+    total = 0.0
+    for i in range(len(unit)):
+        part = unit[i: i + 1]
+        vals = part.values if hasattr(part, "values") else [0.0]
+        units = part.units if hasattr(part, "units") else ["cm"]
+        v = vals[0] if vals else 0.0
+        u = units[0] if units else "cm"
+        if u == "cm":
+            total += v
+        elif u == "mm":
+            total += v / 10.0
+        elif u == "inches":
+            total += v * 2.54
+        elif u == "pt" or u == "points":
+            total += v / 72.27 * 2.54
+        else:
+            # null, npc, etc. — use the numeric value as a rough estimate
+            total += v
+    return total