API Barres doubles (Tornado)

Des barres divergentes depuis une ligne centrale, quand il faut montrer quel côté l'emporte et de combien - voir la démo des Barres doubles (Tornado).

Import

Web Component

import "@michi-vz/wc/dual-horizontal-bar-chart";
// <michi-vz-dual-horizontal-bar-chart> is now defined

Vanilla JS

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

const chart = mountDualHorizontalBarChart(el, props);

Props

Prop	Type	Default	Description
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`. Values tween between periods unless `interpolate: false`.
dataSet*	DualBarDataPoint[]	-	Array of diverging (tornado) rows; each row draws value1 as a bar extending right and value2 as a bar extending left from a shared center
title	string	-	Optional chart title rendered above the plot
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
xAxisDomain	[number, number]	-	Fix the x-axis range instead of deriving it from the data
ticks	number	-	Approximate number of axis ticks to generate
tickHtmlWidth	number	100	Width in px reserved for each y-axis (label) tick's HTML (default 100)
yAxisPosition	"center" | "left"	"center"	Where the row labels sit: "center" (default, legacy: on the shared centre line, over the left-extending bars) or "left" (in the left margin, clear of the plot - the classic population-pyramid look).
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.
value1Opacity	number	0.9	value1 (right) / value2 (left) fill opacities.
value2Opacity	number	0.55	Fill opacity of the left-extending value2 bar (default 0.55)
filter	{ limit: number; criteria: "value1" | "value2"; sortingDir: "asc" | "desc"; }	-	Keep only the top-N labels ranked by the chosen field: limit caps the count, criteria selects "value1" or "value2", sortingDir picks highest (desc) or lowest (asc)
tooltipFormatter	(d: DualBarDataPoint) => string	-	Returns custom tooltip HTML for a hovered datum (sanitized before it is inserted)
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: 120 }	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()

mountDualHorizontalBarChart(el, props).getContext() renvoie un DualBarChartContext 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 DualBarChartProps dans @michi-vz/core.