API Treemap

Các ô phân cấp có kích thước theo giá trị, mỗi ô có thể tùy chọn chia thành hai phần được đặt tên (ví dụ: đã hiện thực hóa so với chưa khai thác), kèm phương án dự phòng xếp chồng thân thiện với di động - xem bản demo Treemap.

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);

Props

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, ...)

Events

Web component phát ra các CustomEvent nổi bọt (bubbling) sau đây (engine cũng cung cấp tương đương qua các callback on* trong bảng ở trên):

Event	Detail	Kích hoạt khi
michi-vz:highlight	string[]	khi trạng thái tô sáng hover thay đổi
michi-vz:colormapping	Record<string, string>	khi một color mapping được tạo ra
michi-vz:dataprocessed	ChartContext	khi dữ liệu được xử lý (lại)
michi-vz:datawarning	DataWarning[]	khi phát hiện cảnh báo về dữ liệu đầu vào

getContext()

mountTreemapChart(el, props).getContext() trả về một TreemapChartContext không phụ thuộc bộ dựng: các leaves phẳng (value / partial / remainder / percent / path), layout đã được phân giải, splitLabels, depth lồng nhau, số liệu thống kê tóm tắt (tổng cộng, tổng theo từng phần, leaf lớn nhất, remainder lớn nhất), một bản tóm tắt ngôn ngữ tự nhiên có tính xác định, và một bảng a11y. Xem ngữ cảnh LLM.

Source

Các prop được định kiểu là TreemapChartProps trong @michi-vz/core.