@multiplatform.one/forms 7.7.4 → 7.8.0

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

@@ -0,0 +1,59 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+  clampLat,
+  clampLng,
+  formatCoordPair,
+  formatPlace,
+  parseLatLngPair,
+  resolveGeocoder,
+} from "./geocoder";
+
+import { parseGeoValue, formatGeoValue } from "./geoValue";
+
+describe("geocoder seam helpers", () => {
+  it("parses and serializes the lat/lng JSON value", () => {
+    expect(parseGeoValue(undefined)).toBeNull();
+    expect(parseGeoValue("")).toBeNull();
+    expect(parseGeoValue("{")).toBeNull();
+    expect(parseGeoValue(JSON.stringify({ lat: 60.16952, lng: 24.93545 }))).toEqual({
+      lat: 60.16952,
+      lng: 24.93545,
+    });
+    expect(formatGeoValue({ lat: clampLat(91), lng: clampLng(200) }, "latlng")).toBe(
+      JSON.stringify({ lat: 90, lng: 180 }),
+    );
+  });
+
+  it("formats the subordinate pair at five decimals", () => {
+    expect(formatCoordPair(60.16952, 24.93545)).toBe("60.16952, 24.93545");
+  });
+
+  it("parses a typed lat, lng pair and rejects out-of-range", () => {
+    expect(parseLatLngPair("60.169, 24.935")).toEqual({ lat: 60.169, lng: 24.935 });
+    expect(parseLatLngPair("  -33.8,  151.2 ")).toEqual({ lat: -33.8, lng: 151.2 });
+    expect(parseLatLngPair("mannerheim")).toBeNull();
+    expect(parseLatLngPair("91, 0")).toBeNull();
+    expect(parseLatLngPair("0, 200")).toBeNull();
+  });
+
+  it("clamps latitude and longitude", () => {
+    expect(clampLat(100)).toBe(90);
+    expect(clampLng(-200)).toBe(-180);
+  });
+
+  it("joins a described place for the input face", () => {
+    expect(formatPlace({ label: "Mannerheimintie 3", description: "00100 Helsinki" })).toBe(
+      "Mannerheimintie 3, 00100 Helsinki",
+    );
+  });
+
+  it("resolveGeocoder prefers explicit props over a geocoder object", () => {
+    const geocode = vi.fn();
+    const reverseGeocode = vi.fn();
+    const other = { geocode: vi.fn(), reverseGeocode: vi.fn() };
+    const resolved = resolveGeocoder({ geocode, reverseGeocode, geocoder: other });
+    expect(resolved.geocode).toBe(geocode);
+    expect(resolved.reverseGeocode).toBe(reverseGeocode);
+    expect(resolveGeocoder({}).geocode).toBeUndefined();
+  });
+});

package/src/fields/Geolocation/geocoder.ts

@@ -0,0 +1,84 @@
+/**
+ * Geolocation geocoder seam (R4 / MPO-54).
+ *
+ * The field never holds provider credentials and never wires a default
+ * network provider. Consumers inject `geocode` / `reverseGeocode` (or a
+ * `Geocoder` object) and the field calls only what it was handed. With no
+ * geocoder injected, search is disabled and the map / locate / coordinate
+ * paths stay intact — the package never reaches a third party the consumer
+ * did not choose.
+ *
+ * This file is the seam and nothing else: no provider, no endpoint, no
+ * transport. A provider is whatever a consumer writes against `Geocoder` —
+ * an offline gazetteer, their own backend proxy holding a commercial key, or
+ * a self-hosted geocoder. See `geocoderSeam.spec.tsx` for both shapes.
+ */
+
+import type { GeoValue } from "./geoValue";
+
+export interface GeocodeResult {
+  lat: number;
+  lng: number;
+  /** Primary line — the place name. */
+  label: string;
+  /** Secondary line — locality / region. Omitted for a bare coordinate. */
+  description?: string;
+}
+
+export interface GeocodeQuery {
+  query: string;
+}
+
+export interface ReverseGeocodeQuery {
+  lat: number;
+  lng: number;
+}
+
+export type GeocodeFn = (query: GeocodeQuery) => Promise<GeocodeResult[]>;
+export type ReverseGeocodeFn = (query: ReverseGeocodeQuery) => Promise<GeocodeResult | null>;
+
+export interface Geocoder {
+  geocode: GeocodeFn;
+  reverseGeocode: ReverseGeocodeFn;
+}
+
+const LAT_LNG_PAIR = /^\s*(-?\d+(?:\.\d+)?)\s*,\s*(-?\d+(?:\.\d+)?)\s*$/;
+
+export function clampLat(val: number): number {
+  return Math.max(-90, Math.min(90, val));
+}
+
+export function clampLng(val: number): number {
+  return Math.max(-180, Math.min(180, val));
+}
+
+/** Quiet mono disclosure / cell fallback — five decimals, board media-13. */
+export function formatCoordPair(lat: number, lng: number): string {
+  return `${lat.toFixed(5)}, ${lng.toFixed(5)}`;
+}
+
+/** Expert path through the same search input: a typed `lat, lng` pair. */
+export function parseLatLngPair(text: string): GeoValue | null {
+  const match = LAT_LNG_PAIR.exec(text);
+  if (!match) return null;
+  const lat = Number.parseFloat(match[1]);
+  const lng = Number.parseFloat(match[2]);
+  if (!Number.isFinite(lat) || !Number.isFinite(lng)) return null;
+  if (lat < -90 || lat > 90 || lng < -180 || lng > 180) return null;
+  return { lat, lng };
+}
+
+export function formatPlace(result: Pick<GeocodeResult, "label" | "description">): string {
+  return result.description ? `${result.label}, ${result.description}` : result.label;
+}
+
+export function resolveGeocoder(input: {
+  geocode?: GeocodeFn;
+  reverseGeocode?: ReverseGeocodeFn;
+  geocoder?: Geocoder;
+}): { geocode?: GeocodeFn; reverseGeocode?: ReverseGeocodeFn } {
+  return {
+    geocode: input.geocode ?? input.geocoder?.geocode,
+    reverseGeocode: input.reverseGeocode ?? input.geocoder?.reverseGeocode,
+  };
+}

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

