From 7331c58859e20bfb31fcd078c4cfda2987f9019f Mon Sep 17 00:00:00 2001
From: Cristian <cristian.mayan@situm.com>
Date: Wed, 2 Jul 2025 13:48:15 +0200
Subject: [PATCH] feat: added 'persistOnUnmount' make MapView singleton to
 avoid re-rendering in StackNavigation integrations

---
 example/package.json                          |  6 +-
 example/src/App.tsx                           | 10 +-
 example/src/navigation/StackNavigator.tsx     | 15 +++
 example/src/navigation/types.tsx              | 10 +-
 example/src/screens/HomeScreen.tsx            |  8 +-
 example/src/screens/WayfindingScreen.tsx      |  1 +
 plugin/src/wayfinding/components/MapView.tsx  | 31 ++++++-
 plugin/src/wayfinding/index.ts                |  3 +
 .../wayfinding/store/PersistentWebView.tsx    | 28 ++++++
 .../src/wayfinding/store/WebViewProvider.tsx  | 74 +++++++++++++++
 yarn.lock                                     | 92 +++++++++++++++++--
 11 files changed, 259 insertions(+), 19 deletions(-)
 create mode 100644 example/src/navigation/StackNavigator.tsx
 create mode 100644 plugin/src/wayfinding/store/PersistentWebView.tsx
 create mode 100644 plugin/src/wayfinding/store/WebViewProvider.tsx

diff --git a/example/package.json b/example/package.json
index 7681e8e5..33aa7652 100644
--- a/example/package.json
+++ b/example/package.json
@@ -12,12 +12,14 @@
   "dependencies": {
     "@react-navigation/bottom-tabs": "^7.3.10",
     "@react-navigation/native": "^7.1.6",
+    "@react-navigation/stack": "^7.4.2",
     "@situm/react-native": "workspace:plugin",
     "react": "19.0.0",
     "react-native": "0.79.1",
+    "react-native-gesture-handler": "^2.26.0",
     "react-native-paper": "^5.13.3",
-    "react-native-safe-area-context": "^5.3.0",
-    "react-native-screens": "^4.10.0",
+    "react-native-safe-area-context": "^5.5.0",
+    "react-native-screens": "^4.11.1",
     "react-native-vector-icons": "^10.2.0",
     "react-native-webview": "^13.13.5"
   },
diff --git a/example/src/App.tsx b/example/src/App.tsx
index 47e1e722..0dc8b440 100644
--- a/example/src/App.tsx
+++ b/example/src/App.tsx
@@ -9,8 +9,10 @@ import React, { useEffect } from "react";
 import { NavigationContainer } from "@react-navigation/native";
 import { SafeAreaProvider } from "react-native-safe-area-context";
 import { TabNavigator } from "./navigation/TabNavigator";
+import { StackNavigator } from "./navigation/StackNavigator";
 import SitumPlugin from "@situm/react-native";
 import { SITUM_API_KEY, SITUM_DASHBOARD_URL } from "./situm";
