ScatterChart

점마다 두 개의 값을 서로에 대해 그려, 둘이 함께 움직이는지를 읽는 차트입니다. 세 번째 숫자를 든 점은 bubble로 그려지므로 산점도와 bubble 차트가 한 컴포넌트입니다.

import { ScatterChart } from 'neba';

<ScatterChart
  label="체류 시간 대비 읽은 페이지 수"
  xAxis={{ label: '체류 시간(초)' }}
  yAxis={{ label: '페이지' }}
  series={[
    {
      name: 'Organic',
      data: [
        { x: 22, y: 2 },
        { x: 41, y: 3 },
        { x: 55, y: 4 }
      ]
    }
  ]}
/>;

데이터 형식

series의 형태는 모든 차트가 공유합니다. 전체 정의는 LineChart에 있습니다. 다만 여기에는 조건이 하나 더 있습니다. 모든 점이 x를 들고 있어야 하고, 그 x는 숫자 또는 Date입니다. 여기서는 두 축이 모두 값을 재므로 숫자 하나짜리 datum은 놓일 자리가 없고, 문자열 x를 받은 점은 수직선 위에 없으므로 차트는 마크를 0에 늘어놓는 대신 빈 상태를 그립니다.

{ x: 22, y: 2 }              // dot
{ x: 22, y: 2, z: 180 }      // bubble
{ x: 22, y: null }           // 결측: 마크를 그리지 않고, 표의 칸도 비웁니다

점이 x를 직접 들고 있지 않으면 categories에서 index로 찾아 씁니다.

z는 선택이며 넓이로 읽힙니다. z가 없는 점은 pointRadius로 그려지고, 있는 점은 비율의 제곱근으로 maxRadius 아래에 맞춰집니다. 값이 네 배면 지름이 두 배인 bubble이 됩니다.

Props

Prop	타입	기본값	설명
series *	NebaChartSeries[]	—	그릴 series. 각 점은 x와 y를 모두 숫자로 들고 있어야 하고, z가 있으면 그 점은 dot이 아니라 bubble이 됩니다
categories	(number | Date)[]	—	점이 x를 직접 들고 있지 않을 때 index로 찾아 쓰는 x 값. 문자열은 수직선 위의 자리가 아니므로 받지 않습니다
xAxis	NebaChartAxis	—	x 축. 여기서는 category 축이 아니라 두 번째 값 축이므로 눈금은 데이터가 아니라 반올림된 수에 놓이고, 격자선도 기본으로 켜집니다
yAxis	NebaChartAxis	—	값 축
shape	'auto' | 'varied' | 'circle' | 'square' | 'triangle' | 'diamond' | 'cross'	'auto'	마크의 모양. auto는 색만으로 구분되는 동안 원을, 네 번째 series부터는 series마다 다른 모양을 씁니다. varied는 항상 모양을 나눕니다. 인쇄하거나 흑백으로 읽을 차트에
pointRadius	number	size	z가 없는 마크의 반지름(px)
maxRadius	number	plot 짧은 변의 1/12 / a twelfth of the plot	가장 큰 bubble의 반지름(px). 나머지는 반지름이 아니라 넓이로 그 아래에 맞춰집니다. z를 반지름에 쓰면 두 배인 값이 네 배로 보입니다
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이 그대로 전달됩니다. xAxis·yAxis·legend·tooltip은 LineChart와 같은 형태를 받습니다. 공용 축은 prop 규약을 참고하세요.

예시

bubble

점에 z가 있으면 bubble이 됩니다. maxRadius는 가장 큰 bubble의 반지름이고 나머지는 그 아래에 맞춰집니다. 생략하면 plot 짧은 변의 1/12입니다.

크기 기준은 모든 series에 걸쳐 한 번만 정해지고 범례를 걸러도 움직이지 않습니다. 그래서 크기가 같은 두 bubble은 어디에 있든 같은 숫자를 뜻합니다.

import { Card, ScatterChart } from 'neba';

/**
 * A third number per point turns a dot into a bubble. `z` is read as an
 * **area**, so the plan with four times the revenue draws a bubble twice as
 * wide rather than four times as wide.
 */
const PLANS = [
  { x: 12, y: 4.2, z: 180, label: 'Free' },
  { x: 29, y: 6.8, z: 620, label: 'Starter' },
  { x: 48, y: 8.1, z: 1450, label: 'Team' },
  { x: 71, y: 9.4, z: 2900, label: 'Business' },
  { x: 96, y: 11.2, z: 4100, label: 'Enterprise' }
];

export default function ScatterChartBubble() {
  return (
    <Card title="Revenue by plan" subtitle="Seats against weekly sessions" className="w-full">
      <ScatterChart
        label="Revenue by plan, against seats and weekly sessions"
        xAxis={{ label: 'Seats' }}
        yAxis={{ label: 'Sessions per week' }}
        maxRadius={26}
        // Each point's `label` names its plan, so the tooltip says which bubble
        // it is rather than repeating the y already on the axis.
        series={[{ name: 'Plan', data: PLANS }]}
      />
    </Card>
  );
}

shape

