@ffolio/ib-chart-kit

대시보드용 재사용 가능한 차트 렌더링 킷

설치

npm install @ffolio/ib-chart-kit

Peer Dependencies

npm install react react-dom recharts zod

| 패키지 | 버전 | |--------|------| | react | ^18 || ^19 | | react-dom | ^18 || ^19 | | recharts | ^3 | | zod | ^4 |

빠른 시작

import { ChartCard, IndicatorCard } from "@ffolio/ib-chart-kit";
import "@ffolio/ib-chart-kit/styles.css"; // CSS 필수 - 아래 스타일 섹션 참고

function Dashboard() {
  return (
    <>
      <ChartCard card={chartCardData} height={360} withShell />
      <IndicatorCard card={indicatorCardData} withShell />
    </>
  );
}

스타일 (CSS)

이 라이브러리는 내부적으로 Tailwind CSS 클래스를 사용하지만, 소비자 프로젝트에 Tailwind 설치는 불필요합니다.

방법 1: 빌드된 CSS import (권장)

import "@ffolio/ib-chart-kit/styles.css";

미리 컴파일된 CSS 파일로, Tailwind 없이도 모든 스타일이 적용됩니다.

방법 2: Tailwind content 설정 (Tailwind 사용 프로젝트)

소비자 프로젝트에서 이미 Tailwind를 사용 중이고, CSS import 없이 쓰고 싶다면:

// tailwind.config.js
module.exports = {
  content: [
    "./src/**/*.{js,ts,jsx,tsx}",
    "./node_modules/@ffolio/ib-chart-kit/dist/**/*.js", // 추가
  ],
};

⚠️ Tailwind 버전 불일치(v3 vs v4) 시 스타일 깨질 수 있음. 방법 1 권장.

서브패키지 import (트리쉐이킹)

번들 크기 최적화가 필요하면 서브패키지에서 직접 import:

// 전체 import (기존 방식)
import { ChartCard, parseCardContainer } from "@ffolio/ib-chart-kit";

// 서브패키지 import (트리쉐이킹 최적화)
import { ChartCard } from "@ffolio/ib-chart-kit/cards";
import { ComposedChartRenderer } from "@ffolio/ib-chart-kit/charts";
import { parseCardContainer } from "@ffolio/ib-chart-kit/core";
import { resolveSeriesColor } from "@ffolio/ib-chart-kit/utils";

| 서브패키지 | 설명 | |-----------|------| | @ffolio/ib-chart-kit/cards | ChartCard, IndicatorCard, UnifiedCard | | @ffolio/ib-chart-kit/charts | 차트 렌더러 (Composed, Pie, Radar 등) | | @ffolio/ib-chart-kit/core | 스키마, 파서, 포맷터, 타입 | | @ffolio/ib-chart-kit/shell | ChartCardShell | | @ffolio/ib-chart-kit/utils | 유틸리티 함수 |

컴포넌트

ChartCard

차트 타입 카드를 렌더링합니다.

<ChartCard
  card={cardData}      // CardContainer 데이터 (필수)
  height={360}         // 차트 높이 (기본값: 320)
  withShell            // 카드 쉘 적용 여부
/>

IndicatorCard

KPI/지표 카드를 렌더링합니다.

<IndicatorCard
  card={cardData}      // CardContainer 데이터 (필수)
  withShell            // 카드 쉘 적용 여부 (기본값: true)
/>

UnifiedCard

차트/지표 타입을 view.encodings에서 자동 파생해 적절한 카드를 렌더링합니다.

import { UnifiedCard } from "@ffolio/ib-chart-kit";

<UnifiedCard
  card={cardDataOrJsonString} // AnyCardContainer 또는 JSON 문자열
  withShell                  // 카드 쉘 적용 여부 (기본값: true)
  height={360}               // 차트 높이 (indicator에는 무시)
/>;

ChartCardShell

카드 래퍼 컴포넌트입니다. 직접 사용할 수도 있습니다.

<ChartCardShell title="차트 제목">
  {children}
</ChartCardShell>

데이터 구조

CardContainer
├── id, title, type ("chart" | "indicator")
└── report_wits: ReportWit[]
    ├── records: T[]           // 데이터
    ├── measures: Record<...>  // 필드 메타데이터
    ├── view: { encodings, render_config }
    └── comparison?: { prev_week, prev_month, ... }

예시

const cardData = {
  id: "chart-1",
  title: "연령별 인원 현황",
  report_wits: [{
    id: "wit-1",
    label: "전체",
    records: [
      { date: "2025-01", age_group: "20대", headcount: 80 },
      { date: "2025-01", age_group: "30대", headcount: 120 },
    ],
    measures: {
      headcount: {
        display_name: "인원 수",
        unit: "명",
        calc_type: "SUM",
      },
    },
    view: {
      encodings: {
        composed: { x: "age_group", y: ["headcount"] },
      },
      render_config: {
        series: {
          headcount: { type: "bar" },
        },
      },
    },
  }],
};

지원 차트 타입

| 타입 | 설명 | |------|------| | composed | Line/Bar/Area 조합 | | pie | 파이 차트 | | radar | 레이더 차트 | | scatter | 산점도 | | table | 테이블 | | heatmap | 히트맵 | | indicator | KPI 지표 | | card_matrix | 카드 그리드 |

포맷터

render_config.interactions.tooltip.valueFormatter 등에서 사용:

| FormatterId | 설명 | |-------------|------| | "number" | 숫자 (1,234) | | "currency" | 통화 (₩1,234) | | "percent" | 백분율 (12.3%) | | "date" | 날짜 | | "datetime" | 날짜시간 | | "time" | 시간 |

링크

• Storybook 데모
• npm 패키지