From 97728345fd34c6d4179603e37a3674408b6b25de Mon Sep 17 00:00:00 2001
From: Max Kohler <hello@maxkohler.com>
Date: Wed, 4 Mar 2026 15:37:45 +0100
Subject: [PATCH 01/10] Implement feature, update stories

---
 .../MapStyle/SWRDataLabLight.stories.svelte   |  4 +++-
 .../maplibre/Tooltip/Tooltip.stories.svelte   | 12 +++++++++---
 .../VectorLayer/VectorLayer.stories.svelte    |  8 ++++++--
 .../VectorTileSource/VectorTileSource.mdx     |  2 +-
 .../VectorTileSource.stories.svelte           |  4 +++-
 .../VectorTileSource/VectorTileSource.svelte  | 19 ++++++++++++++-----
 6 files changed, 36 insertions(+), 13 deletions(-)

diff --git a/components/src/maplibre/MapStyle/SWRDataLabLight.stories.svelte b/components/src/maplibre/MapStyle/SWRDataLabLight.stories.svelte
index 3c7bfa00..0f489ae6 100644
--- a/components/src/maplibre/MapStyle/SWRDataLabLight.stories.svelte
+++ b/components/src/maplibre/MapStyle/SWRDataLabLight.stories.svelte
@@ -97,7 +97,9 @@
 				>
 					<VectorTileSource
 						id="demo-source"
-						url={`https://static.datenhub.net/data/p118_correctiv_waermewende/heating_merged_2.versatiles?{z}/{x}/{y}`}
+						tiles={[
+							`https://static.datenhub.net/data/p118_correctiv_waermewende/heating_merged_2.versatiles?{z}/{x}/{y}`
+						]}
 						attribution="Demo attribution"
 					/>
 
diff --git a/components/src/maplibre/Tooltip/Tooltip.stories.svelte b/components/src/maplibre/Tooltip/Tooltip.stories.svelte
index 106588a6..d53750f8 100644
--- a/components/src/maplibre/Tooltip/Tooltip.stories.svelte
+++ b/components/src/maplibre/Tooltip/Tooltip.stories.svelte
@@ -33,7 +33,9 @@
 			>
 				<VectorTileSource
 					id="ev-infra-source"
-					url={`https://static.datenhub.net/data/p108_e_auto_check/ev_infra_merged.versatiles?{z}/{x}/{y}`}
+					tiles={[
+						`https://static.datenhub.net/data/p108_e_auto_check/ev_infra_merged.versatiles?{z}/{x}/{y}`
+					]}
 				/>
 				<VectorLayer
 					sourceId="ev-infra-source"
@@ -103,7 +105,9 @@
 			>
 				<VectorTileSource
 					id="ev-infra-source"
-					url={`https://static.datenhub.net/data/p108_e_auto_check/ev_infra_merged.versatiles?{z}/{x}/{y}`}
+					tiles={[
+						`https://static.datenhub.net/data/p108_e_auto_check/ev_infra_merged.versatiles?{z}/{x}/{y}`
+					]}
 				/>
 				<VectorLayer
 					sourceId="ev-infra-source"
@@ -187,7 +191,9 @@
 			>
 				<VectorTileSource
 					id="ev-infra-source"
-					url={`https://static.datenhub.net/data/p108_e_auto_check/ev_infra_merged.versatiles?{z}/{x}/{y}`}
+					tiles={[
+						`https://static.datenhub.net/data/p108_e_auto_check/ev_infra_merged.versatiles?{z}/{x}/{y}`
+					]}
 				/>
 				<VectorLayer
 					sourceId="ev-infra-source"
diff --git a/components/src/maplibre/VectorLayer/VectorLayer.stories.svelte b/components/src/maplibre/VectorLayer/VectorLayer.stories.svelte
index bd4989f5..3691ee0d 100644
--- a/components/src/maplibre/VectorLayer/VectorLayer.stories.svelte
+++ b/components/src/maplibre/VectorLayer/VectorLayer.stories.svelte
@@ -40,7 +40,9 @@
 			<Map showDebug={true} style={SWRDataLabLight()} cursor={hovered ? 'pointer' : ''}>
 				<VectorTileSource
 					id="ev-infra-source"
-					url={`https://static.datenhub.net/data/p108_e_auto_check/ev_infra_merged.versatiles?{z}/{x}/{y}`}
+					tiles={[
+						`https://static.datenhub.net/data/p108_e_auto_check/ev_infra_merged.versatiles?{z}/{x}/{y}`
+					]}
 				/>
 				<VectorLayer
 					onmousemove={handleMouseMove}
@@ -125,7 +127,9 @@
 			<Map showDebug={true} style={SWRDataLabLight()}>
 				<VectorTileSource
 					id="ev-infra-source"
-					url={`https://static.datenhub.net/data/p108_e_auto_check/ev_infra_merged.versatiles?{z}/{x}/{y}`}
+					tiles={[
+						`https://static.datenhub.net/data/p108_e_auto_check/ev_infra_merged.versatiles?{z}/{x}/{y}`
+					]}
 				/>
 				<VectorLayer
 					sourceId="ev-infra-source"
