@deck.gl/widgets 9.3.0-alpha.5 → 9.3.0-beta.1

package/src/geocoder-widget.tsx

@@ -48,6 +48,15 @@ export type GeocoderWidgetProps = WidgetProps & {
   apiKey?: string;
   /** Whether to use geolocation @note Experimental*/
   _geolocation?: boolean;
+  /**
+   * Callback when a location is geocoded and the view will navigate to it.
+   */
+  onGeocode?: (params: {
+    /** The view being updated */
+    viewId: string;
+    /** The geocoded coordinates */
+    coordinates: {longitude: number; latitude: number; zoom?: number};
+  }) => void;
 };
 
 /**
@@ -66,7 +75,8 @@ export class GeocoderWidget extends Widget<GeocoderWidgetProps> {
     geocoder: 'coordinates',
     customGeocoder: CoordinatesGeocoder,
     apiKey: '',
-    _geolocation: false
+    _geolocation: false,
+    onGeocode: () => {}
   };
 
   className = 'deck-widget-geocoder';
@@ -188,6 +198,18 @@ export class GeocoderWidget extends Widget<GeocoderWidgetProps> {
   flyTo(viewState: ViewState) {
     const viewIds = this.viewId ? [this.viewId] : (this.deck?.getViews().map(v => v.id) ?? []);
     for (const viewId of viewIds) {
+      // Call callback with geocoded coordinates
+      if ('longitude' in viewState && 'latitude' in viewState) {
+        this.props.onGeocode?.({
+          viewId,
+          coordinates: {
+            longitude: viewState.longitude as number,
+            latitude: viewState.latitude as number,
+            zoom: viewState.zoom as number | undefined
+          }
+        });
+      }
+
       const currentViewState = this.getViewState(viewId);
       const nextViewState: ViewState = {
         ...currentViewState,

package/src/gimbal-widget.tsx

@@ -16,6 +16,18 @@ export type GimbalWidgetProps = WidgetProps & {
   strokeWidth?: number;
   /** Transition duration in ms when resetting rotation. */
   transitionDuration?: number;
