Gap Chart API

Show the distance between two numbers and let the bar carry the punch - see the Gap Chart demo.

Import

Web Component

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

Vanilla JS

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

const chart = mountGapChart(el, props);

Props

Prop	Type	Default	Description
dataSet*	GapDataItem[]	—	Array of rows, one horizontal value1->value2 gap bar per item
title	string	—	Optional chart title rendered above the plot
colorMode	"label" | "shape"	"label"	Whether marks are colored per row label ("label", default) or per role/shape via shapeColorsMapping ("shape")
shapeColorsMapping	ShapeMapping	—	When colorMode is "shape", the colors for the value1, value2, and gap parts
shapesLabelsMapping	ShapeMapping	—	Optional display labels for the value1/value2/gap roles (e.g. legend captions)
filter	Filter	—	Top-N / sort filter applied to the data before rendering
shapeValue1	"circle" | "square" | "triangle"	"circle"	Marker shape for the value1 endpoint: "circle" (default), "square", or "triangle"
shapeValue2	"circle" | "square" | "triangle"	"circle"	Marker shape for the value2 endpoint: "circle" (default), "square", or "triangle"
xAxisDataType	"date_annual" | "date_monthly" | "number"	"number"	How x values are parsed and formatted: yearly dates, monthly dates, or plain numbers
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
tickHtmlWidth	number	100	Width in px of the HTML y-axis label box, which ellipsizes longer labels (default 100)
squareRadius	number	2	Corner radius in px for square markers (default 2)
showLegend	boolean	—	Whether to render a legend
legendAlign	"left" | "center" | "right"	—	Horizontal alignment of the legend: "left", "center", or "right"
tooltipFormatter	(d: GapDataItem) => string	—	Returns custom tooltip HTML for a hovered datum (sanitized before it is inserted)
onHighlightItem	(item: GapDataItem | null) => void	—	Called when the hovered/highlighted label(s) change

Common props — shared by every chart (14)

Prop	Type	Default	Description
width	number	1000	Chart width in pixels
height	number	500	Chart height in pixels
margin	Margin	{ top: 50, right: 150, bottom: 100, left: 150 }	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"	"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, gaps, ...)

Events

The web component dispatches these bubbling CustomEvents (the engine exposes the same via the on* callbacks in the table above):

Event	Detail	Fires when
michi-vz:highlight	string[]	hover highlight changes
michi-vz:colormapping	Record<string, string>	a color mapping is generated
michi-vz:dataprocessed	ChartContext	data is (re)processed
michi-vz:datawarning	DataWarning[]	input warnings are detected

getContext()

mountGapChart(el, props).getContext() returns a renderer-agnostic GapChartContext (structured stats + a deterministic natural-language summary + an a11y table). See LLM context.

Source

Props are typed as GapChartProps in @michi-vz/core.