TimelineChart

일을 시간 축 위에 그립니다. 한 행이 하나를 나타내고, 그 위의 막대 하나가 하나의 기간입니다. 무엇이 어느 갈래에서 얼마나 오래 일어나는지를 보여 주는 Gantt 차트입니다.

import { TimelineChart } from 'neba';

<TimelineChart
  label="워크스트림별 릴리스 계획"
  series={[
    {
      name: 'Design',
      data: [{ start: new Date('2026-02-03'), end: new Date('2026-03-03'), label: 'Wireframes' }]
    }
  ]}
/>;

Timeline과 다른 컴포넌트입니다. 그쪽은 축 없이 단계를 늘어놓는 목록으로 사건의 순서를 보여 주고, 이쪽은 달력 위에 기간을 그려 각각이 얼마나 걸렸는지를 보여 줍니다.

데이터 형식

행 하나가 series이고 그 안의 datum 하나가 span입니다. 다만 span은 NebaChartPoint가 아닙니다. 축 위에 자리가 하나가 아니라 둘이므로 자기 타입을 따로 가집니다.

{ start: new Date('2026-03-02'), end: new Date('2026-03-16'), label: 'Wireframes' }

start와 end는 Date 또는 밀리초 숫자입니다. 앞뒤가 바뀌어 적힌 span도 제대로 그립니다.

한 행의 span들은 그 행을 함께 씁니다. 겹치는 것들은 서로 위에 그려지는 대신 각자 lane을 하나씩 받으므로, 두 가지를 동시에 하는 행은 둘 다 보입니다. 겹치지 않는 행은 원래 두께를 그대로 유지합니다.

Prop	타입	기본값	설명
start *	Date | number	—	이 span이 시작하는 시각
end *	Date | number	—	끝나는 시각. 앞뒤가 바뀌어 있어도 제대로 그립니다
label	ReactNode	—	tooltip과 표에서 이 span을 부르는 이름
color	NebaColor | string	—	이 span 하나만 행의 색 대신 이 색으로

Props

Prop	타입	기본값	설명
series *	NebaTimelineSeries[]	—	series 하나가 행 하나이고, 그 안의 datum이 span입니다. 행 이름이 왼쪽 축에 쓰입니다
min	Date | number	—	시간 축이 시작하는 지점. 생략하면 span에서 오고, 달력이 이름을 가진 날짜로 바깥쪽으로 반올림됩니다
max	Date | number	—	시간 축이 끝나는 지점
xAxis	NebaChartAxis	—	행 축. 방향과 무관하게 xAxis가 category 축입니다
yAxis	NebaChartAxis	—	시간 축. 여기서는 아래쪽에 그려지지만 여전히 값 축이므로 yAxis입니다
barSize	number	size	막대가 두꺼워질 수 있는 최대 두께(px). 그 아래에서는 행의 몫을 채우고, 넘는 만큼은 여백으로 남습니다
rounded	boolean	true	span의 양쪽 끝을 둥글게. BarChart와 달리 양쪽 다입니다. span은 0에서 자라지 않으므로 기준이 되는 끝이 없습니다
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는 없습니다. Gantt의 행은 그 자체가 축이고 이미 왼쪽에 이름이 쓰여 있습니다. 공용 축은 prop 규약을 참고하세요.

예시

min · max

그냥 두면 축은 span들에서 정해지고, 달력이 이름을 가진 날짜로 바깥쪽으로 반올림됩니다. min·max로 분기·스프린트·근무 시간에 고정할 수 있고, 축 밖으로 나가는 span은 축을 늘리는 대신 가장자리에서 잘립니다.

눈금 단위는 범위에 따라 초, 분, 시, 일, 주, 월, 분기, 연으로 바뀝니다. 하루짜리 차트는 정시마다 눈금을 찍습니다.

import { Card, TimelineChart } from 'neba';

const at = (iso: string) => new Date(iso);

/**
 * A single day, so the axis steps in hours rather than in months. `min` and
 * `max` pin it to the working day; the run that started before nine is cut at
 * the edge rather than dragging the whole axis back to midnight.
 */
