Verschildiagram API

Toon de afstand tussen twee getallen en laat de staaf de boodschap overbrengen - zie de Verschildiagram-demo.

Import

Web Component

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

Vanilla JS

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

const chart = mountGapChart(el, props);

Props

Prop	Type	Default	Description
dataSet*	GapDataItem[]	-	Array of rows, one horizontal value1->value2 gap bar per item
title	string	-	Optional chart title rendered above the plot
colorMode	"label" | "shape"	"label"	Whether marks are colored per row label ("label", default) or per role/shape via shapeColorsMapping ("shape")
shapeColorsMapping	ShapeMapping	-	When colorMode is "shape", the colors for the value1, value2, and gap parts
shapesLabelsMapping	ShapeMapping	-	Optional display labels for the value1/value2/gap roles (e.g. legend captions)
filter	Filter	-	Top-N / sort filter applied to the data before rendering
timeline	boolean | TimelinePeriodConfig	-	Opt-in "play through years": snapshots one period at a time over the distinct per-row `date` values, with a headless controller (`chart.timeline()`) plus an optional built-in play button + scrubber. Off by default; requires rows with `date`. The user's `filter` still applies within each period.
shapeValue1	"circle" | "square" | "triangle"	"circle"	Marker shape for the value1 endpoint: "circle" (default), "square", or "triangle"
shapeValue2	"circle" | "square" | "triangle"	"circle"	Marker shape for the value2 endpoint: "circle" (default), "square", or "triangle"
xAxisDataType	"date_annual" | "date_monthly" | "number"	"number"	How x values are parsed and formatted: yearly dates, monthly dates, or plain numbers
xAxisDomain	[number, number]	-	Fix the value-axis range as [min, max] instead of the derived zero-baseline domain (e.g. zoom a life-expectancy story into its 35-90 band)
interactiveRowLabels	boolean	false	Make the row labels interactive: hovering or focusing a label draws a leader line to its row's marks, highlights the row, and shows its tooltip; clicking pins the tooltip. Labels become keyboard-focusable. Default false.
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
ticks	number	5	Approximate number of axis ticks to generate
tickValues	Array<number | Date>	-	Explicit tick values, overriding the generated ones
enableExplicitTickValues	boolean	-	When false, ignore `tickValues` for tick placement and GapChart's mark-scale domain, letting the chart use its data-derived domain and generated ticks.
tickHtmlWidth	number	100	Width in px of the HTML y-axis label box, which ellipsizes longer labels (default 100)
squareRadius	number	2	Corner radius in px for square markers (default 2)
showZeroLineForXAxis	boolean	false	Draw a solid vertical line at x=0 on the value axis (diverging charts). Default false.
maxBarHeight	number	-	Cap each row's thickness (px). When few rows would otherwise balloon the bandwidth (a scaleBand stretched over the full plot height), the band range shrinks to yield exactly this thickness and is centred in the plot (symmetric whitespace), so a 1-2 row chart reads tidily instead of a single row floating mid-plot. No-op for dense charts whose natural bandwidth is already below the cap. Mirrors ComparableBarChart's `maxBarHeight`.
showLegend	boolean	-	Whether to render a legend
legendAlign	"left" | "center" | "right"	-	Horizontal alignment of the legend: "left", "center", or "right"
tooltipFormatter	(d: GapDataItem) => 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: GapDataItem[] | 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	(item: GapDataItem | null) => void	-	Called when the hovered/highlighted label(s) change

Common props - shared by every chart (14)

Prop	Type	Default	Description
width	number	1000	Chart width in pixels
height	number	500	Chart height in pixels
margin	Margin	{ top: 50, right: 150, bottom: 100, left: 150 }	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()

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

Bron

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