codefig 0.17.0__py3-none-any.whl

codefig/notices.py

@@ -0,0 +1,34 @@
+"""v0.12.0: draw-time notices (labels the engine shortened or dropped).
+
+Draw code calls :func:`note` when it ellipsizes a label or skips one for lack of room;
+the linter resets the list before its instrumented render and reports what was noted
+as CF-TXT-011, so nothing disappears silently.
+"""
+from __future__ import annotations
+
+from typing import Any, List, Tuple
+
+_NOTES: List[Tuple[Any, str, str, str]] = []
+
+
+def note(owner: Any, text: str, why: str, level: str = "warn") -> None:
+    """Record that ``owner`` shortened, moved or dropped ``text``.
+
+    ``why``: short reason; ``level``: ``"warn"`` (shortened / not drawn) or ``"info"``
+    (drawn, but at a fallback position).
+    """
+    key = (id(owner), str(text), why)
+    if any((id(o), t, w) == key for o, t, w, _l in _NOTES):
+        return
+    _NOTES.append((owner, str(text), why, level))
+
+
+def reset() -> None:
+    _NOTES.clear()
+
+
+def drained() -> List[Tuple[Any, str, str, str]]:
+    """Notes recorded since the last :func:`reset` (cleared on read)."""
+    out = list(_NOTES)
+    _NOTES.clear()
+    return out

codefig/overlaps.py

