Symboolkaart API

Een symbool-/bellenkaart waarvan overlappingen worden opgelost door een krachtsimulatie: je geeft lng/lat per item op, een eenmalige simulatie duwt overlappende cirkels uit elkaar - zie de Symboolkaart-demo.

Import

Web Component

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

Vanilla JS

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

const chart = mountSymbolMapChart(el, props);

React

import { SymbolMapChart } from "@michi-vz/react/symbol-map-chart";

Vue

import { SymbolMapChart } from "@michi-vz/vue/symbol-map-chart";

Svelte

import { symbolMapChart } from "@michi-vz/svelte/symbol-map-chart";

Angular

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

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*	SymbolMapDataItem[]	-	Array of symbols; each supplies its own lng/lat (core bundles no coordinate table).
geography	GeoJSON.FeatureCollection | GeoFeatureItem[]	-	OPTIONAL muted backdrop landmass (new capability - the legacy chart never drew one). A full GeoJSON FeatureCollection or a pre-normalized `GeoFeatureItem[]`, same contract as `ChoroplethMapChartProps.geography`. Omit for the legacy chart's dot-only look (the default).
title	string	-	Optional chart title rendered above the plot
projection	GeoProjectionName	-	d3-geo / d3-geo-projection projection (default "geoMercator", matching the legacy chart). With no `geography`, the projection is used UNTUNED (bare `factory()`, no translate/scale/rotate/center) and the projected point extent is rescaled to fill the plot - see the chart's docs page. With `geography` supplied, the SAME tuned dispatch as ChoroplethMapChart is used instead, so the backdrop and the symbols share one consistent geographic framing.
projectionConfig	GeoProjectionConfig	-	Fine-tunes the projection; only consulted when `geography` is supplied (see `projection`).
radiusRange	[number, number]	DEFAULT_RADIUS_RANGE	[min, max] circle radius in px (default [3, 70], the legacy `circleRange`). Mapped from the value domain via `buildSymbolMapRadiusScale`, whose domain is the TRUE combined extent of every item's `value` and `valueSecond` - DELIBERATELY NOT legacy Chart.js's own domain formula, which was defective (`[min(primaryMin, secondaryMax), max(primaryMin, secondaryMax)]` silently drops the primary max and secondary min). Relative circle sizes will differ from the legacy chart whenever `value` and `valueSecond` ranges diverge - see `symbolMap/scales.ts`'s `buildSymbolMapRadiusScale` for the worked example and the pinned regression test.
radiusVisibleMin	number	-	Hides items whose RAW `value` is <= this threshold (and, when `valueSecond` is set, whose `valueSecond` is also < this threshold) BEFORE the force layout runs - ported from the legacy chart's own filter, which compares the raw value/valueSecond, not the scaled radius. Omit to show every located item.
positionMode	"force" | "precise" | "honeycomb"	"force"	How symbols are placed: "force" (default) runs a one-shot de-overlap simulation that pulls colliding circles apart, while "precise" keeps every symbol at its exact projected lng/lat (overlaps allowed). - "force": a one-shot de-overlap simulation pulls colliding circles apart - readable for dense data, but symbols DRIFT from their true lng/lat (on small plots the drift can be large). Avoid it when the audience will read exact geographic position off the chart: a symbol drawn over the wrong country is a cartographic-accuracy problem and can be politically sensitive. - "precise": every symbol stays at its exact projected lng/lat; overlapping circles are allowed. Prefer this whenever a `geography` backdrop is shown, since a visible landmass invites reading positions literally.
shape	"circle" | "hexagon"	"circle"	Mark geometry: "circle" (default) or a "hexagon" whose CIRCUMRADIUS is the mark radius - collision, hit-testing and label fitting stay circle-based on `radius`, only the painted outline changes. Orientation follows `honeycomb.orientation` (default "flat"). Pair with `positionMode: "honeycomb"` for tessellating tiles.
honeycomb	{ radius?: number; gap?: number; orientation?: "flat" | "pointy"; placement?: "first" | "geographic"; reserve?: "valued" | "all"; }	-	Lattice settings for `positionMode: "honeycomb"`: tile circumradius in px (default 11), gap between tile edges in px (default 2), and orientation (default "flat" = a flat edge on top, columns offset; "pointy" = a vertex on top, rows offset). Also sets the hexagon outline orientation for `shape`. - `placement` (default "first"): how a crowded cell is shared. "first" resolves collisions in `dataSet` order with a fixed ring walk (stable, but a displaced tile can land on the wrong side of its neighbours). "geographic" keeps neighbours in their real order: the tile nearest a cell's centre keeps it, a displaced tile takes the free cell nearest its true position, and a repair pass swaps or nudges neighbours that read east-for-west or north-for-south. Independent of `dataSet` order; the neighbouring pairs still in the wrong order are counted in `stats.outOfOrderCount` (measured for every placement) and, with "geographic" only, reported as a `layout-out-of-order` warning. - `reserve` (default "valued"): which tiles claim a cell. "valued" = only tiles with a `value` (no-data tiles never push real data around); "all" = every tile, so the layout does not change when the values do (a map that switches between products or years). Tiles removed by `disabledItems` or `radiusVisibleMin` take no part in the layout either way.
fit	"none" | "width"	"none"	How the chart fits its container (default "none"). - "none": the chart is drawn at exactly `width` x `height` pixels (today). - "width": the chart is LAID OUT once at `width` x `height` (the design size) and the drawing is scaled to the container's width, keeping the aspect ratio, never larger than `width`. Positions do not change when the window resizes - useful for a tile map whose honeycomb layout should not reshuffle with the screen size. The svg renderer uses a `viewBox`; canvas and webgpu scale their layer and map the pointer back to design coordinates. The tooltip stays at screen size next to the cursor.
colorScale	{ domain: number[]; range: string[] }	-	Value-driven colour encoding: a resolved hex `range` keyed to a numeric `domain`, built into a d3 `scaleThreshold` (values outside the domain clamp to the first/last colour). Precedence: `colorsMapping[label]` > `colorScale(value)` > the item's `color` > the palette. Same contract as ChoroplethMapChart's `colorScale`. With a colorScale the colour IS the encoding, so marks paint at full opacity (the legacy value->alpha ramp applies only without one).
noDataColor	string	DEFAULT_NO_DATA_COLOR	Fill for items without a `value` (default `#d2d7dd`, ChoroplethMap's no-data grey). Pass "transparent" to hide them while keeping their tooltip target.
markers	SymbolMapMarker[]	-	Decorative pins drawn above the symbols (a home location, an office). Anchored tip-down at the projected lng/lat; never laid out or hit-tested; no tooltip. Built-in map-pin glyph, or pass your own `path` + `pathSize`.
geographyColor	string	DEFAULT_GEOGRAPHY_COLOR	Fill for the optional backdrop `geography` (default `#eef1f5`, a muted neutral).
strokeColor	string	DEFAULT_STROKE_COLOR	Border colour for the optional backdrop `geography` (default `#d7dce3`).
strokeWidth	number	1	Border width for the optional backdrop `geography`, in px (default 1).
showLabels	boolean	true	Draw a fitted label inside each circle when it is large enough (default true).
isLoading	boolean	-	Loading overlay (stale symbols hidden while true)
isNodata	boolean | ((dataSet: SymbolMapDataItem[] | 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
tooltipFormatter	(d: SymbolMapDataItem) => string	-	Formats the tooltip for a hovered symbol.
labelFormatter	(d: SymbolMapDataItem) => string	-	Text drawn inside a symbol when it is large enough (default: the label). Receives the item with its resolved lng/lat, so a share or a value can sit next to the name; the text is still fitted to the circle (ellipsis past the width).
onSymbolClick	(d: SymbolMapDataItem, event: MouseEvent) => void	-	Called when a symbol is clicked (svg marks and the canvas/webgpu hit-test alike), with the same item the tooltip formatter receives and the mouse event. The click still pins the tooltip; use this to navigate or select from the symbol itself.
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	520	Chart height in pixels
margin	Margin	{ top: 40, right: 10, bottom: 10, left: 10 }	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, ...)

Gebeurtenissen

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

Gebeurtenis	Detail	Treedt op wanneer
michi-vz:highlight	string[]	de highlight bij hover verandert
michi-vz:colormapping	Record<string, string>	er een kleurtoewijzing wordt gegenereerd
michi-vz:dataprocessed	ChartContext	gegevens worden (opnieuw) verwerkt
michi-vz:datawarning	DataWarning[]	waarschuwingen worden gedetecteerd (ontbrekende/ongeldige lng-lat, negatieve waarden, dubbele ids)
michi-vz:symbolclick	SymbolMapDataItem	er wordt op een symbool geklikt (de onSymbolClick-callback)

getContext()

mountSymbolMapChart(el, props).getContext() retourneert een renderer-onafhankelijke SymbolMapChartContext: stats.locatedCount / visibleCount / hiddenCount (uitgesloten door radiusVisibleMin) / invalidCount (verworpen wegens ongeldige coördinaten) / valueDomain / min / max / displacedCount / outOfOrderCount (alleen honeycomb, gemeten voor elke placement), een symbols[]-array (één rij per zichtbaar item: id, label, value, valueSecond, radius, radiusSecond, color, x, y), de opgeloste projection-naam, een deterministische samenvatting in gewone taal, en een a11yTable. Zie LLM-context.

Bron

Props zijn getypeerd als SymbolMapChartProps in @michi-vz/core.