@multiplatform.one/forms 6.7.0 → 7.0.0

package/src/fields/Geolocation/index.tsx

@@ -1,6 +1,6 @@
-import { useResolvedKnobs, type KnobProps } from "@multiplatform.one/theme";
+import { ensureFocusVisibleRing, useResolvedKnobs, type KnobProps } from "@multiplatform.one/theme";
 import { NavigationArrowIcon } from "@phosphor-icons/react";
-import type { MutableRefObject, ReactNode } from "react";
+import type { KeyboardEvent, 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";
@@ -18,7 +18,9 @@ import {
 import { formCommonColors, formInputColors } from "../../shared/colorRamps";
 import { t } from "../../shared/t";
 import {
+  clampRadiusForLargeComponent,
   getFieldError,
+  getFieldHeight,
   mergeFieldHandler,
   useFormField,
   useResolvedValidators,
@@ -77,15 +79,15 @@ function mapGeolocationError(
   return err.message || t("Failed to get location");
 }
 
-function parseGeoValue(value: string): GeoValue {
+function parseGeoValue(value: string | undefined): GeoValue | null {
+  if (!value || !value.trim()) return null;
   try {
     const parsed = JSON.parse(value) as Record<string, unknown>;
-    return {
-      lat: typeof parsed.lat === "number" ? parsed.lat : 0,
-      lng: typeof parsed.lng === "number" ? parsed.lng : 0,
-    };
+    if (typeof parsed.lat !== "number" || typeof parsed.lng !== "number") return null;
+    if (!Number.isFinite(parsed.lat) || !Number.isFinite(parsed.lng)) return null;
+    return { lat: parsed.lat, lng: parsed.lng };
   } catch {
-    return { lat: 0, lng: 0 };
+    return null;
   }
 }
 
@@ -242,12 +244,14 @@ function ExpandedMapView({
   onChange,
   disabled,
   readOnly,
+  hasValue,
 }: {
   lat: number;
   lng: number;
   onChange: (lat: number, lng: number) => void;
   disabled: boolean;
   readOnly?: boolean;
+  hasValue: boolean;
 }) {
   const { knobProps } = useResolvedKnobs();
 
@@ -261,12 +265,13 @@ function ExpandedMapView({
       <GeolocationMap
         lat={lat}
         lng={lng}
-        delta={0.05}
+        delta={hasValue ? 0.05 : 40}
         minHeight={400}
         title={t("Location selection")}
         onChange={onChange}
         disabled={disabled}
         readOnly={readOnly}
+        hasValue={hasValue}
       />
     </YStack>
   );
@@ -280,7 +285,11 @@ export interface GeolocationMapProps {
   knobProps: KnobProps;
 }
 
+/** Overlay buttons sit inside the map's overflow:hidden — inset ring (LC-71). */
+const overlayFocusRing = ensureFocusVisibleRing({ outlineOffset: -2 });
+
 function GeoMapSurface({
+  id,
   coordinates,
   onCommitCoordinates,
   onUseMyLocation,
@@ -297,8 +306,10 @@ function GeoMapSurface({
   renderMap,
   required,
   hasError,
+  mapHeight,
 }: {
-  coordinates: GeoValue;
+  id?: string;
+  coordinates: GeoValue | null;
   onCommitCoordinates: (lat: number, lng: number) => void;
   onUseMyLocation: () => void;
   onRetryLocate: () => void;
@@ -314,14 +325,23 @@ function GeoMapSurface({
   renderMap?: (props: GeolocationMapProps) => ReactNode;
   required?: boolean;
   hasError?: boolean;
+  mapHeight: number;
 }) {
   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 locateErrorOpen = locatePhase === "error";
+  const hasValue = coordinates != null;
+  const mapLat = coordinates?.lat ?? 0;
+  const mapLng = coordinates?.lng ?? 0;
+  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.
@@ -332,10 +352,30 @@ function GeoMapSurface({
     setCoordsOpen(open);
   };
 
+  const handleMapKeyDown = (event: KeyboardEvent) => {
+    if (!interactive) return;
+    if (event.key === "Enter") {
+      event.preventDefault();
+      setCoordsOpen(true);
+      return;
+    }
+    if (!coordinates) return;
+    const step = event.shiftKey ? 0.01 : 0.001;
+    let nextLat = coordinates.lat;
+    let nextLng = coordinates.lng;
+    if (event.key === "ArrowUp") nextLat = clampLat(nextLat + step);
+    else if (event.key === "ArrowDown") nextLat = clampLat(nextLat - step);
+    else if (event.key === "ArrowLeft") nextLng = clampLng(nextLng - step);
+    else if (event.key === "ArrowRight") nextLng = clampLng(nextLng + step);
+    else return;
+    event.preventDefault();
+    onMapChange(nextLat, nextLng);
+  };
+
   const customMap = renderMap
     ? renderMap({
-        lat: coordinates.lat,
-        lng: coordinates.lng,
+        lat: mapLat,
+        lng: mapLng,
         onChange: onMapChange,
         disabled,
         knobProps,
@@ -346,65 +386,63 @@ function GeoMapSurface({
     <>
       <YStack
         testID="geolocation-map"
+        id={id}
         {...knobProps.borderRadius}
         {...knobProps.inputSurface}
-        borderColor={formInputColors.border.base}
+        borderRadius={cappedRadius}
+        borderColor={hasError ? formCommonColors.error : formInputColors.border.base}
         overflow="hidden"
-        height={200}
+        height={mapHeight}
         position="relative"
+        outlineWidth={0}
+        focusStyle={{ outlineWidth: 0 }}
+        focusVisibleStyle={interactive ? overlayFocusRing : { outlineWidth: 0 }}
+        {...(interactive && isWeb
+          ? {
+              tabIndex: 0,
+              role: "application",
+              "aria-label": t("Location map"),
+              "aria-valuetext": hasValue ? formatCoordChip(mapLat, mapLng) : t("No location set"),
+              onKeyDown: handleMapKeyDown,
+            }
+          : {})}
       >
-        {/* Platform-split surface: OSM embed on web, expo-maps on native */}
         {customMap ?? (
           <GeolocationMap
-            lat={coordinates.lat}
-            lng={coordinates.lng}
+            lat={mapLat}
+            lng={mapLng}
+            delta={hasValue ? 0.02 : 40}
             onChange={onMapChange}
             disabled={disabled}
             readOnly={readOnly}
+            hasValue={hasValue}
           />
         )}
 
-        {/* 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}
+        {/* Chip is the coordinates editor trigger (Apple/Google compact pattern). */}
+        {readOnly ? (
+          <View
+            position="absolute"
+            top="$2"
+            insetInlineStart="$2"
+            zIndex={2}
+            backgroundColor="$background"
+            opacity={0.92}
+            paddingHorizontal="$2"
+            paddingVertical="$1"
+            {...knobProps.borderRadius}
           >
-            {formatCoordChip(coordinates.lat, coordinates.lng)}
-          </Text>
-        </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")}
+            <Text
+              testID="geolocation-coords-chip"
+              fontSize="$1"
+              {...knobProps.body}
+              color={formCommonColors.muted}
             >
-              {expandIcon}
-            </Button>
+              {hasValue ? formatCoordChip(mapLat, mapLng) : t("No location set")}
+            </Text>
           </View>
-        )}
-
-        {/* Coordinates editor trigger (bottom-start) — FloatingPanel / LC-06 */}
-        {!readOnly && (
-          <View position="absolute" bottom="$2" insetInlineStart="$2" zIndex={1}>
+        ) : (
+          <View position="absolute" top="$2" insetInlineStart="$2" zIndex={2}>
             <FloatingPanel
               open={coordsOpen}
               onOpenChange={handleCoordsOpenChange}
@@ -417,19 +455,21 @@ function GeoMapSurface({
                   size="$2"
                   disabled={disabled}
                   backgroundColor="$background"
-                  opacity={0.9}
+                  opacity={0.92}
+                  testID="geolocation-coords-chip"
                   aria-label={t("Edit coordinates")}
-                  // Web: trigger owns open (ColorPicker pattern). Native: FloatingPanel
-                  // owns the open gesture — a second onPress would double-toggle.
+                  focusVisibleStyle={overlayFocusRing}
                   onPress={isWeb && !disabled ? () => setCoordsOpen(true) : undefined}
                 >
-                  <Button.Text>{t("Coordinates")}</Button.Text>
+                  <Button.Text>
+                    {hasValue ? formatCoordChip(mapLat, mapLng) : t("Set location")}
+                  </Button.Text>
                 </Button>
               }
             >
               <CoordinatesPanel
-                lat={coordinates.lat}
-                lng={coordinates.lng}
+                lat={mapLat}
+                lng={mapLng}
                 knobProps={knobProps}
                 required={required}
                 hasError={hasError}
@@ -440,70 +480,74 @@ function GeoMapSurface({
           </View>
         )}
 
+        {handleExpand && expandIcon && (
+          <View position="absolute" top="$2" insetInlineEnd="$2" zIndex={2}>
+            <Button
+              size="$2"
+              circular
+              disabled={disabled}
+              onPress={handleExpand}
+              backgroundColor="$background"
+              opacity={0.92}
+              aria-label={t("Expand map")}
+              focusVisibleStyle={overlayFocusRing}
+            >
+              {expandIcon}
+            </Button>
+          </View>
+        )}
+
         {/* Locate overlay (bottom-end) — LC-19 preflight runs on press */}
-        {!readOnly && (
-          <View position="absolute" bottom="$2" insetInlineEnd="$2" zIndex={1}>
+        {!readOnly && !locateErrorOpen && (
+          <View position="absolute" bottom="$2" insetInlineEnd="$2" zIndex={2}>
             <Button
               size="$2"
+              circular
               disabled={disabled || locating}
               onPress={onUseMyLocation}
               backgroundColor="$background"
-              opacity={0.9}
+              opacity={0.92}
               icon={locating ? <Spinner size="small" /> : locationIcon}
               aria-label={locating ? t("Locating") : t("Locate")}
-            >
-              <Button.Text>{locating ? t("Locating...") : t("Locate")}</Button.Text>
-            </Button>
+              focusVisibleStyle={overlayFocusRing}
+            />
           </View>
         )}
-      </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…")}
+        {/*
+          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"
+            position="absolute"
+            bottom="$2"
+            left="$2"
+            right="$2"
+            zIndex={3}
+            {...knobProps.borderRadius}
+            {...knobProps.inputSurface}
+            borderColor={formInputColors.border.base}
+            padding="$3"
+            gap="$2"
+            alignItems="center"
+          >
+            <Text {...knobProps.body} color={formCommonColors.error} textAlign="center">
+              {locateError}
             </Text>
-          )}
-        </YStack>
-      )}
+            <XStack gap="$2">
+              <Button size="$2" onPress={onRetryLocate} aria-label={t("Retry location")}>
+                {t("Retry")}
+              </Button>
+              <Button size="$2" onPress={onCloseLocate} aria-label={t("Close location")}>
+                {t("Close")}
+              </Button>
+            </XStack>
+          </YStack>
+        )}
+      </YStack>
 
-      {/* Expand uses AdaptivePopup — large map exceeds FloatingPanel fitContent */}
       {expandIcon && (
         <AdaptivePopup
           open={expanded}
@@ -512,11 +556,12 @@ function GeoMapSurface({
           size="lg"
         >
           <ExpandedMapView
-            lat={coordinates.lat}
-            lng={coordinates.lng}
+            lat={mapLat}
+            lng={mapLng}
             onChange={onMapChange}
             disabled={disabled}
             readOnly={readOnly}
+            hasValue={hasValue}
           />
         </AdaptivePopup>
       )}
@@ -554,7 +599,7 @@ export interface GeolocationProps {
   renderMap?: (props: GeolocationMapProps) => ReactNode;
   /** When true, renders a skeleton placeholder instead of the geolocation field */
   skeleton?: boolean;
-  /** When true, uses compact sizing */
+  /** When true, applies compact density (tighter layout gaps; control size unchanged) */
   compact?: boolean;
 }
 
@@ -646,7 +691,7 @@ export function Geolocation({
   const makeHandlers = useCallback(
     (currentValue: string, onValueChange: (value: string) => void) => {
       onValueChangeRef.current = onValueChange;
-      const coordinates = currentValue ? parseGeoValue(currentValue) : { lat: 0, lng: 0 };
+      const coordinates = parseGeoValue(currentValue);
       return {
         coordinates,
         onCommitCoordinates: (lat: number, lng: number) => {
@@ -670,11 +715,13 @@ export function Geolocation({
     [startLocate, requestPosition],
   );
 
+  const mapHeight = getFieldHeight((size ?? knobProps.sizeToken) as SizeTokens, compact ? 4 : 5);
+
   // 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} />
+        <Skeleton variant="rounded" width="100%" height={mapHeight} />
       </FieldLayout>
     );
   }
@@ -701,6 +748,7 @@ export function Geolocation({
         disabled={disabled}
       >
         <GeoMapSurface
+          id={id}
           coordinates={handlers.coordinates}
           onCommitCoordinates={handlers.onCommitCoordinates}
           onUseMyLocation={handlers.onUseMyLocation}
@@ -717,6 +765,7 @@ export function Geolocation({
           renderMap={renderMap}
           required={required}
           hasError={!!displayError}
+          mapHeight={mapHeight}
         />
       </FieldLayout>
     );
@@ -750,6 +799,7 @@ export function Geolocation({
             disabled={disabled}
           >
             <GeoMapSurface
+              id={id}
               coordinates={handlers.coordinates}
               onCommitCoordinates={handlers.onCommitCoordinates}
               onUseMyLocation={handlers.onUseMyLocation}
@@ -766,6 +816,7 @@ export function Geolocation({
               renderMap={renderMap}
               required={required}
               hasError={!!resolvedError}
+              mapHeight={mapHeight}
             />
           </FieldLayout>
         );

package/src/fields/Geolocation/mapMath.spec.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from "vitest";
+import {
+  latLngFromMapClick,
+  latToTile,
+  lngToTile,
+  tileToLat,
+  tileToLng,
+  tilesForView,
+  zoomFromDelta,
+} from "./mapMath";
+
+describe("mapMath", () => {
+  it("zoomFromDelta(0.02) matches the native camera zoom (13)", () => {
+    expect(zoomFromDelta(0.02)).toBe(13);
+  });
+
+  it("tile projection round-trips the equator", () => {
+    const zoom = 8;
+    const x = lngToTile(0, zoom);
+    const y = latToTile(0, zoom);
+    expect(tileToLng(x, zoom)).toBeCloseTo(0, 8);
+    expect(tileToLat(y, zoom)).toBeCloseTo(0, 8);
+  });
+
+  it("a center click returns the view center", () => {
+    const next = latLngFromMapClick({
+      offsetX: 100,
+      offsetY: 80,
+      width: 200,
+      height: 160,
+      lat: 37.7749,
+      lng: -122.4194,
+      zoom: 13,
+    });
+    expect(next.lat).toBeCloseTo(37.7749, 5);
+    expect(next.lng).toBeCloseTo(-122.4194, 5);
+  });
+
+  it("a click east of center increases longitude", () => {
+    const next = latLngFromMapClick({
+      offsetX: 180,
+      offsetY: 100,
+      width: 200,
+      height: 200,
+      lat: 0,
+      lng: 0,
+      zoom: 8,
+    });
+    expect(next.lng).toBeGreaterThan(0);
+    expect(next.lat).toBeCloseTo(0, 5);
+  });
+
+  it("tilesForView covers the box and skips empty layout", () => {
+    expect(tilesForView({ lat: 0, lng: 0, zoom: 2, width: 0, height: 200 })).toEqual([]);
+    const tiles = tilesForView({ lat: 0, lng: 0, zoom: 2, width: 256, height: 256 });
+    expect(tiles.length).toBeGreaterThan(0);
+    expect(tiles.every((tile) => tile.tx >= 0 && tile.ty >= 0)).toBe(true);
+  });
+});

package/src/fields/Geolocation/mapMath.ts

@@ -0,0 +1,91 @@
+/** OSM slippy-map tile size in CSS pixels. */
+export const OSM_TILE_SIZE = 256;
+
+/**
+ * Viewport half-size in degrees → tile zoom. Shared by the web tile surface
+ * and the native expo-maps camera (360° spans zoom 0, halving per level).
+ */
+export function zoomFromDelta(delta: number): number {
+  const clamped = Math.min(Math.max(delta, 0.0005), 45);
+  return Math.max(1, Math.min(19, Math.round(Math.log2(360 / (clamped * 2)))));
+}
+
+export function lngToTile(lng: number, zoom: number): number {
+  return ((lng + 180) / 360) * 2 ** zoom;
+}
+
+export function latToTile(lat: number, zoom: number): number {
+  const clamped = Math.max(-85.05112878, Math.min(85.05112878, lat));
+  const rad = (clamped * Math.PI) / 180;
+  return ((1 - Math.log(Math.tan(rad) + 1 / Math.cos(rad)) / Math.PI) / 2) * 2 ** zoom;
+}
+
+export function tileToLng(x: number, zoom: number): number {
+  return (x / 2 ** zoom) * 360 - 180;
+}
+
+export function tileToLat(y: number, zoom: number): number {
+  const rad = Math.atan(Math.sinh(Math.PI * (1 - (2 * y) / 2 ** zoom)));
+  return (rad * 180) / Math.PI;
+}
+
+export function wrapTileX(x: number, zoom: number): number {
+  const n = 2 ** zoom;
+  return ((x % n) + n) % n;
+}
+
+export interface MapClickArgs {
+  offsetX: number;
+  offsetY: number;
+  width: number;
+  height: number;
+  lat: number;
+  lng: number;
+  zoom: number;
+}
+
+/** Convert a click in the map box to WGS84, matching the centered-tile view. */
+export function latLngFromMapClick(args: MapClickArgs): { lat: number; lng: number } {
+  const { offsetX, offsetY, width, height, lat, lng, zoom } = args;
+  const worldX = lngToTile(lng, zoom) + (offsetX - width / 2) / OSM_TILE_SIZE;
+  const worldY = latToTile(lat, zoom) + (offsetY - height / 2) / OSM_TILE_SIZE;
+  return { lat: tileToLat(worldY, zoom), lng: tileToLng(worldX, zoom) };
+}
+
+export interface MapTile {
+  tx: number;
+  ty: number;
+  left: number;
+  top: number;
+}
+
+/** Tiles covering a pixel box centered on `lat`/`lng` at `zoom`. */
+export function tilesForView(args: {
+  lat: number;
+  lng: number;
+  zoom: number;
+  width: number;
+  height: number;
+}): MapTile[] {
+  const { lat, lng, zoom, width, height } = args;
+  if (width < 1 || height < 1) return [];
+  const n = 2 ** zoom;
+  const cx = lngToTile(lng, zoom);
+  const cy = latToTile(lat, zoom);
+  const minTx = Math.floor(cx - width / 2 / OSM_TILE_SIZE);
+  const maxTx = Math.ceil(cx + width / 2 / OSM_TILE_SIZE);
+  const minTy = Math.max(0, Math.floor(cy - height / 2 / OSM_TILE_SIZE));
+  const maxTy = Math.min(n - 1, Math.ceil(cy + height / 2 / OSM_TILE_SIZE));
+  const tiles: MapTile[] = [];
+  for (let ty = minTy; ty <= maxTy; ty++) {
+    for (let tx = minTx; tx <= maxTx; tx++) {
+      tiles.push({
+        tx: wrapTileX(tx, zoom),
+        ty,
+        left: (tx - cx) * OSM_TILE_SIZE + width / 2,
+        top: (ty - cy) * OSM_TILE_SIZE + height / 2,
+      });
+    }
+  }
+  return tiles;
+}

package/src/fields/Geolocation/mapTypes.ts

@@ -7,8 +7,8 @@ export interface GeolocationMapSurfaceProps {
   lat: number;
   lng: number;
   /**
-   * Half-size of the visible bbox in degrees. Web uses it for the OSM embed
-   * bbox; native derives an equivalent zoom level from it.
+   * Half-size of the visible viewport in degrees. Both platform surfaces
+   * derive an equivalent tile zoom from it.
    */
   delta?: number;
   /** Minimum pixel height of the map surface (expanded view). */
@@ -22,4 +22,9 @@ export interface GeolocationMapSurfaceProps {
   onChange?: (lat: number, lng: number) => void;
   disabled?: boolean;
   readOnly?: boolean;
+  /**
+   * When false the surface has no value marker (empty field). Omitted /
+   * true keeps the marker so platform twins and existing callers match.
+   */
+  hasValue?: boolean;
 }