codefig 0.17.0__py3-none-any.whl

codefig/fills.py

@@ -0,0 +1,146 @@
+"""Paint objects usable anywhere a ``fill=`` colour is accepted (v0.4.0).
+
+``Gradient("#dbe8fb", "#2e6fd0", angle=90)`` — linear gradient (angle: 0 = left→right,
+90 = top→bottom; any number of colour stops). ``Split("#cfe", "#fdd")`` — two or more
+hard-edged colour regions (``split="diagonal" | "antidiagonal" | "vertical" |
+"horizontal"``, ``at=`` the boundary fraction), e.g. a half-frozen / half-trained module.
+
+Both are resolved by the SVG drawing helpers into ``<linearGradient>`` defs in
+objectBoundingBox units, so they work on rectangles, rounded boxes, ellipses and any
+outline path (shapes), on Group / Box / Key swatches alike.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import List, Optional, Sequence, Tuple, Union
+
+_seq = [0]
+
+
+def _next_id(prefix: str) -> str:
+    _seq[0] += 1
+    return f"cf-{prefix}-{_seq[0]}"
+
+
+class Paint:
+    """Base for non-solid fills. ``ref(buf)`` emits defs and returns ``url(#id)``."""
+
+    def stops(self) -> List[Tuple[float, str]]:  # pragma: no cover - abstract
+        raise NotImplementedError
+
+    def vector(self) -> Tuple[float, float, float, float]:  # pragma: no cover
+        raise NotImplementedError
+
+    def ref(self, buf: List[str]) -> str:
+        gid = _next_id(type(self).__name__.lower())
+        x1, y1, x2, y2 = self.vector()
+        st = "".join(f'<stop offset="{o:.4f}" stop-color="{c}"{self._op()} />'
+                     for o, c in self.stops())
+        buf.append(f'<defs><linearGradient id="{gid}" x1="{x1:.4f}" y1="{y1:.4f}" '
+                   f'x2="{x2:.4f}" y2="{y2:.4f}">{st}</linearGradient></defs>')
+        return f"url(#{gid})"
+
+    def _op(self) -> str:
+        op = getattr(self, "opacity", 1.0)
+        return f' stop-opacity="{op:.3f}"' if op < 0.999 else ""
+
+    def primary(self) -> str:
+        """A representative solid colour (first stop) for places that need one."""
+        return self.stops()[0][1]
+
+    def __str__(self) -> str:  # legend signatures / debugging
+        return f"{type(self).__name__}({', '.join(c for _, c in self.stops())})"
+
+
+def _angle_vector(angle: float) -> Tuple[float, float, float, float]:
+    t = math.radians(angle)
+    dx, dy = math.cos(t), math.sin(t)
+    # unit-square vector through the centre whose ends project onto the far corners
+    k = 0.5 * (abs(dx) + abs(dy))
+    return 0.5 - dx * k, 0.5 - dy * k, 0.5 + dx * k, 0.5 + dy * k
+
+
+class Gradient(Paint):
+    """Linear gradient fill: ``Gradient(c1, c2, ..., angle=0)`` (0 = left→right)."""
+
+    def __init__(self, *colors: Union[str, Sequence[str]], angle: float = 0.0,
+                 opacity: float = 1.0) -> None:
+        if len(colors) == 1 and not isinstance(colors[0], str):
+            colors = tuple(colors[0])  # type: ignore[assignment]
+        if len(colors) < 2:
+            raise ValueError("Gradient needs at least two colours")
+        self.colors = [str(c) for c in colors]
+        self.angle = float(angle)
+        self.opacity = float(opacity)
+
+    def stops(self) -> List[Tuple[float, str]]:
+        n = len(self.colors) - 1
+        return [(i / n, c) for i, c in enumerate(self.colors)]
+
+    def vector(self) -> Tuple[float, float, float, float]:
+        return _angle_vector(self.angle)
+
+
+_SPLITS = {
+    "vertical": (0.0, 0.5, 1.0, 0.5),       # boundary is a vertical line: left | right
+    "horizontal": (0.5, 0.0, 0.5, 1.0),     # top / bottom
+    "diagonal": (0.0, 0.0, 1.0, 1.0),       # top-left ◤ / ◢ bottom-right
+    "antidiagonal": (1.0, 0.0, 0.0, 1.0),   # top-right ◥ / ◣ bottom-left
+}
+
+
+class Split(Paint):
+    """Hard-edged multi-colour fill: ``Split(c1, c2, split="diagonal", at=0.5)``.
+
+    ``split``: vertical (left | right halves) · horizontal (top / bottom) · diagonal
+    (corner to corner, ◤◢) · antidiagonal (◥◣). ``at``: boundary position (two colours)
+    or a list of boundaries for more colours (default: equal bands).
+    """
+
+    def __init__(self, *colors: Union[str, Sequence[str]], split: str = "diagonal",
+                 at: Optional[Union[float, Sequence[float]]] = None, opacity: float = 1.0) -> None:
+        if len(colors) == 1 and not isinstance(colors[0], str):
+            colors = tuple(colors[0])  # type: ignore[assignment]
+        if len(colors) < 2:
+            raise ValueError("Split needs at least two colours")
+        if split not in _SPLITS:
+            raise ValueError(f"split must be one of {tuple(_SPLITS)}, got {split!r}")
+        self.colors = [str(c) for c in colors]
+        self.split = split
+        n = len(self.colors)
+        if at is None:
+            cuts = [i / n for i in range(1, n)]
+        elif isinstance(at, (int, float)):
+            if n != 2:
+                raise ValueError("a single at= works with two colours; pass a list")
+            cuts = [float(at)]
+        else:
+            cuts = [float(a) for a in at]
+            if len(cuts) != n - 1:
+                raise ValueError("at= needs len(colors) - 1 boundaries")
+        self.cuts = cuts
+        self.opacity = float(opacity)
+
+    def stops(self) -> List[Tuple[float, str]]:
+        out: List[Tuple[float, str]] = []
+        bounds = [0.0] + self.cuts + [1.0]
+        for i, c in enumerate(self.colors):
+            out.append((bounds[i], c))
+            out.append((bounds[i + 1], c))
+        return out
+
+    def vector(self) -> Tuple[float, float, float, float]:
+        return _SPLITS[self.split]
+
+
+def resolve_paint(buf: List[str], fill) -> str:
+    """Return an SVG paint string for ``fill`` (emitting gradient defs when needed)."""
+    if fill is None:
+        return "none"
+    if isinstance(fill, Paint):
+        return fill.ref(buf)
+    return str(fill)
+
+
+__all__ = ["Gradient", "Paint", "Split", "resolve_paint"]

codefig/flows.py

@@ -0,0 +1,102 @@
+"""Wrapped flows (v0.7.0): a long chain of steps folded into rows.
+
+``WrapFlow(tokens, per_row=5)`` lays the items out row by row and connects consecutive
+items with arrows. ``mode="snake"`` (default) reverses every other row so the chain turns
+down at the row end (boustrophedon — no long return arrows); ``mode="z"`` keeps every row
+left → right and routes the row-to-row connector back under the row. Items may be
+nodes or strings (→ :class:`~codefig.primitives.Box`). ``items[i]`` stays addressable
+for extra edges / highlights; ``flow.edge(i)`` is the arrow leaving item ``i``.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Sequence, Union
+
+from .edges import Diagram, Edge
+from .node import Grid, Node
+from .primitives import Box, Spacer
+from .styles import themed
+
+
+_ROUTER_PAD = 5.0  # obstacle padding used by Diagram routing (edges.collect_obstacles)
+
+
+class WrapFlow(Diagram):
+    """Chain of items folded into rows of ``per_row`` (see module docs).
+
+    per_row: items per row; ``max_w``: alternatively, fold so a row is at most this wide
+    (items measured at construction). gap: default spacing; ``col_gap`` (between items in
+    a row) and ``row_gap`` (between rows) override it per axis (v0.8.0). The default
+    ``row_gap`` in ``mode="z"`` leaves a clear lane for the return connectors. arrows: connect consecutive items (``edge=`` dict of Edge keywords,
+    e.g. ``edge={"color": "#0072B2"}``). ``equal=True`` gives every column the same width
+    so the snake's turns stay vertical.
+    """
+
+    flow_gap = themed(16.0)
+
+    def __init__(self, items: Sequence[Union[Node, str]], *, per_row: Optional[int] = None,
+                 max_w: Optional[float] = None, mode: str = "snake", gap: Optional[float] = None,
+                 row_gap: Optional[float] = None, col_gap: Optional[float] = None,
+                 arrows: bool = True,
+                 edge: Optional[Dict[str, Any]] = None, equal: bool = True,
+                 align: str = "center", **kwargs: Any) -> None:
+        if mode not in ("snake", "z"):
+            raise ValueError("mode must be snake|z")
+        nodes: List[Node] = [Box(t) if isinstance(t, str) else t for t in items]
+        if not nodes:
+            raise ValueError("WrapFlow needs at least one item")
+        self.flow_gap = gap
+        g = float(self.flow_gap)
+        cgap = g if col_gap is None else float(col_gap)
+        if per_row is None:
+            if max_w is None:
+                per_row = len(nodes)
+            else:
+                widths = [n.measure()[0] for n in nodes]
+                wmax = max(widths)
+                per_row = max(1, int((float(max_w) + cgap) // (wmax + cgap)))
+        per_row = max(1, int(per_row))
+        self.items = nodes
+        self.per_row = per_row
+        self.mode = mode
+        cells: List[Node] = []
+        rows = (len(nodes) + per_row - 1) // per_row
+        self._rc: List[tuple] = []
+        for r in range(rows):
+            chunk = nodes[r * per_row:(r + 1) * per_row]
+            rev = mode == "snake" and r % 2 == 1
+            row: List[Node] = list(reversed(chunk)) if rev else list(chunk)
+            pad = per_row - len(chunk)
+            if pad:
+                fill = [Spacer() for _ in range(pad)]
+                row = fill + row if rev else row + fill
+            cells += row
+        for i in range(len(nodes)):
+            r, c = divmod(i, per_row)
+            rev = mode == "snake" and r % 2 == 1
+            self._rc.append((r, per_row - 1 - c if rev else c, rev))
+        if row_gap is None:
+            # z-mode return legs run along the row gap: leave a lane clear of the
+            # router's obstacle padding (5 pt each side) plus a stub's worth of air.
+            row_gap = max(g, 2 * _ROUTER_PAD + self.theme.L(6.0)) if mode == "z" else g
+        grid = Grid(cells, cols=per_row, gap=g, row_gap=float(row_gap), col_gap=cgap,
+                    align=align, equal_cols=equal)
+        edges: List[Edge] = []
+        kw = dict(edge or {})
+        if arrows:
+            for i in range(len(nodes) - 1):
+                a, b = nodes[i], nodes[i + 1]
+                ra, _ca, reva = self._rc[i]
+                rb = self._rc[i + 1][0]
+                if ra == rb:
+                    if reva:
+                        edges.append(Edge(a.port("left"), b.port("right"), **kw))
+                    else:
+                        edges.append(Edge(a.port("right"), b.port("left"), **kw))
+                else:
+                    edges.append(Edge(a.port("bottom"), b.port("top"), **kw))
+        super().__init__(grid, edges, **kwargs)
+
+    def edge(self, i: int) -> Edge:
+        """The connector leaving item ``i``."""
+        return self.edges[i]

codefig/glyphs.py

@@ -0,0 +1,395 @@
+"""Small generic glyph primitives (v0.2.0): Badge, Divider, BarChart, VectorFan, Swatch.
+
+All are ordinary Nodes: they measure themselves, take part in flex layout and
+constraints, expose ports, and are visible to overlap checks / edge routing.
+None takes absolute coordinates.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Any, Callable, List, Optional, Sequence, Tuple, Union
+
+from .node import Node
+from .styles import theme_default
+from .textutil import measure_text
+
+_DASH = {"solid": None, "dashed": "5 3", "dotted": "1.5 2.5"}
+
+
+class Badge(Node):
+    """Text inside a pill, circle or rectangle sized to the text.
+
+    shape="pill" → tag/label pill (e.g. PREFILL); "circle" → circled number or
+    operator (①, ⊕ combiner); "rect" → plain chip.
+    """
+
+    stroke = theme_default("stroke")
+
+    def __init__(
+        self,
+        text: str = "",
+        *,
+        shape: str = "pill",
+        fill: str = "none",
+        stroke: Optional[str] = None,
+        stroke_width: float = 1.0,
+        text_color: str = "#111111",
+        font_size: Optional[float] = None,
+        weight: str = "normal",
+        pad: Optional[float] = None,
+        size: Optional[float] = None,  # circle: fixed diameter
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(**kwargs)
+        if shape not in ("pill", "circle", "rect"):
+            raise ValueError(f"Badge shape must be pill|circle|rect, got {shape!r}")
+        self.text = text
+        self.shape = shape
+        self.fill = fill
+        self.stroke = stroke
+        self.stroke_width = float(stroke_width)
+        self.text_color = text_color
+        self.font_size = font_size
+        self.weight = weight
+        self.pad = pad
+        self.size = size
+
+    def _fs(self) -> float:
+        return self.font_size if self.font_size is not None else self.theme.font_size
+
+    def _measure(self) -> Tuple[float, float]:
+        fs = self._fs()
+        tw, th = measure_text(self.text, fs, weight=self.weight) if self.text else (0.0, fs)
+        th = min(th, fs * 1.25 * max(1, self.text.count("\n") + 1))
+        if self.shape == "circle":
+            pad = fs * 0.12 if self.pad is None else self.pad
+            d = self.size if self.size is not None else max(tw, fs) + 2 * pad
+            return d, d
+        pad = fs * 0.35 if self.pad is None else self.pad
+        return tw + 2 * pad + (fs * 0.2 if self.shape == "pill" else 0), th + 2 * pad * 0.35
+
+    def draw(self, buf: List[str], ox: float = 0.0, oy: float = 0.0) -> None:
+        from .render_svg import draw_circle, draw_rect, draw_text
+
+        g = self.geom
+        x, y, w, h = g.x + ox, g.y + oy, g.w, g.h
+        sw = self.stroke_width if self.stroke not in (None, "none") else 0.0
+        if self.shape == "circle":
+            r = min(w, h) / 2 - sw / 2
+            draw_circle(buf, x + w / 2, y + h / 2, r, fill=self.fill, stroke=self.stroke or "none",
+                        stroke_width=sw, dasharray=self._dash(sw))
+        else:
+            rad = h / 2 if self.shape == "pill" else 2
+            draw_rect(buf, x + sw / 2, y + sw / 2, w - sw, h - sw, fill=self.fill,
+                      stroke=self.stroke or "none", stroke_width=sw, radius=rad,
+                      dasharray=self._dash(sw))
+        if self.text:
+            fs = self._fs()
+            tw, _ = measure_text(self.text, fs, weight=self.weight)
+            draw_text(buf, self.text, x + (w - tw) / 2, y + h / 2 + fs * 0.35, font_size=fs,
+                      fill=self.text_color, weight=self.weight)
+
+
+class Divider(Node):
+    """A separator line. In a Row/Col with align="stretch" it spans the cross axis.
+
+    orientation: vertical (in a Row) | horizontal (in a Col).
+    """
+
+    def __init__(
+        self,
+        orientation: str = "vertical",
+        *,
+        color: str = "#b0b0b0",
+        width: float = 1.0,
+        style: str = "dashed",
+        margin: float = 2.0,
+        **kwargs: Any,
+    ) -> None:
+        kwargs.setdefault("align_self", "stretch")
+        super().__init__(**kwargs)
+        if orientation not in ("vertical", "horizontal"):
+            raise ValueError("orientation must be vertical|horizontal")
+        self.orientation = orientation
+        self.color = color
+        self.width = float(width)
+        self.style = style
+        self.margin = float(margin)
+
+    def _measure(self) -> Tuple[float, float]:
+        t = self.width + 2 * self.margin
+        return (t, 1.0) if self.orientation == "vertical" else (1.0, t)
+
+    def draw(self, buf: List[str], ox: float = 0.0, oy: float = 0.0) -> None:
+        from .render_svg import draw_line
+
+        g = self.geom
+        if self.orientation == "vertical":
+            x = g.x + ox + g.w / 2
+            draw_line(buf, x, g.y + oy, x, g.y + oy + g.h, stroke=self.color,
+                      stroke_width=self.width, dasharray=_DASH.get(self.style, self.style))
+        else:
+            y = g.y + oy + g.h / 2
+            draw_line(buf, g.x + ox, y, g.x + ox + g.w, y, stroke=self.color,
+                      stroke_width=self.width, dasharray=_DASH.get(self.style, self.style))
+
+
+class BarChart(Node):
+    """Inline bar chart / sparkline: bars, highlighted bars, optional marker dots.
+
+    values:     bar heights (any unit; scaled so the tallest item = ``height``).
+    highlight:  {index: colour} or a set of indices (→ ``highlight_color``).
+    markers:    {index: value} — a dot drawn at that value above bar ``index``.
+    baseline:   draw an axis line under the bars.
+    """
+
+    def __init__(
+        self,
+        values: Sequence[float],
+        *,
+        height: float = 60.0,
+        bar_w: float = 6.0,
+        bar_gap: float = 1.5,
+        color: str = "#c4c4c4",
+        highlight: Optional[Union[dict, Sequence[int]]] = None,
+        highlight_color: str = "#2e6fd0",
+        markers: Optional[dict] = None,
+        marker_color: str = "#7d3c98",
+        marker_size: float = 5.0,
+        baseline: bool = True,
+        baseline_color: str = "#888888",
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(**kwargs)
+        if not values:
+            raise ValueError("BarChart needs at least one value")
+        self.values = [float(v) for v in values]
+        self.height = float(height)
+        self.bar_w = float(bar_w)
+        self.bar_gap = float(bar_gap)
+        self.color = color
+        if highlight is None:
+            self.highlight: dict = {}
+        elif isinstance(highlight, dict):
+            self.highlight = dict(highlight)
+        else:
+            self.highlight = {int(i): highlight_color for i in highlight}
+        self.markers = dict(markers or {})
+        self.marker_color = marker_color
+        self.marker_size = float(marker_size)
+        self.baseline = baseline
+        self.baseline_color = baseline_color
+
+    def _top(self) -> float:
+        return max(list(self.values) + [float(v) for v in self.markers.values()] + [1e-9])
+
+    def _measure(self) -> Tuple[float, float]:
+        n = len(self.values)
+        w = n * self.bar_w + (n - 1) * self.bar_gap
+        return w, self.height + (self.marker_size / 2 + 1 if self.markers else 0) + 1.5
+
+    def _bar_x(self, i: int) -> float:
+        return self.geom.x + i * (self.bar_w + self.bar_gap)
+
+    def _bar_cx(self, i: int) -> float:
+        return self._bar_x(i) + self.bar_w / 2
+
+    def bar_at(self, x: float) -> int:
+        """Index of the bar whose centre is nearest to page coordinate ``x``."""
+        return min(range(len(self.values)), key=lambda i: abs(self._bar_cx(i) - x))
+
+    def bar_anchor(self, i: int, which: str = "center"):
+        """x-Anchor on bar ``i`` (start | center | end) — e.g. ``Brace(span=(…))``."""
+        from .constraints import Anchor
+
+        if not -len(self.values) <= i < len(self.values):
+            raise IndexError(f"bar {i} out of range")
+        i = i % len(self.values)
+        off = {"start": 0.0, "left": 0.0, "center": 0.5, "end": 1.0, "right": 1.0}[which]
+        return Anchor(self, "x", getter=lambda: self._bar_x(i) + self.bar_w * off,
+                      label=f"bar[{i}].{which}")
+
+    def bars(self, i: int, j: int):
+        """(start-of-bar-i, end-of-bar-j) anchors — a span for ``Brace(span=…)``."""
+        return self.bar_anchor(i, "start"), self.bar_anchor(j, "end")
+
+    def bar_port(self, i: int, side: str = "top"):
+        """Port on bar ``i``: top → the bar's tip, bottom → under the baseline."""
+        from .edges import Port
+
+        if not 0 <= i < len(self.values):
+            raise IndexError(f"bar {i} out of range")
+        return Port(self, "cell", side, index=0, col_index=i)
+
+    def resolve_cell_port(self, _row: int, i: int, side: str):
+        g = self.geom
+        x = self._bar_x(i) + self.bar_w / 2
+        if side == "bottom":
+            return x, g.y + g.h, "down"
+        base = g.y + g.h - 1.5
+        return x, base - self.values[i] / self._top() * self.height, "up"
+
+    def draw(self, buf: List[str], ox: float = 0.0, oy: float = 0.0) -> None:
+        from .render_svg import draw_circle, draw_line, draw_rect
+
+        g = self.geom
+        base = g.y + oy + g.h - 1.5
+        top = self._top()
+        for i, v in enumerate(self.values):
+            h = v / top * self.height
+            x = self._bar_x(i) + ox
+            draw_rect(buf, x, base - h, self.bar_w, h, fill=self.highlight.get(i, self.color),
+                      stroke="none", stroke_width=0)
+        for i, v in self.markers.items():
+            if 0 <= int(i) < len(self.values):
+                cx = self._bar_x(int(i)) + ox + self.bar_w / 2
+                cy = base - float(v) / top * self.height
+                draw_circle(buf, cx, cy, self.marker_size / 2, fill=self.marker_color)
+        if self.baseline:
+            draw_line(buf, g.x + ox, base + 0.5, g.x + ox + g.w, base + 0.5,
+                      stroke=self.baseline_color, stroke_width=self.theme.SW(1.0))
+
+
+class VectorFan(Node):
+    """Arrows radiating from one origin, with optional faint axes — the usual
+    "vectors point in many / one direction(s)" sketch.
+
+    angles:  directions in degrees (0 = right, counter-clockwise).
+    lengths: optional per-arrow fractions of ``radius`` (default 1).
+    """
+
+    def __init__(
+        self,
+        angles: Sequence[float],
+        *,
+        lengths: Optional[Sequence[float]] = None,
+        radius: float = 22.0,
+        color: str = "#1f3a68",
+        colors: Optional[Sequence[str]] = None,
+        width: float = 1.1,
+        head_size: float = 4.5,
+        axes: bool = True,
+        axes_color: str = "#c8c8c8",
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(**kwargs)
+        self.angles = [float(a) for a in angles]
+        if lengths is not None and len(lengths) != len(self.angles):
+            raise ValueError("lengths must match angles")
+        self.lengths = [float(x) for x in lengths] if lengths is not None else [1.0] * len(self.angles)
+        self.radius = float(radius)
+        self.color = color
+        self.colors = list(colors) if colors is not None else None
+        self.width = float(width)
+        self.head_size = float(head_size)
+        self.axes = axes
+        self.axes_color = axes_color
+
+    def _measure(self) -> Tuple[float, float]:
+        d = 2 * (self.radius + self.head_size * 0.5 + 2)
+        return d, d
+
+    def draw(self, buf: List[str], ox: float = 0.0, oy: float = 0.0) -> None:
+        from .render_svg import draw_arrowhead, draw_line
+
+        g = self.geom
+        cx, cy = g.x + ox + g.w / 2, g.y + oy + g.h / 2
+        r = self.radius
+        if self.axes:
+            draw_line(buf, cx - r * 1.1, cy, cx + r * 1.1, cy, stroke=self.axes_color, stroke_width=self.theme.SW(0.8))
+            draw_line(buf, cx, cy - r * 1.1, cx, cy + r * 1.1, stroke=self.axes_color, stroke_width=self.theme.SW(0.8))
+        for k, (a, f) in enumerate(zip(self.angles, self.lengths)):
+            col = self.colors[k % len(self.colors)] if self.colors else self.color
+            t = math.radians(a)
+            ex, ey = cx + math.cos(t) * r * f, cy - math.sin(t) * r * f
+            draw_line(buf, cx, cy, ex, ey, stroke=col, stroke_width=self.width)
+            draw_arrowhead(buf, ex, ey, math.atan2(ey - cy, ex - cx), size=self.head_size, color=col)
+
+
+class Swatch(Node):
+    """Legend key: kind = square | rect | dot | line | arrow.
+
+    line / arrow honour ``style`` (solid | dashed | dotted | custom dash) and arrows
+    take ``head`` / ``tail`` / ``hollow`` like Edge; square / rect take ``fill``-colour
+    ``color``, ``stroke``, ``border`` and ``pattern`` (e.g. ``Hatch()``).
+    """
+
+    def __init__(
+        self,
+        kind: str = "square",
+        *,
+        color: str = "#2e6fd0",
+        size: float = 9.0,
+        length: float = 22.0,
+        width: float = 1.5,
+        style: Any = "solid",
+        head: Any = None,
+        tail: Any = None,
+        hollow: Optional[bool] = None,
+        head_size: Optional[float] = None,
+        stroke: Optional[str] = None,
+        pattern: Any = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(**kwargs)
+        if kind not in ("square", "rect", "dot", "line", "arrow"):
+            raise ValueError("Swatch kind must be square|rect|dot|line|arrow")
+        self.kind = kind
+        self.color = color
+        self.size = float(size)
+        self.length = float(length)
+        self.width = float(width)
+        self.style = style
+        self.head = head
+        self.tail = tail
+        self.hollow = hollow
+        self.head_size = head_size
+        self.stroke = stroke
+        self.pattern = pattern
+
+    def _measure(self) -> Tuple[float, float]:
+        if self.kind in ("line", "arrow"):
+            return self.length, max(self.size, 6.0)
+        if self.kind == "rect":
+            return self.length, self.size
+        return self.size, self.size
+
+    def draw(self, buf: List[str], ox: float = 0.0, oy: float = 0.0) -> None:
+        from .legend import Key, draw_key
+
+        g = self.geom
+        x, y, w, h = g.x + ox, g.y + oy, g.w, g.h
+        if self.kind in ("square", "rect"):
+            s = min(w, h)
+            bw = s if self.kind == "square" else w
+            stroke = self.stroke if self.stroke is not None else (
+                "#555555" if self.border not in (None, "none") else "none")
+            k = Key("", kind="box", fill=self.color, stroke=stroke, border=self.border,
+                    pattern=self.pattern, radius=0.0)
+            if stroke == "none":
+                from .render_svg import draw_rect
+
+                draw_rect(buf, x + (w - bw) / 2, y + (h - s) / 2, bw, s, fill=self.color,
+                          stroke="none", stroke_width=0)
+                if self.pattern is not None:
+                    from .primitives import _paint_node_pattern
+
+                    _paint_node_pattern(buf, self.pattern, x + (w - bw) / 2, y + (h - s) / 2, bw, s)
+            else:
+                draw_key(buf, k, x + (w - bw) / 2, y + (h - s) / 2, bw, s, theme=self.theme)
+        elif self.kind == "dot":
+            from .render_svg import draw_circle
+
+            draw_circle(buf, x + w / 2, y + h / 2, min(w, h) / 2, fill=self.color)
+        else:
+            head = self.head if self.head is not None else ("triangle" if self.kind == "arrow" else "none")
+            from .styles import Head
+
+            if self.head_size is not None and isinstance(head, str):
+                head = Head(head, size=self.head_size)
+            elif self.head_size is None and isinstance(head, str) and head != "none":
+                head = Head(head, size=6.0)
+            k = Key("", kind="arrow", color=self.color, style=self.style, width=self.width,
+                    head=head, tail=self.tail, hollow=self.hollow)
+            draw_key(buf, k, x, y, w, h, theme=self.theme)