@multiplatform.one/forms 7.7.4 → 7.8.0

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

@@ -2,9 +2,40 @@ 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 { TableCellContext } from "../../shared/tableCellContext";
 import { Geolocation, preflightGeolocation } from "./index";
+import type { GeocodeResult } from "./geocoder";
+import { Theme } from "tamagui";
+import { NavigationArrowIcon } from "@phosphor-icons/react";
 
 const locationIcon = <span data-testid="location-icon" />;
+const HELSINKI = JSON.stringify({ lat: 60.16952, lng: 24.93545 });
+
+const mannerheim: GeocodeResult = {
+  lat: 60.16952,
+  lng: 24.93545,
+  label: "Mannerheimintie 3",
+  description: "Kamppi, Helsinki, Finland",
+};
+
+function mockGeocode(results: GeocodeResult[] = [mannerheim]) {
+  return vi.fn().mockResolvedValue(results);
+}
+
+function mockReverse(result: GeocodeResult | null = mannerheim) {
+  return vi.fn().mockResolvedValue(result);
+}
+
+function searchInput(container: HTMLElement | Document = document) {
+  return (container.querySelector("[data-testid='geolocation-search']") ??
+    container.querySelector("[aria-label='Search for a location']")) as HTMLInputElement | null;
+}
+
+function typeSearch(container: HTMLElement, text: string) {
+  const input = searchInput(container);
+  expect(input).not.toBeNull();
+  fireEvent.change(input as HTMLInputElement, { target: { value: text } });
+}
 
 /**
  * Recorded stock-Frappe Geolocation value: what
@@ -69,50 +100,268 @@ describe("Geolocation", () => {
       expect(label?.textContent).toContain("*");
     });
 
-    // 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="Bare" value={JSON.stringify({ lat: 1, lng: 2 })} />,
-      );
+      const result = renderWithProviders(<Geolocation label="Bare" value={HELSINKI} />);
       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", () => {
+    it.each(["light", "dark"] as const)(
+      "paints the default Locate glyph with concrete %s ink",
+      (scheme) => {
+        const result = renderWithProviders(
+          <Theme name={scheme}>
+            <Geolocation label="Location" value={HELSINKI} />
+          </Theme>,
+        );
+        const glyph = result.container.querySelector("[aria-label='Locate'] svg")!;
+        const color = glyph.getAttribute("fill");
+        expect(color).toMatch(/^(#|rgb|hsl)/);
+        expect(color).not.toBe("currentColor");
+      },
+    );
+
+    it("preserves explicit Locate glyph paint and an explicit null glyph", () => {
       const result = renderWithProviders(
         <Geolocation
           label="Location"
-          name="loc"
-          locationIcon={locationIcon}
-          value={JSON.stringify({ lat: 51.5, lng: -0.12 })}
+          value={HELSINKI}
+          locationIcon={<NavigationArrowIcon color="#123456" />}
         />,
       );
+      expect(
+        result.container.querySelector("[aria-label='Locate'] svg")?.getAttribute("fill"),
+      ).toBe("#123456");
+      result.rerender(<Geolocation label="Location" value={HELSINKI} locationIcon={null} />);
+      expect(result.container.querySelector("[aria-label='Locate']")).not.toBeNull();
+      expect(result.container.querySelector("[aria-label='Locate'] svg")).toBeNull();
+    });
+
+    it("empty state teaches three paths and labels Use my current location", () => {
+      const result = renderWithProviders(<Geolocation label="Location" />);
+      expect(result.container.textContent).not.toContain("0.00000, 0.00000");
+      expect(result.container.textContent).toContain("No location set");
+      expect(result.container.textContent).toContain("Use my current location");
+      expect(result.container.textContent).toContain("Search, tap the map, or use your location.");
+      expect(searchInput(result.container)).not.toBeNull();
+    });
+
+    it("no input control is absolutely positioned over the map surface", () => {
+      const result = renderWithProviders(
+        <Geolocation label="Location" value={HELSINKI} locationIcon={locationIcon} />,
+      );
+      const map = result.container.querySelector("[data-testid='geolocation-map']");
+      expect(map).not.toBeNull();
+      const inputs = [...result.container.querySelectorAll("input")];
+      expect(inputs.length).toBeGreaterThan(0);
+      for (const input of inputs) {
+        expect(map?.contains(input)).toBe(false);
+      }
+      expect(result.container.querySelector("[data-testid='geolocation-coords-chip']")).toBeNull();
+    });
+
+    it("without an injected geocoder, search is disabled and map/manual paths stay", () => {
+      const result = renderWithProviders(
+        <Geolocation label="Location" value={HELSINKI} locationIcon={locationIcon} />,
+      );
+      const input = searchInput(result.container);
+      expect(input).not.toBeNull();
+      expect(input?.disabled || input?.getAttribute("aria-disabled") === "true").toBeTruthy();
       expect(result.container.querySelector("[data-testid='geolocation-map']")).not.toBeNull();
       expect(
-        result.container.querySelector("[data-testid='geolocation-coords-chip']"),
+        result.container.querySelector("[data-testid='geolocation-coordline']"),
       ).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("empty value does not paint Null Island coordinates", () => {
-      const result = renderWithProviders(<Geolocation label="Location" />);
-      expect(result.container.textContent).not.toContain("0.0000, 0.0000");
-      expect(result.container.textContent).toContain("Set location");
+    it("a set value renders a reverse-geocoded address, pair subordinate", async () => {
+      const reverseGeocode = mockReverse();
+      const result = renderWithProviders(
+        <Geolocation
+          label="Location"
+          value={HELSINKI}
+          reverseGeocode={reverseGeocode}
+          locationIcon={locationIcon}
+        />,
+      );
+      await waitFor(() => {
+        expect(reverseGeocode).toHaveBeenCalledWith({ lat: 60.16952, lng: 24.93545 });
+        expect(searchInput(result.container)?.value).toBe(
+          "Mannerheimintie 3, Kamppi, Helsinki, Finland",
+        );
+      });
+      expect(result.container.textContent).toContain("60.16952, 24.93545");
     });
 
-    it("LC-71: map frame is the keyboard stop; pick layer is not a tab stop", () => {
+    it("typing a place name produces a results panel; picking sets the value", async () => {
+      const geocode = mockGeocode();
+      const onChange = vi.fn();
+      const result = renderWithProviders(
+        <Geolocation
+          label="Location"
+          geocode={geocode}
+          onChange={onChange}
+          locationIcon={locationIcon}
+        />,
+      );
+      typeSearch(result.container, "manner");
+      await waitFor(() => {
+        expect(geocode).toHaveBeenCalledWith({ query: "manner" });
+        expect(document.querySelector("[data-testid='geolocation-results']")).not.toBeNull();
+        expect(document.body.textContent).toContain("Use my current location");
+        expect(document.body.textContent).toContain("Mannerheimintie 3");
+        expect(document.body.textContent).toContain("Kamppi, Helsinki, Finland");
+      });
+      fireEvent.click(document.querySelector("[data-testid='geolocation-result-0']") as Element);
+      await waitFor(() => {
+        expect(onChange).toHaveBeenCalledWith(HELSINKI);
+      });
+      expect(searchInput(result.container)?.value).toBe(
+        "Mannerheimintie 3, Kamppi, Helsinki, Finland",
+      );
+    });
+
+    it("Use my current location is the first results row", async () => {
+      const geocode = mockGeocode();
+      const result = renderWithProviders(
+        <Geolocation label="Location" geocode={geocode} locationIcon={locationIcon} />,
+      );
+      typeSearch(result.container, "manner");
+      await waitFor(() => {
+        expect(document.querySelector("[data-testid='geolocation-results']")).not.toBeNull();
+      });
+      const list = document.querySelector("[data-testid='geolocation-results']") as HTMLElement;
+      const first = list.firstElementChild as HTMLElement;
+      expect(first.getAttribute("data-testid")).toBe("geolocation-use-location");
+      expect(first.textContent).toContain("Use my current location");
+    });
+
+    it("zero-results and geocoder failure leave the map and coordinates working", async () => {
+      const geocode = vi.fn().mockResolvedValueOnce([]).mockRejectedValueOnce(new Error("down"));
+      const onChange = vi.fn();
       const result = renderWithProviders(
         <Geolocation
           label="Location"
-          value={JSON.stringify({ lat: 1, lng: 2 })}
+          geocode={geocode}
+          onChange={onChange}
           locationIcon={locationIcon}
         />,
       );
+      typeSearch(result.container, "mannerheimintei");
+      await waitFor(() => {
+        expect(document.body.textContent).toContain('No places match "mannerheimintei"');
+      });
+      expect(result.container.querySelector("[data-testid='geolocation-map']")).not.toBeNull();
+
+      typeSearch(result.container, "manner");
+      await waitFor(() => {
+        expect(document.body.textContent).toContain(
+          "Search is unavailable — check your connection",
+        );
+      });
+
+      const pick = result.container.querySelector(
+        "[data-testid='geolocation-map-pick']",
+      ) as HTMLElement;
+      pick.getBoundingClientRect = () =>
+        ({
+          width: 200,
+          height: 200,
+          left: 0,
+          top: 0,
+          right: 200,
+          bottom: 200,
+          x: 0,
+          y: 0,
+          toJSON() {},
+        }) as DOMRect;
+      fireEvent.click(pick, { clientX: 100, clientY: 100 });
+      expect(onChange).toHaveBeenCalled();
+    });
+
+    it("a typed lat, lng pair offers the exact point", async () => {
+      const geocode = mockGeocode();
+      const onChange = vi.fn();
+      const result = renderWithProviders(
+        <Geolocation
+          label="Location"
+          geocode={geocode}
+          onChange={onChange}
+          locationIcon={locationIcon}
+        />,
+      );
+      typeSearch(result.container, "60.169, 24.935");
+      await waitFor(() => {
+        expect(document.body.textContent).toContain("Go to 60.16900, 24.93500");
+        expect(document.body.textContent).toContain("Exact coordinates — no address");
+      });
+      expect(geocode).not.toHaveBeenCalled();
+      fireEvent.click(
+        document.querySelector("[data-testid='geolocation-coord-result']") as Element,
+      );
+      await waitFor(() => {
+        expect(onChange).toHaveBeenCalledWith(JSON.stringify({ lat: 60.169, lng: 24.935 }));
+      });
+    });
+
+    it("inTableCell renders a TEXT face inside the row rhythm, never the map", async () => {
+      const reverseGeocode = mockReverse();
+      const result = renderWithProviders(
+        <TableCellContext.Provider value={{ inTableCell: true, isHeader: false, editable: true }}>
+          <Geolocation
+            label="Location"
+            value={HELSINKI}
+            reverseGeocode={reverseGeocode}
+            locationIcon={locationIcon}
+          />
+        </TableCellContext.Provider>,
+      );
+      expect(result.container.querySelector("[data-testid='geolocation-map']")).toBeNull();
+      expect(
+        result.container.querySelector("[data-testid='geolocation-cell-face']"),
+      ).not.toBeNull();
+      await waitFor(() => {
+        expect(result.container.textContent).toContain(
+          "Mannerheimintie 3, Kamppi, Helsinki, Finland",
+        );
+      });
+    });
+
+    it("at <=640 the results panel is a sheet with a pinned search row", async () => {
+      const width = vi.spyOn(window, "innerWidth", "get").mockReturnValue(390);
+      window.dispatchEvent(new Event("resize"));
+      const geocode = mockGeocode();
+      const result = renderWithProviders(
+        <Geolocation label="Location" geocode={geocode} locationIcon={locationIcon} />,
+      );
+      expect(
+        result.container
+          .querySelector("[data-testid='geolocation-search-anchor']")
+          ?.getAttribute("data-sheet"),
+      ).toBe("true");
+      typeSearch(result.container, "manner");
+      await waitFor(() => {
+        expect(geocode).toHaveBeenCalled();
+      });
+      await waitFor(() => {
+        const sheet =
+          document.querySelector("[data-testid='geolocation-results-sheet']") ??
+          document.querySelector("[role='dialog']");
+        expect(sheet).not.toBeNull();
+        expect(
+          sheet?.querySelector("[aria-label='Search for a location']") ??
+            document.querySelector("[data-testid='geolocation-search']"),
+        ).not.toBeNull();
+        expect(document.querySelector("[data-testid='geolocation-results']")).not.toBeNull();
+      });
+      width.mockRestore();
+    });
+
+    it("LC-71: map frame is the keyboard stop; pick layer is not a tab stop", () => {
+      const result = renderWithProviders(
+        <Geolocation label="Location" value={HELSINKI} locationIcon={locationIcon} />,
+      );
       const map = result.container.querySelector("[data-testid='geolocation-map']");
       const pick = result.container.querySelector("[data-testid='geolocation-map-pick']");
       expect(map?.getAttribute("tabindex")).toBe("0");
@@ -189,11 +438,9 @@ describe("Geolocation", () => {
         />,
       );
       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/);
@@ -205,7 +452,6 @@ describe("Geolocation", () => {
       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 }));
@@ -228,7 +474,7 @@ describe("Geolocation", () => {
       expect(result.findTextElement("Pick a point")).toBeDefined();
     });
 
-    it("renders skeleton placeholder as map-only", () => {
+    it("renders skeleton placeholder as search + map", () => {
       const result = renderWithProviders(
         <Geolocation label="Loading" name="l" locationIcon={locationIcon} skeleton />,
       );
@@ -237,11 +483,6 @@ describe("Geolocation", () => {
       expect(result.container.querySelector("input")).toBeNull();
     });
 
-    // A disabled control opens nothing. Expand was the one overlay in this
-    // field that still did: unlike Locate and Coordinates it carried no
-    // `disabled`, and it opens its AdaptivePopup programmatically, so the
-    // Button's own pointerEvents:none was never the whole guard. Both halves
-    // of a real press are fired — `click` alone would pass against the bug.
     describe("disabled opens no overlay", () => {
       const expandIcon = <span data-testid="expand-icon" />;
       const value = JSON.stringify({ lat: 51.5, lng: -0.12 });
@@ -264,7 +505,7 @@ describe("Geolocation", () => {
         );
         press(result.container.querySelector("[aria-label='Expand map']") as Element);
         await waitFor(() => {
-          expect(document.querySelector("[role='dialog']")).not.toBeNull();
+          expect(document.querySelector("[role='dialog'][data-state='open']")).not.toBeNull();
         });
       });
 
@@ -283,7 +524,7 @@ describe("Geolocation", () => {
         expect(expand).not.toBeNull();
         press(expand as Element);
         await new Promise((resolve) => setTimeout(resolve, 50));
-        expect(document.querySelector("[role='dialog']")).toBeNull();
+        expect(document.querySelector("[role='dialog'][data-state='open']")).toBeNull();
       });
 
       it("disabled: Coordinates opens no panel", async () => {
@@ -296,28 +537,39 @@ describe("Geolocation", () => {
             disabled
           />,
         );
-        press(result.container.querySelector("[aria-label='Edit coordinates']") as Element);
+        const line = result.container.querySelector("[data-testid='geolocation-coordline']");
+        expect(line).not.toBeNull();
+        press(line as Element);
         await new Promise((resolve) => setTimeout(resolve, 50));
         expect(document.querySelector("[data-testid='geolocation-coords-panel']")).toBeNull();
         expect(document.querySelector("[data-testid='floating-panel-viewport']")).toBeNull();
       });
     });
 
-    it("renders readOnly — hides locate and coordinates overlay controls", () => {
+    it("renders readOnly — address as fact, no search, no locate", async () => {
+      const reverseGeocode = mockReverse();
       const result = renderWithProviders(
         <Geolocation
           label="ReadOnly"
           name="r"
           locationIcon={locationIcon}
           readOnly
-          value={JSON.stringify({ lat: 1.23, lng: 4.56 })}
+          value={HELSINKI}
+          reverseGeocode={reverseGeocode}
         />,
       );
+      expect(searchInput(result.container)).toBeNull();
       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']"),
+        result.container.querySelector("[data-testid='geolocation-readonly-address']"),
       ).not.toBeNull();
+      expect(result.container.querySelector("[data-testid='geolocation-map']")).not.toBeNull();
+      await waitFor(() => {
+        expect(result.container.textContent).toContain(
+          "Mannerheimintie 3, Kamppi, Helsinki, Finland",
+        );
+      });
     });
   });
 
@@ -470,7 +722,7 @@ describe("Geolocation", () => {
       const result = renderWithProviders(
         <Geolocation label="Location" value={stockFrappePoint} locationIcon={locationIcon} />,
       );
-      expect(result.container.textContent).toContain("37.7749, -122.4194");
+      expect(result.container.textContent).toContain("37.77490, -122.41940");
       expect(result.container.textContent).not.toContain("Set location");
       expect(result.container.querySelector("[data-testid='geolocation-map']")).not.toBeNull();
     });

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

@@ -3,11 +3,14 @@ import { DataTable, type DataTableColumn } from "@multiplatform.one/table";
 import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
 import { ArrowsOutIcon, NavigationArrowIcon } from "@phosphor-icons/react";
 import { useForm } from "@tanstack/react-form";
-import { useState } from "react";
+import { useCallback, useState } from "react";
 import { Text, YStack } from "tamagui";
 import { Button } from "../../Button";
 import { Form } from "../../Form";
-import { Geolocation } from "./index";
+import { TableCellContext } from "../../shared/tableCellContext";
+import { Geolocation, type GeolocationProps } from "./index";
+import type { GeocodeResult, Geocoder } from "./geocoder";
+import { parseGeoValue } from "./geoValue";
 
 const meta: Meta<typeof Geolocation> = {
   title: "Forms/Geolocation",
@@ -16,7 +19,7 @@ const meta: Meta<typeof Geolocation> = {
     docs: {
       description: {
         component:
-          "Map-primary geolocation field: click the map to drop a pin. Locate is an icon overlay; the coordinate chip opens a FloatingPanel (no Apply — LC-21 dismiss-by-intent). LC-19 preflight gates Locate. LC-71: the map frame is the keyboard stop (inset ring, overflow hidden); overlay actions ring themselves. Accepts a custom `renderMap` prop for interactive maps.",
+          "Search-first geolocation field. Inject `geocode` / `reverseGeocode` (or a `geocoder` object); No default provider is supplied. The map is the output; coordinates live below it as a mono disclosure. Locate is a labeled action. LC-19 preflight gates Locate. LC-21: no Apply on the coordinate editor.",
       },
     },
   },
@@ -157,12 +160,12 @@ export const Interactive: Story = {
   render: () => {
     const InteractiveExample = () => {
       const [value, setValue] = useState(JSON.stringify({ lat: 40.7128, lng: -74.006 }));
-      const parsed = JSON.parse(value) as { lat: number; lng: number };
+      const parsed = parseGeoValue(value);
       return (
         <YStack gap="$4" maxWidth={500}>
           <Geolocation
             label="Pick Location"
-            helperText={`Lat: ${parsed.lat.toFixed(4)}, Lng: ${parsed.lng.toFixed(4)}`}
+            helperText={`Lat: ${parsed?.lat.toFixed(4) ?? ""}, Lng: ${parsed?.lng.toFixed(4) ?? ""}`}
             value={value}
             onChange={(v) => {
               setValue(v);
@@ -182,12 +185,12 @@ export const WithCoordinates: Story = {
   render: () => {
     const Example = () => {
       const [value, setValue] = useState(JSON.stringify({ lat: 37.7749, lng: -122.4194 }));
-      const parsed = JSON.parse(value) as { lat: number; lng: number };
+      const parsed = parseGeoValue(value);
       return (
         <YStack gap="$4" maxWidth={500}>
           <Geolocation
             label="Office Location"
-            helperText={`Lat: ${parsed.lat.toFixed(4)}, Lng: ${parsed.lng.toFixed(4)}`}
+            helperText={`Lat: ${parsed?.lat.toFixed(4) ?? ""}, Lng: ${parsed?.lng.toFixed(4) ?? ""}`}
             value={value}
             onChange={(v) => {
               setValue(v);
@@ -295,3 +298,134 @@ export const InTable: Story = {
     );
   },
 };
+
+const places: GeocodeResult[] = [
+  { lat: 60.16952, lng: 24.93545, label: "Mannerheimintie 3", description: "Kamppi, Helsinki" },
+  { lat: -33.8688, lng: 151.2093, label: "Sydney", description: "New South Wales, Australia" },
+];
+
+const fakeGeocoder: Geocoder = {
+  geocode: async ({ query }) =>
+    places.filter((place) =>
+      `${place.label} ${place.description}`.toLowerCase().includes(query.trim().toLowerCase()),
+    ),
+  reverseGeocode: async ({ lat, lng }) =>
+    places.find((place) => Math.abs(place.lat - lat) < 0.01 && Math.abs(place.lng - lng) < 0.01) ??
+    null,
+};
+
+function FakeProviderExample(props: GeolocationProps) {
+  const [value, setValue] = useState(props.value ?? "");
+  return <Geolocation {...props} value={value} onChange={setValue} />;
+}
+
+export const SearchWithFakeProvider: Story = {
+  args: {
+    label: "Location",
+    helperText: "Search Sydney or Helsinki. This example uses an offline provider.",
+    geocoder: fakeGeocoder,
+  },
+  render: (args) => <FakeProviderExample {...args} />,
+};
+
+export const AddressWithFakeProvider: Story = {
+  args: {
+    label: "Office",
+    value: JSON.stringify({ lat: 60.16952, lng: 24.93545 }),
+    geocoder: fakeGeocoder,
+    readOnly: true,
+  },
+};
+
+export const FailedFakeProvider: Story = {
+  args: {
+    label: "Location",
+    geocode: async () => {
+      throw new Error("Offline example failure");
+    },
+  },
+  render: (args) => <FakeProviderExample {...args} />,
+};
+
+/** Direct cell contract, independent of the table adapter's display formatter. */
+export const CellWithFakeProvider: Story = {
+  args: {
+    label: "Location",
+    value: JSON.stringify({ lat: 60.16952, lng: 24.93545 }),
+    geocoder: fakeGeocoder,
+  },
+  render: (args) => (
+    <TableCellContext.Provider value={{ inTableCell: true, isHeader: false, editable: true }}>
+      <FakeProviderExample {...args} />
+    </TableCellContext.Provider>
+  ),
+};
+
+function DeferredControlledExample() {
+  const [value, setValue] = useState(JSON.stringify({ lat: places[0].lat, lng: places[0].lng }));
+  const [proposal, setProposal] = useState<string | null>(null);
+  const [readOnly, setReadOnly] = useState(false);
+  return (
+    <YStack gap="$3">
+      <Geolocation
+        label="Location"
+        value={value}
+        onChange={setProposal}
+        readOnly={readOnly}
+        geocoder={fakeGeocoder}
+      />
+      <Text>The parent holds the current location until it accepts the proposal.</Text>
+      <Button onPress={() => setReadOnly(!readOnly)}>
+        {readOnly ? "Edit search" : "Show selected fact"}
+      </Button>
+      {proposal !== null ? (
+        <Button onPress={() => setValue(proposal)}>Accept proposed location</Button>
+      ) : null}
+    </YStack>
+  );
+}
+
+export const DeferredControlledSelection: Story = {
+  render: () => <DeferredControlledExample />,
+};
+
+function PendingReverseExample() {
+  const [value, setValue] = useState(JSON.stringify({ lat: places[0].lat, lng: places[0].lng }));
+  const [readOnly, setReadOnly] = useState(true);
+  const [resolvePending, setResolvePending] = useState<(() => void) | null>(null);
+  const reverseGeocode = useCallback<NonNullable<GeolocationProps["reverseGeocode"]>>(({ lat }) => {
+    if (lat === places[0].lat) return Promise.resolve(places[0]);
+    return new Promise((resolve) => setResolvePending(() => () => resolve(places[1])));
+  }, []);
+  return (
+    <YStack gap="$3">
+      <Geolocation
+        label="Location"
+        value={value}
+        readOnly={readOnly}
+        geocode={fakeGeocoder.geocode}
+        reverseGeocode={reverseGeocode}
+      />
+      <Button onPress={() => setReadOnly(!readOnly)}>
+        {readOnly ? "Edit search" : "Show selected fact"}
+      </Button>
+      <Button onPress={() => setValue(JSON.stringify({ lat: places[1].lat, lng: places[1].lng }))}>
+        Move bound location to Sydney
+      </Button>
+      {resolvePending ? (
+        <Button
+          onPress={() => {
+            resolvePending();
+            setResolvePending(null);
+          }}
+        >
+          Resolve Sydney address
+        </Button>
+      ) : null}
+    </YStack>
+  );
+}
+
+export const PendingControlledReverse: Story = {
+  render: () => <PendingReverseExample />,
+};

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

@@ -56,6 +56,9 @@ function MapFallback({
  * 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.
+ *
+ * Output surface of the search-first field (MPO-54). Search and the
+ * coordinate disclosure live in the parent.
  */
 export function GeolocationMap({
   lat,

package/src/fields/Geolocation/GeolocationMap.tsx

@@ -19,6 +19,10 @@ function tileSrc(zoom: number, x: number, y: number) {
  * (Frappe Desk / Leaflet, Google/Apple compact pickers) can commit through
  * the field's onChange path. The iframe embed could not report clicks.
  * Native interactive maps live in `GeolocationMap.native.tsx`.
+ *
+ * This surface is the OUTPUT of the search-first field (MPO-54). Search,
+ * geocoding, and the coordinate disclosure live in the parent — nothing
+ * here is an input pasted over the tiles.
  */
 export function GeolocationMap({
   lat,