Singleton MapView on RN

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"
   },

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>
   );
 }

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>
+  );
+};

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 {

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}

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}

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
+    );
   },
 );
 

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";

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 };
+};

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);