API Fontaine (Jet d'Eau)

Un graphique, deux modes : hauteur de l'apex = valeur, panache en éclosion = incertitude. X catégoriel = instantané/comparaison ; x temporel ou numérique = tendance - voir la démo de la Fontaine.

Import

Web Component

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

Vanilla JS

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

const chart = mountFountainChart(el, props);

Props

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.
dataSet*	FountainDataItem[]	-	Array of jets; each item renders one fountain
title	string	-	Optional chart title rendered above the plot
style	"jet" | "plume"	"jet"	Silhouette style: "jet" (default) is the faithful asymmetric Jet d'Eau (vertical column + wind-blown diagonal + a triangular droplet spray curtain); "plume" is the symmetric blooming column.
xAxisDataType	FountainXAxisType	-	How the x-axis is parsed: a temporal/numeric type renders TREND mode; "band" (or omitted) renders SNAPSHOT mode
yAxisDomain	[number, number]	-	Explicit [min, max] for the value (y) axis; overrides the auto domain from value + spread
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 (trend mode)
frothLayers	number	14	Number of graduated-opacity froth layers per jet (default 14, max 20); a per-item density overrides it
bloomExponent	number	5	Exponent in the bloom easing w(h)=stemHalf+spread*(h/H)^p; larger = tighter column, sharper crown (default 5)
stemFraction	number	0.045	Stem half-width at the base as a fraction of the jet's slot width (default 0.045)
showDroplets	boolean	true	Draw ballistic droplet arcs above each apex (default true)
showMist	boolean	true	Draw the misty falling skirt around each nozzle (default true)
showTrendLine	boolean	true	Draw a connecting line through the apexes in trend mode (default true)
tooltipFormatter	(d: FountainDataItem) => string	-	Returns custom tooltip HTML for a hovered jet (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: 40, bottom: 50, 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, ...)

Deux modes, une seule forme de données

Définissez xAxisDataType: "band" (ou omettez-le) pour le mode Instantané - chaque élément obtient sa propre bande en x, côte à côte. Fournissez un xAxisDataType temporel ou numérique ainsi qu'une date sur chaque élément pour le mode Tendance - les jets sont placés le long de l'axe temporel et une ligne de tendance relie leurs sommets. Un élément avec predicted: true s'affiche en pointillés avec une couronne plus mousseuse.

É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 (étiquette du jet)
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 (par ex. une valeur ou une étendue non finie)

getContext()

mountFountainChart(el, props).getContext() renvoie un FountainChartContext agnostique du renderer :

• mode - "snapshot" pour un x catégoriel/en bandes, "trend" pour un x temporel/numérique.
• jets - une entrée par jet visible : { label, code?, color, value, spread, upperBound, spreadRatio, predicted, xPosition }. upperBound = value + spread ; spreadRatio = spread / value (incertitude relative) ; xPosition est la date/le nombre brut en mode tendance, ou null en mode instantané.
• stats - objet de synthèse :
  • jetCount - nombre de jets visibles.
  • tallest - { label, value } du jet le plus haut, ou null s'il est vide.
  • frothiest - { label, spreadRatio } du jet le plus incertain, ou null s'il est vide.
  • trendSlope - pente d'une régression linéaire sur les valeurs des jets par index en mode tendance ; null en mode instantané.
  • valueRange - [min, max] des valeurs des jets, ou null s'il est vide.
  • predictedCount - nombre de jets de prévision.

Voir Contexte LLM pour savoir comment utiliser le contexte dans des prompts et des rapports.

Source

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