codefig 0.17.0__py3-none-any.whl

codefig/steps.py

@@ -0,0 +1,203 @@
+"""Circled / squared step numbers (①②③) drawn as shapes, not font glyphs.
+
+* :class:`Step` — one numbered badge; a normal node (layering role **hard**) you can
+  put in any Row/Col, attach to a :class:`~codefig.primitives.Box` corner with
+  ``Box(..., step=2)`` or place on an edge path with ``Edge(..., step=2)``.
+* :class:`StepCounter` — hands out consecutive :class:`Step` badges that share one
+  style (``steps.next()`` → ①, ②, ③ …).
+
+The digits are ordinary text centred in a vector circle / rounded square, so they
+render identically in every font and at every scale (unlike the Unicode ①
+glyphs, which many fonts lack).
+"""
+
+from __future__ import annotations
+
+from typing import Any, List, Optional, Tuple, Union
+
+from .node import Node
+from .styles import Theme
+
+STEP_STYLES = ("circle", "square")
+
+StepLike = Union[int, str, "Step"]
+
+
+class Step(Node):
+    """A numbered step badge (①-style), drawn as a filled or outlined shape.
+
+    Layering role: **hard** (edges route around it; check_overlaps() reports
+    anything it covers). On an edge (``Edge(step=…)``) it is checked like an
+    edge label.
+
+    Args:
+        n: The number or short text shown inside (``1``, ``"2a"``, ``"A"``).
+        style: ``"circle"`` (default) or ``"square"`` (rounded square).
+        color: Badge colour (px-independent CSS colour). Default: ``theme.highlight``
+            (``"#c0392b"``).
+        filled: ``True`` (default) → solid ``color`` disc with white digits;
+            ``False`` → white disc with a ``color`` outline and ``color`` digits.
+        size: Diameter / side length in px. Default: ``1.5 × font_size`` (≈ 16 px).
+        font_size: Digit size in px. Default: ``0.82 × theme.font_size``.
+        text_color: Digit colour override (default white when filled, else ``color``).
+        stroke_width: Outline width in px for ``filled=False`` (default 1.4).
+        **kwargs: Common :class:`~codefig.node.Node` options (``id``, ``obstacle``,
+            ``legend`` …).
+
+    Example:
+        >>> from codefig import Figure, Row, Box, Step
+        >>> fig = Figure(size="auto", cols=1)
+        >>> with fig.panel("a") as p:
+        ...     p += Row([Step(1), Box("load data"), Step(2, filled=False), Box("train")])
+        >>> svg = fig.to_svg()
+    """
+
+    def __init__(
+        self,
+        n: Union[int, str],
+        *,
+        style: str = "circle",
+        color: Optional[str] = None,
+        filled: bool = True,
+        size: Optional[float] = None,
+        font_size: Optional[float] = None,
+        text_color: Optional[str] = None,
+        stroke_width: float = 1.4,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(**kwargs)
+        if style not in STEP_STYLES:
+            raise ValueError(f"Step style must be one of {STEP_STYLES}, got {style!r}")
+        self.n = n
+        self.text = str(n)
+        self.style = style
+        self.color = color
+        self.filled = bool(filled)
+        self.size = None if size is None else float(size)
+        self.font_size = None if font_size is None else float(font_size)
+        self.text_color = text_color
+        self.stroke_width = float(stroke_width)
+
+    # ---- metrics ---------------------------------------------------------------
+    def _fs(self) -> float:
+        return self.font_size if self.font_size is not None else round(self.theme.font_size * 0.82, 2)
+
+    def diameter(self) -> float:
+        """Badge diameter / side in px (grows for multi-character labels)."""
+        from .textutil import measure_text
+
+        d = self.size if self.size is not None else round(self._fs() * 1.75, 1)
+        tw, _ = measure_text(self.text, self._fs(), weight="bold")
+        return max(d, tw + self._fs() * 0.7)
+
+    def _measure(self) -> Tuple[float, float]:
+        d = self.diameter()
+        return d, d
+
+    def _color(self) -> str:
+        return self.color or self.theme.highlight
+
+    # ---- drawing ---------------------------------------------------------------
+    def paint(self, buf: List[str], cx: float, cy: float, d: Optional[float] = None) -> None:
+        """Draw the badge centred at page coordinates (``cx``, ``cy``)."""
+        from .render_svg import draw_circle, draw_rect, draw_text
+        from .textutil import measure_text
+
+        d = self.diameter() if d is None else d
+        col = self._color()
+        fill = col if self.filled else "#ffffff"
+        stroke = "none" if self.filled else col
+        sw = 0.0 if self.filled else self.stroke_width
+        # marked as a glyph so lint does not count the bold numeral as a bold label
+        buf.append('<g data-cf-glyph="step">')
+        if self.style == "circle":
+            draw_circle(buf, cx, cy, d / 2 - sw / 2, fill=fill, stroke=stroke, stroke_width=sw)
+        else:
+            s = d - sw
+            draw_rect(buf, cx - s / 2, cy - s / 2, s, s, fill=fill, stroke=stroke,
+                      stroke_width=sw, radius=round(d * 0.2, 2))
+        fs = self._fs()
+        tc = self.text_color or ("#ffffff" if self.filled else col)
+        tw, _ = measure_text(self.text, fs, weight="bold")
+        draw_text(buf, self.text, cx - tw / 2, cy + fs * 0.36, font_size=fs, weight="bold",
+                  fill=tc)
+        buf.append("</g>")
+
+    def draw(self, buf: List[str], ox: float = 0.0, oy: float = 0.0) -> None:
+        g = self.geom
+        self.paint(buf, g.cx + ox, g.cy + oy, min(g.w, g.h))
+
+
+class StepCounter:
+    """Hands out consecutive :class:`Step` badges that share one style.
+
+    Args:
+        style: ``"circle"`` (default) or ``"square"``.
+        color: Badge colour (default ``theme.highlight``).
+        filled: Solid (default) or outlined badges.
+        start: First number (default 1).
+        size: Badge diameter in px (default ≈ 1.5 × font size).
+        font_size: Digit size in px.
+        theme: Theme for defaults.
+
+    Example:
+        >>> from codefig import Box, Edge, StepCounter
+        >>> steps = StepCounter(color="#1f6fb2")
+        >>> a, b, c = Box("parse"), Box("plan"), Box("run")
+        >>> e1 = Edge(a, b, step=steps.next())   # ①
+        >>> e2 = Edge(b, c, step=steps.next())   # ②
+        >>> steps.peek()
+        3
+    """
+
+    def __init__(
+        self,
+        *,
+        style: str = "circle",
+        color: Optional[str] = None,
+        filled: bool = True,
+        start: int = 1,
+        size: Optional[float] = None,
+        font_size: Optional[float] = None,
+        theme: Optional[Theme] = None,
+    ) -> None:
+        if style not in STEP_STYLES:
+            raise ValueError(f"StepCounter style must be one of {STEP_STYLES}, got {style!r}")
+        self.style = style
+        self.color = color
+        self.filled = bool(filled)
+        self.size = size
+        self.font_size = font_size
+        self.theme = theme
+        self._next = int(start)
+
+    def next(self, **overrides: Any) -> Step:
+        """Return a new :class:`Step` with the next number (``overrides`` → Step kwargs)."""
+        kw = dict(style=self.style, color=self.color, filled=self.filled, size=self.size,
+                  font_size=self.font_size, theme=self.theme)
+        kw.update(overrides)
+        s = Step(self._next, **kw)
+        self._next += 1
+        return s
+
+    def peek(self) -> int:
+        """The number the next :meth:`next` call will use."""
+        return self._next
+
+    def reset(self, start: int = 1) -> None:
+        """Restart numbering at ``start``."""
+        self._next = int(start)
+
+
+def as_step(v: Optional[StepLike], theme: Optional[Theme] = None) -> Optional[Step]:
+    """Coerce ``None`` / an int / a str / a :class:`Step` to a Step (or None)."""
+    if v is None or v is False:
+        return None
+    if isinstance(v, Step):
+        return v
+    if isinstance(v, (int, str)):
+        return Step(v, theme=theme)
+    raise TypeError(f"step must be an int, str or Step, got {type(v).__name__}")
+
+
+__all__ = ["Step", "StepCounter", "as_step", "STEP_STYLES"]