From ab35447c129f4e0b02e3cf2b10f6a98b2b3e0a9d Mon Sep 17 00:00:00 2001
From: Max Kohler <hello@maxkohler.com>
Date: Wed, 23 Jul 2025 10:44:09 +0200
Subject: [PATCH 1/3] Block out bindable mapContext

---
 .../src/maplibre/Map/Map.stories.svelte       | 62 ++++++++++++++++++-
 components/src/maplibre/Map/Map.svelte        | 28 +++++++--
 .../src/maplibre/MapStyle/SWRDataLabLight.mdx |  2 +-
 components/src/maplibre/Maplibre.mdx          |  2 +
 4 files changed, 87 insertions(+), 7 deletions(-)

diff --git a/components/src/maplibre/Map/Map.stories.svelte b/components/src/maplibre/Map/Map.stories.svelte
index 12be5e7d..a4e90850 100644
--- a/components/src/maplibre/Map/Map.stories.svelte
+++ b/components/src/maplibre/Map/Map.stories.svelte
@@ -1,6 +1,6 @@
-<script context="module" lang="ts">
+<script module lang="ts">
 	import { defineMeta } from '@storybook/addon-svelte-csf';
-	import { within, expect } from 'storybook/test';
+	import { within, expect, userEvent, fn } from 'storybook/test';
 
 	import Map from './Map.svelte';
 	import ScaleControl from '../ScaleControl/ScaleControl.svelte';
@@ -12,6 +12,8 @@
 	import { SWRDataLabLight } from '../MapStyle';
 
 	import { eclipse } from '@versatiles/style';
+	import { MapContext } from '../context.svelte';
+
 	const alternateStyle = eclipse({
 		language: 'de',
 		baseUrl: 'https://tiles.versatiles.org',
@@ -22,6 +24,9 @@
 		title: 'Maplibre/Map',
 		component: Map
 	});
+
+	let mapContext: MapContext;
+	const onMoveStart = fn();
 </script>
 
 <Story
@@ -75,6 +80,59 @@
 	</div>
 </Story>
 
+<Story
+	asChild
+	name="External Controls"
+	play={async ({ canvasElement, step }) => {
+		const canvas = within(canvasElement);
+		const containerEl = canvas.getByTestId('map-container');
+		const flyToBerlinButton = canvas.getByTestId('flyto-berlin');
+
+		await step('map renders', async () => {
+			const mapEl = containerEl.querySelector('.maplibregl-canvas');
+			expect(mapEl).toBeTruthy();
+		});
+		await step('mapContext prop receives valid data', async () => {
+			expect(mapContext).toBeInstanceOf(MapContext);
+		});
+		await step('external trigger map events', async () => {
+			await userEvent.click(flyToBerlinButton);
+			expect(onMoveStart).toHaveBeenCalled();
+			// We'd like to expext.poll() for onMoveEnd.toHaveBeenCalled()
+			// here but that API doesn't exist in Storybook, see:
+			// https://github.com/storybookjs/storybook/issues/29060
+		});
+	}}
+>
+	<div class="container">
+		<DesignTokens>
+			<button
+				data-testid="flyto-berlin"
+				onclick={() => {
+					mapContext.map?.flyTo({ center: [13.3849, 52.5026], zoom: 9.8 });
+				}}>Fly to Berlin</button
+			>
+			<button
+				data-testid="flyto-origin"
+				onclick={() => {
+					mapContext.map?.flyTo({ center: [10.43, 50.88], zoom: 5 });
+				}}>Reset</button
+			>
+			<Map
+				style={SWRDataLabLight()}
+				initialLocation={{ lat: 50.88, lng: 10.43, zoom: 5 }}
+				showDebug
+				onmovestart={onMoveStart}
+				bind:mapContext
+			>
+				<ScaleControl />
+				<AttributionControl />
+				<NavigationControl />
+			</Map>
+		</DesignTokens>
+	</div>
+</Story>
+
 <Story asChild name="Globe Projection">
 	<div class="container dark">
 		<DesignTokens>
