fix(navigation): resolve performance issue (#1092)

The `blur`, `focus`, and `state` listeners all can perform heavy dom
mutations. Performing them at the same time the screen is rendering and
transitioning can cause delays or visual glitches. To resolve, these
listeners are delayed a small amount.

The use of `setTimeout` enables waiting for the screen to render before
mutating the dom. The `navStateMutationsDelay` experiment value is used
to enable the timeout. If the experiment is not set or has a value of
"0", no timeout is used. See
35499d9

| Before | After |
| -- | -- |
|
![before](https://github.com/user-attachments/assets/4563f32e-7c17-47ce-b1e9-d0eb4b50ad64)
|
![after](https://github.com/user-attachments/assets/0f1ab29e-8aed-4bf9-8ec0-c3845acd0960)
|


[Asana](https://app.asana.com/0/1204008699308084/1209403666139702)

src/core/components/hv-route/index.tsx

@@ -570,19 +570,31 @@ function HvRouteFC(props: Types.Props) {
 
       // Use the focus event to set the selected route
       const unsubscribeFocus: () => void = nav.addListener('focus', () => {
-        const doc = docContext?.getDoc();
-        NavigatorService.setSelected(doc, id, docContext?.setDoc);
-        NavigatorService.addStackRoute(
-          doc,
-          id,
-          props.route,
-          nav.getState().routes[0]?.name,
-          navigationContext.entrypointUrl,
-          docContext?.setDoc,
-        );
         if (navigationContext.onRouteFocus && props.route) {
           navigationContext.onRouteFocus(props.route);
         }
+        const navStateMutationsDelay =
+          navigationContext.experimentalFeatures?.navStateMutationsDelay || 0;
+        const updateRouteFocus = () => {
+          const doc = docContext?.getDoc();
+          NavigatorService.setSelected(doc, id, docContext?.setDoc);
+          NavigatorService.addStackRoute(
+            doc,
+            id,
+            props.route,
+            nav.getState().routes[0]?.name,
+            navigationContext.entrypointUrl,
+            docContext?.setDoc,
+          );
+        };
+        if (navStateMutationsDelay > 0) {
+          // The timeout ensures the processing occurs after the screen is rendered or shown
+          setTimeout(() => {
+            updateRouteFocus();
+          }, navStateMutationsDelay);
+        } else {
+          updateRouteFocus();
+        }
       });
 
       // Use the beforeRemove event to remove the route from the stack
@@ -621,12 +633,24 @@ function HvRouteFC(props: Types.Props) {
 
       // Update the urls in each route when the state updates the params
       const unsubscribeState: () => void = nav.addListener('state', event => {
-        NavigatorService.updateRouteUrlFromState(
-          docContext?.getDoc(),
-          id,
-          event.data?.state,
-          docContext?.setDoc,
-        );
+        const navStateMutationsDelay =
+          navigationContext.experimentalFeatures?.navStateMutationsDelay || 0;
+        const updateRouteUrlFromState = (e: NavigatorService.ListenerEvent) => {
+          NavigatorService.updateRouteUrlFromState(
+            docContext?.getDoc(),
+            id,
+            e.data?.state,
+            docContext?.setDoc,
+          );
+        };
+        if (navStateMutationsDelay > 0) {
+          // The timeout ensures the processing occurs after the screen is rendered or shown
+          setTimeout(() => {
+            updateRouteUrlFromState(event);
+          }, navStateMutationsDelay);
+        } else {
+          updateRouteUrlFromState(event);
+        }
       });
 
       return () => {

src/core/components/hv-route/types.ts

@@ -1,6 +1,7 @@
 import * as NavigatorService from 'hyperview/src/services/navigator';
 import { ComponentType, ReactNode } from 'react';
 import {
+  ExperimentalFeatures,
   Fetch,
   HvBehavior,
   HvComponent,
@@ -29,6 +30,7 @@ export type NavigationContextProps = {
   loadingScreen?: ComponentType<LoadingProps>;
   handleBack?: ComponentType<{ children: ReactNode }>;
   reload: Reload;
+  experimentalFeatures?: ExperimentalFeatures;
 };
 
 /**

src/services/navigator/index.ts

@@ -214,6 +214,7 @@ export class Navigator implements NavigationProvider {
 }
 
 export type {
+  ListenerEvent,
   NavigationComponents,
   NavigationProp,
   NavigatorProps,

src/services/navigator/types.ts

@@ -27,6 +27,13 @@ export type NavigationNavigateParams = {
   params?: NavigationNavigateParams | NavigationRouteParams;
 };
 
+export type ListenerEvent = {
+  data: { state: NavigationState | undefined } | undefined;
+  preventDefault: () => void;
+};
+
+export type ListenerCallback = (event: ListenerEvent) => void;
+
 /**
  * Minimal representation of the 'NavigationProp' used by react-navigation
  */
@@ -36,13 +43,7 @@ export type NavigationProp = {
   goBack: () => void;
   getState: () => NavigationState;
   getParent: (id?: string) => NavigationProp | undefined;
-  addListener: (
-    eventName: string,
-    callback: (event: {
-      data: { state: NavigationState | undefined } | undefined;
-      preventDefault: () => void;
-    }) => void,
-  ) => () => void;
+  addListener: (eventName: string, callback: ListenerCallback) => () => void;
   isFocused: () => boolean;
 };
 

src/types.ts

@@ -439,4 +439,8 @@ export type Reload = (
   opts: HvComponentOptions,
 ) => void;
 
-export type ExperimentalFeatures = Record<string, never>;
+export type ExperimentalFeatures = {
+  // Delay the mutation of the navigation state until after the screen has been rendered
+  // This is intended to improve the performance of navigation actions
+  navStateMutationsDelay?: number;
+};