perf(widget-builder): Store pending URL updates in a ref to prevent re-renders (#101878)

This is a tangential improvement for the Widget Builder that I spotted
while trying to improve how fast it opens. Updating a field in the
Widget Builder queues two actions

1. Immediately update the widget builder state context
2. Debounce updating the URL to match the state

Unfortunately, the second step is done in a context, and queuing a URL
update also updates a state, which causes a re-render of the whole
builder. This is visible in the React Profiler, you can see two large
renders. The former is caused by `WidgetBuilderStateProvider` and the
latter by `URLParamBatchProvider`.

**Before:**
<img width="570" height="53" alt="Screenshot 2025-10-21 at 3 09 05 PM"
src="https://github.com/user-attachments/assets/bfc340fb-45c4-4177-a395-f99b09cfd0fa"
/>


In this PR I'm making a few small changes:

1. The pending URL updates are stored in a `ref` instead of state.
Updating the ref does not cause a re-render, nor does it invalidate any
callbacks that use the pending updates as a dependency
2. The debounced URL updater is called _immediately_ in the updater
function, rather than relying on a `useEffect` triggered by the state
update. This is simpler, and is generally a better pattern, even the
React docs recommend that events are not expressed as effects.

React profiler shows the change, the second large render is missing. In
the Chrome profiler, the story is a bit more muddy. For whatever reason,
the speedup is not as obvious, it's only about 50ms, which is less than
the render duration. I'm chalking this up to discrepancies between the
profilers, and profiler overhead.

**After:**
<img width="270" height="51" alt="Screenshot 2025-10-21 at 3 10 31 PM"
src="https://github.com/user-attachments/assets/6cf197ab-6045-454f-a004-0ee623632cc2"
/>

I also updated the mock for `lodash/debounce`. `debounce` does not work
correctly with Jest's timer mocks, we usually mock this out. I'm not
sure why the previous tests pass, to be honest!

Author: gggritso

static/app/utils/url/testUtils.tsx

@@ -0,0 +1,25 @@
+/**
+ * A debounce function that has the same API as lodash debounce, but can be advanced via Jest timer mocks.
+ */
+export function testableDebounce(callback: () => void, delay?: number) {
+  let timeoutId: ReturnType<typeof setTimeout> | null = null;
+
+  const debounced = () => {
+    if (timeoutId) clearTimeout(timeoutId);
+    timeoutId = setTimeout(() => callback(), delay);
+  };
+
+  const cancel = () => {
+    if (timeoutId) clearTimeout(timeoutId);
+  };
+
+  const flush = () => {
+    if (timeoutId) clearTimeout(timeoutId);
+    callback();
+  };
+
+  debounced.cancel = cancel;
+  debounced.flush = flush;
+
+  return debounced;
+}

static/app/utils/url/urlParamBatchContext.spec.tsx

@@ -1,6 +1,7 @@
+import debounce from 'lodash/debounce';
 import {LocationFixture} from 'sentry-fixture/locationFixture';
 
-import {act, renderHook} from 'sentry-test/reactTestingLibrary';
+import {renderHook} from 'sentry-test/reactTestingLibrary';
 
 import {
   UrlParamBatchProvider,
@@ -9,20 +10,26 @@ import {
 import {useLocation} from 'sentry/utils/useLocation';
 import {useNavigate} from 'sentry/utils/useNavigate';
 
+import {testableDebounce} from './testUtils';
+
 jest.mock('sentry/utils/useLocation');
 jest.mock('sentry/utils/useNavigate');
+jest.mock('lodash/debounce');
 
 describe('UrlParamBatchProvider', () => {
   let mockNavigate: jest.Mock;
+
   beforeEach(() => {
     mockNavigate = jest.fn();
     jest.mocked(useNavigate).mockReturnValue(mockNavigate);
+    jest.mocked(debounce).mockImplementation(testableDebounce);
     jest.useFakeTimers();
   });
 
   afterEach(() => {
     jest.clearAllMocks();
-    jest.clearAllTimers();
+    jest.runOnlyPendingTimers();
+    jest.useRealTimers();
   });
 
   it('should batch updates to the URL query params', () => {
@@ -32,14 +39,10 @@ describe('UrlParamBatchProvider', () => {
     });
     const {batchUrlParamUpdates} = result.current;
 
-    act(() => {
-      batchUrlParamUpdates({foo: 'bar'});
-      batchUrlParamUpdates({potato: 'test'});
-    });
+    batchUrlParamUpdates({foo: 'bar'});
+    batchUrlParamUpdates({potato: 'test'});
 
-    act(() => {
-      jest.runAllTimers();
-    });
+    jest.runAllTimers();
 
     expect(mockNavigate).toHaveBeenCalledTimes(1);
     expect(mockNavigate).toHaveBeenCalledWith(

static/app/utils/url/urlParamBatchContext.tsx

@@ -1,14 +1,6 @@
-import {
-  createContext,
-  useCallback,
-  useContext,
-  useEffect,
-  useMemo,
-  useState,
-} from 'react';
+import {createContext, useCallback, useContext, useEffect, useMemo, useRef} from 'react';
 import debounce from 'lodash/debounce';
 
-import {DEFAULT_DEBOUNCE_DURATION} from 'sentry/constants';
 import {useLocation} from 'sentry/utils/useLocation';
 import {useNavigate} from 'sentry/utils/useNavigate';
 
@@ -22,50 +14,67 @@ const BatchContext = createContext<BatchContextType | null>(null);
 export function UrlParamBatchProvider({children}: {children: React.ReactNode}) {
   const navigate = useNavigate();
   const location = useLocation();
-  const [pendingUpdates, setPendingUpdates] = useState<
-    Record<string, string | string[] | undefined>
-  >({});
 
-  const batchUrlParamUpdates = useCallback(
-    (updates: Record<string, string | string[] | undefined>) => {
-      setPendingUpdates(current => ({...current, ...updates}));
-    },
-    []
-  );
+  // Store the pending updates in a `ref`. This way, queuing more updates
+  // doesn't update any state, so the context doesn't re-render and cause a
+  // re-render of all its subscribers.
+  const pendingUpdates = useRef<Record<string, string | string[] | undefined>>({});
 
   const flushUpdates = useCallback(() => {
-    if (Object.keys(pendingUpdates).length === 0) {
+    if (Object.keys(pendingUpdates.current).length === 0) {
       return;
     }
+
     navigate(
       {
         ...location,
         query: {
           ...location.query,
-          ...pendingUpdates,
+          ...pendingUpdates.current,
         },
       },
 
       // TODO: Use replace until we can sync the state of the widget
       // when the user navigates back
       {replace: true, preventScrollReset: true}
     );
-    setPendingUpdates({});
-  }, [location, navigate, pendingUpdates]);
+    pendingUpdates.current = {};
+  }, [location, navigate]);
 
-  // Debounce URL updates
+  // Debounced URL updater function
   const updateURL = useMemo(
     () =>
       debounce(() => {
+        // Flush all current pending URL query parameter updates
         flushUpdates();
-      }, DEFAULT_DEBOUNCE_DURATION),
+      }, URL_UPDATE_DEBOUNCE),
     [flushUpdates]
   );
 
-  // Trigger the URL updates
+  const batchUrlParamUpdates = useCallback(
+    (updates: Record<string, string | string[] | undefined>) => {
+      // Immediate update the pending URL query parameter updates
+      pendingUpdates.current = {
+        ...pendingUpdates.current,
+        ...updates,
+      };
+
+      // Immediately calls the debounced URL updater function
+      updateURL();
+    },
+    [updateURL]
+  );
+
+  // Cancel pending changes during `useEffect` cleanup. All the dependencies are
+  // fairly stable, so this should _only_ happen on unmount. It's important to
+  // run this on unmount rather than on location change because this context
+  // might be mounted low in the tree, and might actually get unmounted during a
+  // location change it should be listening to.
   useEffect(() => {
-    updateURL();
-    return () => updateURL.cancel();
+    return () => {
+      updateURL.cancel();
+      pendingUpdates.current = {};
+    };
   }, [updateURL]);
 
   return (
@@ -80,3 +89,5 @@ export const useUrlBatchContext = () => {
   }
   return context;
 };
+
+const URL_UPDATE_DEBOUNCE = 300;

static/app/views/dashboards/widgetBuilder/components/widgetTemplatesList.spec.tsx

@@ -1,16 +1,19 @@
+import debounce from 'lodash/debounce';
 import {LocationFixture} from 'sentry-fixture/locationFixture';
 import {RouterFixture} from 'sentry-fixture/routerFixture';
 
 import {render, screen, userEvent, waitFor} from 'sentry-test/reactTestingLibrary';
 
 import {addErrorMessage} from 'sentry/actionCreators/indicator';
+import {testableDebounce} from 'sentry/utils/url/testUtils';
 import {useNavigate} from 'sentry/utils/useNavigate';
 import WidgetTemplatesList from 'sentry/views/dashboards/widgetBuilder/components/widgetTemplatesList';
 import {WidgetBuilderProvider} from 'sentry/views/dashboards/widgetBuilder/contexts/widgetBuilderContext';
 
 jest.mock('sentry/utils/useNavigate', () => ({
   useNavigate: jest.fn(),
 }));
+jest.mock('lodash/debounce');
 
 jest.mock('sentry/views/dashboards/widgetLibrary/data', () => ({
   getTopNConvertedDefaultWidgets: jest.fn(() => [
@@ -37,9 +40,13 @@ describe('WidgetTemplatesList', () => {
   const onSave = jest.fn();
 
   beforeEach(() => {
+    jest.useFakeTimers();
+
     const mockNavigate = jest.fn();
     mockUseNavigate.mockReturnValue(mockNavigate);
 
+    jest.mocked(debounce).mockImplementation(testableDebounce);
+
     MockApiClient.addMockResponse({
       url: '/organizations/org-slug/dashboards/widgets/',
       method: 'POST',
@@ -50,6 +57,8 @@ describe('WidgetTemplatesList', () => {
 
   afterEach(() => {
     jest.clearAllMocks();
+    jest.runOnlyPendingTimers();
+    jest.useRealTimers();
   });
 
   it('should render the widget templates list', async () => {
@@ -72,6 +81,8 @@ describe('WidgetTemplatesList', () => {
   });
 
   it('should render buttons when the user clicks on a widget template', async () => {
+    const user = userEvent.setup({advanceTimers: jest.advanceTimersByTime});
+
     render(
       <WidgetBuilderProvider>
         <WidgetTemplatesList
@@ -87,13 +98,17 @@ describe('WidgetTemplatesList', () => {
     );
 
     const widgetTemplate = await screen.findByText('Duration Distribution');
-    await userEvent.click(widgetTemplate);
+    await user.click(widgetTemplate);
+
+    jest.runAllTimers();
 
     expect(await screen.findByText('Customize')).toBeInTheDocument();
     expect(await screen.findByText('Add to dashboard')).toBeInTheDocument();
   });
 
   it('should put widget in url when clicking a template', async () => {
+    const user = userEvent.setup({advanceTimers: jest.advanceTimersByTime});
+
     const mockNavigate = jest.fn();
     mockUseNavigate.mockReturnValue(mockNavigate);
 
@@ -112,8 +127,10 @@ describe('WidgetTemplatesList', () => {
       }
     );
 
-    const widgetTemplate = await screen.findByText('Duration Distribution');
-    await userEvent.click(widgetTemplate);
+    const widgetTemplate = screen.getByText('Duration Distribution');
+    await user.click(widgetTemplate);
+
+    jest.runAllTimers();
 
     expect(mockNavigate).toHaveBeenLastCalledWith(
       expect.objectContaining({
@@ -130,6 +147,8 @@ describe('WidgetTemplatesList', () => {
   });
 
   it('should show error message when the widget fails to save', async () => {
+    const user = userEvent.setup({advanceTimers: jest.advanceTimersByTime});
+
     render(
       <WidgetBuilderProvider>
         <WidgetTemplatesList
@@ -145,9 +164,11 @@ describe('WidgetTemplatesList', () => {
     );
 
     const widgetTemplate = await screen.findByText('Duration Distribution');
-    await userEvent.click(widgetTemplate);
+    await user.click(widgetTemplate);
+
+    await user.click(await screen.findByText('Add to dashboard'));
 
-    await userEvent.click(await screen.findByText('Add to dashboard'));
+    jest.runAllTimers();
 
     await waitFor(() => {
       expect(addErrorMessage).toHaveBeenCalledWith('Unable to add widget');