docs(react) React widgets and useWidget hook documentation

docs/api-reference/react/deckgl.md

@@ -23,21 +23,23 @@ const App = (data) => (
 );
 ```
 
-Like any React component, `DeckGL` can accept child components. Child components are often maps (e.g. the `StaticMap` component from react-map-gl), but can be any React components.
+Like any React component, `DeckGL` can accept child components. Typical React components include:
+
+- Base maps such as the [`Map`](https://visgl.github.io/react-map-gl/docs/api-reference/map) component from `react-map-gl`, which can synchronize with deck.gl's view state.
+- [Widgets](./overview.md#using-react-wrapped-widgets), which can display and control deck.gl state.
 
 ```js
 import DeckGL from '@deck.gl/react';
-import {StaticMap} from 'react-map-gl';
+import {Map} from 'react-map-gl/maplibre';
+import 'maplibre-gl/dist/maplibre-gl.css';
 
 const App = (data) => (
   <DeckGL
     initialViewState={{longitude: -122.45, latitude: 37.78, zoom: 12}}
     controller={true}
     layers={[new ScatterplotLayer({data})]}
   >
-    <StaticMap
-      mapStyle="mapbox://styles/mapbox/dark-v9"
-      mapboxApiAccessToken={MAPBOX_ACCESS_TOKEN} />
+    <Map mapStyle="https://basemaps.cartocdn.com/gl/positron-gl-style/style.json" />
   </DeckGL>
 );
 