diff --git a/components/src/maplibre/VectorTileSource/VectorTileSource.mdx b/components/src/maplibre/VectorTileSource/VectorTileSource.mdx
index fb91ec27..8f188eae 100644
--- a/components/src/maplibre/VectorTileSource/VectorTileSource.mdx
+++ b/components/src/maplibre/VectorTileSource/VectorTileSource.mdx
@@ -11,7 +11,7 @@ Loads tiled vector data from a tileserver. Any mablibre-supported tileserver wil
 ```jsx
 <Map>
 	<VectorTileSource
-		url="https://static.datenhub.net/rent_merged.versatiles?{z}/{x}/{y}"
+		tiles={['https://static.datenhub.net/rent_merged.versatiles?{z}/{x}/{y}']}
 		id="chargers"
 	/>
 	<VectorLayer sourceId="chargers" />
diff --git a/components/src/maplibre/VectorTileSource/VectorTileSource.stories.svelte b/components/src/maplibre/VectorTileSource/VectorTileSource.stories.svelte
index 91a27177..b3bf47c1 100644
--- a/components/src/maplibre/VectorTileSource/VectorTileSource.stories.svelte
+++ b/components/src/maplibre/VectorTileSource/VectorTileSource.stories.svelte
@@ -19,7 +19,9 @@
 			<Map showDebug={true} style={SWRDataLabLight()}>
 				<VectorTileSource
 					id="ev-infra-source"
-					url={`https://static.datenhub.net/data/p108_e_auto_check/ev_infra_merged.versatiles?{z}/{x}/{y}`}
+					tiles={[
+						`https://static.datenhub.net/data/p108_e_auto_check/ev_infra_merged.versatiles?{z}/{x}/{y}`
+					]}
 					attribution="Demo attribution"
 				/>
 				<VectorLayer
diff --git a/components/src/maplibre/VectorTileSource/VectorTileSource.svelte b/components/src/maplibre/VectorTileSource/VectorTileSource.svelte
index 62761ac7..7ed05ef5 100644
--- a/components/src/maplibre/VectorTileSource/VectorTileSource.svelte
+++ b/components/src/maplibre/VectorTileSource/VectorTileSource.svelte
@@ -1,10 +1,11 @@
 <script lang="ts">
