A dataset-bound KPI tile can render no sub-caption at all: DatasetWidget drops every measure after values[0] and never reads options.description

[os-warren]

Found while building a manager dashboard in objectstack-ai/duly (duly#109), where the card asks a KPI tile for a rate plus a two-number sub-caption under it ("N to confirm / M to approve"). Neither of the two ways to author that reaches the screen, and both fail silently.

Measured against @objectstack/spec 17.2.0 and this repo's plugin-dashboard.

1. Extra values[] on a metric tile are dropped without a word

packages/plugin-dashboard/src/DatasetWidget.tsx, the if (isMetric) branch:

const f = measureField(values[0]);
const value = state.rows[0]?.[values[0]] ?? 0;
…
<span className="text-xs text-muted-foreground">{headerLabel(values[0])}</span>

values is z.array(z.string()).min(1) on DashboardWidgetSchema — an author may legally select three measures. The query runs for all of them and the renderer shows the first. No warning, no console message; the widget looks correct and is answering a narrower question than the metadata asks.

The isMetric family is metric / kpi / gauge / solid-gauge / bullet (and any widget with no dimensions), so there is no chart type an author can switch to and keep a tile.

2. The authored sub-caption slot is unreachable on every spec-valid widget

options.description is the sub-caption — it has its own translation key ({ns}.dashboards.{dash}.widgets.{id}.subCaption), the server overlays it in translateDashboard, and DashboardRenderer.tsx resolves it properly in tWidgetSubCaption (added by #4032 item 4).

But the resolved value is only ever attached inside getComponentSchema(), on the two inline arms:

const subCaption = tWidgetSubCaption(widget);
if (isObjectProvider(widgetData)) {
  return { type: 'object-metric', …, description: subCaption, … };
}
return { type: 'metric', …, description: subCaption, … };

A dataset-bound widget never goes through getComponentSchema() — renderWidget routes it to <DatasetWidget> — and DatasetWidget does not read widget.options for a caption at all.

dataset is REQUIRED on DashboardWidgetSchema (dataset: SnakeCaseIdentifierSchema, no .optional()), so every widget the current spec admits takes the DatasetWidget path. The sub-caption key is therefore declared end-to-end — spec slot, translation node, server overlay, renderer resolver — and consumed by nothing: the ADR-0049 declared-but-unenforced shape, with four live pieces of plumbing pointing at a dead end.

MetricWidget's bare layout already renders a caption row (gates its whole caption row on the value's truthiness), so the missing piece is on the dataset side only.

Repro

{
  id: 'list_completeness',
  type: 'metric',
  dataset: 'duly_duty_register',
  values: ['approved_rate', 'duties_to_confirm', 'duties_to_review'],
  options: { description: 'awaiting confirmation / awaiting approval' },
}

Renders the big number for approved_rate and nothing else. Expected: the other two measures reachable as a caption line, and/or options.description honoured.

Why it matters more than it looks

A KPI tile is the one widget where a missing element is invisible. A chart with a series missing looks wrong; a tile that quietly answers with one of the three numbers it was given looks finished. On the dashboard this was found on, the tile's job is a governance completeness rate whose whole point is the two pending counts beside it.

What duly does meanwhile

Ships the tile with values: ['approved_rate'] and no sub-caption, and says so in the dashboard's module header rather than faking the counts as static text. The two extra measures are deliberately not declared on the dataset until this lands, so nothing declared there is unconsumed.

Suggested shape

Either is enough for the case above; the first is the smaller change:

1. DatasetWidget's metric branch reads widget.options.description and renders it in the caption row, matching MetricWidget's bare layout — the key is already resolved and translated by the time the widget is rendered, it just is not passed down.
2. Render measures after values[0] as secondary values on the tile (the same row the compareTo delta already occupies), so a tile can carry its own breakdown.

If neither is wanted, the honest alternative is to retire options.description under ADR-0049 rather than leave four layers of plumbing wired to a slot no author can reach.