From 0540c919e0682b418ce770d6481856fa909c11f8 Mon Sep 17 00:00:00 2001
From: Max Kohler <hello@maxkohler.com>
Date: Sun, 12 Oct 2025 14:39:13 +0200
Subject: [PATCH 1/3] Block out feature

---
 components/package.json                       |   1 +
 components/src/index.js                       |   2 +
 .../src/maplibre/ArrowSource/ArrowSource.mdx  |  10 ++
 .../ArrowSource/ArrowSource.stories.svelte    |  97 ++++++++++++
 .../maplibre/ArrowSource/ArrowSource.svelte   | 138 ++++++++++++++++++
 components/src/maplibre/ArrowSource/index.js  |   2 +
 package-lock.json                             |   7 +
 7 files changed, 257 insertions(+)
 create mode 100644 components/src/maplibre/ArrowSource/ArrowSource.mdx
 create mode 100644 components/src/maplibre/ArrowSource/ArrowSource.stories.svelte
 create mode 100644 components/src/maplibre/ArrowSource/ArrowSource.svelte
 create mode 100644 components/src/maplibre/ArrowSource/index.js

diff --git a/components/package.json b/components/package.json
index e517735a..84331440 100644
--- a/components/package.json
+++ b/components/package.json
@@ -33,6 +33,7 @@
 	"dependencies": {
 		"@maplibre/maplibre-gl-geocoder": "^1.9.1",
 		"@maplibre/maplibre-gl-inspect": "^1.7.1",
+		"bitmap-sdf": "^1.0.4",
 		"maplibre-gl": "^5.7.0",
 		"svelte-select": "^5.8.3"
 	},
diff --git a/components/src/index.js b/components/src/index.js
index 347844e9..140128dd 100644
--- a/components/src/index.js
+++ b/components/src/index.js
@@ -29,6 +29,8 @@ export { default as ScaleControl } from './maplibre/ScaleControl/ScaleControl.sv
 export { default as VectorLayer } from './maplibre/VectorLayer/VectorLayer.svelte';
 export { default as VectorTileSource } from './maplibre/VectorTileSource/VectorTileSource.svelte';
 export { default as GeoJSONSource } from './maplibre/GeoJSONSource/GeoJSONSource.svelte';
+export { default as ArrowSource } from './maplibre/ArrowSource/ArrowSource.svelte';
+export { default as MapSource } from './maplibre/Source/MapSource.svelte';
 export { default as Tooltip } from './maplibre/Tooltip/Tooltip.svelte';
 export { default as WithLinkLocation } from './maplibre/WithLinkLocation/WithLinkLocation.svelte';
 
