fix(react-native): handle accessibility escape back events

.changeset/quiet-escape-back.md

@@ -0,0 +1,5 @@
+---
+'@granite-js/react-native': patch
+---
+
+Handle iOS accessibility escape gestures through the router's registered back handlers and expose `accessibilityEscape` as a back event source.

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

@@ -1,5 +1,5 @@
-import { render } from '@testing-library/react';
-import { BackHandler, Platform } from 'react-native';
+import { render, renderHook } from '@testing-library/react';
+import { BackHandler, Platform, View } from 'react-native';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { CanGoBackGuard } from './CanGoBackGuard';
 
@@ -16,6 +16,74 @@ describe('CanGoBackGuard', () => {
     vi.restoreAllMocks();
   });
 
+  it('passes accessibility escape events to onBack while back events exist', () => {
+    mockPlatformOS('ios');
+
+    const onBack = vi.fn();
+    const children = <div />;
+    const { result } = renderHook(() =>
+      CanGoBackGuard({
+        canGoBack: false,
+        hasBackEvent: true,
+        isInitialScreen: true,
+        onBack,
+        children,
+      })
+    );
+
+    expect(result.current.type).toBe(View);
+    expect(result.current.props.collapsable).toBe(false);
+    expect(result.current.props.children).toBe(children);
+
+    result.current.props.onAccessibilityEscape();
+
+    expect(onBack).toHaveBeenCalledExactlyOnceWith({ source: 'accessibilityEscape' });
+  });
+
+  it('registers the accessibility escape handler only while back events exist', () => {
+    mockPlatformOS('ios');
+
+    const onBack = vi.fn();
+    const { result, rerender } = renderHook(
+      ({ hasBackEvent }) =>
+        CanGoBackGuard({
+          canGoBack: !hasBackEvent,
+          hasBackEvent,
+          isInitialScreen: true,
+          onBack,
+          children: <div />,
+        }),
+      { initialProps: { hasBackEvent: false } }
+    );
+
+    expect(result.current.props.onAccessibilityEscape).toBeUndefined();
+
+    rerender({ hasBackEvent: true });
+
+    result.current.props.onAccessibilityEscape();
+
+    expect(onBack).toHaveBeenCalledExactlyOnceWith({ source: 'accessibilityEscape' });
+
+    rerender({ hasBackEvent: false });
+
+    expect(result.current.props.onAccessibilityEscape).toBeUndefined();
+  });
+
+  it('does not register an accessibility escape handler when onBack is absent', () => {
+    mockPlatformOS('ios');
+
+    const { result } = renderHook(() =>
+      CanGoBackGuard({
+        canGoBack: false,
+        hasBackEvent: true,
+        isInitialScreen: true,
+        children: <div />,
+      })
+    );
+
+    expect(result.current.props.onAccessibilityEscape).toBeUndefined();
+  });
+
   it('passes Android hardware back events to onBack and consumes the native event', () => {
     mockPlatformOS('android');
 

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

@@ -1,5 +1,5 @@
 import { ReactNode, useEffect } from 'react';
-import { BackHandler, Platform } from 'react-native';
+import { BackHandler, Platform, View } from 'react-native';
 import type { BackEvent } from '../../use-back-event';
 
 type SetIosSwipeGestureEnabled = ({ isEnabled }: { isEnabled: boolean }) => Promise<void> | void;
@@ -86,5 +86,13 @@ export function CanGoBackGuard({
     };
   }, [hasBackEvent, onBack, setiOSBackPressHandler]);
 
-  return <>{children}</>;
+  return (
+    <View
+      style={{ flex: 1 }}
+      collapsable={false}
+      onAccessibilityEscape={hasBackEvent && onBack ? () => onBack({ source: 'accessibilityEscape' }) : undefined}
+    >
+      {children}
+    </View>
+  );
 }

packages/react-native/src/use-back-event/useBackEvent.tsx

@@ -10,7 +10,7 @@
 import { useBackEventActionsContext } from './useBackEventActionsContext';
 import type { BackHandlerCallback } from './useBackHandler';
 
-export type BackEventSource = 'backButton' | 'iosSwipeGesture' | 'androidHardwareBackPress';
+export type BackEventSource = 'backButton' | 'iosSwipeGesture' | 'androidHardwareBackPress' | 'accessibilityEscape';
 
 export interface BackEvent {
   source: BackEventSource;
@@ -201,7 +201,7 @@
       onBack,
       onBackHandler,
     };
   }, [
     addEventListener,
     addBackHandler,
     backHandlersRef,