codefig 0.17.0__py3-none-any.whl

codefig/legend.py

@@ -0,0 +1,483 @@
+"""Legends: keys for fills, hatches, borders and edge styles.
+
+``Legend()`` with no entries auto-collects every ``legend="…"`` label in its
+panel: nodes (their fill / pattern / border), edges and forks (colour, dash,
+arrowhead) and Matrix ``legend={colour: label}`` maps. Pass ``entries=[Key(…)]``
+to list keys by hand (or ``auto=False`` to use only those). A Legend is an
+ordinary node: put it in a Row/Col or ``place()`` it next to anything.
+"""
+
+from __future__ import annotations
+
+from typing import Any, List, Optional, Sequence, Tuple
+
+from .node import Node
+from .styles import themed
+from .textutil import measure_text
+
+KINDS = ("box", "line", "arrow", "dot", "mark", "icon")
+
+
+
+class Hatch:
+    """Diagonal hatching pattern for ``pattern=`` on Box / Group / Key.
+
+    angle: degrees (45 = "/", -45 = "\\", 0 = horizontal, 90 = vertical);
+    ``cross=True`` adds the perpendicular set.
+    """
+
+    def __init__(self, *, angle: float = 45.0, spacing: Optional[float] = None,
+                 color: str = "#555555", width: Optional[float] = None, opacity: float = 1.0,
+                 cross: bool = False) -> None:
+        self.angle = float(angle)
+        self._spacing = None if spacing is None else float(spacing)
+        self.color = color
+        self._width = None if width is None else float(width)
+        self.opacity = float(opacity)
+        self.cross = bool(cross)
+
+    @property
+    def spacing(self) -> float:
+        """Line pitch (default ``theme.hatch_spacing``: 5 px classic, 2.8 pt paper)."""
+        if self._spacing is not None:
+            return self._spacing
+        from .styles import current_theme
+
+        return float(current_theme().hatch_spacing)
+
+    @spacing.setter
+    def spacing(self, v: Optional[float]) -> None:
+        self._spacing = None if v is None else float(v)
+
+    @property
+    def width(self) -> float:
+        """Line width (default ``theme.hatch_width``: 0.8 px classic, 0.5 pt paper)."""
+        if self._width is not None:
+            return self._width
+        from .styles import current_theme
+
+        return float(current_theme().hatch_width)
+
+    @width.setter
+    def width(self, v: Optional[float]) -> None:
+        self._width = None if v is None else float(v)
+
+    _seq = 0
+
+    def paint(self, buf: List[str], x: float, y: float, w: float, h: float) -> None:
+        import math
+
+        Hatch._seq += 1
+        cid = f"cf-hatch-{Hatch._seq}"
+        buf.append(f'<defs><clipPath id="{cid}"><rect x="{x:.2f}" y="{y:.2f}" width="{w:.2f}" '
+                   f'height="{h:.2f}"/></clipPath></defs>')
+        op = f' stroke-opacity="{self.opacity:.3g}"' if self.opacity < 1 else ""
+        segs = []
+        cx, cy = x + w / 2, y + h / 2
+        R = math.hypot(w, h) / 2 + self.spacing
+        for ang in ([self.angle, self.angle + 90] if self.cross else [self.angle]):
+            t = math.radians(-ang)
+            dx, dy = math.cos(t), math.sin(t)  # line direction
+            nx, ny = -dy, dx  # normal
+            n = int(R / self.spacing) + 1
+            for k in range(-n, n + 1):
+                ox, oy = cx + nx * k * self.spacing, cy + ny * k * self.spacing
+                segs.append(f"M {ox - dx * R:.2f},{oy - dy * R:.2f} L {ox + dx * R:.2f},{oy + dy * R:.2f}")
+        buf.append(f'<path d="{" ".join(segs)}" stroke="{self.color}" stroke-width="{self.width:.3g}"'
+                   f' fill="none" clip-path="url(#{cid})"{op} />')
+
+
+class Key:
+    """One legend entry.
+
+    kind: one of ``"box"`` (fill / pattern / border / hatch), ``"line"`` or ``"arrow"``
+    (edge ``color=``, ``style="dashed"|"dotted"|…``, ``width=``, ``head=`` / ``tail=``),
+    ``"dot"``, ``"mark"`` (``mark="check"|"cross"|…`` glyph) or ``"icon"`` (``icon=``).
+    Unspecified kind is inferred (``style=`` / ``head=`` → line / arrow, ``mark=`` →
+    mark, ``icon=`` → icon, else box). Labels may contain ``"\n"``: the row grows.
+    Example: ``Key("copy", kind="arrow", color="#0072B2", style="dashed")``.
+    """
+
+    def __init__(self, label: str, *, kind: Optional[str] = None, fill: Optional[str] = None,
+                 stroke: Optional[str] = None, border: Any = None, pattern: Any = None,
+                 hatch: Any = None, color: Optional[str] = None, style: Any = None,
+                 width: Optional[float] = None, head: Any = None, tail: Any = None,
+                 hollow: Optional[bool] = None, mark: Optional[str] = None,
+                 radius: float = 1.5, icon: Any = None) -> None:
+        if hatch is not None and pattern is None:
+            pattern = hatch if not isinstance(hatch, (bool, int, float, str)) else Hatch(
+                angle=45.0 if hatch in (True, "/", "diag") else (
+                    -45.0 if hatch == "\\" else float(hatch) if isinstance(hatch, (int, float))
+                    else 45.0))
+        if icon is not None and not hasattr(icon, "paint"):
+            from .icon import as_icon
+
+            icon = as_icon(icon, color=color)
+        if kind is None:
+            if icon is not None:
+                kind = "icon"
+            elif mark is not None:
+                kind = "mark"
+            elif head is not None or tail is not None:
+                kind = "arrow"
+            elif style is not None and fill is None and pattern is None:
+                kind = "line"
+            else:
+                kind = "box"
+        if kind not in KINDS:
+            raise ValueError(f"Key kind must be one of {KINDS}, got {kind!r}")
+        self.label = label
+        self.kind = kind
+        self.fill = fill
+        self.stroke = stroke
+        self.border = border
+        self.pattern = pattern
+        self.color = color
+        self.style = style
+        self.width = width
+        self.head = head
+        self.tail = tail
+        self.hollow = hollow
+        self.mark = mark
+        self.radius = radius
+        self.icon = icon
+
+    def _sig(self) -> Tuple:
+        return (self.label, self.kind, self.fill, self.color, str(self.style), str(self.border),
+                type(self.pattern).__name__, str(self.head), getattr(self.icon, "name", None))
+
+    @classmethod
+    def from_node(cls, node: Any, label: str) -> "Key":
+        fill = getattr(node, "fill", None)
+        stroke = getattr(node, "stroke", None)
+        return cls(label, kind="box", fill=fill if fill not in (None, "none") else "#ffffff",
+                   stroke=stroke, border=getattr(node, "border", None),
+                   pattern=getattr(node, "pattern", None))
+
+    @classmethod
+    def from_edge(cls, edge: Any, label: str) -> "Key":
+        st = edge.resolved()
+        head = st.end_head.shape if st.end_head is not None and st.end_head.visible else "none"
+        return cls(label, kind="arrow" if head != "none" else "line", color=st.color,
+                   style=st.dash or st.style, width=st.width, head=head,
+                   hollow=st.end_head.hollow if st.end_head is not None else None)
+
+
+def collect_keys(root: Any) -> List[Key]:
+    """Keys from every ``legend=`` in ``root``'s tree (nodes, Matrix maps, edges, forks)."""
+    from .constraints import walk
+    from .edges import Diagram, Edge, Fork
+
+    keys: List[Key] = []
+    seen = set()
+
+    def add(k: Key) -> None:
+        if k.label in seen:
+            return
+        seen.add(k.label)
+        keys.append(k)
+
+    for n in walk(root):
+        if isinstance(n, Legend):
+            continue
+        if hasattr(n, "legend_entries") and getattr(n, "legend", None):
+            for k in n.legend_entries():
+                add(k)
+        elif isinstance(getattr(n, "legend", None), str) and not isinstance(n, Diagram):
+            add(n.legend_key(n.legend) if hasattr(n, "legend_key") else Key.from_node(n, n.legend))
+        elif getattr(n, "category", None) is not None and not isinstance(n, Diagram):
+            add(Key.from_node(n, str(n.category)))
+        if isinstance(n, Diagram):
+            for e in n.edges:
+                lab = getattr(e, "legend", None)
+                if not lab:
+                    continue
+                if isinstance(e, Edge):
+                    add(Key.from_edge(e, lab))
+                elif isinstance(e, Fork):
+                    probe = Edge(e._node(e.hub), e._node(e.leaves[0]), **e._style_kw())
+                    add(Key.from_edge(probe, lab))
+    order = {"box": 0, "icon": 1, "mark": 1, "dot": 1, "line": 2, "arrow": 2}
+    return sorted(keys, key=lambda k: order[k.kind])
+
+
+CORNERS = ("top-right", "top-left", "bottom-right", "bottom-left")
+
+
+class Legend(Node):
+    """Legend box: swatch + label per key, in ``cols`` columns (or ``direction='row'``).
+
+    entries: explicit keys (``Key`` or ``(label, fill)`` tuples); ``auto`` (default: only
+    when no entries are given; ``auto=True`` to combine) collects ``legend=`` labels and
+    ``category=`` names from ``source`` (default: the panel it sits in; a node; or
+    ``source="figure"`` for one shared legend over every panel, v0.14.0).
+    ``corner`` places the legend inside ``of`` (default: panel content), inset by
+    ``inset`` points. ``auto`` chooses a clear corner. ``overlay=True`` excludes
+    corner legends from natural sizing; None preserves ordinary layout.
+    Swatch size, gaps and padding default to the theme (20×11 px classic).
+    """
+
+    swatch = themed((20.0, 11.0))
+    gap = themed(6.0)
+    item_gap = themed(12.0)
+    stroke_width = themed(0.8, "SW")
+    box_pad = themed(5.0)
+    row_gap = themed(3.0)
+
+    def __init__(self, entries: Optional[Sequence[Any]] = None, *, auto: Optional[bool] = None,
+                 title: Optional[str] = None, cols: Optional[int] = None,
+                 direction: str = "col", font_size: Optional[float] = None,
+                 swatch: Optional[Tuple[float, float]] = None, gap: Optional[float] = None,
+                 item_gap: Optional[float] = None, fill: str = "none",
+                 stroke: Optional[str] = None, stroke_width: Optional[float] = None,
+                 pad: Optional[float] = None, source: Any = None,
+                 corner: Optional[str] = None, of: Any = None,
+                 inset: float = 6.0, overlay: bool = True,
+                 **kwargs: Any) -> None:
+        if corner not in (None, "auto", *CORNERS):
+            raise ValueError(f"Legend corner must be None, auto, {', '.join(CORNERS)}; got {corner!r}")
+        self.corner, self.of, self.inset, self.overlay = corner, of, float(inset), overlay
+        if direction not in ("col", "row"):
+            raise ValueError("Legend direction must be col|row")
+        super().__init__(**kwargs)
+        self.entries = [self._as_key(e) for e in (entries or [])]
+        # auto-collect unless keys were given explicitly (pass auto=True for both)
+        self.auto = (entries is None) if auto is None else bool(auto)
+        self.title = title
+        self.cols = cols
+        self.direction = direction
+        self.font_size = font_size
+        self.swatch = None if swatch is None else (float(swatch[0]), float(swatch[1]))
+        self.gap = gap
+        self.item_gap = item_gap
+        self.fill = fill
+        self.stroke = stroke
+        self.stroke_width = stroke_width
+        self.box_pad = pad
+        if isinstance(source, str) and source != "figure":
+            raise ValueError('Legend source= must be a node, a list of nodes or "figure"')
+        self.source = source
+        self._collected: List[Key] = []
+
+    @staticmethod
+    def _as_key(e: Any) -> Key:
+        if isinstance(e, Key):
+            return e
+        if isinstance(e, (tuple, list)) and len(e) == 2:
+            return Key(str(e[0]), fill=e[1])
+        raise TypeError("Legend entries must be Key or (label, fill) pairs")
+
+    def collect(self, root: Any) -> None:
+        """Gather auto keys from ``source`` (or ``root``); called before measuring."""
+        if not self.auto:
+            return
+        src = self.source if self.source is not None and not isinstance(self.source, str) else root
+        if isinstance(src, (list, tuple)):
+            keys, seen = [], set()
+            for r in src:
+                for k in collect_keys(r):
+                    if k.label not in seen:
+                        seen.add(k.label)
+                        keys.append(k)
+        else:
+            keys = collect_keys(src)
+        have = {k.label for k in self.entries}
+        new = [k for k in keys if k.label not in have]
+        if [k._sig() for k in new] != [k._sig() for k in self._collected]:
+            self._collected = new
+            self._measured = None
+
+    def keys(self) -> List[Key]:
+        return list(self.entries) + list(self._collected)
+
+    def _fs(self) -> float:
+        return self.font_size if self.font_size is not None else self.theme.font_size * 0.85
+
+    def _ncols(self) -> int:
+        n = max(1, len(self.keys()))
+        if self.cols:
+            return max(1, min(int(self.cols), n))
+        return n if self.direction == "row" else 1
+
+    def _cells(self) -> Tuple[List[float], float, float]:
+        col_w, rows_h, title_h = self._cells_rows()
+        return col_w, max(rows_h, default=0.0), title_h
+
+    def _cells_rows(self) -> Tuple[List[float], List[float], float]:
+        """Column widths, per-row heights (v0.13.0: a ``"\n"`` label makes its row
+        taller instead of running into the next one) and the title height."""
+        fs = self._fs()
+        keys = self.keys()
+        nc = self._ncols()
+        sw, sh = self.swatch
+        col_w = [0.0] * nc
+        nrows = max(1, (len(keys) + nc - 1) // nc)
+        rows_h = [max(sh, fs * 1.25)] * nrows
+        for i, k in enumerate(keys):
+            tw, _ = measure_text(k.label, fs)
+            r, c = divmod(i, nc)
+            col_w[c] = max(col_w[c], sw + self.gap + tw)
+            n_lines = str(k.label).count("\n") + 1
+            rows_h[r] = max(rows_h[r], fs * 1.25 * n_lines)
+        title_h = measure_text(self.title, fs, weight="bold")[1] + self.row_gap if self.title else 0.0
+        return col_w, rows_h, title_h
+
+    def _measure(self) -> Tuple[float, float]:
+        keys = self.keys()
+        col_w, rows_h, title_h = self._cells_rows()
+        nc = self._ncols()
+        rows = len(rows_h)
+        w = sum(col_w) + self.item_gap * (nc - 1)
+        if self.title:
+            w = max(w, measure_text(self.title, self._fs(), weight="bold")[0])
+        h = title_h + sum(rows_h) + (rows - 1) * self.row_gap
+        framed = self.fill != "none" or self.stroke not in (None, "none")
+        p = self.box_pad if framed else 0.0
+        return w + 2 * p, h + 2 * p
+
+    def draw(self, buf: List[str], ox: float = 0.0, oy: float = 0.0) -> None:
+        from .render_svg import draw_rect, draw_text
+
+        g = self.geom
+        x0, y0 = g.x + ox, g.y + oy
+        framed = self.fill != "none" or self.stroke not in (None, "none")
+        if framed:
+            draw_rect(buf, x0, y0, g.w, g.h, fill=self.fill, stroke=self.stroke or "none",
+                      stroke_width=self.stroke_width if self.stroke not in (None, "none") else 0,
+                      radius=self.theme.L(2), dasharray=self._dash(self.stroke_width))
+            x0 += self.box_pad
+            y0 += self.box_pad
+        fs = self._fs()
+        col_w, rows_h, title_h = self._cells_rows()
+        nc = self._ncols()
+        if self.title:
+            draw_text(buf, self.title, x0, y0 + fs, font_size=fs, weight="bold")
+        sw, sh = self.swatch
+        for i, k in enumerate(self.keys()):
+            r, c = divmod(i, nc)
+            x = x0 + sum(col_w[:c]) + self.item_gap * c
+            y = y0 + title_h + sum(rows_h[:r]) + r * self.row_gap
+            cy = y + rows_h[r] / 2
+            n_lines = str(k.label).count("\n") + 1
+            draw_key(buf, k, x, cy - sh / 2, sw, sh, theme=self.theme)
+            draw_text(buf, k.label, x + sw + self.gap,
+                      cy + fs * 0.35 - (n_lines - 1) * fs * 1.25 / 2, font_size=fs)
+
+
+def draw_key(buf: List[str], k: Key, x: float, y: float, w: float, h: float, *, theme: Any) -> None:
+    """Swatch for one key in box (x, y, w, h)."""
+    from .primitives import _paint_node_pattern
+    from .render_svg import angle_of, draw_circle, draw_head, draw_line, draw_mark, draw_rect
+    from .styles import border_dasharray, resolve_edge_style
+
+    if k.kind == "box":
+        stroke = k.stroke
+        if stroke is None:
+            stroke = "#555555" if k.border not in (None, "none") else theme.stroke
+        sw = theme.SW(1.0)
+        rad = theme.L(k.radius)
+        draw_rect(buf, x, y, w, h, fill=k.fill or "#ffffff", stroke=stroke, stroke_width=sw,
+                  radius=rad, dasharray=border_dasharray(k.border, sw) if k.border else None)
+        if k.pattern is not None:
+            _paint_node_pattern(buf, k.pattern, x + 0.5, y + 0.5, w - 1, h - 1)
+            draw_rect(buf, x, y, w, h, fill="none", stroke=stroke, stroke_width=sw, radius=rad,
+                      dasharray=border_dasharray(k.border, sw) if k.border else None)
+    elif k.kind == "dot":
+        r = min(w, h) / 2
+        draw_circle(buf, x + w / 2, y + h / 2, r * 0.8, fill=k.fill or k.color or theme.stroke)
+    elif k.kind == "icon":
+        s = min(w, h + theme.L(4))
+        k.icon.paint(buf, x + (w - s) / 2, y + (h - s) / 2, s, s, color=k.color)
+    elif k.kind == "mark":
+        draw_mark(buf, k.mark or "check", x + w / 2, y + h / 2, min(w, h), color=k.color or theme.stroke)
+    else:
+        st = resolve_edge_style(theme, color=k.color, width=k.width, style=k.style,
+                                head=(k.head if k.kind == "arrow" else "none"), tail=k.tail,
+                                hollow=k.hollow)
+        cy = y + h / 2
+        eh = st.end_head
+        sh = st.start_head
+        x1, x2 = x, x + w
+        sb_e = eh.setback(st.width) if eh is not None and eh.visible else 0.0
+        sb_s = sh.setback(st.width) if sh is not None and sh.visible else 0.0
+        draw_line(buf, x1 + sb_s, cy, x2 - sb_e, cy, stroke=st.color, stroke_width=st.width,
+                  dasharray=st.dasharray(), opacity=st.opacity)
+        draw_head(buf, x2, cy, angle_of(x1, cy, x2, cy), eh, color=st.color, opacity=st.opacity,
+                  stroke_width=st.width)
+        draw_head(buf, x1, cy, angle_of(x2, cy, x1, cy), sh, color=st.color, opacity=st.opacity,
+                  stroke_width=st.width)
+
+
+__all__ = ["Hatch", "Key", "Legend", "collect_keys", "draw_key"]
+
+
+def hatch_pattern(spec: Optional[str]) -> Optional["Hatch"]:
+    """Matplotlib-style hatch spec → pattern: ``"////"`` (45°), ``"\\\\"`` (−45°),
+    ``"xxxx"`` (cross), ``"----"`` (horizontal), ``"||||"`` (vertical), ``"...."`` (dots)."""
+    if not spec:
+        return None
+    c = spec[0]
+    if c == "/":
+        return Hatch(angle=45, color="#444444")
+    if c == "\\":
+        return Hatch(angle=-45, color="#444444")
+    if c in "xX+":
+        return Hatch(angle=45, cross=True, color="#444444")
+    if c == "-":
+        return Hatch(angle=0, color="#444444")
+    if c == "|":
+        return Hatch(angle=90, color="#444444")
+    if c in ".o":
+        from .primitives import DotGrid
+        from .styles import current_theme
+
+        L = current_theme().L
+        return DotGrid(pitch=L(6.0), r=L(0.9), color="#444444", opacity=0.8)
+    raise ValueError(f"unknown hatch spec {spec!r}")
+
+
+def position_corners(panel: Any) -> None:
+    """Place corner legends after routing, retaining collision scores for lint."""
+    from .constraints import walk
+    from .edges import Diagram
+    from .figure import LayoutError
+    import warnings
+
+    legends = panel.__dict__.get('_corner_legends', [])
+    if not legends:
+        return
+    nodes = list(walk(panel.content))
+    obstacles = []
+    for n in nodes:
+        if not n.children():
+            g = n.geom
+            obstacles.append((g.x, g.y, g.w, g.h))
+        if isinstance(n, Diagram):
+            for _, points in n._routed()[0]:
+                for a, b in zip(points, points[1:]):
+                    obstacles.append((min(a[0], b[0]) - .5, min(a[1], b[1]) - .5,
+                                      abs(a[0]-b[0]) + 1, abs(a[1]-b[1]) + 1))
+    for legend in legends:
+        g = (legend.of or panel.content).geom
+        w, h = legend.measure()
+        inset = legend.inset
+        if w + 2*inset > g.w or h + 2*inset > g.h:
+            raise LayoutError('Legend exceeds reference area; shorten labels, shrink the legend or use external placement')
+        candidates = {}
+        for corner in CORNERS:
+            x = g.x + inset if corner.endswith('left') else g.x + g.w - inset - w
+            y = g.y + inset if corner.startswith('top') else g.y + g.h - inset - h
+            score = sum(max(0, min(x+w, a+c)-max(x,a))*max(0,min(y+h,b+d)-max(y,b))
+                        for a,b,c,d in obstacles)
+            candidates[corner] = (x,y,score)
+        choice = legend.corner
+        if choice == 'auto':
+            choice = min(CORNERS, key=lambda c: round(candidates[c][2], 8))
+            if candidates[choice][2] > 0:
+                from .overlaps import OverlapWarning
+                warnings.warn('Legend: all corners overlap content; using minimum overlap', OverlapWarning, stacklevel=2)
+        x,y,score = candidates[choice]
+        legend.layout(x,y,w,h)
+        legend._corner_conflict = score
+        legend._clear_corners = [c for c in CORNERS if candidates[c][2] == 0 and c != choice]
+        obstacles.append((x,y,w,h))