+import { WebViewProvider } from "@situm/react-native";
 
 function App(): React.JSX.Element {
   useEffect(() => {
@@ -27,9 +29,11 @@ function App(): React.JSX.Element {
 
   return (
     <SafeAreaProvider>
-      <NavigationContainer>
-        <TabNavigator />
-      </NavigationContainer>
+      <WebViewProvider>
+        <NavigationContainer>
+          <StackNavigator />
+        </NavigationContainer>
+      </WebViewProvider>
     </SafeAreaProvider>
   );
 }
diff --git a/example/src/navigation/StackNavigator.tsx b/example/src/navigation/StackNavigator.tsx
new file mode 100644
index 00000000..0a9e47ff
--- /dev/null
+++ b/example/src/navigation/StackNavigator.tsx
@@ -0,0 +1,15 @@
+import React from "react";
+import { HomeScreen } from "../screens/HomeScreen";
+import { WayfindingScreen } from "../screens/WayfindingScreen";
+import { createStackNavigator } from "@react-navigation/stack";
+
+const Stack = createStackNavigator();
+
+export const StackNavigator = () => {
+  return (
+    <Stack.Navigator initialRouteName="Home">
+      <Stack.Screen name="Home" component={HomeScreen} />
+      <Stack.Screen name="Wayfinding" component={WayfindingScreen} />
+    </Stack.Navigator>
+  );
+};
diff --git a/example/src/navigation/types.tsx b/example/src/navigation/types.tsx
index 9d6bad03..3eeb0610 100644
--- a/example/src/navigation/types.tsx
+++ b/example/src/navigation/types.tsx
@@ -2,10 +2,12 @@
 
 export type RootTabsParamsList = {
   Home: undefined;
-  Wayfinding: {
-    poiIdentifier: string;
-    action: "select" | "navigate";
-  };
+  Wayfinding:
+    | {
+        poiIdentifier: string;
+        action: "select" | "navigate";
+      }
+    | undefined;
 };
 
 declare global {
diff --git a/example/src/screens/HomeScreen.tsx b/example/src/screens/HomeScreen.tsx
index 1ebfd32f..cf49992f 100644
--- a/example/src/screens/HomeScreen.tsx
+++ b/example/src/screens/HomeScreen.tsx
@@ -7,7 +7,7 @@ import SitumPlugin, {
   Building,
 } from "@situm/react-native";
 import { PositioningCard } from "./cards/PositioningCard";
-import { Alert, ScrollView, StyleSheet } from "react-native";
+import { Alert, Button, ScrollView, StyleSheet } from "react-native";
 import { FetchResourcesCard } from "./cards/FetchResourcesCard";
 import { SITUM_BUILDING_ID } from "../situm";
 import { MapInteractionCard } from "./cards/MapInteractionCard";
@@ -176,6 +176,12 @@ export const HomeScreen = () => {
           contentContainerStyle={styles.scrollContainer}
           showsVerticalScrollIndicator={true}
         >
+          <Button
+            title="SHOW MAP"
+            onPress={() => {
+              navigation.navigate("Wayfinding", undefined, { merge: true });
+            }}
+          />
           <PositioningCard
             onStartPositioning={startPositioning}
             onStopPositioning={stopPositioning}
diff --git a/example/src/screens/WayfindingScreen.tsx b/example/src/screens/WayfindingScreen.tsx
index 120af7f2..8998dee0 100644
--- a/example/src/screens/WayfindingScreen.tsx
+++ b/example/src/screens/WayfindingScreen.tsx
@@ -124,6 +124,7 @@ export const WayfindingScreen: React.FC = () => {
                 situmApiKey: SITUM_API_KEY,
                 buildingIdentifier: SITUM_BUILDING_ID,
                 profile: SITUM_PROFILE,
+                persistOnUnmount: true,
               }}
               onLoad={onLoad}
               onLoadError={onMapError}
diff --git a/plugin/src/wayfinding/components/MapView.tsx b/plugin/src/wayfinding/components/MapView.tsx
index 152d8d4d..7a21a01f 100644
--- a/plugin/src/wayfinding/components/MapView.tsx
+++ b/plugin/src/wayfinding/components/MapView.tsx
@@ -19,8 +19,11 @@ import type {
   WebViewErrorEvent,
   WebViewMessageEvent,
 } from "react-native-webview/lib/WebViewTypes";
+
 import SitumPlugin from "../../sdk";
 import useSitum from "../hooks";
+import { setError, setLocationStatus } from "../store";
+import { PersistentWebView } from "../store/PersistentWebView";
 import {
   type CartographySelectionOptions,
   type MapViewDirectionsOptions,
@@ -40,7 +43,7 @@ import {
 import { ErrorName } from "../types/constants";
 import { sendMessageToViewer } from "../utils";
 import ViewerMapper from "../utils/mapper";
-import { setError, setLocationStatus } from "../store";
+
 const SITUM_BASE_DOMAIN = "https://maps.situm.com";
 
 const NETWORK_ERROR_CODE = {
@@ -91,6 +94,10 @@ export type MapViewConfiguration = {
    * Sets the UI language based on the given ISO 639-1 code. Checkout the [Situm docs](https://situm.com/docs/query-params/) to see the list of supported languages.
    */
   language?: string;
+  /**
+   * Persist over unmount events
+   */
+  persistOnUnmount?: boolean;
 };
 
 const viewerStyles = StyleSheet.create({
@@ -596,7 +603,7 @@ const MapView = React.forwardRef<MapViewRef, MapViewProps>(
       return effectiveProfile;
     };
 
-    return (
+    const webViewComponent = (
       <WebView
         ref={webViewRef}
         source={{
@@ -637,6 +644,26 @@ const MapView = React.forwardRef<MapViewRef, MapViewProps>(
         }}
       />
     );
+
+    const { showPersistentWebView, hidePersistentWebView } = PersistentWebView({
+      webViewComponent: webViewComponent,
+      // TODO: find a better way to fit inside integrations this 'absolute singleton viewer'.
+      // Ideally PersistentWebView should adjust to the MapView limits
+      style: { height: "90%", width: "100%" },
+    });
+
+    useEffect(() => {
+      configuration.persistOnUnmount && showPersistentWebView();
+      return () => {
+        configuration.persistOnUnmount && hidePersistentWebView();
+      };
+    }, []);
+
+    return configuration.persistOnUnmount ? (
+      <>{/* WebView is rendered through showPersistentWebView() */}</>
+    ) : (
+      webViewComponent
+    );
   },
 );
 
diff --git a/plugin/src/wayfinding/index.ts b/plugin/src/wayfinding/index.ts
index c1febb42..38b1a42d 100644
--- a/plugin/src/wayfinding/index.ts
+++ b/plugin/src/wayfinding/index.ts
@@ -8,5 +8,8 @@ export { default as useSitum } from "./hooks";
 // State Provider
 export { default as SitumProvider } from "./store";
 
+// WebViewProvider
+export { WebViewProvider } from "./store/WebViewProvider";
+
 // Component
 export { default as MapView } from "./components/MapView";
diff --git a/plugin/src/wayfinding/store/PersistentWebView.tsx b/plugin/src/wayfinding/store/PersistentWebView.tsx
new file mode 100644
index 00000000..65d915e5
--- /dev/null
+++ b/plugin/src/wayfinding/store/PersistentWebView.tsx
@@ -0,0 +1,28 @@
+import { useCallback, useMemo } from "react";
+import { ViewStyle } from "react-native";
+
+import { useWebViewPortal } from "./WebViewProvider";
+
+type PersistentWebViewType = {
+  webViewComponent: React.ReactNode;
+  style: ViewStyle;
+};
+
+export const PersistentWebView = (params: PersistentWebViewType) => {
+  const { mountWebView, unmountWebView } = useWebViewPortal();
+
+  const webViewMemo = useMemo(
+    () => params.webViewComponent,
+    [params.webViewComponent],
+  );
+
+  const showPersistentWebView = useCallback(() => {
+    mountWebView(webViewMemo, params.style);
+  }, [webViewMemo]);
+
+  const hidePersistentWebView = useCallback(() => {
+    unmountWebView();
+  }, []);
+
+  return { showPersistentWebView, hidePersistentWebView, webViewMemo };
+};
diff --git a/plugin/src/wayfinding/store/WebViewProvider.tsx b/plugin/src/wayfinding/store/WebViewProvider.tsx
new file mode 100644
index 00000000..e9c16785
--- /dev/null
+++ b/plugin/src/wayfinding/store/WebViewProvider.tsx
@@ -0,0 +1,74 @@
+import React, { createContext, useContext, useState } from "react";
+import { StyleSheet, View, ViewStyle } from "react-native";
+
+type WebViewContextType = {
+  mountWebView: (webView: React.ReactNode, webViewStyle: ViewStyle) => void;
+  unmountWebView: () => void;
+  isMounted: boolean;
+};
+
+// Type-safe default value
+const defaultWebViewContext: WebViewContextType = {
+  mountWebView: () => {
+    if (__DEV__) {
+      console.warn("WebViewPortal used without Provider");
+    }
+  },
+  unmountWebView: () => {
+    if (__DEV__) {
+      console.warn("WebViewPortal used without Provider");
+    }
+  },
+  isMounted: false,
+};
+
+const WebViewContext = createContext<WebViewContextType>(defaultWebViewContext);
+
+export const WebViewProvider = ({
+  children,
+}: {
+  children: React.ReactNode;
+}) => {
+  const [webView, setWebView] = useState<React.ReactNode>(null);
+  const [style, setStyle] = useState<ViewStyle>({});
+  const [isMounted, setIsMounted] = useState(false);
+
+  const mountWebView = (
+    webViewComponent: React.ReactNode,
+    webViewStyle: ViewStyle,
+  ) => {
+    setWebView(webViewComponent);
+    setStyle(webViewStyle);
+    setIsMounted(true);
+  };
+
+  const unmountWebView = () => {
+    setIsMounted(false);
+  };
+
+  return (
+    <WebViewContext.Provider
+      value={{ mountWebView, unmountWebView, isMounted }}
+    >
+      {children}
+      <View
+        style={[style, isMounted ? styles.visible : styles.hidden]}
+        collapsable={false}
+        pointerEvents="box-none"
+      >
+        {webView}
+      </View>
+    </WebViewContext.Provider>
+  );
+};
+
+const styles = StyleSheet.create({
+  visible: {
+    display: "flex",
+  },
+  hidden: {
+    display: "none",
+  },
+});
+
+export const useWebViewPortal = () => useContext(WebViewContext);
diff --git a/yarn.lock b/yarn.lock
index 0bce464a..995f5c51 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -1850,6 +1850,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@egjs/hammerjs@npm:^2.0.17":
+  version: 2.0.17
+  resolution: "@egjs/hammerjs@npm:2.0.17"
+  dependencies:
+    "@types/hammerjs": "npm:^2.0.36"
+  checksum: f695129d45edfcfd6c5f2d1d36186da36ffade013991972ce23721a6b7ad7f214ce282abc4023e3f6b63062620852a63e897b523f247804afc7acd188fee9d9d
+  languageName: node
+  linkType: hard
+
 "@eslint-community/eslint-utils@npm:^4.2.0, @eslint-community/eslint-utils@npm:^4.4.0":
   version: 4.7.0
   resolution: "@eslint-community/eslint-utils@npm:4.7.0"
@@ -3416,6 +3425,26 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@react-navigation/elements@npm:^2.5.2":
+  version: 2.5.2
+  resolution: "@react-navigation/elements@npm:2.5.2"
+  dependencies:
+    color: "npm:^4.2.3"
+    use-latest-callback: "npm:^0.2.4"
+    use-sync-external-store: "npm:^1.5.0"
+  peerDependencies:
+    "@react-native-masked-view/masked-view": ">= 0.2.0"
+    "@react-navigation/native": ^7.1.14
+    react: ">= 18.2.0"
+    react-native: "*"
+    react-native-safe-area-context: ">= 4.0.0"
+  peerDependenciesMeta:
+    "@react-native-masked-view/masked-view":
+      optional: true
+  checksum: f6c472f82487661aee6f41e82e453cb80fea85e3956d94e58aa45b7c3f5ae04e4862df400439d0a58e6c54f8e091d7e08c547a153165d881fa8c74fd3b63d6a3
+  languageName: node
+  linkType: hard
+
 "@react-navigation/native@npm:^7.1.6":
   version: 7.1.10
   resolution: "@react-navigation/native@npm:7.1.10"
@@ -3441,6 +3470,23 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@react-navigation/stack@npm:^7.4.2":
+  version: 7.4.2
+  resolution: "@react-navigation/stack@npm:7.4.2"
+  dependencies:
+    "@react-navigation/elements": "npm:^2.5.2"
+    color: "npm:^4.2.3"
+  peerDependencies:
+    "@react-navigation/native": ^7.1.14
+    react: ">= 18.2.0"
+    react-native: "*"
+    react-native-gesture-handler: ">= 2.0.0"
+    react-native-safe-area-context: ">= 4.0.0"
+    react-native-screens: ">= 4.0.0"
+  checksum: 8a7aa9ab9173eb10638fcd9b1f9a1a3b61704853ebcf059cd7480612dd5c9053615a0df21bd044c3b60d833ce762f7a1acdebc827f49203c6a0441e1aed3f25a
+  languageName: node
+  linkType: hard
+
 "@rtsao/scc@npm:^1.1.0":
   version: 1.1.0
   resolution: "@rtsao/scc@npm:1.1.0"
@@ -3679,6 +3725,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@types/hammerjs@npm:^2.0.36":
+  version: 2.0.46
+  resolution: "@types/hammerjs@npm:2.0.46"
+  checksum: 1b6502d668f45ca49fb488c01f7938d3aa75e989d70c64801c8feded7d659ca1a118f745c1b604d220efe344c93231767d5cc68c05e00e069c14539b6143cfd9
+  languageName: node
+  linkType: hard
+
 "@types/hast@npm:^3.0.4":
   version: 3.0.4
   resolution: "@types/hast@npm:3.0.4"
@@ -6971,6 +7024,7 @@ __metadata:
     "@react-native/typescript-config": "npm:0.79.1"
     "@react-navigation/bottom-tabs": "npm:^7.3.10"
     "@react-navigation/native": "npm:^7.1.6"
+    "@react-navigation/stack": "npm:^7.4.2"
     "@situm/react-native": "workspace:plugin"
     "@types/jest": "npm:^29.5.13"
     "@types/react": "npm:19.1.2"
@@ -6988,9 +7042,10 @@ __metadata:
     react: "npm:19.0.0"
     react-dom: "npm:>=17.0.0"
     react-native: "npm:0.79.1"
+    react-native-gesture-handler: "npm:^2.26.0"
     react-native-paper: "npm:^5.13.3"
-    react-native-safe-area-context: "npm:^5.3.0"
-    react-native-screens: "npm:^4.10.0"
+    react-native-safe-area-context: "npm:^5.5.0"
+    react-native-screens: "npm:^4.11.1"
     react-native-vector-icons: "npm:^10.2.0"
     react-native-webview: "npm:^13.13.5"
     react-test-renderer: "npm:19.0.0"
@@ -12507,6 +12562,20 @@ __metadata:
   languageName: node
   linkType: hard
 
+"react-native-gesture-handler@npm:^2.26.0":
+  version: 2.26.0
+  resolution: "react-native-gesture-handler@npm:2.26.0"
+  dependencies:
+    "@egjs/hammerjs": "npm:^2.0.17"
+    hoist-non-react-statics: "npm:^3.3.0"
+    invariant: "npm:^2.2.4"
+  peerDependencies:
+    react: "*"
+    react-native: "*"
+  checksum: 8741cdd5b8047d541e13051a88e2c144d4e128ec9de11f2abb3b868ac629c51b47a8cf1b5a3ac9464c7a83bc1251e3abe462fdc29e41cd03b563042a49286ecb
+  languageName: node
+  linkType: hard
+
 "react-native-is-edge-to-edge@npm:^1.1.7":
   version: 1.1.7
   resolution: "react-native-is-edge-to-edge@npm:1.1.7"
@@ -12532,17 +12601,17 @@ __metadata:
   languageName: node
   linkType: hard
 
-"react-native-safe-area-context@npm:^5.3.0":
-  version: 5.4.1
-  resolution: "react-native-safe-area-context@npm:5.4.1"
+"react-native-safe-area-context@npm:^5.5.0":
+  version: 5.5.0
+  resolution: "react-native-safe-area-context@npm:5.5.0"
   peerDependencies:
     react: "*"
     react-native: "*"
-  checksum: 1d8de402c4af8ee1bd00dec0c2fdb35b34ba64a62d7e235884c98216a2068f8d89e5bb89f27d2e9cd711ee9b173d9aafde53ebd2b39e64d0a1e83567de95305b
+  checksum: 6b8ea4199ac9e5136091c8193e78e1d4d0539d2831c4ae6d51b2f0e31766184bfee09a5b57fec83bbb208349aec590f5abfaeae27a08090ab5f67dd37e28c7a9
   languageName: node
   linkType: hard
 
-"react-native-screens@npm:^4.10.0":
+"react-native-screens@npm:^4.11.1":
   version: 4.11.1
   resolution: "react-native-screens@npm:4.11.1"
   dependencies:
@@ -14824,6 +14893,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"use-latest-callback@npm:^0.2.4":
+  version: 0.2.4
+  resolution: "use-latest-callback@npm:0.2.4"
+  peerDependencies:
+    react: ">=16.8"
+  checksum: 60c3a6b1b6567e1794f9e48cd86b8cde8a149485cc2fed60570f69ec3b157f6812e0ff0a877f0b971592fb9254b1363cc21c120fd1fc993b1dad1406c69211df
+  languageName: node
+  linkType: hard
+
 "use-sync-external-store@npm:^1.0.0, use-sync-external-store@npm:^1.5.0":
   version: 1.5.0
   resolution: "use-sync-external-store@npm:1.5.0"