docs(widgets) Custom Widget Developer Guide

docs/api-reference/core/widget.md

@@ -21,6 +21,7 @@ class LoadingIndicator implements Widget {
   constructor(options: {
     size: number;
   }) {
+    this.id = 'loading-indicator'
     this.size = options.size;
   }
 
@@ -44,7 +45,7 @@ deckgl.addWidget(new LoadingIndicator({size: 48}));
 
 ## Widget Interface
 
-When a widget instance is added to Deck, the user can optionally specify a `viewId` that it is attached to (default `null`). If assigned, this widget will only respond to events occured inside the specific view that matches this id.
+When a widget instance is added to Deck, the user can optionally specify a `viewId` that it is attached to (default `null`). If assigned, this widget will only respond to events occurred inside the specific view that matches this id.
 
 ### Members
 

docs/developer-guide/custom-widgets/README.md

@@ -0,0 +1,77 @@
+# Writing Your Own Widget
+
+## Preparations
+
+There are many ways to build a widget in deck.gl, and it’s helpful to consider which approach best suits your needs before getting started. Below are guides for commonly used approaches: 
+
+* **[Implement a universal widget](./universal-widgets.md)** - A "universal widget" is a widget compatible with any deck.gl application and is UI framework agnostic. This is the best option for developing widgets intended to work across the deck.gl ecosystem.
+* **[Use Preact in a universal widget](./preact-widgets.md)** - Preact is a lightweight virtual DOM library commonly used to implement dynamic widget UI. It enables you to create highly interactive widgets without tightly coupling their internals to an application’s UI framework.
+* **[Wrap widgets in a React component](./react-widgets.md)** - If you are developing a custom Widget for a React application, you can use React to build the UI. This approach allows you to use React components and can coexist alongside other widgets.
+
+## Creating The Widget class
+
+Your widget class must implement the [Widget](../../api-reference/core/widget.md) interface.
+
+```ts
+import type {Widget} from '@deck.gl/core';
+
+class AwesomeWidget implements Widget {
+  id = 'awesome-widget';
+  props;
+  constructor(props) {
+      this.id = props.id ?? this.id;
+      this.props = { ...props };
+  }
+  onAdd() {...}
+  onRemove() {...}
+}
+```
+
+It's most convenient to use TypeScript, but widgets can also be implemented in JavaScript.
+
+### Defining Widget Properties
+
+The list of properties is the main API your new widget will provide to
+applications. So it makes sense to carefully consider what properties
+your widget should offer.
+
+You also need to define the default values of the widget's properties.
+
+```ts
+import type {WidgetPlacement} from '@deck.gl/core'
+
+type AwesomeWidgetProps = {
+  id?: string;
+  /**
+   * Widget positioning within the view. Default: 'top-left'.
+   */
+  placement?: WidgetPlacement;
+  /**
+   * View to attach to and interact with. Required when using multiple views. Default: null
+   */
+  viewId?: string | null;
+  ...
+}
+
+class AwesomeWidget implements Widget<AwesomeWidgetProps> {
+  id = 'awesome-widget';
+  props: AwesomeWidgetProps;
+  placement: WidgetPlacement = 'top-left';
+  viewId?: string | null = null;
+
+  constructor(props: AwesomeWidgetProps) {
+    this.id = props.id ?? this.id;
+    this.placement = props.placement ?? this.placement;
+    this.viewId = props.viewId ?? this.viewId;
+
+    this.props = { ...props }
+  }
+}
+```
+
+## Best Practices
+
+- **Plan Your API:** Clearly define the properties and events your widget will expose so that its easy for developers to integrate into their applications.
+- **Handle Lifecycle Events:** Implement lifecycle methods like `onAdd`, `onRemove`, and `setProps` to manage the widget's updates effectively.
+- **Optimize for Performance:** Minimize unnecessary DOM re-renders and resource usage by carefully managing state updates.
+- **Ensure Accessibility:** Provide options for styling and interactions that respect user preferences, such as keyboard navigation and screen reader support.

docs/developer-guide/custom-widgets/preact-widgets.md

@@ -0,0 +1,160 @@
+# Preact Widgets
+
+Preact widgets are an easy way to add dynamic UI elements into universal deck.gl widgets using the [Preact](https://preactjs.com/) UI library. This guide will walk you through the process of building Preact-based widgets and best practices.
+
+## Why Use Preact Widgets?
+
+Preact widgets leverage the strengths of React’s component model in a lighter weight library, allowing:
+
+ - **Easy Composition:** Reuse and combine components.
+ - **Declarative UI:** Define your UI in a predictable and straightforward manner using JSX.
+ - **Small Size:** Preact is small enough that your code is the largest part of your application.
+
+Preact widgets are suitable when you are working with any UI framework and is lightweight enough to distribute with your widget in a library.
+
+> Tip: Read more about the differences between Preact and React [here](https://preactjs.com/guide/v10/differences-to-react/).
+
+## Writing a Preact Widget
+
+### Prerequisites
+
+Ensure your project includes the `preact` package.
+
+```sh
+npm install preact
+```
+
+When using the TypeScript compiler, add the following configuration to your `tsconfig.json` to transpile JSX to Preact-compatible JavaScript:
+
+```json
+{
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "jsxImportSource": "preact"
+  }
+}
+```
+
+> Note: Developer environments vary. Refer to the [Preact Typescript](https://preactjs.com/guide/v10/typescript) documentation for additional environments.
+
+## Example: Layer List Widget with Preact
+
+Below is a comprehensive example demonstrating a layer list widget implemented using Preact for dynamic UI rendering:
+
+```tsx
+import {
+  _deepEqual as deepEqual,
+  _applyStyles as applyStyles,
+  _removeStyles as removeStyles
+} from '@deck.gl/core'
+import type {
+  Deck, Viewport, Widget, WidgetPlacement, Layer
+} from '@deck.gl/core'
+import {render} from 'preact';
+
+type LayerListWidgetProps = {
+  id?: string;
+  /**
+   * Widget positioning within the view. Default: 'top-left'.
+   */
+  placement?: WidgetPlacement;
+  /**
+   * View to attach to and interact with. Required when using multiple views. Default: null
+   */
+  viewId?: string | null;
+  /**
+   * CSS inline style overrides.
+   */
+  style?: Partial<CSSStyleDeclaration>;
+  /**
+   * Additional CSS class.
+   */
+  className?: string;
+}
+
+class LayerListWidget implements Widget<LayerListWidgetProps> {
+  id = 'layer-list-widget';
+  props: LayerListWidgetProps;
+  placement: WidgetPlacement = 'top-left';
+  viewports: {[id: string]: Viewport} = {};
+  layers: Layer[] = [];
+  deck?: Deck<any>;
+  element?: HTMLDivElement;
+
+  constructor(props: LayerListWidgetProps) {
+    this.id = props.id ?? this.id;
+    this.placement = props.placement ?? this.placement;
+    this.viewId = props.viewId ?? this.viewId;
+
+    this.props = { 
+      ...props,
+      style: props.style ?? {}
+    }
+  }
+
+  onAdd({deck}: {deck: Deck<any>}): HTMLDivElement {
+    const {style, className} = this.props;
+    const element = document.createElement('div');
+    element.classList.add('deck-widget', 'deck-widget-layer-list');
+    if (className) element.classList.add(className);
+    applyStyles(element, style);
+    this.deck = deck;
+    this.element = element;
+    this.update();
+    return element;
+  }
+
+  setProps(props: Partial<LayerListWidgetProps>) {
+    // Handle when props change here.
+    this.placement = props.placement ?? this.placement;
+    this.viewId = props.viewId ?? this.viewId;
+    this.props = {...props};
+    this.update();
+  }
+
+  onRedraw({layers}: {layers: Layer[]}) {
+    this.layers = layers;
+    this.update();
+  }
+
+  onViewportChange(viewport) {
+    this.viewports[viewport.id] = viewport
+  }
+
+  private update() {
+    const element = this.element;
+    if (!element) {
+      return;
+    }
+    let layers = this.layers
+    if (this.deck?.props.layerFilter) {
+      const ui = (
+        {this.viewports.values().map(viewport => (
+          <div>
+            {viewport.id}
+            <ul>
+              {layers.filter(layer => (
+                this.deck?.props.layerFilter({layer, viewport})
+              )).map((layer) => {
+                <li key={layer.id}>{layer.id}</li>
+              })}
+            </ul>
+          </div>
+        ))}
+      );
+      render(ui, element);
+    } else {
+      const ui = (
+        <ul>
+          {this.layers.map((layer) => (
+            <li key={layer.id}>{layer.id}</li>
+          ))}
+        </ul>
+      )
+      render(ui, element);
+    }
+  }
+}
+```
+
+This widget dynamically renders a list of layers and updates as the deck.gl state changes.