add(examples): react widgets get started

docs/api-reference/core/widget.md

@@ -12,7 +12,7 @@ You may find many ready-to-use widgets in the `@deck.gl/widgets` module.
 A widget is expected to implement the `Widget` interface. Here is a custom widget that shows a spinner while layers are loading:
 
 ```ts
-import {Widget} from '@deck.gl/core';
+import {Deck, Widget} from '@deck.gl/core';
 
 class LoadingIndicator implements Widget {
   element?: HTMLDivElement;
@@ -43,7 +43,9 @@ class LoadingIndicator implements Widget {
   }
 }
 
-deckgl.addWidget(new LoadingIndicator({size: 48}));
+new Deck({
+  widgets=[new LoadingIndicator({size: 48})]
+});
 ```
 
 ## Widget Interface

examples/get-started/pure-js/widgets/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "deckgl-example-pure-js-basic",
+  "name": "deckgl-example-pure-js-widgets",
   "version": "0.0.0",
   "private": true,
   "license": "MIT",

examples/get-started/react/widgets/README.md

@@ -0,0 +1,17 @@
+## Example: Use deck.gl with widgets
+
+Uses [Vite](https://vitejs.dev/) to bundle and serve files.
+
+## Usage
+
+To install dependencies:
+
+```bash
+npm install
+# or
+yarn
+```
+
+Commands:
+* `npm start` is the development target, to serve the app and hot reload.
+* `npm run build` is the production target, to create the final bundle and write to disk.

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

@@ -0,0 +1,128 @@
+import React, {useState} from 'react';
+import {createRoot} from 'react-dom/client';
+import DeckGL, {GeoJsonLayer, ArcLayer} from 'deck.gl';
+import {
+  CompassWidget,
+  ZoomWidget,
+  FullscreenWidget,
+  DarkGlassTheme,
+  LightGlassTheme
+} from '@deck.gl/widgets';
+import '@deck.gl/widgets/stylesheet.css';
+import {createPortal} from 'react-dom';
+
+/* global window */
+const prefersDarkScheme = window.matchMedia('(prefers-color-scheme: dark)');
+const widgetTheme = prefersDarkScheme.matches ? DarkGlassTheme : LightGlassTheme;
+
+// source: Natural Earth http://www.naturalearthdata.com/ via geojson.xyz
+const COUNTRIES =
+  'https://d2ad6b4ur7yvpq.cloudfront.net/naturalearth-3.3.0/ne_50m_admin_0_scale_rank.geojson'; //eslint-disable-line
+const AIR_PORTS =
+  'https://d2ad6b4ur7yvpq.cloudfront.net/naturalearth-3.3.0/ne_10m_airports.geojson';
+
+const INITIAL_VIEW_STATE = {
+  latitude: 51.47,
+  longitude: 0.45,
+  zoom: 4,
+  bearing: 0,
+  pitch: 30
+};
+
+function Root() {
+  const [widgetContainer, setWidgetContainer] = useState();
+
+  class ReactWidget {
+    constructor(props) {
+      this.id = props.id || 'react';
+      this.placement = props.placement || 'top-left';
+      this.viewId = props.viewId;
+      this.props = props;
+    }
+
+    onAdd() {
+      const el = document.createElement('div');
+      setWidgetContainer(el);
+      return el;
+    }
+
+    onRemove() {
+      setWidgetContainer(undefined);
+    }
+
+    setProps(props) {
+      this.props = props;
+    }
+  }
+
+  const reactWidget = new ReactWidget({});
+
+  const onClick = () => {
+    // eslint-disable-next-line
+    alert('React widget!');
+  };
+
+  const widget = (
+    <div className="deck-widget" style={widgetTheme}>
+      <div className="deck-widget-button">
+        <button className="deck-widget-icon-button" onClick={onClick}>
+          <div style={{color: 'var(--button-icon-idle)'}}>i</div>
+        </button>
+      </div>
+    </div>
+  );
+
+  return (
+    <>
+      {widgetContainer && createPortal(widget, widgetContainer)}
+      <DeckGL
+        controller={true}
+        initialViewState={INITIAL_VIEW_STATE}
+        widgets={[
+          new ZoomWidget({style: widgetTheme}),
+          new CompassWidget({style: widgetTheme}),
+          new FullscreenWidget({style: widgetTheme}),
+          reactWidget
+        ]}
+        layers={[
+          new GeoJsonLayer({
+            id: 'base-map',
+            data: COUNTRIES,
+            // Styles
+            stroked: true,
+            filled: true,
+            lineWidthMinPixels: 2,
+            opacity: 0.4,
+            getLineColor: [60, 60, 60],
+            getFillColor: [200, 200, 200]
+          }),
+          new GeoJsonLayer({
+            id: 'airports',
+            data: AIR_PORTS,
+            // Styles
+            filled: true,
+            pointRadiusMinPixels: 2,
+            pointRadiusScale: 2000,
+            getPointRadius: f => 11 - f.properties.scalerank,
+            getFillColor: [200, 0, 80, 180]
+          }),
+          new ArcLayer({
+            id: 'arcs',
+            data: AIR_PORTS,
+            dataTransform: d => d.features.filter(f => f.properties.scalerank < 4),
+            // Styles
+            getSourcePosition: f => [-0.4531566, 51.4709959], // London
+            getTargetPosition: f => f.geometry.coordinates,
+            getSourceColor: [0, 128, 200],
+            getTargetColor: [200, 0, 80],
+            getWidth: 1
+          })
+        ]}
+      />
+    </>
+  );
+}
+
+/* global document */
+const container = document.body.appendChild(document.createElement('div'));
+createRoot(container).render(<Root />);

examples/get-started/react/widgets/index.html

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <title>deck.gl Example</title>
+    <style>
+      body {margin: 0; width: 100vw; height: 100vh; overflow: hidden;}
+    </style>
+  </head>
+  <body></body>
+  <script type="module" src="app.jsx"></script>
+</html>

examples/get-started/react/widgets/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "deckgl-example-react-widgets",
+  "version": "0.0.0",
+  "private": true,
+  "license": "MIT",
+  "scripts": {
+    "start": "vite --open",
+    "start-local": "vite --config ../../../vite.config.local.mjs",
+    "build": "vite build"
+  },
+  "dependencies": {
+    "deck.gl": "^9.0.0",
+    "@deck.gl/widgets": "^9.0.0",
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0"
+  },
+  "devDependencies": {
+    "vite": "^4.0.0"
+  }
+}