Lijndiagram API

Alles wat je nodig hebt om een lijndiagram in code op te zetten; voor het verhaal en de demo's, zie de Lijndiagram-demo.

Import

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

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

const chart = mountLineChart(el, props);

import { LineChart } from "@michi-vz/react/line-chart";

import { LineChart } from "@michi-vz/vue/line-chart";

import { lineChart } from "@michi-vz/svelte/line-chart";

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

Eigenschappen

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.
`dataSet`*	`LineDataItem[]`	-	Array of line series, each with its own points
`title`	`string`	-	Optional chart title rendered above the plot
`yAxisDomain`	`[number \| null, number \| null]`	-	Fix the y-axis range as [min, max] instead of deriving it from the data. Either bound may be null to keep just that bound data-derived — e.g. [0, null] pins the baseline at 0 while the maximum keeps following the visible (post legend-toggle, post top-N) series.
`yAxisScale`	`"linear" \| "log"`	`"linear"`	Y-axis scale: "linear" (default) or a base-10 "log" scale. In "log" mode, a non-positive value (<= 0) can't be plotted, so those points are dropped as missing (reported via `onDataWarning`); a dataSet with no positive values at all renders the no-data state instead.
`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 x-axis ticks to generate
`yTicks`	`number`	-	Number of y-axis ticks (default 10, matching the legacy denser value axis).
`showGridLines`	`boolean`	-	Draw horizontal dashed grid lines at each y tick (default true).
`showVerticalGridLines`	`boolean`	-	Draw vertical dashed grid lines at each x tick (default false - the legacy chart drew none).
`highlightZeroLine`	`boolean`	-	Emphasise the y=0 grid line with a darker solid stroke (default true).
`tickValues`	`Array<number \| Date>`	-	Explicit tick values, overriding the generated ones
`fillPeriodTicks`	`boolean`	-	Draw a tick for EVERY period across the axis range (every month/year), not just the periods present in the data. Periods with no value render faded and show `noDataTickTooltip` on hover. Opt-in; default false.
`noDataTickTooltip`	`(date: number) => string`	-	Tooltip content (plain text or sanitized HTML) for a faded no-data tick; receives the tick's epoch-ms value. Used only with `fillPeriodTicks`. Default: a localized "Data not available".
`noDataTickColor`	`string`	-	Colour for faded no-data tick labels; sets the `--michi-vz-tick-nodata` CSS var on the host. Used only with `fillPeriodTicks`.
`curve`	`"curveBumpX" \| "curveLinear" \| "curveMonotoneX"`	-	Default interpolation for every series (per-series `curve` wins).
`detectGaps`	`boolean`	`false`	Auto-derive `certainty` from missing periods (dashes the gap segment).
`expectedStep`	`number`	-	Expected cadence in axis units; REQUIRED for xAxisDataType "number".
`showDataPoints`	`boolean`	`false`	Whether to draw a marker at each data point (default false)
`enableMouseLine`	`boolean \| MouseLineConfig`	`true`	Solid vertical crosshair line snapped to the nearest data point x on hover; pass a config object to style it (default true)
`zoom`	`boolean \| LineZoomConfig`	-	Opt-in x-axis drag-to-zoom: drag a horizontal range inside the plot to zoom into it (a selection rectangle previews the range). Marks clip to the plot box; axis ticks, crosshair snapping, and tooltips all follow the zoomed domain. The y-domain stays FULL (derived from all data, not the visible slice). While zoomed, a built-in "Reset zoom" button restores the full domain; `resetZoom()` / `setZoomDomain()` on the instance drive it programmatically. Off by default.
`onZoomChange`	`(domain: [number, number] \| null) => void`	-	Called when the zoom domain changes: the zoomed [min, max] in axis units (epoch ms on date axes), or null when reset to the full domain.
`singlePointLine`	`boolean \| SinglePointLineConfig`	-	true / config draws a horizontal guide line for single-point series.
`areaFill`	`boolean \| LineAreaFillConfig`	-	Fill the area under each line with a vertical gradient in the series' colour (true, or a config for the opacities/baseline). The fill spans the whole series, gaps included, and never takes the pointer. Drawn in svg and canvas; a "webgpu" request renders as canvas while it is on. Off by default.
`lastPointLabel`	`boolean \| LineLastPointLabelConfig`	-	Label each series' latest visible point with its value (true, or a config with a formatter/colour/font size). Centred above the point and kept inside the chart width. Disabled series get none; dimmed series dim it. Rendered as SVG text in every renderer mode, so PNG/SVG export includes it. Off by default.
`fontFamily`	`string`	-	Font family for axis/title/tooltip text (SVG + canvas). Sets the --michi-vz-font-family CSS var so both renderers resolve it.
`filter`	`Filter`	-	Top-N / sort filter applied to the data before rendering
`progressiveDraw`	`boolean \| ProgressiveDrawConfig`	-	Animate each line drawing itself left to right on mount (progressive reveal). `true` uses defaults; pass a config to tune duration, easing, tip labels, and autoplay. Off by default, so existing charts are unchanged. Respects prefers-reduced-motion: the chart then renders fully drawn instantly. Ignored by the webgpu renderer.
`isLoading`	`boolean`	-	Show the loading overlay and skip the no-data check (legacy michi-vz parity).
`isNodata`	`boolean \| ((dataSet: LineDataItem[] \| null \| undefined) => boolean)`	-	No-data override: boolean, or a predicate on dataSet; default = empty/all-empty-series.
`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.
`tooltipFormatter`	`(d: DataPoint, series: DataPoint[], dataSet: LineDataItem[]) => string`	-	Returns custom tooltip HTML for a hovered datum (sanitized before it is inserted)
`sharedTooltip`	`boolean`	`false`	When true, hovering anywhere in the plot shows ONE tooltip listing every series' value at the nearest x (year) - the "shared"/crosshair tooltip - instead of the single nearest series. Pairs with the crosshair (enableMouseLine, on by default).
`sharedTooltipFormatter`	`(input: { x: number \| string; xLabel: string; entries: Array<{ label: string; value: number; color: string; d: DataPoint }>; }) => string`	-	Custom HTML for the shared tooltip. `entries` is one row per series that has a point at the hovered x, in dataSet order, each with its resolved colour.
`onHighlightItem`	`(labels: string[]) => void`	-	Called when the hovered/highlighted label(s) change
`svgChildren`	`string`	-	Pre-serialised SVG markup injected as direct <svg> children (axis-title text, reference lines). The React wrapper fills this from `children`; mirrors the legacy <LineChart>'s `{children}` slot.

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: 50, bottom: 50, left: 60 }`	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, ...)

Raster- en asweergave

Vier eigenschappen bepalen de dichtheid van de y-astickmarks en het tekenen van rasterlijnen:

Eigenschap	Standaardwaarde	Opmerkingen
`yTicks`	`10`	Geschat aantal tickmarks op de y-as. De oorspronkelijke standaardwaarde was 10; kies een lagere waarde (bijv. `5`) voor een as met minder tickmarks.
`showGridLines`	`true`	Horizontale onderbroken rasterlijnen bij elke y-tick.
`showVerticalGridLines`	`false`	Verticale onderbroken rasterlijnen bij elke x-tick. Het legacy-diagram tekende deze niet; schakel dit alleen in wanneer de extra hulplijnen de leesbaarheid ten goede komen.
`highlightZeroLine`	`true`	Tekent de y=0-lijn als een doorgetrokken lijn (gekleurd via `--michi-vz-zero-line`, met terugval op de rasterkleur) in plaats van een gewone onderbroken tick. Handig wanneer een dataset zowel positieve als negatieve waarden bevat.

Laad- en 'geen data'-status

De engine beheert een data-mv-state-attribuut op het host-element met drie mogelijke waarden - "loading", "nodata" en "ready" - en toont voor de eerste twee ingebouwde overlays, tenzij je dit uitschakelt.

Eigenschap	Type	Standaardwaarde	Opmerkingen
`isLoading`	`boolean`	`false`	Toont de `.mv-loading`-overlay en slaat de controle op geen data volledig over.
`isNodata`	`boolean \| (dataSet) => boolean`	-	Overschrijft het standaardpredicaat (lege `dataSet` of elke serie heeft nul punten). Geef `false` door om het diagram te forceren te renderen, ook wanneer de data leeg lijkt.
`noDataLabel`	`string`	-	Tekst die wordt getoond in de standaard `.mv-nodata`-overlay. Wordt genegeerd wanneer `suppressDefaultOverlay` `true` is.
`suppressDefaultOverlay`	`boolean`	`false`	Voorkomt dat de engine zijn eigen laad-/geen-data-node injecteert. Gebruik dit wanneer een framework-wrapper (bijv. de `LineChart` van `@michi-vz/react`) in plaats daarvan `isLoadingComponent` / `isNodataComponent` als React-overlay rendert. De host wordt nooit unmount - de overlay wordt er alleen bovenop gelegd.

Gedrag van de React-wrapper

De LineChart van @michi-vz/react stelt automatisch suppressDefaultOverlay in en rendert isLoadingComponent / isNodataComponent als een gepositioneerde React-node boven de host van het diagram. De DOM van het diagram is altijd gemount, dus isNodataComponent wordt ook bij lege data nog altijd geactiveerd, zelfs zonder aangepast predicaat.

Lettertypefamilie

fontFamily stelt de CSS custom property --michi-vz-font-family in op het host-element; deze wordt gelezen door zowel de SVG-tekstrenderer als de getComputedStyle-probe van canvas. Het lettertype moet al door de pagina geladen zijn - er wordt geen lettertype ingebed.

ChartContext / legendData

onChartDataProcessed ontvangt een LineChartContext die BaseChartContext uitbreidt. De basis bevat nu een legendData-veld:

interface LegendItem {
  label: string;         // series label as it appears in dataSet
  color: string;         // resolved colour at the time of processing
  order: number;         // appearance order (legend slot index)
  disabled?: boolean;    // true when the label is currently hidden
  dataLabelSafe?: string; // sanitizeForClassName(label) - the CSS hook the canvas colour probe matches
}

interface BaseChartContext {
  // ... existing fields ...
  legendData?: LegendItem[]; // populated by LineChart; treat absence as []
}

legendData is de canonieke payload voor kleurautoriteiten aan de kant van de consument. Een framework-wrapper die zijn eigen kleur-CSS aanstuurt (bijv. useChartUtils van thd MonitorV2) leest bij elke aanroep van onChartDataProcessed legendData[].{label, dataLabelSafe, color, disabled} en genereert per label stroke/fill-regels die het data-label-safe-attribuut targeten. Dit maakt het niet langer nodig om colorsMapping te kruisverwijzen met de volgorde van de series.

Gebeurtenissen

Het webcomponent verzendt deze bubbelende CustomEvents (de engine biedt dezelfde functionaliteit via de on*-callbacks in de tabel hierboven):

Gebeurtenis	Detail	Wordt geactiveerd wanneer
`michi-vz:highlight`	`string[]`	de hover-markering verandert
`michi-vz:colormapping`	`Record<string, string>`	een kleurmapping wordt gegenereerd
`michi-vz:dataprocessed`	`ChartContext`	data (opnieuw) wordt verwerkt
`michi-vz:datawarning`	`DataWarning[]`	invoerwaarschuwingen worden gedetecteerd

getContext()

mountLineChart(el, props).getContext() retourneert een renderer-onafhankelijke LineChartContext (gestructureerde statistieken + een deterministische samenvatting in gewone taal + een a11y-tabel). Zie LLM-context.

Bron

Eigenschappen zijn getypeerd als LineChartProps in @michi-vz/core.

Lijndiagram API ​

Import ​

Eigenschappen ​

Raster- en asweergave ​

Laad- en 'geen data'-status ​

Lettertypefamilie ​

ChartContext / legendData ​

Gebeurtenissen ​

getContext() ​

Bron ​