codefig 0.17.0__py3-none-any.whl

codefig/dim.py

@@ -0,0 +1,214 @@
+"""Dimension lines: ``|←— label —→|`` between any two anchors.
+
+:class:`Dim` is an overlay item for a :class:`~codefig.edges.Diagram` (pass it in
+``edges=[...]`` like an Edge). It measures along x (``side="top"|"bottom"``) or y
+(``side="left"|"right"``) between two references and is drawn ``offset`` px outside
+them with thin extension (witness) lines back to the measured objects.
+"""
+
+from __future__ import annotations
+
+from typing import Any, List, Optional, Sequence, Tuple
+
+from .edges import Edge, Port, Pt
+from .styles import Theme
+
+DIM_SIDES = ("top", "bottom", "left", "right")
+DIM_ENDS = ("arrow", "stealth", "bar", "none")
+
+
+def _node_of(ref: Any) -> Any:
+    if isinstance(ref, Port):
+        return ref.node
+    if hasattr(ref, "geom"):
+        return ref
+    return getattr(ref, "node", None)
+
+
+def _coord(ref: Any, axis: str, which: str) -> float:
+    """Coordinate of ``ref`` on ``axis``; nodes / refs use their ``which`` edge."""
+    from .constraints import Anchor
+
+    if isinstance(ref, Anchor):
+        if ref.axis == axis:
+            return ref.value()
+        n = ref.node  # cross axis of an x-anchor: its node's box
+        g = n.geom
+        lo, hi = (g.x, g.right) if axis == "x" else (g.y, g.bottom)
+        return lo if which == "start" else (hi if which == "end" else (lo + hi) / 2)
+    if isinstance(ref, Port):
+        x, y, _d = ref.resolve()
+        return x if axis == "x" else y
+    if hasattr(ref, "_anchor"):
+        return ref._anchor(axis, which).value()
+    raise TypeError(f"Dim cannot measure from {type(ref).__name__}")
+
+
+class Dim(Edge):
+    """Dimension line with end arrows / ticks and extension lines between two anchors.
+
+    Layering: the line is an edge-like overlay (an edge crossing a **hard** node is
+    reported by check_overlaps(); the two measured objects are exempt). The label is
+    **soft** with knockout — the dimension line is cut around it.
+
+    Args:
+        a: Start reference — a node, a Matrix row / col / cell ref, a
+            ``CodeBlock.line(n)``, a :class:`~codefig.edges.Port` or an
+            :class:`~codefig.constraints.Anchor` (e.g. ``timeline.at(3.5)``).
+            For a node / ref the *start* edge (left or top) is used.
+        b: End reference (its *end* edge — right or bottom). Default: ``a``, i.e.
+            measure ``a``'s own width / height.
+        label: Text shown on the line (rich text allowed). ``""`` for none.
+        side: Where the line sits: ``"top"`` (default) / ``"bottom"`` measure along x;
+            ``"left"`` / ``"right"`` measure along y.
+        offset: Distance in px from the outermost of the two references to the line
+            (default 10; raised automatically so a centred label clears the objects).
+        ends: End markers — ``"arrow"`` (default, small filled triangles), ``"stealth"``,
+            ``"bar"`` (perpendicular ticks only) or ``"none"``.
+        extension: Draw extension (witness) lines from the objects to the line
+            (default ``True``).
+        color: Line / label colour (default ``"#333333"``).
+        width: Line width in px (default 1.0).
+        style: Line dash style as for Edge (``"dashed"`` …; default solid).
+        font_size: Label size in px (default ``0.85 × theme.font_size``).
+        label_side: ``"on"`` (centred on the line, knocked out; default for
+            horizontal dims), ``"above"`` / ``"below"`` / ``"left"`` / ``"right"``.
+            Vertical dims default to the outward side. A label wider than the line
+            moves outward automatically.
+        head_size: End-arrow size (default: the theme head; 6 px under ``classic``).
+        theme: Theme for defaults.
+
+    Example:
+        >>> from codefig import Figure, Row, Box, Diagram, Dim
+        >>> a, b = Box("prefill", w=120), Box("decode", w=60)
+        >>> d = Diagram(Row([a, b], gap=0), [Dim(a, b, "180 ms", side="top")])
+        >>> fig = Figure(size="auto", cols=1)
+        >>> _ = fig.panel("a").set(d)
+        >>> svg = fig.to_svg()
+    """
+
+    def __init__(
+        self,
+        a: Any,
+        b: Any = None,
+        label: str = "",
+        *,
+        side: str = "top",
+        offset: float = 10.0,
+        ends: str = "arrow",
+        extension: bool = True,
+        color: Optional[str] = None,
+        width: Optional[float] = None,
+        style: Any = None,
+        font_size: Optional[float] = None,
+        label_side: Optional[str] = None,
+        head_size: Optional[float] = None,
+        theme: Optional[Theme] = None,
+    ) -> None:
+        if side not in DIM_SIDES:
+            raise ValueError(f"Dim side must be one of {DIM_SIDES}, got {side!r}")
+        if ends not in DIM_ENDS:
+            raise ValueError(f"Dim ends must be one of {DIM_ENDS}, got {ends!r}")
+        b = a if b is None else b
+        na, nb = _node_of(a), _node_of(b)
+        if na is None or nb is None:
+            raise TypeError("Dim references must be nodes, refs, ports or anchors")
+        self.ref_a, self.ref_b = a, b
+        self.side = side
+        self.offset = float(offset)
+        self.ends = ends
+        self.extension = bool(extension)
+        horizontal = side in ("top", "bottom")
+        if label_side is None:
+            label_side = "on" if horizontal else side
+            if label_side == "top":
+                label_side = "above"
+        from .styles import current_theme
+
+        _th = theme or current_theme()
+        if _th.unit == 1.0:  # classic px look
+            width = 1.0 if width is None else width
+            head_size = 6.0 if head_size is None else head_size
+        head = {"arrow": "triangle", "stealth": "stealth", "bar": "bar", "none": "none"}[ends]
+        super().__init__(
+            Port(na, kind="side", side=side), Port(nb, kind="side", side=side),
+            route="straight", label=label or None, marker_start=head != "none",
+            marker_end=head != "none", head=head, tail=head, color=color or "#333333",
+            width=width, style=style, head_size=head_size, overlap="allow", stub=0.0,
+            label_side=label_side, label_size=font_size, label_gap=_th.L(3.0), theme=theme,
+            knockout=True,
+        )
+        self.route = "straight"
+
+    # ---- geometry -------------------------------------------------------------
+    def _geometry(self) -> Tuple[Pt, Pt, List[Tuple[Pt, Pt]]]:
+        """(start, end, extension segments) in page coordinates."""
+        a, b, s = self.ref_a, self.ref_b, self.side
+        horizontal = s in ("top", "bottom")
+        axis, cross = ("x", "y") if horizontal else ("y", "x")
+        lo = _coord(a, axis, "start")
+        hi = _coord(b, axis, "end")
+        near = "start" if s in ("top", "left") else "end"
+        ca, cb = _coord(a, cross, near), _coord(b, cross, near)
+        off = self.offset
+        if self.label and self.label_side == "on" and horizontal:
+            # a centred label must clear the measured objects (half its height + 2px)
+            from .styles import current_theme
+
+            fs = self.label_size or (self.theme or current_theme()).font_size * 0.85
+            off = max(off, fs * 1.25 / 2 + 3.0)
+        if s in ("top", "left"):
+            line = min(ca, cb) - off
+        else:
+            line = max(ca, cb) + off
+        over = 3.0 if s in ("bottom", "right") else -3.0
+        gap = -2.0 if s in ("bottom", "right") else 2.0
+        ext: List[Tuple[Pt, Pt]] = []
+        if self.extension:
+            for v, c in ((lo, ca), (hi, cb)):
+                if abs(line - c) > 3.0:
+                    p0, p1 = (c - gap, line + over)
+                    ext.append(((v, p0), (v, p1)) if horizontal else ((p0, v), (p1, v)))
+        if horizontal:
+            return (lo, line), (hi, line), ext
+        return (line, lo), (line, hi), ext
+
+    def endpoints(self) -> Tuple[Tuple[float, float, str], Tuple[float, float, str]]:
+        (x1, y1), (x2, y2), _e = self._geometry()
+        if self.side in ("top", "bottom"):
+            return (x1, y1, "left"), (x2, y2, "right")
+        return (x1, y1, "up"), (x2, y2, "down")
+
+    def points(self) -> List[Pt]:
+        p, q, _e = self._geometry()
+        return [p, q]
+
+    def label_geometry(self, pts, theme=None, obstacles=None, paths=None):
+        """Centre the label on the line; move it outward when the line is too short."""
+        import math
+
+        bbox, rot, align = super().label_geometry(pts, theme, obstacles, paths)
+        if self.label_side == "on" and len(pts) >= 2:
+            L = math.hypot(pts[-1][0] - pts[0][0], pts[-1][1] - pts[0][1])
+            horizontal = self.side in ("top", "bottom")
+            along = bbox[2] if horizontal else bbox[3]
+            if along + 2 * 8.0 > L:  # would cover the end arrows
+                keep = self.label_side
+                self.label_side = {"top": "above", "bottom": "below"}.get(self.side, self.side)
+                try:
+                    bbox, rot, align = super().label_geometry(pts, theme, obstacles, paths)
+                finally:
+                    self.label_side = keep
+        return bbox, rot, align
+
+    def draw(self, buf: List[str], ox: float = 0.0, oy: float = 0.0, **kw: Any) -> None:  # type: ignore[override]
+        from .render_svg import draw_line
+
+        super().draw(buf, ox, oy, **kw)
+        st = self.resolved(kw.get("theme"))
+        for (x1, y1), (x2, y2) in self._geometry()[2]:
+            draw_line(buf, x1 + ox, y1 + oy, x2 + ox, y2 + oy, stroke=st.color,
+                      stroke_width=max(0.6, st.width * 0.8), opacity=st.opacity)
+
+
+__all__ = ["Dim", "DIM_SIDES", "DIM_ENDS"]

