Statistic

이름이 붙은 숫자, 그리고 비교할 것이 있을 때는 그것이 얼마나 움직였는지까지.

import { Statistic } from 'neba';

<Statistic label="월 반복 매출" value={48210} prefix="$" previousValue={42800} />;

Card가 그러하듯 배치 하나가 얹힌 Box입니다. 각 자리가 합성 서브컴포넌트가 아니라 prop인 이유는 Card가 대는 이유와 같습니다 — 순서는 변하지 않고, 쓰는 쪽이 정하고 싶은 것은 각 자리에 무엇이 들어가느냐입니다.

차이 표시는 색칠한 span이 아니라 Chip입니다. 이것이 옆의 나머지와 어울려 보이는 이유 전부입니다 — 라이브러리의 다른 곳이 쓰는 것과 같은 토큰이, 컨트롤 사다리에서 같은 한 칸 아래에, 같은 아크릴을 두르고 있습니다.

Props

Prop	타입	기본값	설명
label	ReactNode	—	숫자의 이름. Card가 title이라 부르는 자리지만, 여기 있는 것은 *값*의 이름이고 그것은 라이브러리가 이미 label이라 쓰고 있는 것입니다
value *	number | string	—	수치. 숫자는 형식이 적용되고, 문자열은 그대로 찍힙니다 — 숫자가 아닌 값("3h 42m", "A+")을 위해서
format	Intl.NumberFormatOptions	—	숫자를 어떻게 쓸지. 진행 표시기가 받는 것과 같은 prop이고, 없으면 읽는 사람의 로케일대로 자릿수만 끊습니다
prefix	ReactNode	—	수치 앞 — 통화 기호
unit	ReactNode	—	수치 뒤 — %, MB, 명. prefix와 따로인 이유는 둘이 조판상 다른 것이기 때문입니다: 통화 기호는 숫자 앞에 서고 단위는 뒤에 섭니다
icon	ReactNode	—	라벨 앞의 글리프
previousValue	number	—	비교 대상이 되는 수치 — 지난달 값, 목표치. 이 값을 주는 것이 차이 표시를 켜는 스위치입니다
delta	'percent' | 'absolute' | 'both' | 'none'	'percent'	차이를 어떻게 쓸지. 기본이 백분율인 이유는 보고서가 대개 "몇 개 늘었나"가 아니라 "얼마나 움직였나"를 묻기 때문입니다. previousValue가 0이면 나눌 것이 없으므로 차이 자체로 내려앉습니다
betterWhen	'up' | 'down'	'up'	어느 쪽이 좋은 방향인지, 그래서 차이를 어느 색으로 칠할지. 매출은 up, 이탈률·오류율·페이지 용량은 down. 장식이 아닙니다 — 이탈률이 올랐는데 초록이면 보고서가 뜻과 반대로 말하고, 하필 훑어보는 독자에게 그렇게 말합니다
caption	ReactNode	—	수치 아래 한 줄 — "지난달 대비"
align공통	'start' | 'center' | 'end'	'start'	카드 안에서 블록이 앉는 자리. 한 줄로 늘어놓는 타일이면 center
variant공통	'solid' | 'outline' | 'text'	'outline'	표면의 무게. Box의 것 그대로 — Statistic은 배치가 얹힌 Box입니다
size공통	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'	수치의 타입 스케일과 시트의 여백·모서리
color공통	'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info'	'primary'	의미론적 색 역할. 임의 색상값은 받지 않습니다
density공통	'default' | 'compact'	'default'	여백만 바꿉니다. 높이와 글자 크기는 그대로
elevation공통	0 | 1 | 2 | 3	0	그림자 깊이. 0은 그림자 없음
children	ReactNode	—	caption 아래 무엇이든 — 스파크라인, 목표 대비 ProgressLinear

<div>의 네이티브 속성과 Box의 모든 prop이 그대로 전달됩니다.

예시

비교

차이 표시를 믿을 수 있게 만드는 것은 betterWhen입니다. 아래 두 카드는 둘 다 올랐지만, 좋은 소식은 하나뿐이고 어느 쪽인지는 색이 말해 주어야 합니다. delta는 변화를 비율로 쓸지, 차이 그 자체로 쓸지, 둘 다 쓸지를 정합니다.

import { Grid, GridContainer, Statistic } from 'neba';

/**
 * `betterWhen` is the whole reason the delta can be trusted. Both cards below
 * went *up*; only one of them is good news, and the colour has to say which.
 */
export default function StatisticComparison() {
  return (
    <GridContainer spacing={3} padded={false}>
      <Grid span={{ xs: 12, sm: 6 }}>
        <Statistic
          label="Signups"
          value={3120}
          previousValue={2740}
          caption="betterWhen up (the default)"
          className="h-full"
        />
      </Grid>
      <Grid span={{ xs: 12, sm: 6 }}>
        <Statistic
          label="p95 latency"
          value={412}
          unit="ms"
          previousValue={366}
          betterWhen="down"
          caption="betterWhen down"
          className="h-full"
        />
      </Grid>

      <Grid span={{ xs: 12, sm: 6 }}>
        <Statistic
          label="Open incidents"
          value={7}
          previousValue={12}
          betterWhen="down"
          delta="absolute"
          caption='delta="absolute"'
          className="h-full"
        />
      </Grid>
      <Grid span={{ xs: 12, sm: 6 }}>
        <Statistic
          label="Seats used"
          value={188}
          previousValue={160}
          delta="both"
          caption='delta="both"'
          className="h-full"
        />
      </Grid>
    </GridContainer>
  );
}

