feat(react-native): add opt-in back handler API

.changeset/shiny-mangos-lay.md

@@ -0,0 +1,5 @@
+---
+'@granite-js/react-native': patch
+---
+
+add opt-in back handler API

packages/react-native/package.json

@@ -92,6 +92,7 @@
     "@babel/preset-env": "7.28.5",
     "@babel/preset-typescript": "7.28.5",
     "@granite-js/native": "workspace:*",
+    "@granite-js/vitest": "workspace:*",
     "@testing-library/dom": "^10.4.0",
     "@testing-library/react": "^16.1.0",
     "@types/babel__core": "^7",

packages/react-native/src/app/AppRoot.tsx

@@ -16,6 +16,7 @@ interface AppRootProps extends GraniteProps {
   initialProps: InitialProps;
   initialScheme: string;
   setIosSwipeGestureEnabled?: ({ isEnabled }: { isEnabled: boolean }) => void;
+  setiOSBackPressHandler?: ({ handler }: { handler: () => void }) => Promise<void> | void;
   getInitialUrl: InternalRouterProps['getInitialUrl'];
 }
 
@@ -27,6 +28,7 @@ export function AppRoot({
   initialScheme,
   router,
   setIosSwipeGestureEnabled,
+  setiOSBackPressHandler,
   getInitialUrl,
 }: AppRootProps) {
   const prefix = getSchemePrefix({
@@ -47,6 +49,7 @@ export function AppRoot({
               container={Container}
               prefix={prefix}
               setIosSwipeGestureEnabled={setIosSwipeGestureEnabled}
+              setiOSBackPressHandler={setiOSBackPressHandler}
               getInitialUrl={getInitialUrl}
               {...router}
             />

packages/react-native/src/app/Granite.tsx

@@ -14,7 +14,7 @@
    * The name of the app.
    */
   appName: string;
   /**
    * @description
    * The context of the app.
    *
@@ -39,6 +39,12 @@
    */
   setIosSwipeGestureEnabled?: ({ isEnabled }: { isEnabled: boolean }) => void;
 
+  /**
+   * @description
+   * The function to register a handler that runs when the iOS swipe back gesture is detected.
+   */
+  setiOSBackPressHandler?: ({ handler }: { handler: () => void }) => Promise<void> | void;
+
   /**
    * @description
    * The function to provide the initial URL to router.
@@ -65,7 +71,7 @@
   return {
     registerApp( 
       AppContainer: ComponentType<PropsWithChildren<InitialProps>>,
-      { appName, context, router, initialScheme, setIosSwipeGestureEnabled, getInitialUrl }: GraniteProps
+      { appName, context, router, initialScheme, setIosSwipeGestureEnabled, setiOSBackPressHandler, getInitialUrl }: GraniteProps
     ): (initialProps: InitialProps) => JSX.Element {
       if (appName === ENTRY_BUNDLE_NAME) {
         throw new Error(`Reserved app name 'shared' cannot be used`);
@@ -80,6 +86,7 @@
             initialProps={initialProps}
             initialScheme={initialSchemeValue}
             setIosSwipeGestureEnabled={setIosSwipeGestureEnabled}
+            setiOSBackPressHandler={setiOSBackPressHandler}
             getInitialUrl={getInitialUrl}
             appName={appName}
             context={context}

packages/react-native/src/router/Router.tsx

@@ -65,6 +65,7 @@ export interface InternalRouterProps {
   initialProps: InitialProps;
   initialScheme: string;
   setIosSwipeGestureEnabled?: ({ isEnabled }: { isEnabled: boolean }) => Promise<void> | void;
+  setiOSBackPressHandler?: ({ handler }: { handler: () => void }) => Promise<void> | void;
   getInitialUrl?: RouterControlsConfig['getInitialUrl'];
 }
 
@@ -148,6 +149,7 @@ export function Router({
   defaultErrorComponent,
   // Public props (StackNavigator)
   setIosSwipeGestureEnabled,
+  setiOSBackPressHandler,
   getInitialUrl,
   ...navigationContainerProps
 }: InternalRouterProps & RouterProps): ReactElement {
@@ -162,7 +164,7 @@ export function Router({
 
   const ref = useMemo(() => navigationContainerRef ?? createNavigationContainerRef<never>(), [navigationContainerRef]);
 
-  const { handler, canGoBack, onBack } = useInternalRouterBackHandler({
+  const { handler, handleBackEvent, canGoBack, hasBackEvent } = useInternalRouterBackHandler({
     navigationContainerRef: ref,
     onClose: closeView,
   });
@@ -195,9 +197,11 @@ export function Router({
     >
       <CanGoBackGuard
         canGoBack={canGoBack}
+        hasBackEvent={hasBackEvent}
         isInitialScreen={isInitialScreen}
-        onBack={onBack}
+        onBack={handleBackEvent}
         setIosSwipeGestureEnabled={setIosSwipeGestureEnabled}
+        setiOSBackPressHandler={setiOSBackPressHandler}
       >
         <Container {...initialProps}>
           <StackNavigator.Navigator screenOptions={screenOptions}>{Screens}</StackNavigator.Navigator>

packages/react-native/src/router/components/CanGoBackGuard.spec.tsx

@@ -0,0 +1,85 @@
+import { render } from '@testing-library/react';
+import { BackHandler } from 'react-native';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { CanGoBackGuard } from './CanGoBackGuard';
+
+describe('CanGoBackGuard', () => {
+  beforeEach(() => {
+    vi.mocked(BackHandler.addEventListener).mockClear();
+  });
+
+  it('passes Android hardware back events to onBack and consumes the native event', () => {
+    const onBack = vi.fn();
+
+    render(
+      <CanGoBackGuard canGoBack={false} hasBackEvent={true} isInitialScreen={true} onBack={onBack}>
+        <div />
+      </CanGoBackGuard>
+    );
+
+    const handler = vi.mocked(BackHandler.addEventListener).mock.calls[0]?.[1];
+
+    expect(BackHandler.addEventListener).toHaveBeenCalledWith('hardwareBackPress', expect.any(Function));
+    expect(handler?.()).toBe(true);
+    expect(onBack).toHaveBeenCalledWith({ source: 'androidHardwareBackPress' });
+  });
+
+  it('does not register Android hardware back when no back event exists', () => {
+    const onBack = vi.fn();
+
+    render(
+      <CanGoBackGuard canGoBack={true} hasBackEvent={false} isInitialScreen={true} onBack={onBack}>
+        <div />
+      </CanGoBackGuard>
+    );
+
+    expect(BackHandler.addEventListener).not.toHaveBeenCalled();
+  });
+
+  it('registers the iOS swipe back handler while back events exist', () => {
+    const onBack = vi.fn();
+    const setiOSBackPressHandler = vi.fn();
+
+    const { unmount } = render(
+      <CanGoBackGuard
+        canGoBack={true}
+        hasBackEvent={true}
+        isInitialScreen={true}
+        onBack={onBack}
+        setiOSBackPressHandler={setiOSBackPressHandler}
+      >
+        <div />
+      </CanGoBackGuard>
+    );
+
+    setiOSBackPressHandler.mock.calls[0]?.[0].handler();
+
+    expect(setiOSBackPressHandler).toHaveBeenCalledWith({ handler: expect.any(Function) });
+    expect(onBack).toHaveBeenCalledWith({ source: 'iosSwipeGesture' });
+
+    unmount();
+
+    expect(setiOSBackPressHandler).toHaveBeenLastCalledWith({ handler: expect.any(Function) });
+  });
+
+  it('disables iOS swipe when the current state should block default back navigation', () => {
+    const setIosSwipeGestureEnabled = vi.fn();
+
+    const { unmount } = render(
+      <CanGoBackGuard
+        canGoBack={false}
+        hasBackEvent={true}
+        isInitialScreen={true}
+        setIosSwipeGestureEnabled={setIosSwipeGestureEnabled}
+      >
+        <div />
+      </CanGoBackGuard>
+    );
+
+    expect(setIosSwipeGestureEnabled).toHaveBeenCalledWith({ isEnabled: false });
+
+    unmount();
+
+    expect(setIosSwipeGestureEnabled).toHaveBeenLastCalledWith({ isEnabled: true });
+  });
+});

packages/react-native/src/router/components/CanGoBackGuard.tsx

@@ -1,21 +1,27 @@
 import { ReactNode, useEffect } from 'react';
 import { BackHandler } from 'react-native';
+import type { BackEvent } from '../../use-back-event';
+
+type SetIosSwipeGestureEnabled = ({ isEnabled }: { isEnabled: boolean }) => Promise<void> | void;
+type SetIOSBackPressHandler = ({ handler }: { handler: () => void }) => Promise<void> | void;
 
 export function CanGoBackGuard({
   children,
   canGoBack,
+  hasBackEvent,
   onBack,
   isInitialScreen,
   setIosSwipeGestureEnabled,
+  setiOSBackPressHandler,
 }: {
   canGoBack: boolean;
+  hasBackEvent: boolean;
   isInitialScreen: boolean;
   children: ReactNode;
-  onBack?: () => void;
-  setIosSwipeGestureEnabled?: ({ isEnabled }: { isEnabled: boolean }) => void;
+  onBack?: (event: BackEvent) => void;
+  setIosSwipeGestureEnabled?: SetIosSwipeGestureEnabled;
+  setiOSBackPressHandler?: SetIOSBackPressHandler;
 }) {
-  const shouldBlockGoingBack = !canGoBack;
-
   useEffect(() => {
     if (!isInitialScreen || !canGoBack) {
       setIosSwipeGestureEnabled?.({ isEnabled: false });
@@ -29,19 +35,36 @@ export function CanGoBackGuard({
   }, [canGoBack, isInitialScreen, setIosSwipeGestureEnabled]);
 
   useEffect(() => {
-    if (shouldBlockGoingBack) {
-      const subscription = BackHandler.addEventListener('hardwareBackPress', () => {
-        onBack?.();
-        return true;
-      });
+    if (!hasBackEvent) {
+      return;
+    }
 
-      return () => {
-        subscription.remove();
-      };
+    const subscription = BackHandler.addEventListener('hardwareBackPress', () => {
+      onBack?.({ source: 'androidHardwareBackPress' });
+
+      return true;
+    });
+
+    return () => {
+      subscription.remove();
+    };
+  }, [hasBackEvent, onBack]);
+
+  useEffect(() => {
+    if (!hasBackEvent || setiOSBackPressHandler == null) {
+      return;
     }
 
-    return;
-  }, [shouldBlockGoingBack, onBack]);
+    setiOSBackPressHandler({
+      handler: () => {
+        onBack?.({ source: 'iosSwipeGesture' });
+      },
+    });
+
+    return () => {
+      setiOSBackPressHandler({ handler: () => {} });
+    };
+  }, [hasBackEvent, onBack, setiOSBackPressHandler]);
 
   return <>{children}</>;
 }