Bar track

Bar track data Primitive

Value-against-capacity rows with real progressbar semantics — the resource-usage sibling of the bar chart.

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.

Storage

62%

Compute

38%

2 rows0–100

Copy this

html

<div class="bar-track-region hm-measure-lg" data-bar-track>
  <div class="bar-track-rows">
    <div class="bar-track-row">
      <span class="bar-track-label" title="Storage">Storage</span>
      <div class="bar-track" role="progressbar" aria-valuemin="0" aria-valuemax="100" aria-valuenow="62" aria-label="Storage: 62%"><span class="bar-track-fill" style="width: 62%;" title="Storage: 62%"></span></div>
      <span class="bar-track-value">62%</span>
    </div>
    <div class="bar-track-row">
      <span class="bar-track-label" title="Compute">Compute</span>
      <div class="bar-track" role="progressbar" aria-valuemin="0" aria-valuemax="100" aria-valuenow="38" aria-label="Compute: 38%"><span class="bar-track-fill" style="width: 38%;" title="Compute: 38%"></span></div>
      <span class="bar-track-value">38%</span>
    </div>
  </div>
  <p class="bar-track-summary"><span class="bar-track-summary-gutter" aria-hidden="true"></span><span class="bar-track-summary-meta">2 rows</span><span class="bar-track-summary-scale">0–100</span></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="bar-track-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/bar_track.py`

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

Ingestion model `BarTrackRow`

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

Field	Type	Required
`label`	`string`	required
`value`	`number`	optional
`formatted`	`string`	optional
`fill_pct`	`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.

python

def render(b: BarTrack) -> str:
    """Model → bar-track region (references block is host-local)."""
    if not b.rows:
        return '<div class="dz-bar-track-region" data-dz-bar-track></div>'

    max_str = _num(b.max_value)
    rows_html = "".join(
        f'<div class="dz-bar-track-row">'
        f'<span class="dz-bar-track-label" title="{html.escape(row.label, quote=True)}">'
        f"{html.escape(row.label)}</span>"
        f'<div class="dz-bar-track" role="progressbar" '
        f'aria-valuemin="0" '
        f'aria-valuemax="{max_str}" '
        f'aria-valuenow="{_num(row.value)}" '
        f'aria-label="{html.escape(row.label, quote=True)}: '
        f'{html.escape(row.formatted or _num(row.value), quote=True)}">'
        f'<span class="dz-bar-track-fill" '
        f'style="width: {_num(round(row.fill_pct, 2))}%;" '
        f'title="{html.escape(row.label, quote=True)}: '
        f'{html.escape(row.formatted or _num(row.value), quote=True)}"></span>'
        f"</div>"
        f'<span class="dz-bar-track-value">'
        f"{html.escape(row.formatted or _num(row.value))}</span>"
        f"</div>"
        for row in b.rows
    )
    max_rounded = round(b.max_value, 2)
    max_summary = str(int(max_rounded)) if max_rounded == int(max_rounded) else str(max_rounded)
    n = len(b.rows)
    row_word = "row" if n == 1 else "rows"
    return (
        f'<div class="dz-bar-track-region" data-dz-bar-track>'
        f'<div class="dz-bar-track-rows">{rows_html}</div>'
        f'<p class="dz-bar-track-summary">'
        f'<span class="dz-bar-track-summary-gutter" aria-hidden="true"></span>'
        f'<span class="dz-bar-track-summary-meta">'
        f"{n} {row_word}</span>"
        f'<span class="dz-bar-track-summary-scale">'
        f"0–{max_summary}</span>"
        f"</p>"
        f"</div>"
    )

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

Storage

62%

Compute

38%

2 rows0–100

Notes

Dual-lock root is data-bar-track (contracts/bar_track.py). Each track is a real role="progressbar" with numeric aria values — the fill width is presentation, the aria is the content. Labels and fills both carry title for hover detail.

Source files

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

site/registry.py · contracts/bar_track.py

Bar track data Primitive

Copy this

Server exchange

Swap contract

Envelope response examples

How to use it

Seams

DOM contract

contracts/bar_track.py

Ingestion model BarTrackRow

Exemplar render()

Notes

Source files

`contracts/bar_track.py`

Ingestion model `BarTrackRow`

Exemplar `render()`