plot-io 0.12.0__py3-none-win_amd64.whl

plot_io/decorations.py

@@ -0,0 +1,920 @@
+"""Decorations: reference lines, spans, text, annotations and brackets on a plot.
+
+Decorations are not series: they take no color of the plot's, are in the legend only with a
+``name``, and change the axis limits only with ``extend_limits=True``.  They are drawn
+with the series in ``z`` order (spans under the series, lines and text over them by
+default).  Positions are in data units (``coords="data"``), fractions of the axes
+(``"axes"``) or of the figure (``"figure"``).
+"""
+
+import math
+from typing import Any
+
+from vec_io import Path
+
+from .canvas import Canvas
+from ._methods import AnnotateMixin, AxLineMixin, BracketMixin, HLineMixin, HSpanMixin, TextMixin, VLineMixin, VSpanMixin
+from . import groups
+from . import kernels
+from .color.values import color
+
+from .shapes import swatch
+from .settings import Setting, Settings, boolean, either, literal, number, one_of, table, text
+from .validators import angle, length
+from .lines import dash_of
+from .color.values import resolve_color, with_alpha
+from .text import Font, Run, draw_run, font_of, lines_run
+from .times import axis_value
+
+__all__ = ["Decoration", "HLine", "VLine", "AxLine", "HSpan", "VSpan", "Text", "Annotate",
+           "Bracket"]
+
+
+
+#: A position along an axis: a data value (bare numbers), or `%` of the axes / a length
+#: from its start.
+_AXES_POSITION = length(percent="axes_length", bare="data")
+
+
+def _point(v: Any) -> tuple[Any, Any]:
+    if not isinstance(v, (tuple, list)) or len(v) != 2:
+        raise ValueError(f"expected a point (x, y), got {v!r}")
+    return v[0], v[1]
+
+
+_COORDS = one_of("data", "axes", "figure")
+
+
+def _arrow_style(v: Any) -> str:
+    if v not in ("->", "-|>", "-"):
+        raise ValueError(f"expected '->', '-|>' or '-', got {v!r}")
+    return v
+
+
+def _common() -> dict[str, Setting]:
+    return dict(
+        name=Setting(text, doc="Legend entry; unset: not in the legend."),
+        opacity=Setting(number(0, 1), doc="Opacity."),
+        z=Setting(number(), doc="Drawing order among the series (default 0)."),
+        extend_limits=Setting(boolean, doc="Include the decoration in the axis limits."),
+        clip=Setting(boolean, doc="Clip to the axes area."),
+    )
+
+
+def _line() -> dict[str, Setting]:
+    return dict(
+        **groups.Stroke.embed(only=("color", "line_width", "line_style"),
+                              inherited=("line_width",)),
+    )
+
+
+def _font() -> dict[str, Setting]:
+    return dict(
+        font_size=Setting(length(positive=True, font=True, percent="em"), inherited=True, doc="Font size."),
+        **groups.Font.embed(only=groups.Font.FACE),
+        **groups.TextStyle.embed(only=("font_weight", "font_style")),
+        text_color=Setting(color, inherited=True, doc="Text color."),
+    )
+
+
+class Decoration(Settings):
+    """Base of decorations: behaves like a series towards the axes and the legend."""
+
+    AXES = True
+    DODGE_GROUP = None
+    STACK_GROUP = None
+    #: The axis roles the decoration's data coordinates are on.
+    ROLES: tuple[str, ...] = ()
+
+    def __init__(self, plot: Any, **settings: Any) -> None:
+        self.plot = plot
+        super().__init__(**settings)
+        plot.decorations.append(self)
+
+    def _parent(self) -> Settings:
+        return self.plot
+
+    def __repr__(self) -> str:
+        return f"{self.kind}()"
+
+    # -- what the axes need (only with extend_limits) -------------------------------
+
+    def has_axis(self, role: str) -> bool:
+        return role in self.ROLES and self.resolve("extend_limits")
+
+    def categories(self, role: str) -> list[Any] | None:
+        return None
+
+    def data_values(self, role: str) -> list[float]:
+        return []
+
+    def values(self, role: str) -> Any:
+        from array import array
+        out = array("d")
+        for v in self.data_values(role):
+            try:
+                out.append(axis_value(v))
+            except ValueError:              # a category name
+                pass
+        return out
+
+    def extent(self, role: str, scale: Any) -> tuple[int, float, float]:
+        return kernels.extent(self.values(role), scale.function)
+
+    def inverts(self, role: str) -> bool:
+        return False
+
+    def zero_default(self, role: str) -> bool:
+        return False
+
+    def zero_padding(self, role: str) -> bool:
+        return False
+
+    def sticky(self, role: str) -> list[float]:
+        return []
+
+    def legend_labels(self) -> list[Any]:
+        """Legend entries of the object: its ``name``, or none."""
+        name = self.resolve("name")
+        return [] if name is None else [name]
+
+    def legend_glyph_at(self, ctx: Any, i: int, x: float, y: float, w: float, h: float) -> None:
+        """The symbol of legend entry ``i`` (series with several entries override this)."""
+        self.legend_glyph(ctx, x, y, w, h)
+
+    def legend_colors_at(self, ctx: Any, i: int) -> tuple[Any, Any]:
+        return self.legend_colors(ctx)
+
+    def legend_key_at(self, ctx: Any, i: int) -> Any:
+        """What the symbol of entry ``i`` draws, for comparing entries."""
+        c = with_alpha(ctx.color(self.resolve("color")), self.resolve("opacity"))
+        if "line_style" in self.SETTINGS:
+            lw = self.resolve("line_width")
+            return "line", c, lw, dash_of(self.resolve("line_style"), lw)
+        return "fill", c
+
+    def legend_colors(self, ctx: Any) -> tuple[Any, Any]:
+        c = with_alpha(ctx.color(self.resolve("color")), self.resolve("opacity"))
+        return c, None
+
+    def legend_glyph(self, ctx: Any, x: float, y: float, w: float, h: float) -> None:
+        c = with_alpha(ctx.color(self.resolve("color")), self.resolve("opacity"))
+        if c is None:
+            return
+        if "line_style" in self.SETTINGS:
+            lw = self.resolve("line_width")
+            ctx.canvas.draw_lines([x, x + w], [y + h / 2, y + h / 2], stroke=c, stroke_width=lw,
+                                  stroke_dasharray=dash_of(self.resolve("line_style"), lw))
+        else:
+            ctx.canvas.fill = c
+            ctx.canvas.draw_rect(*swatch(x, y, w, h), stroke=None)
+
+    # -- positions ------------------------------------------------------------------
+
+    def _pos(self, ctx: Any, role: str, v: Any, coords: str) -> float:
+        """Page coordinate of ``v`` along ``role`` (``x`` or ``y``)."""
+        x0, y0, x1, y1 = ctx.rect
+        if coords == "axes":
+            return x0 + float(v) * (x1 - x0) if role == "x" else y1 - float(v) * (y1 - y0)
+        if coords == "figure":
+            fw, fh = getattr(ctx, "figure_size", (x1, y1))
+            return float(v) * fw if role == "x" else (1.0 - float(v)) * fh
+        state = ctx.x if role == "x" else ctx.y
+        mapper = ctx.xmap if role == "x" else ctx.ymap
+        return mapper(state.value(v))
+
+    def _along(self, ctx: Any, name: str, role: str) -> float:
+        """Page coordinate of position setting ``name`` (``min``, ``max``) along ``role``: a
+        data value, or `%` of the axes (a length) from their left or bottom edge."""
+        x0, y0, x1, y1 = ctx.rect
+        raw = self._raw(name)
+        if isinstance(raw, (int, float)):
+            return self._pos(ctx, role, raw, "data")
+        px = self.resolve(name, of=(x1 - x0) if role == "x" else (y1 - y0))
+        return x0 + px if role == "x" else y1 - px
+
+    def draw(self, ctx: Any) -> None:
+        raise NotImplementedError
+
+    def occupy(self, fonts: Any, ctx: Any, occ: Any) -> None:
+        """Marks what it draws over the series on the occupancy grid ``occ`` (guides
+        placed inside the axes avoid it): text and lines; spans, drawn under the series,
+        mark nothing."""
+
+
+class _Rule(Decoration):
+    """A horizontal or vertical reference line across part of the axes."""
+
+    VERTICAL = False
+    value: Any = None
+
+    def _ends(self, ctx: Any) -> tuple[list[float], list[float]] | None:
+        """The line's ends on the page (``None``: outside the scale's domain)."""
+        if self.VERTICAL:
+            p = self._pos(ctx, "x", self.value, "data")
+            xs, ys = [p, p], [self._along(ctx, "min", "y"), self._along(ctx, "max", "y")]
+        else:
+            p = self._pos(ctx, "y", self.value, "data")
+            xs, ys = [self._along(ctx, "min", "x"), self._along(ctx, "max", "x")], [p, p]
+        return (xs, ys) if all(math.isfinite(v) for v in xs + ys) else None
+
+    def occupy(self, fonts: Any, ctx: Any, occ: Any) -> None:
+        ends = self._ends(ctx)
+        if ends is not None:
+            occ.lines(*ends)
+
+    def draw(self, ctx: Any) -> None:
+        c = with_alpha(ctx.color(self.resolve("color")), self.resolve("opacity"))
+        lw = self.resolve("line_width")
+        ends = self._ends(ctx)
+        if c is None or ends is None:
+            return
+        xs, ys = ends
+        ctx.canvas.draw_lines(xs, ys, stroke=c, stroke_width=lw, stroke_dasharray=dash_of(self.resolve("line_style"), lw),
+                              stroke_linecap="butt")
+
+    def data_values(self, role: str) -> list[float]:
+        return [self.value]
+
+
+class HLine(HLineMixin, _Rule):
+    """A horizontal line at ``y`` from ``min`` to ``max`` (data values, or `%` of the axes
+    width).
+
+    Decorations (lines, spans, text, annotations, brackets) take no color of the plot's, are in
+    the legend only with a ``name``, and change the limits only with
+    ``extend_limits=True``.  Spans are drawn under the series (``z=-1``), lines and text over
+    them (``z=1``).  Positions are axis values (numbers, dates, ISO 8601 text, category
+    names), or fractions with ``coords="axes"`` or ``"figure"``.
+    """
+
+    SETTINGS = table(
+        **_line(),
+        min=Setting(_AXES_POSITION, doc="Start: a data value, or `%` (or a length) "
+                                        "from the start of the axes."),
+        max=Setting(_AXES_POSITION, doc="End: a data value, or `%` (or a length) from "
+                                        "the start of the axes."),
+        **_common(),
+    )
+    ROLES = ("y",)
+
+    def __init__(self, plot: Any, y: Any, **settings: Any) -> None:
+        self.value = y
+        super().__init__(plot, **settings)
+
+
+class VLine(VLineMixin, _Rule):
+    """A vertical line at ``x`` from ``min`` to ``max`` (data values, or `%` of the axes
+    height)."""
+
+    SETTINGS = HLine.SETTINGS
+    ROLES = ("x",)
+    VERTICAL = True
+
+    def __init__(self, plot: Any, x: Any, **settings: Any) -> None:
+        self.value = x
+        super().__init__(plot, **settings)
+
+
+class AxLine(AxLineMixin, Decoration):
+    """An infinite straight line through ``point`` and ``point2``, or with ``slope`` (data
+    units; linear axes)."""
+
+    SETTINGS = table(**_line(), **_common())
+    ROLES = ("x", "y")
+
+    def __init__(self, plot: Any, point: Any, slope: Any = None, point2: Any = None,
+                 **settings: Any) -> None:
+        self.p1 = _point(point)
+        if (slope is None) == (point2 is None):
+            raise ValueError("give either slope or point2")
+        self.p2 = _point(point2) if point2 is not None else None
+        self.slope = None if slope is None else float(slope)
+        super().__init__(plot, **settings)
+
+    def data_values(self, role: str) -> list[float]:
+        i = 0 if role == "x" else 1
+        pts = [self.p1] + ([self.p2] if self.p2 is not None else [])
+        return [p[i] for p in pts]
+
+    def draw(self, ctx: Any) -> None:
+        c = with_alpha(ctx.color(self.resolve("color")), self.resolve("opacity"))
+        lw = self.resolve("line_width")
+        if c is None:
+            return
+        if self.p2 is None:
+            for st in (ctx.x, ctx.y):
+                if st.scale is None or st.scale.name != "linear":
+                    raise ValueError("axline with a slope needs linear axes; give point2")
+            p2 = (float(self.p1[0]) + 1.0, float(self.p1[1]) + float(self.slope or 0.0))
+        else:
+            p2 = self.p2
+        ax, ay = self._pos(ctx, "x", self.p1[0], "data"), self._pos(ctx, "y", self.p1[1], "data")
+        bx, by = self._pos(ctx, "x", p2[0], "data"), self._pos(ctx, "y", p2[1], "data")
+        dx, dy = bx - ax, by - ay
+        n = math.hypot(dx, dy)
+        if not n or not math.isfinite(n):
+            return
+        x0, y0, x1, y1 = ctx.rect
+        far = 2.0 * (math.hypot(x1 - x0, y1 - y0) + abs(ax - x0) + abs(ay - y0)) / n
+        ctx.canvas.draw_lines([ax - far * dx, ax + far * dx], [ay - far * dy, ay + far * dy],
+                              stroke=c, stroke_width=lw, stroke_dasharray=dash_of(self.resolve("line_style"), lw))
+
+
+class _Span(Decoration):
+    VERTICAL = False
+    v0: Any = None
+    v1: Any = None
+
+    def draw(self, ctx: Any) -> None:
+        c = with_alpha(ctx.color(self.resolve("color")), self.resolve("opacity"))
+        if c is None:
+            return
+        if self.VERTICAL:
+            a, b = self._end(ctx, "x", self.v0), self._end(ctx, "x", self.v1)
+            lo, hi = self._along(ctx, "min", "y"), self._along(ctx, "max", "y")
+            r = (min(a, b), min(lo, hi), abs(b - a), abs(lo - hi))
+        else:
+            a, b = self._end(ctx, "y", self.v0), self._end(ctx, "y", self.v1)
+            lo, hi = self._along(ctx, "min", "x"), self._along(ctx, "max", "x")
+            r = (min(lo, hi), min(a, b), abs(hi - lo), abs(b - a))
+        if not all(math.isfinite(v) for v in r):
+            return
+        canvas = ctx.canvas
+        path = Path().rect(*r)
+        canvas.draw_path(path, fill=c, stroke=None)
+        lc = ctx.color(self.resolve("edge_color"))
+        if lc is not None and self.resolve("edge_width"):
+            canvas.stroke_width = self.resolve("edge_width")
+            canvas.draw_path(path, fill=None, stroke=lc)
+
+    def _end(self, ctx: Any, role: str, v: Any) -> float:
+        """Page coordinate of an end of the span: outside the scale's domain (0 on a log
+        axis), the axes edge on that side."""
+        p = self._pos(ctx, role, v, "data")
+        if math.isfinite(p):
+            return p
+        x0, y0, x1, y1 = ctx.rect
+        a, b = (x0, x1) if role == "x" else (y0, y1)
+        if math.isnan(p):                   # below the domain: the low limit's edge
+            state = ctx.x if role == "x" else ctx.y
+            low = (ctx.xmap if role == "x" else ctx.ymap)(state.lo)
+            return a if abs(low - a) <= abs(low - b) else b
+        return a if p < a else b
+
+    def data_values(self, role: str) -> list[float]:
+        return [self.v0, self.v1]
+
+
+class HSpan(HSpanMixin, _Span):
+    """A horizontal band from ``y0`` to ``y1``, from ``min`` to ``max`` of the axes width."""
+
+    SETTINGS = table(
+        color=Setting(color, doc="Fill color."),
+        **groups.Stroke.embed("edge_",
+                              only=("color", "line_width"),
+                              docs={"color": "Outline color; default none.",
+                                    "line_width": "Outline width."}),
+        min=Setting(_AXES_POSITION, doc="Start: a data value, or `%` (or a length) "
+                                        "from the start of the axes."),
+        max=Setting(_AXES_POSITION, doc="End: a data value, or `%` (or a length) from "
+                                        "the start of the axes."),
+        **_common(),
+    )
+    ROLES = ("y",)
+
+    def __init__(self, plot: Any, y0: Any, y1: Any, **settings: Any) -> None:
+        self.v0, self.v1 = y0, y1
+        super().__init__(plot, **settings)
+
+
+class VSpan(VSpanMixin, _Span):
+    """A vertical band from ``x0`` to ``x1``, from ``min`` to ``max`` of the axes height."""
+
+    SETTINGS = HSpan.SETTINGS
+    ROLES = ("x",)
+    VERTICAL = True
+
+    def __init__(self, plot: Any, x0: Any, x1: Any, **settings: Any) -> None:
+        self.v0, self.v1 = x0, x1
+        super().__init__(plot, **settings)
+
+
+class Text(TextMixin, Decoration):
+    """Text at ``(x, y)``: a string or rich content.
+
+    A line break starts a line; ``rotation`` turns the text about its point.  Text past the
+    axes (unclipped) widens the plot's margins; it is never moved.
+    """
+
+    SETTINGS = table(
+        align=Setting(one_of("left", "center", "right"),
+                      doc="Horizontal alignment on the point."),
+        valign=Setting(one_of("baseline", "top", "center", "bottom"),
+                       doc="Vertical alignment on the point."),
+        rotation=Setting(angle(), doc="Rotation (degrees, counterclockwise)."),
+        coords=Setting(_COORDS, doc="`data`, `axes` (0–1) or `figure` (0–1)."),
+        **groups.TextStyle.embed(only=("color",),
+                                 docs={"color": "Text color; default `text_color`."}),
+        **_font(),
+        **{k: v for k, v in _common().items() if k != "clip"},
+        clip=Setting(boolean, doc="Clip to the axes area."),
+    )
+    ROLES = ("x", "y")
+
+    def __init__(self, plot: Any, x: Any, y: Any, content: Any, **settings: Any) -> None:
+        self.x, self.y, self.content = x, y, content
+        super().__init__(plot, **settings)
+
+    def has_axis(self, role: str) -> bool:
+        return super().has_axis(role) and self.resolve("coords") == "data"
+
+    def data_values(self, role: str) -> list[float]:
+        return [self.x if role == "x" else self.y]
+
+    def font(self) -> Font:
+        c = self.resolve("color")
+        return font_of(self, self.resolve("font_size"), self.resolve("font_weight"),
+                       self.resolve("font_style"), c)
+
+    def legend_colors(self, ctx: Any) -> tuple[Any, Any]:
+        return ctx.color(self.resolve("color")), None
+
+    def _at(self, ctx: Any) -> tuple[float, float]:
+        """The page point the text is anchored at."""
+        coords = self.resolve("coords")
+        return self._pos(ctx, "x", self.x, coords), self._pos(ctx, "y", self.y, coords)
+
+    def _rotation(self) -> float:
+        return float(self.resolve("rotation"))
+
+    def text_run(self, fonts: Any, ctx: Any) -> "Run | tuple[Run, ...] | None":
+        """The text as drawn on the axes of ``ctx``: a run per line (lines split at
+        ``\\n``; ``None``: nothing drawn, its point outside the scale's domain or no
+        content)."""
+        px, py = self._at(ctx)
+        if not (math.isfinite(px) and math.isfinite(py)):
+            return None
+        font = self.font()
+        font.color = with_alpha(resolve_color(font.color, ctx.cycle), self.resolve("opacity"))
+        return lines_run(fonts, self.content, px, py, font, self.resolve("align"),
+                         self.resolve("valign"), self._rotation())
+
+    def _corners(self, fonts: Any, ctx: Any) -> tuple[list[float], list[float]] | None:
+        """The corners of the drawn text's (rotated) box on the page."""
+        from .labels import run_quad
+        q = run_quad(fonts, self.text_run(fonts, ctx))
+        if q is None:
+            return None
+        return [p[0] for p in q], [p[1] for p in q]
+
+    def occupy(self, fonts: Any, ctx: Any, occ: Any) -> None:
+        got = self._corners(fonts, ctx)
+        if got is not None:
+            xs, ys = got
+            occ.rects([min(xs)], [min(ys)], [max(xs)], [max(ys)], solid=True)
+
+    def reach(self, fonts: Any, ctx: Any) -> tuple[float, float, float, float]:
+        """How far the text drawn on the axes of ``ctx`` passes them on the left, right,
+        top and bottom (px; 0 within)."""
+        got = self._corners(fonts, ctx)
+        if got is None:
+            return 0.0, 0.0, 0.0, 0.0
+        xs, ys = got
+        x0, y0, x1, y1 = ctx.rect
+        return (max(0.0, x0 - min(xs)), max(0.0, max(xs) - x1), max(0.0, y0 - min(ys)),
+                max(0.0, max(ys) - y1))
+
+    def counts(self) -> bool:
+        """Whether the margins make room for the text: drawn unclipped, placed by the axes
+        (data or axes coordinates; text placed on the figure has no plot to grow)."""
+        return not self.resolve("clip") and self.resolve("coords") != "figure"
+
+    def draw(self, ctx: Any) -> None:
+        draw_run(ctx.canvas, self.text_run(ctx.canvas, ctx))
+
+
+class Annotate(AnnotateMixin, Text):
+    """Text at ``xytext`` with an arrow to ``xy``.
+
+    ``text_coords="offset"`` gives ``xytext`` in points from ``xy`` (y up).  The arrow runs
+    from the edge of the text box to ``xy``, ``shrink`` points short of both.
+    """
+
+    SETTINGS = table(
+        **{k: v for k, v in Text.SETTINGS.items() if k not in ("align", "valign")},
+        align=Setting(one_of("left", "center", "right"),
+                      doc="Horizontal alignment on `xytext`."),
+        valign=Setting(one_of("baseline", "top", "center", "bottom"),
+                       doc="Vertical alignment on `xytext`."),
+        text_coords=Setting(one_of("data", "axes", "figure", "offset"),
+                            doc="Coordinates of `xytext`: as `coords`, or `offset` (px from "
+                                "`xy`, y up); default `coords`."),
+        arrow=Setting(boolean, doc="Draw an arrow from the text to `xy`."),
+        arrow_style=Setting(_arrow_style,
+                            doc="`->` (open head), `-|>` (filled head) or `-` (no head)."),
+        **groups.Stroke.embed("arrow_",
+                              only=("color", "line_width"),
+                              docs={"color": "Arrow color; default the text color.",
+                                    "line_width": "Arrow line width."}),
+        head_length=Setting(length(lo=0), doc="Arrowhead length."),
+        shrink=Setting(length(lo=0), doc="Gap left at both ends of the arrow."),
+    )
+
+    def __init__(self, plot: Any, content: Any, xy: Any, xytext: Any = None,
+                 **settings: Any) -> None:
+        self.xy = _point(xy)
+        self.xytext = _point(xytext) if xytext is not None else None
+        x, y = self.xytext if self.xytext is not None else self.xy
+        super().__init__(plot, x, y, content, **settings)
+
+    def data_values(self, role: str) -> list[float]:
+        i = 0 if role == "x" else 1
+        out = [self.xy[i]]
+        if self.xytext is not None and self.resolve("text_coords") == "data":
+            out.append(self.xytext[i])
+        return out
+
+    def _point(self, ctx: Any) -> tuple[float, float]:
+        """The page point the arrow points to (``xy``)."""
+        coords = self.resolve("coords")
+        return self._pos(ctx, "x", self.xy[0], coords), self._pos(ctx, "y", self.xy[1], coords)
+
+    def _at(self, ctx: Any) -> tuple[float, float]:
+        ax, ay = self._point(ctx)
+        tx = self.resolve("text_coords")
+        if self.xytext is None:
+            return ax, ay
+        if tx == "offset":
+            return ax + float(self.xytext[0]), ay - float(self.xytext[1])
+        return self._pos(ctx, "x", self.xytext[0], tx), self._pos(ctx, "y", self.xytext[1], tx)
+
+    def counts(self) -> bool:
+        tc = self.resolve("text_coords")
+        return not self.resolve("clip") and (
+            tc != "figure" if self.xytext is not None and tc != "offset"
+            else self.resolve("coords") != "figure")
+
+    def draw(self, ctx: Any) -> None:
+        canvas = ctx.canvas
+        px, py = self._at(ctx)
+        if not (math.isfinite(px) and math.isfinite(py)):
+            return                              # outside the scale's domain
+        ax, ay = self._point(ctx)
+        draw_run(canvas, self.text_run(canvas, ctx))
+        got = self._corners(canvas, ctx)
+        box = (min(got[0]), min(got[1]), max(got[0]), max(got[1])) if got else (px, py, px, py)
+        if self.resolve("arrow") and self.xytext is not None and math.isfinite(ax) \
+                and math.isfinite(ay):
+            ac = with_alpha(ctx.color(self.resolve("arrow_color")), self.resolve("opacity"))
+            self._arrow(canvas, box, ax, ay, ac)
+
+    def _arrow(self, canvas: Canvas, box: tuple[float, float, float, float], ax: float, ay: float,
+               c: Any) -> None:
+        x0, y0, x1, y1 = box
+        cx, cy = (x0 + x1) / 2, (y0 + y1) / 2
+        dx, dy = ax - cx, ay - cy
+        n = math.hypot(dx, dy)
+        if not n or c is None:
+            return
+        ux, uy = dx / n, dy / n
+        # leave the text box: smallest t where the ray crosses its edge
+        ts = []
+        if ux:
+            ts.append(((x1 if ux > 0 else x0) - cx) / ux)
+        if uy:
+            ts.append(((y1 if uy > 0 else y0) - cy) / uy)
+        t0 = min(t for t in ts if t >= 0) if ts else 0.0
+        shrink = self.resolve("shrink")
+        t0 += shrink
+        t1 = n - shrink
+        if t1 <= t0:
+            return
+        sx, sy = cx + ux * t0, cy + uy * t0
+        ex, ey = cx + ux * t1, cy + uy * t1
+        lw = self.resolve("arrow_width")
+        style = self.resolve("arrow_style")
+        hs = self.resolve("head_length")
+        if style == "-|>":
+            ex2, ey2 = ex - ux * hs * 0.9, ey - uy * hs * 0.9
+        else:
+            ex2, ey2 = ex, ey
+        canvas.draw_lines([sx, ex2], [sy, ey2], stroke=c, stroke_width=lw, stroke_linecap="butt")
+        if style == "-" or not hs:
+            return
+        hw = 0.45 * hs
+        px_, py_ = -uy, ux
+        bx, by = ex - ux * hs, ey - uy * hs
+        with canvas.state():
+            path = Path().move_to(bx + px_ * hw, by + py_ * hw).line_to(ex, ey)
+            path.line_to(bx - px_ * hw, by - py_ * hw)
+            if style == "-|>":
+                canvas.draw_path(path.close(), fill=c, stroke=None)
+            else:
+                canvas.stroke_width = lw
+                canvas.stroke_linejoin = "miter"
+                canvas.draw_path(path, fill=None, stroke=c)
+
+
+# -- brackets ----------------------------------------------------------------------------
+
+def _stars(v: Any) -> tuple[float, ...]:
+    out = tuple(float(number(0, 1)(x)) for x in v)
+    if not out or any(a <= b for a, b in zip(out, out[1:])):
+        raise ValueError(f"expected decreasing thresholds in (0, 1], got {v!r}")
+    return out
+
+
+def _p_format(v: Any) -> Any:
+    if v in ("stars", "p"):
+        return v
+    if isinstance(v, str) and "{" in v:
+        try:
+            v.format(p=0.5)
+        except (IndexError, KeyError, ValueError) as e:
+            raise ValueError(f"invalid format string {v!r}: {e}") from None
+        return v
+    raise ValueError(f"expected 'stars', 'p' or a format string with {{p}}, got {v!r}")
+
+
+class Bracket(BracketMixin, Decoration):
+    """A line from ``a`` to ``b`` (categories or positions on the category axis) with tips
+    toward the data and text beyond it: ``text``, or ``p`` written as ``format`` says.
+    Unset ``y``: ``step`` above the highest value the plot's series draw between ``a`` and
+    ``b``, and ``step`` plus the text (and ``gap``) above every bracket of the plot it
+    overlaps (shorter brackets are placed first).  Categories on y: the bracket stands
+    right of the data, its text rotated.
+
+    ``format``: ``"stars"`` (``*`` to ``****`` at p ≤ 0.05, 0.01, 0.001, 0.0001: ``stars``;
+    else ``ns``), ``"p"`` (``p = 0.003``, ``p < 0.0001``, in the plot's number format) or a
+    format string (``"{p:.2g}"``).  plot_io computes no test: the caller gives p.  Tips stop
+    short of the data or of the bracket under each end.  Brackets are in the axis limits and
+    their text widens the margins.  ``plot.brackets(pairs, p=…)`` adds one per pair; on a
+    facet set, ``panels.bracket`` and ``panels.brackets`` add them to every panel.
+    """
+
+    SETTINGS = table(
+        **_line(),
+        y=Setting(either(literal(None), number()),
+                  doc="Value of the line on the value axis; unset: placed above the data."),
+        format=Setting(_p_format,
+                       doc="Text of `p`: `stars` (`*` … `****` at each of `stars`, else "
+                           "`ns`), `p` (`p = 0.003`, `p < 0.0001`) or a format string "
+                           "(`\"{p:.2g}\"`)."),
+        stars=Setting(_stars, doc="Thresholds of `*`, `**`, `***`, `****` (p at most each)."),
+        tip=Setting(length(lo=0, percent="em"), doc="Length of the tips toward the data."),
+        step=Setting(length(lo=0, percent="axes_length", bare="data"),
+                     doc="Distance above the data and between tiers: `%` of the data's "
+                         "range on the value axis, or bare numbers in its units."),
+        gap=Setting(length(lo=0, percent="em"), doc="Gap between the line and the text."),
+        **_font(),
+        **_common(),
+    )
+
+    def __init__(self, plot: Any, a: Any, b: Any, text: Any = None, p: Any = None,
+                 **settings: Any) -> None:
+        self.a, self.b, self.text, self.p = a, b, text, p
+        if p is not None:
+            p = float(p)
+            if not 0.0 <= p <= 1.0:
+                raise ValueError(f"bracket: p must be in [0, 1], got {p!r}")
+            self.p = p
+        super().__init__(plot, **settings)
+
+    def content(self) -> Any:
+        """The text drawn (``None``: none)."""
+        if self.text is not None or self.p is None:
+            return self.text
+        fmt, p = self.resolve("format"), self.p
+        if fmt == "stars":
+            n = sum(p <= t for t in self.resolve("stars"))
+            return "*" * n if n else "ns"
+        if fmt == "p":
+            from .numbers import NumberStyle, _restyle
+            style = NumberStyle.of(self.plot)
+            low = min(self.resolve("stars"))
+            if p < low:
+                return "p < " + _restyle(format(low, "g"), style)
+            return "p = " + _restyle(format(p, ".2g"), style)
+        return fmt.format(p=p)
+
+    # -- placement (all brackets of the plot together) -------------------------------
+
+    def _placed(self, scale: Any) -> tuple[str, float, float, float, float, float]:
+        """``(value role, position of a, of b, line, floor at a, floor at b)``: the line
+        and the floors under its ends (the data or lower brackets) in the scale's space."""
+        return _layout(self.plot, scale)[id(self)][:6]
+
+    def _clear(self, fonts: Any) -> float:
+        """How far (px) a bracket above this one passes its line: its text and ``gap``."""
+        content = self.content()
+        if content is None or content == "":
+            return 0.0
+        from .labels import quad
+        font = font_of(self, self.resolve("font_size"), self.resolve("font_weight"),
+                       self.resolve("font_style"), self.resolve("text_color"))
+        q = quad(fonts, content, font, 0.0, 0.0, "center", "bottom")
+        return 0.0 if q is None else (max(p[1] for p in q) - min(p[1] for p in q)
+                                      + self.resolve("gap"))
+
+    def _lifts(self, scale: Any, fonts: Any) -> tuple[float, float, float]:
+        """How far (px) the line and the floors at ``a`` and ``b`` lie past their places
+        in the scale's space: each automatic line clears the text of the brackets under
+        it."""
+        got = _layout(self.plot, scale)
+        lift: dict[int, float] = {}
+        for k in sorted(got, key=lambda k: got[k][3]):
+            lift[k] = max((lift[q] + got[q][8]._clear(fonts) for q in got[k][6]),
+                          default=0.0)
+        fa, fb = got[id(self)][7]
+        return (lift[id(self)], 0.0 if fa is None else lift[fa],
+                0.0 if fb is None else lift[fb])
+
+    def label_room(self, fonts: Any, role: str) -> list[tuple[float, float, int]]:
+        """The room (px) the axis keeps past the lines that clear lower brackets' text."""
+        got = self.plot.__dict__.get("_brackets")
+        if got is None or id(self) not in got[2] or role != got[2][id(self)][0]:
+            return []
+        lift = self._lifts(got[3], fonts)[0]
+        v = got[2][id(self)][3]
+        if got[3] is not None and got[3].function:
+            v = got[3].inverse(v)
+        return [(v, lift, 1)] if lift > 0 and math.isfinite(v) else []
+
+    def has_axis(self, role: str) -> bool:
+        return self.resolve("extend_limits") and role == _orient(self.plot)[0]
+
+    def extent(self, role: str, scale: Any) -> tuple[int, float, float]:
+        line = self._placed(scale)[3]
+        v = scale.inverse(line) if scale.function else line
+        return (1, v, v) if math.isfinite(v) else (0, math.nan, math.nan)
+
+    def _geometry(self, ctx: Any, fonts: Any = None
+                  ) -> tuple[list[float], list[float], float, float, str] | None:
+        """The polyline (tips and line) on the page, the text's anchor and the value role
+        (text measured with ``fonts``, else the context's canvas)."""
+        vrole = _orient(self.plot)[0]
+        crole = "x" if vrole == "y" else "y"
+        st = ctx.y if vrole == "y" else ctx.x
+        sc = st.scale
+        _, pa, pb, line, fa, fb = self._placed(sc)
+        vmap = ctx.ymap if vrole == "y" else ctx.xmap
+        up = -1.0 if vrole == "y" else 1.0           # the page direction away from the data
+        lifts = self._lifts(sc, ctx.canvas if fonts is None else fonts)
+
+        def page(f: float, lift: float) -> float:
+            return vmap(sc.inverse(f) if sc is not None and sc.function else f) + up * lift
+        a, b = self._pos(ctx, crole, pa, "data"), self._pos(ctx, crole, pb, "data")
+        lv = page(line, lifts[0])
+        if not all(math.isfinite(v) for v in (a, b, lv)):
+            return None
+        tip = self.resolve("tip")
+        tips = []
+        for f, lift in ((fa, lifts[1]), (fb, lifts[2])):
+            room = abs(page(f, lift) - lv) / 2 if math.isfinite(f) else tip
+            tips.append(lv - up * min(tip, room if math.isfinite(room) else tip))
+        us, vs = [a, a, b, b], [tips[0], lv, lv, tips[1]]
+        gap = self.resolve("gap")
+        if vrole == "y":
+            return us, vs, (a + b) / 2, lv + up * gap, vrole
+        return vs, us, lv + up * gap, (a + b) / 2, vrole
+
+    def text_run(self, fonts: Any, ctx: Any) -> Any:
+        g = self._geometry(ctx, fonts)
+        content = self.content()
+        if g is None or content is None or content == "":
+            return None
+        font = font_of(self, self.resolve("font_size"), self.resolve("font_weight"),
+                       self.resolve("font_style"), self.resolve("text_color"))
+        font.color = with_alpha(resolve_color(font.color, ctx.cycle), self.resolve("opacity"))
+        if g[4] == "y":
+            return lines_run(fonts, content, g[2], g[3], font, "center", "bottom", 0.0)
+        return lines_run(fonts, content, g[2], g[3], font, "center", "bottom", -90.0)
+
+    def _corners(self, fonts: Any, ctx: Any) -> tuple[list[float], list[float]] | None:
+        """The corners of the drawn text's (rotated) box on the page."""
+        from .labels import run_quad
+        q = run_quad(fonts, self.text_run(fonts, ctx))
+        return None if q is None else ([p[0] for p in q], [p[1] for p in q])
+
+    def reach(self, fonts: Any, ctx: Any) -> tuple[float, float, float, float]:
+        """How far the text passes the axes on the left, right, top and bottom (px)."""
+        return Text.reach(self, fonts, ctx)  # type: ignore[arg-type]
+
+    def counts(self) -> bool:
+        return not self.resolve("clip")
+
+    def occupy(self, fonts: Any, ctx: Any, occ: Any) -> None:
+        g = self._geometry(ctx, fonts)
+        if g is not None:
+            occ.lines(g[0], g[1])
+        got = self._corners(fonts, ctx)
+        if got is not None:
+            occ.rects([min(got[0])], [min(got[1])], [max(got[0])], [max(got[1])], solid=True)
+
+    def draw(self, ctx: Any) -> None:
+        g = self._geometry(ctx)
+        c = with_alpha(ctx.color(self.resolve("color")), self.resolve("opacity"))
+        if g is not None and c is not None:
+            lw = self.resolve("line_width")
+            ctx.canvas.draw_lines(g[0], g[1], stroke=c, stroke_width=lw,
+                                  stroke_dasharray=dash_of(self.resolve("line_style"), lw),
+                                  stroke_linecap="butt", stroke_linejoin="miter")
+        draw_run(ctx.canvas, self.text_run(ctx.canvas, ctx))
+
+
+def _orient(plot: Any) -> tuple[str, dict[str, list[Any]]]:
+    """The value role of the plot's brackets (``"x"`` when its categories are on y or its
+    series are horizontal) and the categories of each axis."""
+    from .layers.grammar import flipped
+    from .layers.pipeline import plot_calls
+    cats: dict[str, list[Any]] = {"x": [], "y": []}
+    horizontal = False
+    for c in plot_calls(plot):
+        for r in ("x", "y"):
+            for k in c.categories(r) or ():
+                if k not in cats[r]:
+                    cats[r].append(k)
+        horizontal = horizontal or flipped(c.series)
+    return ("x" if horizontal or (cats["y"] and not cats["x"]) else "y"), cats
+
+
+def _layout(plot: Any, scale: Any) -> dict[int, tuple[Any, ...]]:
+    """Every bracket of ``plot`` placed (see :meth:`Bracket._placed`); cached per set of
+    calls and scale."""
+    from .layers.grammar import top
+    from .layers.pipeline import plot_calls
+    calls = plot_calls(plot)
+    key = (scale.name if scale is not None else None,
+           tuple(sorted(scale.options.items())) if scale is not None else ())
+    got = plot.__dict__.get("_brackets")
+    if got is not None and got[0] is calls and got[1] == key:
+        return got[2]
+    vrole, cats = _orient(plot)
+    crole = "x" if vrole == "y" else "y"
+    names = cats[crole]
+    half = 0.5 if names else 0.0
+    fn = scale.f if scale is not None and scale.function else (lambda v: v)
+
+    def pos(v: Any) -> float:
+        if names and not isinstance(v, (int, float)) and v in names:
+            return float(names.index(v))
+        return float(axis_value(v))
+
+    def high(lo: float, hi: float) -> float:
+        best = -math.inf
+        for c in calls:
+            v = top(c, lo, hi, vrole, cats)
+            if math.isfinite(v):
+                f = fn(v)
+                if math.isfinite(f):
+                    best = max(best, f)
+        return best
+    lo_f, hi_f = math.inf, -math.inf
+    for c in calls:
+        n, a, b = c.extent(vrole, scale) if scale is not None else (0, 0, 0)
+        if n:
+            for v in (fn(a), fn(b)):
+                if math.isfinite(v):
+                    lo_f, hi_f = min(lo_f, v), max(hi_f, v)
+    span = hi_f - lo_f if hi_f > lo_f else 1.0
+    brs = [d for d in plot.decorations if isinstance(d, Bracket)]
+    ends = {id(d): sorted((pos(d.a), pos(d.b))) for d in brs}
+    lines: dict[int, float] = {}
+    for d in brs:
+        y = d.resolve("y")
+        if y is not None:
+            lines[id(d)] = fn(float(y))
+    auto = sorted((d for d in brs if id(d) not in lines),
+                  key=lambda d: ends[id(d)][1] - ends[id(d)][0])
+    for d in auto:
+        a, b = ends[id(d)]
+        raw = d._raw("step")
+        step = float(raw) if isinstance(raw, (int, float)) else d.resolve("step", of=span)
+        base = high(a - half, b + half)
+        line = (base if math.isfinite(base) else (hi_f if math.isfinite(hi_f) else 0.0)) + step
+        for q, ql in lines.items():
+            qa, qb = ends[q]
+            if qa <= b and a <= qb:
+                line = max(line, ql + step)
+        lines[id(d)] = line
+    out = {}
+    placed = {id(d) for d in auto}
+    for d in brs:
+        a, b = ends[id(d)]
+        floors: list[float] = []
+        sources: list[int | None] = []
+        for e in (a, b):
+            f, src = high(e - half, e + half), None
+            for q, ql in lines.items():
+                qa, qb = ends[q]
+                if q != id(d) and qa <= e <= qb and ql < lines[id(d)] and ql > f:
+                    f, src = ql, q
+            floors.append(f)
+            sources.append(src)
+        under = tuple(q for q, ql in lines.items() if id(d) in placed and q != id(d)
+                      and ends[q][0] <= b and a <= ends[q][1] and ql < lines[id(d)])
+        out[id(d)] = (vrole, a, b, lines[id(d)], floors[0], floors[1], under,
+                      tuple(sources), d)
+    plot.__dict__["_brackets"] = (calls, key, out, scale)
+    return out