MetricCard
먼저 보고, 그다음 계약을 읽습니다
운영자·에이전트 대시보드용 KPI 타일 — 값 + 증감(delta) + 미니 스파크라인.
Component intent의도와 경계 읽기
label/value 를 큰 숫자로 세우고, 선택적으로 delta(방향+값+라벨)·미니 sparkline(inline SVG)·우상단 icon·회색 helperText 를 붙이는 KPI 타일. value 에는 항상 tabular-nums 가 적용돼 동적 갱신 시에도 자릿수가 흔들리지 않는다. loading=true 면 자체 skeleton 모드로 전환돼 별도 Skeleton 컴포넌트가 필요 없다. sparkline 은 축·툴팁 없는 6~24 point 추세선이며 데이터가 2점 미만이면 그려지지 않는다.
예제
SSOT에 등록된 실제 API 기준 snippet입니다. standalone 배지만 독립 실행 단위이며, fragment는 주변 state·handler 문맥을 생략합니다.
import { MetricCard } from "@axe/ui";<MetricCard label="활성 세션" value="1,284" delta={{ value: "+12.3%", direction: "up", label: "vs. 어제" }} trend={[8, 11, 9, 14, 13, 18, 21]} helperText="최근 30일"/>import { MetricCard } from "@axe/ui";<MetricCard label="집계 중" value="—" loading /><div class="axe-metric-card"> <div class="axe-metric-card__head"> <span class="axe-metric-card__label">활성 세션</span> <span class="axe-metric-card__icon">◇</span> </div> <div class="axe-metric-card__value">1,284</div> <div class="axe-metric-card__meta"> <span class="axe-metric-card__delta axe-metric-card__delta--up"> <span class="axe-metric-card__delta-arrow" aria-hidden="true">▲</span> <span class="axe-metric-card__delta-value">+12.3%</span> <span class="axe-metric-card__delta-label">vs. 어제</span> </span> <span class="axe-metric-card__helper">최근 30일</span> </div></div>Props
TSX 소스가 진실입니다. 주요 export 컴포넌트의 public API만 노출합니다.
| 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
label | React.ReactNode | 필수 | — | 지표 이름 — head 좌측에 작은 라벨로. |
value | React.ReactNode | 필수 | — | 주 수치 — 큰 글씨 + tabular-nums 로 렌더. |
delta | MetricDelta | — | — | 증감 배지. `{ value: ReactNode; direction: "up" | "down" | "flat"; label?: ReactNode }`. direction 이 색과 화살표(▲/▼/—)를 정한다 — up=success, down=danger, flat=muted. label 은 'vs. 어제' 같은 부가 맥락. |
trend | number[] | — | — | 미니 sparkline 데이터(6~24 point 권장). 2점 미만이면 미표시. currentColor 폴리라인만 그리는 무의존 inline SVG. |
icon | React.ReactNode | — | — | 우상단 아이콘 슬롯(보통 16~18px). |
helperText | React.ReactNode | — | — | 값 아래 회색 부가 문장(예: '최근 30일'). delta 와 같은 meta 줄에 놓인다. |
loading | boolean | — | — | true 면 label/value/helper 자리에 skeleton 3줄을 대신 그리고 aria-busy="true" 를 세운다. |
...rest | Omit<React.HTMLAttributes<HTMLDivElement>, "title"> | — | — | className 병합, 나머지는 루트 div 로 전파. ref 는 루트 div 로 forward. |
.axe-* 클래스 계약
React 밖에서도 같은 표면을 그리는 공개 계약입니다. stable은 minor 버전 안에서 이름을 바꾸지 않습니다.
| 클래스 | 안정성 | 용도 |
|---|---|---|
.axe-metric-card | stable | 루트 div — border·radius·padding 카드. |
.axe-metric-card__head | stable | label + icon 을 좌우로 배치하는 상단 줄. |
.axe-metric-card__label | stable | 지표 이름 라벨. |
.axe-metric-card__icon | stable | 우상단 아이콘 박스. |
.axe-metric-card__value | stable | 주 수치 — 큰 글씨 + tabular-nums. |
.axe-metric-card__meta | stable | delta + helper 를 담는 값 아래 줄. |
.axe-metric-card__delta | stable | 증감 배지 컨테이너(화살표+값+라벨). |
.axe-metric-card__delta--up | stable | 상승 — success 색. |
.axe-metric-card__delta--down | stable | 하락 — danger 색. |
.axe-metric-card__delta--flat | stable | 변화 없음 — muted 색. |
.axe-metric-card__delta-arrow | stable | 방향 화살표 글리프(▲/▼/—). aria-hidden. |
.axe-metric-card__delta-label | stable | delta 부가 라벨(예: 'vs. 어제'). |
.axe-metric-card__helper | stable | 값 아래 회색 부가 문장. |
.axe-metric-card__sparkline | stable | 미니 추세 SVG(polyline, currentColor). |
.axe-metric-card--loading | internal | skeleton 모드 마커. |
.axe-metric-card__skel | internal | skeleton 플레이스홀더 바(shimmer ::after). |
.axe-metric-card__skel--label | internal | label 자리 skeleton(폭 40%). |
.axe-metric-card__skel--value | internal | value 자리 skeleton(폭 70%). |
.axe-metric-card__skel--helper | internal | helper 자리 skeleton(폭 55%). |
접근성
키보드, ARIA, 구현 노트를 함께 검토합니다.
루트는 일반 div — 별도 role 없음. loading=true 동안 aria-busy="true". delta 화살표와 sparkline SVG 는 aria-hidden(focusable=false) 이라 보조기술은 값 텍스트만 읽는다.
방향(up/down)은 색과 화살표로만 시각 전달되므로, 스크린리더 사용자를 위해 delta.value 나 delta.label 에 부호·맥락(예: '+12.3%', '전주 대비 상승')을 담아 텍스트만으로 의미가 서게 할 것. value 의 tabular-nums 는 갱신 시 자릿수 정렬을 보장한다.