Skip to main content

CnStatWidget

Single-value KPI card (Statistic / KPI). Resolves one number from an OpenRegister source block at runtime (via generateUrl + the aggregate API) and renders it as a large formatted figure with an optional icon, caption, and click-through route. Registered in the dashboard widget catalog under the stat type and configured by CnStatWidgetForm.

Content shape​

{
"label": "Open leads",
"icon": "Cash",
"valueColor": "#0082c9",
"caption": "vs previous period",
"format": { "style": "number", "currency": "EUR", "decimals": 0 },
"source": { "register": "pipelinq", "schema": "lead", "metric": "count", "field": "", "filter": {} }
}

Endpoint binding (Wave 2, #91)​

Instead of an OpenRegister source, the tile can bind to an arbitrary app REST endpoint through the shared useEndpointSource engine — token-resolved params, per-(url+params) request dedup + short-TTL cache (four tiles reading one overview endpoint issue ONE request), and cn:page:refresh / cn:widget:refresh refresh wiring. Exactly one of source | endpointSource (validator-enforced; endpointSource wins when both slip through).

{
"label": "Revenue",
"icon": "CashMultiple",
"format": { "style": "currency", "currency": "EUR", "decimals": 0 },
"endpointSource": {
"url": "/apps/pipelinq/api/analytics/commercial",
"params": { "period": "@workspace.datePreset?" }
},
"valueField": "revenue",
"previousField": "previousPeriod.revenue",
"goodDirection": "up",
"variantWhen": [
{ "op": "gte", "value": 100000, "variant": "success" },
{ "op": "lt", "value": 10000, "variant": "warning", "icon": "AlertOutline" }
],
"clickRoute": "leads"
}
  • valueField — dot-path into the payload for the displayed value (omitted = the payload itself).

  • previousField — previous-period value → trend sublabel (arrow + percent-vs-previous, the pipelinq KPI contract), tinted good/bad by goodDirection ('up' default).

  • deltaField — a server-computed delta percent; wins over previousField.

  • variantWhen — first-match threshold rules [{ op: eq|neq|gt|gte|lt|lte, value, variant, icon? }]; the matched variant (default|primary|success|warning|error, plus danger as an error alias) re-tints the value + icon circle, icon overrides content.icon.

  • variant — the tile's resting colour, from the same set as variantWhen. It is the lowest-priority tint: a matched variantWhen rule wins, and so does the limit warning. Use it for a tile whose colour is a property of what it counts ("overdue" is always red) rather than of the current number; use variantWhen when the colour is a statement about the value. An unrecognised name is ignored rather than emitted, so a typo yields the default tint instead of a broken style.

  • caption — the small line under the value. {token} placeholders are resolved against the fetched payload, dot-paths included, so a tile can carry a secondary fact without an app writing its own card to render one: "caption": "{levelName} · {currentStreakDays}-day streak". A token that resolves to nothing collapses to an empty string (never the literal {token}), and the result is whitespace-collapsed so a missing middle field does not leave a gap. Interpolation applies to endpointSource payloads; a caption with no { is passed through untouched, and is translated via translate first either way.

  • clickRoute — whole-tile click-through (alias of route; route wins when both are set).

  • format styles: number, currency, percent, duration-hours (42.5h), decimal (one fraction digit by default). Numbers are formatted in the user's Nextcloud locale.

  • format.currencyField — on a detail page, the field of the page's object that holds the currency (a contract's own currency). The currency is taken from that field, then format.currency (a code, @config.currency or @object.currency), then the app's reporting currency (currency in the app config), then EUR.

  • limitField / limit — render the tile as a capacity pair (0 / 100). limitField is a dot-path into the payload, so a server-configured quota is read live instead of duplicated in the manifest; limit is a static number. The limit is formatted with the value's own format minus prefix/suffix (a suffix belongs to the pair, not to each half, so 0 % / 100 % is never produced). Reaching the limit tints the tile warning — unless a variantWhen rule already matched, which always wins.

  • dateRange — opts the tile into a period. Present and empty ({}) follows the ancestor CnDashboardPage range; add presets ([{ id, label?, from?, to? }]) to render a per-tile picker in the label row that overrides it. With presets and no page range the tile starts on dateRange.default (a preset id), else on the first preset, so the picker never opens blank and the first request already carries a range. The active range is exposed to endpointSource and to the tile's route as @range.from / @range.to / @range.preset.

    A tile that declares no dateRange is unaffected by the page range. That is deliberate: adding a range to an existing dashboard must not silently change what its tiles request.

Share and average tiles​

An OpenRegister source is a count by default. Two more shapes give the tiles of a service board:

{
"label": "Within the deadline",
"format": { "style": "percent", "decimals": 0 },
"source": {
"kind": "ratio", "register": "app", "schema": "ticket", "metric": "count",
"numerator": { "filter": { "assignee": "@me", "answeredInTime": true } },
"denominator": { "filter": { "assignee": "@me", "status": "resolved" } }
}
}

kind: "ratio" is the numerator over the denominator, times 100 (no value while the denominator is 0). Each part may carry its own metric, field and via, so a share of a sum is two sums. A field cannot be compared with another field in a filter, so a share such as "answered by the deadline" needs a stored flag on the object to count.

{
"label": "Average answer time",
"format": { "style": "decimal", "decimals": 1, "suffix": " days" },
"source": {
"kind": "elapsed", "register": "app", "schema": "ticket",
"from": "occurredAt", "to": "resolvedAt", "unit": "days",
"filter": { "assignee": "@me", "status": { "in": ["resolved"] } }
}
}

kind: "elapsed" is the average time between two date fields of the matching objects, in unit (days default, hours, minutes). The aggregation endpoint averages one numeric field, not a difference, so the widget reads the matching objects (up to limit, default 1000) and averages them itself. Objects missing either date, or whose to is before from, are left out; with none left the tile has no value.

A count whose filter holds a list of values ({ "status": { "in": [...] } }, notIn) is read from the list endpoint's total, because the aggregation endpoint cannot express a list. via: "list" forces that for a count of empty values: the aggregation endpoint has no null operator.

Quota tile​

{
"id": "quota-schedules",
"type": "stat",
"content": {
"label": "Schedules",
"icon": "CalendarClock",
"endpointSource": { "url": "/apps/hermiq/api/tenant-ops/quota" },
"valueField": "schedules.count",
"limitField": "schedules.limit"
}
}

Reading a field off the record (objectField)​

The two modes above ask a server "how many". objectField asks the record the detail page has already loaded, so the tile costs no request at all. It is what lets a KPI row headline a case's type or its assignee beside the counts, instead of those facts sitting three rows down in the properties grid.

{
"type": "stat",
"content": {
"label": "Case type",
"icon": "FileTree",
"objectField": {
"field": "caseType",
"resolve": { "register": "dossiq", "schema": "caseType", "labelField": "title" }
}
}
}

A plain scalar needs no resolve, and objectField: "priority" is accepted as shorthand for { field: "priority" }.

resolve is for a field holding a reference uuid, which is not something to show a person. The label is looked up through the shared object store, so per-schema caching and in-flight dedup come for free. It is opt-in rather than inferred: guessing that a string looks like a uuid would turn a legitimate identifier into a failed fetch.

A non-numeric value renders as text, because formatMetricValue returns String(value) for anything non-finite.

Showing a state as a badge (display)​

display: "badge" renders the value as CnStatusBadge instead of as a headline figure. A status is a state, not a quantity, and a state set in 32px type reads as a number that went wrong.

{
"type": "stat",
"content": {
"label": "Status",
"display": "badge",
"emptyText": "Unknown",
"objectField": {
"field": "status",
"resolve": {
"register": "dossiq",
"schema": "statusType",
"labelField": "name",
"variantField": "isFinal",
"variantMap": { "true": "success", "false": "info" }
}
}
}
}

The badge takes its colour from the first rule that names one: an overrides match, a variantWhen rule, the limit warning, the resolved row, then the static variant. danger is accepted as an alias of error, and a name the badge does not know is skipped so the next rule decides.

resolve.variantField names a field on the looked-up row and resolve.variantMap maps its value to a variant, so a status colours itself from its own record rather than from a colour list copied into every manifest. Without a map, a row value that is already a variant name is used as is.

emptyText replaces the dash for a value that is empty or that the lookup could not resolve. It is translated like label and caption. Without it the raw value stays visible, because a blank tile says nothing at all.

Counting down to a date (display: countdown)​

display: "countdown" reads the tile's value as a date and renders the time remaining, so a deadline is a configured KPI tile like any other rather than a component an app writes by hand. It reads whatever the tile already resolves: a property off the record through objectField, or a payload field through endpointSource + valueField.

{
"type": "stat",
"content": {
"label": "Deadline",
"icon": "CalendarClock",
"display": "countdown",
"objectField": "dueDate",
"countdown": {
"unit": "days",
"warnAt": 14,
"dangerAt": 5,
"pastLabel": "Overdue by {n} days",
"emptyText": "No deadline"
}
}
}
KeyWhat it does
unitdays is the only unit, and the tile says so rather than pretending otherwise. Any other value is read as days.
warnAtThe tile turns warning at or below this many days left. Inclusive.
dangerAtThe tile turns error at or below this many days left. Inclusive, and it wins over warnAt.
futureLabelWording for a date still to come. {n} is the number of days. Defaults to 1 day left / {n} days left.
todayLabelWording for a date due today. Defaults to Today.
pastLabelWording for a date that has passed. {n} is how many days past. Defaults to Overdue by 1 day / Overdue by {n} days.
emptyTextWording for an absent or unreadable date. Falls back to the top-level emptyText, then to the dash.

Every one of these is translated the way label and caption are, so a wording written in a manifest still reaches the reader in their own language.

Six things this mode decides on your behalf, each of them a way a deadline tile goes wrong:

  • A date that has passed is not a negative number. It reads as overdue in its own words, and it is the error colour whether or not dangerAt is set. -3 days left is the failure the mode exists to prevent.

  • Today is zero. Not one, which would claim a day that is already being spent, and not minus one, which would call a deadline that has not passed overdue. Zero renders todayLabel, so a reader sees Today rather than 0 days left.

  • A date the tile cannot read renders emptyText. Absent, empty, and unparseable are the same answer, and none of them is NaN or Invalid Date. With no emptyText anywhere the tile keeps the dash.

  • Both thresholds include their own day, and dangerAt wins. At exactly 5 days with dangerAt: 5 the tile is error, not warning, even though warnAt: 14 also matches.

  • overrides still win. A suspended case shows its override label and its override colour, not its deadline colour, exactly as it does in badge mode. The full order is: an overrides match, a variantWhen rule, the countdown threshold, the limit warning, the resolved row, the static variant.

  • Days are counted between calendar days, not as elapsed milliseconds. A deadline is a day on a calendar, not an instant. Subtracting timestamps would make a deadline at 23:00 tonight and one at 01:00 tomorrow two hours apart while 09:00 tomorrow is a whole day, so the same calendar distance would render as two different answers because of a time somebody happened to type. Both ends are collapsed onto the local calendar day they fall on and then subtracted.

    A bare YYYY-MM-DD, which is how OpenRegister stores a date property, is read as the local day it names. new Date("2026-09-13") is specified to parse a date-only string as UTC midnight, so west of Greenwich it lands on the 12th and every countdown built on it would be a day short.

The day count is taken when the tile renders. A tile left open across midnight keeps the number it was drawn with until something else on the page re-renders it.

Recolouring from the record (overrides)​

overrides tests the bound record and replaces the label, the colour and the icon of the tile. The first match wins.

{
"overrides": [
{ "when": { "field": "suspended" }, "label": "Suspended", "variant": "warning", "icon": "PauseCircle" }
]
}

when takes the visibleWhen comparison grammar, so { field, op, value } works alongside the truthiness form above. An override outranks emptyText, which is what makes a suspended record with no status still read as suspended. It recolours the plain text value too, not only the badge.

Props​

PropTypeDefaultDescription
contentobject{}The KPI config blob (label, icon, format, source or endpointSource + valueField/limitField/dateRange/previousField/deltaField/variantWhen/clickRoute/display/countdown, …).
translatefunctionnullTranslate function for the label / caption source strings. Falls back to the injected cnTranslate (identity by default).

Notes​

  • An unresolvable reference shows the raw uuid, not a blank. A blank KPI says nothing at all, so an id the store cannot resolve stays visible, the same way CnFkResolveCell behaves.

  • A number never clips. When the value is wider than its tile (a currency total in a 162px tile), its font steps down until it fits, re-measured whenever the value or the tile's width changes, never under 14px; at 14px a number that still does not fit wraps. A value that fits keeps its own size, and a text value keeps its own wrap and clamp.

  • A countdown reads calendar days, so the answer never depends on the time of day somebody typed. The reasoning, and the UTC-midnight parse it avoids, are in the calendarDay docblock in CnStatWidget.vue.

  • source supports the OpenRegister-backed kinds (metric: 'count' \| 'sum' \| 'avg' \| …) and a legacy { kind: 'endpoint', url } form for arbitrary endpoints (never served from the cache, though tiles loading at once or refreshed together share one request; prefer endpointSource).

  • Self-contained card surface — rendered flush and centred (no inner scrollbar).

  • Filter tokens (@page.*, @object.*, @workspace.*, @range.*) are resolved from injected dashboard/detail context when present, in the endpointSource and in the tile's route alike, so a tile on a detail page can link to { name: 'Traffic', query: { portal: '@object.slug' } }. A route token that stays unresolved is dropped from the URL.

  • The tile injects cnDashboardDateRange — the same ref CnChartWidget reads — so a tile and a chart on one dashboard always agree on the period.

A caption for one and for many​

caption can be { singular, plural }. The singular shows for a count of one, the plural otherwise. The count is the caption's own (captionSource), or the tile's number when the caption has none. Each form is translated on its own, so a Dutch reader sees "1 loopt vandaag af" and "2 lopen vandaag af". zeroText still applies at zero.

{ "caption": { "singular": "{count} ends today", "plural": "{count} end today" },
"captionSource": { "filter": { "deadline": { "gte": "@today", "lt": "@today+1d" } }, "zeroText": "nothing ends today" } }

Colouring the caption (captionVariant, captionVariantWhen, overrides)​

The caption can be coloured without recolouring the tile: captionVariant sets it outright (primary | success | warning | error), captionVariantWhen is a list of { op, value, variant } rules on the value (the variantWhen shape, first match wins), and a record override can carry caption and captionVariant to replace and colour it. {value} in a caption is the tile's own number, so a register-counted tile can read "1 due today".

{ "label": "Deadline within 5 days", "caption": "{value} due today",
"captionVariantWhen": [{ "op": "gte", "value": 1, "variant": "error" }] }

The caption then carries cn-kpi-card__label--<variant>; the colours come from the status text tokens.

A caption with its own count (captionSource)​

A caption can count something else than the tile does: "3" open requests with "1 waiting for 6 days" under it. captionSource is a second count, { register?, schema?, metric?, field?, filter?, via?, zeroText? }; register and schema default to the tile's source. The token {count} in the caption is that count, and captionVariantWhen then tests that count instead of the tile's value. While the count is zero the caption is left out, or reads zeroText when that is set; a count that could not be read leaves the caption out.

{ "label": "Open requests", "layout": "stacked",
"source": { "register": "portaliq", "schema": "portalAccessRequest", "filter": { "state": "pending" } },
"caption": "{count} waiting for more than 5 days",
"captionSource": { "filter": { "state": "pending", "escalated": true } },
"captionVariantWhen": [{ "op": "gte", "value": 1, "variant": "error" }] }

A share (captionSource.kind: "ratio")​

With kind: "ratio" the caption is a share: the numerator over the denominator, times 100. Each part is { metric?, field?, filter?, via? }, as in the tile's own ratio source. Without a numerator the tile's own value is the numerator. {ratio} (and {count}) in the caption is the share, with decimals fraction digits (0 by default) in the reader's locale. A zero or unread denominator leaves the caption out.

{ "label": "1 to 30 days", "layout": "stacked",
"source": { "register": "shillinq", "schema": "ARInvoice", "metric": "sum", "field": "grossAmount", "filter": { "dueDate": { "gte": "@today-30d", "lt": "@today" } } },
"caption": "{ratio}% of open",
"captionSource": { "kind": "ratio", "denominator": { "metric": "sum", "field": "grossAmount", "filter": { "lifecycleState": ["issued", "overdue", "disputed"] } } } }

The longest wait (captionSource.metric: "daysSinceEarliest")​

With metric: "daysSinceEarliest" and a date field, {count} is the number of whole days from the earliest field date among the matching records to today. The tile reads it from one list request, ordered by the field, of the first record that has it. No matching record, or one dated today, counts 0, so the caption reads zeroText or is left out.

{ "label": "Waiting on the applicant", "layout": "stacked",
"source": { "register": "dossiq", "schema": "case", "filter": { "waitingOnApplicant": true } },
"caption": "longest: {count} days",
"captionSource": { "metric": "daysSinceEarliest", "field": "currentStatusEnteredAt", "filter": { "waitingOnApplicant": true } } }

The stacked tile (layout: "stacked")​

content.layout: "stacked" is the board's KPI tile: no icon circle, the label as plain 14px muted text, the value at 34px/700 in the text colour, and the caption on a line of its own under the value. A linked stacked tile is not underlined. Theme hooks: --cn-kpi-stacked-padding (10px 6px, which adds up with a dashboard cell's 8px 14px to 18px 20px), --cn-kpi-stacked-gap, --cn-kpi-stacked-title-size, --cn-kpi-stacked-title-weight, --cn-kpi-stacked-value-size, --cn-kpi-stacked-value-color.

