feat(widgets): GeocoderWidget and experimental Geocoders (#9610)

Author: ibgreen-openai

docs/api-reference/widgets/geocoder-widget.md

@@ -0,0 +1,45 @@
+# GeocoderWidget
+
+The GeocoderWidget helps the user find positions on the map.
+
+This widget provides an input box for entering an address or a pair of coordinates.
+
+The user types an address or coordinates into the text field and press **Go** to move the map.  The most recent addresses that have been successfully located are  presented in a drop-down menu. 
+
+Addresses that return a valid location are stored in browser local storage (up to five entries). They will appear in the drop-down for quick re-use during later visits.
+
+## Usage
+
+```ts
+import {GeocoderWidget} from '@deck.gl/widgets';
+import {Deck} from '@deck.gl/core';
+
+new Deck({
+  widgets: [new GeocoderWidget()]
+});
+```
+
+## Props
+
+The `GeocoderWidget` shares the base properties listed on the [widget overview page](./overview.md). Additional options are listed below.
+
+#### `geocoder` (string, optional) {#geocoder}
+
+Default: `'coordinates'`
+
+Which geocoding service to use. Supported values are `'coordinates'`, `'google'`, `'mapbox'`, `'opencage'`, or `'custom'`.
+
+#### `apiKey` (string, optional) {#apiKey}
+
+Required if `geocoder` is set to a third party provider. For quick testing, applications can use the  `coordinates` geocode does not require an api key.
+
+#### `customGeocoder` (optional) {#customGeocoder}
+
+Only used when `geocoder` is `'custom'`. A function that receives the entered text and an API key, and resolves to a `{longitude, latitude}` object when successful.
+
+#### `_geolocation` (optional) {#geolocation}
+
+In addition to addresses / coordinates, one position of obvious interest is the user's own current position. This experimental option adds a `current` menu item that calls the browser's geolocation API and navigates to the user's current position. Note that this requires the user to enable geolocation in the browser.
+
+If `props._geolocation` **Current position** from the drop-down uses `navigator.geolocation` to center the map. The option is hidden if the browser does not provide the Geolocation API or the user denies access.
+

docs/api-reference/widgets/geolocate-widget.md

@@ -14,7 +14,7 @@ This module contains the following widgets:
 
 - [CompassWidget](./compass-widget.md)
 <!-- - [ScaleWidget](./scale-widget.md) -->
-<!-- - [GeolocateWidget](./geolocate-widget.md) -->
+<!-- - [GeocoderWidget](./geocoder-widget.md) -->
 
 ### Utility Widgets
 

docs/api-reference/widgets/overview.md

@@ -315,15 +315,19 @@
         "items": [
           "api-reference/widgets/overview",
           "api-reference/widgets/styling",
-          "api-reference/widgets/zoom-widget",
           "api-reference/widgets/compass-widget",
+          "api-reference/widgets/fps-widget",
           "api-reference/widgets/fullscreen-widget",
+          "api-reference/widgets/gimbal-widget",
+          "api-reference/widgets/info-widget",
+          "api-reference/widgets/loading-widget",
           "api-reference/widgets/reset-view-widget",
+          "api-reference/widgets/scale-widget",
           "api-reference/widgets/screenshot-widget",
-          "api-reference/widgets/fps-widget",
-          "api-reference/widgets/loading-widget",
+          "api-reference/widgets/splitter-widget",
           "api-reference/widgets/theme-widget",
-          "api-reference/widgets/info-widget"
+          "api-reference/widgets/timeline-widget",
+          "api-reference/widgets/zoom-widget"
         ]
       }
     ]

docs/table-of-contents.json

@@ -12,14 +12,14 @@ Target release date: Q2, 2025
 
 - [ResetViewWidget](./api-reference/widgets/reset-view-widget.md)
 - [ScaleWidget](./api-reference/widgets/scale-widget.md)
-- [GeolocateWidget](./api-reference/widgets/geolocate-widget.md)
+- [GeocoderWidget](./api-reference/widgets/geocoder-widget.md)
 - [ScreenshotWidget](./api-reference/widgets/screenshot-widget.md)
 - [LoadingWidget](./api-reference/widgets/loading-widget.md)
 - [ThemeWidget](./api-reference/widgets/theme-widget.md)
 - [InfoWidget](./api-reference/widgets/info-widget.md)
 - [SplitterWidget](./api-reference/widgets/splitter-widget.md)
 
-Also, pre-wrapped React components for the new deck.gl widgets are available via the [`@deck.gl/react`](./api-reference/react/overview.md) package.
+Pre-wrapped React components for the new deck.gl widgets are available via the [`@deck.gl/react`](./api-reference/react/overview.md) package.
 
 ### Core
 

docs/whats-new.md

@@ -9,7 +9,7 @@ export {default} from './deckgl';
 export {CompassWidget} from './widgets/compass-widget';
 export {FullscreenWidget} from './widgets/fullscreen-widget';
 export {ZoomWidget} from './widgets/zoom-widget';
-export {GeolocateWidget as _GeolocateWidget} from './widgets/geolocate-widget';
+export {GeocoderWidget as _GeocoderWidget} from './widgets/geocoder-widget';
 export {InfoWidget as _InfoWidget} from './widgets/info-widget';
 export {ContextMenuWidget as _ContextMenuWidget} from './widgets/context-menu-widget';
 export {LoadingWidget as _LoadingWidget} from './widgets/loading-widget';

modules/react/src/index.ts

@@ -0,0 +1,15 @@
+// deck.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {_GeocoderWidget} from '@deck.gl/widgets';
+import type {GeocoderWidgetProps} from '@deck.gl/widgets';
+import {useWidget} from '../utils/use-widget';
+
+/**
+ * React wrapper for the GeocoderWidget.
+ */
+export const GeocoderWidget = (props: GeocoderWidgetProps = {}) => {
+  useWidget(_GeocoderWidget, props);
+  return null;
+};