Add widgets prop to Deck class

modules/core/src/lib/deck.ts

@@ -24,7 +24,7 @@ import MapView from '../views/map-view';
 import EffectManager from './effect-manager';
 import DeckRenderer from './deck-renderer';
 import DeckPicker from './deck-picker';
-import {WidgetManager, Widget, WidgetPlacement} from './widget-manager';
+import {WidgetManager, Widget} from './widget-manager';
 import Tooltip from './tooltip';
 import log from '../utils/log';
 import {deepEqual} from '../utils/deep-equal';
@@ -181,6 +181,8 @@ export type DeckProps = {
   _pickable?: boolean;
   /** (Experimental) Fine-tune attribute memory usage. See documentation for details. */
   _typedArrayManagerProps?: TypedArrayManagerOptions;
+  /** An array of Widget instances to be added to the parent element. */
+  widgets?: Widget[];
 
   /** Called once the GPU Device has been initiated. */
   onDeviceInitialized?: (device: Device) => void;
@@ -258,6 +260,7 @@ const defaultProps = {
   _pickable: true,
   _typedArrayManagerProps: {},
   _customRender: null,
+  widgets: [],
 
   onDeviceInitialized: noop,
   onWebGLInitialized: noop,
@@ -485,6 +488,7 @@ export default class Deck {
       this.effectManager.setProps(resolvedProps);
       this.deckRenderer.setProps(resolvedProps);
       this.deckPicker.setProps(resolvedProps);
+      this.widgetManager.setProps(resolvedProps);
     }
 
     this.stats.get('setProps Time').timeEnd();
@@ -988,7 +992,7 @@ export default class Deck {
       deck: this,
       parentElement: this.canvas?.parentElement
     });
-    this.widgetManager.add(new Tooltip(), {placement: 'fill'});
+    this.widgetManager.addDefault(new Tooltip());
 
     this.setProps(this.props);
 

modules/core/src/lib/tooltip.ts

@@ -17,7 +17,7 @@
 // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 // THE SOFTWARE.
-import {Widget} from './widget-manager';
+import type {Widget, WidgetPlacement} from './widget-manager';
 import type {PickingInfo} from './picking/pick-info';
 import type Viewport from '../viewports/viewport';
 import type Deck from './deck';
@@ -46,6 +46,9 @@
     };
 
 export default class Tooltip implements Widget {
+  id = 'default-tooltip';
+  placement: WidgetPlacement = 'fill';
+  props = {};
   isVisible: boolean = false;
   deck?: Deck;
   element?: HTMLDivElement;
@@ -67,6 +70,8 @@
     this.element = undefined;
   }
 
