codefig 0.17.0__py3-none-any.whl

codefig/shapes.py

@@ -0,0 +1,642 @@
+"""Outline shapes with the full Box API (v0.4.0).
+
+Every shape is a :class:`~codefig.primitives.Box` subclass — text / rich markup /
+subtitle, ``fill=`` (colour, Gradient, Split), ``stroke``, ``border=``, ``pattern=``
+(hatch, clipped to the outline), ``icon=`` / ``badge=``, ``legend=`` — that sizes itself
+so the label fits *inside* the outline, and whose ports sit on the true outline
+(``shape.port("top", at=0.2)`` lands on the curve, not on the bounding box;
+``port("auto")`` aims at the other end of the edge). Role: hard (as Box).
+
+Ellipse · Circle · OpCircle (⊕ ⊗ ⊙ …) · Op (bare ×, +) · Cylinder · Document · Trapezoid ·
+Triangle · Polygon · Parallelogram · Hexagon · Diamond · ChatBubble · BlockArrow
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Any, List, Optional, Sequence, Tuple
+
+from .primitives import Box, _paint_node_pattern
+
+Pt = Tuple[float, float]
+SQ2 = math.sqrt(2.0)
+
+
+def _f(v: float) -> str:
+    return f"{v:.2f}"
+
+
+def _poly_d(pts: Sequence[Pt]) -> str:
+    return "M " + " L ".join(f"{_f(x)},{_f(y)}" for x, y in pts) + " Z"
+
+
+def _ellipse_pts(cx: float, cy: float, rx: float, ry: float, a0: float = 0.0, a1: float = 2 * math.pi,
+                 n: int = 48) -> List[Pt]:
+    return [(cx + rx * math.cos(a0 + (a1 - a0) * i / n), cy + ry * math.sin(a0 + (a1 - a0) * i / n))
+            for i in range(n + 1)]
+
+
+class Shape(Box):
+    """Base class: subclasses define ``_frame_size`` / ``_text_rect`` / ``_outline``."""
+
+    _seq = 0
+
+    # -- geometry hooks ---------------------------------------------------------------
+    def _outline(self, x: float, y: float, w: float, h: float) -> List[Pt]:
+        """Closed outline polygon (sampled for curves), page coordinates."""
+        return [(x, y), (x + w, y), (x + w, y + h), (x, y + h)]
+
+    def _path(self, x: float, y: float, w: float, h: float) -> str:
+        """SVG path ``d`` of the outline (curves exact where possible)."""
+        return _poly_d(self._outline(x, y, w, h))
+
+    def _decorate(self, buf: List[str], x: float, y: float, w: float, h: float) -> None:
+        """Extra strokes drawn over the fill (cylinder rim, operator glyph, …)."""
+
+    # -- outline queries (used by ports / overlap checks) ------------------------------
+    def outline_polygon(self) -> List[Pt]:
+        g = self.geom
+        return self._outline(g.x, g.y, g.w, g.h)
+
+    def outline_point(self, side: str, x: float, y: float) -> Pt:
+        """Where a ray entering from ``side`` along the port's axis first meets the outline."""
+        poly = self.outline_polygon()
+        xs = [p[0] for p in poly]
+        ys = [p[1] for p in poly]
+        if side in ("top", "bottom"):
+            v = min(max(x, min(xs) + 0.5), max(xs) - 0.5)
+            hits = _hits(poly, v, vertical=True)
+            if not hits:
+                return x, y
+            return v, (min(hits) if side == "top" else max(hits))
+        if side in ("left", "right"):
+            v = min(max(y, min(ys) + 0.5), max(ys) - 0.5)
+            hits = _hits(poly, v, vertical=False)
+            if not hits:
+                return x, y
+            return (min(hits) if side == "left" else max(hits)), v
+        return x, y
+
+    def ray_point(self, dx: float, dy: float) -> Pt:
+        """Outline point in direction (dx, dy) from the centre of the label area."""
+        g = self.geom
+        tx, ty, tw, th = self._text_rect(g.x, g.y, g.w, g.h)
+        return ray_hit(self.outline_polygon(), tx + tw / 2, ty + th / 2, dx, dy)
+
+    # -- drawing ------------------------------------------------------------------------
+    def _draw_frame(self, buf: List[str], x: float, y: float, w: float, h: float) -> None:
+        from .render_svg import draw_path
+
+        d = self._path(x, y, w, h)
+        stroke = self._border_stroke(self.stroke)
+        draw_path(buf, d, fill=self.fill, stroke="none", stroke_width=0)
+        if self.pattern is not None:
+            Shape._seq += 1
+            cid = f"cf-shape-{Shape._seq}"
+            buf.append(f'<defs><clipPath id="{cid}"><path d="{d}"/></clipPath></defs>'
+                       f'<g clip-path="url(#{cid})">')
+            _paint_node_pattern(buf, self.pattern, x, y, w, h)
+            buf.append("</g>")
+        if stroke not in (None, "none") and self.stroke_width > 0:
+            draw_path(buf, d, fill="none", stroke=stroke, stroke_width=self.stroke_width,
+                      dasharray=self._dash(self.stroke_width))
+        self._decorate(buf, x, y, w, h)
+
+
+def _hits(poly: Sequence[Pt], v: float, *, vertical: bool) -> List[float]:
+    out = []
+    n = len(poly)
+    for i in range(n):
+        (x1, y1), (x2, y2) = poly[i], poly[(i + 1) % n]
+        a1, a2, b1, b2 = (x1, x2, y1, y2) if vertical else (y1, y2, x1, x2)
+        if (a1 - v) * (a2 - v) > 0 or a1 == a2:
+            if a1 == a2 == v:
+                out += [b1, b2]
+            continue
+        t = (v - a1) / (a2 - a1)
+        out.append(b1 + t * (b2 - b1))
+    return out
+
+
+def ray_hit(poly: Sequence[Pt], cx: float, cy: float, dx: float, dy: float) -> Pt:
+    """First intersection of the ray (cx, cy) + t·(dx, dy), t > 0, with a closed polygon."""
+    best = None
+    n = len(poly)
+    for i in range(n):
+        (x1, y1), (x2, y2) = poly[i], poly[(i + 1) % n]
+        ex, ey = x2 - x1, y2 - y1
+        den = dx * ey - dy * ex
+        if abs(den) < 1e-12:
+            continue
+        t = ((x1 - cx) * ey - (y1 - cy) * ex) / den
+        u = ((x1 - cx) * dy - (y1 - cy) * dx) / den
+        if t > 1e-9 and -1e-9 <= u <= 1 + 1e-9 and (best is None or t > best):
+            best = t  # farthest crossing = the outer boundary for star-shaped outlines
+    if best is None:
+        return cx, cy
+    return cx + dx * best, cy + dy * best
+
+
+# ---------------------------------------------------------------------------- ellipse family
+class Ellipse(Shape):
+    """Ellipse sized so the label rectangle is inscribed (w, h = √2 × label box)."""
+
+    def _frame_size(self, iw: float, ih: float) -> Tuple[float, float]:
+        return iw * SQ2, ih * SQ2
+
+    def _text_rect(self, x, y, w, h):
+        iw, ih = w / SQ2, h / SQ2
+        return x + (w - iw) / 2, y + (h - ih) / 2, iw, ih
+
+    def _outline(self, x, y, w, h):
+        return _ellipse_pts(x + w / 2, y + h / 2, w / 2, h / 2, n=72)[:-1]
+
+    def _path(self, x, y, w, h):
+        rx, ry, cy = w / 2, h / 2, y + h / 2
+        return (f"M {_f(x)},{_f(cy)} A {_f(rx)},{_f(ry)} 0 1 1 {_f(x + w)},{_f(cy)} "
+                f"A {_f(rx)},{_f(ry)} 0 1 1 {_f(x)},{_f(cy)} Z")
+
+
+class Circle(Ellipse):
+    """Circle around the label; ``size=`` fixes the diameter.
+
+    Without ``size=`` the diameter follows the label: about the label's width plus the
+    theme padding, so a larger ``font_size`` (or a longer label) makes a larger circle.
+    Pass ``size=`` to keep several circles equal."""
+
+    def __init__(self, text: str = "", *, size: Optional[float] = None, **kwargs: Any) -> None:
+        if size is not None:
+            kwargs.setdefault("w", float(size))
+            kwargs.setdefault("h", float(size))
+        super().__init__(text, **kwargs)
+
+    def _frame_size(self, iw, ih):
+        d = math.hypot(iw, ih)
+        return d, d
+
+    def _measure(self):
+        w, h = super()._measure()
+        d = max(w, h) if (self.fixed_w is None or self.fixed_h is None) else min(w, h)
+        return d, d
+
+    def _text_rect(self, x, y, w, h):
+        d = min(w, h)
+        s = d / SQ2
+        return x + (w - s) / 2, y + (h - s) / 2, s, s
+
+    def _outline(self, x, y, w, h):
+        r = min(w, h) / 2
+        return _ellipse_pts(x + w / 2, y + h / 2, r, r, n=72)[:-1]
+
+    def _path(self, x, y, w, h):
+        r = min(w, h) / 2
+        cx, cy = x + w / 2, y + h / 2
+        return (f"M {_f(cx - r)},{_f(cy)} A {_f(r)},{_f(r)} 0 1 1 {_f(cx + r)},{_f(cy)} "
+                f"A {_f(r)},{_f(r)} 0 1 1 {_f(cx - r)},{_f(cy)} Z")
+
+
+_OPS = {"+": "plus", "plus": "plus", "add": "plus", "⊕": "plus",
+        "x": "times", "×": "times", "*": "times", "times": "times", "mul": "times", "⊗": "times",
+        "dot": "dot", "·": "dot", "⊙": "dot", "hadamard": "dot",
+        "-": "minus", "minus": "minus", "⊖": "minus", "c": "concat", "concat": "concat",
+        "||": "concat"}
+
+
+class OpCircle(Circle):
+    """Small operator node: ``op`` = + (⊕) · × (⊗) · dot (⊙) · − · concat (‖), drawn
+    geometrically; any other string (σ, Σ, ∫, "C") is set as text. Default diameter
+    ≈ 1.6 × font size."""
+
+    def __init__(self, op: str = "+", *, size: Optional[float] = None, color: Optional[str] = None,
+                 **kwargs: Any) -> None:
+        self.op = op
+        self.op_kind = _OPS.get(op)
+        self.op_color = color
+        kwargs.setdefault("pad", 0)
+        kwargs.setdefault("text_margin", 0)
+        super().__init__("" if self.op_kind else op, size=size, **kwargs)
+        if size is None and self.fixed_w is None:
+            d = round(self._fs() * 1.6, 1)
+            if not self.op_kind:
+                d = max(d, super()._measure()[0])
+            self.fixed_w = self.fixed_h = d
+            self.size_w = self.size_h = d
+
+    def _decorate(self, buf, x, y, w, h):
+        if not self.op_kind:
+            return
+        from .render_svg import draw_circle, draw_path
+
+        r = min(w, h) / 2
+        cx, cy = x + w / 2, y + h / 2
+        col = self.op_color or self._border_stroke(self.stroke) or self.text_color
+        if col == "none":
+            col = self.text_color
+        sw = max(self.theme.SW(1.0), self.stroke_width)
+        a = r * 0.55
+        if self.op_kind == "plus":
+            d = f"M {_f(cx - a)},{_f(cy)} L {_f(cx + a)},{_f(cy)} M {_f(cx)},{_f(cy - a)} L {_f(cx)},{_f(cy + a)}"
+        elif self.op_kind == "times":
+            b = a * 0.72
+            d = (f"M {_f(cx - b)},{_f(cy - b)} L {_f(cx + b)},{_f(cy + b)} "
+                 f"M {_f(cx + b)},{_f(cy - b)} L {_f(cx - b)},{_f(cy + b)}")
+        elif self.op_kind == "minus":
+            d = f"M {_f(cx - a)},{_f(cy)} L {_f(cx + a)},{_f(cy)}"
+        elif self.op_kind == "concat":
+            q = a * 0.35
+            d = (f"M {_f(cx - q)},{_f(cy - a)} L {_f(cx - q)},{_f(cy + a)} "
+                 f"M {_f(cx + q)},{_f(cy - a)} L {_f(cx + q)},{_f(cy + a)}")
+        else:  # dot
+            draw_circle(buf, cx, cy, max(1.4, r * 0.22), fill=col)
+            return
+        draw_path(buf, d, stroke=col, stroke_width=sw)
+
+
+class Op(OpCircle):
+    """v0.12.0: a bare operator glyph — ``Op("×")`` / ``Op("+")`` / ``Op("·")`` — drawn
+    without the circle, about as tall as a panel title (``size=`` overrides). Use it
+    between blocks (``Row([a, Op("×"), b])``); ports sit on its (invisible) circle."""
+
+    def __init__(self, op: str = "×", *, size: Optional[float] = None, **kwargs: Any) -> None:
+        kwargs.setdefault("stroke", "none")
+        kwargs.setdefault("fill", "none")
+        super().__init__(op, size=size, **kwargs)
+        if size is None:
+            d = round(max(self.theme.panel_title_size, self._fs()) * 1.25, 1)
+            if not self.op_kind:
+                d = max(d, Circle._measure(self)[0])
+            self.fixed_w = self.fixed_h = d
+            self.size_w = self.size_h = d
+
+    def _decorate(self, buf, x, y, w, h):
+        if not self.op_kind:
+            return
+        sw0 = self.stroke_width
+        self.stroke_width = max(self.theme.SW(1.4), sw0)
+        try:
+            super()._decorate(buf, x, y, w, h)
+        finally:
+            self.stroke_width = sw0
+
+
+# ---------------------------------------------------------------------------- cylinder / doc
+class Cylinder(Shape):
+    """Database / storage drum. ``cap``: ellipse half-height (default from width)."""
+
+    def __init__(self, text: str = "", *, cap: Optional[float] = None, **kwargs: Any) -> None:
+        self.cap = cap
+        super().__init__(text, **kwargs)
+
+    def _ry(self, w: float) -> float:
+        return self.cap if self.cap is not None else max(4.0, min(12.0, w * 0.1))
+
+    def _frame_size(self, iw, ih):
+        return iw, ih + 3 * self._ry(iw)
+
+    def _text_rect(self, x, y, w, h):
+        ry = self._ry(w)
+        return x, y + 2 * ry, w, h - 3 * ry
+
+    def _outline(self, x, y, w, h):
+        ry, rx = self._ry(w), w / 2
+        top = _ellipse_pts(x + rx, y + ry, rx, ry, math.pi, 2 * math.pi, 24)
+        bot = _ellipse_pts(x + rx, y + h - ry, rx, ry, 0, math.pi, 24)
+        return top + bot
+
+    def _path(self, x, y, w, h):
+        ry, rx = self._ry(w), w / 2
+        return (f"M {_f(x)},{_f(y + ry)} A {_f(rx)},{_f(ry)} 0 0 1 {_f(x + w)},{_f(y + ry)} "
+                f"L {_f(x + w)},{_f(y + h - ry)} A {_f(rx)},{_f(ry)} 0 0 1 {_f(x)},{_f(y + h - ry)} Z")
+
+    def _decorate(self, buf, x, y, w, h):
+        from .render_svg import draw_path
+
+        stroke = self._border_stroke(self.stroke)
+        if stroke in (None, "none"):
+            return
+        ry, rx = self._ry(w), w / 2
+        draw_path(buf, f"M {_f(x)},{_f(y + ry)} A {_f(rx)},{_f(ry)} 0 0 0 {_f(x + w)},{_f(y + ry)}",
+                  stroke=stroke, stroke_width=self.stroke_width, dasharray=self._dash(self.stroke_width))
+
+
+class Document(Shape):
+    """Page with a wavy bottom edge (flow-chart document)."""
+
+    def _amp(self, w: float) -> float:
+        return max(2.5, min(6.0, w * 0.045))
+
+    def _frame_size(self, iw, ih):
+        return iw, ih + 2 * self._amp(iw)
+
+    def _text_rect(self, x, y, w, h):
+        return x, y, w, h - 2 * self._amp(w)
+
+    def _wave(self, x, y, w, h, n=20) -> List[Pt]:
+        a = self._amp(w)
+        base = y + h - a
+        return [(x + w - w * i / n, base - a * math.sin(2 * math.pi * i / n)) for i in range(n + 1)]
+
+    def _outline(self, x, y, w, h):
+        return [(x, y), (x + w, y)] + self._wave(x, y, w, h)
+
+    def _path(self, x, y, w, h):
+        a = self._amp(w)
+        b = y + h - a
+        k = a * 2.0  # cubic control offset ≈ a sine of amplitude a
+        return (f"M {_f(x)},{_f(y)} L {_f(x + w)},{_f(y)} L {_f(x + w)},{_f(b)} "
+                f"C {_f(x + w * 0.83)},{_f(b - k)} {_f(x + w * 0.67)},{_f(b - k)} {_f(x + w / 2)},{_f(b)} "
+                f"C {_f(x + w * 0.33)},{_f(b + k)} {_f(x + w * 0.17)},{_f(b + k)} {_f(x)},{_f(b)} Z")
+
+
+# ---------------------------------------------------------------------------- polygons
+class Trapezoid(Shape):
+    """Trapezoid; ``narrow`` = the short side (top | bottom | left | right), ``ratio`` =
+    short / long side, within 0.05..1 (1 = a rectangle; for a point use ``Triangle``). ``narrow="right"`` is the classic encoder (wide input, narrow
+    output); ``narrow="left"`` a decoder."""
+
+    def __init__(self, text: str = "", *, narrow: str = "top", ratio: float = 0.6, **kwargs: Any) -> None:
+        if narrow not in ("top", "bottom", "left", "right"):
+            raise ValueError("narrow must be top|bottom|left|right")
+        if not 0.05 <= ratio <= 1.0:
+            raise ValueError("ratio must be within 0.05..1")
+        self.narrow = narrow
+        self.ratio = float(ratio)
+        super().__init__(text, **kwargs)
+
+    def _frame_size(self, iw, ih):
+        k = 1.12  # slack along the parallel-side axis
+        t = (1 + 1 / k) / 2  # where the label rectangle's narrow end sits (fraction)
+        shrink = 1 - (1 - self.ratio) * t
+        if self.narrow in ("left", "right"):
+            return iw * k, ih / shrink
+        return iw / shrink, ih * k
+
+    def _text_rect(self, x, y, w, h):
+        k = 1.12
+        t = (1 + 1 / k) / 2
+        shrink = 1 - (1 - self.ratio) * t
+        if self.narrow in ("left", "right"):
+            iw, ih = w / k, h * shrink
+        else:
+            iw, ih = w * shrink, h / k
+        return x + (w - iw) / 2, y + (h - ih) / 2, iw, ih
+
+    def _outline(self, x, y, w, h):
+        r = self.ratio
+        if self.narrow == "top":
+            d = w * (1 - r) / 2
+            return [(x + d, y), (x + w - d, y), (x + w, y + h), (x, y + h)]
+        if self.narrow == "bottom":
+            d = w * (1 - r) / 2
+            return [(x, y), (x + w, y), (x + w - d, y + h), (x + d, y + h)]
+        d = h * (1 - r) / 2
+        if self.narrow == "right":
+            return [(x, y), (x + w, y + d), (x + w, y + h - d), (x, y + h)]
+        return [(x, y + d), (x + w, y), (x + w, y + h), (x, y + h - d)]
+
+
+class Triangle(Shape):
+    """v0.12.0: isosceles triangle; ``direction`` = where the apex points
+    (up | down | left | right). The label sits in the wide half (inscribed box ×2)."""
+
+    def __init__(self, text: str = "", *, direction: str = "up", **kwargs: Any) -> None:
+        if direction not in ("up", "down", "left", "right"):
+            raise ValueError("Triangle direction must be up|down|left|right")
+        self.direction = direction
+        super().__init__(text, **kwargs)
+
+    def _frame_size(self, iw, ih):
+        return iw * 2.0, ih * 2.0
+
+    def _text_rect(self, x, y, w, h):
+        d = self.direction
+        if d == "up":
+            return x + w / 4, y + h / 2, w / 2, h / 2
+        if d == "down":
+            return x + w / 4, y, w / 2, h / 2
+        if d == "left":
+            return x + w / 2, y + h / 4, w / 2, h / 2
+        return x, y + h / 4, w / 2, h / 2
+
+    def _outline(self, x, y, w, h):
+        d = self.direction
+        if d == "up":
+            return [(x + w / 2, y), (x + w, y + h), (x, y + h)]
+        if d == "down":
+            return [(x, y), (x + w, y), (x + w / 2, y + h)]
+        if d == "left":
+            return [(x, y + h / 2), (x + w, y), (x + w, y + h)]
+        return [(x, y), (x + w, y + h / 2), (x, y + h)]
+
+
+class Polygon(Shape):
+    """v0.12.0: any closed outline — ``Polygon(points=[(0.5, 0), (1, 1), (0, 1)])`` in unit
+    coordinates of the node box (0..1, y down). ``text_box=(fx, fy, fw, fh)`` (unit
+    coordinates too) is where the label goes; the node grows so the label fits it
+    (default: the central half, ``(0.25, 0.25, 0.5, 0.5)``)."""
+
+    def __init__(self, text: str = "", *, points: Sequence[Pt] = (), text_box: Optional[Sequence[float]] = None,
+                 **kwargs: Any) -> None:
+        pts = [(float(a), float(b)) for a, b in points]
+        if len(pts) < 3:
+            raise ValueError("Polygon needs at least 3 points")
+        if any(not (-1e-9 <= a <= 1 + 1e-9 and -1e-9 <= b <= 1 + 1e-9) for a, b in pts):
+            raise ValueError("Polygon points must use unit coordinates within 0..1 (x right, y down); set w=/h= for physical size")
+        tb = tuple(float(v) for v in (text_box or (0.25, 0.25, 0.5, 0.5)))
+        if len(tb) != 4 or tb[2] <= 0 or tb[3] <= 0:
+            raise ValueError("text_box must be (fx, fy, fw, fh) with fw, fh > 0")
+        self.points, self.text_box = pts, tb
+        super().__init__(text, **kwargs)
+
+    def _frame_size(self, iw, ih):
+        return iw / self.text_box[2], ih / self.text_box[3]
+
+    def _text_rect(self, x, y, w, h):
+        fx, fy, fw, fh = self.text_box
+        return x + fx * w, y + fy * h, fw * w, fh * h
+
+    def _outline(self, x, y, w, h):
+        return [(x + a * w, y + b * h) for a, b in self.points]
+
+
+class Parallelogram(Shape):
+    """Slanted box (data / IO). ``skew`` = horizontal offset as a fraction of height."""
+
+    def __init__(self, text: str = "", *, skew: float = 0.35, **kwargs: Any) -> None:
+        self.skew = float(skew)
+        super().__init__(text, **kwargs)
+
+    def _frame_size(self, iw, ih):
+        return iw + 2 * self.skew * ih, ih
+
+    def _text_rect(self, x, y, w, h):
+        d = self.skew * h
+        return x + d, y, w - 2 * d, h
+
+    def _outline(self, x, y, w, h):
+        d = self.skew * h
+        return [(x + d, y), (x + w, y), (x + w - d, y + h), (x, y + h)]
+
+
+class Hexagon(Shape):
+    """Flat-topped hexagon (pointed left / right). ``cut`` = point depth / height."""
+
+    def __init__(self, text: str = "", *, cut: float = 0.3, **kwargs: Any) -> None:
+        self.cut = float(cut)
+        super().__init__(text, **kwargs)
+
+    def _frame_size(self, iw, ih):
+        return iw + 2 * self.cut * ih, ih
+
+    def _text_rect(self, x, y, w, h):
+        c = self.cut * h
+        return x + c, y, w - 2 * c, h
+
+    def _outline(self, x, y, w, h):
+        c = self.cut * h
+        return [(x + c, y), (x + w - c, y), (x + w, y + h / 2), (x + w - c, y + h),
+                (x + c, y + h), (x, y + h / 2)]
+
+
+class Diamond(Shape):
+    """Decision rhombus (label inscribed: 2 × label box)."""
+
+    def _frame_size(self, iw, ih):
+        return iw * 2, ih * 2
+
+    def _text_rect(self, x, y, w, h):
+        return x + w / 4, y + h / 4, w / 2, h / 2
+
+    def _outline(self, x, y, w, h):
+        return [(x + w / 2, y), (x + w, y + h / 2), (x + w / 2, y + h), (x, y + h / 2)]
+
+
+_TAILS = ("bottom-left", "bottom-right", "top-left", "top-right", "left", "right")
+
+
+class ChatBubble(Shape):
+    """Speech bubble: rounded body + a tail (``tail`` = bottom-left | bottom-right |
+    top-left | top-right | left | right; ``tail_size`` px)."""
+
+    def __init__(self, text: str = "", *, tail: str = "bottom-left", tail_size: float = 9.0,
+                 **kwargs: Any) -> None:
+        if tail not in _TAILS:
+            raise ValueError(f"tail must be one of {_TAILS}")
+        self.tail = tail
+        self.tail_size = float(tail_size)
+        kwargs.setdefault("rounded", True)
+        super().__init__(text, **kwargs)
+
+    def _frame_size(self, iw, ih):
+        t = self.tail_size
+        return (iw + t, ih) if self.tail in ("left", "right") else (iw, ih + t)
+
+    def _text_rect(self, x, y, w, h):
+        t = self.tail_size
+        if self.tail == "left":
+            return x + t, y, w - t, h
+        if self.tail == "right":
+            return x, y, w - t, h
+        if self.tail.startswith("top"):
+            return x, y + t, w, h - t
+        return x, y, w, h - t
+
+    def _r(self, w, h) -> float:
+        r = self.radius if self.radius is not None else max(self.theme.corner_radius, 6.0)
+        return min(r, w / 2, h / 2) if self.rounded else 0.0
+
+    def _outline(self, x, y, w, h):
+        bx, by, bw, bh = self._text_rect(x, y, w, h)
+        r = self._r(bw, bh)
+        t = self.tail_size
+        pts: List[Pt] = []
+
+        def arc(cx, cy, a0, a1):
+            pts.extend(_ellipse_pts(cx, cy, r, r, a0, a1, 6) if r > 0 else [(cx, cy)])
+
+        # clockwise from the top-left corner, inserting the tail on its side
+        arc(bx + r, by + r, math.pi, 1.5 * math.pi)
+        if self.tail.startswith("top"):
+            tx = bx + (bw * 0.25 if self.tail.endswith("left") else bw * 0.75)
+            pts += [(tx - t * 0.6, by), (tx - t * 0.2 if self.tail.endswith("left") else tx + t * 0.6, by - t),
+                    (tx + t * 0.6, by)]
+        arc(bx + bw - r, by + r, 1.5 * math.pi, 2 * math.pi)
+        if self.tail == "right":
+            ty = by + bh / 2
+            pts += [(bx + bw, ty - t * 0.6), (bx + bw + t, ty + t * 0.3), (bx + bw, ty + t * 0.6)]
+        arc(bx + bw - r, by + bh - r, 0, 0.5 * math.pi)
+        if self.tail.startswith("bottom"):
+            tx = bx + (bw * 0.25 if self.tail.endswith("left") else bw * 0.75)
+            pts += [(tx + t * 0.6, by + bh), (tx - t * 0.6 if self.tail.endswith("left") else tx + t * 0.2, by + bh + t),
+                    (tx - t * 0.6, by + bh)]
+        arc(bx + r, by + bh - r, 0.5 * math.pi, math.pi)
+        if self.tail == "left":
+            ty = by + bh / 2
+            pts += [(bx, ty + t * 0.6), (bx - t, ty + t * 0.3), (bx, ty - t * 0.6)]
+        return pts
+
+
+class BlockArrow(Shape):
+    """Fat arrow with the label in its shaft. ``direction`` right | left | up | down |
+    both (↔) | both-vertical (↕); ``shaft`` = shaft thickness / total thickness."""
+
+    def __init__(self, text: str = "", *, direction: str = "right", shaft: float = 0.58,
+                 head: Optional[float] = None, **kwargs: Any) -> None:
+        if direction not in ("right", "left", "up", "down", "both", "both-vertical"):
+            raise ValueError("direction must be right|left|up|down|both|both-vertical")
+        self.direction = direction
+        self.shaft = float(shaft)
+        self.head = head
+        super().__init__(text, **kwargs)
+
+    def _horizontal(self) -> bool:
+        return self.direction in ("right", "left", "both")
+
+    def _heads(self) -> int:
+        return 2 if self.direction.startswith("both") else 1
+
+    def _hl(self, thick: float) -> float:
+        return self.head if self.head is not None else thick * 0.55
+
+    def _frame_size(self, iw, ih):
+        if self._horizontal():
+            th = ih / self.shaft
+            return iw + self._heads() * self._hl(th), th
+        tw = iw / self.shaft
+        return tw, ih + self._heads() * self._hl(tw)
+
+    def _text_rect(self, x, y, w, h):
+        if self._horizontal():
+            hl, s = self._hl(h), h * self.shaft
+            x0 = x + (hl if self.direction in ("left", "both") else 0)
+            return x0, y + (h - s) / 2, w - self._heads() * hl, s
+        hl, s = self._hl(w), w * self.shaft
+        y0 = y + (hl if self.direction in ("up", "both-vertical") else 0)
+        return x + (w - s) / 2, y0, s, h - self._heads() * hl
+
+    def _outline(self, x, y, w, h):
+        if self._horizontal():
+            hl = self._hl(h)
+            s0, s1 = y + h * (1 - self.shaft) / 2, y + h * (1 + self.shaft) / 2
+            cy = y + h / 2
+            L = x + (hl if self.direction in ("left", "both") else 0)
+            R = x + w - (hl if self.direction in ("right", "both") else 0)
+            right = [(R, s0), (R, y), (x + w, cy), (R, y + h), (R, s1)] if self.direction in ("right", "both") \
+                else [(R, s0), (R, s1)]
+            left = [(L, s1), (L, y + h), (x, cy), (L, y), (L, s0)] if self.direction in ("left", "both") \
+                else [(L, s1), (L, s0)]
+            return right + left
+        hl = self._hl(w)
+        s0, s1 = x + w * (1 - self.shaft) / 2, x + w * (1 + self.shaft) / 2
+        cx = x + w / 2
+        T = y + (hl if self.direction in ("up", "both-vertical") else 0)
+        B = y + h - (hl if self.direction in ("down", "both-vertical") else 0)
+        top = [(s0, T), (x, T), (cx, y), (x + w, T), (s1, T)] if self.direction in ("up", "both-vertical") \
+            else [(s0, T), (s1, T)]
+        bot = [(s1, B), (x + w, B), (cx, y + h), (x, B), (s0, B)] if self.direction in ("down", "both-vertical") \
+            else [(s1, B), (s0, B)]
+        return top + bot
+
+
+__all__ = ["BlockArrow", "ChatBubble", "Circle", "Cylinder", "Diamond", "Document", "Ellipse",
+           "Hexagon", "OpCircle", "Parallelogram", "Shape", "Trapezoid", "ray_hit"]