-	import { type SourceSpecification } from 'maplibre-gl';
+	import { type VectorSourceSpecification } from 'maplibre-gl';
 	import MapSource from '../Source/MapSource.svelte';
 
 	interface VectorTileSourceProps {
 		id: string;
-		url: string;
+		url?: string;
+		tiles?: string[];
 		minZoom?: number;
 		maxZoom?: number;
 		/**
@@ -13,11 +14,19 @@
 		attribution?: string;
 	}
 
-	const { minZoom = 0, maxZoom = 24, id, url, attribution = '' }: VectorTileSourceProps = $props();
+	const {
+		minZoom = 0,
+		maxZoom = 24,
+		id,
+		url = '',
+		tiles = [],
+		attribution = ''
+	}: VectorTileSourceProps = $props();
 
-	const sourceSpec: SourceSpecification = {
+	const sourceSpec: VectorSourceSpecification = {
 		type: 'vector',
-		tiles: [url],
+		url,
+		tiles,
 		maxzoom: maxZoom,
 		minzoom: minZoom,
 		attribution

From 53f7bbc900845b87626bde7d149cdd09f8f1033e Mon Sep 17 00:00:00 2001
From: Max Kohler <hello@maxkohler.com>
Date: Wed, 4 Mar 2026 16:19:21 +0100
Subject: [PATCH 02/10] Add url parameter story

Fails due to upstream bug
---
 .../VectorTileSource.stories.svelte           | 24 +++++++++++++++++++
 .../VectorTileSource/VectorTileSource.svelte  |  4 ++--
 2 files changed, 26 insertions(+), 2 deletions(-)

diff --git a/components/src/maplibre/VectorTileSource/VectorTileSource.stories.svelte b/components/src/maplibre/VectorTileSource/VectorTileSource.stories.svelte
index b3bf47c1..f36d1e05 100644
--- a/components/src/maplibre/VectorTileSource/VectorTileSource.stories.svelte
+++ b/components/src/maplibre/VectorTileSource/VectorTileSource.stories.svelte
@@ -41,6 +41,30 @@
 	</DesignTokens>
 </Story>
 
+<Story asChild name="tile json">
+	<DesignTokens theme="light">
+		<div class="container">
+			<Map showDebug={true} style={SWRDataLabLight()}>
+				<VectorTileSource
+					id="test-source"
+					url="https://tiles.versatiles.org/tiles/osm/tiles.json"
+				/>
+				<VectorLayer
+					sourceId="test-source"
+					sourceLayer="boundaries"
+					id="test-layer"
+					type="fill"
+					paint={{
+						'fill-color': 'purple',
+						'fill-opacity': 1
+					}}
+				/>
+				<AttributionControl position="bottom-left" />
+			</Map>
+		</div>
+	</DesignTokens>
+</Story>
+
 <style>
 	.container {
 		width: 100%;
diff --git a/components/src/maplibre/VectorTileSource/VectorTileSource.svelte b/components/src/maplibre/VectorTileSource/VectorTileSource.svelte
index 7ed05ef5..7aa476f5 100644
--- a/components/src/maplibre/VectorTileSource/VectorTileSource.svelte
+++ b/components/src/maplibre/VectorTileSource/VectorTileSource.svelte
@@ -19,14 +19,14 @@
 		maxZoom = 24,
 		id,
 		url = '',
-		tiles = [],
+		tiles,
 		attribution = ''
 	}: VectorTileSourceProps = $props();
 
 	const sourceSpec: VectorSourceSpecification = {
 		type: 'vector',
 		url,
-		tiles,
+		...(tiles ? tiles : {}),
 		maxzoom: maxZoom,
 		minzoom: minZoom,
 		attribution

From 99378ff68cee60ae43745abbd0166d9e40c8a28a Mon Sep 17 00:00:00 2001
From: Max Kohler <hello@maxkohler.com>
Date: Wed, 4 Mar 2026 19:45:59 +0100
Subject: [PATCH 03/10] Start workaround

---
 .../VectorTileSource/VectorTileSource.svelte       | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)

diff --git a/components/src/maplibre/VectorTileSource/VectorTileSource.svelte b/components/src/maplibre/VectorTileSource/VectorTileSource.svelte
index 7aa476f5..a1640d4e 100644
--- a/components/src/maplibre/VectorTileSource/VectorTileSource.svelte
+++ b/components/src/maplibre/VectorTileSource/VectorTileSource.svelte
@@ -23,9 +23,21 @@
 		attribution = ''
 	}: VectorTileSourceProps = $props();
 
+	// Workaround for https://github.com/versatiles-org/versatiles-rs/issues/184
+	// Drop when/if this lands: https://github.com/maplibre/maplibre-gl-js/issues/182
+
+	async function fetchTileJSON(url) {
+		const res = await fetch(url);
+		const data = await res.json();
+		console.log(data);
+	}
+
+	if (url) {
+		fetchTileJSON(url);
+	}
+
 	const sourceSpec: VectorSourceSpecification = {
 		type: 'vector',
-		url,
 		...(tiles ? tiles : {}),
 		maxzoom: maxZoom,
 		minzoom: minZoom,

From 7a003ef36180126e8bdaa0ae80b382ba81d0ce9f Mon Sep 17 00:00:00 2001
From: Max Kohler <hello@maxkohler.com>
Date: Thu, 5 Mar 2026 11:02:49 +0100
Subject: [PATCH 04/10] Build out minimal implementation

---
 .../VectorTileSource/VectorTileSource.mdx     |  4 ++
 .../VectorTileSource.stories.svelte           |  8 ++--
 .../VectorTileSource/VectorTileSource.svelte  | 43 ++++++++-----------
 .../VectorTileSource/fetchTileJson.ts         | 17 ++++++++
 .../src/maplibre/VectorTileSource/types.ts    |  8 ++++
 components/svelte.config.js                   |  6 ++-
 6 files changed, 58 insertions(+), 28 deletions(-)
 create mode 100644 components/src/maplibre/VectorTileSource/fetchTileJson.ts
 create mode 100644 components/src/maplibre/VectorTileSource/types.ts

diff --git a/components/src/maplibre/VectorTileSource/VectorTileSource.mdx b/components/src/maplibre/VectorTileSource/VectorTileSource.mdx
index 8f188eae..746e0f5b 100644
--- a/components/src/maplibre/VectorTileSource/VectorTileSource.mdx
+++ b/components/src/maplibre/VectorTileSource/VectorTileSource.mdx
@@ -8,6 +8,10 @@ import * as VectorTileSourceStories from './VectorTileSource.stories.svelte';
 
 Loads tiled vector data from a tileserver. Any mablibre-supported tileserver will work, but we'll typically use tiles served by `versatiles-rs` or `versatiles-node-static-proxy`.
 
+## Using a tiles.json
+
+## Using tiles directly
+
 ```jsx
 <Map>
 	<VectorTileSource
diff --git a/components/src/maplibre/VectorTileSource/VectorTileSource.stories.svelte b/components/src/maplibre/VectorTileSource/VectorTileSource.stories.svelte
index f36d1e05..bd994ca1 100644
--- a/components/src/maplibre/VectorTileSource/VectorTileSource.stories.svelte
+++ b/components/src/maplibre/VectorTileSource/VectorTileSource.stories.svelte
@@ -1,6 +1,8 @@
 <script context="module" lang="ts">
 	import { defineMeta } from '@storybook/addon-svelte-csf';
 	import DesignTokens from '../../DesignTokens/DesignTokens.svelte';
+	import {shades} from '../../DesignTokens/Tokens.ts';
+
 	import VectorTileSource from './VectorTileSource.svelte';
 	import VectorLayer from '../VectorLayer/VectorLayer.svelte';
 	import Map from '../Map/Map.svelte';
@@ -53,10 +55,10 @@
 					sourceId="test-source"
 					sourceLayer="boundaries"
 					id="test-layer"
-					type="fill"
+					type="line"
 					paint={{
-						'fill-color': 'purple',
-						'fill-opacity': 1
+						'line-color': shades.forest.dark1,
+						'line-width': 3
 					}}
 				/>
 				<AttributionControl position="bottom-left" />
diff --git a/components/src/maplibre/VectorTileSource/VectorTileSource.svelte b/components/src/maplibre/VectorTileSource/VectorTileSource.svelte
index a1640d4e..0a09eb02 100644
--- a/components/src/maplibre/VectorTileSource/VectorTileSource.svelte
+++ b/components/src/maplibre/VectorTileSource/VectorTileSource.svelte
@@ -1,6 +1,9 @@
 <script lang="ts">
-	import { type VectorSourceSpecification } from 'maplibre-gl';
+	import { type PromoteIdSpecification, type VectorSourceSpecification } from 'maplibre-gl';
+	import type { TileJsonData } from './types';
+
 	import MapSource from '../Source/MapSource.svelte';
+	import fetchTileJSON from './fetchTileJson';
 
 	interface VectorTileSourceProps {
 		id: string;
@@ -9,40 +12,32 @@
 		minZoom?: number;
 		maxZoom?: number;
 		/**
-		 * Attribution string for your data, usually rendered using an `<AttributionControl>`
+		 * Attribution string for your data, usually rendered using an `<AttributionControl/>`
 		 */
 		attribution?: string;
+		promoteId?: PromoteIdSpecification;
 	}
 
 	const {
-		minZoom = 0,
-		maxZoom = 24,
+		minZoom,
+		maxZoom,
 		id,
-		url = '',
+		url,
 		tiles,
-		attribution = ''
+		attribution,
+		promoteId
 	}: VectorTileSourceProps = $props();
 
