fix(mapbox): Preserve widget container on setProps to prevent orphaned rootElement

When setProps was called with widgets, _processWidgets would destroy and
recreate all DeckWidgetControls. This removed the container from the DOM,
orphaning the widget's rootElement since WidgetManager wouldn't re-attach
it (same widget id means no change detected).

Now matches widgets by id (like WidgetManager) and only recreates controls
when the widget is new or placement changes. For existing widgets with same
id and placement, the container is preserved and copied to the new widget
instance to support React patterns where widgets are recreated on render.

Co-Authored-By: Claude (global.anthropic.claude-opus-4-5-20251101-v1:0) <noreply@anthropic.com>

Author: chrisgervang

modules/mapbox/src/mapbox-overlay.ts

@@ -193,29 +193,54 @@ export default class MapboxOverlay implements IControl {
    * Process widgets and wrap those with viewId: 'mapbox' as IControls.
    * This enables deck widgets to be positioned in Mapbox's control container
    * alongside native map controls, preventing overlap.
+   *
+   * Matches widgets by id (like WidgetManager) to handle new instances with same id.
+   * Only recreates controls when placement changes to avoid orphaning the widget's
+   * rootElement when the container is removed from the DOM.
    */
   private _processWidgets(widgets: Widget[] | undefined): void {
     const map = this._map;
     if (!map) return;
 
-    // Remove old widget controls
+    const mapboxWidgets = widgets?.filter(w => w.viewId === 'mapbox') ?? [];
+
+    // Build a map of existing controls by widget id
+    const existingControlsById = new Map<string, DeckWidgetControl>();
     for (const control of this._widgetControls) {
-      map.removeControl(control);
+      existingControlsById.set(control.widget.id, control);
     }
-    this._widgetControls = [];
 
-    if (!widgets) return;
+    const newControls: DeckWidgetControl[] = [];
+
+    for (const widget of mapboxWidgets) {
+      const existingControl = existingControlsById.get(widget.id);
 
-    // Wrap widgets with viewId: 'mapbox' as IControls
-    for (const widget of widgets) {
-      if (widget.viewId === 'mapbox') {
+      if (existingControl && existingControl.widget.placement === widget.placement) {
+        // Same id and placement - reuse existing control to preserve container
+        // Set _container on the new widget instance so WidgetManager uses it
+        widget.props._container = existingControl.widget.props._container;
+        newControls.push(existingControl);
+        existingControlsById.delete(widget.id);
+      } else {
+        // New widget or placement changed - need a new control
+        if (existingControl) {
+          // Placement changed - remove old control first
+          map.removeControl(existingControl);
+          existingControlsById.delete(widget.id);
+        }
         const control = new DeckWidgetControl(widget);
         // Add to map - this calls onAdd() synchronously, setting _container
-        // Use control.getDefaultPosition() which handles 'fill' -> 'top-left' conversion
         map.addControl(control, control.getDefaultPosition());
-        this._widgetControls.push(control);
+        newControls.push(control);
       }
     }
+
+    // Remove controls for widgets that are no longer present
+    for (const control of existingControlsById.values()) {
+      map.removeControl(control);
+    }
+
+    this._widgetControls = newControls;
   }
 
   /** Called when the control is removed from a map */

test/modules/mapbox/mapbox-overlay.spec.ts

@@ -629,6 +629,71 @@ test('MapboxOverlay#widgets - setProps updates widget controls', t => {
   t.end();
 });
 
+test('MapboxOverlay#widgets - setProps preserves container for same widget instance', t => {
+  const map = new MockMapboxMap({
+    center: {lng: -122.45, lat: 37.78},
+    zoom: 14
+  });
+
+  const widget = new TestWidget({id: 'widget1', viewId: 'mapbox', placement: 'top-right'});
+  const overlay = new MapboxOverlay({
+    device: overlaidTestDevice,
+    layers: [new ScatterplotLayer()],
+    widgets: [widget]
+  });
+
+  map.addControl(overlay);
+  t.is(overlay._widgetControls.length, 1, 'Widget control created');
+  const originalContainer = widget.props._container;
+  t.ok(originalContainer, 'Widget _container is set');
+  const originalControl = overlay._widgetControls[0];
+
+  // Call setProps with the same widget instance
+  overlay.setProps({
+    widgets: [widget]
+  });
+
+  t.is(overlay._widgetControls.length, 1, 'Still one widget control');
+  t.is(overlay._widgetControls[0], originalControl, 'Same control instance preserved');
+  t.is(widget.props._container, originalContainer, 'Container preserved - not recreated');
+
+  map.removeControl(overlay);
+  t.end();
+});
+
+test('MapboxOverlay#widgets - setProps preserves container for new widget instance with same id', t => {
+  const map = new MockMapboxMap({
+    center: {lng: -122.45, lat: 37.78},
+    zoom: 14
+  });
+
+  const widget1 = new TestWidget({id: 'my-widget', viewId: 'mapbox', placement: 'top-right'});
+  const overlay = new MapboxOverlay({
+    device: overlaidTestDevice,
+    layers: [new ScatterplotLayer()],
+    widgets: [widget1]
+  });
+
+  map.addControl(overlay);
+  t.is(overlay._widgetControls.length, 1, 'Widget control created');
+  const originalContainer = widget1.props._container;
+  t.ok(originalContainer, 'Widget _container is set');
+  const originalControl = overlay._widgetControls[0];
+
+  // Call setProps with a NEW widget instance but same id and placement (React pattern)
+  const widget2 = new TestWidget({id: 'my-widget', viewId: 'mapbox', placement: 'top-right'});
+  overlay.setProps({
+    widgets: [widget2]
+  });
+
+  t.is(overlay._widgetControls.length, 1, 'Still one widget control');
+  t.is(overlay._widgetControls[0], originalControl, 'Same control instance preserved');
+  t.is(widget2.props._container, originalContainer, 'New widget gets existing container');
+
+  map.removeControl(overlay);
+  t.end();
+});
+
 test('MapboxOverlay#widgets - interleaved mode', t => {
   const map = new MockMapboxMap({
     center: {lng: -122.45, lat: 37.78},