{ "type": "stat", "content": { "label": "My open cases", "layout": "stacked", "caption": "3 new this week" } }

A second caption line (content.note)​

content.note (an i18n key) adds a line under the caption, as "3 deadlines this week" under a count; content.noteVariant colours it with the captionVariant names. It is static text: a second count source is not supported yet.

The board look tile​

With the app in the board look (cnLook), the stacked tile (and a stacked CnStatsBlock) draws a 14px grey label, the value at 28px/700 (line height 1.1), a 13px note, a 6px gap and 18px 20px padding. It draws no icon circle; the icon shows as an 18px glyph before the label only when the tile links to a filtered list (content.link or route). A caption variant colours the note only for warning, error or danger; success and info read as the plain grey note (the rule still evaluates, so the screen reader text is unchanged). Without the look the stacked value stays 34px.

In the board look a tile that names no content.layout takes the stacked layout, since every KPI tile on the screens is stacked; an explicit layout keeps what it says. A linked board tile is one link without underline, in any layout. The value keeps its state colour (variant, variantWhen, an override), the success tone included.

content.iconPlacement: "end" draws the icon in a 32px circle at the right of the label row instead of the glyph before the label, tinted by the tile's state: primary light for a plain tile, else the success, warning or error tone the value takes. It has no effect without the board look.

