feat(widgets): New LoadingWidget

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

@@ -0,0 +1,37 @@
+# LoadingWidget
+
+This widget shows a spinning indicator while any deck.gl layers are loading data.
+
+## Props
+
+#### `id` (string, optional) {#id}
+
+Default: `'loading'`
+
+The `id` must be unique among all your widgets at a given time. 
+
+Note: It is necessary to set `id` explicitly if you have more than once instance of the same widget.
+
+#### `placement` (string, optional) {#placement}
+
+Default: `'top-left'`
+
+Widget position within the view relative to the map container. Valid options are `top-left`, `top-right`, `bottom-left`, `bottom-right`, or `fill`.
+
+#### `label` (string, optional) {#label}
+
+Tooltip message displayed while hovering a mouse over the widget.
+
+Default: `'Loading data'`
+
+#### `style` (object, optional) {#style}
+
+Default: `{}`
+
+Additional CSS styles for the widget. camelCase CSS properties (e.g. `backgroundColor`) and kabab-case CSS variables are accepted (e.g. `--button-size`).
+
+#### `className` (string, optional) {#classname}
+
+Default: `undefined`
+
+Class name to attach to the widget element. The element has the default class name of `deck-widget deck-loading-widget`.

docs/table-of-contents.json

@@ -315,7 +315,9 @@
           "api-reference/widgets/overview",
           "api-reference/widgets/zoom-widget",
           "api-reference/widgets/compass-widget",
-          "api-reference/widgets/fullscreen-widget"
+          "api-reference/widgets/fullscreen-widget",
+          "api-reference/widgets/reset-view-widget",
+          "api-reference/widgets/loading-widget"
         ]
       }
     ]

examples/get-started/pure-js/widgets/app.js

@@ -10,6 +10,7 @@ import {
   FullscreenWidget,
   ScreenshotWidget,
   ResetViewWidget,
+  LoadingWidget,
   DarkGlassTheme,
   LightGlassTheme
 } from '@deck.gl/widgets';
@@ -81,6 +82,7 @@ new Deck({
     new CompassWidget({style: widgetTheme}),
     new FullscreenWidget({style: widgetTheme}),
     new ScreenshotWidget({style: widgetTheme}),
-    new ResetViewWidget({style: widgetTheme})
+    new ResetViewWidget({style: widgetTheme}),
+    new LoadingWidget({style: widgetTheme})
   ]
 });

modules/widgets/src/index.ts

@@ -7,12 +7,14 @@ export {CompassWidget} from './compass-widget';
 export {ZoomWidget} from './zoom-widget';
 export {ScreenshotWidget} from './screenshot-widget';
 export {ResetViewWidget} from './reset-view-widget';
+export {LoadingWidget} from './loading-widget';
 
 export type {FullscreenWidgetProps} from './fullscreen-widget';
 export type {CompassWidgetProps} from './compass-widget';
 export type {ZoomWidgetProps} from './zoom-widget';
 export type {ScreenshotWidgetProps} from './screenshot-widget';
 export type {ResetViewWidgetProps} from './reset-view-widget';
+export type {LoadingWidgetProps} from './loading-widget';
 
 export type {WidgetImplProps} from './widget-impl';
 export {WidgetImpl as _WidgetImpl} from './widget-impl';

modules/widgets/src/loading-widget.tsx

@@ -0,0 +1,69 @@
+// deck.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+/* global document */
+import type {WidgetPlacement, Layer} from '@deck.gl/core';
+import {render} from 'preact';
+import {WidgetImpl, WidgetImplProps} from './widget-impl';
+import {IconButton} from './components';
+
+/** Properties for the LoadingWidget */
+export type LoadingWidgetProps = WidgetImplProps & {
+  /** Widget positioning within the view. Default 'top-left'. */
+  placement?: WidgetPlacement;
+  /** Tooltip message when loading */
+  label?: string;
+};
+
+/**
+ * A non-interactive widget that shows a loading spinner if any layers are loading data
+ */
+export class LoadingWidget extends WidgetImpl<LoadingWidgetProps> {
+  static defaultProps: Required<LoadingWidgetProps> = {
+    ...WidgetImpl.defaultProps,
+    id: 'loading',
+    placement: 'top-left',
+    label: 'Loading layer data'
+  };
+
+  className = 'deck-widget-loading';
+  placement: WidgetPlacement = 'top-left';
+  loading = true;
+
+  constructor(props: LoadingWidgetProps = {}) {
+    super({...LoadingWidget.defaultProps, ...props});
+    this.placement = props.placement ?? this.placement;
+  }
+
+  setProps(props: Partial<LoadingWidgetProps>) {
+    this.placement = props.placement ?? this.placement;
+    super.setProps(props);
+  }
+
+  onRenderHTML() {
+    const element = this.element;
+    if (!element) return;
+    render(
+      // TODO(ibgreen) - this should not be a button, but styling is so nested that it is easier to reuse this component.
+      this.loading && <IconButton
+        className="deck-widget-spinner-icon"
+        label={this.props.label}
+        onClick={this.handleClick.bind(this)}
+      />,
+      element
+    );
+  }
+
+  onRedraw({layers}: {layers: Layer[]}): void {
+    const loading = layers.some(layer => !layer.isLoaded);
+    if (loading !== this.loading) {
+      this.loading = loading;
+      this.onRenderHTML();
+    }
+  }
+
+  // TODO(ibgreen) - this should not be a button, see above.
+  handleClick() {
+  }
+}

modules/widgets/src/stylesheet.css

@@ -116,6 +116,16 @@
   );
 }
 
+@keyframes spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+.deck-widget.deck-widget-loading button.deck-widget-spinner-icon .deck-widget-icon {
+  animation: spin 1s linear infinite;
+}
+
 .deck-pseudo-fullscreen {
   height: 100% !important;
   left: 0 !important;
@@ -171,3 +181,8 @@
   );
 }
 
+.deck-widget-spinner-icon {
+  --deck-widget-icon-loading: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="black" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" ><path d="M21 12a9 9 0 1 1-6.219-8.56" /></svg>');
+  mask-image: var(--deck-widget-icon-loading);
+  -webkit-mask-image: var(--deck-widget-icon-loading);
+}