@granite-js/react-native 1.0.30 → 1.0.32

package/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>

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

package/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}</>;
 }

package/src/router/components/useRouterBackHandler.spec.tsx

@@ -0,0 +1,129 @@
+import { act, renderHook } from '@testing-library/react';
+import { ReactNode } from 'react';
+import { describe, expect, it, vi } from 'vitest';
+import { useInternalRouterBackHandler } from './useRouterBackHandler';
+import { BackEventProvider, useBackEvent, useBackHandler } from '../../use-back-event';
+
+vi.mock('../../visibility', () => ({
+  useVisibility: () => true,
+}));
+
+function createNavigationContainerRef() {
+  return {
+    canGoBack: vi.fn(() => true),
+    goBack: vi.fn(),
+  };
+}
+
+function BackEventProviderWrapper({ children }: { children: ReactNode }) {
+  return <BackEventProvider>{children}</BackEventProvider>;
+}
+
+function useBackHandlerTest({
+  navigationContainerRef,
+  onClose,
+}: {
+  navigationContainerRef: ReturnType<typeof createNavigationContainerRef>;
+  onClose?: () => void;
+}) {
+  const backEvent = useBackEvent();
+  const backHandler = useBackHandler();
+  const routerBackHandler = useInternalRouterBackHandler({
+    navigationContainerRef: navigationContainerRef as any,
+    onClose,
+  });
+
+  return {
+    backEvent,
+    backHandler,
+    routerBackHandler,
+  };
+}
+
+describe('useInternalRouterBackHandler', () => {
+  it('stops when a back handler handles the back event', () => {
+    const navigationContainerRef = createNavigationContainerRef();
+    const legacyHandler = vi.fn();
+    const backHandler = vi.fn(() => true);
+    const { result } = renderHook(() => useBackHandlerTest({ navigationContainerRef }), {
+      wrapper: BackEventProviderWrapper,
+    });
+
+    act(() => {
+      result.current.backEvent.addEventListener(legacyHandler);
+      result.current.backHandler.addEventListener(backHandler);
+    });
+
+    act(() => {
+      result.current.routerBackHandler.handleBackEvent({ source: 'backButton' });
+    });
+
+    expect(backHandler).toHaveBeenCalledWith({ source: 'backButton' });
+    expect(legacyHandler).not.toHaveBeenCalled();
+    expect(navigationContainerRef.goBack).not.toHaveBeenCalled();
+  });
+
+  it('runs every legacy handler when back handlers do not handle the event', () => {
+    const navigationContainerRef = createNavigationContainerRef();
+    const backHandler = vi.fn(() => false);
+    const firstLegacyHandler = vi.fn();
+    const secondLegacyHandler = vi.fn();
+    const { result } = renderHook(() => useBackHandlerTest({ navigationContainerRef }), {
+      wrapper: BackEventProviderWrapper,
+    });
+
+    act(() => {
+      result.current.backHandler.addEventListener(backHandler);
+      result.current.backEvent.addEventListener(firstLegacyHandler, secondLegacyHandler);
+    });
+
+    act(() => {
+      result.current.routerBackHandler.handleBackEvent({ source: 'iosSwipeGesture' });
+    });
+
+    expect(backHandler).toHaveBeenCalledWith({ source: 'iosSwipeGesture' });
+    expect(firstLegacyHandler).toHaveBeenCalledTimes(1);
+    expect(secondLegacyHandler).toHaveBeenCalledTimes(1);
+    expect(navigationContainerRef.goBack).not.toHaveBeenCalled();
+  });
+
+  it('runs default back when back handlers return false or undefined and no legacy handler exists', () => {
+    const navigationContainerRef = createNavigationContainerRef();
+    const backHandler = vi.fn(() => false);
+    const passiveHandler = vi.fn();
+    const { result } = renderHook(() => useBackHandlerTest({ navigationContainerRef }), {
+      wrapper: BackEventProviderWrapper,
+    });
+
+    act(() => {
+      result.current.backHandler.addEventListener(backHandler);
+      result.current.backHandler.addEventListener(passiveHandler);
+    });
+
+    act(() => {
+      result.current.routerBackHandler.handleBackEvent({ source: 'androidHardwareBackPress' });
+    });
+
+    expect(passiveHandler).toHaveBeenCalledWith({ source: 'androidHardwareBackPress' });
+    expect(backHandler).toHaveBeenCalledWith({ source: 'androidHardwareBackPress' });
+    expect(navigationContainerRef.goBack).toHaveBeenCalledTimes(1);
+  });
+
+  it('uses backButton as the source for the header back handler', () => {
+    const navigationContainerRef = createNavigationContainerRef();
+    const backHandler = vi.fn(() => true);
+    const { result } = renderHook(() => useBackHandlerTest({ navigationContainerRef }), {
+      wrapper: BackEventProviderWrapper,
+    });
+
+    act(() => {
+      result.current.backHandler.addEventListener(backHandler);
+    });
+
+    act(() => {
+      result.current.routerBackHandler.handler();
+    });
+
+    expect(backHandler).toHaveBeenCalledWith({ source: 'backButton' });
+  });
+});