-	// Workaround for https://github.com/versatiles-org/versatiles-rs/issues/184
-	// Drop when/if this lands: https://github.com/maplibre/maplibre-gl-js/issues/182
-
-	async function fetchTileJSON(url) {
-		const res = await fetch(url);
-		const data = await res.json();
-		console.log(data);
-	}
-
-	if (url) {
-		fetchTileJSON(url);
-	}
+	let tileJsonData = $derived(url ? await fetchTileJSON(url) : {});
 
-	const sourceSpec: VectorSourceSpecification = {
+	const sourceSpec: VectorSourceSpecification = $derived({
 		type: 'vector',
-		...(tiles ? tiles : {}),
-		maxzoom: maxZoom,
-		minzoom: minZoom,
-		attribution
-	};
+		tiles: tiles || tileJsonData.tiles || [],
+		maxzoom: maxZoom || tileJsonData.maxZoom || 24,
+		minzoom: minZoom || tileJsonData.minZoom || 0,
+		attribution: attribution || tileJsonData.attribution || '',
+		promoteId
+	});
 </script>
 
 <MapSource {id} {sourceSpec} />
diff --git a/components/src/maplibre/VectorTileSource/fetchTileJson.ts b/components/src/maplibre/VectorTileSource/fetchTileJson.ts
new file mode 100644
index 00000000..6f8a043c
--- /dev/null
+++ b/components/src/maplibre/VectorTileSource/fetchTileJson.ts
@@ -0,0 +1,17 @@
+// Workaround for https://github.com/versatiles-org/versatiles-rs/issues/184
+// Drop when/if this lands: https://github.com/maplibre/maplibre-gl-js/issues/182
+
+import { type TileJsonData } from './types';
+
+export default async function fetchTileJSON(url: string): Promise<TileJsonData> {
+	const u = new URL(url);
+	const res = await fetch(u);
+	const data = await res.json();
+
+	return {
+		tiles: data?.tiles.map((path: string) => `${u.origin}${path}`),
+		attribution: data?.attribution || data?.author,
+		minZoom: data?.minzoom,
+		maxZoom: data?.maxzoom
+	};
+}
diff --git a/components/src/maplibre/VectorTileSource/types.ts b/components/src/maplibre/VectorTileSource/types.ts
new file mode 100644
index 00000000..827ce3bb
--- /dev/null
+++ b/components/src/maplibre/VectorTileSource/types.ts
@@ -0,0 +1,8 @@
+interface TileJsonData {
+	tiles?: string[];
+	attribution?: string;
+	minZoom?: number;
+	maxZoom?: number;
+}
+
+export { type TileJsonData };
diff --git a/components/svelte.config.js b/components/svelte.config.js
index a356bb48..41649442 100644
--- a/components/svelte.config.js
+++ b/components/svelte.config.js
@@ -8,7 +8,11 @@ const config = {
 
 	// We can't use vitePreprocess() here, see: https://github.com/sveltejs/kit/issues/13122
 	preprocess: sveltePreprocess({ scss: true }),
-
+	compilerOptions: {
+		experimental: {
+			async: true
+		}
+	},
 	kit: {
 		adapter: adapter()
 	}

From 3e0beb94c26989bc7dae729d967ed0ee89d86069 Mon Sep 17 00:00:00 2001
From: Max Kohler <hello@maxkohler.com>
Date: Thu, 5 Mar 2026 11:24:28 +0100
Subject: [PATCH 05/10] Drop stray logs

---
 components/src/Switcher/Switcher.stories.svelte | 2 --
 1 file changed, 2 deletions(-)

diff --git a/components/src/Switcher/Switcher.stories.svelte b/components/src/Switcher/Switcher.stories.svelte
index 64c85962..c7a6a7ae 100644
--- a/components/src/Switcher/Switcher.stories.svelte
+++ b/components/src/Switcher/Switcher.stories.svelte
@@ -62,7 +62,6 @@
 	asChild
 	play={async ({ canvasElement, step }) => {
 		const canvas = within(canvasElement);
-		console.log(canvas);
 		await step('Options are displayed in a row', async () => {
 			const list = canvas.getByRole('list');
 			expect(list.classList).toContain('layout-row');
@@ -84,7 +83,6 @@
 	asChild
 	play={async ({ canvasElement, step }) => {
 		const canvas = within(canvasElement);
-		console.log(canvas);
 		await step('Options are displayed in a row', async () => {
 			const list = canvas.getByRole('list');
 			expect(list.classList).toContain('layout-column');

From 1fe235b5e4e643f8f09bacd844e46999367d0cd2 Mon Sep 17 00:00:00 2001
From: Max Kohler <hello@maxkohler.com>
Date: Thu, 5 Mar 2026 11:35:07 +0100
Subject: [PATCH 06/10] Improve formatting

---
 components/src/maplibre/Map/Map.svelte | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/components/src/maplibre/Map/Map.svelte b/components/src/maplibre/Map/Map.svelte
index 4b2fbef8..9e101044 100644
--- a/components/src/maplibre/Map/Map.svelte
+++ b/components/src/maplibre/Map/Map.svelte
@@ -5,9 +5,12 @@
 		type ProjectionSpecification,
 		type StyleSpecification
 	} from 'maplibre-gl';
+	
+	import { type Location } from '../types';
+
 	import { onMount, onDestroy, type Snippet, getContext, hasContext } from 'svelte';
+	
 	import { createMapContext, MapContext } from '../context.svelte.js';
-	import { type Location } from '../types';
 	import FallbackStyle from './FallbackStyle';
 	import { de } from './locale';
 
@@ -33,7 +36,7 @@
 		showDebug?: boolean;
 		options?: any;
 		/**
-		 * Set the mouse cursor. `""` (empty string) restores Maplibre's default behaviour. See VectorLayer/Default for a common usage example
+		 * Set the mouse cursor. `""` (empty string) restores Maplibre's default behaviour. See VectorLayer/Default for a usage example
 		 */
 		cursor?: string;
 		mapContext?: MapContext;
@@ -87,7 +90,8 @@
 	};
 
 	mapContext = createMapContext();
-	if (getContext('initialLocation') !== undefined && getContext('initialLocation') !== false) {
+
+	if (getContext('initialLocation')) {
 		initialLocation = getContext('initialLocation');
 	}
 

From 52d9a885fc6604bd8af4e92c50f5ec29f7b3eae6 Mon Sep 17 00:00:00 2001
From: Max Kohler <hello@maxkohler.com>
Date: Thu, 5 Mar 2026 11:35:25 +0100
Subject: [PATCH 07/10] Fix tiles prop format

---
 .../src/maplibre/MapStyle/SWRDataLabLight.stories.svelte    | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/components/src/maplibre/MapStyle/SWRDataLabLight.stories.svelte b/components/src/maplibre/MapStyle/SWRDataLabLight.stories.svelte
index 0f489ae6..1b497f04 100644
--- a/components/src/maplibre/MapStyle/SWRDataLabLight.stories.svelte
+++ b/components/src/maplibre/MapStyle/SWRDataLabLight.stories.svelte
@@ -97,9 +97,7 @@
 				>
 					<VectorTileSource
 						id="demo-source"
-						tiles={[
-							`https://static.datenhub.net/data/p118_correctiv_waermewende/heating_merged_2.versatiles?{z}/{x}/{y}`
-						]}
+						tiles={["https://static.datenhub.net/data/p118_correctiv_waermewende/heating_merged_2.versatiles?{z}/{x}/{y}"]}
 						attribution="Demo attribution"
 					/>
 
@@ -152,7 +150,7 @@
 					<GeocoderControl languages="de" service="maptiler" key="V32kPHZjMa0Mkn6YvSzA" />
 					<VectorTileSource
 						id="ev-infra-source"
-						url={`https://static.datenhub.net/data/p109_besser_wohnen/rent_merged_4.versatiles?{z}/{x}/{y}`}
+						tiles={["https://static.datenhub.net/data/p109_besser_wohnen/rent_merged_4.versatiles?{z}/{x}/{y}"]}
 						attribution="Demo attribution"
 					/>
 

From a28de23da5f82255890ccd23cb8f762af16806a7 Mon Sep 17 00:00:00 2001
From: Max Kohler <hello@maxkohler.com>
Date: Thu, 5 Mar 2026 12:29:41 +0100
Subject: [PATCH 08/10] Refactor WithLinkLocation to avoid
 set_context_after_init error

---
 components/src/maplibre/Map/Map.svelte        | 33 +++++++++++--------
 .../WithLinkLocation/WithLinkLocation.mdx     |  2 ++
 .../WithLinkLocation/WithLinkLocation.svelte  | 33 +++++++++++--------
 3 files changed, 41 insertions(+), 27 deletions(-)

diff --git a/components/src/maplibre/Map/Map.svelte b/components/src/maplibre/Map/Map.svelte
index 9e101044..4c1c534b 100644
--- a/components/src/maplibre/Map/Map.svelte
+++ b/components/src/maplibre/Map/Map.svelte
@@ -5,11 +5,11 @@
 		type ProjectionSpecification,
 		type StyleSpecification
 	} from 'maplibre-gl';
-	
+
 	import { type Location } from '../types';
 
 	import { onMount, onDestroy, type Snippet, getContext, hasContext } from 'svelte';
-	
+
 	import { createMapContext, MapContext } from '../context.svelte.js';
 	import FallbackStyle from './FallbackStyle';
 	import { de } from './locale';
@@ -78,22 +78,23 @@
 	}: MapProps = $props();
 
 	let container: HTMLElement;
+	mapContext = createMapContext();
+
+	// Initial location is determined by (in order of precedence) :
+	// 1. An arbitrary default location
+	// 2. initialLocation prop
+	// 3. initialLocation context (notably set by <WithLinkLocation/>)
 
-	// Merge initial location with default object so individual
-	// properties (like pitch) can be omitted by the caller
-	let initialLocation = {
+	let contextLocation = getContext('initialLocation');
+
+	let initialLocation = $derived({
 		lat: 51.3,
 		lng: 10.2,
 		zoom: 5,
 		pitch: 0,
-		...receivedInitialLocation
-	};
-
-	mapContext = createMapContext();
-
-	if (getContext('initialLocation')) {
-		initialLocation = getContext('initialLocation');
-	}
+		...receivedInitialLocation,
+		...contextLocation
+	});
 
 	onMount(() => {
 		mapContext.map = new maplibre.Map({
@@ -155,6 +156,12 @@
 		}
 	});
 
+	$effect(() => {
+		mapContext.map?.jumpTo({
+			center: [initialLocation.lng, initialLocation.lat],
+			zoom: initialLocation.zoom
+		});
+	});
 	$effect(() => {
 		if (allowZoom === false) {
 			mapContext.map?.scrollZoom.disable();
diff --git a/components/src/maplibre/WithLinkLocation/WithLinkLocation.mdx b/components/src/maplibre/WithLinkLocation/WithLinkLocation.mdx
index 564e1cda..05679890 100644
--- a/components/src/maplibre/WithLinkLocation/WithLinkLocation.mdx
+++ b/components/src/maplibre/WithLinkLocation/WithLinkLocation.mdx
@@ -6,6 +6,8 @@ import * as WithLinkLocationStories from './WithLinkLocation.stories.svelte';
 
 # WithLinkLocation
 
+This component allows you to set a map's initial location using a forward-geocoded URL parameter, as in: [http://localhost:6006/iframe.html?id=maplibre-extras-withlinklocation--default&viewMode=story&location=berlin](http://localhost:6006/iframe.html?id=maplibre-extras-withlinklocation--default&viewMode=story&location=berlin) (note `location` parameter at the end of the URL).This can be useful for multi-page visualisation scenarios.
+
 <Controls />
 
 <Stories />
diff --git a/components/src/maplibre/WithLinkLocation/WithLinkLocation.svelte b/components/src/maplibre/WithLinkLocation/WithLinkLocation.svelte
index 71c7c64e..30df757f 100644
--- a/components/src/maplibre/WithLinkLocation/WithLinkLocation.svelte
+++ b/components/src/maplibre/WithLinkLocation/WithLinkLocation.svelte
@@ -23,7 +23,13 @@
 		 * Limit search to one or more countries
 		 */
 		countries?: GeocodingLanguage | GeocodingCountry[];
+		/**
+		 * Limit search to one or more languages
+		 */
 		languages?: GeocodingLanguage | GeocodingLanguage[];
+		/**
+		 * Customise the URL parameter used to set the initial location
+		 */
 		urlParameter?: string;
 		children: Snippet;
 	}
@@ -41,18 +47,20 @@
 	const languagesArr = Array.isArray(languages) ? languages : [languages];
 
 	let geocoder: MaplibreGeocoderApi;
+
 	if (service === 'maptiler') {
 		geocoder = new MaptilerGeocoderAPI(key);
 	}
 
-	let location: Location | boolean | undefined = $state();
+	let location: any = $state({});
 
 	function bboxToArea(bbox: [number, number, number, number]) {
 		return (bbox[2] - bbox[0]) * (bbox[3] - bbox[1]);
 	}
 
-	onMount(async () => {
+	$effect(async () => {
 		const params = new URLSearchParams(window.location.search);
+
 		if (params.has(urlParameter)) {
 			const config: MaplibreGeocoderApiConfig = {
 				countries: countriesArr.join(','),
@@ -60,24 +68,21 @@
 				query: params.get(urlParameter)?.toString(),
 				limit: 1
 			};
+
 			const res = await geocoder.forwardGeocode(config);
+
 			if (res.features[0].bbox && res.features[0].geometry.type === 'Point') {
-				location = {
-					lat: res.features[0].geometry.coordinates[1],
-					lng: res.features[0].geometry.coordinates[0],
-					zoom: 11 - bboxToArea(res.features[0].bbox) * 5.5
-				};
+				location.lat = res.features[0].geometry.coordinates[1];
+				location.lng = res.features[0].geometry.coordinates[0];
+				location.zoom = 11 - bboxToArea(res.features[0].bbox) * 5.5;
+				location.active = true;
 			}
 		} else {
-			location = false;
+			location = {};
 		}
 	});
 
-	$effect.pre(() => {
-		setContext('initialLocation', location);
-	});
+	setContext('initialLocation', location);
 </script>
 
-{#if location !== undefined}
-	{@render children?.()}
-{/if}
+{@render children?.()}

From 5d0dd12c2daec0bdd1733eb7bce37f4f66d18b6a Mon Sep 17 00:00:00 2001
From: Max Kohler <hello@maxkohler.com>
Date: Thu, 5 Mar 2026 13:03:08 +0100
Subject: [PATCH 09/10] Extend docs

---
 .../VectorTileSource/VectorTileSource.mdx     | 36 +++++++++--
 .../VectorTileSource.stories.svelte           | 59 ++++++++++++-------
 .../VectorTileSource/fetchTileJson.ts         |  5 +-
 3 files changed, 72 insertions(+), 28 deletions(-)

diff --git a/components/src/maplibre/VectorTileSource/VectorTileSource.mdx b/components/src/maplibre/VectorTileSource/VectorTileSource.mdx
index 746e0f5b..68f514ce 100644
--- a/components/src/maplibre/VectorTileSource/VectorTileSource.mdx
+++ b/components/src/maplibre/VectorTileSource/VectorTileSource.mdx
@@ -6,19 +6,43 @@ import * as VectorTileSourceStories from './VectorTileSource.stories.svelte';
 
 # VectorTileSource
 
-Loads tiled vector data from a tileserver. Any mablibre-supported tileserver will work, but we'll typically use tiles served by `versatiles-rs` or `versatiles-node-static-proxy`.
+Loads tiled vector data from a tileserver.
 
-## Using a tiles.json
+Any mablibre-supported tileserver will work, but we typically use tiles served by `versatiles-rs` or `versatiles-node-static-proxy`.
 
-## Using tiles directly
+## Using a TileJSON
+
+You should generally load tile data by pointing to a [TileJSON](https://github.com/mapbox/tilejson-spec/blob/master/3.0.0/README.md) file. These are generated by most tile servers and contain useful metadata like `attribution`, `bounds`, `minzoom` and `maxzoom` in addition to the tile data itself.
+
+```jsx
+<Map style={SWRDataLabLight()}>
+	<VectorTileSource id="test-source" url="https://tiles.datenhub.net/tiles/hillshade/tiles.json" />
+	<VectorLayer
+		sourceId="test-source"
+		sourceLayer="boundaries"
+		id="test-layer"
+		type="line"
+		paint={{ 'line-color': shades.red.base, 'line-width': 2 }}
+	/>
+	<AttributionControl position="bottom-left" />
+</Map>
+```
+
+- This component includes a workaround to support for [TileJSON data with relative URLs](https://docs.versatiles.org/compendium/specification_extended_tilejson.html#relaxed-rule-for-tiles) as produced by versatiles-rs.
+- TileJSON data can by overridden by passing the relevant props to the component directly.
+
+## Using tile URLs directly
+
+Alternatively, you can point to a tile URL directly using the `tiles` prop:
 
 ```jsx
-<Map>
+<Map style={SWRDataLabLight()}>
 	<VectorTileSource
 		tiles={['https://static.datenhub.net/rent_merged.versatiles?{z}/{x}/{y}']}
-		id="chargers"
+		attribution="Demo attribution"
+		id="test-source"
 	/>
-	<VectorLayer sourceId="chargers" />
+	<VectorLayer sourceId="test-source" />
 </Map>
 ```
 
diff --git a/components/src/maplibre/VectorTileSource/VectorTileSource.stories.svelte b/components/src/maplibre/VectorTileSource/VectorTileSource.stories.svelte
index bd994ca1..c1a4922f 100644
--- a/components/src/maplibre/VectorTileSource/VectorTileSource.stories.svelte
+++ b/components/src/maplibre/VectorTileSource/VectorTileSource.stories.svelte
@@ -1,7 +1,7 @@
 <script context="module" lang="ts">
 	import { defineMeta } from '@storybook/addon-svelte-csf';
 	import DesignTokens from '../../DesignTokens/DesignTokens.svelte';
-	import {shades} from '../../DesignTokens/Tokens.ts';
+	import { shades } from '../../DesignTokens/Tokens.ts';
 
 	import VectorTileSource from './VectorTileSource.svelte';
 	import VectorLayer from '../VectorLayer/VectorLayer.svelte';
@@ -19,22 +19,36 @@
 	<DesignTokens theme="light">
 		<div class="container">
 			<Map showDebug={true} style={SWRDataLabLight()}>
-				<VectorTileSource
-					id="ev-infra-source"
-					tiles={[
-						`https://static.datenhub.net/data/p108_e_auto_check/ev_infra_merged.versatiles?{z}/{x}/{y}`
-					]}
-					attribution="Demo attribution"
+				<VectorTileSource id="test-source" url="https://tiles.datenhub.net/tiles/osm/tiles.json" />
+				<VectorLayer
+					sourceId="test-source"
+					sourceLayer="boundaries"
+					id="test-layer"
+					type="line"
+					paint={{
+						'line-color': shades.red.base,
+						'line-width': 2
+					}}
 				/>
+				<AttributionControl position="bottom-left" />
+			</Map>
+		</div>
+	</DesignTokens>
+</Story>
+
+<Story asChild name="TileJSON with absolute URLs">
+	<DesignTokens theme="light">
+		<div class="container">
+			<Map showDebug={true} style={SWRDataLabLight()}>
+				<VectorTileSource id="test-source" url="https://demotiles.maplibre.org/tiles/tiles.json" />
 				<VectorLayer
-					sourceId="ev-infra-source"
-					sourceLayer="coverage"
-					id="ev-infra-outline"
+					sourceId="test-source"
+					sourceLayer="countries"
+					id="test-layer"
 					type="line"
 					paint={{
-						'line-width': 0.5,
-						'line-color': 'purple',
-						'line-opacity': 1
+						'line-color': shades.red.base,
+						'line-width': 2
 					}}
 				/>
 				<AttributionControl position="bottom-left" />
@@ -43,22 +57,25 @@
 	</DesignTokens>
 </Story>
 
-<Story asChild name="tile json">
+<Story asChild name="Usign bare tile URL">
 	<DesignTokens theme="light">
 		<div class="container">
 			<Map showDebug={true} style={SWRDataLabLight()}>
 				<VectorTileSource
-					id="test-source"
-					url="https://tiles.versatiles.org/tiles/osm/tiles.json"
+					id="ev-infra-source"
+					tiles={[
+						`https://static.datenhub.net/data/p108_e_auto_check/ev_infra_merged.versatiles?{z}/{x}/{y}`
+					]}
+					attribution="Demo attribution"
 				/>
 				<VectorLayer
-					sourceId="test-source"
-					sourceLayer="boundaries"
-					id="test-layer"
+					sourceId="ev-infra-source"
+					sourceLayer="coverage"
+					id="ev-infra-outline"
 					type="line"
 					paint={{
-						'line-color': shades.forest.dark1,
-						'line-width': 3
+						'line-width': 1,
+						'line-color': shades.red.base
 					}}
 				/>
 				<AttributionControl position="bottom-left" />
diff --git a/components/src/maplibre/VectorTileSource/fetchTileJson.ts b/components/src/maplibre/VectorTileSource/fetchTileJson.ts
index 6f8a043c..b02a77da 100644
--- a/components/src/maplibre/VectorTileSource/fetchTileJson.ts
+++ b/components/src/maplibre/VectorTileSource/fetchTileJson.ts
@@ -8,8 +8,11 @@ export default async function fetchTileJSON(url: string): Promise<TileJsonData>
 	const res = await fetch(u);
 	const data = await res.json();
 
+	// Simple heuristic for absolute URLs
+	const re = /(((http)s?)):\/\/.*/gi;
+
 	return {
-		tiles: data?.tiles.map((path: string) => `${u.origin}${path}`),
+		tiles: data?.tiles.map((path: string) => (re.test(path) ? path : `${u.origin}${path}`)),
 		attribution: data?.attribution || data?.author,
 		minZoom: data?.minzoom,
 		maxZoom: data?.maxzoom

From c2698252b90a1bdcf1ed12c28bc86b591ce18796 Mon Sep 17 00:00:00 2001
From: Max Kohler <hello@maxkohler.com>
Date: Thu, 5 Mar 2026 13:06:21 +0100
Subject: [PATCH 10/10] tweak formatting

---
 components/src/maplibre/VectorTileSource/fetchTileJson.ts | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/components/src/maplibre/VectorTileSource/fetchTileJson.ts b/components/src/maplibre/VectorTileSource/fetchTileJson.ts
index b02a77da..3d6fe0f2 100644
--- a/components/src/maplibre/VectorTileSource/fetchTileJson.ts
+++ b/components/src/maplibre/VectorTileSource/fetchTileJson.ts
@@ -1,8 +1,8 @@
+import { type TileJsonData } from './types';
+
 // Workaround for https://github.com/versatiles-org/versatiles-rs/issues/184
 // Drop when/if this lands: https://github.com/maplibre/maplibre-gl-js/issues/182
 
-import { type TileJsonData } from './types';
-
 export default async function fetchTileJSON(url: string): Promise<TileJsonData> {
 	const u = new URL(url);
 	const res = await fetch(u);