# Stat card

One metric: label, value, change against a named period, and a small trend. The delta's colour is direction × whether up is good, and it carries an arrow, so a drop in errors reads as good news. A value that couldn't be computed says "Not computed" and why — never a zero.

- Registry name: `stat-card` (`@candor/stat-card`)
- Tier: Pro. Installing it needs a Pro, Premium or Team licence key: the person runs `npx candor-ui key <key>` themselves; never ask for the key in chat or write it to a file.
- Docs: https://candor.themethodic.com/docs/stat-card

## Install

```bash
npx candor-ui add stat-card
```

Run `npx candor-ui@latest init` once first (https://candor.themethodic.com/get-started.md). Without the CLI: `npx shadcn@latest add @candor/stat-card`.
It brings in: data, locale, scale, sparkline, utils.
npm packages: lucide-react@^1.67.0.

## Example

```tsx
"use client"

import { KpiRow } from "@/components/stat-card"
import type { Kpi } from "@/lib/data"

const kpis: Kpi[] = [
  { label: "Deploys to Production", value: 34, delta: { value: 6, vs: "last month", good: "up" }, trend: [21, 25, 28, 24, 30, 34] },
  { label: "Test coverage", value: 0.78, format: "percent", delta: { value: 0.06, vs: "4.1 release", good: "up" }, trend: [0.68, 0.7, 0.69, null, 0.72, 0.76, 0.78] },
  { label: "Failing tests", value: 6, delta: { value: -4, vs: "last week", good: "down" } },
  { label: "Users affected", value: null, missing: "Needs session analytics, which isn’t connected." },
]

export default function Example() {
  return <KpiRow kpis={kpis} />
}
```

## <StatCard>

Props:

- `kpi: Kpi`: The metric: label, value (null when not computed, with why), format, delta against a named period, and trend.
- `className?: string | undefined`

## <KpiRow>

A row of stat cards with one rhythm.

Props:

- `kpis: Kpi[]`: The metrics, one card each, keyed by label.
- `className?: string | undefined`

## Strings (`statCard`)

The fixed words, English by default. Override any of them under `statCard` in `<LocaleProvider strings={{ statCard: { … } }}>`; the table is exported as `statCardStrings`.

- `notComputed`: Not computed
- `trend`: {label} trend
- `vs`: vs {period}

## Rules for using Candor UI

- Components take plain typed data. Never pass model output as HTML or render it as a link; messages are typed blocks.
- A control that can't be used says why: wrap it in `<Locked reason="…">`, don't just disable it.
- Don't show a value you don't have: leave it out (it renders as —) rather than guess. An estimate is labelled as one.
- Nothing is pre-selected in a decision a person makes, and the agent is named from your app's data, never from model output.
- Your app's words go in `LocaleProvider` (fixed strings) and `TermsProvider` (nouns); entity kinds and agent roles in `EntityKindsProvider` and `AgentRolesProvider`.