@@ -55,7 +57,10 @@ A [Context.Provider](https://reactjs.org/docs/context.html#contextprovider) comp
 
 - `viewport` ([Viewport](../core/viewport.md)) - the current viewport
 - `container` (DOMElement) - the DOM element containing the deck canvas
-- `eventManager` ([EventManager](https://uber-web.github.io/mjolnir.js/docs/api-reference/event-manager))
+- `eventManager` ([EventManager](https://visgl.github.io/mjolnir.js/docs/api-reference/event-manager))
+- `onViewStateChange` ([onViewStateChange](../core/deck.md#onviewstatechange)) - the view state change handler 
+- `deck` ([Deck](../core/deck.md)) - the current deck instance, if present
+- `widgets` ([Widget](../core/widget.md)[]) - the current jsx widgets, if any
 
 ```jsx
 /// Example using react-map-gl v6 controls with deck.gl
@@ -81,7 +86,7 @@ The following semantics of the standard React `children` property are considered
 It is possible to use JSX syntax to create deck.gl layers as React children of the `DeckGL` React components, instead of providing them as ES6 class instances to the `layers` prop.
 
 ```jsx
-  <DeckGL {...viewState}>
+  <DeckGL initialViewState={...viewState}>
     <LineLayer id="line-layer" data={data} />
   <DeckGL />
 ```
@@ -96,7 +101,7 @@ It is possible to use JSX syntax to create deck.gl views as React children of th
 ```jsx
   <DeckGL initialViewState={...viewState} layers={layers} >
     <MapView id="map" width="50%" controller={true} >
-      <StaticMap mapboxApiAccessToken={MAPBOX_ACCESS_TOKEN} />
+      <Map mapStyle="https://basemaps.cartocdn.com/gl/positron-gl-style/style.json" />
     </MapView>
     <FirstPersonView width="50%" x="50%" fovy={50} />
   <DeckGL />
@@ -112,11 +117,22 @@ If a certain view id is used in both JSX views and the `views` prop, the view in
 
   <DeckGL initialViewState={...viewState} layers={layers} views={views} >
     <View id="map">
-      <StaticMap mapboxApiAccessToken={MAPBOX_ACCESS_TOKEN} />
+      <Map mapStyle="https://basemaps.cartocdn.com/gl/positron-gl-style/style.json" />
     </View>
   <DeckGL />
 ```
 
+#### JSX Widgets
+
+It is possible to use JSX syntax to create deck.gl widgets as React children of the `DeckGL` React components, instead of providing them as ES6 class instances to the `widgets` props.
+
+```jsx
+  <DeckGL initialViewState={...viewState}>
+    <ZoomWidget id="zoom-widget" placement="top-right" />
+  <DeckGL />
+```
+
+Learn how to use widgets in JSX by reading [Using React-wrapped widgets](./overview.md#using-react-wrapped-widgets).
 
 #### Position Children in Views
 

docs/api-reference/react/overview.md

@@ -0,0 +1,56 @@
+# @deck.gl/react
+
+This module integrates deck.gl with React. First-time deck.gl developers may find it helpful to read [Using deck.gl with React](../../get-started/using-with-react.md) before getting started.
+
+This module contains the following:
+
+### React Components
+
+- [\<DeckGL/>](./deckgl.md)
+- Widgets in the [`@deck.gl/widgets`](../widgets/overview.md) module are re-exported as React components in this module.
+  - e.g. `import { ZoomWidget } from '@deck.gl/react';`
+
+### React Hooks
+
+- [useWidget](./use-widget.md)
+
+## Installation
+
+### Install from NPM
+
+```bash
+npm install deck.gl
+# or
+npm install @deck.gl/core @deck.gl/react
+```
+
+```jsx
+import DeckGL from '@deck.gl/react';
+
+<DeckGL initialViewState={{longitude: -122.45, latitude: 37.78, zoom: 12}}/>
+```
+
+## Using React-wrapped Widgets
+
+Here's a typical example of how to switch from using pure-js widgets in the [`@deck.gl/widgets`](../widgets/overview.md) module to their React-equivalent:
+
+```diff
+-import { ZoomWidget } from '@deck.gl/widgets';
++import { ZoomWidget } from '@deck.gl/react';
+
+-<DeckGL widgets={[new ZoomWidget({})]}>
++<DeckGL>
++  <ZoomWidget/>
+</DeckGL>
+```
+
+React props are passed to the widget:
+
+```diff
+-new ZoomWidget({ id: 'zoom', placement: 'top-right' })
++<ZoomWidget id='zoom' placement='top-right'/>
+```
+
+### Authoring Custom Widgets with React
+
+Learn how author your own custom widgets in React with the `useWidget` hook by reading the [Custom Widget Developer Guide](../../developer-guide/custom-widgets).

docs/api-reference/react/use-widget.md

@@ -0,0 +1,78 @@
+# useWidget
+
+The `useWidget` hook is used to create React wrappers for normal (non-React) deck.gl widgets, or to create custom widgets with UI rendered by React.
+
+## Usage
+
+```tsx
+// React wrapper usage
+import DeckGL, {useWidget} from '@deck.gl/react';
+import {CompassWidget as UniversalCompassWidget, type CompassWidgetProps} from '@deck.gl/react';
+
+const CompassWidget = (props: CompassWidgetProps) => {
+  const widget = useWidget(UniversalCompassWidget, props);
+  return null;
+}
+
+<DeckGL>
+  <CompassWidget/>
+</DeckGL>
+```
+
+For a custom widget, React can be used to implement the UI itself. A widget class is used to hook into deck.gl apis, and a React [`portal`](https://react.dev/reference/react-dom/createPortal) is utilized to render the widget UI along-side other widgets.
+
+```tsx
+import React, {useMemo} from 'react';
+import type {Widget} from '@deck.gl/core';
+import DeckGL, {useWidget} from '@deck.gl/react';
+import {createPortal} from 'react-dom';
+
+class MyWidget implements Widget {
+  constructor(props) {
+    this.props = { ...props };
+  }
+
+  onAdd() {
+    return this.props.element; // HTMLDivElement
+  }
+}
+
+const MyReactWidget = (props) => {
+  const element = useMemo(() => document.createElement('div'), []);
+  const widget = useWidget(MyWidget, {...props, element});
+  return createPortal(
+    <div>Hello World</div>,
+    element
+  );
+};
+
+<DeckGL>
+  <MyReactWidget/>
+</DeckGL>
+```
+
+See a full example [here](../../developer-guide/custom-widgets/react-widgets.md).
+
+## Signature
+
+```tsx
+useWidget<T extends Widget, PropsT extends {}>(
+  WidgetClass: {new (props: PropsT): T},
+  props: PropsT
+): T
+```
+
+The hook creates an [`Widget`](../core/widget.md) instance, adds it to deck.gl, and removes it upon unmount.
+
+Parameters:
+
+ - `WidgetClass`: `{new (props: PropsT): T}` - called to create an instance of the control.
+ - `props`: `PropsT` - props passed into the widget constructor on creation and `widget.setProps` on render.
+
+Returns:
+
+[`Widget`](../core/widget.md) - the widget instance of `WidgetClass`.
+
+## Source
+
+[modules/react/src/utils/use-widget.ts](https://github.com/visgl/deck.gl/blob/master/modules/react/src/utils/use-widget.ts)

docs/get-started/using-with-react.md

@@ -49,15 +49,16 @@ The vis.gl community maintains two React libraries that seamlessly work with dec
 - `react-map-gl` - a React wrapper for [Mapbox GL JS](https://docs.mapbox.com/mapbox-gl-js/guides) and [MapLibre GL JS](https://maplibre.org/maplibre-gl-js/docs/). Several integration options are discussed in [using with Mapbox](../developer-guide/base-maps/using-with-mapbox.md).
 - `@vis.gl/react-google-maps` - a React wrapper for [Google Maps JavaScript API](https://developers.google.com/maps/documentation/javascript). See [using with Google Maps](../developer-guide/base-maps/using-with-google-maps.md).
 
-## Using JSX Layers and Views
+## Using JSX Layers, Views, and Widgets
 
-It is possible to use JSX syntax to create deck.gl layers and views as React children of the `DeckGL` React components, instead of providing them as ES6 class instances to the `layers` prop. There are no performance advantages to this syntax but it can allow for a more consistent, React-like coding style.
+It is possible to use JSX syntax to create deck.gl layers, views, and widgets as React children of the `DeckGL` React components, instead of providing them as ES6 class instances to the `layers`, `views`, or `widgets` prop, respectively. There are no performance advantages to this syntax but it can allow for a more consistent, React-like coding style.
 
 ```jsx
 import React from 'react';
 import DeckGL from '@deck.gl/react';
 import {MapViewState} from '@deck.gl/core';
 import {LineLayer} from '@deck.gl/layers';
+import {ZoomWidget} from '@deck.gl/react';
 import {Map} from 'react-map-gl';
 
 const INITIAL_VIEW_STATE: MapViewState = {
@@ -83,6 +84,8 @@ function App() {
       </MapView>
 
       <FirstPersonView width="50%" x="50%" fovy={50} />
+
+      <ZoomWidget/>
     </DeckGL>
   );
 }

docs/table-of-contents.json

@@ -293,7 +293,9 @@
         "type": "category",
         "label": "@deck.gl/react",
         "items": [
-          "api-reference/react/deckgl"
+          "api-reference/react/overview",    
+          "api-reference/react/deckgl",
+          "api-reference/react/use-widget"
         ]
       },
       {

docs/whats-new.md

@@ -39,13 +39,13 @@ Release date: TBD (targeting December 2024)
 ### React Widgets
 
 deck.gl v9.0 added support for widgets, with v9.1 users can now create React components with the same level of deep deck.gl integration. 
-- All the official deck.gl widgets can now be easily wrapped into React components with the new `useWidget` hook.
-- Pre-wrapped React components for existing widget are available from the `@deck.gl/react` package. 
-- To try it out, check out our new [getting started example](https://github.com/visgl/deck.gl/tree/master/examples/get-started/react/widgets) for using widgets in React.
+- All the official deck.gl widgets can now be easily wrapped into React components with the new [`useWidget`](./api-reference/react/use-widget.md) hook.
+- Pre-wrapped React components for existing widget are available from the [`@deck.gl/react`](./api-reference/react/overview.md) package. 
+- To try it out, check out our [React getting started example](https://github.com/visgl/deck.gl/tree/master/examples/get-started/react/basic) for using widgets in React.
 
 ### Widgets Developer Guide
 
-deck.gl v9.1 provides the ability to for applications to write React component that integrate with deck.gl using the widget interface. Learn how to write such React components with our new [Custom Widgets Developer Guide](./docs/developer-guide/custom-widgets).
+deck.gl v9.1 provides the ability to for applications to write React component that integrate with deck.gl using the widget interface. Learn how to write such React components with our new [Custom Widgets Developer Guide](./developer-guide/custom-widgets).
 
 ### Aggregation layers upgrade