feat(ui,rider): shared pluggable map (picker+viewer), Nominatim reverse, fix flicker

Investigation (/plan-eng-review): the two mobile apps differ by role, so parity
means sharing the UX *primitives*, not the screens. The map was customer-only and
duplicated; rider navigated to a fuzzy text address instead of the exact point the
customer pinned.

packages/ui — one map stack, two interactions:
- leaflet-map.ts: shared Leaflet-in-WebView html + pluggable tile presets
  (mapbox @2x, maptiler @2x, tomtom, osm) resolved from env via resolveTiles().
  Tiles are the only HD lever; provider swaps with one env var, no code change.
- MapPicker: refactored to take an injected `tiles` + `reverseGeocode` (api-
  agnostic). FIX: memoise the WebView `source` — an inline source object was a
  new ref every render, so RN WebView reloaded the map, which re-posted its
  centre, which re-rendered... the endless "Locating… <-> address" flicker.
- MapView (new): read-only pin + coord Navigate, for the rider.
- 11 unit tests for the tile resolver + html builder.

rider-mobile:
- orders/[id]: embeds MapView on the pickup, and Navigate now uses the exact
  pickupLat/Lng (falls back to text only for older orders with no pin). A text
  address can resolve blocks away — the whole point of the map picker was the
  coords, and the rider was throwing them away.
- added react-native-webview + expo-location.

customer-mobile:
- components/MapPicker is now a thin wrapper injecting api.reverseGeocode + the
  env tile provider into the shared UI picker.

api — reverseGeocode gains a keyless OSM Nominatim fallback: the TomTom dev key
has Maps (tiles) scope but not Search, so reverse always returned null and the
picker showed raw lat/lng. Nominatim is keyless AND permits storing the result
(Mapbox geocoding forbids storage — we persist the label), so it's the correct
provider for our use. TomTom stays primary when its Search scope is enabled.

Tile provider (opt-in, no card needed for the free HD path):
  EXPO_PUBLIC_MAP_TILE_PROVIDER=maptiler|mapbox|tomtom|osm
  EXPO_PUBLIC_MAPTILER_KEY / EXPO_PUBLIC_MAPBOX_TOKEN / EXPO_PUBLIC_TOMTOM_MAP_KEY

NOTE: react-native-webview + expo-location are native — rebuild both apps
(`npx expo run:ios --device`) to pick them up.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: Banyel3

apps/api/src/maps/tomtom.provider.spec.ts

@@ -141,7 +141,29 @@ describe('TomTomProvider', () => {
       ).toBe('Tetuan, ZC');
     });
 
