Treemap API

Hiërarchische tegels geschaald naar waarde, elk optioneel opgesplitst in twee benoemde delen (bijv. gerealiseerd vs. onbenut), met een mobielvriendelijke stapel-fallback - zie de Treemap-demo.

Import

Web Component

import "@michi-vz/wc/treemap-chart";
// <michi-vz-treemap-chart> is now defined

Vanilla JS

import { mountTreemapChart } from "@michi-vz/core";

const chart = mountTreemapChart(el, props);

Eigenschappen

Prop	Type	Default	Description
timeline	boolean | TimelinePeriodConfig	-	Opt-in "play through years": snapshots one period at a time over the period tags in the data, with a headless controller (`chart.timeline()`) plus the built-in play button + scrubber. Values tween between periods unless `interpolate: false`. Off by default; wins over `progressiveDraw` when both are set.
progressiveDraw	boolean | ProgressiveDrawConfig	-	Opt-in reveal animation: wipes the marks in left to right on mount (a clip reveal; axes and titles stay put). `true` uses defaults (1200 ms, easeInOutCubic); a config tunes durationMs, easing, autoplay, and replayOnUpdate (`tipLabel` is LineChart-only and ignored here). Off by default; respects prefers-reduced-motion (renders fully drawn instantly) and `replay()` re-runs it.
dataSet*	TreemapNode[]	-	Forest of nodes (each a leaf or a parent with children) sized by value and tiled to fill the area
title	string	-	Optional chart title rendered above the plot
paddingInner	number	1	Gap between sibling tiles in px (default 1).
paddingTop	number	18	Header strip height (px) reserved on parent tiles for their label in nested mode (default 18).
layout	"squarify" | "stack" | "auto"	"squarify"	Layout algorithm: "squarify" (treemap, default), "stack" (single-column, mobile-friendly), or "auto" (stack below `stackBreakpoint` width).
stackBreakpoint	number	-	Width (px) below which `layout: "auto"` switches to the stack layout (default 480).
splitLabels	[string, string]	["Filled", "Remaining"]	Names of the two split parts (default ["Filled","Remaining"]).
splitOpacity	number	0.35	Apparent colour strength of the remainder/untapped segment in [0,1] (default 0.35). Rendered as the solid colour under a white veil, so it reads as a lighter tint of the same hue on any background (light or dark) rather than depending on the backdrop.
showSplit	boolean	-	Render the primary/remainder split. Defaults to auto-on when any leaf carries `partial`.
showLegend	boolean	false	Render a 2-swatch split legend (uses splitLabels).
minTileShare	number	-	Floor each leaf's tiling area to this percent of the largest leaf, so tiny tiles stay visible.
filter	{ limit: number; sortingDir: "asc" | "desc" }	-	Keep only the top-N leaves by value.
isLoading	boolean	-	Show the loading overlay and skip the no-data check (legacy michi-vz parity).
isNodata	boolean | ((dataSet: TreemapNode[] | null | undefined) => boolean)	-	No-data override: boolean, or a predicate on dataSet; default = empty dataSet.
noDataLabel	string	-	Text for the vanilla default no-data overlay (ignored when suppressed).
suppressDefaultOverlay	boolean	-	A framework wrapper sets this to render its OWN loading/no-data node instead.
valueFormatter	(n: number) => string	-	Formats numeric values shown in the default tooltip (defaults to a locale number formatter)
tooltipFormatter	(leaf: TreemapLeafContext) => string	-	Returns custom tooltip HTML for a hovered datum (sanitized before it is inserted)
tileValueLabels	boolean | TreemapTileValueLabelsConfig	-	Render each tile's value (+ share of the dataset total) as a SECOND line under the existing name label. Omitted, or `false`, is a byte-for-byte no-op - zero extra DOM, default off. Gated by the SAME tile-size fitting logic this chart already uses: a tile must qualify for its name label at all (`h >= 24 && w >= 30`, see `renderTreemapSvg` in `treemapChart/renderSvg.ts`) AND meet the larger threshold this chart already reserves for a second line - the exact same `w >= 48 && h >= 34` gate the split "percent of leaf" second line already uses right below it. Reused verbatim, not reinvented: two text lines need more room than one, and this chart had already made that call once. Ported from the legacy sdg-trade TreemapChart (`components/Charts/TreemapChart/Chart.js`), which shows `{formattedValue} ({formattedShare})` as a second line only when `leafWidth > 80 && leafHeight > 70` px (a name-only line renders down to `leafWidth >= 60 && leafHeight >= 40`; nothing smaller than that). This port reuses this library's OWN, already-shipped thresholds instead of copying the legacy's exact pixel cutoffs (a different tile-padding/ font-size baseline) - the requirement is "size-gating exists and reuses the chart's existing mechanism", not byte-identical legacy pixels.
onHighlightItem	(labels: string[]) => void	-	Called when the hovered/highlighted label(s) change

Common props - shared by every chart (14)

Prop	Type	Default	Description
width	number	900	Chart width in pixels
height	number	520	Chart height in pixels
margin	Margin	{ top: 36, right: 6, bottom: 6, left: 6 }	Inner margins (top/right/bottom/left, in px) reserved for axes, titles, and labels
colors	string[]	-	Categorical palette for series/labels without an explicit colour or colorsMapping entry
colorsMapping	Record<string, string>	-	Explicit label -> colour map; takes precedence over the palette and per-item colours
highlightItems	string[]	-	Labels to emphasise; all other marks dim
disabledItems	string[]	-	Labels to hide and exclude from scales/stacks
renderer	"svg" | "canvas" | "webgpu"	"svg"	Render as inline SVG (default) or to a canvas (faster for large datasets); getContext() is identical either way
locale	string	-	BCP-47 locale used for number and date formatting
skipColorMappingDispatch	boolean	false	External-CSS mode: unmapped labels resolve to transparent and onColorMappingGenerated is not emitted, so mark colours come from your CSS via the data-label-safe contract
enableTransitions	boolean	true	Animate updates with CSS transitions (default true)
onColorMappingGenerated	(mapping: Record<string, string>) => void	-	Called with the resolved label -> colour map after the chart assigns colours
onChartDataProcessed	(context: ChartContext) => void	-	Called with the renderer-agnostic ChartContext whenever the data is (re)processed
onDataWarning	(warnings: DataWarning[]) => void	-	Called with any non-fatal data warnings (duplicate labels, non-finite values, non-monotonic dates, ...)

Gebeurtenissen

Het webcomponent verzendt deze bubbelende CustomEvents (de engine biedt dezelfde functionaliteit via de on*-callbacks in de tabel hierboven):

Gebeurtenis	Detail	Wordt geactiveerd wanneer
michi-vz:highlight	string[]	de hover-markering verandert
michi-vz:colormapping	Record<string, string>	een kleurmapping wordt gegenereerd
michi-vz:dataprocessed	ChartContext	data (opnieuw) wordt verwerkt
michi-vz:datawarning	DataWarning[]	invoerwaarschuwingen worden gedetecteerd

getContext()

mountTreemapChart(el, props).getContext() retourneert een renderer-onafhankelijke TreemapChartContext: de platte leaves (waarde / gedeeltelijk / restant / percentage / pad), de opgeloste layout, de splitLabels, de depth (nestingsdiepte), samenvattende statistieken (totaalgeneraal, totalen per deel, grootste blad, grootste restant), een deterministische samenvatting in gewone taal, en een a11y-tabel. Zie LLM-context.

Bron

Eigenschappen zijn getypeerd als TreemapChartProps in @michi-vz/core.