const SHIFTS = [
  {
    name: 'Build',
    data: [
      { start: at('2026-03-02T07:40:00'), end: at('2026-03-02T09:20:00'), label: 'Nightly' },
      { start: at('2026-03-02T11:10:00'), end: at('2026-03-02T12:05:00'), label: 'PR #4182' },
      { start: at('2026-03-02T15:30:00'), end: at('2026-03-02T16:40:00'), label: 'PR #4190' }
    ]
  },
  {
    name: 'Deploy',
    data: [
      { start: at('2026-03-02T12:20:00'), end: at('2026-03-02T12:50:00'), label: 'staging' },
      { start: at('2026-03-02T17:00:00'), end: at('2026-03-02T17:35:00'), label: 'production' }
    ]
  },
  {
    name: 'Incident',
    data: [
      {
        start: at('2026-03-02T13:05:00'),
        end: at('2026-03-02T14:10:00'),
        label: 'Elevated 5xx',
        color: 'danger'
      }
    ]
  }
];

export default function TimelineChartRange() {
  return (
    <Card title="Pipeline" subtitle="2 March, 09:00 – 18:00" className="w-full">
      <TimelineChart
        label="Pipeline activity on 2 March"
        min={at('2026-03-02T09:00:00')}
        max={at('2026-03-02T18:00:00')}
        series={SHIFTS}
      />
    </Card>
  );
}

barSize · rounded · density

barSize는 막대가 두꺼워질 수 있는 한계이고, 그 아래에서는 막대가 행의 몫을 채웁니다. density는 그 몫만 바꿉니다. rounded는 span의 모서리를 깎는데, BarChart와 달리 양쪽 끝 모두입니다. span은 0에서 자라지 않으므로 기준이 되는 끝이 없습니다.

import { Card, Grid, GridContainer, TimelineChart } from 'neba';

const on = (iso: string) => new Date(`${iso}T00:00:00`);

const TERMS = [
  {
    name: 'Alpha',
    data: [{ start: on('2026-01-05'), end: on('2026-03-30'), label: 'Alpha' }]
  },
  {
    name: 'Beta',
    data: [{ start: on('2026-03-16'), end: on('2026-06-08'), label: 'Beta' }]
  },
  {
    name: 'GA',
    data: [{ start: on('2026-05-25'), end: on('2026-08-31'), label: 'GA' }]
  }
];

export default function TimelineChartBars() {
  return (
    <GridContainer spacing={3} padded={false}>
      <Grid span={{ xs: 12, md: 6 }}>
        <Card title="barSize + rounded" size="sm" className="h-full">
          <TimelineChart label="Programme phases, thick bars" barSize={30} series={TERMS} />
        </Card>
      </Grid>
      <Grid span={{ xs: 12, md: 6 }}>
        <Card title='density="compact"' size="sm" className="h-full">
          <TimelineChart
            label="Programme phases, square ends"
            density="compact"
            rounded={false}
            series={TERMS}
          />
        </Card>
      </Grid>
    </GridContainer>
  );
}

xAxis · yAxis

xAxis가 행 축이고 yAxis가 시간 축입니다. 모든 차트가 따르는 규칙과 같습니다. 어느 방향으로 그리든 xAxis가 category 축, yAxis가 값 축입니다. 여기서 시간 축은 아래쪽에 그려지지만 여전히 yAxis입니다.

yAxis.tickFormat으로 눈금을 쓰고, yAxis.tickCount로 대략의 개수를 요청하며, xAxis.hidden으로 행 이름을 지웁니다.

<TimelineChart yAxis={{ tickCount: 4 }} xAxis={{ label: 'Workstream' }} … />

색

행의 팔레트 자리는 series 배열에서의 위치로 정해집니다. series.color는 그 자리를 색 계열이나 임의의 CSS 색으로 덮어쓰고, span 자신의 color는 그 막대 하나만 덮어씁니다. 일정이 밀린 하나가 스스로 그렇다고 말하는 방법입니다.

접근성

• 데이터는 label을 caption으로 하는 화면에 보이지 않는 표로도 렌더링됩니다. span 하나가 한 행이고, 그 행이 속한 행 이름 아래에 놓입니다.
• plot에 focus할 수 있습니다. ←·→로 데이터 순서대로 span을 옮기고, Home·End로 양 끝으로, Escape로 tooltip을 해제합니다.
• 포인터는 중심이 가장 가까운 span이 아니라 안에 들어와 있는 span을 고릅니다. 긴 막대의 hover를 옆의 짧은 막대가 가로채지 않습니다.