GaugeChart

미리 정해진 범위 위의 값 하나를 계기판으로 그립니다. 같은 값을 그린 막대보다 멀리서도 읽히므로 대시보드 타일에 적합합니다.

import { GaugeChart } from 'neba';

<GaugeChart label="Memory" caption="Memory" value={82} />;

Props

Prop	타입	기본값	설명
value *	number | null	—	읽은 값. null이면 아무것도 얹히지 않은 계기판을 그립니다
min	number	0	범위의 시작
max	number	100	범위의 끝
sweep	number	180	계기판이 도는 각도. 12시를 중심으로 대칭으로 열립니다. 180은 반원, 270은 계기, 360은 고리입니다
thickness	number	0.22	반지름에 대한 호의 두께 비율
thresholds	readonly NebaThreshold[]	—	호의 색이 바뀌는 지점들. Meter와 같은 { from, color } 항목이고 규칙도 같습니다
ticks	number | false	false	양 끝을 포함해 그려지는 눈금의 수. 대시보드의 계기판은 비율로 읽히므로 기본은 꺼짐입니다
showRange	boolean	true	호의 양 끝에 min과 max를 씁니다
center	ReactNode	—	가운데에 들어갈 것. 기본은 format을 거친 값입니다
caption	ReactNode	—	값 아래 한 줄, 단위, 또는 무엇을 재고 있는지
color공통	'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info'	'primary'	threshold에 도달하기 전 호가 띠는 색 역할
height	number | string	—	그림의 높이. 지정하지 않으면 size 사다리를 따릅니다
format	Intl.NumberFormatOptions	—	숫자를 쓰는 방식
label	string	—	접근성 이름. 있으면 계기판 전체가 하나의 role="img"가 됩니다
empty	ReactNode	—	그릴 것이 없을 때 그리는 것

Box의 모든 prop이 전달되므로 계기판 자체가 카드가 될 수 있습니다. legend도 tooltip도 없습니다. 값이 하나이면 구분할 것도, 드러낼 것도 없습니다. 숫자는 가운데에 쓰여 있습니다.

Meter를 호로 구부린 것이며, 의도적으로 같은 컴포넌트의 두 가지 모양입니다. value, min, max, thresholds는 그쪽에서와 같은 뜻이므로, 하나의 값을 막대에서 계기판으로 옮겨도 말하는 바가 달라지지 않습니다.

shape="semi"인 PieChart가 아닙니다. 파이는 전체의 부분들이고 모든 조각이 범주입니다. 이쪽은 범위에 대한 값 하나이며, 채워지지 않은 호는 두 번째 범주가 아니라 계기판의 나머지입니다.

예시

value · min · max

value가 null이면 아무것도 얹히지 않은 계기판과 가운데의 대시를 그립니다.

thresholds

호의 색이 바뀌는 지점입니다. 값이 도달한 마지막 항목이 이기고, 아무 것에도 도달하지 못했다면 color가 그대로 쓰입니다.

import { useState } from 'react';
import { GaugeChart, Slider } from 'neba';

const thresholds = [
  { from: 70, color: 'warning' },
  { from: 90, color: 'danger' }
] as const;

export default function GaugeChartThresholds() {
  const [used, setUsed] = useState(45);

  return (
    <div className="flex w-full max-w-sm flex-col gap-4">
      <GaugeChart
        variant="outline"
        label="Disk used"
        caption="Disk used"
        value={used}
        thresholds={thresholds}
      />
      <Slider
        aria-label="Disk used"
        value={used}
        onValueChange={(value) => setUsed(value as number)}
      />
    </div>
  );
}

sweep

계기판이 도는 각도이며 12시를 중심으로 좌우 대칭으로 열립니다. 180은 타일이 원하는 반원, 270은 계기의 모양, 360은 고리입니다. 주어진 sweep에 맞춰 상자에 대해 크기가 잡히므로 반원이 위쪽 절반을 비워두는 일이 없습니다.

import { GaugeChart } from 'neba';

const sweeps = [180, 240, 300, 360] as const;

export default function GaugeChartSweep() {
  return (
    <div className="grid w-full max-w-3xl grid-cols-2 gap-4 sm:grid-cols-4">
      {sweeps.map((sweep) => (
        <GaugeChart
          key={sweep}
          variant="outline"
          size="sm"
          label={`${sweep} degrees`}
          caption={`${sweep}°`}
          value={64}
          sweep={sweep}
        />
      ))}
    </div>
  );
}

ticks · thickness · showRange

ticks는 양 끝을 포함해 계기판 둘레에 눈금을 그립니다. 기본은 꺼짐입니다. 대시보드 위의 계기판은 비율로 읽히고, 눈금은 거기서 숫자를 읽어내는 계기의 것이기 때문입니다. thickness는 반지름에 대한 호의 두께이고, showRange는 양 끝에 min과 max를 씁니다.

import { GaugeChart } from 'neba';

export default function GaugeChartTicks() {
  return (
    <div className="grid w-full max-w-lg grid-cols-1 gap-4 sm:grid-cols-2">
      <GaugeChart
        variant="outline"
        label="Without marks"
        caption="no ticks"
        value={7.4}
        min={0}
        max={12}
        sweep={270}
        format={{ maximumFractionDigits: 1 }}
      />
      <GaugeChart
        variant="outline"
        label="With marks"
        caption="ticks = 7"
        value={7.4}
        min={0}
        max={12}
        sweep={270}
        ticks={7}
        thickness={0.14}
        format={{ maximumFractionDigits: 1 }}
      />
    </div>
  );
}

center · caption

가운데의 값은 진짜 텍스트입니다. 선택되고, 찾아지고, 접근성 트리에 들어갑니다. center는 그것을 대체하며 읽는 값이 단어인 계기판을 위한 것이고, caption은 그 아래 단위를 적는 한 줄입니다.

접근성

• label이 있으면 계기판 전체가 하나의 role="img"가 되고, 읽은 값과 범위의 위쪽 끝으로 이름이 붙습니다. 없으면 평범한 상자로 남고, 가운데의 숫자는 이미 그러한 텍스트로 읽힙니다.
• 색이 유일한 전달 수단이 되지 않습니다. threshold를 넘은 값은 호도 더 많이 채웠고, 숫자도 쓰여 있습니다.