Add Zoom and Compass widgets

.eslintrc.js

@@ -109,6 +109,13 @@ module.exports = getESLintConfig({
           'import/named': 0,
           'no-new': 0
         }
+      },
+      {
+        files: ['modules/widgets/**/*.tsx'],
+        rules: {
+          // For widgets module. Disable React-style JSX linting since they conflict with Preact JSX.
+          'react/react-in-jsx-scope': 0
+        }
       }
     ],
 

babel.config.js

@@ -13,6 +13,14 @@ module.exports = getBabelConfig({
           patterns: ['**/*.glsl.js', '**/*.glsl.ts']
         }
       ]
+    ],
+    overrides: [
+      {
+        include: './modules/widgets/**/*.{ts,tsx}',
+        // Parse preact-style JSX in @deck.gl/widgets.
+        presets: [['@babel/typescript', {jsxPragma: 'h'}]],
+        plugins: [['@babel/plugin-transform-react-jsx', {pragma: 'h'}]]
+      }
     ]
   }
 });

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

@@ -0,0 +1,45 @@
+# FullscreenWidget
+
+## Props
+
+### `id` (String)
+
+Default: `'fullscreen'`
+
+Unique identifier of the widget.
+
+### `viewId` (String, optional)
+
+Default: `null`
+
+The view id that this widget is being attached to. If assigned, this widget will only respond to events occured inside the specific view that matches this id.
+
+### `placement` (String, optional)
+
+Default: `'top-left'`
+
+Widget position within the view relatitive to the map container. Valid options are `top-left`, `top-right`, `bottom-left`, `bottom-right`, or `fill`.
+
+### `container` (HTMLElement, optional)
+
+Default: `undefined`
+
+A [compatible DOM element](https://developer.mozilla.org/en-US/docs/Web/API/Element/requestFullScreen#Compatible_elements) which should be made full screen. By default, the map container element will be made full screen.
+
+### `label` (String, optional)
+
+Hovering a mouse over the widget will display the label as a tooltip.
+
+Default: `'Toggle Fullscreen'`
+
+### `style` (Object, optional)
+
+Default: `{}`
+
+Additional CSS styles for the canvas.
+
+### `className` (String, optional)
+
+Default: `undefined`
+
+Class name to attach to the widget element. The element has the default class name of `deck-widget deck-fullscreen-widget`.

docs/api-reference/widgets/overview.md

@@ -18,18 +18,79 @@ npm install @deck.gl/core @deck.gl/widgets
 
 ```js
 import {FullscreenWidget} from '@deck.gl/widgets';
+import '@deck.gl/widgets/stylesheet.css';
+
 new FullscreenWidget({});
 ```
 
 ### Include the Standalone Bundle
 
 ```html
 <script src="https://unpkg.com/deck.gl@^8.10.0/dist.min.js"></script>
+<link src="https://unpkg.com/deck.gl@^8.10.0/widgets/stylesheet.css" rel='stylesheet' />
 <!-- or -->
 <script src="https://unpkg.com/@deck.gl/core@^8.10.0/dist.min.js"></script>
 <script src="https://unpkg.com/@deck.gl/widgets@^8.10.0/dist.min.js"></script>
+<link src="https://unpkg.com/deck.gl@^8.10.0/widgets/stylesheet.css" rel='stylesheet' />
 ```
 
 ```js
 new deck.FullscreenWidget({});
-```
+```
+
+## CSS Themeing
+
+Define CSS variables to customize the appearance of widgets.
+
+Apply to all wigdets with the `.deckgl-widget` selector:
+
+```css
+.deckgl-widget {
+    --button-size: 48px;
+}
+```
+
+Apply to one widget type with `.deckgl-widget-[type]` selector:
+
+```css
+.deckgl-widget-fullscreen {
+    --button-size: 48px;
+}
+```
+
+Apply to one instance of a widget with inline styles:
+
+```js
+new FullscreenWidget({ style: {'--button-size': '48px'}})
+```
+
+Apply a custom class to a widget:
+
+```css
+.my-class {
+    --button-size: 48px;
+}
+```
+```js
+new FullscreenWidget({ className: 'my-class'})
+```
+
+### Size
+
+| Name | Type | Default |
+| ---- | ---- | ------- |
+| `--button-size` | [Dimension](https://developer.mozilla.org/en-US/docs/Web/CSS/dimension) | `28px` |
+| `--button-border-radius` | [Dimension](https://developer.mozilla.org/en-US/docs/Web/CSS/dimension) | `12px` |
+| `--wdgt-margin` | [Dimension](https://developer.mozilla.org/en-US/docs/Web/CSS/dimension) | `12px` |
+
+### Color
+
+| Name | Type | Default |
+| ---- | ---- | ------- |
+| `--button-background` | [Color](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) | `#fff` |
+| `--button-stroke` | [Color](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) | `rgba(255, 255, 255, 0.3)` |
+| `--button-inner-stroke` | [Border](https://developer.mozilla.org/en-US/docs/Web/CSS/border) | `unset` |
+| `--button-shadow` | [Box Shadow](https://developer.mozilla.org/en-US/docs/Web/CSS/box-shadow) | `0px 0px 8px 0px rgba(0, 0, 0, 0.25)` |
+| `--button-backdrop-filter` | [Backdrop Filter](https://developer.mozilla.org/en-US/docs/Web/CSS/backdrop-filter) | `unset` |
+| `--button-icon-idle` | [Color](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) | `rgba(97, 97, 102, 1)`
+| `--button-icon-hover` | [Color](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) | `rgba(24, 24, 26, 1)`

examples/get-started/pure-js/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/pure-js/widgets/app.js

@@ -0,0 +1,84 @@
+import {Deck} from '@deck.gl/core';
+import {GeoJsonLayer, ArcLayer} from '@deck.gl/layers';
+import {
+  CompassWidget,
+  ZoomWidget,
+  FullscreenWidget,
+  DarkGlassTheme,
+  LightGlassTheme
+} from '@deck.gl/widgets';
+import '@deck.gl/widgets/stylesheet.css';
+import {luma} from '@luma.gl/core';
+import {WebGLDevice} from '@luma.gl/webgl';
+
+luma.registerDevices([WebGLDevice]);
+
+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
+};
+
+new Deck({
+  initialViewState: INITIAL_VIEW_STATE,
+  controller: true,
+  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],
+      // Interactive props
+      pickable: true,
+      autoHighlight: true,
+      onClick: info =>
+        // eslint-disable-next-line
+        info.object && alert(`${info.object.properties.name} (${info.object.properties.abbrev})`)
+    }),
+    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
+    })
+  ],
+  widgets: [
+    new ZoomWidget({style: widgetTheme}),
+    new CompassWidget({style: widgetTheme}),
+
+    new FullscreenWidget({}),
+    new FullscreenWidget({id: 'themed', style: widgetTheme}),
+    new FullscreenWidget({id: 'purple', className: 'purple'})
+  ]
+});

