# KPICard

> Card hiển thị metric/KPI — label + big number + delta % + optional sparkline. Tabular numbers cho alignment column.

**Archetype mapping:** A (Dashboard) — primary building block cho dashboard analytics.

## API

| Prop | Type | Default | Description |
|---|---|---|---|
| `label` | `ReactNode` | required | Tên metric (vd "Doanh thu hôm nay") |
| `value` | `ReactNode` | required | Số liệu chính (text-3xl/4xl, font-display, tab-num) |
| `delta` | `KPIDelta` | — | Badge delta % so với kỳ trước |
| `sparkline` | `ReactNode` | — | Mini chart inline (SVG hoặc charting lib) |
| `hint` | `ReactNode` | — | Text-xs phụ ở footer (vd "so với hôm qua") |
| `icon` | `ReactNode` | — | Icon góc phải header |
| `className` | `string` | — | Override container |

### `KPIDelta`

| Field | Type | Description |
|---|---|---|
| `value` | `ReactNode` | Text delta (vd "+12.3%") |
| `direction` | `'up' \| 'down'` | Hướng arrow icon |
| `positive` | `boolean?` | Override màu — nếu không pass, suy từ `direction === 'up'`. Dùng khi `up` không phải tốt (vd churn tăng = bad) |

## Variants

Không có variant style — single layout.

Logic màu delta:
- `positive: true` (hoặc `direction='up'` default) → bg-success-soft text-success
- `positive: false` (hoặc `direction='down'`) → bg-danger-soft text-danger

Override `positive` khi metric ngược ý (vd churn tăng = xấu, set `direction='up'` + `positive: false`).

## Composition

Standalone — không có sub-component. Sparkline slot nhận bất kỳ ReactNode (recharts mini chart, custom SVG path, etc.).

## States

- **Default**: chỉ label + value
- **Với delta**: badge bên cạnh value
- **Với sparkline**: chart phía dưới
- **Với hint**: text-xs cuối card
- **Với icon**: icon góc phải header (text-text-3)

## Usage

```tsx
import { KPICard } from '@cowork/ui';

<KPICard
  label="Doanh thu hôm nay"
  value="12.4M"
  delta={{ value: '+18.2%', direction: 'up' }}
  hint="so với hôm qua"
  icon={<DollarIcon />}
  sparkline={<MiniSparkline data={revenueLast7d} />}
/>

// Churn rate — up là xấu
<KPICard
  label="Tỉ lệ huỷ booking"
  value="4.2%"
  delta={{ value: '+0.8%', direction: 'up', positive: false }}
  hint="7 ngày gần đây"
/>
```

## Real-world example

- An Nhien admin dashboard: 4 KPICard grid `[Doanh thu hôm nay · Đơn mới · Khách mới · Tỉ lệ chuyển đổi]` — mỗi card so với hôm qua.
- KHI Wellness funnel dashboard: KPICard cho từng bước funnel `[Lead · Trial · Active · Member 30d]` — delta so với tuần trước.
- Cakeinsights cross-brand: KPICard cho `[Tổng chat 4 kênh · Phản hồi <5min · NPS]` mỗi brand.

## Accessibility

- Value dùng `tab-num` (tabular numerals) cho alignment khi nhiều KPICard cạnh nhau
- Delta direction là arrow SVG có `aria-hidden` implicit
- Label là `<span>` text-text-2 — screen reader đọc tự nhiên
- Color delta không phải tín hiệu duy nhất — có arrow direction kèm

## Responsive behavior

- Padding `p-5 md:p-6` — tăng nhẹ desktop
- Value text `text-3xl md:text-4xl` — responsive scale
- Caller nên grid 4-col desktop, 2-col tablet, 1-col mobile:
  ```tsx
  <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-4 gap-4">
    <KPICard … />
  </div>
  ```

## Related

- [[Card]] — primitive cơ bản, KPICard là specialization cho metric
- [[DataTable]] — pair với KPICard ở row trên (KPI summary + detail table dưới)

## Source

`react/src/organisms/KPICard.tsx`