API Barres comparables verticales
Deux valeurs par catégorie, de base vs comparée, sous forme de colonnes superposées en pleine largeur avec une flèche de variation optionnelle au-dessus de chaque paire - voir la démo des Barres comparables verticales.
Import
ts
import "@michi-vz/wc/comparable-vertical-bar-chart";
// <michi-vz-comparable-vertical-bar-chart> is now definedts
import { mountComparableVerticalBarChart } from "@michi-vz/core";
const chart = mountComparableVerticalBarChart(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* | ComparableBarDataPoint[] | - | Array of column categories; each renders two overlaid sub-bars (valueBased behind, valueCompared in front), full column bandwidth, diverging from y=0 |
title | string | - | Optional chart title rendered above the plot |
colorsBasedMapping | Record<string, string> | - | Optional label -> colour map for the value-based sub-bar ONLY (falls back to the row colour). Pair an opaque light tint here with valueBasedOpacity 1 for the crispest before/after contrast (legacy michi-vz parity). |
xAxisFormat | (d: string) => string | - | Formats a category (x tick) label |
yAxisFormat | (d: number | string) => string | - | Formats a y tick value into its display label |
yAxisDomain | [number, number] | - | Fix the y-axis (value) range instead of deriving it from the data |
symmetricYDomain | boolean | - | Force a symmetric y-domain [-M, M], M = max(|min|, |max|) of the data, so 0 sits centred and the negative/positive sides mirror. Wins over yAxisDomain. |
ticks | number | 5 | Approximate number of y-axis (value) ticks |
xAxisLabelPadding | number | - | Min gap (px) a column label needs before it tilts -45° (chooseAxisMode). Default 8. |
xAxisMode | "auto" | "horizontal" | - | "auto" (default) tilts crowded column labels -45°, else thins; "horizontal" keeps them flat (thinning instead), so no rotated-label bottom margin is reserved. |
patternsMapping | Record<string, string> | - | Per-label image source (data-URI, e.g. createHatchPattern) used to FILL the value-based sub-bar - the canvas tiles it via ctx.createPattern, the SVG renderer via a real `<pattern>`/`<image>` def (same contract as ComparableHorizontalBarChart). |
valueBasedOpacity | number | 0.45 | Fill opacity of the rear valueBased sub-bar (historical look: 0.45) |
valueComparedOpacity | number | 0.9 | Fill opacity of the front valueCompared sub-bar (default 0.9) |
showZeroLineForYAxis | boolean | false | Draw a solid horizontal line at y=0 on the value axis (diverging charts) |
showGrid | boolean | false | Draw horizontal gridlines on the value axis (default false, legacy parity) |
hideTickLabels | boolean | false | Hide the x-axis category labels |
minBarHeight | number | 5 | Floor for a sub-bar's pixel height so near-zero values stay visible (default 5) |
maxBarWidth | number | - | Cap each column's thickness (px). When few categories would otherwise balloon the bandwidth, the band range shrinks to yield exactly this thickness and is centred in the plot. No-op for dense charts whose natural bandwidth is already below the cap. |
deltaIndicator | DeltaIndicatorConfig | - | Row-level change indicator (arrow + formatted diff label) comparing valueCompared to valueBased, drawn above each column pair. Omitted, or `{ show: false }`, is a provable no-op (zero geometry, zero `.mv-delta` DOM). Unlike ComparableHorizontalBarChart, THIS chart's context DOES reflect the indicator (per-series direction/color/label) - see DeltaIndicatorConfig JSDoc for the full decision-logic contract. |
isLoading | boolean | - | Loading overlay (stale bars hidden while true) |
isNodata | | boolean | ((dataSet: ComparableBarDataPoint[] | null | undefined) => boolean) | - | No-data predicate/flag; default = empty dataSet |
noDataLabel | string | - | Text for the built-in no-data overlay |
suppressDefaultOverlay | boolean | - | Set by a framework wrapper passing its own overlay node - suppresses the default overlay |
filter | { limit: number; criteria: "valueBased" | "valueCompared"; sortingDir: "asc" | "desc"; } | - | Keep only the top-N labels ranked by the chosen field: limit caps the count, criteria selects "valueBased" or "valueCompared", sortingDir picks highest (desc) or lowest (asc) |
tooltipFormatter | ( d: ComparableBarDataPoint, dataSet?: ComparableBarDataPoint[], type?: "based" | "compared", ) => string | - | Returns custom tooltip HTML for a hovered datum (sanitized before it is inserted). `type` is the hovered sub-bar ("based" | "compared"); `dataSet` is all rows. |
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: 100, 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 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()
mountComparableVerticalBarChart(el, props).getContext() renvoie un ComparableVerticalBarChartContext agnostique du renderer (statistiques structurées + un résumé déterministe en langage naturel + un tableau d'accessibilité). Contrairement à ComparableHorizontalBarChart, ce contexte reflète deltaIndicator quand il est actif : series[].deltaDirection / deltaColor / deltaLabel, et stats.grew / stats.shrank / stats.unchanged / stats.improved / stats.worsened. Voir Contexte LLM.
Source
Les props sont typées comme ComparableVerticalBarChartProps dans @michi-vz/core.