fix(react): Fix StrictMode widget cleanup with deferred removal

- Use widget class defaultProps.id for lookup when props.id is undefined
- Defer cleanup removal with setTimeout(0) to allow StrictMode remount to cancel
- Cancel pending removals in both render and effect phases
- Fix spurious "widgets prop ignored" warning by checking for user-supplied widgets

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

Author: chrisgervang

modules/react/src/utils/use-widget.ts

@@ -4,10 +4,13 @@
 
 import {useContext, useRef, useEffect} from 'react';
 import {DeckGlContext} from './deckgl-context';
-import {log, Widget, type WidgetProps, _deepEqual as deepEqual} from '@deck.gl/core';
+import {log, Widget, type WidgetProps} from '@deck.gl/core';
+
+// Track pending removals by widget ID so they can be cancelled on remount
+const pendingRemovals = new Map<string, ReturnType<typeof setTimeout>>();
 
 export function useWidget<WidgetT extends Widget, WidgetPropsT extends WidgetProps>(
-  WidgetClass: {new (props_: WidgetPropsT): WidgetT},
+  WidgetClass: {new (props_: WidgetPropsT): WidgetT} & {defaultProps?: {id?: string}},
   props: WidgetPropsT
 ): WidgetT {
   const context = useContext(DeckGlContext);
@@ -18,9 +21,14 @@ export function useWidget<WidgetT extends Widget, WidgetPropsT extends WidgetPro
   // Instead, find existing widgets by ID to handle StrictMode's double-mount.
   const widgetRef = useRef<WidgetT | null>(null);
 
+  // Determine the widget ID: use props.id if provided, otherwise fall back to the class default
+  const widgetId = props.id ?? WidgetClass.defaultProps?.id;
+
   if (!widgetRef.current) {
     // Check if a widget with this ID already exists (from StrictMode's first mount)
-    const existingWidget = widgets?.find(w => w.id === props.id) as WidgetT | undefined;
+    const existingWidget = widgetId
+      ? (widgets?.find(w => w.id === widgetId) as WidgetT | undefined)
+      : undefined;
     if (existingWidget) {
       // Reuse the existing widget instance
       widgetRef.current = existingWidget;
@@ -31,6 +39,13 @@ export function useWidget<WidgetT extends Widget, WidgetPropsT extends WidgetPro
   }
   const widget = widgetRef.current;
 
+  // Cancel any pending removal for this widget (handles StrictMode remount)
+  const pendingRemoval = pendingRemovals.get(widget.id);
+  if (pendingRemoval) {
+    clearTimeout(pendingRemoval);
+    pendingRemovals.delete(widget.id);
+  }
+
   // Register widget during render for immediate availability (needed for onLoad callbacks)
   // Check by ID to prevent duplicates in StrictMode where refs are recreated
   const existingInArray = widgets?.find(w => w.id === widget.id);
@@ -42,28 +57,47 @@ export function useWidget<WidgetT extends Widget, WidgetPropsT extends WidgetPro
   widget.setProps(props);
 
   useEffect(() => {
+    // Cancel any pending removal for this widget (handles StrictMode effect remount).
+    // This must be in useEffect because StrictMode re-runs effects without re-rendering,
+    // so the render-phase cancellation won't run between cleanup and effect re-run.
+    const pendingRemovalInEffect = pendingRemovals.get(widget.id);
+    if (pendingRemovalInEffect) {
+      clearTimeout(pendingRemovalInEffect);
+      pendingRemovals.delete(widget.id);
+    }
+
     // Re-register widget if cleanup removed it (handles StrictMode remount after cleanup)
     if (widgets && !widgets.includes(widget)) {
       widgets.push(widget);
     }
 
-    // Warn if the user supplied a pure-js widget, since it will be ignored
-    // Check BEFORE setProps so we can compare the user's widgets with our React widgets
+    // Warn if the user supplied a pure-js widget via the widgets prop, since it will be ignored.
+    // Only warn if there are widgets in deck.props.widgets that aren't in our managed array.
+    // This avoids false positives from normal React sync timing differences.
     const internalWidgets = deck?.props.widgets;
-    if (widgets?.length && internalWidgets?.length && !deepEqual(internalWidgets, widgets, 1)) {
+    const hasUserSuppliedWidgets = internalWidgets?.some(w => !widgets?.includes(w));
+    if (widgets?.length && hasUserSuppliedWidgets) {
       log.warn('"widgets" prop will be ignored because React widgets are in use.')();
     }
 
     // Sync widgets to deck
     deck?.setProps({widgets: widgets ? [...widgets] : []});
 
     return () => {
-      // Remove widget from context when it is unmounted
-      const index = widgets?.indexOf(widget);
-      if (typeof index === 'number' && index !== -1) {
-        widgets?.splice(index, 1);
-        deck?.setProps({widgets: widgets ? [...widgets] : []});
-      }
+      // Defer widget removal to allow StrictMode remount to cancel it.
+      // In StrictMode, React unmounts and remounts effects to detect side effects.
+      // If we remove immediately, the remounted component can't find the widget.
+      // By deferring, we give the remount a chance to cancel the removal.
+      const id = widget.id;
+      const timeoutId = setTimeout(() => {
+        pendingRemovals.delete(id);
+        const index = widgets?.findIndex(w => w.id === id);
+        if (typeof index === 'number' && index !== -1) {
+          widgets?.splice(index, 1);
+          deck?.setProps({widgets: widgets ? [...widgets] : []});
+        }
+      }, 0);
+      pendingRemovals.set(id, timeoutId);
     };
   }, [widgets, deck, widget]);