+  /**
+   * Callback when the gimbal reset button is clicked.
+   * Called for each viewport that will be reset.
+   */
+  onReset?: (params: {
+    /** The view being reset */
+    viewId: string;
+    /** The new rotationOrbit value (0) */
+    rotationOrbit: number;
+    /** The new rotationX value (0) */
+    rotationX: number;
+  }) => void;
 };
 
 export class GimbalWidget extends Widget<GimbalWidgetProps> {
@@ -26,7 +38,8 @@ export class GimbalWidget extends Widget<GimbalWidgetProps> {
     viewId: null,
     label: 'Gimbal',
     strokeWidth: 1.5,
-    transitionDuration: 200
+    transitionDuration: 200,
+    onReset: () => {}
   };
 
   className = 'deck-widget-gimbal';
@@ -122,6 +135,9 @@ export class GimbalWidget extends Widget<GimbalWidgetProps> {
     const viewId = this.viewId || viewport?.id || 'OrbitView';
     const viewState = this.getViewState(viewId);
     if ('rotationOrbit' in viewState || 'rotationX' in viewState) {
+      // Call callback
+      this.props.onReset?.({viewId, rotationOrbit: 0, rotationX: 0});
+
       const nextViewState = {
         ...viewState,
         rotationOrbit: 0,

package/src/loading-widget.tsx

@@ -15,6 +15,11 @@ export type LoadingWidgetProps = WidgetProps & {
   viewId?: string | null;
   /** Tooltip message when loading */
   label?: string;
+  /**
+   * Callback when the loading state changes.
+   * Called when layers transition between loading and loaded states.
+   */
+  onLoadingChange?: (loading: boolean) => void;
 };
 
 /**
@@ -26,7 +31,8 @@ export class LoadingWidget extends Widget<LoadingWidgetProps> {
     id: 'loading',
     placement: 'top-left',
     viewId: null,
-    label: 'Loading layer data'
+    label: 'Loading layer data',
+    onLoadingChange: () => {}
   };
 
   className = 'deck-widget-loading';
@@ -62,6 +68,10 @@ export class LoadingWidget extends Widget<LoadingWidgetProps> {
     const loading = layers.some(layer => !layer.isLoaded);
     if (loading !== this.loading) {
       this.loading = loading;
+
+      // Call callback when loading state changes
+      this.props.onLoadingChange?.(loading);
+
       this.updateHTML();
     }
   }

package/src/reset-view-widget.tsx

@@ -21,6 +21,15 @@ export type ResetViewWidgetProps<ViewsT extends ViewOrViews = null> = WidgetProp
   initialViewState?: ViewStateMap<ViewsT>;
   /** View to interact with. Required when using multiple views. */
   viewId?: string | null;
+  /**
+   * Callback when the reset view button is clicked.
+   */
+  onReset?: (params: {
+    /** The view being reset */
+    viewId: string;
+    /** The view state being reset to */
+    viewState: Record<string, unknown>;
+  }) => void;
 };
 
 /**
@@ -36,7 +45,8 @@ export class ResetViewWidget<ViewsT extends ViewOrViews = null> extends Widget<
     placement: 'top-left',
     label: 'Reset View',
     initialViewState: undefined!,
-    viewId: null
+    viewId: null,
+    onReset: () => {}
   };
 
   className = 'deck-widget-reset-view';
@@ -78,6 +88,10 @@ export class ResetViewWidget<ViewsT extends ViewOrViews = null> extends Widget<
         // transitionDuration: this.props.transitionDuration,
         // transitionInterpolator: new FlyToInterpolator()
       };
+
+      // Call callback
+      this.props.onReset?.({viewId, viewState: nextViewState as Record<string, unknown>});
+
       this.setViewState(viewId, nextViewState);
     }
   }

package/src/stats-widget.tsx

@@ -38,7 +38,7 @@ export type StatsWidgetProps = WidgetProps & {
   /** Expand the stats UI by default.
    * @default false
    */
-  defaultIsExpanded?: boolean;
+  initialExpanded?: boolean;
   /** Stats object to visualize. */
   stats?: Stats;
   /** Title shown in the header of the pop-up. Defaults to stats.id. */
@@ -49,6 +49,15 @@ export type StatsWidgetProps = WidgetProps & {
   formatters?: Record<string, string | ((stat: Stat) => string)>;
   /** Whether to reset particular stats after each update. */
   resetOnUpdate?: Record<string, boolean>;
+  /**
+   * Controlled expanded state. When provided, the widget is in controlled mode.
+   */
+  expanded?: boolean;
+  /**
+   * Callback when the expanded state changes (user clicks header).
+   * In controlled mode, use this to update the expanded prop.
+   */
+  onExpandedChange?: (expanded: boolean) => void;
 };
 
 /** Displays probe.gl stats in a floating pop-up. */
@@ -58,13 +67,15 @@ export class StatsWidget extends Widget<StatsWidgetProps> {
     type: 'deck',
     placement: 'top-left',
     viewId: null,
-    defaultIsExpanded: false,
+    initialExpanded: false,
     stats: undefined!,
     title: 'Stats',
     framesPerUpdate: 1,
     formatters: {},
     resetOnUpdate: {},
-    id: 'stats'
+    id: 'stats',
+    expanded: undefined!,
+    onExpandedChange: () => {}
   };
 
   className = 'deck-widget-stats';
@@ -73,13 +84,22 @@ export class StatsWidget extends Widget<StatsWidgetProps> {
   private _counter = 0;
   private _formatters: Record<string, (stat: Stat) => string>;
   private _resetOnUpdate: Record<string, boolean>;
-  collapsed: boolean = true;
+  private _expanded: boolean = false;
+
+  /**
+   * Returns the current expanded state.
+   * In controlled mode, returns the expanded prop.
+   * In uncontrolled mode, returns the internal state.
+   */
+  getExpanded(): boolean {
+    return this.props.expanded ?? this._expanded;
+  }
 
   constructor(props: StatsWidgetProps = {}) {
     super(props);
     this._formatters = {...DEFAULT_FORMATTERS};
     this._resetOnUpdate = {...this.props.resetOnUpdate};
-    this.collapsed = !props.defaultIsExpanded;
+    this._expanded = Boolean(props.initialExpanded);
     this.setProps(props);
   }
 
@@ -107,9 +127,9 @@ export class StatsWidget extends Widget<StatsWidgetProps> {
   }
 
   onRenderHTML(rootElement: HTMLElement): void {
-    const collapsed = this.collapsed;
-    if (collapsed) {
-      render(<FpsIcon getFps={this._getFps} onClick={this._toggleCollapsed} />, rootElement);
+    const isExpanded = this.getExpanded();
+    if (!isExpanded) {
+      render(<FpsIcon getFps={this._getFps} onClick={this._toggleExpanded} />, rootElement);
       return;
     }
 
@@ -139,7 +159,7 @@ export class StatsWidget extends Widget<StatsWidgetProps> {
         <div
           className="deck-widget-stats-header"
           style={{cursor: 'pointer', pointerEvents: 'auto'}}
-          onClick={this._toggleCollapsed}
+          onClick={this._toggleExpanded}
         >
           <b>{title}</b>
           {deviceLabel && <span className="deck-widget-stats-device">{deviceLabel}</span>}
@@ -154,7 +174,7 @@ export class StatsWidget extends Widget<StatsWidgetProps> {
   }
 
   onRedraw(): void {
-    if (!this.collapsed) {
+    if (this.getExpanded()) {
       const framesPerUpdate = Math.max(1, this.props.framesPerUpdate || 1);
       if (this._counter++ % framesPerUpdate === 0) {
         this.updateHTML();
@@ -182,9 +202,18 @@ export class StatsWidget extends Widget<StatsWidgetProps> {
     }
   }
 
-  protected _toggleCollapsed = (): void => {
-    this.collapsed = !this.collapsed;
-    this.updateHTML();
+  protected _toggleExpanded = (): void => {
+    const nextExpanded = !this.getExpanded();
+
+    // Always call callback if provided
+    this.props.onExpandedChange?.(nextExpanded);
+
+    // Only update internal state if uncontrolled
+    if (this.props.expanded === undefined) {
+      this._expanded = nextExpanded;
+      this.updateHTML();
+    }
+    // In controlled mode, parent will update expanded prop which triggers updateHTML via setProps
   };
 
   protected _getFps = (): number => {

package/src/theme-widget.tsx

@@ -23,8 +23,19 @@ export type ThemeWidgetProps = WidgetProps & {
   darkModeLabel?: string;
   /** Styles for dark mode theme */
   darkModeTheme?: DeckWidgetTheme;
-  /** Initial theme mode. 'auto' reads the browser default setting */
+  /** Initial theme mode for uncontrolled usage. 'auto' reads the browser default setting */
   initialThemeMode?: 'auto' | 'light' | 'dark';
+  /**
+   * Controlled theme mode. When provided, the widget is in controlled mode
+   * and this prop determines the current theme.
+   */
+  themeMode?: 'light' | 'dark';
+  /**
+   * Callback when the user clicks the theme toggle button.
+   * In controlled mode, use this to update the themeMode prop.
+   * In uncontrolled mode, this is called after the internal state updates.
+   */
+  onThemeModeChange?: (newMode: 'light' | 'dark') => void;
 };
 
 export class ThemeWidget extends Widget<ThemeWidgetProps> {
@@ -37,7 +48,9 @@ export class ThemeWidget extends Widget<ThemeWidgetProps> {
     lightModeTheme: LightGlassTheme,
     darkModeLabel: 'Dark Mode',
     darkModeTheme: DarkGlassTheme,
-    initialThemeMode: 'auto'
+    initialThemeMode: 'auto',
+    themeMode: undefined!,
+    onThemeModeChange: () => {}
   };
 
   className = 'deck-widget-theme';
@@ -52,36 +65,44 @@ export class ThemeWidget extends Widget<ThemeWidgetProps> {
 
   // eslint-disable-next-line complexity
   setProps(props: Partial<ThemeWidgetProps>) {
-    const {lightModeTheme, darkModeTheme} = this.props;
+    const {lightModeTheme, darkModeTheme, themeMode: prevThemeMode} = this.props;
     this.placement = props.placement ?? this.placement;
     this.viewId = props.viewId ?? this.viewId;
     super.setProps(props);
 
-    switch (this.themeMode) {
+    const currentMode = this.getThemeMode();
+
+    // Handle controlled mode - apply theme when controlled prop changes
+    if (props.themeMode !== undefined && props.themeMode !== prevThemeMode) {
+      this._applyTheme(props.themeMode);
+      return;
+    }
+
+    switch (currentMode) {
       case 'light':
         if (props.lightModeTheme && !deepEqual(props.lightModeTheme, lightModeTheme, 1)) {
-          this._setThemeMode('light');
+          this._applyTheme('light');
         }
         break;
       case 'dark':
         if (props.darkModeTheme && !deepEqual(props.darkModeTheme, darkModeTheme, 1)) {
-          this._setThemeMode('dark');
+          this._applyTheme('dark');
         }
         break;
       default:
-        log.warn(`Invalid theme mode ${this.themeMode}`)();
+        log.warn(`Invalid theme mode ${currentMode}`)();
     }
   }
 
   onRenderHTML(rootElement: HTMLElement): void {
     const {lightModeLabel, darkModeLabel} = this.props;
-    // const onClick = useCallback(this._handleClick.bind(this), [this._handleClick]);
+    const currentMode = this.getThemeMode();
 
     render(
       <IconButton
         onClick={this._handleClick.bind(this)}
-        label={this.themeMode === 'dark' ? darkModeLabel : lightModeLabel}
-        className={this.themeMode === 'dark' ? 'deck-widget-moon' : 'deck-widget-sun'}
+        label={currentMode === 'dark' ? darkModeLabel : lightModeLabel}
+        className={currentMode === 'dark' ? 'deck-widget-moon' : 'deck-widget-sun'}
       />,
       rootElement
     );
@@ -89,24 +110,42 @@ export class ThemeWidget extends Widget<ThemeWidgetProps> {
 
   onAdd() {
     // Note: theme styling is applied in here onAdd() once DOM element is created
-    this._setThemeMode(this.themeMode);
+    this._applyTheme(this.getThemeMode());
+  }
+
+  /**
+   * Returns the current theme mode.
+   * In controlled mode, returns the themeMode prop.
+   * In uncontrolled mode, returns the internal state.
+   */
+  getThemeMode(): 'light' | 'dark' {
+    return this.props.themeMode ?? this.themeMode;
   }
 
   _handleClick() {
-    const newThemeMode = this.themeMode === 'dark' ? 'light' : 'dark';
-    this._setThemeMode(newThemeMode);
+    const currentMode = this.getThemeMode();
+    const nextMode = currentMode === 'dark' ? 'light' : 'dark';
+
+    // Always call callback if provided
+    this.props.onThemeModeChange?.(nextMode);
+
+    // Only update internal state if uncontrolled
+    if (this.props.themeMode === undefined) {
+      this.themeMode = nextMode;
+      this._applyTheme(nextMode);
+    }
+    // In controlled mode, parent will update themeMode prop which triggers _applyTheme via setProps
   }
 
-  _setThemeMode(themeMode: 'light' | 'dark') {
-    this.themeMode = themeMode;
+  /** Apply theme styling without changing internal state */
+  _applyTheme(themeMode: 'light' | 'dark') {
     const container = this.rootElement?.closest<HTMLDivElement>('.deck-widget-container');
     if (container) {
       const themeStyle =
         themeMode === 'dark' ? this.props.darkModeTheme : this.props.lightModeTheme;
       applyStyles(container, themeStyle);
 
-      const label =
-        this.themeMode === 'dark' ? this.props.darkModeLabel : this.props.lightModeLabel;
+      const label = themeMode === 'dark' ? this.props.darkModeLabel : this.props.lightModeLabel;
       log.log(1, `Switched theme to ${label}`, themeStyle)();
 
       this.updateHTML();

package/src/timeline-widget.tsx

@@ -21,11 +21,16 @@ export type TimelineWidgetProps = WidgetProps & {
    * @default 1
    */
   step?: number;
-  /** Initial slider value.
+  /** Initial slider value for uncontrolled usage.
    * @default `timeRange[0]`
    */
   initialTime?: number;
-  /** Callback when value changes. */
+  /**
+   * Controlled time value. When provided, the widget is in controlled mode
+   * for the time slider.
+   */
+  time?: number;
+  /** Callback when time value changes (via slider or playback). */
   onTimeChange?: (value: number) => void;
   /** Start playing automatically
    * @default false
@@ -39,6 +44,16 @@ export type TimelineWidgetProps = WidgetProps & {
    * @default 1000
    */
   playInterval?: number;
+  /**
+   * Controlled playing state. When provided, the widget is in controlled mode
+   * for play/pause.
+   */
+  playing?: boolean;
+  /**
+   * Callback when play/pause button is clicked.
+   * In controlled mode, use this to update the playing prop.
+   */
+  onPlayingChange?: (playing: boolean) => void;
   /** Callback to get label from time value */
   formatLabel?: (value: number) => string;
 };
@@ -48,10 +63,28 @@ export class TimelineWidget extends Widget<TimelineWidgetProps> {
   className = 'deck-widget-timeline';
   placement: WidgetPlacement = 'fill';
 
-  private playing = false;
+  private _playing = false;
   private timerId: number | null = null;
   currentTime: number;
 
+  /**
+   * Returns the current time value.
+   * In controlled mode, returns the time prop.
+   * In uncontrolled mode, returns the internal state.
+   */
+  getTime(): number {
+    return this.props.time ?? this.currentTime;
+  }
+
+  /**
+   * Returns the current playing state.
+   * In controlled mode, returns the playing prop.
+   * In uncontrolled mode, returns the internal state.
+   */
+  getPlaying(): boolean {
+    return this.props.playing ?? this._playing;
+  }
+
   static defaultProps: Required<TimelineWidgetProps> = {
     ...Widget.defaultProps,
     id: 'timeline',
@@ -61,29 +94,56 @@ export class TimelineWidget extends Widget<TimelineWidgetProps> {
     timeRange: [0, 100],
     step: 1,
     initialTime: undefined!,
+    time: undefined!,
     onTimeChange: () => {},
     autoPlay: false,
     loop: false,
     playInterval: 1000,
+    playing: undefined!,
+    onPlayingChange: () => {},
     formatLabel: String
   };
 
   constructor(props: TimelineWidgetProps = {}) {
     super(props);
     this.currentTime = this.props.initialTime ?? this.props.timeRange[0];
-    this.props.timeline?.setTime(this.currentTime);
+    // In controlled mode, sync Timeline to the controlled time prop
+    const syncTime = this.props.time ?? this.currentTime;
+    this.props.timeline?.setTime(syncTime);
     this.setProps(this.props);
   }
 
   setProps(props: Partial<TimelineWidgetProps>): void {
+    const {playing: prevPlaying, time: prevTime} = this.props;
     this.viewId = props.viewId ?? this.viewId;
     super.setProps(props);
+
+    // Sync Timeline object when controlled time prop changes
+    if (props.time !== undefined && props.time !== prevTime) {
+      this.props.timeline?.setTime(props.time);
+    }
+
+    // Handle controlled playing state changes
+    if (props.playing !== undefined && props.playing !== prevPlaying) {
+      if (props.playing && !this._playing) {
+        this._startTimer();
+      } else if (!props.playing && this._playing) {
+        this._stopTimer();
+      }
+    }
   }
 
   onAdd(): void {
-    this.playing = false;
+    this._playing = false;
     this.timerId = null;
-    if (this.props.autoPlay) this.play();
+    if (this.props.autoPlay) {
+      if (this.props.playing !== undefined) {
+        // In controlled mode, notify parent instead of starting directly
+        this.props.onPlayingChange?.(true);
+      } else {
+        this.play();
+      }
+    }
   }
 
   onRemove(): void {
@@ -92,13 +152,14 @@ export class TimelineWidget extends Widget<TimelineWidgetProps> {
 
   onRenderHTML(rootElement: HTMLElement): void {
     const {timeRange, step, formatLabel} = this.props;
-    const currentTime = this.currentTime;
+    const isPlaying = this.getPlaying();
+    const currentTime = this.getTime();
 
     rootElement.dataset.placement = this.props.placement;
 
     render(
       <div className="deck-widget-button-group">
-        {this.playing ? (
+        {isPlaying ? (
           <IconButton
             label="Pause"
             className="deck-widget-timeline-pause"
@@ -135,40 +196,69 @@ export class TimelineWidget extends Widget<TimelineWidgetProps> {
   }
 
   private handlePlayPause = (): void => {
-    if (this.playing) {
-      this.stop();
-    } else {
-      this.play();
+    const isPlaying = this.getPlaying();
+    const nextPlaying = !isPlaying;
+
+    // Always call callback if provided
+    this.props.onPlayingChange?.(nextPlaying);
+
+    // Only update internal state if uncontrolled
+    if (this.props.playing === undefined) {
+      if (nextPlaying) {
+        this.play();
+      } else {
+        this.stop();
+      }
     }
+    // In controlled mode, parent will update playing prop which triggers start/stop via setProps
   };
 
   private handleTimeChange = ([value]: [number, number]): void => {
-    this.currentTime = value;
-    this.props.timeline?.setTime(value);
+    // Always call callback
     this.props.onTimeChange(value);
-    this.updateHTML();
+
+    // Only update internal state if uncontrolled
+    if (this.props.time === undefined) {
+      this.currentTime = value;
+      this.props.timeline?.setTime(value);
+      this.updateHTML();
+    }
+    // In controlled mode, parent will update time prop which triggers updateHTML via setProps
   };
 
   public play(): void {
-    this.playing = true;
+    this._playing = true;
     const {
       timeRange: [min, max]
     } = this.props;
-    if (this.currentTime >= max) {
+    // In uncontrolled mode, reset to start if at end
+    if (this.props.time === undefined && this.getTime() >= max) {
       this.currentTime = min;
       this.props.onTimeChange(min);
+      this.props.timeline?.setTime(min);
     }
     this.updateHTML();
     this.tick();
   }
 
   public stop(): void {
-    this.playing = false;
+    this._stopTimer();
+    this.updateHTML();
+  }
+
+  /** Start the playback timer (used internally) */
+  private _startTimer(): void {
+    this._playing = true;
+    this.tick();
+  }
+
+  /** Stop the playback timer (used internally) */
+  private _stopTimer(): void {
+    this._playing = false;
     if (this.timerId !== null) {
       window.clearTimeout(this.timerId);
       this.timerId = null;
     }
-    this.updateHTML();
   }
 
   private tick = (): void => {
@@ -178,22 +268,31 @@ export class TimelineWidget extends Widget<TimelineWidgetProps> {
       loop
     } = this.props;
     if (step > 0) {
-      let next = Math.round(this.currentTime / step) * step + step;
+      const currentTime = this.getTime();
+      let next = Math.round(currentTime / step) * step + step;
       if (next > max) {
-        if (this.currentTime < max) {
+        if (currentTime < max) {
           next = max;
         } else if (loop) {
           next = min;
         } else {
           next = max;
-          this.playing = false;
+          this._playing = false;
+          this.props.onPlayingChange?.(false);
         }
       }
-      this.currentTime = next;
+
+      // Always call callback
       this.props.onTimeChange(next);
+
+      // Only update internal state if uncontrolled
+      if (this.props.time === undefined) {
+        this.currentTime = next;
+        this.props.timeline?.setTime(next);
+      }
       this.updateHTML();
     }
-    if (this.playing) {
+    if (this._playing) {
       this.timerId = window.setTimeout(this.tick, this.props.playInterval);
     } else {
       this.timerId = null;