diff --git a/components/src/maplibre/Map/Map.svelte b/components/src/maplibre/Map/Map.svelte
index d5c1389c..4f0350b0 100644
--- a/components/src/maplibre/Map/Map.svelte
+++ b/components/src/maplibre/Map/Map.svelte
@@ -1,7 +1,11 @@
 <script lang="ts">
-	import maplibre, { type ProjectionSpecification, type StyleSpecification } from 'maplibre-gl';
+	import maplibre, {
+		type MapLibreEvent,
+		type ProjectionSpecification,
+		type StyleSpecification
+	} from 'maplibre-gl';
 	import { onMount, onDestroy, type Snippet, getContext, hasContext } from 'svelte';
-	import { createMapContext } from '../context.svelte.js';
+	import { createMapContext, MapContext } from '../context.svelte.js';
 	import { type Location } from '../types';
 	import FallbackStyle from './FallbackStyle';
 
@@ -20,6 +24,9 @@
 		projection?: ProjectionSpecification;
 		showDebug?: boolean;
 		options?: any;
+		mapContext?: MapContext;
+		onmovestart?: (e: MapLibreEvent) => null;
+		onmoveend?: (e: MapLibreEvent) => null;
 		children?: Snippet;
 	}
 
@@ -38,7 +45,12 @@
 		allowRotation = false,
 		allowZoom = true,
 		showDebug = false,
-		initialLocation: receivedInitialLocation
+		initialLocation: receivedInitialLocation,
+		// Future: This should become bindable.readonly when that becomes
+		// available, see: https://github.com/sveltejs/svelte/issues/7712
+		mapContext = $bindable(),
+		onmoveend,
+		onmovestart
 	}: MapProps = $props();
 
 	let container: HTMLElement;
@@ -53,7 +65,7 @@
 		...receivedInitialLocation
 	};
 
-	const mapContext = createMapContext();
+	mapContext = createMapContext();
 	if (getContext('initialLocation') !== undefined && getContext('initialLocation') !== false) {
 		initialLocation = getContext('initialLocation');
 	}
@@ -85,6 +97,13 @@
 			pitch = mapContext.map?.getPitch();
 			bearing = mapContext.map?.getBearing();
 		});
