@multiplatform.one/forms 7.11.0 → 7.15.0

package/src/fields/DatePicker/MultiDatePicker.tsx

@@ -1,3 +1,4 @@
+import { useTouchSurface } from "@multiplatform.one/theme";
 import type { DeepKeys, DeepValue } from "@tanstack/form-core";
 import { formatAbsoluteDate, useResolvedKnobs } from "@multiplatform.one/theme";
 import { type ComponentProps, useCallback, useEffect, useMemo, useRef, useState } from "react";
@@ -306,6 +307,7 @@ export function MultiDatePicker<
   TFormValidator extends Validator<TParentData, unknown> | undefined = undefined,
   TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,
 >(props: MultiDatePickerProps<TParentData, TName, TFieldValidator, TFormValidator, TData>) {
+  const hydrationTouch = useTouchSurface();
   const {
     defaultValue,
     value: valueProp,
@@ -338,7 +340,7 @@ export function MultiDatePicker<
   const { resolvedForm, knobProps, id } = useFormField({ form, id: idProp, compact });
   const resolvedValidators = useResolvedValidators(required, validators, label, name, isEmptyDates);
   const resolvedSize = (size ?? knobProps.sizeToken) as SizeTokens;
-  const visualHeight = getFieldHeight(resolvedSize);
+  const visualHeight = getFieldHeight(resolvedSize, 1, hydrationTouch);
 
   const initialDates = (
     Array.isArray(valueProp) ? valueProp : Array.isArray(defaultValue) ? defaultValue : []

package/src/fields/Duration/index.tsx

@@ -1,3 +1,4 @@
+import { useTouchSurface } from "@multiplatform.one/theme";
 import { sizeRecipeForToken, type KnobProps } from "@multiplatform.one/theme";
 import { ClockIcon } from "@phosphor-icons/react";
 import type { ReactNode } from "react";
@@ -434,6 +435,7 @@ export function Duration({
   skeleton,
   compact,
 }: DurationProps) {
+  const hydrationTouch = useTouchSurface();
   const { resolvedForm, knobProps, id } = useFormField({
     form: formProp,
     id: idProp,
@@ -445,7 +447,7 @@ export function Duration({
   const seconds = normalizeSeconds(isControlled ? value : internal);
   const inTableCell = useIsInTableCell();
   const resolvedSize = (size ?? knobProps.sizeToken) as SizeTokens;
-  const visualHeight = getFieldHeight(resolvedSize);
+  const visualHeight = getFieldHeight(resolvedSize, 1, hydrationTouch);
 
   const handleChange = useCallback(
     (next: number, fieldChange?: (v: any) => void) => {

package/src/fields/FileUpload/index.tsx

@@ -1,3 +1,4 @@
+import { useTouchSurface } from "@multiplatform.one/theme";
 import { FileIcon, UploadIcon, XIcon } from "@phosphor-icons/react";
 import type { DeepKeys, DeepValue } from "@tanstack/form-core";
 import { type DragEvent, type ReactNode, useCallback, useEffect, useRef, useState } from "react";
@@ -195,6 +196,7 @@ export function FileUpload<
   TFormValidator extends Validator<TParentData, unknown> | undefined = undefined,
   TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,
 >(props: FileUploadProps<TParentData, TName, TFieldValidator, TFormValidator, TData>) {
+  const hydrationTouch = useTouchSurface();
   const {
     defaultValue,
     form,
@@ -263,7 +265,7 @@ export function FileUpload<
   // frame move together per size. The corner remove disc hangs a quarter of
   // its own nestedControl step (8 at medium) outside the tile's top-right,
   // which is the Bento Image Picker overlap read under the house tokens.
-  const tilePx = getFieldHeight(knobProps.sizeToken as SizeTokens, 2);
+  const tilePx = getFieldHeight(knobProps.sizeToken as SizeTokens, 2, hydrationTouch);
   const tileRemoveInset = -Math.round(knobProps.nestedControl.px / 4);
 
   const [selectedFiles, setSelectedFiles] = useState<File[]>([]);
@@ -688,7 +690,11 @@ export function FileUpload<
 
   // Render skeleton placeholder
   if (skeleton) {
-    const minHeightPx = getFieldHeight((fieldProps.size || knobProps.sizeToken) as SizeTokens, 5);
+    const minHeightPx = getFieldHeight(
+      (fieldProps.size || knobProps.sizeToken) as SizeTokens,
+      5,
+      hydrationTouch,
+    );
     return (
       <FieldLayout id={id} label={fieldProps.label} size={fieldProps.size} knobProps={knobProps}>
         <Skeleton variant="rounded" width="100%" height={minHeightPx} />
@@ -876,7 +882,11 @@ export function FileUpload<
         // CONTRACT (boards media-01..03): the getFieldHeight floor sits on
         // the FRAME, so the frame border-box measures 220 — hanging it on
         // the inner stack painted 222, a number no token expresses.
-        minHeight={getFieldHeight((fieldProps.size || knobProps.sizeToken) as SizeTokens, 5)}
+        minHeight={getFieldHeight(
+          (fieldProps.size || knobProps.sizeToken) as SizeTokens,
+          5,
+          hydrationTouch,
+        )}
         aria-required={fieldProps.required || undefined}
         aria-invalid={!!errorProp || undefined}
         aria-readonly={readOnly || undefined}

package/src/fields/FileUpload/nativePickerLoader.spec.ts

@@ -0,0 +1,34 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { pickerNativeModules } from "./nativePickerLoader";
+
+const nodeRequire = createRequire(import.meta.url);
+
+/** Every native module name a package's build asks expo-modules-core for. */
+function registeredNativeModules(pkg: string): string[] {
+  const build = join(dirname(nodeRequire.resolve(`${pkg}/package.json`)), "build");
+  const names = new Set<string>();
+  for (const file of readdirSync(build)) {
+    if (!file.endsWith(".js")) continue;
+    const source = readFileSync(join(build, file), "utf8");
+    for (const match of source.matchAll(/require(?:Optional)?NativeModule\(\s*['"]([^'"]+)['"]/g)) {
+      names.add(match[1]!);
+    }
+  }
+  return [...names];
+}
+
+// MPO-73: the probe runs before the require, so a name the package never
+// registers makes the picker look absent and an image-only field opens the
+// Files browser instead of the photo library.
+describe("native picker probes", () => {
+  it("probe the name expo-image-picker registers", () => {
+    expect(registeredNativeModules("expo-image-picker")).toContain(pickerNativeModules.image);
+  });
+
+  it("probe the name expo-document-picker registers", () => {
+    expect(registeredNativeModules("expo-document-picker")).toContain(pickerNativeModules.document);
+  });
+});

package/src/fields/FileUpload/nativePickerLoader.ts

@@ -1,6 +1,15 @@
 export type DocumentPickerModule = typeof import("expo-document-picker");
 export type ImagePickerModule = typeof import("expo-image-picker");
 
+/**
+ * The names each picker registers with expo-modules-core. expo-image-picker
+ * keeps its Exponent-era name (MPO-73).
+ */
+export const pickerNativeModules = {
+  document: "ExpoDocumentPicker",
+  image: "ExponentImagePicker",
+} as const;
+
 let cachedDocumentPicker: DocumentPickerModule | null | undefined;
 let cachedImagePicker: ImagePickerModule | null | undefined;
 
@@ -36,7 +45,7 @@ function hasNativeModule(name: string): boolean {
 export function loadDocumentPicker(): DocumentPickerModule | null {
   if (cachedDocumentPicker !== undefined) return cachedDocumentPicker;
   try {
-    cachedDocumentPicker = hasNativeModule("ExpoDocumentPicker")
+    cachedDocumentPicker = hasNativeModule(pickerNativeModules.document)
       ? (require("expo-document-picker") as DocumentPickerModule)
       : null;
   } catch {
@@ -49,7 +58,7 @@ export function loadDocumentPicker(): DocumentPickerModule | null {
 export function loadImagePicker(): ImagePickerModule | null {
   if (cachedImagePicker !== undefined) return cachedImagePicker;
   try {
-    cachedImagePicker = hasNativeModule("ExpoImagePicker")
+    cachedImagePicker = hasNativeModule(pickerNativeModules.image)
       ? (require("expo-image-picker") as ImagePickerModule)
       : null;
   } catch {

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

@@ -4,7 +4,8 @@ import { renderWithProviders } from "@multiplatform.one/test-utils";
 import { Form } from "../../Form";
 import { TableCellContext } from "../../shared/tableCellContext";
 import { Geolocation, preflightGeolocation } from "./index";
-import type { GeocodeResult } from "./geocoder";
+import type { GeocodeResult, Geocoder } from "./geocoder";
+import { GeocoderProvider } from "./geocoderContext";
 import { Theme } from "tamagui";
 import { NavigationArrowIcon } from "@phosphor-icons/react";
 
@@ -31,6 +32,15 @@ function searchInput(container: HTMLElement | Document = document) {
     container.querySelector("[aria-label='Search for a location']")) as HTMLInputElement | null;
 }
 
+const mapControlSelector =
+  "button, input, textarea, select, [role='button'], [role='combobox'], [role='option'], [tabindex]";
+
+function mapControls(container: HTMLElement): Element[] {
+  const map = container.querySelector("[data-testid='geolocation-map']");
+  expect(map).not.toBeNull();
+  return [...(map as HTMLElement).querySelectorAll(mapControlSelector)];
+}
+
 function typeSearch(container: HTMLElement, text: string) {
   const input = searchInput(container);
   expect(input).not.toBeNull();
@@ -161,6 +171,35 @@ describe("Geolocation", () => {
       expect(result.container.querySelector("[data-testid='geolocation-coords-chip']")).toBeNull();
     });
 
+    it.each([
+      ["a set value", HELSINKI],
+      ["the empty state", ""],
+    ])("with %s, nothing interactive sits on the map; the controls live below it", (_, value) => {
+      const result = renderWithProviders(
+        <Geolocation
+          label="Location"
+          value={value}
+          geocode={mockGeocode()}
+          locationIcon={locationIcon}
+          expandIcon={<span data-testid="expand-icon" />}
+        />,
+      );
+      expect(mapControls(result.container)).toEqual([]);
+      const map = result.container.querySelector("[data-testid='geolocation-map']") as HTMLElement;
+      const footer = result.container.querySelector(
+        "[data-testid='geolocation-map-footer']",
+      ) as HTMLElement;
+      expect(footer).not.toBeNull();
+      expect(map.compareDocumentPosition(footer) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy();
+      const locate = footer.querySelector(
+        value ? "[aria-label='Locate']" : "[aria-label='Use my current location']",
+      );
+      expect(locate).not.toBeNull();
+      expect(locate?.textContent).toContain(value ? "Locate" : "Use my current location");
+      expect(footer.querySelector("[aria-label='Expand map']")).not.toBeNull();
+      expect(footer.querySelector("[data-testid='geolocation-coordline']")).not.toBeNull();
+    });
+
     it("without an injected geocoder, search is disabled and map/manual paths stay", () => {
       const result = renderWithProviders(
         <Geolocation label="Location" value={HELSINKI} locationIcon={locationIcon} />,
@@ -280,6 +319,37 @@ describe("Geolocation", () => {
       expect(onChange).toHaveBeenCalled();
     });
 
+    it("after a geocoder failure the coordinate editor still commits", async () => {
+      const geocode = vi.fn().mockRejectedValue(new Error("down"));
+      const onChange = vi.fn();
+      const result = renderWithProviders(
+        <Geolocation
+          label="Location"
+          geocode={geocode}
+          onChange={onChange}
+          locationIcon={locationIcon}
+        />,
+      );
+      typeSearch(result.container, "manner");
+      await waitFor(() => {
+        expect(document.body.textContent).toContain(
+          "Search is unavailable — check your connection",
+        );
+      });
+      fireEvent.keyDown(document, { key: "Escape" });
+      fireEvent.click(result.container.querySelector("[aria-label='Edit coordinates']") as Element);
+      const lat = await waitFor(() => {
+        const input = document.querySelector("input[aria-label='Latitude']");
+        expect(input).not.toBeNull();
+        return input as HTMLInputElement;
+      });
+      fireEvent.change(lat, { target: { value: "12.5" } });
+      await waitFor(() => {
+        expect(onChange).toHaveBeenCalledWith(JSON.stringify({ lat: 12.5, lng: 0 }));
+      });
+      expect(result.container.querySelector("[data-testid='geolocation-map']")).not.toBeNull();
+    });
+
     it("a typed lat, lng pair offers the exact point", async () => {
       const geocode = mockGeocode();
       const onChange = vi.fn();
@@ -573,6 +643,55 @@ describe("Geolocation", () => {
     });
   });
 
+  describe("GeocoderProvider", () => {
+    const provided: Geocoder = {
+      geocode: mockGeocode(),
+      reverseGeocode: mockReverse(),
+    };
+
+    it("hands its geocoder to a field that was given none", async () => {
+      const result = renderWithProviders(
+        <GeocoderProvider geocoder={provided}>
+          <Geolocation label="Location" value={HELSINKI} locationIcon={locationIcon} />
+        </GeocoderProvider>,
+      );
+      await waitFor(() => {
+        expect(searchInput(result.container)?.value).toBe(
+          "Mannerheimintie 3, Kamppi, Helsinki, Finland",
+        );
+      });
+      expect(searchInput(result.container)?.disabled).toBe(false);
+      typeSearch(result.container, "manner");
+      await waitFor(() => {
+        expect(provided.geocode).toHaveBeenCalledWith({ query: "manner" });
+      });
+    });
+
+    it("loses to the field's own props, and geocoder={null} opts out", async () => {
+      const own = mockReverse({ ...mannerheim, label: "Own provider", description: undefined });
+      const result = renderWithProviders(
+        <GeocoderProvider geocoder={provided}>
+          <Geolocation
+            label="Own"
+            value={HELSINKI}
+            reverseGeocode={own}
+            locationIcon={locationIcon}
+          />
+          <Geolocation label="None" value={HELSINKI} geocoder={null} locationIcon={locationIcon} />
+        </GeocoderProvider>,
+      );
+      const inputs = () =>
+        [
+          ...result.container.querySelectorAll("[data-testid='geolocation-search']"),
+        ] as HTMLInputElement[];
+      await waitFor(() => {
+        expect(inputs()[0].value).toBe("Own provider");
+      });
+      expect(inputs()[1].value).toBe("");
+      expect(inputs()[1].disabled).toBe(true);
+    });
+  });
+
   describe("geolocation pre-flight (LC-19 CAPABILITY-PREFLIGHT)", () => {
     afterEach(() => {
       vi.unstubAllGlobals();
@@ -628,7 +747,7 @@ describe("Geolocation", () => {
       const result = renderWithProviders(
         <Geolocation label="Location" name="loc" locationIcon={locationIcon} />,
       );
-      const button = result.container.querySelector("[aria-label='Locate']");
+      const button = result.container.querySelector("[aria-label='Use my current location']");
       expect(button).not.toBeNull();
       fireEvent.click(button as Element);
       await waitFor(() => {
@@ -650,7 +769,9 @@ describe("Geolocation", () => {
       const result = renderWithProviders(
         <Geolocation label="Location" name="loc" locationIcon={locationIcon} />,
       );
-      fireEvent.click(result.container.querySelector("[aria-label='Locate']") as Element);
+      fireEvent.click(
+        result.container.querySelector("[aria-label='Use my current location']") as Element,
+      );
       await waitFor(() => {
         expect(result.container.textContent).toContain("permission denied");
       });
@@ -681,7 +802,9 @@ describe("Geolocation", () => {
       const result = renderWithProviders(
         <Geolocation label="Location" name="loc" locationIcon={locationIcon} />,
       );
-      fireEvent.click(result.container.querySelector("[aria-label='Locate']") as Element);
+      fireEvent.click(
+        result.container.querySelector("[aria-label='Use my current location']") as Element,
+      );
 
       await waitFor(() => {
         expect(
@@ -689,6 +812,7 @@ describe("Geolocation", () => {
         ).not.toBeNull();
         expect(result.container.textContent).toContain("timed out");
       });
+      expect(mapControls(result.container)).toEqual([]);
       const retry = result.container.querySelector("[aria-label='Retry location']");
       expect(retry).not.toBeNull();
       expect(getCurrentPosition).toHaveBeenCalledTimes(1);
@@ -797,3 +921,40 @@ describe("Geolocation", () => {
     });
   });
 });
+
+describe("Geolocation search opens on intent, not on focus (MPO-360)", () => {
+  const resultsPanel = () => document.querySelector("[data-testid='geolocation-results']");
+
+  it("a focus alone, as a cell editor's focus-into-panel gives, leaves the results closed", async () => {
+    const result = renderWithProviders(
+      <Geolocation label="Location" geocode={mockGeocode()} locationIcon={locationIcon} />,
+    );
+    const input = searchInput(result.container) as HTMLInputElement;
+    input.focus();
+    fireEvent.focus(input);
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    expect(resultsPanel()).toBeNull();
+    expect(input.getAttribute("aria-expanded")).toBe("false");
+  });
+
+  it("a press on the search still opens the results with Use my current location first", async () => {
+    const result = renderWithProviders(
+      <Geolocation label="Location" geocode={mockGeocode()} locationIcon={locationIcon} />,
+    );
+    fireEvent.click(searchInput(result.container) as HTMLInputElement);
+    await waitFor(() => expect(resultsPanel()).not.toBeNull());
+    expect((resultsPanel() as HTMLElement).firstElementChild?.getAttribute("data-testid")).toBe(
+      "geolocation-use-location",
+    );
+  });
+
+  it("ArrowDown on a focused search opens the results", async () => {
+    const result = renderWithProviders(
+      <Geolocation label="Location" geocode={mockGeocode()} locationIcon={locationIcon} />,
+    );
+    const input = searchInput(result.container) as HTMLInputElement;
+    input.focus();
+    fireEvent.keyDown(input, { key: "ArrowDown" });
+    await waitFor(() => expect(resultsPanel()).not.toBeNull());
+  });
+});

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

@@ -10,7 +10,9 @@ import { Form } from "../../Form";
 import { TableCellContext } from "../../shared/tableCellContext";
 import { Geolocation, type GeolocationProps } from "./index";
 import type { GeocodeResult, Geocoder } from "./geocoder";
+import { GeocoderProvider } from "./geocoderContext";
 import { parseGeoValue } from "./geoValue";
+import { createPhotonGeocoder } from "./photonGeocoder";
 
 const meta: Meta<typeof Geolocation> = {
   title: "Forms/Geolocation",
@@ -19,7 +21,7 @@ const meta: Meta<typeof Geolocation> = {
     docs: {
       description: {
         component:
-          "Search-first geolocation field. Inject `geocode` / `reverseGeocode` (or a `geocoder` object); No default provider is supplied. The map is the output; coordinates live below it as a mono disclosure. Locate is a labeled action. LC-19 preflight gates Locate. LC-21: no Apply on the coordinate editor.",
+          "Search-first geolocation field. Inject `geocode` / `reverseGeocode` (or a `geocoder` object), or wrap an app in `GeocoderProvider`; the field supplies no provider of its own. `createPhotonGeocoder()` is a keyless opt-in adapter (the Live stories use it). The map is the output and carries no controls: coordinates, Locate and Expand sit in a row below it. LC-19 preflight gates Locate. LC-21: no Apply on the coordinate editor.",
       },
     },
   },
@@ -71,7 +73,7 @@ export const Main: Story = {
 export const Standalone: Story = {
   args: {
     label: "Location",
-    helperText: "Click the map to set a pin, or open the coordinate chip to type Lat/Lng",
+    helperText: "Click the map to set a pin, or edit the coordinates below it",
   },
   render: (args) => <Geolocation {...args} locationIcon={<NavigationArrowIcon size={16} />} />,
 };
@@ -92,7 +94,7 @@ export const Bare: Story = {
 export const Basic: Story = {
   args: {
     label: "Location",
-    helperText: "Click the map to set a pin, or open the coordinate chip to type Lat/Lng",
+    helperText: "Click the map to set a pin, or edit the coordinates below it",
     onChange: action("onChange"),
   },
   render: (args) => <Geolocation {...args} locationIcon={<NavigationArrowIcon size={16} />} />,
@@ -120,7 +122,7 @@ export const Disabled: Story = {
 export const WithError: Story = {
   args: {
     label: "Location",
-    helperText: "Click the map to set a pin, or open the coordinate chip to type Lat/Lng",
+    helperText: "Click the map to set a pin, or edit the coordinates below it",
     required: true,
     error: "Location is required",
     onChange: action("onChange"),
@@ -217,7 +219,7 @@ export const WithExpandButton: Story = {
         <YStack gap="$4" maxWidth={500}>
           <Geolocation
             label="Delivery Location"
-            helperText="Click the expand button on the map for a larger view"
+            helperText="Press Expand below the map for a larger view"
             value={value}
             onChange={(v) => {
               setValue(v);
@@ -274,29 +276,31 @@ export const SkeletonState: Story = {
 type InTableRow = { id: string; label: string; value: { lat: number; lng: number } | "" };
 
 /** LC-06: Geolocation stays hosted in DataTable; the cell opens a modal. */
+function InTableExample({ geocoder }: { geocoder?: Geocoder }) {
+  const [data, setData] = useState<InTableRow[]>([
+    { id: "1", label: "Alpha", value: { lat: 30.2672, lng: -97.7431 } },
+    { id: "2", label: "Beta", value: { lat: 48.8566, lng: 2.3522 } },
+    { id: "3", label: "Gamma", value: "" },
+  ]);
+  const columns: DataTableColumn<InTableRow>[] = [
+    { accessorKey: "label", header: "Row" },
+    {
+      accessorKey: "value",
+      header: "Location",
+      field: "geolocation",
+      fieldProps: { locationIcon: <NavigationArrowIcon size={16} />, geocoder },
+    },
+  ];
+  return (
+    <YStack width="100%" height={320}>
+      <DataTable data={data} columns={columns} enablePagination={false} onDataChange={setData} />
+    </YStack>
+  );
+}
+
 export const InTable: Story = {
   name: "In table",
-  render: () => {
-    const [data, setData] = useState<InTableRow[]>([
-      { id: "1", label: "Alpha", value: { lat: 30.2672, lng: -97.7431 } },
-      { id: "2", label: "Beta", value: { lat: 48.8566, lng: 2.3522 } },
-      { id: "3", label: "Gamma", value: "" },
-    ]);
-    const columns: DataTableColumn<InTableRow>[] = [
-      { accessorKey: "label", header: "Row" },
-      {
-        accessorKey: "value",
-        header: "Location",
-        field: "geolocation",
-        fieldProps: { locationIcon: <NavigationArrowIcon size={16} /> },
-      },
-    ];
-    return (
-      <YStack width="100%" height={320}>
-        <DataTable data={data} columns={columns} enablePagination={false} onDataChange={setData} />
-      </YStack>
-    );
-  },
+  render: () => <InTableExample />,
 };
 
 const places: GeocodeResult[] = [
@@ -347,6 +351,12 @@ export const FailedFakeProvider: Story = {
   render: (args) => <FakeProviderExample {...args} />,
 };
 
+/** The table's cell editor with a live search: opening it must not open the results (MPO-360). */
+export const InTableWithFakeProvider: Story = {
+  name: "In table with fake provider",
+  render: () => <InTableExample geocoder={fakeGeocoder} />,
+};
+
 /** Direct cell contract, independent of the table adapter's display formatter. */
 export const CellWithFakeProvider: Story = {
   args: {
@@ -429,3 +439,77 @@ function PendingReverseExample() {
 export const PendingControlledReverse: Story = {
   render: () => <PendingReverseExample />,
 };
+
+const photon = createPhotonGeocoder();
+
+function LiveField(props: GeolocationProps) {
+  const [value, setValue] = useState(props.value ?? "");
+  return (
+    <Geolocation
+      {...props}
+      value={value}
+      onChange={(next) => {
+        setValue(next);
+        action("onChange")(next);
+      }}
+    />
+  );
+}
+
+/**
+ * Keyless live search through Photon (photon.komoot.io). Type a place name;
+ * the results panel lists real geocoded places. No key, no account.
+ */
+export const LiveKeylessSearch: Story = {
+  render: () => (
+    <GeocoderProvider geocoder={photon}>
+      <YStack gap="$4" maxWidth={500}>
+        <LiveField label="Location" expandIcon={<ArrowsOutIcon size={16} />} />
+      </YStack>
+    </GeocoderProvider>
+  ),
+};
+
+/** A set value reverse-geocodes to an address, editable and read-only. */
+export const LiveKeylessAddress: Story = {
+  render: () => (
+    <GeocoderProvider geocoder={photon}>
+      <YStack gap="$4" maxWidth={500}>
+        <LiveField label="Office" value={JSON.stringify({ lat: 60.16952, lng: 24.93545 })} />
+        <Geolocation
+          label="Office (read-only)"
+          value={JSON.stringify({ lat: 60.16952, lng: 24.93545 })}
+          readOnly
+        />
+      </YStack>
+    </GeocoderProvider>
+  ),
+};
+
+type LiveRow = { id: string; label: string; value: { lat: number; lng: number } | "" };
+
+function LiveTable() {
+  const [data, setData] = useState<LiveRow[]>([
+    { id: "1", label: "Austin", value: { lat: 30.2672, lng: -97.7431 } },
+    { id: "2", label: "Paris", value: { lat: 48.8566, lng: 2.3522 } },
+    { id: "3", label: "Empty", value: "" },
+  ]);
+  const columns: DataTableColumn<LiveRow>[] = [
+    { accessorKey: "label", header: "Row" },
+    { accessorKey: "value", header: "Location", field: "geolocation" },
+  ];
+  return (
+    <YStack width="100%" height={320}>
+      <DataTable data={data} columns={columns} enablePagination={false} onDataChange={setData} />
+    </YStack>
+  );
+}
+
+/** The provider reaches fields a table renders: cell faces read as addresses. */
+export const LiveKeylessInTable: Story = {
+  render: () => (
+    <GeocoderProvider geocoder={photon}>
+      <LiveTable />
+    </GeocoderProvider>
+  ),
+};

package/src/fields/Geolocation/GeolocationMap.tsx

@@ -87,6 +87,9 @@ export function GeolocationMap({
               key={`${zoom}-${tile.tx}-${tile.ty}-${Math.round(tile.left)}-${Math.round(tile.top)}`}
               alt=""
               draggable={false}
+              onError={(event) => {
+                event.currentTarget.style.visibility = "hidden";
+              }}
               src={tileSrc(zoom, tile.tx, tile.ty)}
               width={OSM_TILE_SIZE}
               height={OSM_TILE_SIZE}

package/src/fields/Geolocation/geocoderContext.tsx

@@ -0,0 +1,56 @@
+import type { ReactNode } from "react";
+import { createContext, useContext, useEffect, useState } from "react";
+import type { Geocoder } from "./geocoder";
+import { formatPlace } from "./geocoder";
+
+const GeocoderContext = createContext<Geocoder | null>(null);
+
+/**
+ * Hands one geocoder to every Geolocation field below it, including fields a
+ * registry or a table renders where the app cannot reach props. A field's own
+ * `geocode` / `reverseGeocode` / `geocoder` props win, and `geocoder={null}`
+ * opts a field out. Create the geocoder once (module scope or `useMemo`), not
+ * per render.
+ */
+export function GeocoderProvider({
+  geocoder,
+  children,
+}: {
+  geocoder: Geocoder | null;
+  children?: ReactNode;
+}) {
+  return <GeocoderContext.Provider value={geocoder}>{children}</GeocoderContext.Provider>;
+}
+
+export function useGeocoder(): Geocoder | null {
+  return useContext(GeocoderContext);
+}
+
+/**
+ * The provider's address for a pair, or null while it resolves, when no
+ * provider is mounted, when nothing is near, or when the lookup fails. A
+ * read-only face shows the pair until this answers.
+ */
+export function useReverseGeocodedLabel(pair: { lat: number; lng: number } | null): string | null {
+  const geocoder = useGeocoder();
+  const lat = pair?.lat;
+  const lng = pair?.lng;
+  const key = lat === undefined || lng === undefined ? null : `${lat},${lng}`;
+  const [resolved, setResolved] = useState<{ key: string; label: string } | null>(null);
+  useEffect(() => {
+    if (!geocoder || lat === undefined || lng === undefined || key === null) return;
+    let live = true;
+    geocoder.reverseGeocode({ lat, lng }).then(
+      (result) => {
+        if (live) setResolved(result ? { key, label: formatPlace(result) } : null);
+      },
+      () => {
+        if (live) setResolved(null);
+      },
+    );
+    return () => {
+      live = false;
+    };
+  }, [geocoder, key, lat, lng]);
+  return resolved && resolved.key === key ? resolved.label : null;
+}