Vlakdiagram API

Ontdek welk deel van een groeiend totaal daar echt de motor achter is - props en events hieronder, of de Vlakdiagram-demo om het in actie te zien.

Import

Web Component

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

Vanilla JS

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

const chart = mountAreaChart(el, props);

Props

Prop	Type	Default	Description
timeline	boolean | TimelinePeriodConfig	-	Opt-in "play through years" (cumulative): the marks draw UP TO the active period and extend as the timeline steps; `interpolate` sweeps smoothly between years, `false` jump-cuts. Headless controller via `chart.timeline()` plus the built-in play button + scrubber. 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.
series*	AreaDataRow[]	-	Array of rows, each carrying an x (`date`) plus one numeric value per stacked key
keys*	string[]	-	Category keys to stack (bottom-to-top); disabledItems removes from the stack.
title	string	-	Optional chart title rendered above the plot
xAxisDataType	"date_annual" | "date_monthly" | "number"	"number"	How x values are parsed and formatted: yearly dates, monthly dates, or plain numbers
xAxisFormat	(d: number | string) => string	-	Formats an x tick value into its display label
yAxisFormat	(d: number | string) => string	-	Formats a y tick value into its display label
yAxisDomain	[number, number]	-	Fix the y-axis range as [min, max] instead of deriving it from the data
forcePercentageScale	boolean	false	Fix the y-axis to [0,100] regardless of data (display only; data not normalized).
stackOffset	"none" | "expand"	"none"	Stacking normalization, named after d3-shape's own `stackOffsetExpand`. `"none"` (default) stacks absolute values, unchanged. `"expand"` NORMALIZES each x-slice so its band heights sum to 1 (a true 100%-stacked chart, unlike the display-only `forcePercentageScale`): the y domain becomes [0,1] and y-axis ticks render as percentages unless an explicit `yAxisFormat` is given. A slice whose keys are all zero/null renders as an empty (zero-height) band rather than `NaN`.
ticks	number	10	Approximate number of axis ticks to generate
tickValues	Array<number | Date>	-	Explicit tick values, overriding the generated ones
fillPeriodTicks	boolean	-	Draw a tick for EVERY period across the axis range (every month/year), not just the periods present in the data. Periods with no value render faded and show `noDataTickTooltip` on hover. Opt-in; default false.
noDataTickTooltip	(date: number) => string	-	Tooltip content (plain text or sanitized HTML) for a faded no-data tick; receives the tick's epoch-ms value. Used only with `fillPeriodTicks`. Default: a localized "Data not available".
noDataTickColor	string	-	Colour for faded no-data tick labels; sets the `--michi-vz-tick-nodata` CSS var on the host. Used only with `fillPeriodTicks`.
curve	"curveBumpX" | "curveLinear" | "curveMonotoneX"	-	Line interpolation: curveLinear, curveMonotoneX, or curveBumpX
tooltipFormatter	( row: AreaDataRow, series: AreaDataRow[], key: string, ) => string	-	Returns custom tooltip HTML for a hovered datum (sanitized before it is inserted)
isLoading	boolean	-	Show the loading overlay and skip the no-data check (legacy michi-vz parity).
isNodata	boolean | ((dataSet: AreaDataRow[] | null | undefined) => boolean)	-	No-data override: boolean, or a predicate on the data; default = empty data.
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.
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	480	Chart height in pixels
margin	Margin	{ top: 50, right: 50, bottom: 50, left: 60 }	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

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

Gebeurtenis	Detail	Treedt op wanneer
michi-vz:highlight	string[]	de highlight bij hover verandert
michi-vz:colormapping	Record<string, string>	er een kleurtoewijzing wordt gegenereerd
michi-vz:dataprocessed	ChartContext	gegevens worden (opnieuw) verwerkt
michi-vz:datawarning	DataWarning[]	invoerwaarschuwingen worden gedetecteerd

getContext()

mountAreaChart(el, props).getContext() retourneert een renderer-onafhankelijke AreaChartContext (gestructureerde statistieken + een deterministische samenvatting in gewone taal + een a11y-tabel). Zie LLM-context.

Bron

Props zijn getypeerd als AreaChartProps in @michi-vz/core.