fix(react): Defer onLoad to ensure React widgets are available

- Intercept onLoad from Deck and defer it until after React widget
  children have registered via useWidget
- Use setTimeout(0) to escape React's commit phase, allowing callbacks
  to safely trigger state updates or nested act() calls
- Update tests to import act from 'react' instead of deprecated
  'react-dom/test-utils'
- Use shared gl context from @deck.gl/test-utils for all React tests

This ensures widgets are available on deck.props.widgets when the
onLoad callback fires, fixing the issue where onLoad fired before
React children had a chance to render and register their widgets.

Co-Authored-By: Claude (global.anthropic.claude-opus-4-5-20251101-v1:0) <noreply@anthropic.com>

Author: chrisgervang

modules/react/src/deckgl.ts

@@ -124,6 +124,9 @@ function DeckGLWithRef<ViewsT extends ViewOrViews = null>(
   const canvasRef = useRef(null);
   // Stable widgets array for React widget components (survives StrictMode remounts)
   const widgetsRef = useRef<Widget[]>([]);
+  // Track deferred onLoad - use state to trigger re-render when deck initializes
+  const [onLoadPending, setOnLoadPending] = useState(false);
+  const onLoadCalledRef = useRef(false);
 
   // extract any deck.gl layers masquerading as react elements from props.children
   const jsxProps = useMemo(
@@ -158,6 +161,14 @@ function DeckGLWithRef<ViewsT extends ViewOrViews = null>(
     }
   };
 
+  // Defer onLoad until after React widget children have had a chance to register.
+  // Deck's onLoad fires during initialization, before React children render.
+  // By using state to track pending status, we trigger a re-render when deck initializes,
+  // then call onLoad in useEffect after children have rendered and registered widgets.
+  const handleOnLoad: DeckProps<ViewsT>['onLoad'] = () => {
+    setOnLoadPending(true);
+  };
+
   // Update Deck's props. If Deck needs redraw, this will trigger a call to `_customRender` in
   // the next animation frame.
   // Needs to be called both from initial mount, and when new props are received
@@ -174,7 +185,10 @@ function DeckGLWithRef<ViewsT extends ViewOrViews = null>(
       layers: jsxProps.layers,
       views: jsxProps.views as ViewsT,
       onViewStateChange: handleViewStateChange,
-      onInteractionStateChange: handleInteractionStateChange
+      onInteractionStateChange: handleInteractionStateChange,
+      // Always provide onLoad handler - Deck expects it to be a function.
+      // The deferred effect will only call the user's callback if they provided one.
+      onLoad: handleOnLoad
     };
 
     // The defaultValue for _customRender is null, which would overwrite the definition
@@ -200,6 +214,24 @@ function DeckGLWithRef<ViewsT extends ViewOrViews = null>(
     return () => thisRef.deck?.finalize();
   }, []);
 
