API Graphique en ruban

Observez une composition se réorganiser dans le temps, une catégorie connectée à la fois. Voir la démo Graphique en ruban.

Import

Web Component

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

Vanilla JS

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

const chart = mountRibbonChart(el, props);

Propriétés

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*	RibbonDataRow[]	-	Array of rows (one per date) whose keys stack into a column; same-key segments are linked across adjacent dates by ribbon trapezoids
keys*	string[]	-	Ordered segment keys to stack within each column (bottom-to-top) and to connect with ribbons between columns
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
yAxisDomain	[number, number]	-	Explicit [min, max] for the value (y) axis; overrides the auto domain from the stacked column totals
columnWidth	number	30	column width in px (default 30).
ticks	number	5	Approximate number of axis ticks to generate
tooltipFormatter	(row: RibbonDataRow, key: string, value: number) => 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: 60, 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, ...)

Événements

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

Événement	Détail	Se déclenche quand
michi-vz:highlight	string[]	la surbrillance au survol change
michi-vz:colormapping	Record<string, string>	un mapping de couleurs est généré
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()

mountRibbonChart(el, props).getContext() retourne un RibbonChartContext indépendant du moteur de rendu (statistiques structurées + un résumé déterministe en langage naturel + une table d'accessibilité). Voir Contexte LLM.

Source

Les propriétés sont typées comme RibbonChartProps dans @michi-vz/core.