@multiplatform.one/forms 7.7.4 → 7.8.0

package/src/fields/Geolocation/index.tsx

@@ -1,23 +1,33 @@
-import { ensureFocusVisibleRing, useResolvedKnobs, type KnobProps } from "@multiplatform.one/theme";
-import { NavigationArrowIcon } from "@phosphor-icons/react";
+import {
+  ensureFocusVisibleRing,
+  pressTargetHitSlop,
+  useResolvedKnobs,
+  useGlyphColor,
+  type KnobProps,
+} from "@multiplatform.one/theme";
+import { MagnifyingGlassIcon, MapPinIcon, NavigationArrowIcon, XIcon } from "@phosphor-icons/react";
 import type { KeyboardEvent, MutableRefObject, ReactNode } from "react";
-import { useCallback, useEffect, useRef, useState } from "react";
+import { useCallback, useEffect, useId, useRef, useState } from "react";
 import type { LabelProps, SizeTokens } from "tamagui";
-import { Spinner, Text, View, XStack, YStack, isWeb } from "tamagui";
+import { ScrollView, Spinner, Text, View, XStack, YStack, isWeb } from "tamagui";
 import { AdaptivePopup } from "../../AdaptivePopup";
 import { Button } from "../../Button";
 import { Field, FieldLayout } from "../../fieldLayout";
-import { FloatingPanel } from "../../FloatingPanel";
-import { GeolocationMap } from "./GeolocationMap";
-import { detectGeoShape, formatGeoValue, type GeoValue, parseGeoValue } from "./geoValue";
+import { FloatingPanel, useViewportGtSm } from "../../FloatingPanel";
 import { Input as InputParts } from "../../InputParts";
 import { Skeleton } from "../../Skeleton";
+import { GeolocationMap } from "./GeolocationMap";
+import { createNativeSearchFocus } from "./nativeSearchFocus";
+import { detectGeoShape, formatGeoValue, parseGeoValue } from "./geoValue";
 import {
   queryPermissionState,
   type CapabilityPreflightResult,
 } from "../../shared/capabilityPreflight";
 import { formCommonColors, formInputColors } from "../../shared/colorRamps";
 import { t } from "../../shared/t";
