Merge pull request #290 from OneBusAway/fix-288

feat: support URL query parameters for initial map position

Author: aaronbrethorst

.claude/agents/simplify.md

@@ -0,0 +1,132 @@
+---
+name: simplify
+description: Use to simplify JavaScript/TypeScript/Svelte code before code review. Invoke with "simplify my branch", "simplify these changes", or "use simplify on these changes". Analyzes git diff against main, iterates file-by-file, proposes refactors interactively.
+tools: Read, Grep, Glob, Bash, Write, Task
+---
+
+You are an opinionated code simplifier for JavaScript, TypeScript, and SvelteKit projects. Your job is to make code cleaner, more readable, and more maintainable before code review.
+
+## Workflow
+
+1. **Get the diff**: Run `git diff main...HEAD --name-only` to find changed files
+2. **Filter**: Only process `.js`, `.ts`, `.svelte` files
+3. **Iterate file-by-file**: For each file:
+   - Show the filename
+   - Read the file and the diff for that file (`git diff main...HEAD -- <file>`)
+   - Analyze against simplification principles
+   - Present numbered proposals + observations
+   - Wait for user input before proceeding
+
+## Before proposing changes
+
+**Always consult Svelte/SvelteKit conventions first.** Use the Svelte MCP tools:
+
+- `list-sections` to find relevant documentation sections
+- `get-documentation` to fetch current best practices
+- `svelte-autofixer` to detect anti-patterns in Svelte files
+
+This ensures your suggestions align with Svelte 5 and SvelteKit conventions, not outdated patterns.
+
+## Interaction format
+
+Present proposals like this:
+
+```
+## src/routes/dashboard/+page.svelte
+
+### Proposals
+1. [Lines 23-41] Flatten nested if/else into early returns
+2. [Lines 67-89] Extract repeated fetch error handling into `$lib/utils/fetch.ts`
+3. [Lines 102-108] Rename `d` to `dashboardData` for clarity
+
+### Observations
+- This component is 180 lines. Consider extracting the chart configuration (lines 100-150) into a separate component.
+- The reactive statement on line 45 recalculates on every state change. Consider using $derived with more specific dependencies.
+
+[1] [2] [3] [all] [skip] [discuss N]
+```
+
+Wait for user response:
+
+- `1`, `2`, `3`, etc. → Apply that specific proposal, show the change, confirm
+- `all` → Apply all proposals in sequence
+- `skip` → Move to next file
+- `discuss 2` → Explain proposal 2 in detail, show before/after, wait for approval
+
+After applying changes or skipping, move to the next file. Continue until all files are processed.
+
+## Simplification principles (opinionated)
+
+### Control flow
+
+- **Early returns over nested conditionals.** Flip conditions and return/continue early.
+- **No nested ternaries.** One level max. Otherwise use if/else or extract to a function.
+- **Guard clauses first.** Handle edge cases and errors at the top of functions.
+- **Prefer `switch` with early returns** over long if/else chains when matching discrete values.
+
+### Functions
+
+- **Max 30 lines per function.** If longer, it probably does too much—extract.
+- **Single responsibility.** A function should do one thing. "And" in a description = split it.
+- **Max 3 parameters.** More than 3? Use an options object.
+- **No boolean parameters** that change behavior. Use two functions or an options object.
+- **Name functions for what they return**, not what they do internally. `getUserRole()` not `checkUserAndGetRole()`.
+
+### Naming
+
+- **Variables: nouns.** `user`, `dashboardData`, `isLoading`
+- **Functions: verbs.** `fetchUser`, `calculateTotal`, `handleSubmit`
+- **Booleans: `is`, `has`, `should`, `can`.** `isActive`, `hasPermission`
+- **No abbreviations** unless universally understood (`id`, `url`, `api`). `btn` → `button`, `msg` → `message`
+- **No single-letter variables** except in very short lambdas or loop indices.
+
+### Svelte/SvelteKit specific
+
+- **Use `$state` and `$derived`** (Svelte 5 runes), not legacy `let` + `$:` reactive statements.
+- **Prefer `onclick` over `on:click`** (Svelte 5 syntax).
+- **Colocate related logic** in the same file unless it's reused elsewhere.
+- **Use `+page.server.ts` for data loading**, not client-side fetches in `onMount`.
+- **Use `$lib` aliases** for imports from lib folder.
+- **Form actions over API routes** for mutations when possible.
+- **Keep components under 150 lines.** Extract sub-components or move logic to `.svelte.ts` files.
+
+### Extraction patterns
+
+- **Repeated code (2+ times)**: Extract to a function or component.
+- **Complex conditionals**: Extract to a well-named boolean or function.
+- **Magic numbers/strings**: Extract to named constants.
+- **Fetch/error handling patterns**: Extract to `$lib/utils/`.
+- **Shared component logic**: Extract to `$lib/components/` or colocate in same folder.
+
+### Removal
+
+- **Dead code**: Unused imports, unreachable branches, commented-out code.
+- **Unnecessary abstractions**: If a wrapper adds no value, inline it.
+- **Redundant type annotations**: Let TypeScript infer when obvious.
+
+## Summary
+
+After all files are processed, provide a summary:
+
+```
+## Summary
+
+### Applied
+- src/routes/dashboard/+page.svelte: 3 refactors (early returns, fetch helper, naming)
+- src/lib/components/DataTable.svelte: 1 refactor (extracted sort logic)
+
+### Skipped
+- src/routes/api/health/+server.ts: No changes needed
+
+### Observations to consider later
+- Dashboard component could be split into smaller pieces
+- Consider adding error boundary around chart section
+```
+
+## Important
+
+- **Don't change behavior.** These are refactors, not rewrites. Tests should still pass.
+- **Preserve comments** that explain "why", but remove obvious "what" comments.
+- **One thing at a time.** Apply proposals individually so user can review each change.
+- **Be specific.** Show line numbers, show before/after snippets.
+- **Respect user decisions.** If they skip something, don't bring it up again.