+  setProps() {}
+
   onViewportChange(viewport: Viewport) {
     if (this.isVisible && viewport.id === this.lastViewport?.id && viewport !== this.lastViewport) {
       // Camera has moved, clear tooltip

modules/core/src/lib/widget-manager.ts

@@ -5,11 +5,16 @@
 import type Layer from './layer';
 
 import {EVENTS} from './constants';
+import {deepEqual} from '../utils/deep-equal';
 
 export interface Widget<PropsT = any> {
+  id: string;
+  props: PropsT;
+  viewId?: string | null;
+  placement?: WidgetPlacement;
+
   // Populated by core when mounted
   _element?: HTMLDivElement | null;
-  _viewId?: string | null;
 
   // Lifecycle hooks
   /** Called when the widget is added to a Deck instance.
@@ -23,7 +28,7 @@
   /** Called when the widget is removed */
   onRemove: () => void;
   /** Called to update widget options */
-  setProps?: (props: Partial<PropsT>) => void;
+  setProps: (props: Partial<PropsT>) => void;
 
   // Optional event hooks
   /** Called when the containing view is changed */
@@ -49,6 +54,7 @@
   'bottom-right': {bottom: 0, right: 0},
   fill: {top: 0, left: 0, bottom: 0, right: 0}
 } as const;
+const DEFAULT_PLACEMENT = 'top-left';
 
 export type WidgetPlacement = keyof typeof PLACEMENTS;
 
@@ -57,61 +63,119 @@
 export class WidgetManager {
   deck: Deck;
   parentElement?: HTMLElement | null;
-  containers: {[id: string]: HTMLDivElement} = {};
-  widgets: Widget[] = [];
-  lastViewports: {[id: string]: Viewport} = {};
+
+  /** Widgets added via the imperative API */
+  private defaultWidgets: Widget[] = [];
+  /** Widgets received from the declarative API */
+  private widgets: Widget[] = [];
+  /** Resolved widgets from both imperative and declarative APIs */
+  private resolvedWidgets: Widget[] = [];
+  private containers: {[id: string]: HTMLDivElement} = {};
+  private lastViewports: {[id: string]: Viewport} = {};
 
   constructor({deck, parentElement}: {deck: Deck; parentElement?: HTMLElement | null}) {
     this.deck = deck;
     this.parentElement = parentElement;
   }
 
+  getWidgets(): Widget[] {
+    return this.resolvedWidgets;
+  }
+
+  /** Declarative API to configure widgets */
+  setProps(props: {widgets?: Widget[]}) {
+    if (props.widgets && !deepEqual(props.widgets, this.widgets, 1)) {
+      this._setWidgets(props.widgets);
+    }
+  }
+
   finalize() {
-    for (const widget of this.widgets) {
-      this.remove(widget);
+    for (const widget of this.getWidgets()) {
+      this._remove(widget);
     }
+    this.defaultWidgets.length = 0;
+    this.resolvedWidgets.length = 0;
     for (const id in this.containers) {
       this.containers[id].remove();
     }
   }
 
-  add(
-    widget: Widget,
-    opts: {
-      viewId?: string | null;
-      placement?: WidgetPlacement;
-    } = {}
-  ) {
-    if (this.widgets.includes(widget)) {
-      // widget already added
-      return;
+  /** Imperative API. Widgets added this way are not affected by the declarative prop. */
+  addDefault(widget: Widget) {
+    if (!this.defaultWidgets.find(w => w.id === widget.id)) {
+      this._add(widget);
+      this.defaultWidgets.push(widget);
+      // Update widget list
+      this._setWidgets(this.widgets);
+    }
+  }
+
+  /** Resolve widgets from the declarative prop */
+  private _setWidgets(nextWidgets: Widget[]) {
+    const oldWidgetMap: Record<string, Widget | null> = {};
+
+    for (const widget of this.resolvedWidgets) {
+      oldWidgetMap[widget.id] = widget;
     }
+    // Clear and rebuild the list
+    this.resolvedWidgets.length = 0;
 
-    const {placement = 'top-left', viewId = null} = opts;
+    // Add all default widgets
+    for (const widget of this.defaultWidgets) {
+      oldWidgetMap[widget.id] = null;
+      this.resolvedWidgets.push(widget);
+    }
+
+    for (let widget of nextWidgets) {
+      const oldWidget = oldWidgetMap[widget.id];
+      if (!oldWidget) {
+        // Widget is new
+        this._add(widget);
+      } else if (
+        // Widget placement changed
+        oldWidget.viewId !== widget.viewId ||
+        oldWidget.placement !== widget.placement
+      ) {
+        this._remove(oldWidget);
+        this._add(widget);
+      } else if (widget !== oldWidget) {
+        // Widget props changed
+        oldWidget.setProps(widget.props);
+        widget = oldWidget;
+      }
+
+      // mark as matched
+      oldWidgetMap[widget.id] = null;
+      this.resolvedWidgets.push(widget);
+    }
+
+    for (const id in oldWidgetMap) {
+      const oldWidget = oldWidgetMap[id];
+      if (oldWidget) {
+        // No longer exists
+        this._remove(oldWidget);
+      }
+    }
+    this.widgets = nextWidgets;
+  }
+
+  private _add(widget: Widget) {
+    const {viewId = null, placement = DEFAULT_PLACEMENT} = widget;
     const element = widget.onAdd({deck: this.deck, viewId});
 
     if (element) {
       this._getContainer(viewId, placement).append(element);
     }
-    widget._viewId = viewId;
     widget._element = element;
-    this.widgets.push(widget);
   }
 
-  remove(widget: Widget) {
-    const i = this.widgets.indexOf(widget);
-    if (i < 0) {
-      // widget not found
-      return;
-    }
-    this.widgets.splice(i, 1);
+  private _remove(widget: Widget) {
     widget.onRemove();
 
     if (widget._element) {
       widget._element.remove();
     }
     widget._element = undefined;
-    widget._viewId = undefined;
   }
 
   /* global document */
@@ -165,8 +229,8 @@
     }, {});
     const {lastViewports} = this;
 
-    for (const widget of this.widgets) {
-      const viewId = widget._viewId;
+    for (const widget of this.getWidgets()) {
+      const {viewId} = widget;
       if (viewId) {
         // Attached to a specific view
         const viewport = viewportsById[viewId];
@@ -180,7 +244,7 @@
         // Not attached to a specific view
         if (widget.onViewportChange) {
           for (const viewport of viewports) {
             if (!viewport.equals(lastViewports[viewport.id])) {
               widget.onViewportChange(viewport);
             }
           }
@@ -193,8 +257,8 @@
   }
 
   onHover(info: PickingInfo, event: MjolnirPointerEvent) {
-    for (const widget of this.widgets) {
-      const viewId = widget._viewId;
+    for (const widget of this.getWidgets()) {
+      const {viewId} = widget;
       if (!viewId || viewId === info.viewport?.id) {
         widget.onHover?.(info, event);
       }
@@ -206,8 +270,8 @@
     if (!eventOptions) {
       return;
     }
-    for (const widget of this.widgets) {
-      const viewId = widget._viewId;
+    for (const widget of this.getWidgets()) {
+      const {viewId} = widget;
       if (!viewId || viewId === info.viewport?.id) {
         widget[eventOptions.handler]?.(info, event);
       }

test/modules/core/lib/tooltip.spec.js

@@ -11,7 +11,7 @@ function setupTest() {
   const container = document.createElement('div');
   const widgetManager = new WidgetManager({parentElement: container});
   const tooltip = new Tooltip();
-  widgetManager.add(tooltip);
+  widgetManager.addDefault(tooltip);
   return {tooltip, widgetManager, container};
 }
 
@@ -90,13 +90,12 @@ test('Tooltip#remove', t => {
   const {widgetManager, tooltip, container} = setupTest();
 
   t.equals(container.querySelectorAll('.deck-tooltip').length, 1, 'Tooltip element present');
-  widgetManager.remove(tooltip);
+  widgetManager.finalize();
   t.equals(
     container.querySelectorAll('.deck-tooltip').length,
     0,
     'Tooltip element successfully removed'
   );
 
-  widgetManager.finalize();
   t.end();
 });