@@ -0,0 +1,203 @@
+/**
+ * R4 candidate A evidence — the seam alone is sufficient.
+ *
+ * Nothing here imports `createNominatimGeocoder`. Every provider in this file
+ * is written by hand the way a consumer would write one, typed only against
+ * the exported `Geocoder` / `GeocodeFn` / `ReverseGeocodeFn` contract. If this
+ * file is green with the adapter deleted from the package, candidate A ships.
+ *
+ * The two shapes a real consumer actually has:
+ *   1. a static/offline provider (no network at all)
+ *   2. a backend-proxy provider (the key lives on the consumer's server and
+ *      never reaches the client — the only shape a KEYED provider can take
+ *      in a component that must not hold credentials)
+ */
+
+import { describe, expect, it, vi } from "vitest";
+import { fireEvent, waitFor } from "@testing-library/react";
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { Geolocation } from "./index";
+import type { GeocodeResult, Geocoder } from "./geocoder";
+
+const HELSINKI = JSON.stringify({ lat: 60.16952, lng: 24.93545 });
+const SYDNEY = JSON.stringify({ lat: -33.8688, lng: 151.2093 });
+
+function searchInput(container: HTMLElement) {
+  return (container.querySelector("[data-testid='geolocation-search']") ??
+    container.querySelector("[aria-label='Search for a location']")) as HTMLInputElement | null;
+}
+
+function typeSearch(container: HTMLElement, text: string) {
+  const input = searchInput(container);
+  expect(input).not.toBeNull();
+  fireEvent.change(input as HTMLInputElement, { target: { value: text } });
+}
+
+/**
+ * Consumer provider #1 — offline gazetteer. No network, no key, no adapter.
+ * This is the whole implementation; it is what candidate A asks a consumer to
+ * write, and it is 14 lines.
+ */
+const gazetteer: GeocodeResult[] = [
+  { lat: 60.16952, lng: 24.93545, label: "Mannerheimintie 3", description: "Kamppi, Helsinki" },
+  { lat: -33.8688, lng: 151.2093, label: "Sydney", description: "New South Wales, Australia" },
+];
+
+const offlineGeocoder = {
+  geocode: async ({ query }) =>
+    gazetteer.filter((place) => place.label.toLowerCase().includes(query.trim().toLowerCase())),
+  reverseGeocode: async ({ lat, lng }) =>
+    gazetteer.find(
+      (place) => Math.abs(place.lat - lat) < 0.01 && Math.abs(place.lng - lng) < 0.01,
+    ) ?? null,
+} satisfies Geocoder;
+
+/**
+ * Consumer provider #2 — backend proxy. The consumer's own server holds the
+ * provider key; the component sees only `fetch`. This is the shape a keyed
+ * provider must take, and the reason the seam is the load-bearing half of R4
+ * under BOTH candidates.
+ */
+function createProxyGeocoder(options: {
+  endpoint: string;
+  fetch: typeof globalThis.fetch;
+}): Geocoder {
+  const call = async (path: string, params: Record<string, string>): Promise<unknown> => {
+    const url = new URL(path, options.endpoint);
+    for (const [key, value] of Object.entries(params)) url.searchParams.set(key, value);
+    const response = await options.fetch(url.toString());
+    if (!response.ok) throw new Error(`proxy geocoder failed (${response.status})`);
+    return response.json();
+  };
+  return {
+    geocode: async ({ query }) => (await call("search", { q: query })) as GeocodeResult[],
+    reverseGeocode: async ({ lat, lng }) =>
+      (await call("reverse", { lat: String(lat), lng: String(lng) })) as GeocodeResult | null,
+  };
+}
+
+describe("R4 candidate A — a consumer-authored geocoder satisfies the seam", () => {
+  it("type-level: a hand-written object satisfies Geocoder with no package adapter", () => {
+    // `satisfies Geocoder` above is the compile-time assertion; this asserts the
+    // same contract at runtime so the evidence is not purely structural.
+    expect(typeof offlineGeocoder.geocode).toBe("function");
+    expect(typeof offlineGeocoder.reverseGeocode).toBe("function");
+    const proxy = createProxyGeocoder({ endpoint: "https://app.example/geo/", fetch: vi.fn() });
+    expect(typeof proxy.geocode).toBe("function");
+    expect(typeof proxy.reverseGeocode).toBe("function");
+  });
+
+  it("offline provider drives the whole field: search, pick, value, address", async () => {
+    const onChange = vi.fn();
+    const result = renderWithProviders(
+      <Geolocation label="Location" geocoder={offlineGeocoder} onChange={onChange} />,
+    );
+
+    typeSearch(result.container, "sydney");
+    await waitFor(() => {
+      expect(document.querySelector("[data-testid='geolocation-results']")).not.toBeNull();
+      expect(document.body.textContent).toContain("Sydney");
+      expect(document.body.textContent).toContain("New South Wales, Australia");
+    });
+
+    fireEvent.click(document.querySelector("[data-testid='geolocation-result-0']") as Element);
+    await waitFor(() => {
+      expect(onChange).toHaveBeenCalledWith(SYDNEY);
+    });
+    expect(searchInput(result.container)?.value).toBe("Sydney, New South Wales, Australia");
+  });
+
+  it("offline provider reverse-geocodes a set value into the address face", async () => {
+    const result = renderWithProviders(
+      <Geolocation label="Location" value={HELSINKI} geocoder={offlineGeocoder} />,
+    );
+    await waitFor(() => {
+      expect(searchInput(result.container)?.value).toBe("Mannerheimintie 3, Kamppi, Helsinki");
+    });
+    expect(result.container.textContent).toContain("60.16952, 24.93545");
+  });
+
+  it("backend-proxy provider drives the same field through injected fetch only", async () => {
+    const fetchImpl = vi.fn(async (url: string) => {
+      const parsed = new URL(url);
+      if (parsed.pathname.endsWith("/search")) {
+        return {
+          ok: true,
+          json: async () => [
+            {
+              lat: 60.16952,
+              lng: 24.93545,
+              label: "Mannerheimintie 3",
+              description: "Kamppi, Helsinki",
+            },
+          ],
+        };
+      }
+      return { ok: true, json: async () => null };
+    });
+    const onChange = vi.fn();
+    const result = renderWithProviders(
+      <Geolocation
+        label="Location"
+        geocoder={createProxyGeocoder({
+          endpoint: "https://app.example/geo/",
+          fetch: fetchImpl as unknown as typeof globalThis.fetch,
+        })}
+        onChange={onChange}
+      />,
+    );
+
+    typeSearch(result.container, "manner");
+    await waitFor(() => {
+      expect(document.body.textContent).toContain("Mannerheimintie 3");
+    });
+    fireEvent.click(document.querySelector("[data-testid='geolocation-result-0']") as Element);
+    await waitFor(() => {
+      expect(onChange).toHaveBeenCalledWith(HELSINKI);
+    });
+    // No credential ever reaches the component: it only ever saw a fetch.
+    const calledUrl = String(fetchImpl.mock.calls[0]?.[0]);
+    expect(calledUrl).toContain("app.example");
+    expect(calledUrl).not.toContain("nominatim");
+  });
+
+  it("swapping providers is a prop change — the component is untouched", async () => {
+    const first = renderWithProviders(
+      <Geolocation label="Location" value={HELSINKI} geocoder={offlineGeocoder} />,
+    );
+    await waitFor(() => {
+      expect(searchInput(first.container)?.value).toBe("Mannerheimintie 3, Kamppi, Helsinki");
+    });
+
+    const renamed: Geocoder = {
+      geocode: offlineGeocoder.geocode,
+      reverseGeocode: async () => ({ lat: 60.16952, lng: 24.93545, label: "HQ" }),
+    };
+    const second = renderWithProviders(
+      <Geolocation label="Location" value={HELSINKI} geocoder={renamed} />,
+    );
+    await waitFor(() => {
+      expect(searchInput(second.container)?.value).toBe("HQ");
+    });
+  });
+
+  it("a failing consumer provider degrades honestly — map and pair survive", async () => {
+    const broken: Geocoder = {
+      geocode: async () => {
+        throw new Error("consumer provider down");
+      },
+      reverseGeocode: async () => {
+        throw new Error("consumer provider down");
+      },
+    };
+    const result = renderWithProviders(
+      <Geolocation label="Location" value={HELSINKI} geocoder={broken} />,
+    );
+    typeSearch(result.container, "manner");
+    await waitFor(() => {
+      expect(result.container.querySelector("[data-testid='geolocation-map']")).not.toBeNull();
+    });
+    expect(result.container.querySelector("[data-testid='geolocation-coordline']")).not.toBeNull();
+    expect(result.container.textContent).toContain("60.16952, 24.93545");
+  });
+});