+
+		if (onmoveend) {
+			mapContext.map.on('moveend', onmoveend);
+		}
+		if (onmovestart) {
+			mapContext.map.on('movestart', onmovestart);
+		}
 	});
 
 	onDestroy(async () => {
@@ -94,6 +113,7 @@
 	$effect(() => {
 		if (mapContext.map) mapContext.map.setStyle(style);
 	});
+
 	$effect(() => {
 		if (mapContext.styleLoaded) {
 			mapContext.map?.setProjection(projection);
diff --git a/components/src/maplibre/MapStyle/SWRDataLabLight.mdx b/components/src/maplibre/MapStyle/SWRDataLabLight.mdx
index 946f44e6..3db8d902 100644
--- a/components/src/maplibre/MapStyle/SWRDataLabLight.mdx
+++ b/components/src/maplibre/MapStyle/SWRDataLabLight.mdx
@@ -12,7 +12,7 @@ Light-themed general-purpose basemap using SWR colours and typefaces based on
 
 - Data sources
   - Vector data: [versatiles-osm](https://download.versatiles.org/) in the [Shortbread schema](https://shortbread-tiles.org/) served from `tiles.versatiles.org`
-  - Building footprints with heights: [basemap-de](https://basemap.de/produkte-und-dienste/web-vektor/) vector tiles served from `sgx.geodatenzentrum.de`
+  - Building footprints with heights: [basemap-de](https://basemap.de/produkte-und-dienste/web-vektor/) vector tiles served from `sgx.geodatenzentrum.de` ([License](https://sgx.geodatenzentrum.de/web_public/gdz/lizenz/deu/Nutzungsbedingungen_basemapde.pdf))
   - Typefaces: SWR Sans served from `https://static.datenhub.net/maps/fonts/`.
 - Layer count: {SWRDataLabLight({enableBuildingExtrusions: true}).layers.length} (including building extrusions)
 
diff --git a/components/src/maplibre/Maplibre.mdx b/components/src/maplibre/Maplibre.mdx
index 533e0dc9..33a2a17e 100644
--- a/components/src/maplibre/Maplibre.mdx
+++ b/components/src/maplibre/Maplibre.mdx
@@ -58,6 +58,8 @@ This example initialises a map using the SWRDataLabLight style, adds an addition
 </style>
 ```
 
+- `mapContext` is [bindable](https://svelte.dev/docs/svelte/$bindable), so you can access MapLibre APIs from outside the `<Map>` component. This is useful if you want to control the map programatically, ie. in a scrollytelling application.
+
 ## Available components
 
 ### Sources

From b5dec93820fade950ec51334c932e12b04692e44 Mon Sep 17 00:00:00 2001
From: Max Kohler <hello@maxkohler.com>
Date: Wed, 23 Jul 2025 10:56:22 +0200
Subject: [PATCH 2/3] tidy stories

---
 components/src/maplibre/Map/Map.stories.svelte | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/components/src/maplibre/Map/Map.stories.svelte b/components/src/maplibre/Map/Map.stories.svelte
index a4e90850..5c24de83 100644
--- a/components/src/maplibre/Map/Map.stories.svelte
+++ b/components/src/maplibre/Map/Map.stories.svelte
@@ -125,16 +125,14 @@
 				onmovestart={onMoveStart}
 				bind:mapContext
 			>
-				<ScaleControl />
 				<AttributionControl />
-				<NavigationControl />
 			</Map>
 		</DesignTokens>
 	</div>
 </Story>
 
 <Story asChild name="Globe Projection">
-	<div class="container dark">
+	<div class="container">
 		<DesignTokens>
 			<Map
 				style={SWRDataLabLight()}

From a3ade611173c051e37804831c35d9218057cfbfb Mon Sep 17 00:00:00 2001
From: Max Kohler <hello@maxkohler.com>
Date: Wed, 23 Jul 2025 13:22:53 +0200
Subject: [PATCH 3/3] Link to license

---
 components/src/maplibre/MapStyle/SWRDataLabLight.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/components/src/maplibre/MapStyle/SWRDataLabLight.mdx b/components/src/maplibre/MapStyle/SWRDataLabLight.mdx
index 3db8d902..5452bfce 100644
--- a/components/src/maplibre/MapStyle/SWRDataLabLight.mdx
+++ b/components/src/maplibre/MapStyle/SWRDataLabLight.mdx
@@ -11,7 +11,7 @@ Light-themed general-purpose basemap using SWR colours and typefaces based on
 [versatiles-greybeard](https://github.com/versatiles-org/versatiles-style).
 
 - Data sources
-  - Vector data: [versatiles-osm](https://download.versatiles.org/) in the [Shortbread schema](https://shortbread-tiles.org/) served from `tiles.versatiles.org`
+  - Vector data: [versatiles-osm](https://download.versatiles.org/) in the [Shortbread schema](https://shortbread-tiles.org/) served from `tiles.versatiles.org` ([License](https://docs.versatiles.org/basics/tilesets.html#license--attribution))
   - Building footprints with heights: [basemap-de](https://basemap.de/produkte-und-dienste/web-vektor/) vector tiles served from `sgx.geodatenzentrum.de` ([License](https://sgx.geodatenzentrum.de/web_public/gdz/lizenz/deu/Nutzungsbedingungen_basemapde.pdf))
   - Typefaces: SWR Sans served from `https://static.datenhub.net/maps/fonts/`.
 - Layer count: {SWRDataLabLight({enableBuildingExtrusions: true}).layers.length} (including building extrusions)