examples/get-started/pure-js/widgets/index.html

@@ -0,0 +1,32 @@
+<!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;
+      }
+
+      @media screen and (max-width: 600px) {
+        .deckgl-widget {
+          /* mobile */
+          --button-size: 48px;
+          --button-corner-radius: 12px;
+        }
+      }
+
+      .purple {
+        --button-background: hsl(240, 40%, 40%);
+        --button-stroke: hsla(240, 40%, 40%, 0.3);
+        --button-icon-hover: rgb(236, 236, 236);
+        --button-icon-idle: rgb(174, 174, 202);
+      }
+    </style>
+  </head>
+  <body></body>
+  <script type="module" src="app.js"></script>
+</html>

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

@@ -0,0 +1,21 @@
+{
+  "name": "deckgl-example-pure-js-basic",
+  "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/core": "^8.8.0",
+    "@deck.gl/layers": "^8.8.0",
+    "@deck.gl/widgets": "8.10.0-alpha.2",
+    "@luma.gl/core": "^8.6.0-alpha.1",
+    "@luma.gl/webgl": "^8.5.20"
+  },
+  "devDependencies": {
+    "vite": "^4.0.0"
+  }
+}

modules/widgets/package.json

@@ -30,7 +30,8 @@
     "prepublishOnly": "npm run build-bundle && npm run build-bundle -- --env=dev"
   },
   "dependencies": {
-    "@babel/runtime": "^7.0.0"
+    "@babel/runtime": "^7.0.0",
+    "preact": "^10.17.0"
   },
   "peerDependencies": {
     "@deck.gl/core": "^8.0.0"