codefig 0.17.0__py3-none-any.whl

codefig/compose.py

@@ -0,0 +1,374 @@
+"""Repetition idioms (v0.4.0): Stacked decks, "× N" repeats, and "0 … N-1" series.
+
+``Stacked(node, n=3)``  — the node drawn as the front card of a deck (instances /
+    replicas / multi-head), back cards offset up-right by default.
+``Repeat(node, n=12)``  — the node framed (or bracketed) with a "× N" annotation,
+    Transformer style.
+``Series(a, b, c)``     — items in a row / column with an ellipsis before the last one,
+    for "Worker 0, Worker 1, …, Worker N-1".
+
+All three are ordinary nodes (flex layout, constraints, ports); none takes coordinates.
+"""
+
+from __future__ import annotations
+
+from typing import Any, List, Optional, Sequence, Tuple, Union
+
+from .node import Container, Node, Row
+from .primitives import Ellipsis, Text
+from .styles import themed
+from .textutil import measure_text
+
+_OFFSETS = {"up-right": (1, -1), "down-right": (1, 1), "up-left": (-1, -1), "down-left": (-1, 1),
+            "right": (1, 0), "down": (0, 1), "up": (0, -1), "left": (-1, 0)}
+
+
+class Stacked(Node):
+    """A deck of ``n`` cards: ``node`` in front, ``n - 1`` copies peeking out behind.
+
+    offset: px per card (number, or ``(dx, dy)``); direction: up-right | down-right |
+    up-left | down-left | right | down | …. copies: "blank" (default — the card's frame
+    and fill only, like replicated instances), "full" (each copy redrawn, contents and
+    all), or "outline" (frame with no fill). ``back_fill`` overrides the copies' fill.
+    ``deck.port(side)`` lands on the FRONT card (v0.7.0) — the card the reader sees —
+    so ``Edge(deck, x)`` / ``deck.port("right")`` start at the front card's outline, not
+    at the edge of the peeking back cards; ``deck.deck_port(side)`` is the old
+    whole-stack bounding-box port. ``back_tint`` (default 0.25 per card, ``0`` = off)
+    lightens each card further back so the front card reads as the object and the
+    copies as depth; ``back_stroke_width`` defaults to the thin theme stroke.
+    Role: inherits the front card's (hard for Box / shapes, background for Group).
+    ``same_width(deck, x)`` / ``same_height`` size the front card (v0.13.0).
+    """
+
+    def __init__(self, node: Node, n: int = 3, *,
+                 offset: Union[float, Tuple[float, float], None] = None,
+                 direction: str = "up-right", copies: str = "blank",
+                 back_fill: Optional[Any] = None, back_stroke: Optional[str] = None,
+                 back_tint: float = 0.25, back_stroke_width: Optional[float] = None,
+                 **kwargs: Any) -> None:
+        if n < 1:
+            raise ValueError("Stacked needs n >= 1")
+        if copies not in ("blank", "full", "outline"):
+            raise ValueError("copies must be blank|full|outline")
+        if direction not in _OFFSETS:
+            raise ValueError(f"direction must be one of {tuple(_OFFSETS)}")
+        self._role_explicit = None
+        super().__init__(**kwargs)
+        self.node = node
+        node.parent = self
+        self.n = int(n)
+        self._offset = offset
+        self._direction = direction
+        self.copies = copies
+        self.back_fill = back_fill
+        self.back_stroke = back_stroke
+        self.back_tint = float(back_tint)
+        self.back_stroke_width = back_stroke_width
+
+    def port(self, side: str = "right", **kw: Any):
+        """Port in line with the FRONT card; same arguments as :meth:`Node.port`.
+
+        On the sides the back cards do not peek out of, it is the front card's own
+        outline. On the sides they do (``right`` / ``top`` for the default up-right
+        deck) it sits on the outermost card, level with the front card's port, so an
+        edge attaches to the deck without crossing the copies.
+        """
+        if side in ("left", "right", "top", "bottom") and set(kw) <= {"at"}:
+            from .edges import Port
+
+            return Port(self, kind="side", side=side, at=float(kw.get("at", 0.5)))
+        return self.node.port(side, **kw)
+
+    def resolve_port_side(self, side: str, at: float = 0.5):
+        """(x, y, direction) of :meth:`port` — used by :class:`~codefig.edges.Port`."""
+        fg = self.node.geom
+        k = self.n - 1
+        at = max(0.0, min(1.0, at))
+        ex, ey = self.dx * k, self.dy * k  # rearmost card offset from the front card
+        if side == "right":
+            return fg.right + max(0.0, ex), fg.y + fg.h * at, "right"
+        if side == "left":
+            return fg.x + min(0.0, ex), fg.y + fg.h * at, "left"
+        if side == "top":
+            return fg.x + fg.w * at, fg.y + min(0.0, ey), "up"
+        return fg.x + fg.w * at, fg.bottom + max(0.0, ey), "down"
+
+    @property
+    def _size_proxy(self) -> Node:
+        """same_width / same_height size the front card (v0.13.0)."""
+        return self.node
+
+    def deck_port(self, side: str = "right", **kw: Any):
+        """Port on the whole deck's bounding box (front + peeking back cards)."""
+        return Node.port(self, side, **kw)
+
+    def _offset_xy(self) -> Tuple[float, float]:
+        off = self._offset
+        if off is None:  # theme length: 7 px classic, ≈ 3.9 pt paper
+            off = self.theme.L(7.0)
+        if isinstance(off, (int, float)):
+            sx, sy = _OFFSETS[self._direction]
+            return sx * float(off), sy * float(off)
+        return float(off[0]), float(off[1])
+
+    @property
+    def dx(self) -> float:
+        """Per-card x offset (from ``offset`` / ``direction``; default a theme length)."""
+        return self._offset_xy()[0]
+
+    @property
+    def dy(self) -> float:
+        """Per-card y offset."""
+        return self._offset_xy()[1]
+
+    # role follows the front card unless set explicitly
+    @property
+    def obstacle(self) -> Optional[str]:
+        if self._role_explicit is not None:
+            return self._role_explicit
+        from .policy import role_of
+
+        return role_of(self.node) if hasattr(self, "node") else None
+
+    @obstacle.setter
+    def obstacle(self, v: Optional[str]) -> None:
+        self._role_explicit = v
+
+    def children(self) -> Sequence[Node]:
+        return [self.node]
+
+    def invalidate(self) -> None:
+        super().invalidate()
+        if hasattr(self, "node"):
+            self.node.invalidate()
+
+    def _measure(self) -> Tuple[float, float]:
+        w, h = self.node.measure()
+        k = self.n - 1
+        return w + abs(self.dx) * k, h + abs(self.dy) * k
+
+    def _layout_children(self) -> None:
+        g = self.geom
+        cw, ch = self.node.measure()
+        k = self.n - 1
+        x = g.x + (abs(self.dx) * k if self.dx < 0 else 0.0)
+        y = g.y + (abs(self.dy) * k if self.dy < 0 else 0.0)
+        self.node.layout(x, y, min(cw, g.w - abs(self.dx) * k) if g.w > 0 else cw,
+                         min(ch, g.h - abs(self.dy) * k) if g.h > 0 else ch)
+
+    def _draw_card(self, buf: List[str], x: float, y: float, w: float, h: float,
+                   depth: int = 1) -> None:
+        from .render_svg import draw_rect
+        from .styles import tint
+
+        nd = self.node
+        fill = self.back_fill if self.back_fill is not None else getattr(nd, "fill", None)
+        if self.copies == "outline":
+            fill = "none"
+        if fill is None:
+            fill = "#ffffff"
+        if (self.back_tint > 0 and isinstance(fill, str) and fill.startswith("#")
+                and len(fill) in (4, 7)):
+            fill = tint(fill, min(0.85, self.back_tint * depth))
+        stroke = self.back_stroke or getattr(nd, "stroke", None) or self.theme.stroke
+        sw = (self.back_stroke_width if self.back_stroke_width is not None
+              else (getattr(nd, "stroke_width", None) or self.theme.stroke_width))
+        if hasattr(nd, "_draw_frame") and hasattr(nd, "_path"):  # a Shape: same outline
+            from .render_svg import draw_path
+
+            draw_path(buf, nd._path(x, y, w, h), fill=fill, stroke=stroke, stroke_width=sw)
+            if hasattr(nd, "_decorate"):
+                nd._decorate(buf, x, y, w, h)
+            return
+        r = 0.0
+        if getattr(nd, "rounded", False):
+            r = getattr(nd, "radius", None) or self.theme.corner_radius
+        draw_rect(buf, x, y, w, h, fill=fill, stroke=stroke, stroke_width=sw, radius=r,
+                  dasharray=nd._dash(sw) if hasattr(nd, "_dash") else None)
+
+    def draw(self, buf: List[str], ox: float = 0.0, oy: float = 0.0) -> None:
+        ng = self.node.geom
+        for k in range(self.n - 1, 0, -1):
+            if self.copies == "full":
+                self.node.draw(buf, ox + self.dx * k, oy + self.dy * k)
+            else:
+                self._draw_card(buf, ng.x + ox + self.dx * k, ng.y + oy + self.dy * k, ng.w, ng.h,
+                                depth=k)
+        self.node.draw(buf, ox, oy)
+
+
+class Repeat(Node):
+    """``node`` repeated N times, shown once with an "× N" mark (Transformer "N×").
+
+    style: "frame" (rounded dashed frame around the node, label beside it), "bracket"
+    (a square bracket on ``side`` with the label next to it) or "label" (just the text).
+    side: right | left | top | bottom. label: default "× {n}" (pass e.g. "N×" or "L layers").
+    The label is a real soft Text child (knockout / overlap aware); the frame is
+    background (edges may cross it, like a Group).
+    """
+
+    def __init__(self, node: Node, n: Any = "N", *, label: Optional[str] = None,
+                 style: str = "frame", side: str = "right", gap: Optional[float] = None,
+                 pad: Optional[float] = None, color: str = "#555555",
+                 font_size: Optional[float] = None, border: Any = "dashed",
+                 radius: Optional[float] = None, fill: Optional[Any] = None,
+                 weight: str = "bold", **kwargs: Any) -> None:
+        if style not in ("frame", "bracket", "label"):
+            raise ValueError("style must be frame|bracket|label")
+        if side not in ("right", "left", "top", "bottom"):
+            raise ValueError("side must be right|left|top|bottom")
+        super().__init__(border=border if style == "frame" else None, **kwargs)
+        self.node = node
+        node.parent = self
+        self.n = n
+        self.style = style
+        self.side = side
+        self.gap = gap
+        self._pad = pad
+        self.color = color
+        self.radius = radius
+        self.fill = fill
+        txt = label if label is not None else f"× {n}"
+        self.label = Text(txt, font_size=font_size, weight=weight, color=color,
+                          theme=self._theme)
+        self.label.parent = self
+
+    gap = themed(6.0)
+    radius = themed(6.0)
+    frame_width = themed(1.2, "SW")
+
+    @property
+    def pad(self) -> float:
+        """Frame padding around the node (theme length; 0 unless ``style="frame"``)."""
+        if self.style != "frame":
+            return 0.0
+        return float(self._pad) if self._pad is not None else self.theme.L(6.0)
+
+    def children(self) -> Sequence[Node]:
+        return [self.node, self.label]
+
+    def invalidate(self) -> None:
+        super().invalidate()
+        if hasattr(self, "node"):
+            self.node.invalidate()
+            self.label.invalidate()
+
+    def _bracket_w(self) -> float:
+        return self.theme.L(7.0) if self.style == "bracket" else 0.0
+
+    def _measure(self) -> Tuple[float, float]:
+        cw, ch = self.node.measure()
+        lw, lh = self.label.measure()
+        fw, fh = cw + 2 * self.pad, ch + 2 * self.pad
+        bw = self._bracket_w()
+        if self.side in ("left", "right"):
+            ext = bw + (self.gap if bw else 0) + self.gap + lw
+            return fw + ext, max(fh, lh)
+        ext = bw + (self.gap if bw else 0) + self.gap + lh
+        return max(fw, lw), fh + ext
+
+    def _frame_rect(self) -> Tuple[float, float, float, float]:
+        g = self.geom
+        cw, ch = self.node.measure()
+        fw, fh = cw + 2 * self.pad, ch + 2 * self.pad
+        lw, lh = self.label.measure()
+        ext_h = self._bracket_w() + (self.gap if self._bracket_w() else 0) + self.gap
+        if self.side == "right":
+            return g.x, g.y + (g.h - fh) / 2, fw, fh
+        if self.side == "left":
+            return g.x + ext_h + lw, g.y + (g.h - fh) / 2, fw, fh
+        if self.side == "bottom":
+            return g.x + (g.w - fw) / 2, g.y, fw, fh
+        return g.x + (g.w - fw) / 2, g.y + ext_h + lh, fw, fh
+
+    def _layout_children(self) -> None:
+        self._follow = False
+        fx, fy, fw, fh = self._frame_rect()
+        cw, ch = self.node.measure()
+        self.node.layout(fx + self.pad, fy + self.pad, cw, ch)
+        self._place_label(fx, fy, fw, fh)
+
+    def _after_solve(self) -> None:
+        """Constraints moved the repeated node: frame and label follow it."""
+        g = self.node.geom
+        fr = (g.x - self.pad, g.y - self.pad, g.w + 2 * self.pad, g.h + 2 * self.pad)
+        if max(abs(a - b) for a, b in zip(fr, self._frame_rect())) < 1e-6:
+            return
+        self._follow = True
+        self._place_label(*fr)
+
+    def _drawn_frame(self) -> Tuple[float, float, float, float]:
+        if not getattr(self, "_follow", False):
+            return self._frame_rect()
+        g = self.node.geom  # later whole-subtree translations move this too
+        return g.x - self.pad, g.y - self.pad, g.w + 2 * self.pad, g.h + 2 * self.pad
+
+    def _place_label(self, fx: float, fy: float, fw: float, fh: float) -> None:
+        lw, lh = self.label.measure()
+        bw = self._bracket_w()
+        step = bw + (self.gap if bw else 0) + self.gap
+        if self.side == "right":
+            self.label.layout(fx + fw + step, fy + (fh - lh) / 2, lw, lh)
+        elif self.side == "left":
+            self.label.layout(fx - step - lw, fy + (fh - lh) / 2, lw, lh)
+        elif self.side == "bottom":
+            self.label.layout(fx + (fw - lw) / 2, fy + fh + step, lw, lh)
+        else:
+            self.label.layout(fx + (fw - lw) / 2, fy - step - lh, lw, lh)
+
+    def draw(self, buf: List[str], ox: float = 0.0, oy: float = 0.0) -> None:
+        from .render_svg import draw_path, draw_rect
+
+        fx, fy, fw, fh = self._drawn_frame()
+        fx, fy = fx + ox, fy + oy
+        if self.style == "frame":
+            draw_rect(buf, fx, fy, fw, fh, fill=self.fill if self.fill is not None else "none",
+                      stroke=self.color, stroke_width=self.frame_width, radius=self.radius,
+                      dasharray=self._dash(self.frame_width))
+        elif self.style == "bracket":
+            b, t = self._bracket_w(), self.theme.L(3.0)
+            if self.side in ("right", "left"):
+                x0 = fx + fw + self.gap if self.side == "right" else fx - self.gap
+                s = 1 if self.side == "right" else -1
+                d = (f"M {x0:.2f},{fy + t:.2f} L {x0 + s * b:.2f},{fy + t:.2f} "
+                     f"L {x0 + s * b:.2f},{fy + fh - t:.2f} L {x0:.2f},{fy + fh - t:.2f}")
+            else:
+                y0 = fy + fh + self.gap if self.side == "bottom" else fy - self.gap
+                s = 1 if self.side == "bottom" else -1
+                d = (f"M {fx + t:.2f},{y0:.2f} L {fx + t:.2f},{y0 + s * b:.2f} "
+                     f"L {fx + fw - t:.2f},{y0 + s * b:.2f} L {fx + fw - t:.2f},{y0:.2f}")
+            draw_path(buf, d, stroke=self.color, stroke_width=self.theme.SW(1.3))
+        self.node.draw(buf, ox, oy)
+        self.label.draw(buf, ox, oy)
+
+
+class Series(Row):
+    """Items with an ellipsis before the last: ``Series(w0, w1, wN)`` → w0 w1 … wN.
+
+    direction: "row" (default, "⋯") or "column" ("⋮"). ``ellipsis=False`` drops the
+    mark; ``at`` = index the ellipsis is inserted before (default: last item).
+    Takes every Row / Col keyword (gap, align, …). Layout-only role, like Row.
+    """
+
+    def __init__(self, *items: Any, ellipsis: bool = True, at: Optional[int] = None,
+                 direction: str = "row", ellipsis_text: Optional[str] = None,
+                 ellipsis_size: Optional[float] = None, ellipsis_color: str = "#444444",
+                 **kwargs: Any) -> None:
+        if len(items) == 1 and isinstance(items[0], (list, tuple)):
+            items = tuple(items[0])
+        if direction not in ("row", "column", "col"):
+            raise ValueError("direction must be row|column")
+        kids: List[Node] = list(items)
+        self.ellipsis_node: Optional[Node] = None
+        if ellipsis and len(kids) >= 2:
+            vertical = direction != "row"
+            txt = ellipsis_text or ("⋮" if vertical else "⋯")
+            self.ellipsis_node = Ellipsis(txt, font_size=ellipsis_size or 16, color=ellipsis_color)
+            i = len(kids) - 1 if at is None else at
+            kids.insert(i, self.ellipsis_node)
+        kwargs.setdefault("align", "center")
+        kwargs["direction"] = "row" if direction == "row" else "column"
+        super().__init__(kids, **kwargs)
+
+
+__all__ = ["Repeat", "Series", "Stacked"]