React API 참조
공개 TypeScript 타입, 컴포넌트 props, 레이아웃 결과와 검증 규칙입니다.
공개 API는 @taewooyo/heatmap-react에서 가져옵니다.
import { Heatmap, computeHeatmapLayout, useHeatmapState } from "@taewooyo/heatmap-react";
import type { HeatmapProps, HeatmapNode, HeatmapLayoutOptions, HeatmapLayoutCell, HeatmapDisplayPolicy, HeatmapInteraction, HeatmapMotion, HeatmapStyle } from "@taewooyo/heatmap-react";HeatmapNode
| 필드 | 타입 | 의미 |
|---|---|---|
id | string | 필수, 비어 있지 않고 형제 사이에서 고유해야 함; 다른 가지에서는 반복 가능 |
label | string | 필수 표시·접근성 문자열 |
value | number | 필수 유한 면적 가중치; 양수만 면적을 받음 |
metric | number? | 선택적 유한 부호 지표, 색상 계산에 사용 |
color | string? | #RRGGBB 또는 #RRGGBBAA 형식의 색상 재정의 |
imageUrl | string? | 호스트가 관리하는 선택적 이미지 URL |
children | readonly HeatmapNode[]? | 중첩 노드; 없거나 비어 있으면 리프 |
입력 트리에 순환 참조가 있으면 안 됩니다. metric은 색상만 바꾸고 면적은 바꾸지 않습니다. 코어는 imageUrl을 가져오지 않습니다.
Heatmap props
HeatmapProps는 HeatmapLayoutOptions를 확장하고 다음 컴포넌트 props를 추가합니다.
| Prop | 타입 | 기본값·동작 |
|---|---|---|
data | HeatmapNode | 필수 루트 트리; 갱신 시 새 참조 전달 |
className | string? | 루트 SVG에 적용 |
ariaLabel | string? | "Heatmap"; 접근성 차트 이름 |
cellGap | number? | 1; SVG 단위의 0 이상 유한 간격 |
selectedId | string | null | null; 일치하는 리프 ID 선택 |
selectedKey | string | null | null; 경로 기반 리프 키, selectedId보다 우선 |
selectedBorderColor | string? | "#0f172a"; 선택 리프 윤곽선 색상 |
tooltipHoverDelayMs | number? | 400; 밀리초 단위의 0 이상 정수 대기 시간 |
logoMaxSize | number? | 48; SVG 이미지의 0 이상 유한 최대 크기 |
metricFormatter | (metric: number) => string | 부호 있는 숫자; 셀·툴팁 문자열 형식 지정 |
valueFormatter | (value: number) => string | 기본은 String(value)이며 셀 설명·툴팁에 원본 값을 추가합니다. |
valueLabel | string | 기본은 "Value"; 접근성 설명에서 값 앞에 표시할 이름입니다. |
onLeafClick | (node, cell) => void | 리프 클릭 또는 Enter/Space 활성화 시 호출 |
onLeafLongClick | (node, cell) => void | 500ms 이상 터치했을 때 호출 |
onGroupClick | (node, cell) => void | 그룹 헤더 클릭 또는 키보드 활성화 시 호출 |
onLeafHover | (node | null) => void | hover된 리프 또는 포인터가 나간 뒤 null 전달 |
state | HeatmapState? | useHeatmapState가 만든 상태; 연결하면 내부 drill-down·선택 사용 |
displayPolicy, style, interaction, motion | 설정 객체 | Compose와 같은 이름과 의미의 렌더링·상호작용 설정 |
Compose와 맞춘 설정 객체
Compose에서 Dp를 쓰는 값은 React에서 SVG 픽셀 숫자로 지정합니다. 객체의 이름과 기본값은 같습니다.
| 객체 | 필드 |
|---|---|
HeatmapStyle | borderColor, groupHeaderColor, groupHeaderTextColor, selectedBorderColor, leafTextColor |
HeatmapDisplayPolicy | hideContentBelow, showMetricAbove, showLabelAbove, cellContentPadding, adaptiveContent, metricFormatter |
HeatmapInteraction | drillDownOnGroupClick, selectLeafOnClick, showTooltipOnLongClick, tooltipDurationMillis, showTooltipOnHover, tooltipHoverDelayMillis |
HeatmapMotion | enabled, durationMillis, initialScale, pressScale, pressedAlpha, pressDurationMillis |
기존 metricFormatter, selectedBorderColor, tooltipHoverDelayMs props도 사용할 수 있습니다. 같은 값이 설정 객체와 기존 prop에 모두 있으면 설정 객체가 우선합니다. hover 툴팁은 Compose처럼 기본적으로 꺼져 있습니다. React 전용 SVG 채우기 색상 전환은 240ms입니다.
useHeatmapState(root)
이 훅을 Heatmap의 state에 전달하면 Compose처럼 현재 그룹, breadcrumb, 리프 선택 상태를 관리합니다.
const state = useHeatmapState(market);
<Heatmap data={market} state={state} width={960} height={600} />visibleNode, breadcrumbs, selectedNode, selectedId, canNavigateUp과 함께 drillDown,
navigateUp, navigateTo, navigateToBreadcrumb, reset, select, isSelected,
clearSelection을 제공합니다. SVG의 필수 크기와 className은 React 방식대로 지정합니다.
HeatmapLayoutOptions
| 옵션 | 타입 | 기본값·검증 |
|---|---|---|
width | number | 필수 양의 정수 SVG 너비 |
height | number | 필수 양의 정수 SVG 높이 |
groupHeaderHeight | number? | 20; 0 이상 정수 |
maximumAbsoluteMetric | number? | 10; 팔레트 양·음 끝점에 대응하는 양의 유한 지표 값 |
palette | { negative: string; neutral: string; positive: string }? | 코어 기본값; 각 색상은 #RRGGBB 또는 #RRGGBBAA |
computeHeatmapLayout(root, options)
React를 렌더링하지 않고 레이아웃만 계산할 수 있습니다.
const cells = computeHeatmapLayout(market, { width: 960, height: 480 });
const visibleLeaves = cells.filter((cell) => cell.visible && cell.isLeaf);결과는 트리 순서의 readonly HeatmapLayoutCell[]입니다. 각 셀에는 원본 node, 경로 기반 key, parentIndex(루트는 -1), depth, x, y, width, height, 계산된 CSS hex color, isLeaf, visible이 있습니다. 보이지 않는 셀은 그리지 마세요. key는 다른 가지에서 반복된 ID를 구분합니다.
잘못된 크기·지표·색상, 순환 참조, 형제 ID 중복은 오류를 발생시킵니다. 컴포넌트가 내부적으로 이 함수를 사용하므로 일반적인 사용자는 Heatmap만 필요합니다.
Kotlin/Compose API는 별도 Kotlin API 참조와 생성된 Dokka 참조를 확인하세요.
0.3.0 추가 API
ResponsiveHeatmap: width/height 대신containerStyle과containerClassName을 받습니다. 높이가 제한된 컨테이너를 제공하세요. 측정 전·숨겨진 상태에는fallback을 표시합니다.emptyContent: 양수 시각화 항목이 없을 때 보여줄 콘텐츠입니다. 기본값은No data입니다.- 원본 값은 접근성 이름에 기본 포함됩니다.
valueFormatter로 숫자 표기를 바꾸고,valueLabel로 값 이름을 현지화할 수 있습니다. state.navigationPath,state.navigateToPath(path): root를 제외한 ID 배열로 탐색합니다.state.drillDown(node): 현재 데이터의 깊은 그룹을 정확하게 엽니다. 문자열은 직계 자식용입니다.
같은 root ID로 갱신하면 유효한 경로와 선택을 유지합니다. root ID 변경 시 초기화합니다.
motion.enabled = false는 채우기 색상 전환도 끕니다.