{ "type": "stat", "content": { "label": "Te laat", "icon": "AlertCircleOutline", "iconPlacement": "end", "variant": "error", "caption": "actie nodig" } }

content.iconPlacement: "top" draws the icon in a 42px circle above the label (the learniq Today tiles), tinted the same way, with no glyph before the label. It has no effect without the board look either.

{ "type": "stat", "content": { "label": "Openstaande betrokkenheidssignalen", "icon": "AlertOutline", "iconPlacement": "top", "variant": "warning" } }

Reading only when asked (loadOn: "request")​

An endpoint whose every read is recorded (an audit trail per read, say) should not be read because somebody opened the page. With loadOn: "request" in the endpointSource block the widget reads nothing on mount: it shows a button (requestLabel, default "Show") with an optional requestHint sentence above it, and reads only when the reader presses it. When the request changes (another period from the page filters), the last answer is dropped and the widget waits for the next press. Page and widget refreshes do not read a widget that is waiting. Each press is a fresh read, past the shared cache.

"endpointSource": {
"url": "/apps/dossiq/api/woo/reports/throughput",
"params": { "from": "@workspace.from", "to": "@workspace.to" },
"responsePath": "rows",
"loadOn": "request",
"requestLabel": "Show",
"requestHint": "Every time you open this report, it is recorded."
}

CnWidgetObjectTable, CnChartWidget and CnStatWidget all honour it; the labels go through the app's translate.