diff --git a/components/src/maplibre/ArrowSource/ArrowSource.mdx b/components/src/maplibre/ArrowSource/ArrowSource.mdx
new file mode 100644
index 00000000..48861ac9
--- /dev/null
+++ b/components/src/maplibre/ArrowSource/ArrowSource.mdx
@@ -0,0 +1,10 @@
+import { Story, Meta, Primary, Controls, Stories } from '@storybook/addon-docs/blocks';
+
+import * as ArrowSourceStories from './ArrowSource.stories.svelte';
+
+<Meta of={ArrowSourceStories} />
+
+# ArrowSource
+
+<Controls />
+
diff --git a/components/src/maplibre/ArrowSource/ArrowSource.stories.svelte b/components/src/maplibre/ArrowSource/ArrowSource.stories.svelte
new file mode 100644
index 00000000..ec4f23e8
--- /dev/null
+++ b/components/src/maplibre/ArrowSource/ArrowSource.stories.svelte
@@ -0,0 +1,97 @@
+<script context="module" lang="ts">
+	import { defineMeta } from '@storybook/addon-svelte-csf';
+	import Map from '../Map/Map.svelte';
+	import ArrowSource from './ArrowSource.svelte';
+	import VectorLayer from '../VectorLayer/VectorLayer.svelte';
+	import DesignTokens from '../../DesignTokens/DesignTokens.svelte';
+	import InspectControl from '../InspectControl/InspectControl.svelte';
+	import AttributionControl from '../AttributionControl/AttributionControl.svelte';
+
+	import { SWRDataLabLight } from '../MapStyle';
+	import { tokens } from '../../DesignTokens';
+
+	const { Story } = defineMeta({
+		title: 'Maplibre/Source/ArrowSource',
+		component: ArrowSource
+	});
+</script>
+
+<Story asChild name="Default">
+	<DesignTokens theme="light">
+		<div class="container">
+			<Map
+				showDebug={true}
+				style={SWRDataLabLight()}
+				initialLocation={{
+					lng: -84.783,
+					lat: 15.623,
+					zoom: 3.39,
+					pitch: 0
+				}}
+			>
+				<ArrowSource
+					id="demo"
+					attribution="Demo attribution"
+					arrows={[
+						{
+							width: 10,
+							a: [-80.1, 11.3],
+							b: [-84.783, 15.6],
+							c: [-81, 14.6]
+						},
+						{
+							width: 15,
+							a: [-71.1, 11.3],
+							b: [-75.783, 15.6],
+							c: [-75, 12.6]
+						}
+					]}
+				/>
+				<InspectControl />
+				<AttributionControl />
+				<VectorLayer
+					sourceId="demo"
+					id="arrow-tails"
+					filter={['==', 'kind', 'arrow-tail']}
+					type="line"
+					paint={{
+						'line-gradient': [
+							'interpolate',
+							['linear'],
+							['line-progress'],
+							0,
+							'transparent',
+							0.4,
+							tokens.shades.red.base
+						],
+						'line-width': ['get', 'width']
+					}}
+				/>
+				<VectorLayer
+					sourceId="demo"
+					id="arrow-heads"
+					filter={['==', 'kind', 'arrow-head']}
+					type="symbol"
+					paint={{
+						'icon-color': tokens.shades.red.base
+					}}
+					layout={{
+						'icon-image': 'arrow-head',
+						'icon-anchor': 'top',
+						'icon-offset': [0, -2],
+						'icon-rotate': ['get', 'angle'],
+						'icon-overlap': 'always',
+						'icon-size': ['get', 'size']
+					}}
+				/>
+			</Map>
+		</div>
+	</DesignTokens>
+</Story>
+
+<style>
+	.container {
+		width: 100%;
+		height: 600px;
+	}
+</style>
diff --git a/components/src/maplibre/ArrowSource/ArrowSource.svelte b/components/src/maplibre/ArrowSource/ArrowSource.svelte
new file mode 100644
index 00000000..252fbebd
--- /dev/null
+++ b/components/src/maplibre/ArrowSource/ArrowSource.svelte
@@ -0,0 +1,138 @@
+<script lang="ts">
+	// See: https://maplibre.org/maplibre-gl-js/docs/API/classes/GeoJSONSource/
+	import { type GeoJSONSourceSpecification } from 'maplibre-gl';
+	import MapSource from '../Source/MapSource.svelte';
+	import { getMapContext } from '../context.svelte.js';
+	import { onDestroy } from 'svelte';
+	import { default as calcSdf } from 'bitmap-sdf';
+	const { map, styleLoaded } = $derived(getMapContext());
+
+	interface ArrowSpec {
+		a: [number, number]; // p0
+		b: [number, number]; // p2
+		c: [number, number]; // p1
+		width?: number;
+		debug?: boolean;
+	}
+
+	interface ArrowSourceProps {
+		id: string;
+		attribution: string;
+		arrows: ArrowSpec[];
+	}
+
+	const { id, arrows = [], attribution = '' }: ArrowSourceProps = $props();
+
+	interface JsonArrow {
+		width: number;
+		points: [number, number][];
+	}
+
+	const makeArrowHead = (width: number, height: number) => {
+		const canvas = document.createElement('canvas');
+		const c = canvas.getContext('2d');
+		const w = Math.round(width);
+		const h = Math.round(height);
+		canvas.width = w;
+		canvas.height = h;
+		if (c) {
+			c.fillStyle = 'white';
+			c.beginPath();
+			c.moveTo(0, 0);
+			c.lineTo(w / 2, h);
+			c.lineTo(w, 0);
+			c.fill();
+
+			const sdf = calcSdf(canvas);
+			const data = new Uint8ClampedArray(w * h * 4);
+			for (let i = 0; i < w; i++) {
+				for (let j = 0; j < h; j++) {
+					data[j * w * 4 + i * 4 + 0] = sdf[j * w + i] * 255;
+					data[j * w * 4 + i * 4 + 1] = sdf[j * w + i] * 255;
+					data[j * w * 4 + i * 4 + 2] = sdf[j * w + i] * 255;
+					data[j * w * 4 + i * 4 + 3] = sdf[j * w + i] * 255;
+				}
+			}
+			return new ImageData(data, w, h);
+		}
+	};
+
+	const arrowsToJson = (arrows: JsonArrow[] = []) => {
+		const tails = arrows.map((a) => {
+			return {
+				type: 'Feature',
+				geometry: { type: 'LineString', coordinates: a.points },
+				properties: { width: a.width, kind: 'arrow-tail' }
+			};
+		});
+
+		const heads = arrows.map((a) => {
+			const bc = a.points[a.points.length - 1][0] - a.points[a.points.length - 2][0];
+			const ac = a.points[a.points.length - 1][1] - a.points[a.points.length - 2][1];
+			const ba = Math.sqrt(bc * bc + ac * ac);
+			const angle = Math.asin(bc / ba) * (180 / Math.PI) - 180;
+			return {
+				type: 'Feature',
+				geometry: {
+					type: 'Point',
+					coordinates: a.points[a.points.length - 1]
+				},
+				properties: { kind: 'arrow-head', angle, size: (a.width / 20) * 1.35 }
+			};
+		});
+
+		return {
+			type: 'FeatureCollection',
+			features: [...tails, ...heads]
+		} as GeoJSON.GeoJSON;
+	};
+
+	const quadraticToPoints = (
+		a: [number, number],
+		b: [number, number],
+		c: [number, number],
+		pointCount = 10
+	) => {
+		// B(t) = (1-t)[(1-t)P0 + tP1] + t[(1-t)P1+tP2]
+		// This is a naive implementation but good enough for now
+		// See: https://en.wikipedia.org/wiki/B%C3%A9zier_curve#Quadratic_B%C3%A9zier_curves
+		// https://bit-101.com/blog/posts/2024-09-29/evenly-placed-points-on-bezier-curves
+
+		let points = [];
+		for (let n = 0; n < pointCount; n++) {
+			const t = n / pointCount;
+			const x = (1 - t) * ((1 - t) * a[0] + t * c[0]) + t * ((1 - t) * c[0] + t * b[0]);
+			const y = (1 - t) * ((1 - t) * a[1] + t * c[1]) + t * ((1 - t) * c[1] + t * b[1]);
+			points.push([x.toFixed(4), y.toFixed(4)]);
+		}
+
+		return [...points, b] as [number, number][];
+	};
+	$effect(() => {
+		const s = 6.5;
+		const ah = makeArrowHead(10 * s, 10 * s * 0.75, 'black');
+		if (map && styleLoaded && ah) {
+			map.addImage('arrow-head', ah, { sdf: true, pixelRatio: 2 });
+		}
+	});
+	onDestroy(() => {
+		if (map && styleLoaded) {
+			map.removeImage('arrow-head');
+		}
+	});
+	const ar = arrows.map((a) => {
+		return { width: a.width || 10, points: quadraticToPoints(a.a, a.b, a.c, 20) };
+	});
+
+	const data = arrowsToJson(ar);
+
+	const sourceSpec: GeoJSONSourceSpecification = {
+		type: 'geojson',
+		lineMetrics: true,
+		maxzoom: 24,
+		attribution,
+		data
+	};
+</script>
+
+<MapSource {id} {sourceSpec} />
diff --git a/components/src/maplibre/ArrowSource/index.js b/components/src/maplibre/ArrowSource/index.js
new file mode 100644
index 00000000..cadb874e
--- /dev/null
+++ b/components/src/maplibre/ArrowSource/index.js
@@ -0,0 +1,2 @@
+import ArrowSource from './ArrowSource.svelte';
+export default ArrowSource;
diff --git a/package-lock.json b/package-lock.json
index 1ff684bb..bff0924b 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -22,6 +22,7 @@
 			"dependencies": {
 				"@maplibre/maplibre-gl-geocoder": "^1.9.1",
 				"@maplibre/maplibre-gl-inspect": "^1.7.1",
+				"bitmap-sdf": "^1.0.4",
 				"maplibre-gl": "^5.7.0",
 				"svelte-select": "^5.8.3"
 			},
