Architecture and Modules
Choose the smallest Volcano artifact set and keep domain data outside the SDK.
Artifact boundary
| Artifact | Responsibility | Add when |
|---|---|---|
volcano | HeatmapNode, color contracts, sorting, filtering, aggregation, squarified layout primitives | A shared data/domain module prepares heatmap data. |
volcano-compose | Heatmap, state, navigation controls, default rendering, interaction, accessibility | A Compose Multiplatform UI renders a heatmap. |
volcano-compose-coil | CoilHeatmapLogo optional remote-image renderer | The application chooses Coil for imageUrl values. |
@taewooyo/heatmap-react | TypeScript API and React SVG renderer with a bundled Kotlin/JS core | A React web app renders a heatmap. |
The first two Gradle artifacts are normally paired in a UI source set. The npm package is installed independently; web consumers do not install the Gradle artifacts. React and Compose share layout/color calculations but not UI components or identical public data types. Coil is deliberately separate: an SDK must not force an image loader, a networking stack, or its cache policy onto every client.
Ownership model
The application owns source data, navigation destination, image loading policy, analytics, and
layout constraints. Volcano owns only hierarchical layout and the reusable heatmap interaction
surface. Keep API DTOs and business objects out of HeatmapNode; map them at the presentation
boundary.
fun Portfolio.toHeatmapNode() = HeatmapNode(
id = id,
label = title,
value = marketValue,
metric = dailyReturnPercent,
children = positions.map(Position::toHeatmapNode),
)This keeps the SDK domain-neutral: a metric can be a stock return, SLA deviation, budget
variance, inventory health, or another signed measure.
State lifetime
rememberHeatmapState(root) retains drill-down and leaf selection while the same immutable root
instance is used. When refreshed data replaces the root, construct the display tree before
composition and pass the new root; state safely starts from the updated root. Hoist state only when
the host needs to coordinate Back behavior or a detail pane.
Use HeatmapState as presentation state, not as a repository for mutable domain data.
The React package exposes useHeatmapState for visible groups, breadcrumbs, and leaf selection. Applications can use that hook or manage navigation externally; pass a new immutable data reference when values change. See React Integration.