@multiplatform.one/forms 6.0.4 → 6.3.0

package/src/fields/Geolocation/Geolocation.spec.tsx

@@ -1,7 +1,8 @@
-import { describe, expect, it, vi } from "vitest";
+import { describe, expect, it, vi, afterEach } from "vitest";
+import { fireEvent, waitFor } from "@testing-library/react";
 import { renderWithProviders } from "@multiplatform.one/test-utils";
 import { Form } from "../../Form";
-import { Geolocation } from "./index";
+import { Geolocation, preflightGeolocation } from "./index";
 
 const locationIcon = <span data-testid="location-icon" />;
 
@@ -22,12 +23,73 @@ describe("Geolocation", () => {
       expect(label?.textContent).toContain("*");
     });
 
-    it("renders Lat and Lng inputs", () => {
+    // UX-010 / Axiom 13 ONE BODY: bare use renders the full locate affordance.
+    it("renders bare without locationIcon — package default glyph on Locate", () => {
       const result = renderWithProviders(
-        <Geolocation label="Location" name="loc" locationIcon={locationIcon} />,
+        <Geolocation label="Bare" value={JSON.stringify({ lat: 1, lng: 2 })} />,
+      );
+      const locate = result.container.querySelector("[aria-label='Locate']");
+      expect(locate).not.toBeNull();
+      expect(locate?.querySelector("svg")).not.toBeNull();
+    });
+
+    it("renders map-primary surface without inline Lat/Lng inputs", () => {
+      const result = renderWithProviders(
+        <Geolocation
+          label="Location"
+          name="loc"
+          locationIcon={locationIcon}
+          value={JSON.stringify({ lat: 51.5, lng: -0.12 })}
+        />,
+      );
+      expect(result.container.querySelector("[data-testid='geolocation-map']")).not.toBeNull();
+      expect(
+        result.container.querySelector("[data-testid='geolocation-coords-chip']"),
+      ).not.toBeNull();
+      expect(result.container.textContent).toContain("51.5000, -0.1200");
+      // Lat/Lng inputs are NOT always-visible under the map
+      expect(result.container.querySelector("input")).toBeNull();
+      expect(result.container.querySelector("[aria-label='Edit coordinates']")).not.toBeNull();
+      expect(result.container.querySelector("[aria-label='Locate']")).not.toBeNull();
+    });
+
+    it("coordinates FloatingPanel commits live — no Apply button", async () => {
+      const onChange = vi.fn();
+      const result = renderWithProviders(
+        <Geolocation
+          label="Location"
+          name="loc"
+          locationIcon={locationIcon}
+          value={JSON.stringify({ lat: 10, lng: 20 })}
+          onChange={onChange}
+        />,
       );
-      expect(result.findTextElement("Lat")).toBeDefined();
-      expect(result.findTextElement("Lng")).toBeDefined();
+      fireEvent.click(result.container.querySelector("[aria-label='Edit coordinates']") as Element);
+      // Sheet mode portals outside the field container — query document.
+      await waitFor(() => {
+        expect(document.querySelector("[data-testid='geolocation-coords-panel']")).not.toBeNull();
+      });
+      // LC-21 EDITOR: no Apply / Cancel / Done affordance — dismiss is outside/Escape
+      expect(document.querySelector("[aria-label='Apply coordinates']")).toBeNull();
+      expect(document.querySelector("[aria-label='Cancel coordinates']")).toBeNull();
+      expect(document.body.textContent).not.toMatch(/\bApply\b/);
+      expect(document.body.textContent).not.toMatch(/\bCancel\b/);
+      expect(document.body.textContent).not.toMatch(/\bDone\b/);
+
+      const latInput = document.querySelector("input[aria-label='Latitude']") as HTMLInputElement;
+      const lngInput = document.querySelector("input[aria-label='Longitude']") as HTMLInputElement;
+      expect(latInput).not.toBeNull();
+      expect(lngInput).not.toBeNull();
+
+      // Valid parse commits live (as soon as the number is set)
+      fireEvent.change(latInput, { target: { value: "12.34" } });
+      await waitFor(() => {
+        expect(onChange).toHaveBeenCalledWith(JSON.stringify({ lat: 12.34, lng: 20 }));
+      });
+      fireEvent.change(lngInput, { target: { value: "56.78" } });
+      await waitFor(() => {
+        expect(onChange).toHaveBeenCalledWith(JSON.stringify({ lat: 12.34, lng: 56.78 }));
+      });
     });
 
     it("renders with helper text", () => {
@@ -42,14 +104,16 @@ describe("Geolocation", () => {
       expect(result.findTextElement("Pick a point")).toBeDefined();
     });
 
-    it("renders skeleton placeholder", () => {
+    it("renders skeleton placeholder as map-only", () => {
       const result = renderWithProviders(
         <Geolocation label="Loading" name="l" locationIcon={locationIcon} skeleton />,
       );
-      expect(result.findTextElement("Lat")).toBeUndefined();
+      expect(result.container.querySelector("[data-testid='geolocation-map']")).toBeNull();
+      expect(result.container.querySelector("[aria-label='Locate']")).toBeNull();
+      expect(result.container.querySelector("input")).toBeNull();
     });
 
-    it("renders readOnly — hides locate button", () => {
+    it("renders readOnly — hides locate and coordinates overlay controls", () => {
       const result = renderWithProviders(
         <Geolocation
           label="ReadOnly"
@@ -59,21 +123,141 @@ describe("Geolocation", () => {
           value={JSON.stringify({ lat: 1.23, lng: 4.56 })}
         />,
       );
-      expect(result.findTextElement("Locate")).toBeUndefined();
+      expect(result.container.querySelector("[aria-label='Locate']")).toBeNull();
+      expect(result.container.querySelector("[aria-label='Edit coordinates']")).toBeNull();
+      expect(
+        result.container.querySelector("[data-testid='geolocation-coords-chip']"),
+      ).not.toBeNull();
+    });
+  });
+
+  describe("geolocation pre-flight (LC-19 CAPABILITY-PREFLIGHT)", () => {
+    afterEach(() => {
+      vi.unstubAllGlobals();
+      vi.restoreAllMocks();
+    });
+
+    it("preflightGeolocation fails when no geolocation capability exists", async () => {
+      vi.stubGlobal("navigator", {
+        ...navigator,
+        geolocation: undefined,
+        permissions: undefined,
+      });
+      const result = await preflightGeolocation();
+      expect(result).toEqual({
+        ok: false,
+        reason: expect.stringContaining("Geolocation unavailable"),
+      });
+    });
+
+    it("preflightGeolocation fails when permission is hard-denied", async () => {
+      vi.stubGlobal("navigator", {
+        ...navigator,
+        geolocation: { getCurrentPosition: vi.fn() },
+        permissions: {
+          query: vi.fn().mockResolvedValue({ state: "denied" }),
+        },
+      });
+      const result = await preflightGeolocation();
+      expect(result).toEqual({
+        ok: false,
+        reason: expect.stringContaining("permission denied"),
+      });
+    });
+
+    it("preflightGeolocation passes when permission is prompt", async () => {
+      vi.stubGlobal("navigator", {
+        ...navigator,
+        geolocation: { getCurrentPosition: vi.fn() },
+        permissions: {
+          query: vi.fn().mockResolvedValue({ state: "prompt" }),
+        },
+      });
+      const result = await preflightGeolocation();
+      expect(result).toEqual({ ok: true });
+    });
+
+    it("locate press without geolocation shows inline error and never mounts the locate panel", async () => {
+      vi.stubGlobal("navigator", {
+        ...navigator,
+        geolocation: undefined,
+        permissions: undefined,
+      });
+      const result = renderWithProviders(
+        <Geolocation label="Location" name="loc" locationIcon={locationIcon} />,
+      );
+      const button = result.container.querySelector("[aria-label='Locate']");
+      expect(button).not.toBeNull();
+      fireEvent.click(button as Element);
+      await waitFor(() => {
+        expect(result.container.textContent).toContain("Geolocation unavailable");
+      });
+      expect(result.container.querySelector("[data-testid='geolocation-locate-panel']")).toBeNull();
+      expect((button as HTMLElement).getAttribute("aria-disabled")).not.toBe("true");
     });
 
-    it("displays parsed coordinate values", () => {
+    it("denied permission pre-flight shows inline error without mounting locate panel", async () => {
+      const getCurrentPosition = vi.fn();
+      vi.stubGlobal("navigator", {
+        ...navigator,
+        geolocation: { getCurrentPosition },
+        permissions: {
+          query: vi.fn().mockResolvedValue({ state: "denied" }),
+        },
+      });
       const result = renderWithProviders(
-        <Geolocation
-          label="Location"
-          name="loc"
-          locationIcon={locationIcon}
-          value={JSON.stringify({ lat: 51.5, lng: -0.12 })}
-        />,
+        <Geolocation label="Location" name="loc" locationIcon={locationIcon} />,
+      );
+      fireEvent.click(result.container.querySelector("[aria-label='Locate']") as Element);
+      await waitFor(() => {
+        expect(result.container.textContent).toContain("permission denied");
+      });
+      expect(result.container.querySelector("[data-testid='geolocation-locate-panel']")).toBeNull();
+      expect(getCurrentPosition).not.toHaveBeenCalled();
+    });
+
+    it("post-preflight failure keeps the locate panel open with Retry", async () => {
+      const getCurrentPosition = vi.fn(
+        (_success: PositionCallback, error?: PositionErrorCallback | null) => {
+          error?.({
+            code: 3,
+            message: "Timeout expired",
+            PERMISSION_DENIED: 1,
+            POSITION_UNAVAILABLE: 2,
+            TIMEOUT: 3,
+          } as GeolocationPositionError);
+        },
       );
-      const inputs = result.container.querySelectorAll("input");
-      expect(inputs[0]?.value).toBe("51.5");
-      expect(inputs[1]?.value).toBe("-0.12");
+      vi.stubGlobal("navigator", {
+        ...navigator,
+        geolocation: { getCurrentPosition },
+        permissions: {
+          query: vi.fn().mockResolvedValue({ state: "granted" }),
+        },
+      });
+
+      const result = renderWithProviders(
+        <Geolocation label="Location" name="loc" locationIcon={locationIcon} />,
+      );
+      fireEvent.click(result.container.querySelector("[aria-label='Locate']") as Element);
+
+      await waitFor(() => {
+        expect(
+          result.container.querySelector("[data-testid='geolocation-locate-panel']"),
+        ).not.toBeNull();
+        expect(result.container.textContent).toContain("timed out");
+      });
+      const retry = result.container.querySelector("[aria-label='Retry location']");
+      expect(retry).not.toBeNull();
+      expect(getCurrentPosition).toHaveBeenCalledTimes(1);
+
+      fireEvent.click(retry as Element);
+      await waitFor(() => {
+        expect(getCurrentPosition).toHaveBeenCalledTimes(2);
+      });
+      expect(
+        result.container.querySelector("[data-testid='geolocation-locate-panel']"),
+      ).not.toBeNull();
     });
   });
 

package/src/fields/Geolocation/Geolocation.stories.tsx

@@ -15,7 +15,7 @@ const meta: Meta<typeof Geolocation> = {
     docs: {
       description: {
         component:
-          "A geolocation input field with map preview, latitude/longitude inputs, and browser geolocation support. Accepts a custom `renderMap` prop for interactive maps.",
+          "Map-primary geolocation field: the map is the primary surface. Locate and Coordinates are map overlays; Lat/Lng edit live in a FloatingPanel (no Apply — LC-21 dismiss-by-intent). LC-19 preflight gates Locate. Accepts a custom `renderMap` prop for interactive maps.",
       },
     },
   },
@@ -67,15 +67,28 @@ export const Main: Story = {
 export const Standalone: Story = {
   args: {
     label: "Location",
-    helperText: "Enter coordinates or use your location",
+    helperText: "Use Locate on the map, or open Coordinates to type Lat/Lng",
   },
   render: (args) => <Geolocation {...args} locationIcon={<NavigationArrowIcon size={16} />} />,
 };
 
+/**
+ * Bare contract (UX-010 / Axiom 13 ONE BODY): no `locationIcon` — the package
+ * default navigation-arrow glyph renders on the Locate overlay.
+ */
+export const Bare: Story = {
+  args: {
+    label: "Location",
+    helperText: "No locationIcon prop — package default glyph",
+    value: JSON.stringify({ lat: 48.8566, lng: 2.3522 }),
+    onChange: action("onChange"),
+  },
+};
+
 export const Basic: Story = {
   args: {
     label: "Location",
-    helperText: "Enter coordinates or use your location",
+    helperText: "Use Locate on the map, or open Coordinates to type Lat/Lng",
     onChange: action("onChange"),
   },
   render: (args) => <Geolocation {...args} locationIcon={<NavigationArrowIcon size={16} />} />,
@@ -94,7 +107,7 @@ export const Disabled: Story = {
 export const WithError: Story = {
   args: {
     label: "Location",
-    helperText: "Enter coordinates or use your location",
+    helperText: "Use Locate on the map, or open Coordinates to type Lat/Lng",
     required: true,
     error: "Location is required",
     onChange: action("onChange"),
@@ -233,3 +246,9 @@ export const ExpandableInForm: Story = {
     return <FormExample />;
   },
 };
+
+/** Loading placeholder — the skeleton mirrors the field + map anatomy (LC-20 / DG-ST-02). */
+export const SkeletonState: Story = {
+  render: (args) => <Geolocation {...args} locationIcon={<NavigationArrowIcon size={16} />} />,
+  args: { label: "Location", skeleton: true },
+};

package/src/fields/Geolocation/GeolocationMap.native.spec.tsx

@@ -0,0 +1,188 @@
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import React, { useImperativeHandle } from "react";
+import { Platform } from "react-native";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { Geolocation } from "./index";
+import { GeolocationMap } from "./GeolocationMap.native";
+import { loadExpoMaps } from "./expoMapsLoader";
+
+// The optional-peer loader is the mock seam: on-device it try/catch-requires
+// `expo-maps` (Metro optional dependency); here we swap the module wholesale.
+vi.mock("./expoMapsLoader", () => ({
+  loadExpoMaps: vi.fn(() => null),
+}));
+
+const loadExpoMapsMock = vi.mocked(loadExpoMaps);
+
+type AnyProps = Record<string, any>;
+
+let appleProps: AnyProps | null = null;
+let googleProps: AnyProps | null = null;
+const setCameraPosition = vi.fn();
+
+/** Reset captured props inside a function so TS flow analysis can't narrow the lets to `null`. */
+function resetCapturedProps() {
+  appleProps = null;
+  googleProps = null;
+}
+
+function createMapsMock() {
+  function AppleView(props: AnyProps) {
+    appleProps = props;
+    useImperativeHandle(props.ref, () => ({ setCameraPosition }));
+    return React.createElement("div", { "data-testid": "apple-maps-view" });
+  }
+  function GoogleView(props: AnyProps) {
+    googleProps = props;
+    useImperativeHandle(props.ref, () => ({ setCameraPosition }));
+    return React.createElement("div", { "data-testid": "google-maps-view" });
+  }
+  return {
+    AppleMaps: { View: AppleView },
+    GoogleMaps: { View: GoogleView },
+  } as unknown as NonNullable<ReturnType<typeof loadExpoMaps>>;
+}
+
+describe("GeolocationMap (native)", () => {
+  beforeEach(() => {
+    appleProps = null;
+    googleProps = null;
+    setCameraPosition.mockClear();
+    loadExpoMapsMock.mockReset();
+    loadExpoMapsMock.mockReturnValue(null);
+  });
+
+  afterEach(() => {
+    (Platform as AnyProps).OS = "web";
+  });
+
+  it("renders the Apple map with the value marker on iOS", () => {
+    (Platform as AnyProps).OS = "ios";
+    loadExpoMapsMock.mockReturnValue(createMapsMock());
+    const onChange = vi.fn();
+    const result = renderWithProviders(
+      <GeolocationMap lat={51.5} lng={-0.12} onChange={onChange} />,
+    );
+    expect(result.getByTestId("apple-maps-view")).toBeTruthy();
+    expect(result.container.querySelector("[data-testid='geolocation-native-map']")).not.toBeNull();
+    expect(appleProps?.markers).toEqual([
+      expect.objectContaining({ coordinates: { latitude: 51.5, longitude: -0.12 } }),
+    ]);
+    expect(appleProps?.cameraPosition).toEqual({
+      coordinates: { latitude: 51.5, longitude: -0.12 },
+      zoom: 13,
+    });
+  });
+
+  it("tap on the Apple map commits picked coordinates through onChange", () => {
+    (Platform as AnyProps).OS = "ios";
+    loadExpoMapsMock.mockReturnValue(createMapsMock());
+    const onChange = vi.fn();
+    renderWithProviders(<GeolocationMap lat={10} lng={20} onChange={onChange} />);
+    appleProps?.onMapClick?.({ coordinates: { latitude: 12.5, longitude: 99.25 } });
+    expect(onChange).toHaveBeenCalledWith(12.5, 99.25);
+    // Apple has no long-press pick in expo-maps SDK 55 — tap only.
+    expect(appleProps?.onMapLongClick).toBeUndefined();
+  });
+
+  it("renders the Google map on Android with tap and long-press pick", () => {
+    (Platform as AnyProps).OS = "android";
+    loadExpoMapsMock.mockReturnValue(createMapsMock());
+    const onChange = vi.fn();
+    const result = renderWithProviders(<GeolocationMap lat={10} lng={20} onChange={onChange} />);
+    expect(result.getByTestId("google-maps-view")).toBeTruthy();
+    expect(googleProps?.markers).toEqual([
+      expect.objectContaining({ coordinates: { latitude: 10, longitude: 20 } }),
+    ]);
+    googleProps?.onMapClick?.({ coordinates: { latitude: 1.5, longitude: 2.5 } });
+    expect(onChange).toHaveBeenCalledWith(1.5, 2.5);
+    googleProps?.onMapLongClick?.({ coordinates: { latitude: -3, longitude: -4 } });
+    expect(onChange).toHaveBeenCalledWith(-3, -4);
+  });
+
+  it("does not attach pick handlers when disabled or readOnly", () => {
+    (Platform as AnyProps).OS = "ios";
+    loadExpoMapsMock.mockReturnValue(createMapsMock());
+    const onChange = vi.fn();
+
+    renderWithProviders(<GeolocationMap lat={10} lng={20} onChange={onChange} disabled />);
+    expect(appleProps?.onMapClick).toBeUndefined();
+
+    resetCapturedProps();
+    renderWithProviders(<GeolocationMap lat={10} lng={20} onChange={onChange} readOnly />);
+    expect(appleProps?.onMapClick).toBeUndefined();
+    expect(onChange).not.toHaveBeenCalled();
+  });
+
+  it("ignores click events without numeric coordinates", () => {
+    (Platform as AnyProps).OS = "ios";
+    loadExpoMapsMock.mockReturnValue(createMapsMock());
+    const onChange = vi.fn();
+    renderWithProviders(<GeolocationMap lat={10} lng={20} onChange={onChange} />);
+    appleProps?.onMapClick?.({ coordinates: {} });
+    appleProps?.onMapClick?.({});
+    expect(onChange).not.toHaveBeenCalled();
+  });
+
+  it("recenters the camera when the bound value changes after mount", () => {
+    (Platform as AnyProps).OS = "ios";
+    loadExpoMapsMock.mockReturnValue(createMapsMock());
+    const onChange = vi.fn();
+    const result = renderWithProviders(<GeolocationMap lat={10} lng={20} onChange={onChange} />);
+    // Initial mount uses the declarative cameraPosition — no imperative call.
+    expect(setCameraPosition).not.toHaveBeenCalled();
+    result.rerender(<GeolocationMap lat={11} lng={21} onChange={onChange} />);
+    expect(setCameraPosition).toHaveBeenCalledWith({
+      coordinates: { latitude: 11, longitude: 21 },
+      zoom: 13,
+    });
+  });
+
+  it("falls back to the placeholder when expo-maps is absent", () => {
+    (Platform as AnyProps).OS = "ios";
+    loadExpoMapsMock.mockReturnValue(null);
+    const result = renderWithProviders(<GeolocationMap lat={51.5} lng={-0.12} />);
+    const fallback = result.container.querySelector("[data-testid='geolocation-map-fallback']");
+    expect(fallback).not.toBeNull();
+    expect(result.container.textContent).toContain("Map preview unavailable");
+    expect(result.container.textContent).toContain("51.5000, -0.1200");
+    expect(result.container.querySelector("[data-testid='apple-maps-view']")).toBeNull();
+  });
+
+  it("falls back to the placeholder on platforms without a native map", () => {
+    // Platform.OS stays "web" (react-native-web default in this environment).
+    loadExpoMapsMock.mockReturnValue(createMapsMock());
+    const result = renderWithProviders(<GeolocationMap lat={1} lng={2} />);
+    expect(
+      result.container.querySelector("[data-testid='geolocation-map-fallback']"),
+    ).not.toBeNull();
+    expect(appleProps).toBeNull();
+    expect(googleProps).toBeNull();
+  });
+});
+
+describe("Geolocation field map wiring", () => {
+  it("map picks commit through the field's existing onChange path (clamped JSON)", () => {
+    const onChange = vi.fn();
+    // renderMap receives the same onChange handler the built-in platform map
+    // uses (makeHandlers.onMapChange) — proves pick → commit wiring.
+    let mapProps: { onChange: (lat: number, lng: number) => void } | null = null;
+    renderWithProviders(
+      <Geolocation
+        label="Location"
+        name="loc"
+        locationIcon={<span data-testid="location-icon" />}
+        value={JSON.stringify({ lat: 10, lng: 20 })}
+        onChange={onChange}
+        renderMap={(props) => {
+          mapProps = props;
+          return null;
+        }}
+      />,
+    );
+    mapProps!.onChange(12.5, 99.25);
+    expect(onChange).toHaveBeenCalledWith(JSON.stringify({ lat: 12.5, lng: 99.25 }));
+    mapProps!.onChange(1234, -5678);
+    expect(onChange).toHaveBeenCalledWith(JSON.stringify({ lat: 90, lng: -180 }));
+  });
+});

package/src/fields/Geolocation/GeolocationMap.native.tsx

@@ -0,0 +1,134 @@
+import { useEffect, useRef } from "react";
+import { Platform } from "react-native";
+import { Text, YStack } from "tamagui";
+// Type-only imports are erased at runtime — the value module loads through
+// `loadExpoMaps` so the peer stays optional (Video / expo-video precedent).
+import type { AppleMaps as AppleMapsNS, GoogleMaps as GoogleMapsNS } from "expo-maps";
+import { t } from "../../shared/t";
+import { loadExpoMaps } from "./expoMapsLoader";
+import type { GeolocationMapSurfaceProps } from "./mapTypes";
+
+interface MapClickEvent {
+  coordinates?: { latitude?: number; longitude?: number };
+}
+
+/**
+ * The web surface expresses viewport as a bbox half-size in degrees; expo-maps
+ * wants a tile zoom level. 360° spans zoom 0, halving per level.
+ */
+function zoomFromDelta(delta: number): number {
+  const clamped = Math.min(Math.max(delta, 0.0005), 45);
+  return Math.max(1, Math.min(20, Math.round(Math.log2(360 / (clamped * 2)))));
+}
+
+/**
+ * Placeholder when no native map can render (module absent — e.g. Expo Go or
+ * a consumer that skipped the optional peer — or an unsupported platform).
+ */
+function MapFallback({ lat, lng, minHeight }: { lat: number; lng: number; minHeight?: number }) {
+  return (
+    <YStack
+      testID="geolocation-map-fallback"
+      flex={1}
+      minHeight={minHeight}
+      alignItems="center"
+      justifyContent="center"
+      backgroundColor="$backgroundHover"
+      gap="$1"
+    >
+      <Text color="$colorSubtle" fontSize="$2">
+        {t("Map preview unavailable — requires expo-maps")}
+      </Text>
+      <Text color="$colorSubtle" fontSize="$1">
+        {`${lat.toFixed(4)}, ${lng.toFixed(4)}`}
+      </Text>
+    </YStack>
+  );
+}
+
+/**
+ * Native map surface — a real map through the optional `expo-maps` peer
+ * (SDK 55+): Apple Maps on iOS, Google Maps on Android (mirrors the
+ * components Video / expo-video split). The marker mirrors the bound value;
+ * tap (and long-press on Android) picks a coordinate and commits through the
+ * field's existing onChange path. When the module is missing the surface
+ * degrades to the placeholder instead of crashing — `loadExpoMaps` requires
+ * it as a Metro optional dependency.
+ */
+export function GeolocationMap({
+  lat,
+  lng,
+  delta = 0.02,
+  minHeight,
+  onChange,
+  disabled,
+  readOnly,
+}: GeolocationMapSurfaceProps) {
+  const maps = loadExpoMaps();
+  const appleRef = useRef<AppleMapsNS.MapView | null>(null);
+  const googleRef = useRef<GoogleMapsNS.MapView | null>(null);
+  const mountedRef = useRef(false);
+  const zoom = zoomFromDelta(delta);
+
+  // `cameraPosition` is initial-only in expo-maps: follow later value changes
+  // (Locate, coordinates panel, pick) so the marker never leaves the viewport.
+  useEffect(() => {
+    if (!mountedRef.current) {
+      mountedRef.current = true;
+      return;
+    }
+    const view = appleRef.current ?? googleRef.current;
+    view?.setCameraPosition({ coordinates: { latitude: lat, longitude: lng }, zoom });
+  }, [lat, lng, zoom]);
+
+  if (!maps || (Platform.OS !== "ios" && Platform.OS !== "android")) {
+    return <MapFallback lat={lat} lng={lng} minHeight={minHeight} />;
+  }
+
+  const interactive = !disabled && !readOnly && typeof onChange === "function";
+  const handlePick = interactive
+    ? (event: MapClickEvent) => {
+        const { latitude, longitude } = event?.coordinates ?? {};
+        if (typeof latitude !== "number" || typeof longitude !== "number") return;
+        onChange?.(latitude, longitude);
+      }
+    : undefined;
+
+  const cameraPosition = { coordinates: { latitude: lat, longitude: lng }, zoom };
+  const markers = [
+    {
+      id: "geolocation-value",
+      coordinates: { latitude: lat, longitude: lng },
+      title: t("Selected location"),
+    },
+  ];
+
+  if (Platform.OS === "ios") {
+    const AppleMapsView = maps.AppleMaps.View;
+    return (
+      <YStack testID="geolocation-native-map" flex={1} minHeight={minHeight}>
+        <AppleMapsView
+          ref={appleRef}
+          style={{ flex: 1 }}
+          cameraPosition={cameraPosition}
+          markers={markers}
+          onMapClick={handlePick}
+        />
+      </YStack>
+    );
+  }
+
+  const GoogleMapsView = maps.GoogleMaps.View;
+  return (
+    <YStack testID="geolocation-native-map" flex={1} minHeight={minHeight}>
+      <GoogleMapsView
+        ref={googleRef}
+        style={{ flex: 1 }}
+        cameraPosition={cameraPosition}
+        markers={markers}
+        onMapClick={handlePick}
+        onMapLongClick={handlePick}
+      />
+    </YStack>
+  );
+}

package/src/fields/Geolocation/GeolocationMap.tsx

@@ -0,0 +1,36 @@
+import { useMemo } from "react";
+import { t } from "../../shared/t";
+import type { GeolocationMapSurfaceProps } from "./mapTypes";
+
+function useMapSrc(lat: number, lng: number, delta: number) {
+  return useMemo(() => {
+    const bbox = `${lng - delta},${lat - delta},${lng + delta},${lat + delta}`;
+    return `https://www.openstreetmap.org/export/embed.html?bbox=${bbox}&layer=mapnik&marker=${lat},${lng}`;
+  }, [lat, lng, delta]);
+}
+
+/**
+ * Web map surface — OpenStreetMap embed with the value marker. Picking
+ * happens through the Coordinates panel / Locate on web (the embed pans
+ * internally but does not report clicks). The interactive native map lives in
+ * `GeolocationMap.native.tsx` behind the optional `expo-maps` peer.
+ */
+export function GeolocationMap({
+  lat,
+  lng,
+  delta = 0.02,
+  minHeight,
+  title = t("Location preview"),
+}: GeolocationMapSurfaceProps) {
+  const src = useMapSrc(lat, lng, delta);
+  return (
+    <iframe
+      title={title}
+      src={src}
+      width="100%"
+      height="100%"
+      style={{ border: 0, display: "block", ...(minHeight ? { minHeight } : {}) }}
+      loading="lazy"
+    />
+  );
+}