Bullet chart

Bullet chart data Primitive

Actual vs target on qualitative bands — the KPI-with-context bar. All geometry is server-computed inline percentages.

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.

Revenue

72 / 80

1 rows · scale 0–100

Copy this

html

<div class="bullet-region hm-measure-lg" data-bullet>
  <div class="bullet-rows">
    <div class="bullet-row">
      <span class="bullet-label">Revenue</span>
      <div class="bullet-track"><span class="bullet-band" style="left: 0%; width: 60%; background: var(--colour-danger);" title="Poor: 0–60"></span><span class="bullet-band" style="left: 60%; width: 25%; background: hsl(40, 90%, 55%);" title="OK: 60–85"></span><span class="bullet-band" style="left: 85%; width: 15%; background: hsl(145, 55%, 45%);" title="Good: 85–100"></span><span class="bullet-actual" style="width: 72%;" title="Revenue actual: 72"></span><span class="bullet-target" style="left: 80%;" title="Revenue target: 80"></span></div>
      <span class="bullet-value">72 / 80</span>
    </div>
  </div>
  <p class="bullet-summary">1 rows · scale 0–100</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="bullet-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/bullet.py`

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

Ingestion model `BulletBand`

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

Field	Type	Required
`from_value`	`number`	required
`to_value`	`number`	required
`label`	`string`	optional
`color`	`string ∈ ['target', 'positive', 'warning', 'destructive', 'muted']`	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: Bullet) -> str:
    """Model → bullet chart region."""
    if not b.rows or b.max_value <= 0:
        return (
            f'<div class="dz-bullet-region" data-dz-bullet>'
            f'<p class="dz-empty-dense" role="status">'
            f"{html.escape(b.empty_message)}</p>"
            f"</div>"
        )

    suffix = b.unit_suffix
    rows_html: list[str] = []
    for row in b.rows:
        actual_pct = round(row.actual / b.max_value * 100, 2)
        bands_html = ""
        for band in b.bands:
            band_left = round(band.from_value / b.max_value * 100, 2)
            band_width = round((band.to_value - band.from_value) / b.max_value * 100, 2)
            colour = _BAND_COLORS.get(band.color, _BAND_COLORS["target"])
            bands_html += (
                f'<span class="dz-bullet-band" '
                f'style="left: {band_left}%; width: {band_width}%; '
                f'background: {colour};" '
                f'title="{html.escape(band.label, quote=True)}: '
                f'{_measure_num(band.from_value, suffix)}–{_measure_num(band.to_value, suffix)}"></span>'
            )

        actual_rounded = round(row.actual, 1)
        value_html = _measure_num(actual_rounded, suffix)
        target_html = ""
        if row.target is not None:
            target_pct = round(row.target / b.max_value * 100, 2)
            target_html = (
                f'<span class="dz-bullet-target" '
                f'style="left: {target_pct}%;" '
                f'title="{html.escape(row.label, quote=True)} target: '
                f'{_measure_num(row.target, suffix)}"></span>'
            )
            target_rounded = round(row.target, 1)
            value_html += f" / {_measure_num(target_rounded, suffix)}"

        rows_html.append(
            f'<div class="dz-bullet-row">'
            f'<span class="dz-bullet-label">{html.escape(row.label)}</span>'
            f'<div class="dz-bullet-track">'
            f"{bands_html}"
            f'<span class="dz-bullet-actual" '
            f'style="width: {actual_pct}%;" '
            f'title="{html.escape(row.label, quote=True)} actual: '
            f'{_measure_num(row.actual, suffix)}"></span>'
            f"{target_html}"
            f"</div>"
            f'<span class="dz-bullet-value">{value_html}</span>'
            f"</div>"
        )

    return (
        f'<div class="dz-bullet-region" data-dz-bullet>'
        f'<div class="dz-bullet-rows">{"".join(rows_html)}</div>'
        f'<p class="dz-bullet-summary">'
        f"{len(b.rows)} rows · scale 0–{_measure_num(round(b.max_value, 1), suffix)}"
        f"</p>"
        f"</div>"
    )

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

Revenue

72 / 80

1 rows · scale 0–100

Notes

Dual-lock root is data-bullet (contracts/bullet.py). Bands, the actual bar, and the target tick are absolutely positioned by SERVER-computed inline percentages (per-row data, the same contract as the funnel widths); each carries a title with its numeric range. Band fills come from the server's reference-band colour map. The value (and target, when set) renders as text beside the track; the mono summary line carries row count and scale.

Source files

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

site/registry.py · contracts/bullet.py

Bullet chart data Primitive

Copy this

Server exchange

Swap contract

Envelope response examples

How to use it

Seams

DOM contract

contracts/bullet.py

Ingestion model BulletBand

Exemplar render()

Notes

Source files

`contracts/bullet.py`

Ingestion model `BulletBand`

Exemplar `render()`