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;
   }
 
@@ -48,7 +49,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,70 @@
+# Writing Your Own Widget
+
+## Preparations
+
+There are a many ways to build a widget in deck.gl, and it is helpful to consider what approach will serve you best before starting. We've provided guides for commonly used approaches: 
+
+* **[Implement a universal widget](./universal-widgets.md)** - A universal widget is compatible with any deck.gl application and is UI framework agnostic. This option is best for developing widgets to be used throughout the deck.gl ecosystem.
+* **[Create a react widget](./react-widgets.md)** - A react widget utilizes the convenience of react to develop the UI for your widget. It is tightly coupled to your react application, being mounted in the same root as the rest of your UI. This option is best for developing widgets custom to your react application. 
+
+
+## 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 {
+    constructor(props) {
+        this.id = props.id || 'awesome-widget';
+        this.props = { ...props };
+    }
+    onAdd() {...}
+    onRemove() {...}
+}
+```
+
+It's most convenient to use TypeScript, but it 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'
+
+interface 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 {
+  constructor(props: AwesomeWidgetProps) {
+    this.id = props.id || 'awesome-widget';
+    this.placement = props.placement || 'top-left';
+    this.viewId = props.viewId || null;
+
+    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/react-widgets.md

@@ -0,0 +1,131 @@
+# React Widgets
+
+React widgets are a powerful way to integrate custom UI elements into deck.gl applications using the React framework. This guide will walk you through the process of building React-based widgets and best practices.
+
+We recommend users writing their own react widgets be familiar with implementing the `Widget` interface, consider reviewing the [Universal Widgets](./universal-widgets.md) guide.
+
+## Why Use React Widgets?
+
+React widgets leverage the strengths of React’s component model, allowing:
+ - **Easy Composition:** Reuse and combine components within the React ecosystem.
+ - **React Lifecycle Integration:** Utilize React’s lifecycle hooks to manage state and updates.
+ - **Declarative UI:** Define your UI in a predictable and straightforward manner using JSX.
+
+React widgets are most suitable when you are working on React applications and do not intend to distribute your widget outside of your application.
+
+## Writing a React Widget
+
+### Prerequisites
+
+Ensure your deck.gl project includes the `@deck.gl/react` package to utilize React-specific utilities, such as the [`useWidget`](../../api-reference/react/use-widget.md) hook. 
+
+Install the package if it’s not already included:
+
+```sh
+npm install @deck.gl/react
+```
+
+### Example: Creating a React Widget
+
+Below is a step-by-step example of implementing a simple React widget.
+
+#### Define Your Widget Class
+
+Start by creating the core widget class, which must implement the [Widget](../../api-reference/core/widget.md) interface.
+
+```ts
+import type { Widget, WidgetPlacement } from '@deck.gl/react';=
+import { useWidget } from '@deck.gl/react';
+import React, { useRef, RefObject } from 'react';
+
+interface RotateWidgetProps {
+    id?: string
+    placement?: WidgetPlacement
+    ref: RefObject<HTMLDivElement>
+}
+
+class RotateWidget {
+  constructor(props: BearingWidgetProps) {
+    this.id = props.id || 'bearing-widget';
+    this.placement = props.placement || 'top-right';
+    this.props = props;
+    this.viewports = {};
+  }
+
+  onAdd({ deck }) {
+    this.deck = deck;
+    return this.props.ref.current;
+  }
+
+  onViewportChange(viewport) {
+    this.viewports[viewport.id] = viewport;
+  }
+
+  handleRotate(viewport, bearingDelta) {
+    const nextBearing = viewport.bearing + bearingDelta;
+    const viewState = {
+      ...viewport,
+      bearing: nextBearing
+    };
+    this.deck.setProps({ viewState });
+  }
+
+  handleCWRotate() {
+    Object.values(this.viewports).forEach(viewport => this.handleRotate(viewport, 90));
+  }
+
+  handleCCWRotate() {
+    Object.values(this.viewports).forEach(viewport => this.handleRotate(viewport, -90));
+  }
+}
+```
+
+#### Create a React Component
+
+Wrap the widget class in a React component using the [`useWidget`](../../api-reference/react/use-widget.md) hook.
+
+```tsx
+export const RotateReactWidget = (props) => {
+  const ref = useRef();
+  const widget = useWidget(RotateWidget, { ref, ...props });
+
+  return (
+    <div 
+        ref={ref} 
+        style={{ padding: '10px', backgroundColor: '#f0f0f0', ...props.style }}
+        className='custom-rotate-widget'
+    >
+      <button onClick={() => widget.handleCCWRotate()} style={{ marginRight: '5px' }}>
+        Rotate CCW
+      </button>
+      <button onClick={() => widget.handleCWRotate()}>
+        Rotate CW
+      </button>
+    </div>
+  );
+};
+```
+
+This widget controls the bearing of the view its attached to.
+
+### Styling Your React Widget
+
+#### Inline Styles
+
+React widgets can be written to accept `style` props for inline styling.
+
+```tsx
+<RotateReactWidget style={{ backgroundColor: 'blue', color: 'white' }} />
+```
+
+#### CSS Classes
+
+React widgets can use `className` and add styles to their stylesheet.
+
+```css
+.custom-rotate-widget {
+  padding: 10px;
+  background-color: #333;
+  color: white;
+}
+```