Metric tiles

Metric tiles data Primitive

The KPI strip: label + value tiles in a packing grid, optionally toned. The server stamps the tile count for e2e anchors.

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.

Outstanding

£12,450

Paid this month

£48,900

Overdue

Copy this

html

<div class="metrics-grid" data-tile-count="3">
  <div class="metric-tile" data-metric-key="outstanding">
    <div class="metric-label">Outstanding</div>
    <div class="metric-value">£12,450</div>
  </div>
  <div class="metric-tile" data-metric-key="paid" data-tone="positive">
    <div class="metric-label">Paid this month</div>
    <div class="metric-value">£48,900</div>
  </div>
  <div class="metric-tile" data-metric-key="overdue" data-tone="warning">
    <div class="metric-label">Overdue</div>
    <div class="metric-value">3</div>
  </div>
</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="metrics-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/metrics.py`

Required in the DOM: root [data-metric-key] (part metrics). 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-metric-key]`	`data-metric-key`	present (any value)

Ingestion model `MetricTile`

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

Field	Type	Required
`label`	`string`	required
`value`	`string`	required
`metric_key`	`string`	optional
`tone`	`string ∈ ['', 'positive', 'warning', 'destructive', 'accent', 'neutral']`	optional
`delta_direction`	`string ∈ ['', 'up', 'down', 'flat']`	optional
`delta_sentiment`	`string ∈ ['', 'positive_up', 'positive_down']`	optional
`delta_value`	`string`	optional
`delta_pct`	`number`	optional
`delta_period_label`	`string`	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: value=£12,450, label=Outstanding.

python

def render(tile: MetricTile) -> str:
    """Model → one metric tile."""
    key = html.escape(tile.metric_key, quote=True)
    label = html.escape(tile.label)
    value = html.escape(tile.value)
    tone_attr = ""
    if tile.tone:
        tone_attr = f' data-dz-tone="{html.escape(tile.tone, quote=True)}"'

    delta_html = ""
    if tile.delta_direction:
        is_good = (tile.delta_direction == "up" and tile.delta_sentiment == "positive_up") or (
            tile.delta_direction == "down" and tile.delta_sentiment == "positive_down"
        )
        is_bad = (tile.delta_direction == "down" and tile.delta_sentiment == "positive_up") or (
            tile.delta_direction == "up" and tile.delta_sentiment == "positive_down"
        )
        delta_tone = "positive" if is_good else ("destructive" if is_bad else "neutral")
        arrow = (
            "↑"
            if tile.delta_direction == "up"
            else ("↓" if tile.delta_direction == "down" else "→")
        )
        sign = "+" if tile.delta_direction == "up" else ""
        pct_html = (
            f'<span class="dz-metric-delta-pct">({tile.delta_pct}%)</span>'
            if tile.delta_pct
            else ""
        )
        period_html = (
            f'<span class="dz-metric-delta-period">vs {html.escape(tile.delta_period_label)}</span>'
        )
        delta_html = (
            f'<div class="dz-metric-delta" '
            f'data-dz-delta-tone="{delta_tone}" '
            f'data-dz-delta-direction="{html.escape(tile.delta_direction, quote=True)}" '
            f'data-dz-delta-sentiment="{html.escape(tile.delta_sentiment, quote=True)}">'
            f'<span aria-hidden="true">{arrow}</span>'
            f'<span class="dz-metric-delta-value">{sign}{html.escape(tile.delta_value)}</span>'
            f"{pct_html}"
            f"{period_html}"
            f"</div>"
        )

    return (
        f'<div class="dz-metric-tile" data-dz-metric-key="{key}"{tone_attr}>'
        f'<div class="dz-metric-label">{label}</div>'
        f'<div class="dz-metric-value">{value}</div>'
        f"{delta_html}"
        f"</div>"
    )

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

Outstanding

£12,450

Notes

Each tile carries data-metric-key (dual-lock root; contracts/metrics.py) and an optional data-tone. In Dazzle one scope-aware GROUP BY query fills the whole strip — the tiles can never disagree with each other.

Source files

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

site/registry.py · contracts/metrics.py

Metric tiles data Primitive

Copy this

Server exchange

Swap contract

Envelope response examples

How to use it

Seams

DOM contract

contracts/metrics.py

Ingestion model MetricTile

Exemplar render()

Notes

Source files

`contracts/metrics.py`

Ingestion model `MetricTile`

Exemplar `render()`