feat(widgets): generic controls (#10090)

Author: Pessimistress

docs/api-reference/widgets/icon-widget.md

@@ -0,0 +1,60 @@
+# IconWidget
+
+<img src="https://img.shields.io/badge/from-v9.3-green.svg?style=flat-square" alt="from v9.3" />
+
+This widget renders a single icon button. Use it for simple actions that should live alongside the other built-in deck.gl widgets.
+
+## Usage
+
+
+```ts
+import {Deck} from '@deck.gl/core';
+import {IconWidget} from '@deck.gl/widgets';
+
+new Deck({
+  widgets: [
+    new IconWidget({
+      icon: `./action.svg`,
+      label: 'Custom action',
+      onClick: () => {
+        // do something
+      }
+    })
+  ]
+});
+```
+
+## Types
+
+### `IconWidgetProps` {#iconwidgetprops}
+
+The `IconWidget` accepts the generic [`WidgetProps`](../core/widget.md#widgetprops) and:
+
+#### `icon` (string, required) {#icon}
+
+Data URL used as the button icon mask.
+
+#### `label` (string, optional) {#label}
+
+Tooltip message displayed while hovering over the widget.
+
+#### `color` (string, optional) {#color}
+
+CSS color applied to the icon.
+
+#### `onClick` (function, optional) {#onclick}
+
+```ts
+() => void
+```
+
+Callback invoked when the button is clicked.
+
+## Styles
+
+The `IconWidget` uses the shared button theme variables described in the [styling guide](./styling.md).
+
+
+## Source
+
+[modules/widgets/src/icon-widget.tsx](https://github.com/visgl/deck.gl/tree/master/modules/widgets/src/icon-widget.tsx)

docs/api-reference/widgets/overview.md

@@ -20,7 +20,6 @@ This module contains the following widgets:
 
 - [FullscreenWidget](./fullscreen-widget.md)
 - [SplitterWidget](./splitter-widget.md)
-- [ViewSelectorWidget](./view-selector-widget.md)
 
 ### Information Widgets
 
@@ -29,6 +28,9 @@ This module contains the following widgets:
 
 ### Control Widgets
 
+- [IconWidget](./icon-widget.md)
+- [ToggleWidget](./toggle-widget.md)
+- [SelectorWidget](./selector-widget.md)
 - [TimelineWidget](./timeline-widget.md)
 
 ### Utility Widgets

docs/api-reference/widgets/selector-widget.md

@@ -0,0 +1,82 @@
+# SelectorWidget
+
+<img src="https://img.shields.io/badge/from-v9.3-green.svg?style=flat-square" alt="from v9.3" />
+
+This widget renders an icon button that opens a popover menu of selectable options. Each option provides an icon and an optional label, and the button updates to reflect the current selection.
+
+## Usage
+
+```ts
+import {Deck} from '@deck.gl/core';
+import {SelectorWidget} from '@deck.gl/widgets';
+
+new Deck({
+  widgets: [
+    new SelectorWidget({
+      initialValue: 'single',
+      options: [
+        {
+          value: 'single',
+          label: 'Single view',
+          icon: `./single-view.svg`
+        },
+        {
+          value: 'split-horizontal',
+          label: 'Split horizontal',
+          icon: `./split-views-horizontal.svg`
+        }
+      ],
+      onChange: value => {
+        console.log('selected:', value);
+      }
+    })
+  ]
+});
+```
+
+## Types
+
+### `SelectorWidgetProps` {#selectorwidgetprops}
+
+The `SelectorWidget` accepts the generic [`WidgetProps`](../core/widget.md#widgetprops) and:
+
+#### `options` (`SelectorWidgetOption[]`, required) {#options}
+
+Selectable options displayed in the popover menu.
+
+#### `initialValue` (any, optional) {#initialvalue}
+
+* Default: value of the first option
+
+Initial selected value. If it does not match any option, the first option is displayed.
+
+#### `onChange` (function, optional) {#onchange}
+
+```ts
+(value: ValueT) => void
+```
+
+Callback invoked when a new option is selected.
+
+### `SelectorWidgetOption` {#selectorwidgetoption}
+
+#### `value` (any, required) {#value}
+
+Value returned from `onChange` when this option is selected.
+
+#### `icon` (string, required) {#optionicon}
+
+Data URL used as the option icon mask.
+
+#### `label` (string, optional) {#optionlabel}
+
+Text shown in the menu and used as the button tooltip when selected.
+
+## Styles
+
+The `SelectorWidget` uses the shared button and menu theme variables described in the [styling guide](./styling.md).
+
+
+## Source
+
+[modules/widgets/src/selector-widget.tsx](https://github.com/visgl/deck.gl/tree/master/modules/widgets/src/selector-widget.tsx)

docs/api-reference/widgets/toggle-widget.md

@@ -0,0 +1,86 @@
+# ToggleWidget
+
+<img src="https://img.shields.io/badge/from-v9.3-green.svg?style=flat-square" alt="from v9.3" />
+
+This widget renders an icon button with internal on/off state. It is useful for lightweight toggles such as layer visibility, mode switches, or filter controls.
+
+## Usage
+
+
+```ts
+import {Deck} from '@deck.gl/core';
+import {ToggleWidget} from '@deck.gl/widgets';
+
+new Deck({
+  widgets: [
+    new ToggleWidget({
+      icon: `./play.png`,
+      onIcon: `./pause.png`,
+      label: 'Play',
+      onLabel: 'Pause',
+      onChange: checked => {
+        // do something
+      }
+    })
+  ]
+});
+```
+
+## Types
+
+### `ToggleWidgetProps` {#togglewidgetprops}
+
+The `ToggleWidget` accepts the generic [`WidgetProps`](../core/widget.md#widgetprops) and:
+
+#### `initialChecked` (boolean, optional) {#initialchecked}
+
+* Default: `false`
+
+Whether the widget starts in the checked state.
+
+#### `icon` (string, required) {#icon}
+
+Data URL used as the default button icon mask.
+
+#### `onIcon` (string, optional) {#onicon}
+
+* Default: same as `icon`
+
+Data URL used as the icon when the widget is checked.
+
+#### `label` (string, optional) {#label}
+
+Tooltip shown while the widget is unchecked.
+
+#### `onLabel` (string, optional) {#onlabel}
+
+* Default: same as `label`
+
+Tooltip shown while the widget is checked.
+
+#### `color` (string, optional) {#color}
+
+CSS color applied while the widget is unchecked.
+
+#### `onColor` (string, optional) {#oncolor}
+
+* Default: same as `color`
+
+CSS color applied while the widget is checked.
+
+#### `onChange` (function, optional) {#onchange}
+
+```ts
+(checked: boolean) => void
+```
+
+Callback invoked after the widget toggles state.
+
+## Styles
+
+The `ToggleWidget` uses the shared button theme variables described in the [styling guide](./styling.md).
+
+
+## Source
+
+[modules/widgets/src/toggle-widget.tsx](https://github.com/visgl/deck.gl/tree/master/modules/widgets/src/toggle-widget.tsx)

docs/api-reference/widgets/view-selector-widget.md

@@ -323,16 +323,18 @@
           "api-reference/widgets/geocoder-widget",
           "api-reference/widgets/gimbal-widget",
           "api-reference/widgets/info-widget",
+          "api-reference/widgets/icon-widget",
           "api-reference/widgets/loading-widget",
           "api-reference/widgets/popup-widget",
           "api-reference/widgets/reset-view-widget",
           "api-reference/widgets/scale-widget",
           "api-reference/widgets/screenshot-widget",
+          "api-reference/widgets/selector-widget",
           "api-reference/widgets/splitter-widget",
           "api-reference/widgets/stats-widget",
           "api-reference/widgets/theme-widget",
           "api-reference/widgets/timeline-widget",
-          "api-reference/widgets/view-selector-widget",
+          "api-reference/widgets/toggle-widget",
           "api-reference/widgets/zoom-widget"
         ]
       }

docs/table-of-contents.json

@@ -48,7 +48,7 @@ Target release date: September, 2025
   - [StatsWidget](./api-reference/widgets/stats-widget.md)
   - [ThemeWidget](./api-reference/widgets/theme-widget.md)
   - [TimelineWidget](./api-reference/widgets/timeline-widget.md)
-  - [ViewSelectorWidget](./api-reference/widgets/view-selector-widget.md)
+  - ViewSelectorWidget
 - Pre-wrapped React components - deck.gl widgets are available via the [`@deck.gl/react`](./api-reference/react/overview.md) package
 - Custom widgets in pydeck - via the `custom_libraries` parameter, Python users can integrate custom deck.gl widgets seamlessly
 - Documentation for styling and custom themes - see [Styling Widgets](./api-reference/widgets/styling)

docs/whats-new.md

@@ -15,14 +15,16 @@ export {InfoWidget as _InfoWidget} from './widgets/info-widget';
 export {PopupWidget} from './widgets/popup-widget';
 export {ContextMenuWidget as _ContextMenuWidget} from './widgets/context-menu-widget';
 export {ScrollbarWidget} from './widgets/scrollbar-widget';
+export {IconWidget} from './widgets/icon-widget';
+export {ToggleWidget} from './widgets/toggle-widget';
+export {SelectorWidget} from './widgets/selector-widget';
 export {LoadingWidget as _LoadingWidget} from './widgets/loading-widget';
 export {ResetViewWidget as _ResetViewWidget} from './widgets/reset-view-widget';
 export {ScaleWidget as _ScaleWidget} from './widgets/scale-widget';
 export {ScreenshotWidget as _ScreenshotWidget} from './widgets/screenshot-widget';
 export {SplitterWidget as _SplitterWidget} from './widgets/splitter-widget';
 export {ThemeWidget as _ThemeWidget} from './widgets/theme-widget';
 export {TimelineWidget as _TimelineWidget} from './widgets/timeline-widget';
-export {ViewSelectorWidget as _ViewSelectorWidget} from './widgets/view-selector-widget';
 export {StatsWidget as _StatsWidget} from './widgets/stats-widget';
 export {useWidget} from './utils/use-widget';
 export type {
@@ -35,14 +37,16 @@ export type {
   PopupWidgetProps,
   ContextMenuWidgetProps,
   ScrollbarWidgetProps,
+  IconWidgetProps,
+  ToggleWidgetProps,
+  SelectorWidgetProps,
   LoadingWidgetProps,
   ResetViewWidgetProps,
   ScaleWidgetProps,
   ScreenshotWidgetProps,
   SplitterWidgetProps,
   ThemeWidgetProps,
   TimelineWidgetProps,
-  ViewSelectorWidgetProps,
   StatsWidgetProps
 } from '@deck.gl/widgets';
 

modules/react/src/index.ts

@@ -0,0 +1,12 @@
+// deck.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {IconWidget as _IconWidget} from '@deck.gl/widgets';
+import type {IconWidgetProps} from '@deck.gl/widgets';
+import {useWidget} from '../utils/use-widget';
+
+export const IconWidget = (props: IconWidgetProps) => {
+  useWidget(_IconWidget, props);
+  return null;
+};