# StatCard (stat-card)

> One number with its context on a raised Card: mono label, large value, and a short sub line, stacked or in a row.

- Entry: component
- Category: UI
- Preview capabilities: none (still preview)
- Runtime: React
- Needs Remotion: no
- QA page: https://jbm-ui.bns.studio/c/stat-card
- JSON: https://jbm-ui.bns.studio/catalog/stat-card.json
- Registry item: https://jbm-ui.bns.studio/r/stat-card.json (source code in files[].content)

## Install

```sh
npx shadcn@latest add @jbm/stat-card
```

Also installs @jbm/tokens, @jbm/card (registry dependencies install automatically).

## Required setup

1. Add the `@jbm` registry to components.json (keep any entries already there):

   ```json
   {
     "registries": {
       "@jbm": "https://jbm-ui.bns.studio/r/{name}.json"
     }
   }
   ```

2. Map `@/*` to `./src/*` in tsconfig.json `compilerOptions.paths`, so `@/jbm/…` imports resolve to src/jbm/.

## Files

Each file's source code is in the registry item JSON (https://jbm-ui.bns.studio/r/stat-card.json, files[].content).

| Source path | Installs to | Import |
| --- | --- | --- |
| `registry/jbm/ui/stat-card.tsx` | `src/jbm/ui/stat-card.tsx` | `@/jbm/ui/stat-card` |

## API

### `StatCard` (component)

Fixed-size Card (border-box) holding a mono label, an 800-weight value, and an optional sub line. Stacked by default for landscape; `row` puts the value (fixed 400px column) beside the label and sub for vertical stages.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | required | Mono caption naming the number, 22px in the dim color. |
| `value` | `React.ReactNode` | required | The number or short value; 96px stacked, 84px in row mode, -3px tracking. |
| `sub` | `string` | none | Optional one-line context under the label (row) or under the value (stacked); dim when stacked, ink in row mode. |
| `valueColor` | `string` | `color.accent` | Value color; defaults to the vermilion accent. Use color.ink when another element already carries the accent. |
| `w` | `number` | `520` | Card width in stage pixels, including padding and border. |
| `h` | `number` | `300` | Card height in stage pixels, including padding and border. |
| `row` | `boolean` | `false` | Lays value, then label and sub, side by side with 22×34px padding and a 30px gap; the scene compiler uses it for vertical stages. |
| `style` | `React.CSSProperties` | none | Inline styles merged after the size and row layout. |

## Stage

Declared in stage pixels at the documented defaults.

| Orientation | Width | Height |
| --- | --- | --- |
| Landscape (1920×1080) | 520 | 300 |
| Vertical (1080×1920) | 520 | 300 |

Card is border-box, so the defaults w=520 and h=300 are the outer size in either orientation. For vertical stages SceneFromSpec renders `row` cards at the full content width (936) and h=180, and the gallery shows w=620 with h=245 stacked and h=140 in a row.

## Examples

### Stacked and row cards

```tsx
import { StatCard } from "@/jbm/ui/stat-card"

<StatCard label="Contexto" value="1M" sub="tokens" w={620} h={245} />
<StatCard row label="Latencia" value="0.8s" sub="p50" w={620} h={140} />
```

### Ink value beside another accent

```tsx
import { StatCard } from "@/jbm/ui/stat-card"
import { color } from "@/jbm/lib/tokens"

<StatCard label="Precisión" value="86%" valueColor={color.ink} />
```

## QA

- Content does not fit itself: check the widest value and longest sub stay inside w×h in both layouts, since the card has a fixed height and does not clip or shrink text.
- In row mode the value column is a fixed 400px; with w below about 500 the label and sub have almost no room.
- Compare stacked landscape and row vertical cards on cream: fine border, layered shadow, and inset highlight come from Card.

## Related

Installs:

- [Tokens (tokens)](https://jbm-ui.bns.studio/catalog/tokens.md)
- [Card (card)](https://jbm-ui.bns.studio/catalog/card.md)

Installed by:

- [SceneFromSpec (scene-spec)](https://jbm-ui.bns.studio/catalog/scene-spec.md)

## More

- [llms.txt](https://jbm-ui.bns.studio/llms.txt): index of every item
- [catalog.json](https://jbm-ui.bns.studio/catalog.json): every item as JSON
- [Agent contract](https://jbm-ui.bns.studio/docs/agent-contract.md): what each field means
