feat(react) Support for JSX Widgets in React

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

@@ -5,6 +5,9 @@
 import React from 'react';
 import {createRoot} from 'react-dom/client';
 import DeckGL, {GeoJsonLayer, ArcLayer} from 'deck.gl';
+import {CompassWidget, ZoomWidget} from '@deck.gl/react';
+import {FullscreenWidget} from '@deck.gl/widgets';
+import '@deck.gl/widgets/stylesheet.css';
 
 // source: Natural Earth http://www.naturalearthdata.com/ via geojson.xyz
 const COUNTRIES =
@@ -29,7 +32,13 @@
   };
 
   return (
-    <DeckGL controller={true} initialViewState={INITIAL_VIEW_STATE}>
+    <DeckGL 
+      controller={true} 
+      initialViewState={INITIAL_VIEW_STATE} 
+      // widgets={[new FullscreenWidget({})]}
+    >
+      <CompassWidget />
+      <ZoomWidget orientation="horizontal" />
       <GeoJsonLayer
         id="base-map"
         data={COUNTRIES}

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,11 @@
 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';
+
 // 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,32 @@
+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 prop, since it will be ignored
+    // NOTE: effect runs once per widget after the first render
+    // TODO: this doesn't work since the widgets override the deck prop. Can't tell which are user set.
+    // if (!deepEqual(deck?.props.widgets, widgets, 1)) {
+    if (deck?.props.widgets.length !== 0) {
+      log.warn('Detected deck "widgets" prop used simultaneously with React widgets. Vanilla widgets will be ignored.')();
+    }
+  }, []);
+  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

@@ -7,7 +7,7 @@ import {FlyToInterpolator, WebMercatorViewport, _GlobeViewport} from '@deck.gl/c
 import type {Deck, Viewport, Widget, WidgetPlacement} from '@deck.gl/core';
 import {render} from 'preact';
 
-interface CompassWidgetProps {
+export interface CompassWidgetProps {
   id?: string;
   placement?: WidgetPlacement;
   /**
@@ -45,10 +45,13 @@ export class CompassWidget implements Widget<CompassWidgetProps> {
     this.id = props.id || 'compass';
     this.viewId = props.viewId || null;
     this.placement = props.placement || 'top-left';
-    props.transitionDuration = props.transitionDuration || 200;
-    props.label = props.label || 'Compass';
-    props.style = props.style || {};
-    this.props = props;
+
+    this.props = {
+      ...props,
+      transitionDuration: props.transitionDuration || 200,
+      label: props.label || 'Compass',
+      style: props.style || {}
+    };
   }
 
   setProps(props: Partial<CompassWidgetProps>) {

modules/widgets/src/fullscreen-widget.tsx

@@ -8,7 +8,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;
   /**
@@ -48,10 +48,13 @@ export class FullscreenWidget implements Widget<FullscreenWidgetProps> {
   constructor(props: FullscreenWidgetProps) {
     this.id = props.id || 'fullscreen';
     this.placement = props.placement || 'top-left';
-    props.enterLabel = props.enterLabel || 'Enter Fullscreen';
-    props.exitLabel = props.exitLabel || 'Exit Fullscreen';
-    props.style = props.style || {};
-    this.props = props;
+
+    this.props = {
+      ...props,
+      enterLabel: props.enterLabel || 'Enter Fullscreen',
+      exitLabel: props.exitLabel || 'Exit Fullscreen',
+      style: props.style || {}
+    };
   }
 
   onAdd({deck}: {deck: Deck<any>}): HTMLDivElement {

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

@@ -8,7 +8,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;
   /**
@@ -56,11 +56,14 @@ export class ZoomWidget implements Widget<ZoomWidgetProps> {
     this.viewId = props.viewId || null;
     this.placement = props.placement || 'top-left';
     this.orientation = props.orientation || 'vertical';
-    props.transitionDuration = props.transitionDuration || 200;
-    props.zoomInLabel = props.zoomInLabel || 'Zoom In';
-    props.zoomOutLabel = props.zoomOutLabel || 'Zoom Out';
-    props.style = props.style || {};
-    this.props = props;
+
+    this.props = {
+      ...props,
+      transitionDuration: props.transitionDuration || 200,
+      zoomInLabel: props.zoomInLabel || 'Zoom In',
+      zoomOutLabel: props.zoomOutLabel || 'Zoom Out',
+      style: props.style || {}
+    };
   }
 
   onAdd({deck}: {deck: Deck<any>}): HTMLDivElement {