+  // Stable reference to onLoad callback for use in deferred effect
+  const onLoadRef = useRef(props.onLoad);
+  onLoadRef.current = props.onLoad;
+
+  // Call deferred onLoad after React widget children have registered.
+  // React guarantees parent effects run after children effects, so by this point
+  // any widgets using useWidget will have synced to deck.
+  // Use setTimeout(0) to escape React's commit phase and act() scope, allowing
+  // the callback to safely trigger state updates or nested act() calls in tests.
+  useEffect(() => {
+    if (onLoadPending && !onLoadCalledRef.current) {
+      onLoadCalledRef.current = true;
+      setTimeout(() => {
+        onLoadRef.current?.();
+      }, 0);
+    }
+  }, [onLoadPending]);
+
   useIsomorphicLayoutEffect(() => {
     // render has just been called. The children are positioned based on the current view state.
     // Redraw Deck canvas immediately, if necessary, using the current view state, so that it

test/modules/react/deckgl.spec.ts

@@ -4,14 +4,12 @@
 
 /* eslint-disable no-unused-vars */
 import test from 'tape-promise/tape';
-import {StrictMode, createElement, createRef} from 'react';
+import {StrictMode, createElement, createRef, act} from 'react';
 import {createRoot} from 'react-dom/client';
-import {act} from 'react-dom/test-utils';
 
 import {DeckGL, Layer, Widget} from 'deck.gl';
 import {useWidget} from '@deck.gl/react';
 import {type WidgetProps, type WidgetPlacement} from '@deck.gl/core';
-
 import {gl} from '@deck.gl/test-utils';
 
 const TEST_VIEW_STATE = {
@@ -22,10 +20,7 @@ const TEST_VIEW_STATE = {
   pitch: 45
 };
 
-// Reuse shared WebGL context from test-utils to avoid context exhaustion
-// gl is already set up by test-utils for both Node (headless) and browser
 /* global document */
-const getTestContext = () => gl;
 
 test('DeckGL#mount/unmount', t => {
   const ref = createRef();
@@ -40,7 +35,7 @@ test('DeckGL#mount/unmount', t => {
         ref,
         width: 100,
         height: 100,
-        gl: getTestContext(),
+        gl: gl,
         onLoad: () => {
           const {deck} = ref.current;
           t.ok(deck, 'DeckGL is initialized');
@@ -73,7 +68,7 @@ test('DeckGL#render', t => {
         viewState: TEST_VIEW_STATE,
         width: 100,
         height: 100,
-        gl: getTestContext(),
+        gl: gl,
         onAfterRender: () => {
           const child = container.querySelector('.child');
           t.ok(child, 'Child is rendered');
@@ -123,7 +118,7 @@ test('DeckGL#props omitted are reset', t => {
         ref,
         width: 100,
         height: 100,
-        gl: getTestContext(),
+        gl: gl,
         layers: LAYERS,
         widgets: WIDGETS,
         onLoad: () => {
@@ -187,9 +182,6 @@ test('useWidget#StrictMode cleanup removes duplicate widgets', t => {
   const container = document.createElement('div');
   document.body.append(container);
   const root = createRoot(container);
-  let testCompleted = false;
-  let renderCount = 0;
-  const MAX_RENDERS = 100; // Safety limit to prevent infinite loop
 
   act(() => {
     root.render(
@@ -203,41 +195,17 @@ test('useWidget#StrictMode cleanup removes duplicate widgets', t => {
             ref,
             width: 100,
             height: 100,
-            gl: getTestContext(),
-            // Use onAfterRender instead of onLoad because React widget children
-            // can only render after deck exists, and onLoad fires before that.
-            // Widget children need multiple render cycles to be positioned and registered:
-            // 1. First render: deck doesn't exist yet, children can't be positioned
-            // 2. useEffect creates deck
-            // 3. deck triggers forceUpdate, React re-renders
-            // 4. Children are now positioned and widget component can render
-            // 5. useWidget registers the widget and syncs to deck
-            onAfterRender: () => {
-              if (testCompleted) {
-                return;
-              }
-
-              renderCount++;
+            gl: gl,
+            // onLoad is deferred by the React wrapper until after widget children
+            // have registered, so widgets are available when this callback fires.
+            onLoad: () => {
               const deck = ref.current?.deck;
               const widgets = deck?.props.widgets;
 
-              // Wait for widget to render - children can only render after deck exists
-              // and React needs additional render cycles to position them
-              if (!deck || !widgets?.length) {
-                if (renderCount >= MAX_RENDERS) {
-                  t.fail('Widget did not render after maximum render attempts');
-                  act(() => root.render(null));
-                  container.remove();
-                  t.end();
-                }
-                return;
-              }
-
-              testCompleted = true;
               t.ok(deck, 'DeckGL is initialized');
               t.is(widgets?.length, 1, 'Only one widget instance remains after StrictMode remount');
 
-              // Clean up - don't wrap in act() to avoid nested act() errors
+              // Clean up
               root.render(null);
               container.remove();
               t.end();