API Graphique d'écart

Montrez la distance entre deux nombres et laissez la barre porter tout l'impact - voir la démo du Graphique d'écart.

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

Événements

Le composant web émet ces CustomEvents en bubbling (le moteur expose les mêmes via les callbacks on* dans le tableau ci-dessus) :

Événement	Détail	Se déclenche quand
michi-vz:highlight	string[]	le surlignage au survol change
michi-vz:colormapping	Record<string, string>	une correspondance de couleurs est générée
michi-vz:dataprocessed	ChartContext	les données sont (re)traitées
michi-vz:datawarning	DataWarning[]	des avertissements sur les données d'entrée sont détectés

getContext()

mountGapChart(el, props).getContext() renvoie un GapChartContext agnostique du renderer (statistiques structurées + un résumé déterministe en langage naturel + un tableau d'accessibilité). Voir Contexte LLM.

Source

Les props sont typées comme GapChartProps dans @michi-vz/core.