feat(react) Support for JSX Widgets in React

examples/get-started/react/basic/app.jsx

@@ -4,7 +4,8 @@
 
 import React from 'react';
 import {createRoot} from 'react-dom/client';
-import DeckGL, {GeoJsonLayer, ArcLayer} from 'deck.gl';
+import DeckGL, {GeoJsonLayer, ArcLayer, CompassWidget} from 'deck.gl';
+import '@deck.gl/widgets/stylesheet.css';
 
 // source: Natural Earth http://www.naturalearthdata.com/ via geojson.xyz
 const COUNTRIES =
@@ -62,6 +63,7 @@ function Root() {
         getTargetColor={[200, 0, 80]}
         getWidth={1}
       />
+      <CompassWidget />
     </DeckGL>
   );
 }

modules/react/package.json

@@ -35,6 +35,7 @@
   "scripts": {},
   "peerDependencies": {
     "@deck.gl/core": "^9.1.0-beta",
+    "@deck.gl/widgets": "^9.1.0-beta",
     "react": ">=16.3.0",
     "react-dom": ">=16.3.0"
   },

modules/react/src/deckgl.ts

@@ -11,7 +11,7 @@ import extractJSXLayers, {DeckGLRenderCallback} from './utils/extract-jsx-layers
 import positionChildrenUnderViews from './utils/position-children-under-views';
 import extractStyles from './utils/extract-styles';
 
-import type {DeckGLContextValue} from './utils/position-children-under-views';
+import type {DeckGLContextValue} from './utils/deckgl-context';
 import type {DeckProps, View, Viewport} from '@deck.gl/core';
 
 export type ViewOrViews = View | View[] | null;

modules/react/src/index.ts

@@ -5,6 +5,12 @@
 export {default as DeckGL} from './deckgl';
 export {default} from './deckgl';
 
+// Widgets
+export {CompassWidget} from './widgets/compass-widget';
+export {FullscreenWidget} from './widgets/fullscreen-widget';
+export {ZoomWidget} from './widgets/zoom-widget';
+export {default as useWidget} from './utils/use-widget';
+
 // Types
-export type {DeckGLContextValue} from './utils/position-children-under-views';
+export type {DeckGLContextValue} from './utils/deckgl-context';
 export type {DeckGLRef, DeckGLProps} from './deckgl';

modules/react/src/utils/deckgl-context.ts

@@ -0,0 +1,15 @@
+import {createContext} from 'react';
+import type {EventManager} from 'mjolnir.js';
+import type {Deck, DeckProps, Viewport, Widget} from '@deck.gl/core';
+
+export type DeckGLContextValue = {
+  viewport: Viewport;
+  container: HTMLElement;
+  eventManager: EventManager;
+  onViewStateChange: DeckProps['onViewStateChange'];
+  deck?: Deck<any>;
+  widgets?: Widget[];
+};
+
+// @ts-ignore
+export const DeckGlContext = createContext<DeckGLContextValue>();

modules/react/src/utils/position-children-under-views.ts

@@ -9,22 +9,15 @@ import {inheritsFrom} from './inherits-from';
 import evaluateChildren, {isComponent} from './evaluate-children';
 
 import type {ViewOrViews} from '../deckgl';