수치와 차이 표시는 색만이 아니라 모양도 함께 지고 있습니다 — 올라가는 화살표, 내려가는 화살표, 움직이지 않은 수치를 위한 짧은 선. "내려갔다"를 빨강으로만 말하는 보고서는 빨강과 초록을 구분하지 못하는 독자에게는 아무것도 말하지 않습니다.

구성

라벨 앞의 아이콘, 수치 뒤의 단위, 그 아래에 무엇이든 — 목표 대비 ProgressLinear나 스파크라인. align="center"는 한 줄로 늘어놓았을 때 하나의 띠로 읽혀야 하는 타일들을 위한 것입니다.

import { Grid, GridContainer, Icon, ProgressLinear, Statistic } from 'neba';

function UsersIcon() {
  return (
    <svg viewBox="0 0 16 16" fill="none">
      <circle cx="6" cy="5.5" r="2.5" stroke="currentColor" strokeWidth="1.5" />
      <path
        d="M1.75 13c0-2.3 1.9-3.75 4.25-3.75S10.25 10.7 10.25 13"
        stroke="currentColor"
        strokeWidth="1.5"
        strokeLinecap="round"
      />
      <path
        d="M11 4.5a2 2 0 0 1 0 4M12 9.75c1.4.45 2.25 1.6 2.25 3.25"
        stroke="currentColor"
        strokeWidth="1.5"
        strokeLinecap="round"
      />
    </svg>
  );
}

/**
 * The slots, and what a Statistic looks like when it is asked to carry more than
 * a number: an icon on the label, a unit on the figure, and something of your
 * own underneath.
 */
export default function StatisticAnatomy() {
  return (
    <GridContainer spacing={3} padded={false}>
      <Grid span={{ xs: 12, sm: 6 }}>
        <Statistic
          icon={<Icon icon={<UsersIcon />} size="sm" />}
          label="Seats"
          value={188}
          unit="/ 250"
          caption="75% of the plan"
          className="h-full"
        >
          <ProgressLinear value={75} label="Seats used" />
        </Statistic>
      </Grid>

      <Grid span={{ xs: 12, sm: 3 }}>
        <Statistic
          label="Uptime"
          value="99.98%"
          align="center"
          variant="solid"
          color="success"
          className="h-full"
        />
      </Grid>

      <Grid span={{ xs: 12, sm: 3 }}>
        <Statistic
          label="Median build"
          value="3m 12s"
          align="center"
          variant="text"
          size="sm"
          className="h-full"
        />
      </Grid>
    </GridContainer>
  );
}

형식

format은 Intl.NumberFormat에 그대로 넘어가며, 진행 표시기가 받는 것과 같은 prop입니다. 없으면 읽는 사람의 로케일대로 자릿수만 끊고 나머지는 그대로 둡니다. 문자열 value는 준 그대로 찍히는데, 애초에 숫자가 아닌 수치들을 위해서입니다.

<Statistic label="매출" value={48210} format={{ style: 'currency', currency: 'KRW' }} />
<Statistic label="전환율" value={0.0423} format={{ style: 'percent', maximumFractionDigits: 1 }} />
<Statistic label="빌드 중앙값" value="3m 12s" />

prefix와 unit이 방향을 가진 하나의 장식이 아니라 두 개의 자리인 이유는 둘이 조판상 다른 것이고 늘 달랐기 때문입니다 — 통화 기호는 숫자 앞에 서고 단위는 뒤에 섭니다. 둘 다 있는 어느 로케일에서든 그렇습니다.

나눌 것이 없을 때

previousValue가 0일 때의 백분율은 큰 수가 아니라 정의되지 않은 수입니다. 그래서 비율은 버리고 차이 그 자체를 대신 씁니다. 지난달이 첫 달이었다는 이유로 +∞%를 보고하는 것은, 대시보드가 딱 한 번 하고 나면 아무도 다시 믿지 않게 되는 종류의 일입니다.

Ant Design에서 옮겨올 때

Ant	Neba
title	label — 값의 이름이고, 그것이 라이브러리가 이미 label이라 부르는 것입니다
value	같습니다
precision={2}	format={{ minimumFractionDigits: 2, maximumFractionDigits: 2 }}
prefix / suffix	prefix / unit
valueStyle	없습니다. color, size, variant가 축입니다
<Statistic.Countdown />	없습니다. 형식을 맞춘 문자열을 value로 넘기고 직접 흘려보내세요
—	previousValue, delta, betterWhen — Ant이 쓰는 쪽에 맡겨 두는 비교