Stat

아이콘·수치·라벨로 이루어진 요약 타일 컴포넌트

개요

Stat 컴포넌트는 아이콘과 수치, 라벨을 한 타일로 보여 줍니다. 값은 prop으로 주고, 세부 설정이 필요하면 부품(Stat.Icon, Stat.Value, Stat.Label)을 요소로 넘깁니다.

주요 특징

• ✅ 값 또는 요소: icon·value·label에 문자열·숫자를 주면 부품으로 감싸고, 요소를 주면 그대로 배치
• ✅ 아이콘 위치: top · bottom · left · right (기본 right)
• ✅ 내용 정렬: contentAlign으로 start · center · end
• ✅ 부품: Stat.Icon(변형·크기), Stat.Value(천 단위 구분), Stat.Label
• ✅ 클릭 가능: onClick을 주면 role="button"과 Enter·Space 동작을 제공
• ✅ 접근성: 포커스 링, 아이콘 aria-hidden/aria-label, DOM 순서 아이콘 → 라벨 → 수치

기본 사용

아이콘·수치·라벨을 prop으로 주어 타일을 렌더링합니다.

import { Stat } from "@vortex/ui-cals"
import { Users } from "lucide-react"
 
<Stat icon={<Stat.Icon icon={<Users />} />} value={1234} suffix="명" label="방문자" />

icon에 요소를 주면 그대로 배치되므로 배경(원)이 없습니다. 아이콘 요소에 배경이 필요하면 Stat.Icon으로 감쌉니다.

문자열 아이콘

문자열·숫자 icon은 자동으로 Stat.Icon으로 감쌉니다.

<Stat icon="A" value={7} label="문자열 아이콘은 원으로 감싼다" />

아이콘 위치

iconPosition으로 아이콘을 내용의 위·아래·왼쪽·오른쪽에 둡니다. top·bottom은 세로 배치, left·right는 가로 배치입니다.

<Stat icon={<Stat.Icon icon={<Heart />} />} iconPosition="left" value={42} label="left" />

부품으로 세부 설정

Stat.Icon의 variant·size, Stat.Value의 thousandSeparator처럼 세부 설정은 부품을 요소로 넘겨 정합니다. 부품은 Stat 안에서만 사용합니다. 토큰이 Stat 루트에 걸려 있기 때문입니다.

<Stat
  icon={<Stat.Icon icon={<ChartColumn />} size="sm" />}
  value={<Stat.Value value={1234567} thousandSeparator suffix="원" />}
  label={<Stat.Label label="매출" />}
/>
 
<Stat
  icon={<Stat.Icon icon={<ChartColumn />} variant="ghost" size="lg" />}
  value="87"
  suffix="%"
  label="달성률"
/>

크기 단계(sm md lg xl) 밖의 아이콘 크기가 필요하면 루트 또는 Stat.Icon의 className에서 --icon-size를 덮습니다. 가로 배치(left·right)에서 아이콘 영역이 차지하는 비율(기본 37.5%)은 루트 className에서 --ratio로 덮습니다. top·bottom에서는 --ratio를 쓰지 않습니다.

긴 수치

수치는 내용 영역 폭을 넘으면 줄임표로 잘리고, 접미어는 항상 보입니다. 자동 툴팁은 없으므로 전체 값을 보여 주려면 Stat.Value에 title을 직접 넘깁니다.

<Stat
  icon={<Stat.Icon icon={<ChartColumn />} size="sm" />}
  value={
    <Stat.Value
      value={1234567890123}
      thousandSeparator
      suffix="원"
      title="1,234,567,890,123원"
    />
  }
  label="누적 매출"
/>

줄바꿈으로 전체 값을 보여 주려면 Stat.Value의 className에 whitespace-normal break-all을 줍니다.

내용 정렬

contentAlign을 주지 않으면 아이콘 위치에서 정합니다. left는 start, right는 end, top·bottom은 center입니다.

<Stat
  icon={<Stat.Icon icon={<Heart />} size="sm" />}
  iconPosition="top"
  contentAlign="end"
  value={99}
  label="end"
/>

클릭

onClick을 주면 role="button", Enter·Space 동작, 포인터 커서가 붙습니다. 클릭하면 MouseEvent, Enter·Space로 활성화하면 KeyboardEvent가 전달됩니다.

<Stat icon={<Stat.Icon icon={<Heart />} />} value={count} label="클릭 횟수" onClick={() => setCount((c) => c + 1)} />

API Reference

Stat Props

그 밖의 HTML 속성과 ref를 그대로 받습니다.

Stat.Icon Props

그 밖의 HTML 속성과 ref를 그대로 받습니다.

Stat.Value Props

그 밖의 HTML 속성과 ref를 그대로 받습니다.

Stat.Label Props

그 밖의 HTML 속성과 ref를 그대로 받습니다.

토큰

루트 data-token="stat" 한 블록입니다. 부품에는 data-token이 없고 루트 값을 상속합니다.

수치 글자색 토큰은 없습니다. 수치는 부모의 글자색을 상속합니다.

--ratio와 --icon-size는 토큰이 아니라 className으로 덮는 변수입니다. 토큰 시트에 두지 않습니다.

접근성

권장 사항

• ✅ onClick이 있으면 role="button", tabIndex, Enter·Space 키 동작을 제공
• ✅ 소비자가 넘긴 role·tabIndex·onKeyDown은 유지
• ✅ 키보드 포커스 시 focus-visible 링 표시
• ✅ 장식용 아이콘은 aria-hidden, 의미가 있으면 Stat.Icon의 aria-label로 접근성 이름 제공
• ✅ DOM 순서는 아이콘 → 라벨 → 수치
• ✅ 잘린 수치의 전체 값은 소비자가 넘긴 title로만 표시 (마우스 보조, 스크린리더는 DOM 전체 텍스트를 읽음). 잘리면 안 되는 곳은 줄바꿈(whitespace-normal break-all) 사용
• ❌ 클릭 가능한 Stat 안에 버튼·링크 같은 상호작용 요소를 넣지 않기

관련 컴포넌트

• Label: 제목과 데이터를 조합해 표시하는 읽기 전용 컴포넌트
• Progress: 진행률을 프로그레스 바로 표시하는 컴포넌트
• Timeline: 시간 순서에 따라 항목을 카드 형태로 표시하는 컴포넌트