API Sankey

Des flux entre nœuds disposés en colonnes, avec une épaisseur de bande proportionnelle à la valeur du flux (construit sur d3-sankey) - voir la démo Sankey.

Import

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

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

const chart = mountSankeyChart(el, props);

import { SankeyChart } from "@michi-vz/react/sankey-chart";

import { SankeyChart } from "@michi-vz/vue/sankey-chart";

import { sankeyChart } from "@michi-vz/svelte/sankey-chart";

import { bindChart, applySankeyChartProps } from "@michi-vz/angular/sankey-chart";
// needs CUSTOM_ELEMENTS_SCHEMA on the component that hosts <michi-vz-sankey-chart>

Propriétés

Prop	Type	Default	Description
`timeline`	`boolean \| TimelinePeriodConfig`	-	Opt-in "play through years": snapshots one period at a time over the period tags in the data, with a headless controller (`chart.timeline()`) plus the built-in play button + scrubber. Values tween between periods unless `interpolate: false`. 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.
`nodes`*	`SankeyNodeItem[]`	-	Flow nodes; each needs a unique id that links reference
`links`*	`SankeyLinkItem[]`	-	Directed flows between nodes (source -> target); band thickness is proportional to value
`title`	`string`	-	Optional chart title rendered above the plot
`nodeWidth`	`number`	`18`	Node rect width in px (default 18).
`nodePadding`	`number`	`12`	Vertical gap between nodes in a column in px (default 12).
`nodeRadius`	`number`	`2`	Corner radius of the node rects in px (default 2; 0 = square corners). Clamped to half the node's shorter side.
`linkRadius`	`number`	`2`	Corner radius (px) of the filled flow ribbons where they meet the nodes (default 2; 0 = sharp corners). Clamped to half the band's thickness.
`linkColorMode`	`"source" \| "target"`	`"source"`	Colour links by their "source" (default) or "target" node.
`linkOpacity`	`number`	`0.45`	Link opacity in [0,1] (default 0.45).
`showLabels`	`boolean`	`true`	Draw node labels (default true).
`hoverHighlight`	`boolean`	`false`	Built-in hover emphasis, default false: hovering a NODE keeps it, every flow into or out of it and the nodes at those flows' other ends at full strength, hovering a FLOW keeps only that flow and its two end nodes, and everything else dims to the `highlightItems` levels (flows at linkOpacity x 0.25, nodes at 0.25). Applied in place (svg updates opacity on the existing marks and fades per `enableTransitions`; canvas/webgpu repaint), so hovering never re-renders the chart and consumers need not mirror `onHighlightItem` into `highlightItems`. While hovering it wins over `highlightItems`; leaving restores that state. A pinned (clicked) tooltip keeps its emphasis until unpinned. `onHighlightItem` fires exactly as without it.
`nodeSort`	`"auto" \| "input"`	`"auto"`	Vertical order of the nodes inside a column (default "auto"): "auto" lets d3-sankey arrange them to reduce crossings, "input" keeps the order of the `nodes` array (and the order of `links` for the bands leaving a node), so a "Rest of ..." or "Others" node stays where you listed it, typically last.
`minLinkValue`	`number`	-	Floor for the band thickness, in value units (default none): a link whose value is below it is LAID OUT as if it had this value, so a trickle next to a big flow still has a band wide enough to hover. Only the geometry changes; the tooltip, `valueFormatter`, the context and the totals keep the real values. Pick it from your data, e.g. 15% of the largest link.
`isLoading`	`boolean`	-	Show the loading overlay and skip the no-data check (legacy michi-vz parity).
`isNodata`	`boolean \| ((dataSet: SankeyNodeItem[] \| null \| undefined) => boolean)`	-	No-data override: boolean, or a predicate on nodes; default = empty nodes.
`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.
`valueFormatter`	`(n: number) => string`	-	Formats a numeric value for labels and tooltips
`tooltipFormatter`	`(mark: SankeyNodeContext \| SankeyLinkContext) => string`	-	Returns custom tooltip HTML for a hovered datum/mark (sanitized before it is inserted)
`onNodeClick`	`(node: SankeyNodeContext, event: MouseEvent) => void`	-	Called when a node is clicked (svg marks and the canvas/webgpu hit-test alike), with the same node context the tooltip formatter receives and the mouse event. The click still pins the tooltip as before; use this to navigate or select from the mark itself instead of a link inside the pinned tooltip.
`onLinkClick`	`(link: SankeyLinkContext, event: MouseEvent) => void`	-	Called when a flow band is clicked, with its link context and the mouse event (same pinning behaviour as `onNodeClick`).
`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`	`800`	Chart width in pixels
`height`	`number`	`500`	Chart height in pixels
`margin`	`Margin`	`{ top: 36, right: 12, bottom: 12, left: 12 }`	Inner margins (top/right/bottom/left, in px); default 8 (36 top with a title)
`colors`	`string[]`	-	Categorical palette for rings 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 (active styling); others keep their base opacity
`disabledItems`	`string[]`	-	Labels to hide entirely (ring + track removed; remaining rings keep their radii order)
`renderer`	`"svg" \| "canvas" \| "webgpu"`	`"svg"`	Render as inline SVG (default) or to a canvas / WebGPU layer; getContext() is identical either way
`locale`	`string`	-	BCP-47 locale used for number formatting
`skipColorMappingDispatch`	`boolean`	`false`	External-CSS mode: unmapped labels resolve to transparent and onColorMappingGenerated is not emitted, so arc colours come from your CSS via the data-label-safe contract
`enableTransitions`	`boolean`	`true`	Animate opacity/arc changes with CSS transitions (SVG renderer; 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 (out-of-range values, duplicate labels, ...)

Les données sont deux tableaux

Contrairement aux autres graphiques, un Sankey prend nodes ({ id, label?, color? }[]) et links ({ source, target, value }[]) au lieu d'un unique dataSet.

É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 (id de nœud, ou la source + la cible d'un lien)
`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 (par exemple un lien vers un nœud inconnu)
`michi-vz:nodeclick`	`SankeyNodeContext`	un nœud est cliqué (le callback `onNodeClick`)
`michi-vz:linkclick`	`SankeyLinkContext`	une bande de flux est cliquée (le callback `onLinkClick`)

getContext()

mountSankeyChart(el, props).getContext() retourne un SankeyChartContext indépendant du moteur de rendu : les nodes (id / étiquette / couleur / valeur / profondeur de colonne), les links (source / cible / valeur / couleur), des statistiques de synthèse (nombre de nœuds et de liens, nombre de colonnes, flux total, plus grand lien, nœud le plus actif), un résumé déterministe en langage naturel, et une table d'accessibilité listant les flux. Voir Contexte LLM.

Source

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

API Sankey ​

Import ​

Propriétés ​

Événements ​

getContext() ​

Source ​