.claude/settings.json

@@ -1,15 +1,15 @@
 {
-  "permissions": {
-    "allow": [
-      "WebFetch(domain:github.com)",
-      "Bash(cat:*)",
-      "Bash(gh issue edit:*)",
-      "Bash(grep:*)",
-      "Bash(npm run prepush:*)",
-      "Bash(find:*)",
-      "Bash(sort:*)",
-      "Bash(npm run build:*)",
-      "Bash(npm run test:*)"
-    ]
-  }
+	"permissions": {
+		"allow": [
+			"WebFetch(domain:github.com)",
+			"Bash(cat:*)",
+			"Bash(gh issue edit:*)",
+			"Bash(grep:*)",
+			"Bash(npm run prepush:*)",
+			"Bash(find:*)",
+			"Bash(sort:*)",
+			"Bash(npm run build:*)",
+			"Bash(npm run test:*)"
+		]
+	}
 }

.mcp.json

@@ -0,0 +1,10 @@
+{
+	"mcpServers": {
+		"svelte": {
+			"type": "stdio",
+			"command": "npx",
+			"args": ["-y", "@sveltejs/mcp"],
+			"env": {}
+		}
+	}
+}

README.md

@@ -89,6 +89,30 @@ Use these in Tailwind classes: `bg-primary-500`, `text-primary-700`, `border-pri
 
 - `PUBLIC_OTP_SERVER_URL` - string: (optional) Your OpenTripPlanner 1.x-compatible trip planner server URL.
 
+## URL Parameters
+
+You can link directly to a specific location on the map using URL query parameters:
+
+| Parameter | Description                         | Example     |
+| --------- | ----------------------------------- | ----------- |
+| `lat`     | Latitude of the initial map center  | `47.6062`   |
+| `lng`     | Longitude of the initial map center | `-122.3321` |
+
+**Example URL:**
+
+```
+https://your-wayfinder-instance.com/?lat=47.6062&lng=-122.3321
+```
+
+**Validation rules:**
+
+- Both `lat` and `lng` must be provided together
+- Latitude must be between -90 and 90
+- Longitude must be between -180 and 180
+- Coordinates must be within 200km of the configured region center (`PUBLIC_OBA_REGION_CENTER_LAT`/`PUBLIC_OBA_REGION_CENTER_LNG`)
+
+When valid coordinates are provided, the map will center on that location and place a location marker there. The URL parameters are automatically cleaned from the browser address bar after being applied.
+
 ## Building
 
 To create a production version of your app:

src/components/MapContainer.svelte

@@ -10,7 +10,13 @@
 	import { MapSource } from './../config/mapSource.js';
 
 	let apiKey = env.PUBLIC_OBA_GOOGLE_MAPS_API_KEY;
-	let { handleStopMarkerSelect, mapProvider = $bindable(), stop, ...restProps } = $props();
+	let {
+		handleStopMarkerSelect,
+		mapProvider = $bindable(),
+		stop,
+		initialCoords = null,
+		...restProps
+	} = $props();
 
 	onMount(() => {
 		if (PUBLIC_OBA_MAP_PROVIDER === MapSource.Google) {
@@ -24,7 +30,7 @@
 </script>
 
 {#if mapProvider}
-	<MapView {handleStopMarkerSelect} {mapProvider} {stop} {...restProps} />
+	<MapView {handleStopMarkerSelect} {mapProvider} {stop} {initialCoords} {...restProps} />
 {:else}
 	<FullPageLoadingSpinner />
 {/if}

src/components/map/MapView.svelte

@@ -20,6 +20,7 @@
 	 * @property {boolean} [showRouteMap]
 	 * @property {any} [mapProvider]
 	 * @property {any} [stop] - Currently selected stop to preserve visual context
+	 * @property {{ lat: number, lng: number } | null} [initialCoords] - Optional initial coordinates from URL params
 	 */
 
 	/** @type {Props} */
@@ -30,7 +31,8 @@
 		isRouteSelected = false,
 		showRouteMap = false,
 		mapProvider = null,
-		stop = null
+		stop = null,
+		initialCoords = null
 	} = $props();
 
 	let isTripPlanModeActive = $state(false);
@@ -132,14 +134,26 @@
 
 	async function initMap() {
 		try {
+			// Use URL-provided coordinates if available, otherwise use region center
+			const mapCenterLat = initialCoords?.lat ?? Number(initialLat);
+			const mapCenterLng = initialCoords?.lng ?? Number(initialLng);
+
 			await mapProvider.initMap(mapElement, {
-				lat: Number(initialLat),
-				lng: Number(initialLng)
+				lat: mapCenterLat,
+				lng: mapCenterLng
 			});
 
 			mapInstance = mapProvider;
 
-			await loadStopsAndAddMarkers(initialLat, initialLng, true);
+			// If we have initial coordinates from URL, update the user location store
+			// and add a user location marker
+			if (initialCoords) {
+				const coords = { lat: mapCenterLat, lng: mapCenterLng };
+				userLocation.set(coords);
+				mapInstance.addUserLocationMarker(coords);
+			}
+
+			await loadStopsAndAddMarkers(mapCenterLat, mapCenterLng, true);
 
 			const debouncedLoadMarkers = debounce(async () => {
 				if (mapMode !== Modes.NORMAL) {

src/lib/urlParams.js

@@ -0,0 +1,75 @@
+import { calcDistanceBetweenTwoPoints } from './mathUtils';
+
+/**
+ * Maximum allowed distance (in kilometers) from region center for URL coordinates
+ */
+const MAX_DISTANCE_FROM_REGION_KM = 200;
+
+/**
+ * Parses and validates latitude and longitude from URL search parameters.
+ * Both parameters must be present and numeric, and the coordinates must be
+ * within 200km of the configured region center.
+ *
+ * @param {URLSearchParams} searchParams - The URL search parameters
+ * @param {number} regionCenterLat - The region center latitude
+ * @param {number} regionCenterLng - The region center longitude
+ * @returns {{ lat: number, lng: number } | null} The validated coordinates or null if invalid
+ */
+export function parseInitialCoordinates(searchParams, regionCenterLat, regionCenterLng) {
+	const latParam = searchParams.get('lat');
+	const lngParam = searchParams.get('lng');
+
+	// Both parameters must be present
+	if (latParam === null || lngParam === null) {
+		return null;
+	}
+
+	// Parse as numbers
+	const lat = parseFloat(latParam);
+	const lng = parseFloat(lngParam);
+
+	// Both must be valid finite numbers
+	if (isNaN(lat) || isNaN(lng) || !isFinite(lat) || !isFinite(lng)) {
+		return null;
+	}
+
+	// Validate latitude range (-90 to 90)
+	if (lat < -90 || lat > 90) {
+		return null;
+	}
+
+	// Validate longitude range (-180 to 180)
+	if (lng < -180 || lng > 180) {
+		return null;
+	}
+
+	// Check distance from region center
+	const distanceKm = calcDistanceBetweenTwoPoints(lat, lng, regionCenterLat, regionCenterLng);
+
+	if (distanceKm > MAX_DISTANCE_FROM_REGION_KM) {
+		return null;
+	}
+
+	return { lat, lng };
+}
+
+/**
+ * Removes lat and lng parameters from the current URL without triggering navigation.
+ * Uses history.replaceState to clean the URL after coordinates have been applied.
+ */
+export function cleanUrlParams() {
+	if (typeof window === 'undefined') {
+		return;
+	}
+
+	const url = new URL(window.location.href);
+	const hadParams = url.searchParams.has('lat') || url.searchParams.has('lng');
+
+	if (hadParams) {
+		url.searchParams.delete('lat');
+		url.searchParams.delete('lng');
+
+		// Use replaceState to avoid adding to browser history
+		window.history.replaceState({}, '', url.toString());
+	}
+}