산점도는 어떤 두 마크든 나란히 놓일 수 있는 형태이므로, 팔레트가 이웃한 쌍이 아니라 모든 쌍에서 구분되어야 합니다. 그렇게 검사하면 구분되는 것은 세 series까지입니다. 넷째부터는 shape="auto"가 series마다 다른 모양을 내어 줍니다. 순서는 circle, square, triangle, diamond, cross입니다. 범례에도 같은 모양이 나옵니다.

shape="varied"는 첫 series부터 모양을 나눕니다. 인쇄하거나 흑백으로 읽을 차트에 필요한 값입니다. 다섯 모양 중 하나를 직접 지정하면 모든 마크가 그 모양이 되는데, series가 넷 이상일 때 이것은 두 번째 채널을 포기하는 선택이므로 각 series가 자기 color를 들고 있을 때만 쓰세요.

import { Card, ScatterChart } from 'neba';

const cloud = (offsetX: number, offsetY: number) =>
  Array.from({ length: 8 }, (_, index) => ({
    x: offsetX + index * 9 + ((index * 37) % 11),
    y: offsetY + ((index * 53) % 17) + index * 2
  }));

/**
 * Four series is one past what the palette separates on a plot where any two
 * marks can end up side by side, so `shape="auto"` gives each series a shape of
 * its own from the fourth on. The legend shows the same shapes.
 */
export default function ScatterChartShape() {
  return (
    <Card title="Latency by region" subtitle="Four regions, four shapes" className="w-full">
      <ScatterChart
        label="Latency against request rate, by region"
        xAxis={{ label: 'Requests per second' }}
        yAxis={{ label: 'p95 latency (ms)' }}
        series={[
          { name: 'us-east', data: cloud(10, 40) },
          { name: 'eu-west', data: cloud(16, 60) },
          { name: 'ap-south', data: cloud(22, 30) },
          { name: 'sa-east', data: cloud(28, 75) }
        ]}
      />
    </Card>
  );
}

xAxis · yAxis

여기서 x 축은 category 축이 아니라 값 축입니다. 눈금이 데이터가 아니라 반올림된 수에 놓이고, 격자선도 긋습니다. 마크의 x를 그림에서 읽어 내는 것이 이 차트를 보는 이유의 절반이기 때문입니다. xAxis의 grid를 false로 두면 끌 수 있습니다.

두 축 모두 0을 지나도록 강제하지 않습니다. 위치가 나타내는 것은 자리이므로 축을 잘라도 모든 마크가 같은 만큼 움직여 구름의 모양은 그대로 남습니다. 비교에 고정된 틀이 필요하면 min·max로 축을 고정하세요.

format은 값 축의 것이므로, x 눈금의 표기는 xAxis.tickFormat으로 정합니다.

import { Card, ScatterChart } from 'neba';

const READINGS = [
  { x: -8, y: 412 },
  { x: -3, y: 388 },
  { x: 2, y: 341 },
  { x: 6, y: 310 },
  { x: 11, y: 264 },
  { x: 15, y: 238 },
  { x: 19, y: 201 },
  { x: 24, y: 176 },
  { x: 28, y: 168 },
  { x: 31, y: 155 }
];

/**
 * Neither axis is dragged down to zero — a scatter is about where the cloud
 * sits, and a scale that starts at zero on both axes would push all of it into
 * one corner. `min` and `max` pin an axis when a comparison needs a fixed frame.
 */
export default function ScatterChartAxes() {
  return (
    <Card title="Heating load" subtitle="Against outdoor temperature" className="w-full">
      <ScatterChart
        label="Heating load against outdoor temperature"
        xAxis={{ label: 'Outdoor °C', min: -10, max: 35, tickFormat: (value) => `${value}°` }}
        yAxis={{ label: 'kWh per day', grid: false }}
        pointRadius={5}
        series={[{ name: 'Readings', data: READINGS, color: 'warning' }]}
      />
    </Card>
  );
}

tooltip

모아 보여 줄 공통 category가 없으므로 tooltip은 언제나 마크 하나에 대한 것입니다. 포인터는 자기 반지름에 24px을 더한 범위 안에서 가장 가까운 마크를 고르고, crosshair는 그리지 않습니다. 패널의 제목은 그 마크의 x이고 한 줄에 series와 y가 들어갑니다. 점이 label을 들고 있으면 값 대신 그것이 쓰이고, tooltip.render로 패널 전체를 대신 그릴 수 있습니다.

<ScatterChart tooltip={{ render: ({ category, items }) => … }} … />

색

series의 팔레트 자리는 series 배열에서의 위치로 정해지므로, 범례를 걸러도 남은 series의 색은 그대로입니다. series.color는 그 자리를 색 계열이나 임의의 CSS 색으로 덮어쓰고, 점 자신의 color는 그 마크 하나만 덮어씁니다.

접근성

• 데이터는 label을 caption으로 하는 화면에 보이지 않는 표로도 렌더링됩니다. 점 하나가 한 행이고, 열 이름은 축 라벨에서 옵니다.
• plot에 focus할 수 있습니다. ←·→로 데이터 순서대로 마크를 옮기고, Home·End로 양 끝으로, Escape로 tooltip을 해제합니다.
• series가 셋을 넘으면 색뿐 아니라 모양도 series를 구분합니다. 색각 이상이 있는 독자에게도, 흑백에서도, 인쇄물에서도 차트가 읽히는 것은 이 때문입니다.