@@ -6537,6 +6538,12 @@
 				"url": "https://github.com/sponsors/sindresorhus"
 			}
 		},
+		"node_modules/bitmap-sdf": {
+			"version": "1.0.4",
+			"resolved": "https://registry.npmjs.org/bitmap-sdf/-/bitmap-sdf-1.0.4.tgz",
+			"integrity": "sha512-1G3U4n5JE6RAiALMxu0p1XmeZkTeCwGKykzsLTCqVzfSDaN6S7fKnkIkfejogz+iwqBWc0UYAIKnKHNN7pSfDg==",
+			"license": "MIT"
+		},
 		"node_modules/bottleneck": {
 			"version": "2.19.5",
 			"resolved": "https://registry.npmjs.org/bottleneck/-/bottleneck-2.19.5.tgz",

From 90d611c2e8dcfb21bc6b11ddcdf708720a49871f Mon Sep 17 00:00:00 2001
From: Max Kohler <hello@maxkohler.com>
Date: Sun, 12 Oct 2025 16:46:06 +0200
Subject: [PATCH 2/3] Iterate

---
 .../src/maplibre/ArrowSource/ArrowSource.mdx  |  3 ++
 .../maplibre/ArrowSource/ArrowSource.svelte   | 39 +++++++++++--------
 2 files changed, 25 insertions(+), 17 deletions(-)

diff --git a/components/src/maplibre/ArrowSource/ArrowSource.mdx b/components/src/maplibre/ArrowSource/ArrowSource.mdx
index 48861ac9..62fa8492 100644
--- a/components/src/maplibre/ArrowSource/ArrowSource.mdx
+++ b/components/src/maplibre/ArrowSource/ArrowSource.mdx
@@ -8,3 +8,6 @@ import * as ArrowSourceStories from './ArrowSource.stories.svelte';
 
 <Controls />
 
+## Notes
+- https://github.com/dy/bitmap-sdf
+- https://github.com/maplibre/maplibre-gl-js/issues/5037
diff --git a/components/src/maplibre/ArrowSource/ArrowSource.svelte b/components/src/maplibre/ArrowSource/ArrowSource.svelte
index 252fbebd..662a51e5 100644
--- a/components/src/maplibre/ArrowSource/ArrowSource.svelte
+++ b/components/src/maplibre/ArrowSource/ArrowSource.svelte
@@ -1,10 +1,11 @@
 <script lang="ts">
-	// See: https://maplibre.org/maplibre-gl-js/docs/API/classes/GeoJSONSource/
 	import { type GeoJSONSourceSpecification } from 'maplibre-gl';
+	import { default as calcSdf } from 'bitmap-sdf';
+
 	import MapSource from '../Source/MapSource.svelte';
 	import { getMapContext } from '../context.svelte.js';
 	import { onDestroy } from 'svelte';
-	import { default as calcSdf } from 'bitmap-sdf';
+
 	const { map, styleLoaded } = $derived(getMapContext());
 
 	interface ArrowSpec {
@@ -23,11 +24,6 @@
 
 	const { id, arrows = [], attribution = '' }: ArrowSourceProps = $props();
 
-	interface JsonArrow {
-		width: number;
-		points: [number, number][];
-	}
-
 	const makeArrowHead = (width: number, height: number) => {
 		const canvas = document.createElement('canvas');
 		const c = canvas.getContext('2d');
@@ -57,16 +53,21 @@
 		}
 	};
 
+	interface JsonArrow {
+		width: number;
+		points: [number, number][];
+	}
+
 	const arrowsToJson = (arrows: JsonArrow[] = []) => {
-		const tails = arrows.map((a) => {
+		const tails = arrows.map((a, i) => {
 			return {
 				type: 'Feature',
 				geometry: { type: 'LineString', coordinates: a.points },
-				properties: { width: a.width, kind: 'arrow-tail' }
+				properties: { width: a.width, kind: 'arrow-tail', id: i }
 			};
 		});
 
-		const heads = arrows.map((a) => {
+		const heads = arrows.map((a, i) => {
 			const bc = a.points[a.points.length - 1][0] - a.points[a.points.length - 2][0];
 			const ac = a.points[a.points.length - 1][1] - a.points[a.points.length - 2][1];
 			const ba = Math.sqrt(bc * bc + ac * ac);
@@ -77,7 +78,12 @@
 					type: 'Point',
 					coordinates: a.points[a.points.length - 1]
 				},
-				properties: { kind: 'arrow-head', angle, size: (a.width / 20) * 1.35 }
+				properties: {
+					kind: 'arrow-head',
+					angle,
+					size: (a.width / 20) * 1.35,
+					id: arrows.length + i
+				}
 			};
 		});
 
@@ -110,13 +116,13 @@
 	};
 	$effect(() => {
 		const s = 6.5;
-		const ah = makeArrowHead(10 * s, 10 * s * 0.75, 'black');
+		const ah = makeArrowHead(10 * s, 10 * s * 0.75);
 		if (map && styleLoaded && ah) {
 			map.addImage('arrow-head', ah, { sdf: true, pixelRatio: 2 });
 		}
 	});
 	onDestroy(() => {
-		if (map && styleLoaded) {
+		if (map) {
 			map.removeImage('arrow-head');
 		}
 	});
@@ -124,14 +130,13 @@
 		return { width: a.width || 10, points: quadraticToPoints(a.a, a.b, a.c, 20) };
 	});
 
-	const data = arrowsToJson(ar);
-
 	const sourceSpec: GeoJSONSourceSpecification = {
 		type: 'geojson',
-		lineMetrics: true,
 		maxzoom: 24,
 		attribution,
-		data
+		promoteId: 'id',
+		lineMetrics: true,
+		data: arrowsToJson(ar)
 	};
 </script>
 

From 27104b2e329cebdde1b7d6c6f7f7c1ffdd88c66c Mon Sep 17 00:00:00 2001
From: Max Kohler <hello@maxkohler.com>
Date: Sun, 12 Oct 2025 17:06:14 +0200
Subject: [PATCH 3/3] Iterate docs

---
 .../src/maplibre/ArrowSource/ArrowSource.mdx  | 57 ++++++++++++++++++-
 .../maplibre/ArrowSource/ArrowSource.svelte   |  7 +--
 2 files changed, 58 insertions(+), 6 deletions(-)

diff --git a/components/src/maplibre/ArrowSource/ArrowSource.mdx b/components/src/maplibre/ArrowSource/ArrowSource.mdx
index 62fa8492..a755dbe8 100644
--- a/components/src/maplibre/ArrowSource/ArrowSource.mdx
+++ b/components/src/maplibre/ArrowSource/ArrowSource.mdx
@@ -6,8 +6,61 @@ import * as ArrowSourceStories from './ArrowSource.stories.svelte';
 
 # ArrowSource
 
+Source component for creating smooth ([quadratic bezier](https://en.wikipedia.org/wiki/B%C3%A9zier_curve#Quadratic_B%C3%A9zier_curves)) vector arrows [like these](https://www.nytimes.com/interactive/2025/10/09/world/americas/drug-trafficking-venezuela.html?searchResultPosition=4).
+
 <Controls />
 
+## Usage
+
+ArrowSource  takes an `arrow` prop of shape `ArrowSpec[]`:
+
+```js
+interface ArrowSpec {
+  a: [number, number]; // Start point
+  b: [number, number]; // End point
+  c: [number, number]; // Control point
+  width?: number;
+}
+
+```
+
+Use regular VectorLayers to render the arrows:
+
+```jsx
+<Map>
+  <ArrowSource
+    id="demo"
+    attribution="Demo attribution"
+    arrows={[
+      {width: 10, a: [-80.1, 11.3], b: [-84.783, 15.6], c: [-81, 14.6]},
+      {width: 15, a: [-71.1, 11.3], b: [-75.783, 15.6], c: [-75, 12.6]}
+    ]}/>
+  <VectorLayer
+    id="arrow-tails"
+    type="line"
+    sourceId="demo"
+    filter={['==', 'kind', 'arrow-tail']}
+    paint={{
+      'line-gradient': ['interpolate',['linear'],['line-progress'],0,'transparent',0.4"red"],
+      'line-width': ['get', 'width']
+    }}/>
+    <VectorLayer
+      id="arrow-heads"
+      type="symbol"
+      sourceId="demo"
+      filter={['==', 'kind', 'arrow-head']}
+      layout={{
+        'icon-image': 'arrow-head',
+        'icon-anchor': 'top',
+        'icon-offset': [0, -2],
+        'icon-rotate': ['get', 'angle'],
+        'icon-overlap': 'always',
+        'icon-size': ['get', 'size']
+      }}
+      paint={{'icon-color': "red"}}/>
+</Map>
+```
+
 ## Notes
-- https://github.com/dy/bitmap-sdf
-- https://github.com/maplibre/maplibre-gl-js/issues/5037
+- [https://github.com/dy/bitmap-sdf](https://github.com/dy/bitmap-sdf)
+- [https://github.com/maplibre/maplibre-gl-js/issues/5037](https://github.com/maplibre/maplibre-gl-js/issues/5037)
diff --git a/components/src/maplibre/ArrowSource/ArrowSource.svelte b/components/src/maplibre/ArrowSource/ArrowSource.svelte
index 662a51e5..4068e88b 100644
--- a/components/src/maplibre/ArrowSource/ArrowSource.svelte
+++ b/components/src/maplibre/ArrowSource/ArrowSource.svelte
@@ -9,11 +9,10 @@
 	const { map, styleLoaded } = $derived(getMapContext());
 
 	interface ArrowSpec {
-		a: [number, number]; // p0
-		b: [number, number]; // p2
-		c: [number, number]; // p1
+		a: [number, number];
+		b: [number, number];
+		c: [number, number];
 		width?: number;
-		debug?: boolean;
 	}
 
 	interface ArrowSourceProps {