feat(mapbox): Add widget support to MapboxOverlay via IControl adapter

Enable deck widgets to coexist with native Mapbox/MapLibre controls without
DOM overlap by rendering widgets with viewId: 'mapbox' into the map's control
container system.

- Add DeckWidgetControl class that wraps deck widgets as IControls
- Process widgets with viewId: 'mapbox' in MapboxOverlay
- Set widget._container to Mapbox-positioned element via IControl
- Widgets stack correctly with native controls in same container

Closes #9962

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

Author: chrisgervang

modules/mapbox/src/deck-widget-control.ts

@@ -0,0 +1,78 @@
+// deck.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {Widget} from '@deck.gl/core';
+import type {IControl, ControlPosition, Map} from './types';
+
+/**
+ * Wraps a deck.gl Widget as a Mapbox/MapLibre IControl.
+ *
+ * This enables deck widgets to be positioned alongside native map controls
+ * in the same DOM container, preventing overlap issues.
+ *
+ * Used internally by MapboxOverlay for widgets with `viewId: 'mapbox'`.
+ * Can also be used directly for more control over widget positioning.
+ *
+ * @example
+ * ```typescript
+ * const zoomWidget = new ZoomWidget({placement: 'top-right'});
+ * const control = new DeckWidgetControl(zoomWidget);
+ * map.addControl(control, 'top-right');
+ * ```
+ */
+export class DeckWidgetControl implements IControl {
+  private _widget: Widget;
+  private _container: HTMLDivElement | null = null;
+
+  constructor(widget: Widget) {
+    this._widget = widget;
+  }
+
+  /**
+   * Called when the control is added to the map.
+   * Creates a container element that will be positioned by Mapbox/MapLibre,
+   * and sets the widget's _container prop so WidgetManager appends the widget here.
+   */
+  onAdd(map: Map): HTMLElement {
+    this._container = document.createElement('div');
+    this._container.className = 'maplibregl-ctrl mapboxgl-ctrl deck-widget-ctrl';
+
+    // Set _container so WidgetManager appends the widget's rootElement here
+    // instead of in its own overlay container
+    this._widget.props._container = this._container;
+
+    return this._container;
+  }
+
+  /**
+   * Called when the control is removed from the map.
+   */
+  onRemove(): void {
+    // Clear the _container reference so widget doesn't try to append there
+    if (this._widget.props._container === this._container) {
+      this._widget.props._container = null;
+    }
+    this._container?.remove();
+    this._container = null;
+  }
+
+  /**
+   * Returns the default position for this control.
+   * Uses the widget's placement, which conveniently matches Mapbox control positions.
+   * Note: 'fill' placement is not supported by Mapbox controls, defaults to 'top-left'.
+   */
+  getDefaultPosition(): ControlPosition {
+    const placement = this._widget.placement;
+    // 'fill' is not a valid Mapbox control position
+    if (!placement || placement === 'fill') {
+      return 'top-left';
+    }
+    return placement;
+  }
+
+  /** Returns the wrapped widget */
+  get widget(): Widget {
+    return this._widget;
+  }
+}

modules/mapbox/src/mapbox-overlay.ts

@@ -11,10 +11,11 @@ import {
   getDefaultParameters,
   getProjection
 } from './deck-utils';
+import {DeckWidgetControl} from './deck-widget-control';
 
 import type {Map, IControl, MapMouseEvent, ControlPosition} from './types';
 import type {MjolnirGestureEvent, MjolnirPointerEvent} from 'mjolnir.js';
-import type {DeckProps, LayersList} from '@deck.gl/core';
+import type {DeckProps, LayersList, Widget} from '@deck.gl/core';
 
 import {resolveLayers} from './resolve-layers';
 import {resolveLayerGroups} from './resolve-layer-groups';
@@ -55,6 +56,8 @@ export default class MapboxOverlay implements IControl {
   private _interleaved: boolean;
   private _renderLayersInGroups: boolean;
   private _lastMouseDownPoint?: {x: number; y: number; clientX: number; clientY: number};
+  /** IControl wrappers for widgets with viewId: 'mapbox' */
+  private _widgetControls: DeckWidgetControl[] = [];
 
   constructor(props: MapboxOverlayProps) {
     const {interleaved = false} = props;
@@ -79,6 +82,12 @@ export default class MapboxOverlay implements IControl {
       this._resolveLayers(this._map, this._deck, this._props.layers, props.layers);
     }
 
+    // Process widgets with viewId: 'mapbox' before updating props
+    // This must happen before deck.setProps so _container is set
+    if (props.widgets !== undefined) {
+      this._processWidgets(props.widgets);
+    }
+
     Object.assign(this._props, this.filterProps(props));
 
     if (this._deck && this._map) {
@@ -112,6 +121,10 @@ export default class MapboxOverlay implements IControl {
     });
     this._container = container;
 
+    // Process widgets with viewId: 'mapbox' BEFORE creating Deck
+    // so _container is set when WidgetManager initializes
+    this._processWidgets(this._props.widgets);
+
     this._deck = new Deck<any>({
       ...this._props,
       parent: container,
@@ -143,6 +156,11 @@ export default class MapboxOverlay implements IControl {
         'Incompatible basemap library. See: https://deck.gl/docs/api-reference/mapbox/overview#compatibility'
       )();
     }
+
+    // Process widgets with viewId: 'mapbox' BEFORE creating Deck
+    // so _container is set when WidgetManager initializes
+    this._processWidgets(this._props.widgets);
+
     this._deck = getDeckInstance({
       map,
       deck: new Deck({
@@ -171,11 +189,46 @@ 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.
+   */
+  private _processWidgets(widgets: Widget[] | undefined): void {
+    const map = this._map;
+    if (!map) return;
+
+    // Remove old widget controls
+    for (const control of this._widgetControls) {
+      map.removeControl(control);
+    }
+    this._widgetControls = [];
+
+    if (!widgets) return;
+
+    // Wrap widgets with viewId: 'mapbox' as IControls
+    for (const widget of widgets) {
+      if (widget.viewId === 'mapbox') {
+        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);
+      }
+    }
+  }
+
   /** Called when the control is removed from a map */
   onRemove(): void {
     const map = this._map;
 
     if (map) {
+      // Remove widget controls
+      for (const control of this._widgetControls) {
+        map.removeControl(control);
+      }
+      this._widgetControls = [];
+
       if (this._interleaved) {
         this._onRemoveInterleaved(map);
       } else {