feat(search): resolve H3 cell indexes in the place-search box (#1497)

* feat(search): resolve H3 cell indexes in the place-search box

Typing an H3 cell index into the Layers panel search box now resolves it
locally, with no geocoder round-trip, and jumps to that cell. Both
spellings people copy around are accepted: the hexadecimal string
(8928308280fffff, optionally 0x-prefixed and in any case) and the
unsigned 64-bit integer (617700169958293503).

Selecting the result fits the view to the cell rather than flying to a
fixed zoom, since a cell spans anything from a continent at resolution 0
to under a square meter at resolution 15, and outlines the cell on the
map so the match is visible. The outline is ephemeral, cleared on the
next selection, on Clear, and on unmount.

Parsing lives in a standalone lib module alongside coordinates.ts so it
unit tests in isolation, and unwraps boundary longitudes around the cell
center so a cell crossing the antimeridian yields a contiguous ring.

Fixes #1492

* i18n: localize the search placeholder's coordinate and H3 hints

The English placeholder advertises place, lat/lon, and H3 input, but every
other locale still read "Search places...", so the two locally resolved
query forms were undiscoverable outside English. Bring all 15 remaining
locales in line.

Author: giswqs

apps/geolibre-desktop/package.json

@@ -57,6 +57,7 @@
     "exifr": "^7.1.3",
     "fflate": "^0.8.3",
     "gdal3.js": "^2.8.1",
+    "h3-js": "^4.5.0",
     "html2canvas-pro": "^2.3.2",
     "i18next": "^26.3.6",
     "jspdf": "^4.2.1",

apps/geolibre-desktop/src/components/panels/LayerPanelPlaceSearch.tsx

@@ -19,8 +19,9 @@ import {
 } from "@geolibre/core";
 import type { MapController } from "@geolibre/map";
 import { Input } from "@geolibre/ui";
-import { Loader2, LocateFixed, MapPin, Search, X } from "lucide-react";
+import { Hexagon, Loader2, LocateFixed, MapPin, Search, X } from "lucide-react";
 import { formatLatLon, parseLatLon } from "../../lib/coordinates";
+import { type H3CellMatch, parseH3Cell } from "../../lib/h3-search";
 
 interface LayerPanelPlaceSearchProps {
   mapControllerRef: RefObject<MapController | null>;
@@ -32,6 +33,12 @@ const DEBOUNCE_MS = 500;
 const MAX_RESULTS = 6;
 /** Don't search until the query is at least this many characters. */
 const MIN_QUERY_LENGTH = 2;
+/** Ephemeral map ids for the outline drawn around a searched H3 cell. */
+const H3_SOURCE_ID = "geolibre-h3-search-cell";
+const H3_FILL_LAYER_ID = "geolibre-h3-search-cell-fill";
+const H3_LINE_LAYER_ID = "geolibre-h3-search-cell-line";
+/** Highlight color for the H3 cell, matching the place-search marker. */
+const H3_HIGHLIGHT_COLOR = "#ef4444";
 
 type SearchStatus = "idle" | "loading" | "error" | "empty";
 
@@ -40,6 +47,11 @@ type SearchStatus = "idle" | "loading" | "error" | "empty";
  * panel. Forward-geocodes the typed query through the configured provider,
  * lists matches in a dropdown above the input, and on selection flies the map
  * to the place and drops a marker. Replaces the former advanced-formats note.
+ *
+ * Two query forms bypass the geocoder entirely and resolve locally: a lat/lon
+ * coordinate (see `coordinates.ts`) and an H3 cell index in either spelling
+ * (see `h3-search.ts`), the latter fitting the view to the cell and outlining
+ * it on the map.
  */
 export function LayerPanelPlaceSearch({
   mapControllerRef,
@@ -53,6 +65,9 @@ export function LayerPanelPlaceSearch({
   // True when the single result is a parsed lat/lon jump rather than a geocoder
   // match, so the row is labeled and iconed as a coordinate instead of a place.
   const [isCoordinate, setIsCoordinate] = useState(false);
+  // Set when the single result is a parsed H3 cell index, both to label the row
+  // and to supply the outline drawn on selection.
+  const [h3Cell, setH3Cell] = useState<H3CellMatch | null>(null);
   const [open, setOpen] = useState(false);
   const [status, setStatus] = useState<SearchStatus>("idle");
   const [activeIndex, setActiveIndex] = useState(-1);
@@ -74,13 +89,28 @@ export function LayerPanelPlaceSearch({
     return Math.max(DEBOUNCE_MS, geocoderMinIntervalMs(endpoint));
   }, [geocodingPrefs]);
 
+  /**
+   * Remove the H3 cell outline from the map, if one is currently drawn. Safe to
+   * call when the map is gone or was never given the highlight (style reloads
+   * drop it), so callers never have to track whether it exists.
+   */
+  const clearH3Highlight = useCallback(() => {
+    const map = mapControllerRef.current?.getMap();
+    if (!map) return;
+    for (const layerId of [H3_FILL_LAYER_ID, H3_LINE_LAYER_ID]) {
+      if (map.getLayer(layerId)) map.removeLayer(layerId);
+    }
+    if (map.getSource(H3_SOURCE_ID)) map.removeSource(H3_SOURCE_ID);
+  }, [mapControllerRef]);
+
   useEffect(
     () => () => {
       abortRef.current?.abort();
       markerRef.current?.remove();
+      clearH3Highlight();
       if (blurTimerRef.current) clearTimeout(blurTimerRef.current);
     },
-    [],
+    [clearH3Highlight],
   );
 
   const runSearch = useCallback(
@@ -89,6 +119,7 @@ export function LayerPanelPlaceSearch({
       const controller = new AbortController();
       abortRef.current = controller;
       setIsCoordinate(false);
+      setH3Cell(null);
       setStatus("loading");
       setActiveIndex(-1);
       setOpen(true);
@@ -122,10 +153,25 @@ export function LayerPanelPlaceSearch({
       setResults([]);
       setActiveIndex(-1);
       setIsCoordinate(false);
+      setH3Cell(null);
       setStatus("idle");
       setOpen(false);
       return;
     }
+    // H3 short-circuit: a query that parses as an H3 cell index (hexadecimal or
+    // unsigned 64-bit integer) resolves locally to that cell's center, so the
+    // exact cell is used rather than whatever the geocoder makes of the digits.
+    const cell = parseH3Cell(trimmed);
+    if (cell) {
+      abortRef.current?.abort();
+      setResults([{ lat: cell.lat, lon: cell.lon, displayName: cell.cell, score: null }]);
+      setActiveIndex(0);
+      setIsCoordinate(false);
+      setH3Cell(cell);
+      setStatus("idle");
+      setOpen(true);
+      return;
+    }
     // Coordinate short-circuit: a query that parses as lat/lon (DD, DMS, or DDM)
     // becomes a direct "go to coordinate" jump, resolved instantly with no
     // geocoder round-trip so the exact point (not the nearest named place) is
@@ -138,6 +184,7 @@ export function LayerPanelPlaceSearch({
       ]);
       setActiveIndex(0);
       setIsCoordinate(true);
+      setH3Cell(null);
       setStatus("idle");
       setOpen(true);
       return;
@@ -151,16 +198,45 @@ export function LayerPanelPlaceSearch({
   const handleSelect = useCallback(
     (match: GeocodeMatch) => {
       const map = mapControllerRef.current?.getMap();
-      // Drop the previous marker unconditionally so it is never orphaned when
-      // the map is briefly unavailable (mount/teardown/headless).
+      // Drop the previous marker and cell outline unconditionally so neither is
+      // ever orphaned when the map is briefly unavailable (mount/teardown/
+      // headless) or when the next result is of a different kind.
       markerRef.current?.remove();
       markerRef.current = null;
-      if (map) {
+      clearH3Highlight();
+      if (map && h3Cell) {
+        // An H3 cell spans anything from a continent (resolution 0) to under a
+        // square meter (resolution 15), so frame the cell itself rather than
+        // flying to a fixed zoom, and outline it so the match is visible.
+        map.addSource(H3_SOURCE_ID, {
+          type: "geojson",
+          data: {
+            type: "Feature",
+            properties: { h3: h3Cell.cell, resolution: h3Cell.resolution },
+            geometry: { type: "Polygon", coordinates: [h3Cell.boundary] },
+          },
+        });
+        map.addLayer({
+          id: H3_FILL_LAYER_ID,
+          type: "fill",
+          source: H3_SOURCE_ID,
+          paint: { "fill-color": H3_HIGHLIGHT_COLOR, "fill-opacity": 0.15 },
+        });
+        map.addLayer({
+          id: H3_LINE_LAYER_ID,
+          type: "line",
+          source: H3_SOURCE_ID,
+          paint: { "line-color": H3_HIGHLIGHT_COLOR, "line-width": 2 },
+        });
+        const bounds = new maplibregl.LngLatBounds();
+        for (const position of h3Cell.boundary) bounds.extend(position);
+        map.fitBounds(bounds, { padding: 60 });
+      } else if (map) {
         map.flyTo({
           center: [match.lon, match.lat],
           zoom: Math.max(map.getZoom(), 12),
         });
-        markerRef.current = new maplibregl.Marker({ color: "#ef4444" })
+        markerRef.current = new maplibregl.Marker({ color: H3_HIGHLIGHT_COLOR })
           .setLngLat([match.lon, match.lat])
           .addTo(map);
       }
@@ -169,23 +245,26 @@ export function LayerPanelPlaceSearch({
       setResults([]);
       setActiveIndex(-1);
       setIsCoordinate(false);
+      setH3Cell(null);
       setStatus("idle");
       setOpen(false);
     },
-    [mapControllerRef],
+    [clearH3Highlight, h3Cell, mapControllerRef],
   );
 
   const handleClear = useCallback(() => {
     abortRef.current?.abort();
     markerRef.current?.remove();
     markerRef.current = null;
+    clearH3Highlight();
     setQuery("");
     setResults([]);
     setActiveIndex(-1);
     setIsCoordinate(false);
+    setH3Cell(null);
     setStatus("idle");
     setOpen(false);
-  }, []);
+  }, [clearH3Highlight]);
 
   const showResults = status === "idle" && results.length > 0;
 
@@ -226,17 +305,24 @@ export function LayerPanelPlaceSearch({
                     }}
                     onMouseEnter={() => setActiveIndex(index)}
                   >
-                    {isCoordinate ? (
+                    {h3Cell ? (
+                      <Hexagon className="mt-0.5 h-3.5 w-3.5 shrink-0 text-muted-foreground" />
+                    ) : isCoordinate ? (
                       <LocateFixed className="mt-0.5 h-3.5 w-3.5 shrink-0 text-muted-foreground" />
                     ) : (
                       <MapPin className="mt-0.5 h-3.5 w-3.5 shrink-0 text-muted-foreground" />
                     )}
                     <span className="line-clamp-2">
-                      {isCoordinate
-                        ? t("layers.searchPlacesGoToCoordinate", {
-                            coordinate: match.displayName,
+                      {h3Cell
+                        ? t("layers.searchPlacesGoToH3Cell", {
+                            cell: h3Cell.cell,
+                            resolution: h3Cell.resolution,
                           })
-                        : match.displayName}
+                        : isCoordinate
+                          ? t("layers.searchPlacesGoToCoordinate", {
+                              coordinate: match.displayName,
+                            })
+                          : match.displayName}
                     </span>
                   </button>
                 </li>

apps/geolibre-desktop/src/i18n/locales/ar.json

@@ -4251,12 +4251,13 @@
     "saveEditsPostgisNoConnection": "لا يتوفر اتصال PostgreSQL لهذه الطبقة. أعد الاتصال من إضافة البيانات > PostgreSQL، ثم حاول مرة أخرى.",
     "typeBasemap": "خريطة أساس",
     "searchPlaces": "البحث عن أماكن",
-    "searchPlacesPlaceholder": "ابحث عن أماكن...",
+    "searchPlacesPlaceholder": "ابحث عن مكان أو إحداثيات أو خلية H3...",
     "searchPlacesSearching": "جارٍ البحث...",
     "searchPlacesNoResults": "لم يُعثر على أماكن",
     "searchPlacesError": "فشل البحث. حاول مرة أخرى.",
     "searchPlacesClear": "مسح البحث",
     "searchPlacesGoToCoordinate": "الانتقال إلى {{coordinate}}",
+    "searchPlacesGoToH3Cell": "الانتقال إلى خلية H3 ‏{{cell}} (الدقة {{resolution}})",
     "background": "الخلفية",
     "backgroundCannotReorder": "لا يمكن إعادة ترتيب الخلفية",
     "hideBackground": "إخفاء الخلفية",

apps/geolibre-desktop/src/i18n/locales/de.json

@@ -4020,12 +4020,13 @@
     "saveEditsPostgisNoConnection": "Für diese Ebene ist keine PostgreSQL-Verbindung verfügbar. Stellen Sie die Verbindung unter Daten hinzufügen > PostgreSQL erneut her und versuchen Sie es dann noch einmal.",
     "typeBasemap": "Basiskarte",
     "searchPlaces": "Orte suchen",
-    "searchPlacesPlaceholder": "Orte suchen...",
+    "searchPlacesPlaceholder": "Orte, Koordinaten oder H3-Zelle suchen...",
     "searchPlacesSearching": "Suche läuft...",
     "searchPlacesNoResults": "Keine Orte gefunden",
     "searchPlacesError": "Suche fehlgeschlagen. Versuchen Sie es erneut.",
     "searchPlacesClear": "Suche löschen",
     "searchPlacesGoToCoordinate": "Zu {{coordinate}} springen",
+    "searchPlacesGoToH3Cell": "Zur H3-Zelle {{cell}} springen (Res. {{resolution}})",
     "background": "Hintergrund",
     "backgroundCannotReorder": "Der Hintergrund kann nicht neu angeordnet werden",
     "hideBackground": "Hintergrund ausblenden",

apps/geolibre-desktop/src/i18n/locales/en.json

@@ -4255,12 +4255,13 @@
     "saveEditsPostgisNoConnection": "No PostgreSQL connection is available for this layer. Reconnect in Add Data > PostgreSQL, then try again.",
     "typeBasemap": "basemap",
     "searchPlaces": "Search places",
-    "searchPlacesPlaceholder": "Search places or lat, lon...",
+    "searchPlacesPlaceholder": "Search places, lat, lon, or H3 cell...",
     "searchPlacesSearching": "Searching...",
     "searchPlacesNoResults": "No places found",
     "searchPlacesError": "Search failed. Try again.",
     "searchPlacesClear": "Clear search",
     "searchPlacesGoToCoordinate": "Go to {{coordinate}}",
+    "searchPlacesGoToH3Cell": "Go to H3 cell {{cell}} (res {{resolution}})",
     "background": "Background",
     "backgroundCannotReorder": "Background cannot be reordered",
     "hideBackground": "Hide background",

apps/geolibre-desktop/src/i18n/locales/es.json

@@ -4031,12 +4031,13 @@
     "saveEditsPostgisNoConnection": "No hay ninguna conexión de PostgreSQL disponible para esta capa. Vuelva a conectar en Añadir datos > PostgreSQL, e inténtelo de nuevo.",
     "typeBasemap": "mapa base",
     "searchPlaces": "Buscar lugares",
-    "searchPlacesPlaceholder": "Buscar lugares...",
+    "searchPlacesPlaceholder": "Buscar lugares, coordenadas o celda H3...",
     "searchPlacesSearching": "Buscando...",
     "searchPlacesNoResults": "No se encontraron lugares",
     "searchPlacesError": "Error en la búsqueda. Inténtelo de nuevo.",
     "searchPlacesClear": "Borrar búsqueda",
     "searchPlacesGoToCoordinate": "Ir a {{coordinate}}",
+    "searchPlacesGoToH3Cell": "Ir a la celda H3 {{cell}} (res. {{resolution}})",
     "background": "Fondo",
     "backgroundCannotReorder": "El fondo no se puede reordenar",
     "hideBackground": "Ocultar fondo",

apps/geolibre-desktop/src/i18n/locales/fr.json

@@ -4020,12 +4020,13 @@
     "saveEditsPostgisNoConnection": "Aucune connexion PostgreSQL n'est disponible pour cette couche. Reconnectez-vous dans Ajouter des données > PostgreSQL, puis réessayez.",
     "typeBasemap": "fond de carte",
     "searchPlaces": "Rechercher des lieux",
-    "searchPlacesPlaceholder": "Rechercher des lieux...",
+    "searchPlacesPlaceholder": "Rechercher un lieu, des coordonnées ou une cellule H3...",
     "searchPlacesSearching": "Recherche...",
     "searchPlacesNoResults": "Aucun lieu trouvé",
     "searchPlacesError": "Échec de la recherche. Réessayez.",
     "searchPlacesClear": "Effacer la recherche",
     "searchPlacesGoToCoordinate": "Aller à {{coordinate}}",
+    "searchPlacesGoToH3Cell": "Aller à la cellule H3 {{cell}} (rés. {{resolution}})",
     "background": "Arrière-plan",
     "backgroundCannotReorder": "L'arrière-plan ne peut pas être réorganisé",
     "hideBackground": "Masquer l'arrière-plan",

apps/geolibre-desktop/src/i18n/locales/hi.json

@@ -4020,12 +4020,13 @@
     "saveEditsPostgisNoConnection": "इस लेयर के लिए कोई PostgreSQL कनेक्शन उपलब्ध नहीं है। Add Data > PostgreSQL में पुनः कनेक्ट करें, फिर पुनः प्रयास करें।",
     "typeBasemap": "बेसमैप",
     "searchPlaces": "स्थान खोजें",
-    "searchPlacesPlaceholder": "स्थान खोजें...",
+    "searchPlacesPlaceholder": "स्थान, निर्देशांक या H3 सेल खोजें...",
     "searchPlacesSearching": "खोजा जा रहा है...",
     "searchPlacesNoResults": "कोई स्थान नहीं मिला",
     "searchPlacesError": "खोज विफल रही। पुनः प्रयास करें।",
     "searchPlacesClear": "खोज साफ़ करें",
     "searchPlacesGoToCoordinate": "{{coordinate}} पर जाएँ",
+    "searchPlacesGoToH3Cell": "H3 सेल {{cell}} पर जाएँ (रेज़ॉल्यूशन {{resolution}})",
     "background": "पृष्ठभूमि",
     "backgroundCannotReorder": "पृष्ठभूमि का क्रम नहीं बदला जा सकता",
     "hideBackground": "पृष्ठभूमि छिपाएं",

apps/geolibre-desktop/src/i18n/locales/id.json

@@ -3962,12 +3962,13 @@
     "saveEditsPostgisNoConnection": "Tidak ada koneksi PostgreSQL yang tersedia untuk layer ini. Hubungkan kembali di Tambah Data > PostgreSQL, lalu coba lagi.",
     "typeBasemap": "peta dasar",
     "searchPlaces": "Cari tempat",
-    "searchPlacesPlaceholder": "Cari tempat...",
+    "searchPlacesPlaceholder": "Cari tempat, koordinat, atau sel H3...",
     "searchPlacesSearching": "Mencari...",
     "searchPlacesNoResults": "Tidak ada tempat yang ditemukan",
     "searchPlacesError": "Pencarian gagal. Coba lagi.",
     "searchPlacesClear": "Bersihkan pencarian",
     "searchPlacesGoToCoordinate": "Menuju {{coordinate}}",
+    "searchPlacesGoToH3Cell": "Menuju sel H3 {{cell}} (res {{resolution}})",
     "background": "Latar belakang",
     "backgroundCannotReorder": "Latar belakang tidak dapat diurutkan ulang",
     "hideBackground": "Sembunyikan latar belakang",

apps/geolibre-desktop/src/i18n/locales/it.json

@@ -4020,12 +4020,13 @@
     "saveEditsPostgisNoConnection": "Nessuna connessione PostgreSQL disponibile per questo livello. Riconnetti da Aggiungi dati > PostgreSQL, quindi riprova.",
     "typeBasemap": "mappa di base",
     "searchPlaces": "Cerca luoghi",
-    "searchPlacesPlaceholder": "Cerca luoghi...",
+    "searchPlacesPlaceholder": "Cerca luoghi, coordinate o celle H3...",
     "searchPlacesSearching": "Ricerca in corso...",
     "searchPlacesNoResults": "Nessun luogo trovato",
     "searchPlacesError": "Ricerca non riuscita. Riprova.",
     "searchPlacesClear": "Cancella ricerca",
     "searchPlacesGoToCoordinate": "Vai a {{coordinate}}",
+    "searchPlacesGoToH3Cell": "Vai alla cella H3 {{cell}} (ris. {{resolution}})",
     "background": "Sfondo",
     "backgroundCannotReorder": "Lo sfondo non può essere riordinato",
     "hideBackground": "Nascondi sfondo",