React 통합

설치

npm install @taewooyo/heatmap-react

npm 패키지에는 Volcano의 Kotlin/JS 레이아웃·색상 코어가 포함됩니다. 0.3.0은 반응형 크기 조정, 데이터 갱신을 유지하는 상태, 키보드 탐색, 값 접근성 정보를 추가합니다. peer 범위는 React 18.2–18.x와 19.x(19.3 포함)를 허용하며, 저장소의 현재 개발 의존성은 React 19.2.4입니다. 소비 앱에는 Kotlin이나 Gradle이 필요하지 않습니다. 미래의 React 메이저 버전은 자동으로 호환된다고 선언하지 않으며 테스트한 뒤 peer 범위를 넓혀야 합니다. React는 SVG로 렌더링하며 Compose UI를 포함하지 않습니다. npm 패키지는 Kotlin 아티팩트와 별도 버전 계열로 관리합니다.

히트맵 렌더링

import { Heatmap, type HeatmapNode } from "@taewooyo/heatmap-react";

const market: HeatmapNode = {
  id: "market",
  label: "Market",
  value: 0,
  children: [
    { id: "A", label: "Alpha", value: 60, metric: 4.2 },
    { id: "B", label: "Beta", value: 40, metric: -2.1 },
  ],
};

export function MarketHeatmap() {
  return (
    <Heatmap
      data={market}
      width={960}
      height={480}
      ariaLabel="Market performance"
      metricFormatter={(value) => `${value > 0 ? "+" : ""}${value.toFixed(2)}%`}
      onLeafClick={(node) => console.log(node.id)}
    />
  );
}

Heatmap의 width와 height는 필수 양의 정수 SVG 크기입니다. 반응형 화면에서는 높이가 지정된 컨테이너 안에 ResponsiveHeatmap을 사용하세요. 컨테이너 크기를 관찰하고 SSR용 선택적 fallback을 지원합니다. value는 면적, 선택적인 metric은 기본 부호 색상 스케일을 제어합니다. 자식의 가중치가 양수라면 그룹의 value는 0이어도 됩니다. 노드 ID는 비어 있으면 안 되고 형제 사이에서 고유해야 합니다.

데이터 갱신, 선택, 탐색

실시간 값이 바뀌면 새로운 불변 data 트리를 전달하세요. 기존 트리를 제자리에서 수정하면 레이아웃 메모이제이션이 갱신되지 않습니다. 색상이 바뀐 셀에는 기본 240ms 전환 효과가 적용되지만, 이는 피드 수신 속도를 제한하지 않습니다. 빠른 피드에서는 앱에서 업데이트 묶음을 결정하고 대상 브라우저와 데이터 규모로 측정하세요.

React에서 drill-down과 리프 선택을 직접 관리하려면 useHeatmapState(root)를 만들고 <Heatmap data={root} state={state} />로 전달하세요. state.visibleNode, state.breadcrumbs, state.navigationPath, state.navigateToPath(path)를 사용할 수 있습니다. 같은 root ID의 불변 데이터 갱신에서는 유효한 탐색과 선택이 유지됩니다. 기존처럼 onGroupClick과 외부 data를 직접 관리하는 방식도 지원합니다. selectedId 또는 selectedKey는 외부에서 제어하는 선택 강조에 사용할 수 있습니다.

렌더링과 접근성

SVG 렌더러는 셀 크기에 맞춰 글자와 선택적인 원형 imageUrl 로고를 표시합니다. 이미지 로딩과 캐시는 브라우저·호스트 앱의 책임이며 Kotlin 코어는 이미지를 가져오지 않습니다. style, displayPolicy, interaction, motion 설정 객체는 Compose와 같은 이름 및 기본값을 사용합니다. hover 툴팁은 기본적으로 꺼져 있으며 interaction={{ showTooltipOnHover: true }}로 켤 수 있습니다. 차트는 Tab 한 번으로 진입하고 방향키는 데이터 순서로 이동하며 Home/End는 첫 항목과 마지막 항목으로 이동합니다. 기본 접근성 이름에는 원본 값이 포함되며 valueFormatter, valueLabel로 표기를 조정할 수 있습니다. 설정 가능한 필드는 React API 참조를 확인하세요.

색상 규칙에는 palette, maximumAbsoluteMetric, 선택적 노드 color를 사용합니다. metricFormatter는 표시 문자열만 바꾸며 레이아웃·색상 계산에는 영향을 주지 않습니다. 타입, 기본값, 검증 규칙은 React API 참조를 확인하세요.

웹 데모 실행

React 데모에는 일반 화면, 100ms 빠른 피드, 집계/원본 5,000리프 모드가 있습니다. 수동 스트레스 시나리오이며 프레임률 보장은 아닙니다. 이 저장소에서 실행하려면 로컬 Kotlin/JS 코어와 패키지를 먼저 빌드합니다.

./gradlew :volcano:jsDevelopmentLibraryCompileSync
cd packages/volcano-react && npm ci && npm run build
cd ../../examples/react-demo && npm ci && npm run dev