Time series

Time series data Primitive

Line or area sequential chart — one series of (label, value) points, or multi-series overlays with a shared legend.

Layer: L1 surface · Recipe: unset — see docs/agent/pick-a-surface.md. Curriculum: AGENTS.md; pick matrix: docs/agent/pick-a-surface.md; blast radius: CONSUMER_MAP.md.

14 buckets · peak 91

Copy this

html

<div class="line-chart-region hm-measure-lg" data-time-series>
  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 400 120" class="line-chart-svg chart-svg" role="img" aria-label="Traffic time series — 14 buckets, peak 91">
    <line x1="8" y1="92" x2="392" y2="92" stroke="var(--colour-border)" stroke-width="1"/>
    <polygon points="8,92 8.0,53.23 37.54,44.92 67.08,47.69 96.62,33.85 126.15,26.46 155.69,56.92 185.23,59.69 214.77,38.46 244.31,31.08 273.85,25.54 303.38,18.15 332.92,8.0 362.46,48.62 392.0,51.38 392,92" fill="var(--colour-brand)" fill-opacity="0.12" stroke="none"/>
    <polyline points="8.0,53.23 37.54,44.92 67.08,47.69 96.62,33.85 126.15,26.46 155.69,56.92 185.23,59.69 214.77,38.46 244.31,31.08 273.85,25.54 303.38,18.15 332.92,8.0 362.46,48.62 392.0,51.38" fill="none" stroke="var(--colour-brand)" stroke-width="1.5" stroke-linejoin="round" stroke-linecap="round"/>
    <circle cx="8.0" cy="53.23" r="2.5" fill="var(--colour-brand)" stroke="var(--colour-surface)" stroke-width="1">
      <title>3 Mar: 42</title>
    </circle>
    <circle cx="37.54" cy="44.92" r="2.5" fill="var(--colour-brand)" stroke="var(--colour-surface)" stroke-width="1">
      <title>4 Mar: 51</title>
    </circle>
    <circle cx="67.08" cy="47.69" r="2.5" fill="var(--colour-brand)" stroke="var(--colour-surface)" stroke-width="1">
      <title>5 Mar: 48</title>
    </circle>
    <circle cx="96.62" cy="33.85" r="2.5" fill="var(--colour-brand)" stroke="var(--colour-surface)" stroke-width="1">
      <title>6 Mar: 63</title>
    </circle>
    <circle cx="126.15" cy="26.46" r="2.5" fill="var(--colour-brand)" stroke="var(--colour-surface)" stroke-width="1">
      <title>7 Mar: 71</title>
    </circle>
    <circle cx="155.69" cy="56.92" r="2.5" fill="var(--colour-brand)" stroke="var(--colour-surface)" stroke-width="1">
      <title>8 Mar: 38</title>
    </circle>
    <circle cx="185.23" cy="59.69" r="2.5" fill="var(--colour-brand)" stroke="var(--colour-surface)" stroke-width="1">
      <title>9 Mar: 35</title>
    </circle>
    <circle cx="214.77" cy="38.46" r="2.5" fill="var(--colour-brand)" stroke="var(--colour-surface)" stroke-width="1">
      <title>10 Mar: 58</title>
    </circle>
    <circle cx="244.31" cy="31.08" r="2.5" fill="var(--colour-brand)" stroke="var(--colour-surface)" stroke-width="1">
      <title>11 Mar: 66</title>
    </circle>
    <circle cx="273.85" cy="25.54" r="2.5" fill="var(--colour-brand)" stroke="var(--colour-surface)" stroke-width="1">
      <title>12 Mar: 72</title>
    </circle>
    <circle cx="303.38" cy="18.15" r="2.5" fill="var(--colour-brand)" stroke="var(--colour-surface)" stroke-width="1">
      <title>13 Mar: 80</title>
    </circle>
    <circle cx="332.92" cy="8.0" r="2.5" fill="var(--colour-brand)" stroke="var(--colour-surface)" stroke-width="1">
      <title>14 Mar: 91</title>
    </circle>
    <circle cx="362.46" cy="48.62" r="2.5" fill="var(--colour-brand)" stroke="var(--colour-surface)" stroke-width="1">
      <title>15 Mar: 47</title>
    </circle>
    <circle cx="392.0" cy="51.38" r="2.5" fill="var(--colour-brand)" stroke="var(--colour-surface)" stroke-width="1">
      <title>16 Mar: 44</title>
    </circle>
    <text x="8.0" y="112" text-anchor="middle" font-size="9" fill="var(--colour-text-muted)" font-family="ui-monospace, 'SF Mono', Menlo, monospace">3 Mar</text>
    <text x="96.62" y="112" text-anchor="middle" font-size="9" fill="var(--colour-text-muted)" font-family="ui-monospace, 'SF Mono', Menlo, monospace">6 Mar</text>
    <text x="185.23" y="112" text-anchor="middle" font-size="9" fill="var(--colour-text-muted)" font-family="ui-monospace, 'SF Mono', Menlo, monospace">9 Mar</text>
    <text x="273.85" y="112" text-anchor="middle" font-size="9" fill="var(--colour-text-muted)" font-family="ui-monospace, 'SF Mono', Menlo, monospace">12 Mar</text>
    <text x="362.46" y="112" text-anchor="middle" font-size="9" fill="var(--colour-text-muted)" font-family="ui-monospace, 'SF Mono', Menlo, monospace">15 Mar</text>
    <text x="392.0" y="112" text-anchor="middle" font-size="9" fill="var(--colour-text-muted)" font-family="ui-monospace, 'SF Mono', Menlo, monospace">16 Mar</text>
  </svg>
  <p class="chart-summary">14 buckets · peak 91</p>
