chore(widgets): Join Widget and WidgetImpl, clean up widgets (#9576)

Author: ibgreen

docs/api-reference/core/widget.md

@@ -9,12 +9,15 @@ A widget is a UI component that can interact with deck.gl's cameras and layers.
 
 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:
+The `Widget` class is not used directly by an app. It is a base class used to define new widgets.
+
+
+A widget should inherit the `Widget` class. Here is a custom widget that shows a spinner while layers are loading:
 
 ```ts
 import {Deck, Widget} from '@deck.gl/core';
 
-class LoadingIndicator implements Widget {
+class LoadingIndicator extends Widget {
   element?: HTMLDivElement;
   size: number;
 
@@ -24,18 +27,15 @@ class LoadingIndicator implements Widget {
     this.size = options.size;
   }
 
-  onAdd() {
-    const el = document.createElement('div');
+  onRenderHTML(el: HTMLElement) {
     el.className = 'spinner';
     el.style.width = `${this.size}px`;
     // TODO - create animation for .spinner in the CSS stylesheet
-    this.element = el;
-    return el;
   }
 
   onRedraw({layers}) {
     const isVisible = layers.some(layer => !layer.isLoaded);
-    this.element.style.display = isVisible ? 'block' : 'none';
+    this.rootElement.style.display = isVisible ? 'block' : 'none';
   }
 }
 
@@ -80,6 +80,25 @@ Widget positioning within the view. One of:
 
 ### Methods
 
+#### `setProps` {#setprops}
+
+Optional. Called to update widget options.
+
+#### `updateHTML` {#updatehtml}
+
+Updates the widget. Normally called automatically.
+
+
+### Lifecycle Methods
+
+The following methods are available when implementing a new widget.
+
+#### `constructor`
+
+Supply the props and default props to the base class.
+
+#### `onRenderHTML`
+
 #### `onAdd` {#onadd}
 
 Required. Called when the widget is added to a Deck instance.
@@ -96,10 +115,6 @@ Returns an optional UI element that should be appended to the Deck container.
 
 Optional. Called when the widget is removed.
 
-#### `setProps` {#setprops}
-
-Optional. Called to update widget options.
-
 #### `onViewportChange` {#onviewportchange}
 
 Op†ional. Called when the containing view is changed. If `viewId: null`, will be called if any viewport changes.

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

@@ -9,8 +9,7 @@ import {
   ZoomWidget,
   FullscreenWidget,
   DarkGlassTheme,
-  LightGlassTheme,
-  TimelineWidget
+  LightGlassTheme
 } from '@deck.gl/widgets';
 import '@deck.gl/widgets/stylesheet.css';
 
@@ -78,15 +77,6 @@ new Deck({
   widgets: [
     new ZoomWidget({style: widgetTheme}),
     new CompassWidget({style: widgetTheme}),
-    new FullscreenWidget({style: widgetTheme}),
-    new TimelineWidget({
-      style: widgetTheme,
-      domain: [0, 24],
-      step: 1,
-      value: 0,
-      playInterval: 1000,
-      // eslint-disable-next-line no-console, no-undef
-      onTimeChange: time => console.log('Time:', time)
-    })
+    new FullscreenWidget({style: widgetTheme})
   ]
 });

modules/aggregation-layers/src/screen-grid-layer/screen-grid-cell-layer.ts

@@ -4,7 +4,7 @@
 
 import {Texture} from '@luma.gl/core';
 import {Model, Geometry} from '@luma.gl/engine';
-import {Layer, picking, UpdateParameters, DefaultProps, Color} from '@deck.gl/core';
+import {Layer, picking, UpdateParameters, Color} from '@deck.gl/core';
 import {createColorRangeTexture, updateColorRangeTexture} from '../common/utils/color-utils';
 import vs from './screen-grid-layer-vertex.glsl';
 import fs from './screen-grid-layer-fragment.glsl';

modules/carto/src/layers/schema/spatialjson-utils.ts

@@ -6,7 +6,6 @@ import {bigIntToHex} from 'quadbin';
 import {BinaryPointFeature} from '@loaders.gl/schema';
 
 export type IndexScheme = 'h3' | 'quadbin';
-type TypedArray = Float32Array | Float64Array;
 
 export type Indices = {value: BigUint64Array};
 export type NumericProps = BinaryPointFeature['numericProps'];

modules/carto/src/layers/vector-tile-layer.ts

@@ -3,7 +3,7 @@
 // Copyright (c) vis.gl contributors
 
 import {registerLoaders} from '@loaders.gl/core';
-import {BinaryFeatureCollection, BinaryPointFeature} from '@loaders.gl/schema';
+import {BinaryPointFeature} from '@loaders.gl/schema';
 import CartoPropertiesTileLoader from './schema/carto-properties-tile-loader';
 import CartoVectorTileLoader from './schema/carto-vector-tile-loader';
 registerLoaders([CartoPropertiesTileLoader, CartoVectorTileLoader]);
@@ -13,7 +13,6 @@ import {ClipExtension, CollisionFilterExtension} from '@deck.gl/extensions';
 import {
   MVTLayer,
   MVTLayerProps,
-  TileLayer,
   _getURLFromTemplate,
   _Tile2DHeader,
   _TileLoadProps as TileLoadProps,

modules/carto/src/utils.ts

@@ -2,12 +2,7 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import {
-  BinaryAttribute,
-  BinaryFeature,
-  BinaryFeatureCollection,
-  BinaryPointFeature
-} from '@loaders.gl/schema';
+import {BinaryFeatureCollection, BinaryPointFeature} from '@loaders.gl/schema';
 import {log} from '@deck.gl/core';
 import type {Properties, NumericProps} from './layers/schema/spatialjson-utils';
 

modules/core/src/index.ts

@@ -129,7 +129,8 @@ export type {Effect, EffectContext, PreRenderOptions, PostRenderOptions} from '.
 export type {PickingUniforms, ProjectProps, ProjectUniforms} from './shaderlib/index';
 export type {DefaultProps} from './lifecycle/prop-types';
 export type {LayersPassRenderOptions} from './passes/layers-pass';
-export type {Widget} from './lib/widget';
+export {Widget} from './lib/widget';
+export type {WidgetProps} from './lib/widget';
 export type {WidgetPlacement} from './lib/widget-manager';
 export type {LightingEffectProps} from './effects/lighting/lighting-effect';
 export type {AmbientLightOptions} from './effects/lighting/ambient-light';

modules/core/src/lib/deck.ts

@@ -10,7 +10,7 @@ import DeckRenderer from './deck-renderer';
 import DeckPicker from './deck-picker';
 import {Widget} from './widget';
 import {WidgetManager} from './widget-manager';
-import Tooltip from './tooltip';
+import {TooltipWidget} from './tooltip-widget';
 import log from '../utils/log';
 import {deepEqual} from '../utils/deep-equal';
 import typedArrayManager from '../utils/typed-array-manager';
@@ -41,7 +41,7 @@ import type {ViewStateChangeParameters, InteractionState} from '../controllers/c
 import type {PickingInfo} from './picking/pick-info';
 import type {PickByPointOptions, PickByRectOptions} from './deck-picker';
 import type {LayersList} from './layer-manager';
-import type {TooltipContent} from './tooltip';
+import type {TooltipContent} from './tooltip-widget';
 import type {ViewStateMap, AnyViewStateOf, ViewOrViews, ViewStateObject} from './view-manager';
 import {CreateDeviceProps} from '@luma.gl/core';
 
@@ -295,7 +295,7 @@ export default class Deck<ViewsT extends ViewOrViews = null> {
   protected deckPicker: DeckPicker | null = null;
   protected eventManager: EventManager | null = null;
   protected widgetManager: WidgetManager | null = null;
-  protected tooltip: Tooltip | null = null;
+  protected tooltip: TooltipWidget | null = null;
   protected animationLoop: AnimationLoop | null = null;
 
   /** Internal view state if no callback is supplied */
@@ -1026,7 +1026,7 @@ export default class Deck<ViewsT extends ViewOrViews = null> {
       deck: this,
       parentElement: this.canvas?.parentElement
     });
-    this.widgetManager.addDefault(new Tooltip());
+    this.widgetManager.addDefault(new TooltipWidget());
 
     this.setProps(this.props);
 

modules/core/src/lib/layer.ts

@@ -1253,6 +1253,7 @@ export default abstract class Layer<PropsT extends {} = {}> extends Component<
   // Private methods
 
   /** Called after updateState to perform common tasks */
+  // eslint-disable-next-line complexity
   protected _postUpdate(updateParams: UpdateParameters<Layer<PropsT>>, forceUpdate: boolean) {
     const {props, oldProps} = updateParams;
 

modules/core/src/lib/tooltip.ts renamed to modules/core/src/lib/tooltip-widget.ts

@@ -2,11 +2,10 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import type {Widget} from './widget';
+import {Widget, WidgetProps} from './widget';
 import type {WidgetPlacement} from './widget-manager';
 import type {PickingInfo} from './picking/pick-info';
 import type Viewport from '../viewports/viewport';
-import type Deck from './deck';
 
 /* global document */
 const defaultStyle: Partial<CSSStyleDeclaration> = {
@@ -31,32 +30,34 @@ export type TooltipContent =
       style?: Partial<CSSStyleDeclaration>;
     };
 
-export default class Tooltip implements Widget {
+export type TooltipWidgetProps = WidgetProps;
+
+export class TooltipWidget extends Widget<TooltipWidgetProps> {
+  static defaultProps: Required<TooltipWidgetProps> = {
+    ...Widget.defaultProps
+  };
+
   id = 'default-tooltip';
   placement: WidgetPlacement = 'fill';
-  props = {};
+  className = 'deck-tooltip';
+
   isVisible: boolean = false;
-  deck?: Deck<any>;
-  element?: HTMLDivElement;
   lastViewport?: Viewport;
 
-  onAdd({deck}: {deck: Deck<any>}): HTMLDivElement {
+  constructor(props: TooltipWidgetProps = {}) {
+    super(props, TooltipWidget.defaultProps);
+    this.setProps(props);
+  }
+
+  // TODO(ib) - does this really need to be overridden?
+  onCreateRootElement() {
     const el = document.createElement('div');
-    el.className = 'deck-tooltip';
+    el.className = this.className;
     Object.assign(el.style, defaultStyle);
-
-    this.deck = deck;
-    this.element = el;
-
     return el;
   }
 
-  onRemove() {
-    this.deck = undefined;
-    this.element = undefined;
-  }
-
-  setProps() {}
+  onRenderHTML(rootElement: HTMLElement): void {}
 
   onViewportChange(viewport: Viewport) {
     if (this.isVisible && viewport.id === this.lastViewport?.id && viewport !== this.lastViewport) {
@@ -77,7 +78,7 @@ export default class Tooltip implements Widget {
   }
 
   setTooltip(displayInfo: TooltipContent, x?: number, y?: number): void {
-    const el = this.element;
+    const el = this.rootElement;
     if (!el) {
       return;
     }