"""HYPERPART: box-plot — per-group quartile distribution chart.
Dual-lock unit is the region root. Whisker/quartile geometry is
server-computed SVG (``svg_html`` trusted); the summary line is derived
from group count + sample totals.
"""
from __future__ import annotations
import html
from pydantic import BaseModel, Field
from contracts._kit import DomContract, Node, Present
DOM_CONTRACT = DomContract(
part="box-plot",
root="[data-dz-box-plot]",
nodes=(
Node(
"[data-dz-box-plot]",
attrs={"data-dz-box-plot": Present()},
),
),
)
class BoxPlotGroup(BaseModel):
"""One group five-number summary (+ optional sample count)."""
label: str
min: float = 0.0
q1: float = 0.0
median: float = 0.0
q3: float = 0.0
max: float = 0.0
samples: int = 0
class BoxPlot(BaseModel):
"""Distribution box-plot.
- ``groups`` → series data (summary is derived)
- ``svg_html`` → trusted server-rendered SVG body (empty → no glyph)
- ``label`` → chart title used by host SVG helpers (not always in DOM)
"""
label: str = ""
groups: list[BoxPlotGroup] = Field(default_factory=list)
svg_html: str = Field(
default="",
description="Trusted inline SVG markup for the chart body.",
)
empty_message: str = "No data available."
EXEMPLARS: list[BoxPlot] = [
BoxPlot(
label="Latency",
groups=[
BoxPlotGroup(label="API", min=10, q1=20, median=30, q3=45, max=80, samples=120),
BoxPlotGroup(label="Web", min=5, q1=15, median=25, q3=40, max=70, samples=98),
BoxPlotGroup(label="Jobs", min=12, q1=22, median=35, q3=50, max=95, samples=64),
],
svg_html='',
),
BoxPlot(groups=[], empty_message="No box-plot groups"),
]
def render(b: BoxPlot) -> str:
"""Model → box-plot region."""
if not b.groups:
return (
f''
f'
'
f"{html.escape(b.empty_message)}
"
f"
{len(b.groups)} groups · {n_total} samples
'
return f'{b.svg_html}{summary}
'
__all__ = [
"DOM_CONTRACT",
"BoxPlotGroup",
"BoxPlot",
"EXEMPLARS",
"render",
]