@@ -0,0 +1,392 @@
+"""Global overlap detection and resolution inside one panel.
+
+Any two *visible* nodes that are not ancestor/descendant of each other (boxes,
+texts, matrices, strips, dot grids, braces, framed groups, and place()
+annotations) may not overlap by more than ``tol`` px on both axes. Layout-only
+containers (Row/Col/Stack/Grid/Diagram), Spacers, arrows and CircleHighlight /
+Callout rings (intentional overlays) are ignored, as are nodes listed in an
+``allow_overlap(...)`` constraint.
+
+Policies (``Figure(overlap=...)`` / ``Panel(overlap=...)``):
+
+* ``"resolve"`` (default): each overlapping pair gets a ``no_overlap`` constraint
+  along the axis of least penetration and the panel is re-solved (≤ 6 rounds);
+  anything still overlapping emits an :class:`OverlapWarning`.
+* ``"warn"``: report only (OverlapWarning).
+* ``"error"``: raise :class:`OverlapError`.
+* ``"ignore"``: skip the check.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, Iterable, List, Optional, Sequence, Tuple
+
+from .constraints import Constraint, node_name, no_overlap, walk
+
+POLICIES = ("resolve", "warn", "error", "ignore")
+
+_VISIBLE = {"Box", "Text", "Ellipsis", "Matrix", "DotGrid", "Strip", "Brace", "Group",
+            "Badge", "BarChart", "VectorFan", "Swatch", "Legend"}
+# intentional overlays: rings / callouts sit on top of what they highlight
+_OVERLAY_TYPES = {"CircleHighlight", "Callout"}
+
+
+
+def _unit() -> str:
+    from .styles import length_unit
+
+    return length_unit()
+
+class OverlapError(ValueError):
+    """Raised with overlap='error' when visible nodes overlap."""
+
+
+class OverlapWarning(UserWarning):
+    """Emitted when visible nodes overlap (overlap='warn', or unresolved)."""
+
+
+def _node_context(node: Any) -> str:
+    """v0.13.0: where a crossed node is — its nearest named container and its box —
+    so ``Task('…')`` or an unnamed Box can be found without guessing."""
+    parts = []
+    p = getattr(node, "parent", None)
+    while p is not None:
+        nm = node_name(p)
+        if "@" not in nm:
+            parts.append(f"inside {nm}")
+            break
+        p = getattr(p, "parent", None)
+    g = getattr(node, "geom", None)
+    if g is not None:
+        parts.append(f"at x {g.x:.0f}–{g.x + g.w:.0f}, y {g.y:.0f}–{g.y + g.h:.0f}{_unit()}")
+    return f" ({', '.join(parts)})" if parts else ""
+
+
+@dataclass
+class Overlap:
+    a: Any
+    b: Any
+    dx: float  # penetration along x (px, pre-scale panel units)
+    dy: float
+    panel: str = ""
+    kind: str = "node"  # node | edge-node | head-text | label-node | label-text | label-label
+    #                     | step-node | step-text | step-label (edge step badges, v0.5.0)
+
+
+    @property
+    def axis(self) -> str:
+        """Axis of least penetration (the cheap way out)."""
+        return "x" if self.dx <= self.dy else "y"
+
+    def __str__(self) -> str:
+        where = f"panel ({self.panel}): " if self.panel else ""
+        if self.kind == "edge-node":
+            return (f"{where}{edge_name(self.a)} crosses hard node {node_name(self.b)}"
+                    f"{_node_context(self.b)}")
+        if self.kind == "head-text":
+            return (f"{where}arrowhead of {edge_name(self.a)} lands on text {node_name(self.b)} "
+                    f"by {self.dx:.1f}×{self.dy:.1f}{_unit()}")
+        if self.kind.startswith("step-"):
+            other = (f"label/step of {edge_name(self.b)}" if self.kind == "step-label"
+                     else node_name(self.b))
+            return (f"{where}step badge {self.a.step.text!r} on {edge_name(self.a)} overlaps {other} "
+                    f"by {self.dx:.1f}×{self.dy:.1f}{_unit()}")
+        if self.kind.startswith("label-"):
+            other = (f"label {self.b.label!r}" if self.kind == "label-label"
+                     else node_name(self.b))
+            return (f"{where}label {self.a.label!r} of {edge_name(self.a)} overlaps {other} "
+                    f"by {self.dx:.1f}×{self.dy:.1f}{_unit()}")
+        return (f"{where}{node_name(self.a)} overlaps {node_name(self.b)} "
+                f"by {self.dx:.1f}×{self.dy:.1f}{_unit()}")
+
+
+def edge_name(e: Any) -> str:
+    try:
+        return f"edge {node_name(e.src.node)}→{node_name(e.dst.node)}"
+    except Exception:  # pragma: no cover
+        return "edge"
+
+
+def check_policy(p: Optional[str]) -> Optional[str]:
+    if p is None:
+        return None
+    p = str(p).lower()
+    if p not in POLICIES:
+        raise ValueError(f"overlap must be one of {POLICIES}, got {p!r}")
+    return p
+
+
+def _visible(n: Any, overlay_ids: set) -> bool:
+    """Takes part in node-vs-node checks: any role except none (see codefig.policy)."""
+    from .policy import role_of
+
+    if getattr(n, "allow_overlap", False):
+        return False
+    if getattr(n, "_cf_guide", False):  # timeline lane bands / marker lines / axis
+        return False
+    role = role_of(n)
+    if id(n) in overlay_ids:
+        return getattr(n, "_cf_obstacle", True) and role != "none"
+    if type(n).__name__ in _OVERLAY_TYPES:
+        return False
+    return role in ("hard", "soft", "background")
+
+
+def _contains(outer: Any, inner: Any, eps: float = 0.5) -> bool:
+    """A framed Group (or any background-role node) fully containing another node
+    (e.g. an annotation hosted inside it) is nesting, not overlap."""
+    from .policy import role_of
+
+    if type(outer).__name__ != "Group" and role_of(outer) != "background":
+        return False
+    go, gi = outer.geom, inner.geom
+    return (gi.x >= go.x - eps and gi.y >= go.y - eps and gi.x + gi.w <= go.x + go.w + eps
+            and gi.y + gi.h <= go.y + go.h + eps)
+
+
+def find_overlaps(root: Any, overlays: Sequence[Any] = (), constraints: Sequence[Constraint] = (),
+                  tol: float = 0.5) -> List[Overlap]:
+    """All topmost overlapping pairs of visible nodes under ``root`` (+ overlays)."""
+    parent: Dict[int, Any] = {}
+    nodes: List[Any] = []
+    for top in [root] + list(overlays):
+        for n in walk(top):
+            nodes.append(n)
+            for k in n.children():
+                parent[id(k)] = n
+    overlay_ids = {id(o) for o in overlays}
+
+    free_all: set = set()
+    free_pairs: List[set] = []
+    for c in constraints:
+        if c.kind == "allow_overlap":
+            ids = {id(n) for n in c.subjects}
+            if len(ids) == 1:
+                free_all |= ids
+            else:
+                free_pairs.append(ids)
+
+    def chain(n: Any) -> List[int]:
+        out = []
+        while n is not None:
+            out.append(id(n))
+            n = parent.get(id(n))
+        return out
+
+    chains = {id(n): chain(n) for n in nodes}
+    cand = [n for n in nodes if _visible(n, overlay_ids)]
+
+    def freed(a: Any, b: Any) -> bool:
+        ca, cb = set(chains[id(a)]), set(chains[id(b)])
+        if ca & free_all or cb & free_all:
+            return True
+        return any((ca & ids) and (cb & ids) for ids in free_pairs)
+
+    raw: List[Overlap] = []
+    for i, a in enumerate(cand):
+        ga = a.geom
+        if ga.w <= 1 or ga.h <= 1:
+            continue
+        for b in cand[i + 1:]:
+            gb = b.geom
+            if gb.w <= 1 or gb.h <= 1:
+                continue
+            if id(a) in chains[id(b)] or id(b) in chains[id(a)]:
+                continue
+            if _contains(a, b) or _contains(b, a):
+                continue
+            dx = min(ga.x + ga.w, gb.x + gb.w) - max(ga.x, gb.x)
+            dy = min(ga.y + ga.h, gb.y + gb.h) - max(ga.y, gb.y)
+            if dx > tol and dy > tol and not freed(a, b):
+                raw.append(Overlap(a, b, dx, dy))
+    # keep only topmost pairs: drop (a, b) if an ancestor pair also overlaps
+    keys = {(id(o.a), id(o.b)) for o in raw} | {(id(o.b), id(o.a)) for o in raw}
+    out = []
+    for o in raw:
+        ca, cb = chains[id(o.a)], chains[id(o.b)]
+        shadowed = any((x, y) in keys and (x, y) != (id(o.a), id(o.b))
+                       for x in ca for y in cb)
+        if not shadowed:
+            out.append(o)
+    return out
+
+
+def _isect(a: Tuple[float, float, float, float], b: Tuple[float, float, float, float]
+           ) -> Tuple[float, float]:
+    dx = min(a[0] + a[2], b[0] + b[2]) - max(a[0], b[0])
+    dy = min(a[1] + a[3], b[1] + b[3]) - max(a[1], b[1])
+    return dx, dy
+
+
+def _head_box(tip: Tuple[float, float], prev: Tuple[float, float], length: float,
+              width: float) -> Tuple[float, float, float, float]:
+    """Axis-aligned box of an arrowhead whose tip is ``tip`` (coming from ``prev``)."""
+    import math
+
+    dx, dy = tip[0] - prev[0], tip[1] - prev[1]
+    L = math.hypot(dx, dy) or 1.0
+    ux, uy = dx / L, dy / L
+    bx, by = tip[0] - ux * length, tip[1] - uy * length
+    hw = width / 2
+    xs = [tip[0], bx - uy * hw, bx + uy * hw]
+    ys = [tip[1], by + ux * hw, by - ux * hw]
+    return min(xs), min(ys), max(xs) - min(xs), max(ys) - min(ys)
+
+
+def find_edge_issues(diagram: Any, overlays: Sequence[Any] = (), constraints: Sequence[Any] = (),
+                     tol: float = 0.5) -> List[Overlap]:
+    """Layering errors for a Diagram's routed edges and labels (codefig.policy):
+
+    * an edge path crossing a **hard** node that is not one of its endpoints (nor an
+      ancestor / descendant of one) → ``edge-node``;
+    * an edge label overlapping a hard node / soft text / another label → ``label-*``.
+
+    Edges passing under soft text or labels, and across background groups, are fine.
+    """
+    from .edges import _poly_hits_rect
+    from .policy import role_of
+
+    lay = diagram.layout_edges()
+    parent: Dict[int, Any] = {}
+    hard: List[Any] = []
+    soft: List[Any] = []
+    free = set()
+    for c in constraints:
+        if getattr(c, "kind", "") == "allow_overlap":
+            free |= {id(n) for n in c.subjects}
+    for top in [diagram.content] + list(overlays):
+        for n in walk(top):
+            for k in n.children():
+                parent[id(k)] = n
+            if getattr(n, "allow_overlap", False) or id(n) in free:
+                continue
+            if id(n) in {id(o) for o in overlays} and not getattr(n, "_cf_obstacle", True):
+                continue
+            r = role_of(n)
+            g = n.geom
+            if g.w <= 1 or g.h <= 1:
+                continue
+            if r == "hard":
+                hard.append(n)
+            elif r == "soft":
+                soft.append(n)
+
+    def family(nodes: Iterable[Any]) -> set:
+        out = set()
+        for n in nodes:
+            m = n
+            while m is not None:  # ancestors
+                out.add(id(m))
+                m = parent.get(id(m))
+            for d in walk(n):  # descendants
+                out.add(id(d))
+        return out
+
+    issues: List[Overlap] = []
+    shrink = 1.5
+    for e, pts in lay["routed"]:
+        fk = getattr(e, "_fork", None)
+        ends = [e.src.node, e.dst.node]
+        if fk is not None:  # a fork piece is exempt only for the hub and its own leaf
+            ends = [fk._node(fk.hub), e.src.node, e.dst.node]
+        if getattr(e, "around", None) is not None:
+            ends.append(e.around)
+        fam = family(ends)
+        # v0.13.0: a Guide is meant to pass over things — no runtime "crosses hard node"
+        for n in (() if getattr(e, "_cf_guide_edge", False) else hard):
+            if id(n) in fam:
+                continue
+            g = n.geom
+            r = (g.x + shrink, g.y + shrink, g.w - 2 * shrink, g.h - 2 * shrink)
+            if r[2] > 0 and r[3] > 0 and _poly_hits_rect(pts, r):
+                issues.append(Overlap(e, n, 0.0, 0.0, kind="edge-node"))
+        # arrowheads are never knocked out, so a head on soft text is an error
+        st = e.resolved(diagram.theme)
+        for hd, tip, prev in ((st.end_head, pts[-1], pts[-2]), (st.start_head, pts[0], pts[1])):
+            if hd is None or not hd.visible:
+                continue
+            hb = _head_box(tip, prev, hd.length, hd.width)
+            for n in soft:
+                if id(n) in fam:
+                    continue
+                ib = n.ink_box() if hasattr(n, "ink_box") else (n.geom.x, n.geom.y, n.geom.w, n.geom.h)
+                dx, dy = _isect(hb, ib)
+                if dx > tol and dy > tol:
+                    issues.append(Overlap(e, n, dx, dy, kind="head-text"))
+
+    labels = lay["labels"]
+    for i, (e, _pts, geo) in enumerate(labels):
+        box = geo[0]
+        for n in hard:
+            g = n.geom
+            dx, dy = _isect(box, (g.x, g.y, g.w, g.h))
+            if dx > tol and dy > tol:
+                issues.append(Overlap(e, n, dx, dy, kind="label-node"))
+        for n in soft:
+            ib = n.ink_box() if hasattr(n, "ink_box") else (n.geom.x, n.geom.y, n.geom.w, n.geom.h)
+            dx, dy = _isect(box, ib)
+            if dx > tol and dy > tol:
+                issues.append(Overlap(e, n, dx, dy, kind="label-text"))
+        for e2, _p2, geo2 in labels[i + 1:]:
+            dx, dy = _isect(box, geo2[0])
+            if dx > tol and dy > tol:
+                issues.append(Overlap(e, e2, dx, dy, kind="label-label"))
+    # step badges on edges (①): like labels — no hard node, soft text, label or badge
+    steps = lay.get("steps", [])
+    for i, (e, box) in enumerate(steps):
+        for n in hard:
+            g = n.geom
+            dx, dy = _isect(box, (g.x, g.y, g.w, g.h))
+            if dx > tol and dy > tol:
+                issues.append(Overlap(e, n, dx, dy, kind="step-node"))
+        for n in soft:
+            ib = n.ink_box() if hasattr(n, "ink_box") else (n.geom.x, n.geom.y, n.geom.w, n.geom.h)
+            dx, dy = _isect(box, ib)
+            if dx > tol and dy > tol:
+                issues.append(Overlap(e, n, dx, dy, kind="step-text"))
+        for e2, _p2, geo2 in labels:
+            dx, dy = _isect(box, geo2[0])
+            if dx > tol and dy > tol:
+                issues.append(Overlap(e, e2, dx, dy, kind="step-label"))
+        for e2, box2 in steps[i + 1:]:
+            dx, dy = _isect(box, box2)
+            if dx > tol and dy > tol:
+                issues.append(Overlap(e, e2, dx, dy, kind="step-label"))
+    return issues
+
+
+def resolution_for(o: Overlap, overlays: Sequence[Any] = (), margin: float = 2.0,
+                   strength: str = "required") -> Constraint:
+    """A no_overlap constraint that separates the pair along its cheapest axis.
+    The annotation (if any) stays; the other node is pushed."""
+    ax = o.axis
+    a, b = o.a, o.b
+    ga, gb = a.geom, b.geom
+    ca = ga.x + ga.w / 2 if ax == "x" else ga.y + ga.h / 2
+    cb = gb.x + gb.w / 2 if ax == "x" else gb.y + gb.h / 2
+    first, second = (a, b) if ca <= cb else (b, a)
+    c = no_overlap(first, second, ax, margin=margin, strength=strength)
+    ov = {id(x) for x in overlays}
+    # subject = the mover; prefer moving the non-annotation
+    if id(second) in ov and id(first) not in ov:
+        c.subjects, c.refs = [first], [second]
+    return c
+
+
+def emit(found: Iterable[Overlap], policy: str) -> None:
+    import warnings
+
+    found = list(found)
+    if not found or policy == "ignore":
+        return
+    msg = "; ".join(str(o) for o in found)
+    what = ("overlapping nodes" if all(o.kind == "node" for o in found)
+            else "layering violations")
+    if policy == "error":
+        raise OverlapError(f"{what}: {msg}")
+    warnings.warn(f"{what}: {msg}", OverlapWarning, stacklevel=4)
+
+
+__all__ = ["Overlap", "OverlapError", "OverlapWarning", "find_overlaps", "find_edge_issues",
+           "resolution_for", "POLICIES"]

codefig/policy.py

@@ -0,0 +1,137 @@
+"""Layering / overlap policy: who may cover whom.
+
+Every element has one *role* (``obstacle=``). Authors rarely set it — the class
+default is right almost always:
+
+=============  =====================================================  =====================
+role           routing (edges …)                                      check_overlaps()
+=============  =====================================================  =====================
+``"hard"``     route *around* it; never drawn across it               edge across it → error
+``"soft"``     may pass *under* it (mild preference to avoid);        edge under it: fine;
+               the text knocks the line out (clean gap)               text-on-text → error
+``"background"`` cross freely (a small preference to stay outside)    edges: fine; nesting fine
+``"none"``     invisible to routing and overlap checks                ignored
+=============  =====================================================  =====================
+
+Defaults — hard: Box, Matrix (TokenStrip / Table / heatmaps), Badge, BarChart,
+VectorFan, Swatch, DotGrid, Strip, Brace, Legend, CircleHighlight/Callout, and (v0.4.0)
+every shape (Ellipse, Circle, OpCircle, Cylinder, Document, Trapezoid, Parallelogram,
+Hexagon, Diamond, ChatBubble, BlockArrow — Box subclasses), Icon, Image. Stacked
+inherits its front card's role (hard for a Box, background for a Group).
+v0.5.0 hard: Step badges (on boxes and edges), CodeBlock, Timeline Task bars and
+TimeSpan braces / brackets / dims.
+Soft: Text, Ellipsis, edge labels, place() text annotations, Repeat's "× N" label,
+Dim / Timeline labels (lane headers, tick / marker / span labels).
+Background: Group, Repeat's frame (and the panel), Lanes / Lane. A background node
+that fully contains another is nesting, not overlap. Timeline lane bands, marker
+lines and the axis line are *guides* (``_cf_guide``): background for routing and
+skipped by check_overlaps(). Layout-only containers (Row/Col/Series/Tree/Timeline
+body/…) take no part.
+
+Override per element (``Text(..., obstacle="hard")``, ``Group(..., obstacle="none")``,
+``Text(..., knockout=False)``) or per figure (``Figure(roles={"Text": "hard"},
+knockout=False)``). ``obstacle=True`` means "hard", ``False`` means "none".
+"""
+
+from __future__ import annotations
+
+import contextlib
+from typing import Any, Dict, Iterator, Mapping, Optional
+
+ROLES = ("hard", "soft", "background", "none")
+
+_DEFAULT_ROLES: Dict[str, str] = {
+    "Box": "hard",
+    "Matrix": "hard",
+    "Badge": "hard",
+    "BarChart": "hard",
+    "VectorFan": "hard",
+    "Swatch": "hard",
+    "DotGrid": "hard",
+    "Strip": "hard",
+    "Brace": "hard",
+    "Legend": "hard",
+    "CircleHighlight": "hard",
+    "Callout": "hard",
+    "Icon": "hard",
+    "Image": "hard",
+    "Stacked": "hard",  # overridden per instance: follows the front card's role
+    "Repeat": "background",
+    "Text": "soft",
+    "Ellipsis": "soft",
+    "Group": "background",
+    # v0.5.0
+    "Step": "hard",
+    "CodeBlock": "hard",
+    "TimeSpan": "hard",
+    "Lanes": "background",
+    "Lane": "background",
+}
+
+_ALIASES = {True: "hard", False: "none", "solid": "hard", "coverable": "soft",
+            "transparent": "none", "free": "none", "bg": "background"}
+
+_overrides: Dict[str, str] = {}
+_knockout_default: bool = True
+
+
+def normalize_role(v: Any) -> Optional[str]:
+    if v is None:
+        return None
+    if isinstance(v, bool):
+        return _ALIASES[v]
+    s = str(v).lower()
+    s = _ALIASES.get(s, s)
+    if s not in ROLES:
+        raise ValueError(f"obstacle must be one of {ROLES} (or True/False), got {v!r}")
+    return s
+
+
+def default_role(node: Any) -> Optional[str]:
+    """Class default (MRO aware, so subclasses inherit), after figure overrides."""
+    for cls in type(node).__mro__:
+        name = cls.__name__
+        if name in _overrides:
+            return _overrides[name]
+        if name in _DEFAULT_ROLES:
+            return _DEFAULT_ROLES[name]
+    return None
+
+
+def role_of(node: Any) -> Optional[str]:
+    """Effective role of ``node`` (None → layout-only, takes no part)."""
+    explicit = getattr(node, "_cf_obstacle_role", None)  # set by place(obstacle=…)
+    if explicit is None:
+        explicit = normalize_role(getattr(node, "obstacle", None))
+    return explicit if explicit is not None else default_role(node)
+
+
+def knockout_of(node: Any) -> bool:
+    k = getattr(node, "knockout", None)
+    return _knockout_default if k is None else bool(k)
+
+
+def knockout_enabled(theme: Any = None) -> bool:
+    """Figure-level knockout default (``use_policy``), further gated by ``theme.knockout``."""
+    if not _knockout_default:
+        return False
+    return bool(getattr(theme, "knockout", True)) if theme is not None else True
+
+
+@contextlib.contextmanager
+def use_policy(roles: Optional[Mapping[str, Any]] = None,
+               knockout: Optional[bool] = None) -> Iterator[None]:
+    """Figure-level defaults (applied while a Figure lays out / renders)."""
+    global _overrides, _knockout_default
+    old, old_k = dict(_overrides), _knockout_default
+    if roles:
+        _overrides.update({k: normalize_role(v) for k, v in roles.items()})  # type: ignore[misc]
+    if knockout is not None:
+        _knockout_default = bool(knockout)
+    try:
+        yield
+    finally:
+        _overrides, _knockout_default = old, old_k
+
+
+POLICY_TABLE = __doc__