PieChart

전체에 대한 부분을 원의 조각으로 보여 줍니다. "이 중 하나가 대부분인가?"라는 질문 하나에는 잘 답하고, 그보다 세밀한 것은 막대 차트의 몫입니다.

import { PieChart } from 'neba';

<PieChart
  label="유입 경로별 세션"
  shape="donut"
  categories={['Organic', 'Direct', 'Paid']}
  data={[18420, 9260, 6140]}
/>;

데이터 형식

pie는 series가 하나이므로 series 배열이 아니라 data를 직접 받습니다. 여기서 정체성을 갖는 것은 조각이며, 조각 하나하나가 팔레트 slot을 가져가고 범례도 조각을 나열합니다.

data는 NebaChartDatum의 배열입니다. 숫자이거나 null이거나, 이름과 색을 직접 들고 있는 점입니다. categories가 조각의 이름을 정하고, 대신 각 점이 x를 들고 있어도 됩니다.

<PieChart categories={['Free', 'Pro', 'Team']} data={[4820, 2140, 890]} />

<PieChart
  data={[
    { x: 'Passed', y: 1284, color: 'success' },
    { x: 'Failed', y: 96, color: 'danger' }
  ]}
/>

조각은 넘긴 순서대로 그려지고 다시 정렬되지 않습니다. 필터를 바꿔도 각 category는 원래의 색과 자리를 유지합니다.

Props

Prop	타입	기본값	설명
data *	NebaChartDatum[]	—	조각들. pie는 series가 하나이므로 series 배열이 아니라 값의 배열을 받습니다. 여기서 정체성을 갖는 것은 조각입니다
categories	(string | number | Date)[]	—	조각의 이름. 대신 각 점이 x를 직접 들고 있어도 됩니다
shape	'pie' | 'donut' | 'semi'	'pie'	pie는 꽉 찬 원, donut은 가운데를 비운 고리, semi는 상자 아래쪽에서 그리는 반원입니다
startAngle	number	0	첫 조각이 시작하는 각도, 12시 방향에서 시계 방향으로. semi는 무시합니다
center	ReactNode	—	고리 가운데에 들어가는 것. 가운데가 빈 donut은 한 입 베어 문 pie일 뿐입니다
valueLabels	'none' | 'all'	'none'	각 조각에 그 비중을 씁니다. 글자가 양옆 여유까지 들어갈 만큼 넓은 조각에만 그려지고, 들어가지 않으면 잘리는 대신 그려지지 않습니다
variant공통	'solid' | 'outline' | 'text'	'text'	표면의 무게. 차트는 시트가 아니라 그림이므로 기본값이 text입니다. Card 안에 넣으면 가장자리가 겹치지 않습니다. 혼자 서는 차트에는 outline을 주세요
size공통	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'	축 글자·선 두께·마커 크기, 그리고 height를 주지 않았을 때의 높이
color공통	'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info'	'primary'	시트의 색 계열. series의 색은 여기서 오지 않습니다. 팔레트나 series.color가 정합니다
density공통	'default' | 'compact'	'default'	여백만 바꿉니다. 높이와 글자 크기는 그대로
elevation공통	0 | 1 | 2 | 3	0	그림자 깊이. 0은 그림자 없음
height	number | string	size	그림의 높이. 축 라벨도 이 높이 안에 그려집니다
label	string	locale's word	차트의 접근 가능한 이름. 그림 대신 읽히고, 아래에 숨겨진 데이터 표의 caption이 됩니다. 없으면 locale의 일반 명사가 쓰이지만, 무엇에 대한 차트인지는 여기서만 말할 수 있습니다
format	Intl.NumberFormatOptions	—	숫자가 나타나는 모든 곳의 표기, 축·tooltip·값 라벨·표. 없으면 만 이상은 축약됩니다(12.4K)
locale	string	—	차트가 스스로 쓰는 말과 날짜의 언어
legend	boolean | NebaChartLegend	series ≥ 2	series가 둘 이상이면 자동으로 나오고 하나면 나오지 않습니다. 색 하나짜리 범례는 제목을 반복할 뿐입니다
tooltip	boolean | NebaChartTooltip	true	포인터가 무엇을 드러낼지. tooltip에만 있는 값은 없습니다. 모든 값이 숨겨진 표에도 있습니다
empty	ReactNode	—	그릴 것이 없을 때 대신 그릴 내용

<div>의 native 속성과 Box의 모든 prop이 그대로 전달됩니다. legend와 tooltip은 LineChart와 같은 형태를 받습니다. 공용 축은 prop 규약을 참고하세요.

예시

shape