+import { pressSlopProps } from "../../shared/pressSlopProps";
+import { useIsInTableCell } from "../../shared/tableCellContext";
+import { zIndex } from "../../shared/zIndex";
 import {
   clampRadiusForLargeComponent,
   getFieldError,
@@ -27,8 +37,44 @@ import {
   useResolvedValidators,
 } from "../../shared/utils";
 import type { AnyFormApi } from "../../types";
+import type { GeocodeFn, GeocodeResult, Geocoder, ReverseGeocodeFn } from "./geocoder";
+import {
+  clampLat,
+  clampLng,
+  formatCoordPair,
+  formatPlace,
+  parseLatLngPair,
+  resolveGeocoder,
+} from "./geocoder";
+
+export type {
+  GeocodeFn,
+  GeocodeQuery,
+  GeocodeResult,
+  Geocoder,
+  ReverseGeocodeFn,
+  ReverseGeocodeQuery,
+} from "./geocoder";
+export {
+  clampLat,
+  clampLng,
+  formatCoordPair,
+  formatPlace,
+  parseLatLngPair,
+  resolveGeocoder,
+} from "./geocoder";
 
 type LocatePhase = "idle" | "locating" | "error";
+type SearchStatus = "idle" | "searching" | "results" | "empty" | "error";
+type ResolvedAddress = { key: string; label: string };
+
+function coordinateKey({ lat, lng }: { lat: number; lng: number }): string {
+  return `${lat},${lng}`;
+}
+
+const SEARCH_DEBOUNCE_MS = 300;
+const COORD_LINE_HEIGHT = 28;
+const RESULTS_PANEL_SHADOW = "0px 8px 28px rgba(0,0,0,0.12), 0px 2px 6px rgba(0,0,0,0.04)";
 
 /**
  * Geolocation capability pre-flight (LC-19 CAPABILITY-PREFLIGHT). Runs BEFORE
@@ -75,17 +121,6 @@ function mapGeolocationError(
   return err.message || t("Failed to get location");
 }
 
-function clampLat(val: number): number {
-  return Math.max(-90, Math.min(90, val));
-}
-function clampLng(val: number): number {
-  return Math.max(-180, Math.min(180, val));
-}
-
-function formatCoordChip(lat: number, lng: number): string {
-  return `${lat.toFixed(4)}, ${lng.toFixed(4)}`;
-}
-
 /**
  * Parse a coordinate draft. Returns undefined while the user is mid-keystroke
  * (empty, lone minus, trailing decimal) so we don't clobber the bound value.
@@ -144,7 +179,6 @@ function CoordinatesPanel({
     [onCommit],
   );
 
-  /** Dismiss/blur flush — more permissive than live parse (accepts trailing "."). */
   const flushDraft = useCallback(() => {
     const rawLat = Number.parseFloat(latTextRef.current);
     const rawLng = Number.parseFloat(lngTextRef.current);
@@ -269,8 +303,159 @@ export interface GeolocationMapProps {
   knobProps: KnobProps;
 }
 
-/** Overlay buttons sit inside the map's overflow:hidden — inset ring (LC-71). */
-const overlayFocusRing = ensureFocusVisibleRing({ outlineOffset: -2 });
+/** Overlay buttons sit inside the map — 2px ring at offset 0 (media-13). */
+const overlayFocusRing = ensureFocusVisibleRing({ outlineOffset: 0 });
+
+function ResultRow({
+  testID,
+  label,
+  description,
+  onPress,
+  disabled,
+}: {
+  testID?: string;
+  label: string;
+  description?: string;
+  onPress: () => void;
+  disabled?: boolean;
+}) {
+  return (
+    <YStack
+      testID={testID}
+      role="option"
+      aria-selected={false}
+      aria-disabled={disabled || undefined}
+      {...(isWeb
+        ? {
+            tabIndex: disabled ? -1 : 0,
+            onKeyDown: (event: KeyboardEvent<HTMLElement>) => {
+              if (disabled) return;
+              if (event.key === "Enter" || event.key === " ") {
+                event.preventDefault();
+                onPress();
+              } else if (event.key === "ArrowDown" || event.key === "ArrowUp") {
+                event.preventDefault();
+                const rows = [
+                  ...(event.currentTarget.parentElement?.querySelectorAll<HTMLElement>(
+                    "[role='option']:not([aria-disabled='true'])",
+                  ) ?? []),
+                ];
+                const index = rows.indexOf(event.currentTarget);
+                rows[
+                  (index + (event.key === "ArrowDown" ? 1 : -1) + rows.length) % rows.length
+                ]?.focus();
+              }
+            },
+          }
+        : {})}
+      minHeight={description ? 62 : 44}
+      justifyContent="center"
+      paddingHorizontal="$3"
+      paddingVertical={description ? "$2" : 0}
+      cursor={disabled ? "not-allowed" : "pointer"}
+      hoverStyle={disabled ? undefined : { backgroundColor: "$color3" }}
+      pressStyle={disabled ? undefined : { backgroundColor: "$color3" }}
+      onPress={disabled ? undefined : onPress}
+      opacity={disabled ? 0.5 : 1}
+    >
+      <Text fontSize="$4" lineHeight={25} color="$color12">
+        {label}
+      </Text>
+      {description ? (
+        <Text fontSize="$3" lineHeight={24} color={formCommonColors.muted}>
+          {description}
+        </Text>
+      ) : null}
+    </YStack>
+  );
+}
+
+function StatusRow({ children, testID }: { children: ReactNode; testID?: string }) {
+  return (
+    <XStack testID={testID} minHeight={44} alignItems="center" paddingHorizontal="$3" role="status">
+      <Text fontSize="$4" lineHeight={25} color={formCommonColors.muted}>
+        {children}
+      </Text>
+    </XStack>
+  );
+}
+
+function SearchResultsList({
+  listId,
+  status,
+  query,
+  results,
+  pair,
+  onLocate,
+  onPick,
+  onPickPair,
+  locateDisabled,
+}: {
+  listId: string;
+  status: SearchStatus;
+  query: string;
+  results: GeocodeResult[];
+  pair: { lat: number; lng: number } | null;
+  onLocate: () => void;
+  onPick: (result: GeocodeResult) => void;
+  onPickPair: (lat: number, lng: number) => void;
+  locateDisabled?: boolean;
+}) {
+  const showLocate = status === "idle" || status === "results" || pair != null;
+  return (
+    <YStack
+      testID="geolocation-results"
+      id={listId}
+      overflow="hidden"
+      {...(isWeb
+        ? // role="listbox" is a valid ARIA role but outside RN's `Role` union;
+          // this web-only bag forwards it to the DOM node (house Record cast).
+          ({ role: "listbox" } as Record<string, unknown>)
+        : undefined)}
+    >
+      {showLocate ? (
+        <ResultRow
+          testID="geolocation-use-location"
+          label={t("Use my current location")}
+          onPress={onLocate}
+          disabled={locateDisabled}
+        />
+      ) : null}
+      {status === "searching" ? (
+        <StatusRow testID="geolocation-search-status">{t("Searching…")}</StatusRow>
+      ) : null}
+      {status === "error" ? (
+        <StatusRow testID="geolocation-search-status">
+          {t("Search is unavailable — check your connection")}
+        </StatusRow>
+      ) : null}
+      {status === "empty" && !pair ? (
+        <StatusRow testID="geolocation-search-status">
+          {t('No places match "{{query}}"', { query })}
+        </StatusRow>
+      ) : null}
+      {pair ? (
+        <ResultRow
+          testID="geolocation-coord-result"
+          label={t("Go to {{pair}}", { pair: formatCoordPair(pair.lat, pair.lng) })}
+          description={t("Exact coordinates — no address")}
+          onPress={() => onPickPair(pair.lat, pair.lng)}
+        />
+      ) : null}
+      {status === "results"
+        ? results.map((result, index) => (
+            <ResultRow
+              key={`${result.lat},${result.lng},${index}`}
+              testID={`geolocation-result-${index}`}
+              label={result.label}
+              description={result.description}
+              onPress={() => onPick(result)}
+            />
+          ))
+        : null}
+    </YStack>
+  );
+}
 
 function GeoMapSurface({
   id,
@@ -293,7 +478,7 @@ function GeoMapSurface({
   mapHeight,
 }: {
   id?: string;
-  coordinates: GeoValue | null;
+  coordinates: { lat: number; lng: number } | null;
   onCommitCoordinates: (lat: number, lng: number) => void;
   onUseMyLocation: () => void;
   onRetryLocate: () => void;
@@ -322,13 +507,8 @@ function GeoMapSurface({
   const interactive = !disabled && !readOnly;
   const cappedRadius = clampRadiusForLargeComponent(knobProps.borderRadius.borderRadius);
 
-  // A disabled field opens nothing: the Button below is pointerEvents-none
-  // when disabled, but Expand is opened programmatically (AdaptivePopup here
-  // takes no `trigger`), so the guard has to live in the handler too.
   const handleExpand = expandIcon ? () => !disabled && setExpanded(true) : undefined;
 
-  // LC-21 EDITOR: outside/Escape closes; flush any in-progress draft so nothing is lost.
-  // Live-valid parses already committed — close is then dismiss-only.
   const handleCoordsOpenChange = (open: boolean) => {
     if (!open) {
       coordsFlushRef.current?.();
@@ -338,7 +518,7 @@ function GeoMapSurface({
 
   const handleMapKeyDown = (event: KeyboardEvent) => {
     if (!interactive) return;
-    if (event.key === "Enter") {
+    if (event.key === "Enter" && hasValue) {
       event.preventDefault();
       setCoordsOpen(true);
       return;
@@ -366,8 +546,71 @@ function GeoMapSurface({
       })
     : null;
 
+  const coordLine =
+    readOnly || disabled ? (
+      <XStack
+        testID="geolocation-coordline"
+        alignItems="center"
+        minHeight={COORD_LINE_HEIGHT}
+        paddingHorizontal="$2"
+        hitSlop={pressTargetHitSlop(COORD_LINE_HEIGHT)}
+      >
+        <Text fontFamily="$mono" fontSize={12} lineHeight={22} color={formCommonColors.muted}>
+          {hasValue ? formatCoordPair(mapLat, mapLng) : t("Enter coordinates")}
+        </Text>
+      </XStack>
+    ) : (
+      <FloatingPanel
+        open={coordsOpen}
+        onOpenChange={handleCoordsOpenChange}
+        disabled={disabled}
+        fitContent={false}
+        sizing="fill"
+        contentPadding="none"
+        trigger={
+          <XStack
+            testID="geolocation-coordline"
+            alignItems="center"
+            minHeight={COORD_LINE_HEIGHT}
+            paddingHorizontal="$2"
+            cursor="pointer"
+            {...pressSlopProps(COORD_LINE_HEIGHT, true)}
+            hoverStyle={{ backgroundColor: "$color3" }}
+            focusVisibleStyle={overlayFocusRing}
+            {...(isWeb
+              ? {
+                  tabIndex: 0,
+                  role: "button",
+                  "aria-label": t("Edit coordinates"),
+                  onKeyDown: (event: KeyboardEvent) => {
+                    if (event.key === "Enter" || event.key === " ") {
+                      event.preventDefault();
+                      setCoordsOpen(true);
+                    }
+                  },
+                }
+              : {})}
+          >
+            <Text fontFamily="$mono" fontSize={12} lineHeight={22} color={formCommonColors.muted}>
+              {hasValue ? formatCoordPair(mapLat, mapLng) : t("Enter coordinates")}
+            </Text>
+          </XStack>
+        }
+      >
+        <CoordinatesPanel
+          lat={mapLat}
+          lng={mapLng}
+          knobProps={knobProps}
+          required={required}
+          hasError={hasError}
+          flushRef={coordsFlushRef}
+          onCommit={onCommitCoordinates}
+        />
+      </FloatingPanel>
+    );
+
   return (
-    <>
+    <YStack gap="$2">
       <YStack
         testID="geolocation-map"
         id={id}
@@ -386,7 +629,7 @@ function GeoMapSurface({
               tabIndex: 0,
               role: "application",
               "aria-label": t("Location map"),
-              "aria-valuetext": hasValue ? formatCoordChip(mapLat, mapLng) : t("No location set"),
+              "aria-valuetext": hasValue ? formatCoordPair(mapLat, mapLng) : t("No location set"),
               onKeyDown: handleMapKeyDown,
             }
           : {})}
@@ -403,66 +646,36 @@ function GeoMapSurface({
           />
         )}
 
-        {/* Chip is the coordinates editor trigger (Apple/Google compact pattern). */}
-        {readOnly ? (
-          <View
+        {!hasValue && !locateErrorOpen ? (
+          <YStack
+            testID="geolocation-empty"
             position="absolute"
-            top="$2"
-            insetInlineStart="$2"
+            top={0}
+            right={0}
+            bottom={0}
+            left={0}
             zIndex={2}
-            backgroundColor="$background"
-            opacity={0.92}
-            paddingHorizontal="$2"
-            paddingVertical="$1"
-            {...knobProps.borderRadius}
+            alignItems="center"
+            justifyContent="center"
+            gap="$2"
+            pointerEvents="box-none"
           >
-            <Text
-              testID="geolocation-coords-chip"
-              fontSize="$1"
-              {...knobProps.body}
-              color={formCommonColors.muted}
-            >
-              {hasValue ? formatCoordChip(mapLat, mapLng) : t("No location set")}
+            <Text {...knobProps.body} color={formCommonColors.muted} pointerEvents="none">
+              {t("No location set")}
             </Text>
-          </View>
-        ) : (
-          <View position="absolute" top="$2" insetInlineStart="$2" zIndex={2}>
-            <FloatingPanel
-              open={coordsOpen}
-              onOpenChange={handleCoordsOpenChange}
-              disabled={disabled}
-              fitContent
-              sizing="fill"
-              contentPadding="none"
-              trigger={
-                <Button
-                  size="$2"
-                  disabled={disabled}
-                  backgroundColor="$background"
-                  opacity={0.92}
-                  testID="geolocation-coords-chip"
-                  aria-label={t("Edit coordinates")}
-                  focusVisibleStyle={overlayFocusRing}
-                  onPress={isWeb && !disabled ? () => setCoordsOpen(true) : undefined}
-                >
-                  <Button.Text>
-                    {hasValue ? formatCoordChip(mapLat, mapLng) : t("Set location")}
-                  </Button.Text>
-                </Button>
-              }
-            >
-              <CoordinatesPanel
-                lat={mapLat}
-                lng={mapLng}
-                knobProps={knobProps}
-                required={required}
-                hasError={hasError}
-                flushRef={coordsFlushRef}
-                onCommit={onCommitCoordinates}
-              />
-            </FloatingPanel>
-          </View>
-        )}
+            {!readOnly && !disabled ? (
+              <Button
+                size="$4"
+                onPress={onUseMyLocation}
+                disabled={locating}
+                testID="geolocation-empty-locate"
+                aria-label={t("Use my current location")}
+              >
+                <Button.Text>{t("Use my current location")}</Button.Text>
+              </Button>
+            ) : null}
+          </YStack>
+        ) : null}
 
         {handleExpand && expandIcon && (
           <View position="absolute" top="$2" insetInlineEnd="$2" zIndex={2}>
@@ -472,16 +685,15 @@ function GeoMapSurface({
               disabled={disabled}
               onPress={handleExpand}
               backgroundColor="$background"
-              opacity={0.92}
               aria-label={t("Expand map")}
               focusVisibleStyle={overlayFocusRing}
+              hitSlop={pressTargetHitSlop(32)}
             >
               {expandIcon}
             </Button>
           </View>
         )}
 
-        {/* Locate overlay (bottom-end) — LC-19 preflight runs on press */}
         {!readOnly && !locateErrorOpen && (
           <View position="absolute" bottom="$2" insetInlineEnd="$2" zIndex={2}>
             <Button
@@ -490,18 +702,14 @@ function GeoMapSurface({
               disabled={disabled || locating}
               onPress={onUseMyLocation}
               backgroundColor="$background"
-              opacity={0.92}
               icon={locating ? <Spinner size="small" /> : locationIcon}
               aria-label={locating ? t("Locating") : t("Locate")}
               focusVisibleStyle={overlayFocusRing}
+              hitSlop={pressTargetHitSlop(32)}
             />
           </View>
         )}
 
-        {/*
-          LC-19: locate error stays on the map (Retry + Close) — never
-          mount-fail-unmount, never a layout-jumping sibling under the field.
-        */}
         {locateErrorOpen && (
           <YStack
             testID="geolocation-locate-panel"
@@ -531,6 +739,7 @@ function GeoMapSurface({
           </YStack>
         )}
       </YStack>
+      {coordLine}
 
       {expandIcon && (
         <AdaptivePopup
@@ -549,7 +758,7 @@ function GeoMapSurface({
           />
         </AdaptivePopup>
       )}
-    </>
+    </YStack>
   );
 }
 
@@ -564,7 +773,7 @@ export interface GeolocationProps {
   required?: boolean;
   size?: SizeTokens;
   id?: string;
-  /** JSON string: {"lat": number, "lng": number} */
+  /** JSON string: compact lat/lng or a stock Frappe FeatureCollection. */
   value?: string;
   defaultValue?: string;
   onChange?: (value: string) => void;
@@ -585,12 +794,65 @@ export interface GeolocationProps {
   skeleton?: boolean;
   /** When true, applies compact density (tighter layout gaps; control size unchanged) */
   compact?: boolean;
+  /**
+   * Forward geocode. Injected — the field never ships a default provider
+   * (R4). Without this, search is disabled and the map / locate / coordinate
+   * paths stay intact.
+   */
+  geocode?: GeocodeFn;
+  /** Reverse geocode for a set pin. Injected; the pair is the fallback face. */
+  reverseGeocode?: ReverseGeocodeFn;
+  /**
+   * Convenience bag for `geocode` + `reverseGeocode`. Explicit props win.
+   * Any object satisfying `Geocoder` works. No provider is constructed for you.
+   */
+  geocoder?: Geocoder;
 }
 
-// Package icon default (UX-010): same glyph the frappe-ui adapter supplies —
-// bare use renders a complete locate affordance. Module-level element reuse
-// is safe (immutable descriptor).
-const defaultLocationIcon = <NavigationArrowIcon size={16} />;
+function CellFace({
+  address,
+  coordinates,
+  onOpen,
+}: {
+  address: string | null;
+  onOpen?: () => void;
+  coordinates: { lat: number; lng: number } | null;
+}) {
+  const glyphColor = useGlyphColor();
+  const text = address
+    ? address
+    : coordinates
+      ? formatCoordPair(coordinates.lat, coordinates.lng)
+      : t("No location set");
+  return (
+    <XStack
+      testID="geolocation-cell-face"
+      {...(isWeb && onOpen
+        ? {
+            tabIndex: 0,
+            role: "button",
+            "aria-label": t("Edit location"),
+            onKeyDown: (event: KeyboardEvent) => {
+              if (event.key === "Enter" || event.key === " ") {
+                event.preventDefault();
+                onOpen();
+              }
+            },
+          }
+        : {})}
+      alignItems="center"
+      gap="$2"
+      minHeight={44}
+      minWidth={0}
+      flex={1}
+    >
+      <MapPinIcon size={14} color={glyphColor} />
+      <Text fontSize="$3" lineHeight={24} color="$color12" numberOfLines={1} flex={1} minWidth={0}>
+        {text}
+      </Text>
+    </XStack>
+  );
+}
 
 export function Geolocation({
   name,
@@ -609,25 +871,102 @@ export function Geolocation({
   onBlur,
   disabled,
   readOnly,
-  locationIcon = defaultLocationIcon,
+  locationIcon,
   expandIcon,
   renderMap,
   skeleton,
   compact,
+  geocode: geocodeProp,
+  reverseGeocode: reverseGeocodeProp,
+  geocoder,
 }: GeolocationProps) {
   const { resolvedForm, knobProps, id } = useFormField({ form: formProp, id: idProp, compact });
   const resolvedValidators = useResolvedValidators(required, validators, label, name);
+  const glyphColor = useGlyphColor();
+  const resolvedLocationIcon =
+    locationIcon === undefined ? (
+      <NavigationArrowIcon size={16} color={glyphColor} />
+    ) : (
+      locationIcon
+    );
+  const inTableCell = useIsInTableCell();
+  const viewportGtSm = useViewportGtSm();
+  const shouldUseSheet = !isWeb || !viewportGtSm;
+  const { geocode, reverseGeocode } = resolveGeocoder({
+    geocode: geocodeProp,
+    reverseGeocode: reverseGeocodeProp,
+    geocoder,
+  });
+  const searchEnabled = Boolean(geocode) && !disabled && !readOnly;
+  const listId = useId();
+
   const [locatePhase, setLocatePhase] = useState<LocatePhase>("idle");
   const [locateError, setLocateError] = useState<string | null>(null);
-  /** Pre-flight field error (surface never mounts). Cleared on next successful pre-flight. */
   const [preflightError, setPreflightError] = useState<string | undefined>();
+  const [address, setAddress] = useState<ResolvedAddress | null>(null);
+  const [query, setQuery] = useState("");
+  const [resultsOpen, setResultsOpen] = useState(false);
+  const [searchStatus, setSearchStatus] = useState<SearchStatus>("idle");
+  const [results, setResults] = useState<GeocodeResult[]>([]);
+  const [cellOpen, setCellOpen] = useState(false);
   const preflightingRef = useRef(false);
   const onValueChangeRef = useRef<(value: string) => void>(() => {});
   // MPO-100: the value being replaced, so an async locate writes back in the
   // shape the doc arrived in instead of forcing this repo's compact shape.
   const currentValueRef = useRef<string>("");
+  const searchGenRef = useRef(0);
+  const reverseGenRef = useRef(0);
+  const searchRootRef = useRef<HTMLElement | null>(null);
+  const searchInputRef = useRef<HTMLInputElement | null>(null);
+  const sheetSearchInputRef = useRef<HTMLInputElement | null>(null);
+  const closingSearchRef = useRef(false);
+  const [nativeSearchFocus] = useState(createNativeSearchFocus);
+  // The input owns return focus. FloatingPanel's delayed restore would run
+  // onFocus after dismissal and reopen its own results sheet.
+  const skipResultsReturnFocusRef = useRef(true);
+  const closeSearch = useCallback(
+    (restoreFocus = true) => {
+      if (!isWeb) nativeSearchFocus.dismiss();
+      closingSearchRef.current = true;
+      setResultsOpen(false);
+      if (isWeb && restoreFocus) searchInputRef.current?.focus({ preventScroll: true });
+      closingSearchRef.current = false;
+    },
+    [nativeSearchFocus],
+  );
+  const queryIsAddressRef = useRef(true);
+  const selectedPlaceRef = useRef<{ key: string; place: GeocodeResult } | null>(null);
+  const locateGenRef = useRef(0);
+  const interactiveRef = useRef(!disabled && !readOnly);
+  interactiveRef.current = !disabled && !readOnly;
+  const cancelLocate = useCallback(() => {
+    ++locateGenRef.current;
+    setLocatePhase("idle");
+    setLocateError(null);
+  }, []);
+  useEffect(() => {
+    if (disabled || readOnly) cancelLocate();
+  }, [disabled, readOnly, cancelLocate]);
+  useEffect(
+    () => () => {
+      ++locateGenRef.current;
+      ++reverseGenRef.current;
+      ++searchGenRef.current;
+    },
+    [],
+  );
+
+  const applyAddress = useCallback((next: ResolvedAddress | null, intoQuery: boolean) => {
+    setAddress(next);
+    if (intoQuery) {
+      queryIsAddressRef.current = true;
+      setQuery(next?.label ?? "");
+    }
+  }, []);
 
   const requestPosition = useCallback(() => {
+    if (!interactiveRef.current) return;
+    const gen = ++locateGenRef.current;
     if (!navigator?.geolocation) {
       setLocateError(t("Geolocation unavailable: not supported in this browser."));
       setLocatePhase("error");
@@ -637,32 +976,35 @@ export function Geolocation({
     setLocateError(null);
     navigator.geolocation.getCurrentPosition(
       (position) => {
+        if (gen !== locateGenRef.current || !interactiveRef.current) return;
+        selectedPlaceRef.current = null;
+        queryIsAddressRef.current = true;
         const lat = clampLat(position.coords.latitude);
         const lng = clampLng(position.coords.longitude);
         const previous = currentValueRef.current;
         onValueChangeRef.current(formatGeoValue({ lat, lng }, detectGeoShape(previous), previous));
         setLocatePhase("idle");
         setLocateError(null);
+        closeSearch();
+        setCellOpen(false);
       },
       (err) => {
-        // Surface stays OPEN: error renders inside with Retry + Close.
+        if (gen !== locateGenRef.current || !interactiveRef.current) return;
         setLocateError(mapGeolocationError(err));
         setLocatePhase("error");
       },
       { enableHighAccuracy: true, timeout: 10000 },
     );
-  }, []);
+  }, [closeSearch]);
 
-  // LC-19 CAPABILITY-PREFLIGHT: verify geolocation availability BEFORE presenting
-  // the locate surface. Pre-flight failure renders an inline field error and the
-  // surface never mounts. The Locate button stays enabled — pressing it again
-  // re-runs the pre-flight.
   const startLocate = useCallback(async () => {
     if (disabled || readOnly) return;
     if (preflightingRef.current || locatePhase === "locating") return;
     preflightingRef.current = true;
+    const gen = ++locateGenRef.current;
     try {
       const result = await preflightGeolocation();
+      if (gen !== locateGenRef.current || !interactiveRef.current) return;
       if (result.ok) {
         setPreflightError(undefined);
         requestPosition();
@@ -676,6 +1018,102 @@ export function Geolocation({
     }
   }, [disabled, readOnly, locatePhase, requestPosition]);
 
+  const runReverse = useCallback(
+    async (lat?: number, lng?: number) => {
+      const gen = ++reverseGenRef.current;
+      if (lat === undefined || lng === undefined) {
+        selectedPlaceRef.current = null;
+        applyAddress(null, queryIsAddressRef.current);
+        return;
+      }
+      const key = coordinateKey({ lat, lng });
+      const selected = selectedPlaceRef.current;
+      if (selected?.key === key) {
+        applyAddress({ key, label: formatPlace(selected.place) }, queryIsAddressRef.current);
+        return;
+      }
+      // A new bound pair must not inherit the old address while it resolves.
+      // An independent typed query remains a draft across this transition.
+      applyAddress(null, queryIsAddressRef.current);
+      if (!reverseGeocode) {
+        return;
+      }
+      try {
+        const result = await reverseGeocode({ lat, lng });
+        if (gen !== reverseGenRef.current) return;
+        applyAddress(
+          result ? { key, label: formatPlace(result) } : null,
+          queryIsAddressRef.current,
+        );
+      } catch {
+        if (gen !== reverseGenRef.current) return;
+        applyAddress(null, queryIsAddressRef.current);
+      }
+    },
+    [reverseGeocode, applyAddress],
+  );
+
+  const runSearch = useCallback(
+    async (text: string) => {
+      if (!geocode) return;
+      const gen = ++searchGenRef.current;
+      setSearchStatus("searching");
+      try {
+        const next = await geocode({ query: text });
+        if (gen !== searchGenRef.current) return;
+        setResults(next);
+        setSearchStatus(next.length > 0 ? "results" : "empty");
+      } catch {
+        if (gen !== searchGenRef.current) return;
+        setResults([]);
+        setSearchStatus("error");
+      }
+    },
+    [geocode],
+  );
+
+  useEffect(() => {
+    ++searchGenRef.current;
+    if (!searchEnabled || !resultsOpen) return;
+    const trimmed = query.trim();
+    if (queryIsAddressRef.current) return;
+    if (!trimmed) {
+      setSearchStatus("idle");
+      setResults([]);
+      return;
+    }
+    if (parseLatLngPair(trimmed)) {
+      setSearchStatus("idle");
+      setResults([]);
+      return;
+    }
+    const handle = setTimeout(() => {
+      void runSearch(trimmed);
+    }, SEARCH_DEBOUNCE_MS);
+    return () => {
+      clearTimeout(handle);
+      ++searchGenRef.current;
+    };
+  }, [query, resultsOpen, searchEnabled, runSearch]);
+
+  useEffect(() => {
+    if (!resultsOpen || shouldUseSheet) return;
+    const onDoc = (event: MouseEvent) => {
+      const root = searchRootRef.current;
+      if (root && event.target instanceof Node && root.contains(event.target)) return;
+      closeSearch(false);
+    };
+    const onKey = (event: globalThis.KeyboardEvent) => {
+      if (event.key === "Escape") closeSearch();
+    };
+    document.addEventListener("mousedown", onDoc);
+    document.addEventListener("keydown", onKey);
+    return () => {
+      document.removeEventListener("mousedown", onDoc);
+      document.removeEventListener("keydown", onKey);
+    };
+  }, [resultsOpen, shouldUseSheet, closeSearch]);
+
   const makeHandlers = useCallback(
     (currentValue: string, onValueChange: (value: string) => void) => {
       onValueChangeRef.current = onValueChange;
@@ -683,64 +1121,329 @@ export function Geolocation({
       const coordinates = parseGeoValue(currentValue);
       const shape = detectGeoShape(currentValue);
       const write = (lat: number, lng: number) => {
+        cancelLocate();
         onValueChange(
           formatGeoValue({ lat: clampLat(lat), lng: clampLng(lng) }, shape, currentValue),
         );
       };
       return {
         coordinates,
-        onCommitCoordinates: write,
-        onMapChange: write,
+        onCommitCoordinates: (lat: number, lng: number) => {
+          write(lat, lng);
+          selectedPlaceRef.current = null;
+          queryIsAddressRef.current = true;
+        },
+        onMapChange: (lat: number, lng: number) => {
+          write(lat, lng);
+          selectedPlaceRef.current = null;
+          queryIsAddressRef.current = true;
+        },
         onUseMyLocation: () => {
           void startLocate();
         },
         onRetryLocate: () => {
           requestPosition();
         },
-        onCloseLocate: () => {
-          setLocatePhase("idle");
-          setLocateError(null);
+        onCloseLocate: cancelLocate,
+        onPick: (result: GeocodeResult) => {
+          ++reverseGenRef.current;
+          const place = { ...result, lat: clampLat(result.lat), lng: clampLng(result.lng) };
+          selectedPlaceRef.current = { key: coordinateKey(place), place };
+          write(result.lat, result.lng);
+          // A controlled parent may reject or defer the proposal. Keep its
+          // label as a query/candidate until the bound pair actually matches.
+          queryIsAddressRef.current = true;
+          setQuery(formatPlace(result));
+          closeSearch();
+          setCellOpen(false);
+          setSearchStatus("idle");
+        },
+        onPickPair: (lat: number, lng: number) => {
+          write(lat, lng);
+          selectedPlaceRef.current = null;
+          queryIsAddressRef.current = true;
+          closeSearch();
+          setCellOpen(false);
+          setSearchStatus("idle");
+        },
+        onClear: () => {
+          cancelLocate();
+          ++searchGenRef.current;
+          ++reverseGenRef.current;
+          selectedPlaceRef.current = null;
+          onValueChange("");
+          applyAddress(null, true);
+          setQuery("");
+          setResults([]);
+          setSearchStatus("idle");
         },
       };
     },
-    [startLocate, requestPosition],
+    [startLocate, requestPosition, cancelLocate, applyAddress, closeSearch],
   );
 
   const mapHeight = getFieldHeight((size ?? knobProps.sizeToken) as SizeTokens, compact ? 4 : 5);
+  const displayError = error || preflightError;
 
-  // Skeleton mirrors map-primary anatomy (no lat/lng row).
-  if (skeleton) {
+  const renderSearch = (
+    handlers: ReturnType<typeof makeHandlers>,
+    opts: { sheetHeader?: boolean; editingCell?: boolean } = {},
+  ) => {
+    const showClear = Boolean(query) && !disabled && !readOnly;
+    const inputRef = opts.sheetHeader ? sheetSearchInputRef : searchInputRef;
+    const activateNativeSearch = (focusInput = false) => {
+      nativeSearchFocus.activate();
+      if (!searchEnabled || opts.editingCell) return;
+      const nativeInput = inputRef.current as unknown as {
+        isFocused?: () => boolean;
+        focus: () => void;
+      } | null;
+      // Let first focus open the keyboard before mounting the modal. A restored
+      // input is already focused, so a deliberate new press must open directly.
+      if (nativeInput?.isFocused?.()) setResultsOpen(true);
+      else if (focusInput) nativeInput?.focus();
+    };
+    const clearSearch = () => {
+      handlers.onClear();
+      closingSearchRef.current = true;
+      if (isWeb) inputRef.current?.focus({ preventScroll: true });
+      closingSearchRef.current = false;
+    };
     return (
-      <FieldLayout id={id} label={label} size={size} knobProps={knobProps}>
-        <Skeleton variant="rounded" width="100%" height={mapHeight} />
-      </FieldLayout>
+      <InputParts size={size || knobProps.sizeToken}>
+        <InputParts.Box
+          disabled={disabled || !searchEnabled}
+          // Keep the square Clear target pressable across the frame's border.
+          style={{ overflow: "visible" }}
+          {...(opts.sheetHeader
+            ? {
+                borderWidth: 0,
+                borderBottomWidth: 1,
+                borderRadius: 0,
+              }
+            : {})}
+        >
+          <InputParts.Section>
+            <InputParts.Icon adornment="leading">
+              <MagnifyingGlassIcon size={16} />
+            </InputParts.Icon>
+          </InputParts.Section>
+          <InputParts.Section>
+            <InputParts.Area
+              ref={inputRef as never}
+              value={query}
+              disabled={disabled || !searchEnabled}
+              placeholder={t("Search address or place")}
+              aria-label={t("Search for a location")}
+              role="combobox"
+              aria-haspopup="listbox"
+              aria-expanded={resultsOpen}
+              aria-controls={listId}
+              aria-autocomplete="list"
+              data-testid="geolocation-search"
+              onChangeText={(text: string) => {
+                if (!isWeb) nativeSearchFocus.activate();
+                ++searchGenRef.current;
+                queryIsAddressRef.current = false;
+                setResults([]);
+                setSearchStatus("idle");
+                setQuery(text);
+                if (searchEnabled) setResultsOpen(true);
+              }}
+              onKeyDown={(event: KeyboardEvent) => {
+                if (event.key === "ArrowDown") {
+                  if (searchEnabled) setResultsOpen(true);
+                  event.preventDefault();
+                  document
+                    .getElementById(listId)
+                    ?.querySelector<HTMLElement>("[role='option']:not([aria-disabled='true'])")
+                    ?.focus();
+                }
+              }}
+              onClick={() => {
+                if (searchEnabled) setResultsOpen(true);
+              }}
+              {...(!isWeb
+                ? {
+                    onPressIn: () => activateNativeSearch(),
+                    onAccessibilityTap: () => activateNativeSearch(true),
+                    onBlur: () => nativeSearchFocus.blur(!!opts.sheetHeader, resultsOpen),
+                  }
+                : {})}
+              onFocus={() => {
+                if (
+                  searchEnabled &&
+                  !opts.editingCell &&
+                  !closingSearchRef.current &&
+                  (isWeb || nativeSearchFocus.canOpen(!!opts.sheetHeader))
+                )
+                  setResultsOpen(true);
+              }}
+            />
+          </InputParts.Section>
+          {showClear ? (
+            <InputParts.Section>
+              <InputParts.Button
+                glyphRing
+                onPress={clearSearch}
+                onKeyDown={(event: KeyboardEvent) => {
+                  if (event.key === "Enter" || event.key === " ") {
+                    event.preventDefault();
+                    event.stopPropagation();
+                    clearSearch();
+                  }
+                }}
+                aria-label={t("Clear location")}
+                testID="geolocation-search-clear"
+              >
+                <InputParts.Icon>
+                  <XIcon size={14} />
+                </InputParts.Icon>
+              </InputParts.Button>
+            </InputParts.Section>
+          ) : null}
+        </InputParts.Box>
+      </InputParts>
     );
-  }
+  };
 
-  // Pre-flight failures surface as the field error; post-preflight errors stay
-  // inside the locate panel (Retry + Close) and are not mirrored here.
-  const displayError = error || preflightError;
+  const renderResults = (handlers: ReturnType<typeof makeHandlers>) => (
+    <SearchResultsList
+      listId={listId}
+      status={searchStatus}
+      query={query.trim()}
+      results={results}
+      pair={parseLatLngPair(query)}
+      onLocate={handlers.onUseMyLocation}
+      onPick={handlers.onPick}
+      onPickPair={handlers.onPickPair}
+      locateDisabled={disabled || locatePhase === "locating"}
+    />
+  );
+
+  const renderFormBody = (
+    currentValue: string,
+    onValueChange: (v: string) => void,
+    editingCell = false,
+    resolvedError: string | boolean | undefined = displayError,
+  ): ReactNode => {
+    const handlers = makeHandlers(currentValue, onValueChange);
+    const coordinates = handlers.coordinates;
+    const key = coordinates ? coordinateKey(coordinates) : null;
+    const selected = selectedPlaceRef.current;
+    const displayAddress =
+      (selected?.key === key ? formatPlace(selected.place) : null) ??
+      (address?.key === key ? address.label : null) ??
+      (coordinates ? formatCoordPair(coordinates.lat, coordinates.lng) : null);
+
+    if (inTableCell && !editingCell) {
+      const face = (
+        <CellFace
+          address={displayAddress}
+          coordinates={coordinates}
+          onOpen={!disabled && !readOnly ? () => setCellOpen(true) : undefined}
+        />
+      );
+      if (readOnly || disabled) return face;
+      return (
+        <FloatingPanel
+          open={cellOpen}
+          onOpenChange={setCellOpen}
+          disabled={disabled}
+          fitContent={false}
+          contentPadding="none"
+          trigger={face}
+        >
+          <YStack minWidth={260} maxWidth={420}>
+            {renderFormBody(currentValue, onValueChange, true, resolvedError)}
+          </YStack>
+        </FloatingPanel>
+      );
+    }
+
+    if (readOnly) {
+      return (
+        <YStack gap="$2">
+          <XStack testID="geolocation-readonly-address" alignItems="center" gap="$2" minHeight={25}>
+            <MapPinIcon size={14} color={glyphColor} />
+            <Text fontSize="$4" lineHeight={25} color="$color12">
+              {displayAddress ?? t("No location set")}
+            </Text>
+          </XStack>
+          <GeoMapSurface
+            id={id}
+            coordinates={coordinates}
+            onCommitCoordinates={handlers.onCommitCoordinates}
+            onUseMyLocation={handlers.onUseMyLocation}
+            onRetryLocate={handlers.onRetryLocate}
+            onCloseLocate={handlers.onCloseLocate}
+            onMapChange={handlers.onMapChange}
+            disabled={!!disabled}
+            readOnly
+            locatePhase={locatePhase}
+            locateError={locateError}
+            knobProps={knobProps}
+            locationIcon={resolvedLocationIcon}
+            expandIcon={expandIcon}
+            renderMap={renderMap}
+            required={required}
+            hasError={!!resolvedError}
+            mapHeight={mapHeight}
+          />
+        </YStack>
+      );
+    }
+
+    const resultsPanel =
+      resultsOpen && searchEnabled ? (
+        shouldUseSheet ? (
+          <FloatingPanel
+            open={resultsOpen}
+            onOpenChange={(open) => (open ? setResultsOpen(true) : closeSearch())}
+            onNativeShow={() => sheetSearchInputRef.current?.focus()}
+            skipReturnFocusRef={skipResultsReturnFocusRef}
+            sheet
+            sheetFill
+            scrollable
+            contentPadding="none"
+            header={renderSearch(handlers, { sheetHeader: true })}
+            trigger={<View testID="geolocation-sheet-trigger" height={1} width="100%" />}
+          >
+            <YStack testID="geolocation-results-sheet">{renderResults(handlers)}</YStack>
+          </FloatingPanel>
+        ) : (
+          <YStack
+            position="absolute"
+            top="100%"
+            left={0}
+            right={0}
+            zIndex={zIndex.dropdown}
+            backgroundColor="$color1"
+            borderWidth={1}
+            borderColor={formInputColors.border.base}
+            borderRadius={knobProps.borderRadius.borderRadius}
+            overflow="hidden"
+            style={{ boxShadow: RESULTS_PANEL_SHADOW }}
+          >
+            <ScrollView maxHeight={mapHeight * 1.5}>{renderResults(handlers)}</ScrollView>
+          </YStack>
+        )
+      ) : null;
 
-  if (!resolvedForm || !name) {
-    const handlers = makeHandlers(value || "", (v) => onChange?.(v));
     return (
-      <FieldLayout
-        id={id}
-        label={label}
-        labelProps={labelProps}
-        error={displayError}
-        helperText={helperText}
-        required={required}
-        size={size}
-        knobProps={knobProps}
-        onBlur={onBlur}
-        // LC-40: FieldLayout owns the dimWhole assembly dim (keepLabel pins
-        // the sibling label/helper readable) — it needs the disabled state.
-        disabled={disabled}
-      >
+      <YStack gap="$2">
+        <YStack
+          ref={searchRootRef as never}
+          position="relative"
+          testID="geolocation-search-anchor"
+          data-sheet={shouldUseSheet ? "true" : "false"}
+        >
+          {renderSearch(handlers, { editingCell })}
+          {resultsPanel}
+        </YStack>
         <GeoMapSurface
           id={id}
-          coordinates={handlers.coordinates}
+          coordinates={coordinates}
           onCommitCoordinates={handlers.onCommitCoordinates}
           onUseMyLocation={handlers.onUseMyLocation}
           onRetryLocate={handlers.onRetryLocate}
@@ -751,17 +1454,61 @@ export function Geolocation({
           locatePhase={locatePhase}
           locateError={locateError}
           knobProps={knobProps}
-          locationIcon={locationIcon}
+          locationIcon={resolvedLocationIcon}
           expandIcon={expandIcon}
           renderMap={renderMap}
           required={required}
-          hasError={!!displayError}
+          hasError={!!resolvedError}
           mapHeight={mapHeight}
         />
+      </YStack>
+    );
+  };
+
+  if (skeleton) {
+    return (
+      <FieldLayout id={id} label={label} size={size} knobProps={knobProps}>
+        <YStack gap="$2">
+          <Skeleton variant="rounded" width="100%" height={44} />
+          <Skeleton variant="rounded" width="100%" height={mapHeight} />
+        </YStack>
       </FieldLayout>
     );
   }
 
+  const wrap = (
+    currentValue: string,
+    onValueChange: (v: string) => void,
+    resolvedError?: string | boolean,
+    fieldBlur?: (...args: any[]) => void,
+  ) => {
+    const coordinates = parseGeoValue(currentValue);
+    const taughtHelper =
+      helperText ??
+      (!coordinates && !readOnly ? t("Search, tap the map, or use your location.") : undefined);
+    return (
+      <FieldLayout
+        id={id}
+        label={label}
+        labelProps={labelProps}
+        error={resolvedError ?? displayError}
+        helperText={inTableCell ? undefined : taughtHelper}
+        required={required}
+        size={size}
+        knobProps={knobProps}
+        onBlur={fieldBlur ?? onBlur}
+        disabled={disabled}
+      >
+        <GeolocationValueSync value={currentValue} runReverse={runReverse} />
+        {renderFormBody(currentValue, onValueChange, false, resolvedError)}
+      </FieldLayout>
+    );
+  };
+
+  if (!resolvedForm || !name) {
+    return wrap(value || "", (v) => onChange?.(v));
+  }
+
   return (
     <Field
       form={resolvedForm}
@@ -771,47 +1518,32 @@ export function Geolocation({
     >
       {(field) => {
         const resolvedError = getFieldError(field, displayError);
-        const handlers = makeHandlers((field.state.value as string) || "", (v) => {
-          field.handleChange(v as any);
-          onChange?.(v);
-        });
-        return (
-          <FieldLayout
-            id={id}
-            label={label}
-            labelProps={labelProps}
-            error={resolvedError}
-            helperText={helperText}
-            required={required}
-            size={size}
-            knobProps={knobProps}
-            onBlur={mergeFieldHandler(field, "handleBlur", onBlur)}
-            // LC-40: see standalone branch — FieldLayout carries dimWhole.
-            disabled={disabled}
-          >
-            <GeoMapSurface
-              id={id}
-              coordinates={handlers.coordinates}
-              onCommitCoordinates={handlers.onCommitCoordinates}
-              onUseMyLocation={handlers.onUseMyLocation}
-              onRetryLocate={handlers.onRetryLocate}
-              onCloseLocate={handlers.onCloseLocate}
-              onMapChange={handlers.onMapChange}
-              disabled={!!disabled}
-              readOnly={!!readOnly}
-              locatePhase={locatePhase}
-              locateError={locateError}
-              knobProps={knobProps}
-              locationIcon={locationIcon}
-              expandIcon={expandIcon}
-              renderMap={renderMap}
-              required={required}
-              hasError={!!resolvedError}
-              mapHeight={mapHeight}
-            />
-          </FieldLayout>
+        return wrap(
+          (field.state.value as string) || "",
+          (v) => {
+            field.handleChange(v as never);
+            onChange?.(v);
+          },
+          resolvedError,
+          mergeFieldHandler(field, "handleBlur", onBlur),
         );
       }}
     </Field>
   );
 }
+
+function GeolocationValueSync({
+  value,
+  runReverse,
+}: {
+  value: string;
+  runReverse: (lat?: number, lng?: number) => void;
+}) {
+  const coords = parseGeoValue(value);
+  const key = coords ? coordinateKey(coords) : "";
+  useEffect(() => {
+    const next = parseGeoValue(value);
+    void runReverse(next?.lat, next?.lng);
+  }, [key, value, runReverse]);
+  return null;
+}