-import type {Deck, DeckProps, Viewport} from '@deck.gl/core';
-import type {EventManager} from 'mjolnir.js';
-
-export type DeckGLContextValue = {
-  viewport: Viewport;
-  container: HTMLElement;
-  eventManager: EventManager;
-  onViewStateChange: DeckProps['onViewStateChange'];
-};
+import type {Deck, Viewport} from '@deck.gl/core';
+import {DeckGlContext, type DeckGLContextValue} from './deckgl-context';
 
 // Iterate over views and reposition children associated with views
 // TODO - Can we supply a similar function for the non-React case?
 export default function positionChildrenUnderViews<ViewsT extends ViewOrViews>({
   children,
   deck,
-  ContextProvider
+  ContextProvider = DeckGlContext.Provider
 }: {
   children: React.ReactNode[];
   deck?: Deck<ViewsT>;
@@ -103,6 +96,7 @@ export default function positionChildrenUnderViews<ViewsT extends ViewOrViews>({
 
     if (ContextProvider) {
       const contextValue: DeckGLContextValue = {
+        deck,
         viewport,
         // @ts-expect-error accessing protected property
         container: deck.canvas.offsetParent,
@@ -112,7 +106,8 @@ export default function positionChildrenUnderViews<ViewsT extends ViewOrViews>({
           params.viewId = viewId;
           // @ts-expect-error accessing protected method
           deck._onViewStateChange(params);
-        }
+        },
+        widgets: []
       };
       return createElement(ContextProvider, {key, value: contextValue}, viewElement);
     }

modules/react/src/utils/use-widget.ts

@@ -0,0 +1,40 @@
+import {useContext, useMemo, useEffect} from 'react';
+import {DeckGlContext} from './deckgl-context';
+import {log, type Widget, _deepEqual as deepEqual} from '@deck.gl/core';
+
+function useWidget<T extends Widget, PropsT extends {}>(
+  WidgetClass: {new (props: PropsT): T},
+  props: PropsT
+): T {
+  const context = useContext(DeckGlContext);
+  const {widgets, deck} = context;
+  useEffect(() => {
+    // warn if the user supplied a vanilla widget, since it will be ignored
+    // NOTE: This effect runs once per widget. Context widgets and deck widget props are synced after first effect runs.
+    const internalWidgets = deck?.props.widgets;
+    if (widgets?.length && internalWidgets && !deepEqual(deck?.props.widgets, widgets, 1)) {
+      log.warn('"widgets" prop will be ignored because React widgets are in use.')();
+    }
+
+    return () => {
+      // Remove widget from context when it is unmounted
+      const index = widgets?.indexOf(widget);
+      if (index && index !== -1) {
+        widgets?.splice(index, 1);
+        deck?.setProps({widgets});
+      }
+    };
+  }, []);
+  const widget = useMemo(() => new WidgetClass(props), [WidgetClass]);
+
+  widgets?.push(widget);
+  widget.setProps(props);
+
+  useEffect(() => {
+    deck?.setProps({widgets});
+  }, [widgets]);
+
+  return widget;
+}
+
+export default useWidget;

modules/react/src/widgets/compass-widget.tsx

@@ -0,0 +1,8 @@
+import {CompassWidget as VanillaCompassWidget} from '@deck.gl/widgets';
+import type {CompassWidgetProps} from '@deck.gl/widgets';
+import useWidget from '../utils/use-widget';
+
+export const CompassWidget = (props: CompassWidgetProps = {}) => {
+  const widget = useWidget(VanillaCompassWidget, props);
+  return null;
+};

modules/react/src/widgets/fullscreen-widget.tsx

@@ -0,0 +1,8 @@
+import {FullscreenWidget as VanillaFullscreenWidget} from '@deck.gl/widgets';
+import type {FullscreenWidgetProps} from '@deck.gl/widgets';
+import useWidget from '../utils/use-widget';
+
+export const FullscreenWidget = (props: FullscreenWidgetProps = {}) => {
+  const widget = useWidget(VanillaFullscreenWidget, props);
+  return null;
+};

modules/react/src/widgets/zoom-widget.tsx

@@ -0,0 +1,8 @@
+import {ZoomWidget as VanillaZoomWidget} from '@deck.gl/widgets';
+import type {ZoomWidgetProps} from '@deck.gl/widgets';
+import useWidget from '../utils/use-widget';
+
+export const ZoomWidget = (props: ZoomWidgetProps = {}) => {
+  const widget = useWidget(VanillaZoomWidget, props);
+  return null;
+};

modules/react/tsconfig.json

@@ -8,6 +8,7 @@
     "outDir": "dist"
   },
   "references": [
-    {"path": "../core"}
+    {"path": "../core"},
+    {"path": "../widgets"}
   ]
 }

modules/widgets/src/compass-widget.tsx

@@ -14,7 +14,7 @@ import {
 import type {Deck, Viewport, Widget, WidgetPlacement} from '@deck.gl/core';
 import {render} from 'preact';
 
-interface CompassWidgetProps {
+export interface CompassWidgetProps {
   id?: string;
   placement?: WidgetPlacement;
   /**

modules/widgets/src/fullscreen-widget.tsx

@@ -12,7 +12,7 @@ import type {Deck, Widget, WidgetPlacement} from '@deck.gl/core';
 import {render} from 'preact';
 import {IconButton} from './components';
 
-interface FullscreenWidgetProps {
+export interface FullscreenWidgetProps {
   id?: string;
   placement?: WidgetPlacement;
   /**

modules/widgets/src/index.ts

@@ -6,4 +6,8 @@ export {FullscreenWidget} from './fullscreen-widget';
 export {CompassWidget} from './compass-widget';
 export {ZoomWidget} from './zoom-widget';
 
+export type {FullscreenWidgetProps} from './fullscreen-widget';
+export type {CompassWidgetProps} from './compass-widget';
+export type {ZoomWidgetProps} from './zoom-widget';
+
 export * from './themes';

modules/widgets/src/zoom-widget.tsx

@@ -13,7 +13,7 @@ import type {Deck, Viewport, Widget, WidgetPlacement} from '@deck.gl/core';
 import {render} from 'preact';
 import {ButtonGroup, GroupedIconButton} from './components';
 
-interface ZoomWidgetProps {
+export interface ZoomWidgetProps {
   id?: string;
   placement?: WidgetPlacement;
   /**