package/src/router/components/useRouterBackHandler.tsx

@@ -1,6 +1,7 @@
-import { NavigationContainerRefWithCurrent } from '@granite-js/native/@react-navigation/native';
+import type { NavigationContainerRefWithCurrent } from '@granite-js/native/@react-navigation/native';
 import { useCallback, useMemo } from 'react';
-import { useBackEventContext } from '../../use-back-event';
+import type { BackEvent } from '../../use-back-event';
+import { useBackEventContext } from '../../use-back-event/useBackEventContext';
 
 /**
  * @public
@@ -63,29 +64,49 @@ export function useInternalRouterBackHandler({
   navigationContainerRef: NavigationContainerRefWithCurrent<never>;
   onClose?: () => void;
 }) {
-  const { hasBackEvent, onBack } = useBackEventContext();
-  const canGoBack = !hasBackEvent;
-
-  const handler = useCallback(() => {
-    onBack?.();
-
-    if (!canGoBack) {
-      return;
-    }
+  const { hasBackEvent, hasBackHandler, onBack, onBackHandler } = useBackEventContext();
+  const hasRegisteredBackHandler = hasBackEvent || hasBackHandler;
+  const canGoBack = !hasRegisteredBackHandler;
 
+  const handleDefaultBack = useCallback(() => {
     if (navigationContainerRef.canGoBack()) {
       navigationContainerRef.goBack();
     } else {
       onClose?.();
     }
-  }, [canGoBack, onClose, navigationContainerRef, onBack]);
+  }, [navigationContainerRef, onClose]);
+
+  const handleBackEvent = useCallback(
+    (event: BackEvent) => {
+      const didHandleBackEvent = onBackHandler(event);
+
+      if (didHandleBackEvent) {
+        return;
+      }
+
+      onBack();
+
+      if (hasBackEvent) {
+        return;
+      }
+
+      handleDefaultBack();
+    },
+    [handleDefaultBack, hasBackEvent, onBack, onBackHandler]
+  );
+
+  const handler = useCallback(() => {
+    handleBackEvent({ source: 'backButton' });
+  }, [handleBackEvent]);
 
   return useMemo(
     () => ({
       handler,
+      handleBackEvent,
       canGoBack,
+      hasBackEvent: hasRegisteredBackHandler,
       onBack,
     }),
-    [canGoBack, handler, onBack]
+    [canGoBack, handleBackEvent, handler, hasRegisteredBackHandler, onBack]
   );
 }

package/src/use-back-event/BackEventContext.ts

@@ -0,0 +1,26 @@
+import { createContext } from 'react';
+import type { BackEvent, BackEventControls, BackEventHandler } from './useBackEvent';
+import type { BackHandlerCallback, BackHandlerControls } from './useBackHandler';
+
+export interface PrivateBackEventControls extends BackEventControls {
+  handlersRef: Set<BackEventHandler>;
+  hasBackEvent: boolean;
+  hasBackHandler: boolean;
+  addBackHandler: BackHandlerControls['addEventListener'];
+  removeBackHandler: (...handlers: Array<BackHandlerCallback>) => void;
+  onBack: () => void;
+  onBackHandler: (event: BackEvent) => boolean;
+}
+
+export type BackEventActionsContextValue = Omit<
+  PrivateBackEventControls,
+  'handlersRef' | 'hasBackEvent' | 'hasBackHandler'
+>;
+
+export type BackEventStateContextValue = Pick<
+  PrivateBackEventControls,
+  'handlersRef' | 'hasBackEvent' | 'hasBackHandler'
+>;
+
+export const BackEventActionsContext = createContext<BackEventActionsContextValue | null>(null);
+export const BackEventStateContext = createContext<BackEventStateContextValue | null>(null);

package/src/use-back-event/index.ts

@@ -1 +1,2 @@
 export * from './useBackEvent';
+export * from './useBackHandler';

package/src/use-back-event/useBackEvent.spec.tsx

@@ -0,0 +1,107 @@
+import { act, renderHook } from '@testing-library/react';
+import { ReactNode } from 'react';
+import { describe, expect, it, vi } from 'vitest';
+import { BackEventProvider, useBackEvent, useBackEventState } from './useBackEvent';
+
+vi.mock('../visibility', () => ({
+  useVisibility: () => true,
+}));
+
+function BackEventProviderWrapper({ children }: { children: ReactNode }) {
+  return <BackEventProvider>{children}</BackEventProvider>;
+}
+
+describe('useBackEventState', () => {
+  it('keeps legacy back event handlers variadic and runs every handler', () => {
+    const firstHandler = vi.fn();
+    const secondHandler = vi.fn();
+    const { result } = renderHook(() => useBackEventState());
+
+    act(() => {
+      result.current.addEventListener(firstHandler, secondHandler);
+    });
+
+    result.current.onBack();
+
+    expect(result.current.hasBackEvent).toBe(true);
+    expect(firstHandler).toHaveBeenCalledTimes(1);
+    expect(secondHandler).toHaveBeenCalledTimes(1);
+  });
+
+  it('ignores legacy back event handler return values', () => {
+    const handler = vi.fn(() => false);
+    const { result } = renderHook(() => useBackEventState());
+
+    act(() => {
+      result.current.addEventListener(handler);
+    });
+
+    result.current.onBack();
+
+    expect(result.current.hasBackEvent).toBe(true);
+    expect(handler).toHaveBeenCalledTimes(1);
+  });
+
+  it('derives legacy back event state from registered handlers', () => {
+    const handler = vi.fn();
+    const { result } = renderHook(() => useBackEventState());
+
+    act(() => {
+      result.current.addEventListener(handler);
+    });
+
+    expect(result.current.hasBackEvent).toBe(true);
+
+    act(() => {
+      result.current.removeEventListener(handler);
+    });
+
+    result.current.onBack();
+
+    expect(result.current.hasBackEvent).toBe(false);
+    expect(handler).not.toHaveBeenCalled();
+  });
+
+  it('keeps the legacy state object stable while back event existence does not change', () => {
+    const firstHandler = vi.fn();
+    const secondHandler = vi.fn();
+    const { result } = renderHook(() => useBackEventState());
+
+    act(() => {
+      result.current.addEventListener(firstHandler);
+    });
+
+    const activeBackEvent = result.current;
+
+    act(() => {
+      result.current.addEventListener(secondHandler);
+    });
+
+    expect(result.current).toBe(activeBackEvent);
+  });
+});
+
+describe('useBackEvent', () => {
+  it('keeps the returned back event controls stable when provider state changes', () => {
+    const handler = vi.fn();
+    const renderCount = vi.fn();
+    const { result } = renderHook(
+      () => {
+        renderCount();
+
+        return useBackEvent();
+      },
+      {
+        wrapper: BackEventProviderWrapper,
+      }
+    );
+    const backEvent = result.current;
+
+    act(() => {
+      result.current.addEventListener(handler);
+    });
+
+    expect(result.current).toBe(backEvent);
+    expect(renderCount).toHaveBeenCalledTimes(1);
+  });
+});