@multiplatform.one/forms 6.1.0 → 6.3.0

package/src/fields/Geolocation/index.tsx

@@ -1,14 +1,22 @@
 import { useResolvedKnobs, type KnobProps } from "@multiplatform.one/theme";
-import type { ReactNode } from "react";
-import { useCallback, useMemo, useState } from "react";
+import { NavigationArrowIcon } from "@phosphor-icons/react";
+import type { MutableRefObject, ReactNode } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
 import type { LabelProps, SizeTokens } from "tamagui";
 import { 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 { Input as InputParts } from "../../InputParts";
 import { Skeleton } from "../../Skeleton";
+import {
+  queryPermissionState,
+  type CapabilityPreflightResult,
+} from "../../shared/capabilityPreflight";
 import { formCommonColors, formInputColors } from "../../shared/colorRamps";
+import { t } from "../../shared/t";
 import {
   getFieldError,
   mergeFieldHandler,
@@ -22,6 +30,53 @@ interface GeoValue {
   lng: number;
 }
 
+type LocatePhase = "idle" | "locating" | "error";
+
+/**
+ * Geolocation capability pre-flight (LC-19 CAPABILITY-PREFLIGHT). Runs BEFORE
+ * the locate surface / permission prompt is presented: checks secure context,
+ * geolocation API support, and that permission is not hard-denied. A `prompt`
+ * permission state passes — the prompt happens inside the stable locate
+ * surface, never as a locating-flash-then-fail flicker.
+ */
+export async function preflightGeolocation(): Promise<CapabilityPreflightResult> {
+  if (typeof navigator === "undefined" || !navigator.geolocation) {
+    const insecure = typeof window !== "undefined" && window.isSecureContext === false;
+    return {
+      ok: false,
+      reason: insecure
+        ? t("Geolocation unavailable: insecure context (HTTPS required).")
+        : t("Geolocation unavailable: not supported in this browser."),
+    };
+  }
+  const permission = await queryPermissionState("geolocation");
+  if (permission === "denied") {
+    return {
+      ok: false,
+      reason: t(
+        "Geolocation unavailable: permission denied. Allow location access in browser settings.",
+      ),
+    };
+  }
+  return { ok: true };
+}
+
+function mapGeolocationError(
+  err: GeolocationPositionError | { message?: string; code?: number },
+): string {
+  const code = "code" in err ? err.code : undefined;
+  if (code === 1) {
+    return t("Location permission denied. Please allow location access.");
+  }
+  if (code === 2) {
+    return t("Location unavailable. Try again or enter coordinates manually.");
+  }
+  if (code === 3) {
+    return t("Location request timed out. Try again.");
+  }
+  return err.message || t("Failed to get location");
+}
+
 function parseGeoValue(value: string): GeoValue {
   try {
     const parsed = JSON.parse(value) as Record<string, unknown>;
@@ -41,66 +96,142 @@ function clampLng(val: number): number {
   return Math.max(-180, Math.min(180, val));
 }
 
-function useMapSrc(lat: number, lng: number, delta = 0.02) {
-  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]);
+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.
+ */
+function tryParseCoord(text: string, clamp: (n: number) => number): number | undefined {
+  const trimmed = text.trim();
+  if (trimmed === "" || trimmed === "-" || trimmed === "." || trimmed === "-.") return undefined;
+  if (trimmed.endsWith(".")) return undefined;
+  const n = Number.parseFloat(trimmed);
+  if (Number.isNaN(n)) return undefined;
+  return clamp(n);
 }
 
-function DefaultMapPreview({
+/**
+ * Draft Lat/Lng editor hosted inside FloatingPanel (LC-21 EDITOR).
+ * Valid parses commit live — no Apply/Done. Outside/Escape closes the panel;
+ * parent flushes any remaining draft via `flushRef` on dismiss.
+ */
+function CoordinatesPanel({
   lat,
   lng,
+  onCommit,
+  flushRef,
   knobProps,
-  onExpand,
-  expandIcon,
+  required,
+  hasError,
 }: {
   lat: number;
   lng: number;
+  onCommit: (lat: number, lng: number) => void;
+  flushRef: MutableRefObject<(() => void) | null>;
   knobProps: KnobProps;
-  onExpand?: () => void;
-  expandIcon?: ReactNode;
+  required?: boolean;
+  hasError?: boolean;
 }) {
-  const src = useMapSrc(lat, lng);
+  const [latText, setLatText] = useState(String(lat));
+  const [lngText, setLngText] = useState(String(lng));
+  const latTextRef = useRef(latText);
+  const lngTextRef = useRef(lngText);
+  const committedRef = useRef({ lat, lng });
+
+  useEffect(() => {
+    setLatText(String(lat));
+    setLngText(String(lng));
+    latTextRef.current = String(lat);
+    lngTextRef.current = String(lng);
+    committedRef.current = { lat, lng };
+  }, [lat, lng]);
+
+  const commitPair = useCallback(
+    (nextLat: number, nextLng: number) => {
+      if (nextLat === committedRef.current.lat && nextLng === committedRef.current.lng) return;
+      committedRef.current = { lat: nextLat, lng: nextLng };
+      onCommit(nextLat, nextLng);
+    },
+    [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);
+    const nextLat = Number.isNaN(rawLat) ? committedRef.current.lat : clampLat(rawLat);
+    const nextLng = Number.isNaN(rawLng) ? committedRef.current.lng : clampLng(rawLng);
+    commitPair(nextLat, nextLng);
+  }, [commitPair]);
+
+  useEffect(() => {
+    flushRef.current = flushDraft;
+    return () => {
+      flushRef.current = null;
+    };
+  }, [flushRef, flushDraft]);
+
+  const handleLatChange = (text: string) => {
+    setLatText(text);
+    latTextRef.current = text;
+    const parsed = tryParseCoord(text, clampLat);
+    if (parsed !== undefined) {
+      commitPair(parsed, committedRef.current.lng);
+    }
+  };
+
+  const handleLngChange = (text: string) => {
+    setLngText(text);
+    lngTextRef.current = text;
+    const parsed = tryParseCoord(text, clampLng);
+    if (parsed !== undefined) {
+      commitPair(committedRef.current.lat, parsed);
+    }
+  };
 
   return (
-    <YStack
-      {...knobProps.borderRadius}
-      {...knobProps.inputSurface}
-      borderColor={formInputColors.border.base}
-      overflow="hidden"
-      height={200}
-      position="relative"
-    >
-      {isWeb ? (
-        <iframe
-          title="Location preview"
-          src={src}
-          width="100%"
-          height="100%"
-          style={{ border: 0, display: "block" }}
-          loading="lazy"
-        />
-      ) : (
-        <YStack
-          flex={1}
-          alignItems="center"
-          justifyContent="center"
-          backgroundColor="$backgroundHover"
-        >
-          <Text color="$colorSubtle" fontSize="$2">
-            Map preview (web only)
-          </Text>
-          <Text color="$colorSubtle" fontSize="$1">{`${lat.toFixed(4)}, ${lng.toFixed(4)}`}</Text>
-        </YStack>
-      )}
-      {onExpand && expandIcon && (
-        <View position="absolute" top="$2" right="$2" zIndex={1}>
-          <Button size="$2" circular onPress={onExpand} backgroundColor="$background" opacity={0.9}>
-            {expandIcon}
-          </Button>
-        </View>
-      )}
+    <YStack testID="geolocation-coords-panel" gap="$3" minWidth={260} {...knobProps.panelPadding}>
+      <YStack gap="$1">
+        <Text fontSize="$1" {...knobProps.body} color={formCommonColors.muted}>
+          {t("Lat")}
+        </Text>
+        <InputParts size={knobProps.sizeToken}>
+          <InputParts.Box>
+            <InputParts.Area
+              value={latText}
+              onChangeText={handleLatChange}
+              onBlur={flushDraft}
+              placeholder={t("-90 to 90")}
+              inputMode="decimal"
+              aria-label={t("Latitude")}
+              aria-required={required || undefined}
+              aria-invalid={hasError || undefined}
+            />
+          </InputParts.Box>
+        </InputParts>
+      </YStack>
+      <YStack gap="$1">
+        <Text fontSize="$1" {...knobProps.body} color={formCommonColors.muted}>
+          {t("Lng")}
+        </Text>
+        <InputParts size={knobProps.sizeToken}>
+          <InputParts.Box>
+            <InputParts.Area
+              value={lngText}
+              onChangeText={handleLngChange}
+              onBlur={flushDraft}
+              placeholder={t("-180 to 180")}
+              inputMode="decimal"
+              aria-label={t("Longitude")}
+              aria-required={required || undefined}
+              aria-invalid={hasError || undefined}
+            />
+          </InputParts.Box>
+        </InputParts>
+      </YStack>
     </YStack>
   );
 }
@@ -108,16 +239,17 @@ function DefaultMapPreview({
 function ExpandedMapView({
   lat,
   lng,
-  onChange: _onChange,
-  disabled: _disabled,
+  onChange,
+  disabled,
+  readOnly,
 }: {
   lat: number;
   lng: number;
   onChange: (lat: number, lng: number) => void;
   disabled: boolean;
+  readOnly?: boolean;
 }) {
   const { knobProps } = useResolvedKnobs();
-  const src = useMapSrc(lat, lng, 0.05);
 
   return (
     <YStack
@@ -126,28 +258,16 @@ function ExpandedMapView({
       borderRadius={knobProps.borderRadius.borderRadius}
       overflow="hidden"
     >
-      {isWeb ? (
-        <iframe
-          title="Location selection"
-          src={src}
-          width="100%"
-          height="100%"
-          style={{ border: 0, display: "block", minHeight: 400 }}
-          loading="lazy"
-        />
-      ) : (
-        <YStack
-          flex={1}
-          alignItems="center"
-          justifyContent="center"
-          backgroundColor="$backgroundHover"
-        >
-          <Text color="$colorSubtle" fontSize="$2">
-            Map view (web only)
-          </Text>
-          <Text color="$colorSubtle" fontSize="$1">{`${lat.toFixed(4)}, ${lng.toFixed(4)}`}</Text>
-        </YStack>
-      )}
+      <GeolocationMap
+        lat={lat}
+        lng={lng}
+        delta={0.05}
+        minHeight={400}
+        title={t("Location selection")}
+        onChange={onChange}
+        disabled={disabled}
+        readOnly={readOnly}
+      />
     </YStack>
   );
 }
@@ -160,15 +280,17 @@ export interface GeolocationMapProps {
   knobProps: KnobProps;
 }
 
-function GeoInputs({
+function GeoMapSurface({
   coordinates,
-  onLatChange,
-  onLngChange,
+  onCommitCoordinates,
   onUseMyLocation,
+  onRetryLocate,
+  onCloseLocate,
   onMapChange,
   disabled,
   readOnly,
-  locating,
+  locatePhase,
+  locateError,
   knobProps,
   locationIcon,
   expandIcon,
@@ -177,13 +299,15 @@ function GeoInputs({
   hasError,
 }: {
   coordinates: GeoValue;
-  onLatChange: (text: string) => void;
-  onLngChange: (text: string) => void;
+  onCommitCoordinates: (lat: number, lng: number) => void;
   onUseMyLocation: () => void;
+  onRetryLocate: () => void;
+  onCloseLocate: () => void;
   onMapChange: (lat: number, lng: number) => void;
   disabled: boolean;
   readOnly?: boolean;
-  locating: boolean;
+  locatePhase: LocatePhase;
+  locateError: string | null;
   knobProps: KnobProps;
   locationIcon: ReactNode;
   expandIcon?: ReactNode;
@@ -192,91 +316,207 @@ function GeoInputs({
   hasError?: boolean;
 }) {
   const [expanded, setExpanded] = useState(false);
+  const [coordsOpen, setCoordsOpen] = useState(false);
+  const coordsFlushRef = useRef<(() => void) | null>(null);
+  const locating = locatePhase === "locating";
+  const locateSurfaceOpen = locatePhase === "locating" || locatePhase === "error";
 
   const handleExpand = expandIcon ? () => setExpanded(true) : undefined;
 
-  const mapNode = renderMap ? (
-    renderMap({
-      lat: coordinates.lat,
-      lng: coordinates.lng,
-      onChange: onMapChange,
-      disabled,
-      knobProps,
-    })
-  ) : (
-    <DefaultMapPreview
-      lat={coordinates.lat}
-      lng={coordinates.lng}
-      knobProps={knobProps}
-      onExpand={handleExpand}
-      expandIcon={expandIcon}
-    />
-  );
+  // 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?.();
+    }
+    setCoordsOpen(open);
+  };
+
+  const customMap = renderMap
+    ? renderMap({
+        lat: coordinates.lat,
+        lng: coordinates.lng,
+        onChange: onMapChange,
+        disabled,
+        knobProps,
+      })
+    : null;
 
   return (
     <>
-      {mapNode}
-      <XStack {...knobProps.gap} alignItems="flex-end">
-        <YStack flex={1} gap="$1">
-          <Text fontSize="$1" {...knobProps.body} color={formCommonColors.muted}>
-            Lat
-          </Text>
-          <InputParts size={knobProps.sizeToken}>
-            <InputParts.Box>
-              <InputParts.Area
-                value={String(coordinates.lat)}
-                onChangeText={readOnly ? undefined : onLatChange}
-                readOnly={readOnly}
-                aria-readonly={readOnly || undefined}
-                disabled={disabled}
-                placeholder="-90 to 90"
-                inputMode="decimal"
-                aria-required={required || undefined}
-                aria-invalid={hasError || undefined}
-              />
-            </InputParts.Box>
-          </InputParts>
-        </YStack>
-        <YStack flex={1} gap="$1">
-          <Text fontSize="$1" {...knobProps.body} color={formCommonColors.muted}>
-            Lng
+      <YStack
+        testID="geolocation-map"
+        {...knobProps.borderRadius}
+        {...knobProps.inputSurface}
+        borderColor={formInputColors.border.base}
+        overflow="hidden"
+        height={200}
+        position="relative"
+      >
+        {/* Platform-split surface: OSM embed on web, expo-maps on native */}
+        {customMap ?? (
+          <GeolocationMap
+            lat={coordinates.lat}
+            lng={coordinates.lng}
+            onChange={onMapChange}
+            disabled={disabled}
+            readOnly={readOnly}
+          />
+        )}
+
+        {/* Compact read-only coords chip */}
+        <View
+          position="absolute"
+          top="$2"
+          insetInlineStart="$2"
+          zIndex={1}
+          backgroundColor="$background"
+          opacity={0.92}
+          paddingHorizontal="$2"
+          paddingVertical="$1"
+          {...knobProps.borderRadius}
+        >
+          <Text
+            testID="geolocation-coords-chip"
+            fontSize="$1"
+            {...knobProps.body}
+            color={formCommonColors.muted}
+          >
+            {formatCoordChip(coordinates.lat, coordinates.lng)}
           </Text>
-          <InputParts size={knobProps.sizeToken}>
-            <InputParts.Box>
-              <InputParts.Area
-                value={String(coordinates.lng)}
-                onChangeText={readOnly ? undefined : onLngChange}
-                readOnly={readOnly}
-                aria-readonly={readOnly || undefined}
-                disabled={disabled}
-                placeholder="-180 to 180"
-                inputMode="decimal"
-                aria-required={required || undefined}
-                aria-invalid={hasError || undefined}
+        </View>
+
+        {/* Expand overlay (top-end) */}
+        {handleExpand && expandIcon && (
+          <View position="absolute" top="$2" insetInlineEnd="$2" zIndex={1}>
+            <Button
+              size="$2"
+              circular
+              onPress={handleExpand}
+              backgroundColor="$background"
+              opacity={0.9}
+              aria-label={t("Expand map")}
+            >
+              {expandIcon}
+            </Button>
+          </View>
+        )}
+
+        {/* Coordinates editor trigger (bottom-start) — FloatingPanel / LC-06 */}
+        {!readOnly && (
+          <View position="absolute" bottom="$2" insetInlineStart="$2" zIndex={1}>
+            <FloatingPanel
+              open={coordsOpen}
+              onOpenChange={handleCoordsOpenChange}
+              disabled={disabled}
+              fitContent
+              sizing="fill"
+              contentPadding="none"
+              trigger={
+                <Button
+                  size="$2"
+                  disabled={disabled}
+                  backgroundColor="$background"
+                  opacity={0.9}
+                  aria-label={t("Edit coordinates")}
+                  // Web: trigger owns open (ColorPicker pattern). Native: FloatingPanel
+                  // owns the open gesture — a second onPress would double-toggle.
+                  onPress={isWeb && !disabled ? () => setCoordsOpen(true) : undefined}
+                >
+                  <Button.Text>{t("Coordinates")}</Button.Text>
+                </Button>
+              }
+            >
+              <CoordinatesPanel
+                lat={coordinates.lat}
+                lng={coordinates.lng}
+                knobProps={knobProps}
+                required={required}
+                hasError={hasError}
+                flushRef={coordsFlushRef}
+                onCommit={onCommitCoordinates}
               />
-            </InputParts.Box>
-          </InputParts>
-        </YStack>
+            </FloatingPanel>
+          </View>
+        )}
+
+        {/* Locate overlay (bottom-end) — LC-19 preflight runs on press */}
         {!readOnly && (
-          <Button
-            size={knobProps.sizeToken}
-            disabled={disabled || locating}
-            onPress={onUseMyLocation}
-            flexShrink={0}
-            icon={locating ? <Spinner size="small" /> : locationIcon}
-          >
-            <Button.Text>{locating ? "Locating..." : "Locate"}</Button.Text>
-          </Button>
+          <View position="absolute" bottom="$2" insetInlineEnd="$2" zIndex={1}>
+            <Button
+              size="$2"
+              disabled={disabled || locating}
+              onPress={onUseMyLocation}
+              backgroundColor="$background"
+              opacity={0.9}
+              icon={locating ? <Spinner size="small" /> : locationIcon}
+              aria-label={locating ? t("Locating") : t("Locate")}
+            >
+              <Button.Text>{locating ? t("Locating...") : t("Locate")}</Button.Text>
+            </Button>
+          </View>
         )}
-      </XStack>
+      </YStack>
+
+      {/*
+        LC-19: locate surface only mounts after a passing pre-flight. Init /
+        prompt failures render INSIDE the still-open surface with Retry + Close
+        — never mount-fail-unmount.
+      */}
+      {locateSurfaceOpen && (
+        <YStack
+          testID="geolocation-locate-panel"
+          {...knobProps.borderRadius}
+          {...knobProps.inputSurface}
+          borderColor={formInputColors.border.base}
+          padding="$3"
+          gap="$3"
+          alignItems="center"
+        >
+          {locatePhase === "error" ? (
+            <>
+              <Text {...knobProps.body} color={formCommonColors.error} textAlign="center">
+                {locateError}
+              </Text>
+              <XStack gap="$2">
+                <Button
+                  size={knobProps.sizeToken}
+                  onPress={onRetryLocate}
+                  aria-label={t("Retry location")}
+                >
+                  {t("Retry")}
+                </Button>
+                <Button
+                  size={knobProps.sizeToken}
+                  onPress={onCloseLocate}
+                  aria-label={t("Close location")}
+                >
+                  {t("Close")}
+                </Button>
+              </XStack>
+            </>
+          ) : (
+            <Text {...knobProps.body} textAlign="center" opacity={0.7}>
+              {t("Requesting location…")}
+            </Text>
+          )}
+        </YStack>
+      )}
 
+      {/* Expand uses AdaptivePopup — large map exceeds FloatingPanel fitContent */}
       {expandIcon && (
-        <AdaptivePopup open={expanded} onOpenChange={setExpanded} title="Select Location" size="lg">
+        <AdaptivePopup
+          open={expanded}
+          onOpenChange={setExpanded}
+          title={t("Select Location")}
+          size="lg"
+        >
           <ExpandedMapView
             lat={coordinates.lat}
             lng={coordinates.lng}
             onChange={onMapChange}
             disabled={disabled}
+            readOnly={readOnly}
           />
         </AdaptivePopup>
       )}
@@ -302,8 +542,12 @@ export interface GeolocationProps {
   onBlur?: (...args: any[]) => void;
   disabled?: boolean;
   readOnly?: boolean;
-  /** Icon for the locate button */
-  locationIcon: ReactNode;
+  /**
+   * Icon for the locate button. Optional — bare use falls back to the package
+   * navigation-arrow glyph (Phosphor, the house icon set) so the locate
+   * affordance renders without icon wiring (Axiom 13 ONE BODY).
+   */
+  locationIcon?: ReactNode;
   /** Icon for the expand/fullscreen button. If provided, enables fullscreen map view. */
   expandIcon?: ReactNode;
   /** Custom map component. Receives lat/lng and an onChange callback for pick-on-map. */
@@ -314,6 +558,11 @@ export interface GeolocationProps {
   compact?: boolean;
 }
 
+// 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} />;
+
 export function Geolocation({
   name,
   form: formProp,
@@ -331,7 +580,7 @@ export function Geolocation({
   onBlur,
   disabled,
   readOnly,
-  locationIcon,
+  locationIcon = defaultLocationIcon,
   expandIcon,
   renderMap,
   skeleton,
@@ -339,71 +588,100 @@ export function Geolocation({
 }: GeolocationProps) {
   const { resolvedForm, knobProps, id } = useFormField({ form: formProp, id: idProp, compact });
   const resolvedValidators = useResolvedValidators(required, validators, label, name);
-  const [locating, setLocating] = useState(false);
-  const [geoError, setGeoError] = useState<string | undefined>();
+  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 preflightingRef = useRef(false);
+  const onValueChangeRef = useRef<(value: string) => void>(() => {});
+
+  const requestPosition = useCallback(() => {
+    if (!navigator?.geolocation) {
+      setLocateError(t("Geolocation unavailable: not supported in this browser."));
+      setLocatePhase("error");
+      return;
+    }
+    setLocatePhase("locating");
+    setLocateError(null);
+    navigator.geolocation.getCurrentPosition(
+      (position) => {
+        const lat = clampLat(position.coords.latitude);
+        const lng = clampLng(position.coords.longitude);
+        onValueChangeRef.current(JSON.stringify({ lat, lng }));
+        setLocatePhase("idle");
+        setLocateError(null);
+      },
+      (err) => {
+        // Surface stays OPEN: error renders inside with Retry + Close.
+        setLocateError(mapGeolocationError(err));
+        setLocatePhase("error");
+      },
+      { enableHighAccuracy: true, timeout: 10000 },
+    );
+  }, []);
+
+  // 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;
+    try {
+      const result = await preflightGeolocation();
+      if (result.ok) {
+        setPreflightError(undefined);
+        requestPosition();
+      } else {
+        setPreflightError(result.reason);
+        setLocatePhase("idle");
+        setLocateError(null);
+      }
+    } finally {
+      preflightingRef.current = false;
+    }
+  }, [disabled, readOnly, locatePhase, requestPosition]);
 
   const makeHandlers = useCallback(
     (currentValue: string, onValueChange: (value: string) => void) => {
+      onValueChangeRef.current = onValueChange;
       const coordinates = currentValue ? parseGeoValue(currentValue) : { lat: 0, lng: 0 };
       return {
         coordinates,
-        onLatChange: (text: string) => {
-          const parsedNumber = Number.parseFloat(text);
-          if (Number.isNaN(parsedNumber) && text !== "" && text !== "-") return;
-          const lat = Number.isNaN(parsedNumber) ? 0 : clampLat(parsedNumber);
-          onValueChange(JSON.stringify({ lat, lng: coordinates.lng }));
-        },
-        onLngChange: (text: string) => {
-          const parsedNumber = Number.parseFloat(text);
-          if (Number.isNaN(parsedNumber) && text !== "" && text !== "-") return;
-          const lng = Number.isNaN(parsedNumber) ? 0 : clampLng(parsedNumber);
-          onValueChange(JSON.stringify({ lat: coordinates.lat, lng }));
+        onCommitCoordinates: (lat: number, lng: number) => {
+          onValueChange(JSON.stringify({ lat: clampLat(lat), lng: clampLng(lng) }));
         },
         onMapChange: (lat: number, lng: number) => {
           onValueChange(JSON.stringify({ lat: clampLat(lat), lng: clampLng(lng) }));
         },
         onUseMyLocation: () => {
-          if (disabled || readOnly) return;
-          if (!navigator?.geolocation) {
-            setGeoError("Geolocation is not supported by this browser");
-            return;
-          }
-          setLocating(true);
-          setGeoError(undefined);
-          navigator.geolocation.getCurrentPosition(
-            (position) => {
-              const lat = clampLat(position.coords.latitude);
-              const lng = clampLng(position.coords.longitude);
-              onValueChange(JSON.stringify({ lat, lng }));
-              setLocating(false);
-            },
-            (err) => {
-              setGeoError(err.message || "Failed to get location");
-              setLocating(false);
-            },
-            { enableHighAccuracy: true, timeout: 10000 },
-          );
+          void startLocate();
+        },
+        onRetryLocate: () => {
+          requestPosition();
+        },
+        onCloseLocate: () => {
+          setLocatePhase("idle");
+          setLocateError(null);
         },
       };
     },
-    [disabled],
+    [startLocate, requestPosition],
   );
 
-  // Render skeleton placeholder
+  // Skeleton mirrors map-primary anatomy (no lat/lng row).
   if (skeleton) {
     return (
       <FieldLayout id={id} label={label} size={size} knobProps={knobProps}>
         <Skeleton variant="rounded" width="100%" height={200} />
-        <XStack {...knobProps.gap} width="100%">
-          <Skeleton variant="rounded" width="100%" height={knobProps.sizeToken} flex={1} />
-          <Skeleton variant="rounded" width="100%" height={knobProps.sizeToken} flex={1} />
-          <Skeleton variant="rounded" width={80} height={knobProps.sizeToken} />
-        </XStack>
       </FieldLayout>
     );
   }
 
-  const displayError = error || geoError;
+  // 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;
 
   if (!resolvedForm || !name) {
     const handlers = makeHandlers(value || "", (v) => onChange?.(v));
@@ -418,16 +696,21 @@ export function Geolocation({
         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}
       >
-        <GeoInputs
+        <GeoMapSurface
           coordinates={handlers.coordinates}
-          onLatChange={handlers.onLatChange}
-          onLngChange={handlers.onLngChange}
+          onCommitCoordinates={handlers.onCommitCoordinates}
           onUseMyLocation={handlers.onUseMyLocation}
+          onRetryLocate={handlers.onRetryLocate}
+          onCloseLocate={handlers.onCloseLocate}
           onMapChange={handlers.onMapChange}
           disabled={!!disabled}
           readOnly={!!readOnly}
-          locating={locating}
+          locatePhase={locatePhase}
+          locateError={locateError}
           knobProps={knobProps}
           locationIcon={locationIcon}
           expandIcon={expandIcon}
@@ -463,15 +746,20 @@ export function Geolocation({
             size={size}
             knobProps={knobProps}
             onBlur={mergeFieldHandler(field, "handleBlur", onBlur)}
+            // LC-40: see standalone branch — FieldLayout carries dimWhole.
+            disabled={disabled}
           >
-            <GeoInputs
+            <GeoMapSurface
               coordinates={handlers.coordinates}
-              onLatChange={handlers.onLatChange}
-              onLngChange={handlers.onLngChange}
+              onCommitCoordinates={handlers.onCommitCoordinates}
               onUseMyLocation={handlers.onUseMyLocation}
+              onRetryLocate={handlers.onRetryLocate}
+              onCloseLocate={handlers.onCloseLocate}
               onMapChange={handlers.onMapChange}
               disabled={!!disabled}
-              locating={locating}
+              readOnly={!!readOnly}
+              locatePhase={locatePhase}
+              locateError={locateError}
               knobProps={knobProps}
               locationIcon={locationIcon}
               expandIcon={expandIcon}