pie는 꽉 찬 원, donut은 가운데를 비운 고리입니다. semi는 상자 아래쪽에서 반원을 그리므로, 세로보다 가로가 긴 대시보드 타일에 맞습니다.

import { Card, Grid, GridContainer, PieChart, Typography } from 'neba';

const CATEGORIES = ['Free', 'Pro', 'Team', 'Enterprise'];
const DATA = [4820, 2140, 890, 210];

export default function PieChartShapes() {
  return (
    <GridContainer spacing={3} padded={false}>
      <Grid span={{ xs: 12, md: 4 }}>
        <Card title='shape="pie"' size="sm" className="h-full">
          <PieChart
            label="Accounts by plan, pie"
            size="sm"
            height={160}
            categories={CATEGORIES}
            data={DATA}
            valueLabels="all"
          />
        </Card>
      </Grid>
      <Grid span={{ xs: 12, md: 4 }}>
        <Card title='shape="donut"' size="sm" className="h-full">
          <PieChart
            label="Accounts by plan, donut"
            size="sm"
            height={160}
            shape="donut"
            categories={CATEGORIES}
            data={DATA}
            center={<Typography level="h5">8,060</Typography>}
          />
        </Card>
      </Grid>
      <Grid span={{ xs: 12, md: 4 }}>
        <Card title='shape="semi"' size="sm" className="h-full">
          <PieChart
            label="Accounts by plan, semicircle"
            size="sm"
            height={160}
            shape="semi"
            categories={CATEGORIES}
            data={DATA}
          />
        </Card>
      </Grid>
    </GridContainer>
  );
}

center

donut이나 semi의 빈 가운데에 들어가는 것입니다. 가운데가 빈 고리는 한 입 베어 문 pie일 뿐이고, 합계나 이 차트가 말하려는 수치 하나가 그 고리를 그린 이유입니다.

<PieChart shape="donut" center={<Typography level="h4">38.6K</Typography>} … />

valueLabels

all은 각 조각에 그 비중을 씁니다. pie가 그리는 것이 비중이고, 값은 hover 한 번 거리에 있습니다. 라벨은 양옆에 여유를 두고 들어갈 만큼 조각이 넓을 때만 그려집니다. 들어가지 않는 라벨은 잘리는 대신 그려지지 않으며, tooltip과 표에는 그대로 남아 있습니다.

색

조각은 넘긴 순서대로 팔레트 slot을 가져갑니다. 점의 color가 그것을 덮어쓰는데, 조각 자체에 의미가 있을 때 그렇게 해야 합니다. 성공과 실패는 "series 1"과 "series 2"가 아닙니다.

import { Card, PieChart } from 'neba';

/**
 * A slice takes the palette slot its position gives it, and a point's own
 * `color` overrides that. Here the four states mean something — a colour that
 * says "failed" is doing a different job from one that says "series four" — so
 * every slice names its own.
 */
export default function PieChartColors() {
  return (
    <Card title="Pipeline runs" subtitle="Last 24 hours" className="w-full">
      <PieChart
        label="Pipeline runs by outcome"
        shape="donut"
        legend={{ side: 'right', align: 'center' }}
        data={[
          { x: 'Passed', y: 1284, color: 'success' },
          { x: 'Failed', y: 96, color: 'danger' },
          { x: 'Cancelled', y: 41, color: 'secondary' },
          { x: 'Flaky', y: 28, color: 'warning' }
        ]}
      />
    </Card>
  );
}

legend · startAngle

범례는 조각이 둘 이상이면 나타나고 기본적으로 클릭할 수 있습니다. 조각의 항목을 클릭하면 그 조각이 빠지고 나머지가 원을 다시 채웁니다. startAngle은 12시 방향에서 시계 방향으로 몇 도에서 시작할지를 정합니다.

<PieChart legend={{ side: 'right', align: 'center' }} startAngle={-30} … />

접근성

• 데이터는 label을 caption으로 하는 화면에 보이지 않는 표로도 렌더링됩니다.
• plot에 focus할 수 있습니다. ←·→로 조각을 옮기고 Escape로 해제하므로, 포인터 없이도 tooltip에 닿을 수 있습니다.
• 조각은 각각의 테두리가 아니라 표면 색의 간격으로 분리되며, 그 간격은 반지름과 무관하게 화면에서 2px로 유지됩니다.

쓰지 말아야 할 때

각도는 비교하기 나쁜 양입니다. 몇 퍼센트 차이의 두 조각은 구분되지 않고, 여섯 조각의 순위를 매길 수 있는 사람은 없습니다. 조각이 여섯을 넘거나 질문이 "이것들의 순위는?"이라면 BarChart를 쓰세요. 조각이 둘인 pie는 Statistic입니다.