"""HYPERPART: time-series — line / area sequential charts.
Dual-lock unit is the region root (``data-dz-time-series``). Geometry is
server-computed SVG (``svg_html`` trusted). Multi-series legends ride
trusted ``legend_html``. Wrapper class remains view-specific
(``dz-line-chart-region`` / ``dz-area-chart-region``) for CSS.
"""
from __future__ import annotations
import html
from typing import Literal
from pydantic import BaseModel, Field
from contracts._kit import DomContract, Node, Present
DOM_CONTRACT = DomContract(
part="time-series",
root="[data-dz-time-series]",
nodes=(
Node(
"[data-dz-time-series]",
attrs={"data-dz-time-series": Present()},
),
),
)
TimeSeriesView = Literal["line", "area"]
class TimeSeriesPoint(BaseModel):
"""One (label, value) sample on the shared axis."""
label: str
value: float = 0.0
class TimeSeriesLayer(BaseModel):
"""One named series in a multi-series chart."""
name: str
points: list[TimeSeriesPoint] = Field(default_factory=list)
class TimeSeries(BaseModel):
"""Line or area chart.
- ``view`` → ``line`` | ``area`` (wrapper class + SVG style)
- ``points`` → single-series samples
- ``series`` → multi-series layers (takes precedence when non-empty)
- ``svg_html`` → trusted server-rendered SVG body
- ``legend_html`` → trusted multi-series legend markup (optional)
- ``peak_display`` → host-formatted peak for the summary line
"""
label: str = ""
view: TimeSeriesView = "line"
points: list[TimeSeriesPoint] = Field(default_factory=list)
series: list[TimeSeriesLayer] = Field(default_factory=list)
svg_html: str = Field(
default="",
description="Trusted inline SVG markup for the chart body.",
)
legend_html: str = ""
peak_display: str = ""
# Empty default matches legacy emit: bare wrapper, no empty-state copy.
empty_message: str = ""
EXEMPLARS: list[TimeSeries] = [
TimeSeries(
label="Traffic",
view="line",
points=[
TimeSeriesPoint(label="3 Mar", value=42),
TimeSeriesPoint(label="4 Mar", value=51),
TimeSeriesPoint(label="5 Mar", value=48),
TimeSeriesPoint(label="6 Mar", value=63),
TimeSeriesPoint(label="7 Mar", value=71),
TimeSeriesPoint(label="8 Mar", value=38),
TimeSeriesPoint(label="9 Mar", value=35),
TimeSeriesPoint(label="10 Mar", value=58),
TimeSeriesPoint(label="11 Mar", value=66),
TimeSeriesPoint(label="12 Mar", value=72),
TimeSeriesPoint(label="13 Mar", value=80),
TimeSeriesPoint(label="14 Mar", value=91),
TimeSeriesPoint(label="15 Mar", value=47),
TimeSeriesPoint(label="16 Mar", value=44),
],
svg_html='',
peak_display="91",
),
TimeSeries(
label="Stacked",
view="area",
series=[
TimeSeriesLayer(
name="API",
points=[
TimeSeriesPoint(label="W1", value=12),
TimeSeriesPoint(label="W2", value=14),
TimeSeriesPoint(label="W3", value=13),
TimeSeriesPoint(label="W4", value=18),
TimeSeriesPoint(label="W5", value=22),
TimeSeriesPoint(label="W6", value=20),
TimeSeriesPoint(label="W7", value=24),
TimeSeriesPoint(label="W8", value=26),
],
),
TimeSeriesLayer(
name="Webhooks",
points=[
TimeSeriesPoint(label="W1", value=6),
TimeSeriesPoint(label="W2", value=8),
TimeSeriesPoint(label="W3", value=9),
TimeSeriesPoint(label="W4", value=7),
TimeSeriesPoint(label="W5", value=11),
TimeSeriesPoint(label="W6", value=12),
TimeSeriesPoint(label="W7", value=10),
TimeSeriesPoint(label="W8", value=14),
],
),
],
svg_html='',
legend_html='
API
Webhooks
',
peak_display="26",
),
TimeSeries(points=[]),
]
def _wrapper_class(view: TimeSeriesView) -> str:
return "dz-area-chart-region" if view == "area" else "dz-line-chart-region"
def render(t: TimeSeries) -> str:
"""Model → line/area chart region."""
cls = _wrapper_class(t.view)
if not t.points and not t.series:
if t.empty_message:
return (
f'
'
f'
'
f"{html.escape(t.empty_message)}
"
f"
"
)
return f''
if t.series:
axis_labels = {p.label for layer in t.series for p in layer.points}
peak = t.peak_display
if not peak:
vals = [p.value for layer in t.series for p in layer.points]
max_val = max(vals, default=0) or 0
peak = str(int(max_val)) if max_val == int(max_val) else str(max_val)
summary = (
f'
{len(axis_labels)} buckets · '
f"{len(t.series)} series · peak {html.escape(peak)}
"
)
return f'
{t.svg_html}{t.legend_html}{summary}
'
peak = t.peak_display
if not peak:
max_val = max((p.value for p in t.points), default=0) or 0
peak = str(int(max_val)) if max_val == int(max_val) else str(max_val)
summary = f'