feat: Support for map controls (#924)

### Change list

- Adds definitions for map "controls" (which deck.gl calls "widgets",
but the name "widget" is too overloaded in the context of Jupyter, so
I'd like to call them "controls")
- Support for `ScaleControl`, `NavigationControl`, `FullscreenControl`
- These controls are supported by both deck.gl and maplibre, and so
implementations are defined for creating both the deck.gl and maplibre
counterparts

### Example

```py
from lonboard import Map
from lonboard.controls import ScaleControl, FullscreenControl, NavigationControl
from lonboard.basemap import MaplibreBasemap

m = Map([], 
    basemap=MaplibreBasemap(mode="overlaid"),
    controls=[ScaleControl(), FullscreenControl(), NavigationControl()]
)
m
```

<img width="734" height="506" alt="image"
src="https://github.com/user-attachments/assets/42fb5e55-57d8-4b2a-8fe2-f70b804dabce"
/>

We should probably change the default positioning of controls, move the
bbox selector, or make the bbox selector a control itself.

----

However, for deck.gl-driven rendering, I can only see the scale control:
<img width="756" height="611" alt="image"
src="https://github.com/user-attachments/assets/f8e6be57-55ec-45be-9c14-cf76b4ea64d0"
/>

Logged in #990

### Todo list

- Figure out how to pass these react components as children of the
`OverlayRenderer` or `DeckFirstRenderer` (depends on
#921)
- Use the refactored model initialization from
#923 to create the list
of control instances on the deck side
- Integrate more cleanly into the Python API (an extension of
#908)

Closes #842, relevant
to #681

Author: kylebarron

lonboard/_map.py

@@ -13,6 +13,7 @@
 from lonboard._html_export import map_to_html
 from lonboard._viewport import compute_view
 from lonboard.basemap import CartoStyle, MaplibreBasemap
+from lonboard.controls import BaseControl
 from lonboard.layer import BaseLayer
 from lonboard.traits import HeightTrait, VariableLengthTuple, ViewStateTrait
 from lonboard.traits._map import DEFAULT_INITIAL_VIEW_STATE
@@ -192,6 +193,12 @@ def on_click(self, callback: Callable, *, remove: bool = False) -> None:
     """One or more `Layer` objects to display on this map.
     """
 
+    controls = VariableLengthTuple(t.Instance(BaseControl)).tag(
+        sync=True,
+        **ipywidgets.widget_serialization,
+    )
+    """One or more map controls to display on this map."""
+
     views: t.Instance[BaseView | None] = t.Instance(BaseView, allow_none=True).tag(
         sync=True,
         **ipywidgets.widget_serialization,

lonboard/controls.py

@@ -2,13 +2,15 @@
 from functools import partial
 from typing import Any
 
-import traitlets
+import traitlets as t
 from ipywidgets import FloatRangeSlider
 from ipywidgets.widgets.trait_types import TypedTuple
 
 # Import from source to allow mkdocstrings to link to base class
 from ipywidgets.widgets.widget_box import VBox
 
+from lonboard._base import BaseWidget
+
 
 class MultiRangeSlider(VBox):
     """A widget for multiple ranged sliders.
@@ -62,7 +64,7 @@ class MultiRangeSlider(VBox):
     # We use a tuple to force reassignment to update the list
     # This is because list mutations do not get propagated as events
     # https://github.com/jupyter-widgets/ipywidgets/blob/b2531796d414b0970f18050d6819d932417b9953/python/ipywidgets/ipywidgets/widgets/widget_box.py#L52-L54
-    value = TypedTuple(trait=TypedTuple(trait=traitlets.Float())).tag(sync=True)
+    value = TypedTuple(trait=TypedTuple(trait=t.Float())).tag(sync=True)
 
     def __init__(self, children: Sequence[FloatRangeSlider], **kwargs: Any) -> None:
         """Create a new MultiRangeSlider."""
@@ -88,3 +90,74 @@ def callback(change: dict, *, i: int) -> None:
             initial_values.append(child.value)
 
         super().__init__(children, value=initial_values, **kwargs)
+
+
+class BaseControl(BaseWidget):
+    """A deck.gl or Maplibre Control."""
+
+    position = t.Union(
+        [
+            t.Unicode("top-left"),
+            t.Unicode("top-right"),
+            t.Unicode("bottom-left"),
+            t.Unicode("bottom-right"),
+        ],
+        allow_none=True,
+        default_value=None,
+    ).tag(sync=True)
+    """Position of the control in the map.
+    """
+
+
+class FullscreenControl(BaseControl):
+    """A deck.gl FullscreenControl."""
+
+    _control_type = t.Unicode("fullscreen").tag(sync=True)
+
+
+class NavigationControl(BaseControl):
+    """A deck.gl NavigationControl."""
+
+    _control_type = t.Unicode("navigation").tag(sync=True)
+
+    show_compass = t.Bool(allow_none=True, default_value=None).tag(sync=True)
+    """Whether to show the compass button.
+
+    Default `true`.
+    """
+
+    show_zoom = t.Bool(allow_none=True, default_value=None).tag(sync=True)
+    """Whether to show the zoom buttons.
+
+    Default `true`.
+    """
+
+    visualize_pitch = t.Bool(allow_none=True, default_value=None).tag(sync=True)
+    """Whether to enable pitch visualization.
+
+    Default `true`.
+    """
+
+    visualize_roll = t.Bool(allow_none=True, default_value=None).tag(sync=True)
+    """Whether to enable roll visualization.
+
+    Default `false`.
+    """
+
+
+class ScaleControl(BaseControl):
+    """A deck.gl ScaleControl."""
+
+    _control_type = t.Unicode("scale").tag(sync=True)
+
+    max_width = t.Int(allow_none=True, default_value=None).tag(sync=True)
+    """The maximum width of the scale control in pixels.
+
+    Default `100`.
+    """
+
+    unit = t.Unicode(allow_none=True, default_value=None).tag(sync=True)
+    """The unit of the scale.
+
+    One of `'metric'`, `'imperial'`, or `'nautical'`. Default is `'metric'`.
+    """

src/hooks/controls.ts

@@ -0,0 +1,41 @@
+import type { IWidgetManager, WidgetModel } from "@jupyter-widgets/base";
+import { useEffect, useState } from "react";
+
+import { BaseMapControlModel } from "../model";
+import { initializeChildModels } from "../model/index.js";
+import { initializeControl } from "../model/map-control";
+
+/**
+ * Hook to manage map controls state
+ */
+export function useControlsState(
+  controlsIds: string[],
+  widgetManager: IWidgetManager,
+  updateStateCallback: () => void,
+): BaseMapControlModel[] {
+  const [controlsState, setControlsState] = useState<
+    Record<string, BaseMapControlModel>
+  >({});
+
+  useEffect(() => {
+    const loadMapControls = async () => {
+      try {
+        const controlsModels = await initializeChildModels<BaseMapControlModel>(
+          widgetManager,
+          controlsIds,
+          controlsState,
+          async (model: WidgetModel) =>
+            initializeControl(model, updateStateCallback),
+        );
+
+        setControlsState(controlsModels);
+      } catch (error) {
+        console.error("Error loading controls:", error);
+      }
+    };
+
+    loadMapControls();
+  }, [controlsIds]);
+
+  return Object.values(controlsState);
+}

src/hooks/index.ts

@@ -1,3 +1,4 @@
 export { useBasemapState } from "./basemap.js";
+export { useControlsState } from "./controls.js";
 export { useLayersState } from "./layers.js";
 export { useViewsState } from "./views.js";

src/index.tsx

@@ -12,6 +12,7 @@ import { v4 as uuidv4 } from "uuid";
 import { flyTo } from "./actions/fly-to.js";
 import {
   useBasemapState,
+  useControlsState,
   useLayersState,
   useViewsState,
 } from "./hooks/index.js";
@@ -92,6 +93,7 @@ function App() {
   const [mapId] = useState(uuidv4());
   const [childLayerIds] = useModelState<string[]>("layers");
   const [viewIds] = useModelState<string | string[] | null>("views");
+  const [controlsIds] = useModelState<string[]>("controls");
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
   const [_selectedBounds, setSelectedBounds] = useModelState<number[] | null>(
     "selected_bounds",
@@ -132,6 +134,12 @@ function App() {
     updateStateCallback,
   );
 
+  const controls = useControlsState(
+    controlsIds,
+    model.widget_manager as IWidgetManager,
+    updateStateCallback,
+  );
+
   const layers = useLayersState(
     childLayerIds,
     model.widget_manager as IWidgetManager,
@@ -215,6 +223,7 @@ function App() {
     },
     parameters: parameters || {},
     views,
+    controls,
   };
 
   const overlayRenderProps: OverlayRendererProps = {

src/model/index.ts

@@ -13,4 +13,10 @@ export {
   PathStyleExtension,
   initializeExtension,
 } from "./extension.js";
+export {
+  BaseMapControlModel,
+  FullscreenControlModel,
+  NavigationControlModel,
+  ScaleControlModel,
+} from "./map-control.js";
 export { initializeChildModels } from "./initialize.js";

src/model/map-control.tsx

@@ -0,0 +1,161 @@
+import {
+  CompassWidget,
+  FullscreenWidget,
+  _ScaleWidget as ScaleWidget,
+  ZoomWidget,
+} from "@deck.gl/react";
+import type { WidgetModel } from "@jupyter-widgets/base";
+import React from "react";
+import {
+  FullscreenControl,
+  NavigationControl,
+  ScaleControl,
+} from "react-map-gl/maplibre";
+
+import { isDefined } from "../util";
+import { BaseModel } from "./base";
+
+export abstract class BaseMapControlModel extends BaseModel {
+  static controlType: string;
+
+  protected position?:
+    | "top-left"
+    | "top-right"
+    | "bottom-left"
+    | "bottom-right";
+
+  constructor(model: WidgetModel, updateStateCallback: () => void) {
+    super(model, updateStateCallback);
+
+    this.initRegularAttribute("position", "position");
+  }
+
+  baseDeckProps() {
+    return {
+      ...(isDefined(this.position) ? { placement: this.position } : {}),
+    };
+  }
+
+  baseMaplibreProps() {
+    return {
+      ...(isDefined(this.position) ? { position: this.position } : {}),
+    };
+  }
+
+  abstract renderDeck(): React.JSX.Element | null;
+  abstract renderMaplibre(): React.JSX.Element | null;
+}
+
+export class FullscreenControlModel extends BaseMapControlModel {
+  static controlType = "fullscreen";
+
+  constructor(model: WidgetModel, updateStateCallback: () => void) {
+    super(model, updateStateCallback);
+  }
+
+  renderDeck() {
+    const { placement, ...otherProps } = this.baseDeckProps();
+    const props = { placement: placement || "top-right", ...otherProps };
+    console.log(placement);
+    return <div>{<FullscreenWidget {...props} />}</div>;
+  }
+
+  renderMaplibre() {
+    return <div>{<FullscreenControl {...this.baseMaplibreProps()} />}</div>;
+  }
+}
+
+export class NavigationControlModel extends BaseMapControlModel {
+  static controlType = "navigation";
+
+  protected showCompass?: boolean;
+  protected showZoom?: boolean;
+  protected visualizePitch?: boolean;
+  protected visualizeRoll?: boolean;
+
+  constructor(model: WidgetModel, updateStateCallback: () => void) {
+    super(model, updateStateCallback);
+
+    this.initRegularAttribute("show_compass", "showCompass");
+    this.initRegularAttribute("show_zoom", "showZoom");
+    this.initRegularAttribute("visualize_pitch", "visualizePitch");
+    this.initRegularAttribute("visualize_roll", "visualizeRoll");
+  }
+
+  renderDeck() {
+    return (
+      <div>
+        {this.showZoom && <ZoomWidget {...this.baseDeckProps()} />}
+        {this.showCompass && <CompassWidget {...this.baseDeckProps()} />}
+      </div>
+    );
+  }
+
+  renderMaplibre() {
+    const props = {
+      ...this.baseMaplibreProps(),
+      ...(isDefined(this.showCompass) && { showCompass: this.showCompass }),
+      ...(isDefined(this.showZoom) && { showZoom: this.showZoom }),
+      ...(isDefined(this.visualizePitch) && {
+        visualizePitch: this.visualizePitch,
+      }),
+      ...(isDefined(this.visualizeRoll) && {
+        visualizeRoll: this.visualizeRoll,
+      }),
+    };
+    return <NavigationControl {...props} />;
+  }
+}
+
+export class ScaleControlModel extends BaseMapControlModel {
+  static controlType = "scale";
+
+  protected maxWidth?: number;
+  protected unit?: "imperial" | "metric" | "nautical";
+
+  constructor(model: WidgetModel, updateStateCallback: () => void) {
+    super(model, updateStateCallback);
+
+    this.initRegularAttribute("max_width", "maxWidth");
+    this.initRegularAttribute("unit", "unit");
+  }
+
+  renderDeck() {
+    return <ScaleWidget {...this.baseDeckProps()} />;
+  }
+
+  renderMaplibre() {
+    const props = {
+      ...this.baseMaplibreProps(),
+      ...(isDefined(this.maxWidth) && { maxWidth: this.maxWidth }),
+      ...(isDefined(this.unit) && { unit: this.unit }),
+    };
+    return <div>{<ScaleControl {...props} />}</div>;
+  }
+}
+
+export async function initializeControl(
+  model: WidgetModel,
+  updateStateCallback: () => void,
+): Promise<BaseMapControlModel> {
+  const controlType = model.get("_control_type");
+  let controlModel: BaseMapControlModel;
+  switch (controlType) {
+    case FullscreenControlModel.controlType:
+      controlModel = new FullscreenControlModel(model, updateStateCallback);
+      break;
+
+    case NavigationControlModel.controlType:
+      controlModel = new NavigationControlModel(model, updateStateCallback);
+      break;
+
+    case ScaleControlModel.controlType:
+      controlModel = new ScaleControlModel(model, updateStateCallback);
+      break;
+
+    default:
+      throw new Error(`no control supported for ${controlType}`);
+  }
+
+  return controlModel;
+}