codefig/edge_align.py

@@ -0,0 +1,231 @@
+"""v0.11.0: node-nudging edge alignment.
+
+After flex layout, the constraint solver still has freedom: a child of a ``Row`` can
+move vertically inside the row's padding band, a ``Col`` child horizontally, gaps
+may shrink to the container ``gap``, and unconstrained siblings can shift. This pass
+uses that freedom to put the two ports of a connected pair on one line so the edge
+is a single straight segment instead of a Z.
+
+For every orthogonal edge between two side ports that face each other (right→left,
+bottom→top, …) and are offset by more than 0.05 pt, a *medium* relation
+``port_a.y == port_b.y`` (or ``.x``) is a candidate. Candidates are tried greedily —
+short edges first, then small offsets — and one is kept only if, after solving with
+everything kept so far:
+
+* the relation really holds (stronger user constraints and the layout invariants win);
+* no container grows and the content bbox does not get larger;
+* no node moves by more than ``theme.align_max_shift`` (balance: a big move to fix
+  one edge usually skews the layout);
+* the number of visible jogs over the panel's diagrams drops, and no new overlap
+  appears.
+* (v0.12.0) no user constraint gets a larger residual, and no node that a user
+  equality constraint names (``same_x`` / ``same_y`` / ``align`` / ``place`` …)
+  moves on that constraint's axis — what you pinned stays where you pinned it.
+
+Opt out per figure (``Figure(align_edges=False)``), per panel
+(``fig.panel(..., align_edges=False)``) or per edge (``Edge(..., align=False)``).
+"""
+from __future__ import annotations
+
+from typing import Any, Callable, List, Optional, Sequence, Tuple
+
+from .constraints import Anchor, Constraint, Rel, node_name, walk
+
+
+def _facing_axis(a: Tuple[float, float, str], b: Tuple[float, float, str]) -> Optional[int]:
+    """Coordinate index that must match for a straight edge (1 = y, 0 = x), or None."""
+    if (a[2], b[2]) == ("right", "left") and b[0] > a[0] or \
+            (a[2], b[2]) == ("left", "right") and b[0] < a[0]:
+        return 1
+    if (a[2], b[2]) == ("down", "up") and b[1] > a[1] or \
+            (a[2], b[2]) == ("up", "down") and b[1] < a[1]:
+        return 0
+    return None
+
+
+def _is_ancestor(a: Any, b: Any) -> bool:
+    n = getattr(b, "parent", None)
+    while n is not None:
+        if n is a:
+            return True
+        n = getattr(n, "parent", None)
+    return False
+
+
+def _port_getter(port: Any, k: int) -> Callable[[], float]:
+    return lambda: float(port.resolve()[k])
+
+
+def candidates(content: Any) -> List[Tuple[Tuple[float, float], Any, Constraint]]:
+    """(priority, edge, medium constraint) for every alignable edge under ``content``."""
+    from .edges import Diagram, Edge
+
+    out = []
+    for d in walk(content):
+        if not isinstance(d, Diagram):
+            continue
+        th = d.theme
+        max_off = th.L(float(getattr(th, "align_max_offset", 60.0)))
+        for e in d.edges:
+            if not isinstance(e, Edge) or not e.align or e.route != "ortho" or \
+                    getattr(e, "bundle", None):
+                continue
+            if getattr(e.src, "node", None) is None or getattr(e.dst, "node", None) is None:
+                continue
+            if getattr(e, "_bare_ends", False):
+                e._pick_bare_sides()
+            na, nb = e.src.node, e.dst.node
+            if na is nb or _is_ancestor(na, nb) or _is_ancestor(nb, na):
+                continue
+            try:
+                a, b = e.src.resolve(), e.dst.resolve()
+            except Exception:  # pragma: no cover - unresolvable custom anchor
+                continue
+            k = _facing_axis(a, b)
+            if k is None:
+                continue
+            off = abs(a[k] - b[k])
+            if not 0.05 < off <= max_off:
+                continue
+            axis = "y" if k == 1 else "x"
+            ra = Anchor(na, axis, getter=_port_getter(e.src, k), label="port")
+            rb = Anchor(nb, axis, getter=_port_getter(e.dst, k), label="port")
+            c = Constraint(kind="align_edge", rels=[Rel(ra, "==", rb)], strength="medium",
+                           desc=f"align_edge({node_name(na)} → {node_name(nb)})")
+            length = abs(a[1 - k] - b[1 - k])
+            out.append(((round(length, 1), round(off, 2)), e, c))
+    out.sort(key=lambda t: t[0])
+    return out
+
+
+def visible_jogs(content: Any) -> int:
+    """Orthogonal routes with a Z / staircase step (first and last runs parallel,
+    heading the same way, not collinear) over every Diagram under ``content``."""
+    from .edges import Diagram, _simplify_ortho
+
+    n = 0
+    for d in walk(content):
+        if not isinstance(d, Diagram):
+            continue
+        try:
+            routed = d._routed()[0]
+        except Exception:  # pragma: no cover
+            continue
+        for e, pts in routed:
+            if getattr(e, "route", None) != "ortho":
+                continue
+            if is_jog(_simplify_ortho(pts)):
+                n += 1
+    return n
+
+
+def is_jog(q: Sequence[Tuple[float, float]]) -> bool:
+    if len(q) < 4:
+        return False
+    (x0, y0), (x1, y1) = q[0], q[1]
+    (x2, y2), (x3, y3) = q[-2], q[-1]
+    h = abs(y0 - y1) < 1e-6 and abs(y2 - y3) < 1e-6
+    v = abs(x0 - x1) < 1e-6 and abs(x2 - x3) < 1e-6
+    if not (h or v):
+        return False
+    k = 1 if h else 0
+    if (q[1][1 - k] - q[0][1 - k]) * (q[-1][1 - k] - q[-2][1 - k]) <= 0:
+        return False
+    return abs(q[-1][k] - q[0][k]) >= 0.05
+
+
+def snapshot(content: Any) -> dict:
+    return {id(n): (n.geom.x, n.geom.y, n.geom.w, n.geom.h) for n in walk(content)}
+
+
+def flush_pairs(content: Any, snap: dict) -> List[Tuple[int, int, int, int]]:
+    """Sibling pairs whose start or end edges coincide (``(id_a, id_b, axis, end)``).
+
+    A nudge that breaks one of these is rejected: flush tops in a row of panels or
+    flush left edges in a column read as deliberate alignment, and moving one box
+    off that line to straighten an arrow makes the figure look worse, not better."""
+    out = []
+    for n in walk(content):
+        kids = [k for k in (n.children() if hasattr(n, "children") else [])
+                if id(k) in snap and getattr(k, "visible", True)]
+        if not kids or len(kids) > 40:
+            continue
+        gp = snap[id(n)]
+        for ax in (0, 1):  # children pinned to one side of their parent (align="start")
+            offs = [(k, snap[id(k)][ax] - gp[ax],
+                     gp[ax] + gp[ax + 2] - snap[id(k)][ax] - snap[id(k)][ax + 2]) for k in kids]
+            lo_s = min(o[1] for o in offs)
+            lo_e = min(o[2] for o in offs)
+            for k, so, eo in offs:
+                if abs(so - lo_s) < 0.05 and so < eo - 0.05:
+                    out.append((id(n), id(k), ax, 2))
+                if abs(eo - lo_e) < 0.05 and eo < so - 0.05:
+                    out.append((id(n), id(k), ax, 3))
+        for i, a in enumerate(kids):
+            ga = snap[id(a)]
+            for b in kids[i + 1:]:
+                gb = snap[id(b)]
+                for ax in (0, 1):
+                    if abs(ga[ax] - gb[ax]) < 0.05:
+                        out.append((id(a), id(b), ax, 0))
+                    if abs(ga[ax] + ga[ax + 2] - gb[ax] - gb[ax + 2]) < 0.05:
+                        out.append((id(a), id(b), ax, 1))
+    return out
+
+
+def breaks_flush(pairs: Sequence[Tuple[int, int, int, int]], snap: dict,
+                 snap0: Optional[dict] = None) -> bool:
+    for ia, ib, ax, end in pairs:
+        ga, gb = snap[ia], snap[ib]
+        if end >= 2:  # parent ia, child ib: keep the child's offset to that side
+            if snap0 is not None:
+                p0, k0 = snap0[ia], snap0[ib]
+                if end == 2:
+                    d, d0 = gb[ax] - ga[ax], k0[ax] - p0[ax]
+                else:
+                    d = ga[ax] + ga[ax + 2] - gb[ax] - gb[ax + 2]
+                    d0 = p0[ax] + p0[ax + 2] - k0[ax] - k0[ax + 2]
+                if abs(d - d0) > 0.05:
+                    return True
+            continue
+        va = ga[ax] + (ga[ax + 2] if end else 0.0)
+        vb = gb[ax] + (gb[ax + 2] if end else 0.0)
+        if abs(va - vb) > 0.05:
+            return True
+    return False
+
+
+def broken_sibling_pairs(pairs: Sequence[Tuple[int, int, int, int]], snap: dict
+                         ) -> List[Tuple[int, int, int, int]]:
+    """The sibling entries of ``pairs`` (``end`` 0 / 1) whose shared edge ``snap`` broke."""
+    out = []
+    for ia, ib, ax, end in pairs:
+        if end >= 2:
+            continue
+        ga, gb = snap[ia], snap[ib]
+        va = ga[ax] + (ga[ax + 2] if end else 0.0)
+        vb = gb[ax] + (gb[ax + 2] if end else 0.0)
+        if abs(va - vb) > 0.05:
+            out.append((ia, ib, ax, end))
+    return out
+
+
+def flush_repairs(content: Any, broken: Sequence[Tuple[int, int, int, int]]) -> list:
+    """v0.11.0: medium constraints that keep each broken sibling pair flush again, so a
+    nudge can move a node *together with* the siblings it was lined up with (a parser
+    and the model box beside it) instead of being rejected."""
+    from .constraints import Constraint, Rel
+
+    by_id = {id(n): n for n in walk(content)}
+    out = []
+    for ia, ib, ax, end in broken:
+        a, b = by_id.get(ia), by_id.get(ib)
+        if a is None or b is None:
+            continue
+        axis = "x" if ax == 0 else "y"
+        fr = 1.0 if end else 0.0
+        out.append(Constraint(kind="align_edge", rels=[Rel(Anchor(a, axis, frac=fr), "==",
+                                                            Anchor(b, axis, frac=fr))],
+                              strength="medium",
+                              desc=f"flush({node_name(a)}, {node_name(b)})"))
+    return out