-    it('degrades to null when the Reverse Geocoding product is off (403)', async () => {
+    it('falls back to Nominatim when TomTom Search is off (403)', async () => {
+      const fetchFn = mockFetch((url) => {
+        if (url.includes('nominatim')) {
+          return {
+            ok: true,
+            status: 200,
+            body: {
+              address: {
+                road: 'Veterans Ave',
+                suburb: 'Tetuan',
+                city: 'Zamboanga City',
+              },
+            },
+          };
+        }
+        return { ok: false, status: 403, body: {} }; // TomTom reverse off
+      });
+      expect(
+        await new TomTomProvider(KEY, fetchFn).reverseGeocode({ lat: 1, lng: 1 }),
+      ).toBe('Veterans Ave, Tetuan, Zamboanga City');
+    });
+
+    it('degrades to null when both TomTom and Nominatim fail', async () => {
       const fetchFn = mockFetch(() => ({ ok: false, status: 403, body: {} }));
       expect(
         await new TomTomProvider(KEY, fetchFn).reverseGeocode({ lat: 1, lng: 1 }),

apps/api/src/maps/tomtom.provider.ts

@@ -7,7 +7,10 @@ import type {
 } from '@wash-and-go/maps';
 
 // Injectable fetch so specs can drive the adapter without real HTTP.
-export type FetchLike = (url: string) => Promise<{
+export type FetchLike = (
+  url: string,
+  init?: { headers?: Record<string, string> },
+) => Promise<{
   ok: boolean;
   status: number;
   json(): Promise<unknown>;
@@ -22,14 +25,34 @@ export type FetchLike = (url: string) => Promise<{
  * throw. Geocode failures also degrade to null so a booking never hard-fails on
  * a maps outage; route() throws (the caller needs a distance to price).
  */
+// Build a short, human label from a Nominatim reverse result: street (with
+// house number if present), barangay/suburb, city — skipping blanks and dupes.
+// Falls back to the full display_name if we can't assemble parts.
+function shortLabel(body: {
+  name?: string;
+  display_name?: string;
+  address?: Record<string, string>;
+}): string | undefined {
+  const a = body.address ?? {};
+  const street = [a.house_number, a.road ?? body.name].filter(Boolean).join(' ');
+  const area = a.neighbourhood ?? a.suburb ?? a.village ?? a.quarter;
+  const city = a.city ?? a.town ?? a.municipality ?? a.county;
+  const parts = [street || body.name, area, city].filter(
+    (p): p is string => !!p,
+  );
+  const seen = new Set<string>();
+  const label = parts.filter((p) => !seen.has(p) && seen.add(p)).join(', ');
+  return label || body.display_name || undefined;
+}
+
 export class TomTomProvider implements MapsProvider {
   readonly name = 'tomtom';
   private readonly logger = new Logger('TomTomProvider');
   private readonly base = 'https://api.tomtom.com';
 
   constructor(
     private readonly apiKey: string,
-    private readonly fetchFn: FetchLike = (url) => fetch(url),
+    private readonly fetchFn: FetchLike = (url, init) => fetch(url, init),
   ) {}
 
   async geocode(query: string): Promise<GeocodeResult | null> {
@@ -99,13 +122,42 @@ export class TomTomProvider implements MapsProvider {
       `?key=${this.apiKey}`;
     try {
       const res = await this.fetchFn(url);
-      if (!res.ok) return this.warnNull('reverseGeocode', res.status);
+      if (res.ok) {
+        const body = (await res.json()) as {
+          addresses?: { address?: { freeformAddress?: string } }[];
+        };
+        const label = body.addresses?.[0]?.address?.freeformAddress;
+        if (label) return label;
+      } else {
+        this.warnNull('reverseGeocode', res.status);
+      }
+    } catch (e) {
+      this.logger.warn(`reverseGeocode error: ${String(e)}`);
+    }
+    // Fallback: keyless OSM Nominatim. The dev TomTom key often has only the
+    // Maps (tiles) product enabled, not Search — so reverse returns a readable
+    // street name instead of raw coordinates. Nominatim policy: identify via
+    // User-Agent, keep it to ~1 req/s (the picker debounces to one call).
+    return this.nominatimReverse(point);
+  }
+
+  private async nominatimReverse(point: GeoPoint): Promise<string | null> {
+    const url =
+      `https://nominatim.openstreetmap.org/reverse?format=jsonv2` +
+      `&lat=${point.lat}&lon=${point.lng}&zoom=18&addressdetails=1`;
+    try {
+      const res = await this.fetchFn(url, {
+        headers: { 'User-Agent': 'WashAndGo/1.0 (pilot; Zamboanga)' },
+      });
+      if (!res.ok) return this.warnNull('nominatimReverse', res.status);
       const body = (await res.json()) as {
-        addresses?: { address?: { freeformAddress?: string } }[];
+        name?: string;
+        display_name?: string;
+        address?: Record<string, string>;
       };
-      return body.addresses?.[0]?.address?.freeformAddress ?? null;
+      return shortLabel(body) ?? null;
     } catch (e) {
-      this.logger.warn(`reverseGeocode error: ${String(e)}`);
+      this.logger.warn(`nominatimReverse error: ${String(e)}`);
       return null;
     }
   }

apps/customer-mobile/src/components/MapPicker.tsx

@@ -1,179 +1,29 @@
-import * as Location from 'expo-location';
-import React, { useCallback, useEffect, useRef, useState } from 'react';
-import { Modal, Pressable, StyleSheet, Text, View } from 'react-native';
-import { WebView, type WebViewMessageEvent } from 'react-native-webview';
-import { PrimaryButton, colors, space, type as typo } from '@wash-and-go/ui';
+import React from 'react';
+import { MapPicker as UIMapPicker, resolveTiles } from '@wash-and-go/ui';
 import { api } from '../lib/api';
 
-// Center-pin map picker (Grab/Uber style): the map moves under a fixed pin; the
-// map centre is the chosen point. TomTom tiles via Leaflet in a WebView (reuses
-// the TomTom key, cross-platform, no Google key). Replaces the unreliable
-// type-an-address flow.
-const KEY = process.env.EXPO_PUBLIC_TOMTOM_MAP_KEY ?? '';
-const ZAMBOANGA: [number, number] = [6.9214, 122.079];
-
-function mapHtml(lat: number, lng: number): string {
-  return `<!doctype html><html><head>
-<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no">
-<link rel="stylesheet" href="https://unpkg.com/leaflet@1.9.4/dist/leaflet.css"/>
-<style>
-  html,body,#map{height:100%;margin:0;padding:0;background:#e7eef5}
-  #pin{position:absolute;top:50%;left:50%;transform:translate(-50%,-100%);font-size:40px;z-index:1000;pointer-events:none;filter:drop-shadow(0 3px 3px rgba(0,0,0,.35))}
-</style></head><body>
-<div id="map"></div><div id="pin">📍</div>
-<script src="https://unpkg.com/leaflet@1.9.4/dist/leaflet.js"></script>
-<script>
-  var map = L.map('map',{zoomControl:false,attributionControl:false}).setView([${lat},${lng}],16);
-  L.tileLayer('https://api.tomtom.com/map/1/tile/basic/main/{z}/{x}/{y}.png?key=${KEY}',{maxZoom:22,minZoom:5}).addTo(map);
-  function post(){var c=map.getCenter();window.ReactNativeWebView.postMessage(JSON.stringify({lat:c.lat,lng:c.lng}));}
-  map.on('moveend', post);
-  setTimeout(post, 300);
-</script></body></html>`;
-}
+// App-local wrapper: injects this app's API client (reverse-geocode) and the
+// tile provider resolved from env into the shared UI picker. Tile provider is
+// pluggable — set EXPO_PUBLIC_MAP_TILE_PROVIDER=maptiler|mapbox|tomtom|osm and
+// the matching key; falls back to the sharpest key present, then keyless OSM.
+const tiles = resolveTiles({
+  provider: process.env.EXPO_PUBLIC_MAP_TILE_PROVIDER,
+  mapboxToken: process.env.EXPO_PUBLIC_MAPBOX_TOKEN,
+  mapTilerKey: process.env.EXPO_PUBLIC_MAPTILER_KEY,
+  tomtomKey: process.env.EXPO_PUBLIC_TOMTOM_MAP_KEY,
+});
 
-export function MapPicker({
-  visible,
-  initial,
-  onClose,
-  onPick,
-}: {
+export function MapPicker(props: {
   visible: boolean;
   initial?: { lat: number; lng: number } | null;
   onClose: () => void;
   onPick: (p: { lat: number; lng: number; address: string }) => void;
 }) {
-  const [center, setCenter] = useState<[number, number] | null>(null);
-  const [coords, setCoords] = useState<{ lat: number; lng: number } | null>(null);
-  const [label, setLabel] = useState<string>('Move the map to your pickup point');
-  const [resolving, setResolving] = useState(false);
-  const revTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
-
-  // Decide the starting centre once the sheet opens: passed-in point → device
-  // GPS → Zamboanga fallback.
-  useEffect(() => {
-    if (!visible) {
-      setCenter(null);
-      return;
-    }
-    let cancelled = false;
-    (async () => {
-      if (initial) {
-        if (!cancelled) setCenter([initial.lat, initial.lng]);
-        return;
-      }
-      try {
-        const perm = await Location.getForegroundPermissionsAsync();
-        if (perm.status === 'granted') {
-          const pos = await Location.getCurrentPositionAsync({
-            accuracy: Location.Accuracy.Balanced,
-          });
-          if (!cancelled) {
-            setCenter([pos.coords.latitude, pos.coords.longitude]);
-            return;
-          }
-        }
-      } catch {
-        // fall through to default
-      }
-      if (!cancelled) setCenter(ZAMBOANGA);
-    })();
-    return () => {
-      cancelled = true;
-    };
-  }, [visible, initial]);
-
-  const onMessage = useCallback((e: WebViewMessageEvent) => {
-    let c: { lat: number; lng: number };
-    try {
-      c = JSON.parse(e.nativeEvent.data);
-    } catch {
-      return;
-    }
-    setCoords(c);
-    // Debounce the reverse-geocode — one call after the map settles.
-    if (revTimer.current) clearTimeout(revTimer.current);
-    setResolving(true);
-    revTimer.current = setTimeout(async () => {
-      try {
-        const { label: l } = await api.reverseGeocode(c.lat, c.lng);
-        setLabel(l ?? `${c.lat.toFixed(5)}, ${c.lng.toFixed(5)}`);
-      } catch {
-        setLabel(`${c.lat.toFixed(5)}, ${c.lng.toFixed(5)}`);
-      } finally {
-        setResolving(false);
-      }
-    }, 450);
-  }, []);
-
-  const confirm = () => {
-    if (!coords) return;
-    onPick({ lat: coords.lat, lng: coords.lng, address: label });
-  };
-
   return (
-    <Modal visible={visible} animationType="slide" onRequestClose={onClose}>
-      <View style={styles.root}>
-        {center ? (
-          <WebView
-            style={{ flex: 1 }}
-            originWhitelist={['*']}
-            source={{ html: mapHtml(center[0], center[1]) }}
-            onMessage={onMessage}
-            scrollEnabled={false}
-          />
-        ) : (
-          <View style={styles.loading}>
-            <Text style={typo.body}>Getting your location…</Text>
-          </View>
-        )}
-
-        <Pressable onPress={onClose} style={styles.close} accessibilityRole="button">
-          <Text style={styles.closeText}>✕</Text>
-        </Pressable>
-
-        <View style={styles.sheet}>
-          <Text style={styles.sheetLabel} numberOfLines={2}>
-            {resolving ? 'Locating…' : label}
-          </Text>
-          <PrimaryButton
-            label="Use this location"
-            onPress={confirm}
-            disabled={!coords}
-            testID="map-confirm"
-          />
-        </View>
-      </View>
-    </Modal>
+    <UIMapPicker
+      {...props}
+      tiles={tiles}
+      reverseGeocode={(lat, lng) => api.reverseGeocode(lat, lng)}
+    />
   );
 }
-
-const styles = StyleSheet.create({
-  root: { flex: 1, backgroundColor: colors.bg },
-  loading: { flex: 1, alignItems: 'center', justifyContent: 'center' },
-  close: {
-    position: 'absolute',
-    top: 52,
-    left: 16,
-    width: 40,
-    height: 40,
-    borderRadius: 20,
-    backgroundColor: colors.surface,
-    alignItems: 'center',
-    justifyContent: 'center',
-    shadowColor: '#000',
-    shadowOpacity: 0.18,
-    shadowRadius: 6,
-    shadowOffset: { width: 0, height: 2 },
-    elevation: 4,
-  },
-  closeText: { fontSize: 18, color: colors.text, fontWeight: '700' },
-  sheet: {
-    padding: space.lg,
-    paddingBottom: space.xl,
-    gap: space.md,
-    backgroundColor: colors.surface,
-    borderTopLeftRadius: 20,
-    borderTopRightRadius: 20,
-  },
-  sheetLabel: { ...typo.title, color: colors.text },
-});

apps/rider-mobile/package.json

@@ -20,6 +20,7 @@
     "expo-constants": "~57.0.6",
     "expo-font": "^57.0.1",
     "expo-linking": "~57.0.3",
+    "expo-location": "~57.0.5",
     "expo-router": "~57.0.7",
     "expo-splash-screen": "~57.0.4",
     "expo-status-bar": "~57.0.1",
@@ -31,6 +32,7 @@
     "react-native-reanimated": "4.5.0",
     "react-native-safe-area-context": "~5.7.0",
     "react-native-screens": "4.25.2",
+    "react-native-webview": "13.16.1",
     "react-native-web": "~0.21.0",
     "react-native-worklets": "0.10.0",
     "firebase": "^12.16.0",