</div>

Server exchange

This Hyperpart has no server exchange — it is presentation or client chrome only. htmx does not issue a request on this part's behalf. If you put an affordance (hx-*) on a control that uses this markup, that action's exchange belongs to the action, not this part. See Swap contract for host-owned envelopes.

Swap contract

Agent-visible HTMX topology (ADR-0054 / decision 0012). exchange envelope = what the response may re-emit relative to the persistent slot (body_only | outer | none | host_owned | document). dual-lock validates part markup only — not this envelope. Stem: stems/morph-safe-hypermedia.md; decision: docs/decisions/0012-swap-identity-contract.md.

No host HTMX exchange on this part — presentation or client chrome only. exchange envelope: n/a.

If a host wraps this markup in hx-*, that host owns the swap contract (sole identity + envelope). Prefer innerMorph / outerMorph for stable slots; replacement for flash; body-only responses under inner swaps.

Envelope response examples

This part has no owned exchange (envelope n/a). If a host adds hx-*, that host’s envelope applies — typically body_only:

html

<!-- Host wraps this presentation part with hx-* (host owns envelope) -->
<!-- Prefer: hx-swap="innerMorph" hx-target="#panel-body" -->
<!-- Server returns body_only interior for #panel-body -->
<div class="dz-stack">content…</div>

Do not re-own the slot:

html

<!-- WRONG: server returns the presentation root with a new id every poll -->
<div id="time-series-root" data-dz-region>…</div>

How to use it

No extended guidance authored yet — start from Copy this and the dependency chips (Primitive = markup only; controller = load listed JS; Endpoint = implement Server exchange).

Seams

copy the partial under Copy this; keep root class and data-* modifiers so the CSS/JS bundle matches
no Server exchange on this part — pure presentation or client chrome
satisfy the DOM contract tables (CI stop-ship)

DOM contract

What the emitted HTML must satisfy — the table is the required surface; Python under contracts/ is the package-internal dual-lock CI runs (tests/test_contracts.py), not an app route. Standalone HTMX4: implement the API so responses match this markup. Dazzle: the agent emits SSR that already satisfies it. Do not invent attrs outside these tables. For request/response wiring see Server exchange.

`contracts/time_series.py`

Required in the DOM: root [data-time-series] (part time-series). Emit only these attributes — inventing extras is fine only if controllers ignore them; omitting required ones fails CI (tests/test_contracts.py).

Node	Attr	Constraint
`[data-time-series]`	`data-time-series`	present (any value)

Ingestion model `TimeSeriesPoint`

Server-side shape before render — one normalisation boundary for producers.

Field	Type	Required
`label`	`string`	required
`value`	`number`	optional

Exemplar `render()`

Executable in CI: the Python below is render(); the boxed preview is render(EXEMPLARS[0]) — the first fixture the dual-lock tests emit, not a separate widget and not gallery mock data. Sample model: label=Traffic.

python

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'<div class="{cls}" data-dz-time-series>'
                f'<p class="dz-empty-dense" role="status">'
                f"{html.escape(t.empty_message)}</p>"
                f"</div>"
            )
        return f'<div class="{cls}" data-dz-time-series></div>'

    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'<p class="dz-chart-summary">{len(axis_labels)} buckets · '
            f"{len(t.series)} series · peak {html.escape(peak)}</p>"
        )
        return f'<div class="{cls}" data-dz-time-series>{t.svg_html}{t.legend_html}{summary}</div>'

    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'<p class="dz-chart-summary">{len(t.points)} buckets · peak {html.escape(peak)}</p>'
    return f'<div class="{cls}" data-dz-time-series>{t.svg_html}{summary}</div>'

Live output of render(EXEMPLARS[0]) — fixture markup the dual-lock validates (sample field values only).

14 buckets · peak 91

Notes

Dual-lock root is data-time-series (contracts/time_series.py). Wrapper class stays view-specific (line-chart-region / area-chart-region). Multi-series charts append a trusted legend; SVG geometry comes from dazzle.render.svg.time_series_svg.

Source files

Canonical registration in the registry. No dedicated controller — CSS for this part lives in the layered bundle.

site/registry.py · contracts/time_series.py

Time series data Primitive

Copy this

Server exchange

Swap contract

Envelope response examples

How to use it

Seams

DOM contract

contracts/time_series.py

Ingestion model TimeSeriesPoint

Exemplar render()

Notes

Source files

`contracts/time_series.py`

Ingestion model `TimeSeriesPoint`

Exemplar `render()`