@granite-js/react-native 1.0.31 → 1.0.32

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

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

@@ -1,18 +1,27 @@
-import { createContext, ReactNode, useCallback, useContext, useEffect, useMemo, useRef, useState } from 'react';
+import { ReactNode, useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { useVisibility } from '../visibility';
+import {
+  BackEventActionsContext,
+  BackEventStateContext,
+  type BackEventActionsContextValue,
+  type BackEventStateContextValue,
+  type PrivateBackEventControls,
+} from './BackEventContext';
+import { useBackEventActionsContext } from './useBackEventActionsContext';
+import type { BackHandlerCallback } from './useBackHandler';
 
-export interface BackEventControls {
-  addEventListener: (...handlers: Array<() => void>) => void;
-  removeEventListener: (...handlers: Array<() => void>) => void;
-}
+export type BackEventSource = 'backButton' | 'iosSwipeGesture' | 'androidHardwareBackPress';
 
-interface PrivateBackEventControls extends BackEventControls {
-  handlersRef: Set<() => void>;
-  hasBackEvent: boolean;
-  onBack: () => void;
+export interface BackEvent {
+  source: BackEventSource;
 }
 
-const BackEventContext = createContext<PrivateBackEventControls | null>(null);
+export type BackEventHandler = () => void;
+
+export interface BackEventControls {
+  addEventListener: (...handlers: Array<BackEventHandler>) => void;
+  removeEventListener: (...handlers: Array<BackEventHandler>) => void;
+}
 
 /**
  * @component
@@ -41,7 +50,37 @@ const BackEventContext = createContext<PrivateBackEventControls | null>(null);
 export function BackEventProvider({ children }: { children: ReactNode }) {
   const backEventState = useBackEventState();
 
-  return <BackEventContext.Provider value={backEventState}>{children}</BackEventContext.Provider>;
+  const actions = useMemo((): BackEventActionsContextValue => {
+    return {
+      addEventListener: backEventState.addEventListener,
+      removeEventListener: backEventState.removeEventListener,
+      addBackHandler: backEventState.addBackHandler,
+      removeBackHandler: backEventState.removeBackHandler,
+      onBack: backEventState.onBack,
+      onBackHandler: backEventState.onBackHandler,
+    };
+  }, [
+    backEventState.addBackHandler,
+    backEventState.addEventListener,
+    backEventState.onBack,
+    backEventState.onBackHandler,
+    backEventState.removeBackHandler,
+    backEventState.removeEventListener,
+  ]);
+
+  const state = useMemo((): BackEventStateContextValue => {
+    return {
+      handlersRef: backEventState.handlersRef,
+      hasBackEvent: backEventState.hasBackEvent,
+      hasBackHandler: backEventState.hasBackHandler,
+    };
+  }, [backEventState.handlersRef, backEventState.hasBackEvent, backEventState.hasBackHandler]);
+
+  return (
+    <BackEventActionsContext.Provider value={actions}>
+      <BackEventStateContext.Provider value={state}>{children}</BackEventStateContext.Provider>
+    </BackEventActionsContext.Provider>
+  );
 }
 
 /**
@@ -70,11 +109,26 @@ export function BackEventProvider({ children }: { children: ReactNode }) {
  * ```
  */
 export function useBackEventState() {
-  const handlersRef = useRef<Set<() => void>>(new Set()).current;
+  const handlersRef = useRef<Set<BackEventHandler>>(new Set()).current;
+  const backHandlersRef = useRef<Set<BackHandlerCallback>>(new Set()).current;
   const [hasBackEvent, setHasBackEvent] = useState(false);
+  const [hasBackHandler, setHasBackHandler] = useState(false);
+
+  const removeEventListener = useCallback(
+    (...handlers: Array<BackEventHandler>) => {
+      for (const handler of handlers) {
+        handlersRef.delete(handler);
+      }
+
+      if (handlersRef.size === 0) {
+        setHasBackEvent(false);
+      }
+    },
+    [handlersRef]
+  );
 
   const addEventListener = useCallback(
-    (...handlers: Array<() => void>) => {
+    (...handlers: Array<BackEventHandler>) => {
       for (const handler of handlers) {
         handlersRef.add(handler);
       }
@@ -86,17 +140,53 @@ export function useBackEventState() {
     [handlersRef]
   );
 
-  const removeEventListener = useCallback(
-    (...handlers: Array<() => void>) => {
+  const removeBackHandler = useCallback(
+    (...handlers: Array<BackHandlerCallback>) => {
       for (const handler of handlers) {
-        handlersRef.delete(handler);
+        backHandlersRef.delete(handler);
       }
 
-      if (handlersRef.size === 0) {
-        setHasBackEvent(false);
+      if (backHandlersRef.size === 0) {
+        setHasBackHandler(false);
       }
     },
-    [handlersRef]
+    [backHandlersRef]
+  );
+
+  const addBackHandler = useCallback(
+    (handler: BackHandlerCallback) => {
+      backHandlersRef.add(handler);
+
+      if (backHandlersRef.size > 0) {
+        setHasBackHandler(true);
+      }
+
+      return {
+        remove: () => removeBackHandler(handler),
+      };
+    },
+    [backHandlersRef, removeBackHandler]
+  );
+
+  const onBack = useCallback(() => {
+    handlersRef.forEach((handler) => handler());
+  }, [handlersRef]);
+
+  const onBackHandler = useCallback(
+    (event: BackEvent) => {
+      const orderedBackHandlers = Array.from(backHandlersRef).reverse();
+
+      for (const handler of orderedBackHandlers) {
+        const didHandleBackEvent = handler(event) === true;
+
+        if (didHandleBackEvent) {
+          return true;
+        }
+      }
+
+      return false;
+    },
+    [backHandlersRef]
   );
 
   const backEvent = useMemo((): PrivateBackEventControls => {
@@ -105,11 +195,24 @@ export function useBackEventState() {
       removeEventListener,
       handlersRef,
       hasBackEvent,
-      onBack: () => {
-        handlersRef.forEach((handler) => handler());
-      },
+      hasBackHandler,
+      addBackHandler,
+      removeBackHandler,
+      onBack,
+      onBackHandler,
     };
-  }, [addEventListener, handlersRef, hasBackEvent, removeEventListener]);
+  }, [
+    addEventListener,
+    addBackHandler,
+    backHandlersRef,
+    handlersRef,
+    hasBackEvent,
+    hasBackHandler,
+    onBack,
+    onBackHandler,
+    removeBackHandler,
+    removeEventListener,
+  ]);
 
   return backEvent;
 }
@@ -180,36 +283,32 @@ export function useBackEventState() {
  * ```
  */
 export function useBackEvent() {
-  const context = useContext(BackEventContext);
-  const handlersRef = useRef<Set<() => void>>(new Set()).current;
+  const context = useBackEventActionsContext();
+  const handlersRef = useRef<Set<BackEventHandler>>(new Set()).current;
 
   const isVisible = useVisibility();
 
-  if (context == null) {
-    throw new Error('useBackEvent must be used within a BackEventProvider');
-  }
-
   const contextAddEventListener = context.addEventListener;
   const contextRemoveEventListener = context.removeEventListener;
 
-  const addEventListener = useCallback(
-    (...handlers: Array<() => void>) => {
+  const removeEventListener = useCallback(
+    (...handlers: Array<BackEventHandler>) => {
       for (const handler of handlers) {
-        handlersRef.add(handler);
-        contextAddEventListener(handler);
+        handlersRef.delete(handler);
+        contextRemoveEventListener(handler);
       }
     },
-    [contextAddEventListener, handlersRef]
+    [contextRemoveEventListener, handlersRef]
   );
 
-  const removeEventListener = useCallback(
-    (...handlers: Array<() => void>) => {
+  const addEventListener = useCallback(
+    (...handlers: Array<BackEventHandler>) => {
       for (const handler of handlers) {
-        handlersRef.delete(handler);
-        contextRemoveEventListener(handler);
+        handlersRef.add(handler);
+        contextAddEventListener(handler);
       }
     },
-    [contextRemoveEventListener, handlersRef]
+    [contextAddEventListener, handlersRef]
   );
 
   /**
@@ -242,12 +341,3 @@ export function useBackEvent() {
 
   return backEvent;
 }
-
-export function useBackEventContext() {
-  const context = useContext(BackEventContext);
-  if (context == null) {
-    throw new Error('useBackEvent must be used within a BackEventProvider');
-  }
-
-  return context;
-}

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

@@ -0,0 +1,11 @@
+import { useContext } from 'react';
+import { BackEventActionsContext } from './BackEventContext';
+
+export function useBackEventActionsContext() {
+  const context = useContext(BackEventActionsContext);
+  if (context == null) {
+    throw new Error('useBackEvent must be used within a BackEventProvider');
+  }
+
+  return context;
+}

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

@@ -0,0 +1,28 @@
+import { useContext, useMemo } from 'react';
+import {
+  BackEventActionsContext,
+  BackEventStateContext,
+  type PrivateBackEventControls,
+} from './BackEventContext';
+
+export function useBackEventContext() {
+  const actions = useContext(BackEventActionsContext);
+  const state = useContext(BackEventStateContext);
+
+  const context = useMemo((): PrivateBackEventControls | null => {
+    if (actions == null || state == null) {
+      return null;
+    }
+
+    return {
+      ...actions,
+      ...state,
+    };
+  }, [actions, state]);
+
+  if (context == null) {
+    throw new Error('useBackEvent must be used within a BackEventProvider');
+  }
+
+  return context;
+}

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

@@ -0,0 +1,113 @@
+import { act, renderHook } from '@testing-library/react';
+import { ReactNode } from 'react';
+import { describe, expect, it, vi } from 'vitest';
+import { BackEventProvider } from './useBackEvent';
+import { useBackEventContext } from './useBackEventContext';
+import { useBackHandler } from './useBackHandler';
+
+vi.mock('../visibility', () => ({
+  useVisibility: () => true,
+}));
+
+function BackEventProviderWrapper({ children }: { children: ReactNode }) {
+  return <BackEventProvider>{children}</BackEventProvider>;
+}
+
+function useBackHandlerTest() {
+  const backHandler = useBackHandler();
+  const backEventContext = useBackEventContext();
+
+  return {
+    backHandler,
+    backEventContext,
+  };
+}
+
+describe('useBackHandler', () => {
+  it('exposes removal only through the returned subscription', () => {
+    const { result } = renderHook(() => useBackHandler(), {
+      wrapper: BackEventProviderWrapper,
+    });
+
+    expect(result.current).toEqual({
+      addEventListener: expect.any(Function),
+    });
+    expect('removeEventListener' in result.current).toBe(false);
+  });
+
+  it('bubbles from the latest handler and stops when one explicitly handles the event', () => {
+    const parent = vi.fn(() => true);
+    const child = vi.fn(() => false);
+    const overlay = vi.fn(() => true);
+    const { result } = renderHook(() => useBackHandlerTest(), {
+      wrapper: BackEventProviderWrapper,
+    });
+
+    act(() => {
+      result.current.backHandler.addEventListener(parent);
+      result.current.backHandler.addEventListener(child);
+      result.current.backHandler.addEventListener(overlay);
+    });
+
+    expect(result.current.backEventContext.onBackHandler({ source: 'iosSwipeGesture' })).toBe(true);
+    expect(overlay).toHaveBeenCalledWith({ source: 'iosSwipeGesture' });
+    expect(child).not.toHaveBeenCalled();
+    expect(parent).not.toHaveBeenCalled();
+  });
+
+  it('continues bubbling while handlers return false', () => {
+    const parent = vi.fn(() => true);
+    const child = vi.fn(() => false);
+    const { result } = renderHook(() => useBackHandlerTest(), {
+      wrapper: BackEventProviderWrapper,
+    });
+
+    act(() => {
+      result.current.backHandler.addEventListener(parent);
+      result.current.backHandler.addEventListener(child);
+    });
+
+    expect(result.current.backEventContext.onBackHandler({ source: 'backButton' })).toBe(true);
+    expect(child).toHaveBeenCalledWith({ source: 'backButton' });
+    expect(parent).toHaveBeenCalledWith({ source: 'backButton' });
+  });
+
+  it('allows default navigation when handlers return false or undefined', () => {
+    const parent = vi.fn(() => false);
+    const child = vi.fn();
+    const { result } = renderHook(() => useBackHandlerTest(), {
+      wrapper: BackEventProviderWrapper,
+    });
+
+    act(() => {
+      result.current.backHandler.addEventListener(parent);
+      result.current.backHandler.addEventListener(child);
+    });
+
+    expect(result.current.backEventContext.onBackHandler({ source: 'androidHardwareBackPress' })).toBe(false);
+    expect(child).toHaveBeenCalledWith({ source: 'androidHardwareBackPress' });
+    expect(parent).toHaveBeenCalledWith({ source: 'androidHardwareBackPress' });
+  });
+
+  it('removes a back handler through the returned subscription', () => {
+    const handler = vi.fn(() => true);
+    const { result } = renderHook(() => useBackHandlerTest(), {
+      wrapper: BackEventProviderWrapper,
+    });
+    let subscription!: ReturnType<typeof result.current.backHandler.addEventListener>;
+
+    act(() => {
+      subscription = result.current.backHandler.addEventListener(handler);
+    });
+
+    expect(result.current.backEventContext.onBackHandler({ source: 'backButton' })).toBe(true);
+
+    act(() => {
+      subscription.remove();
+    });
+
+    expect(result.current.backEventContext.hasBackHandler).toBe(false);
+    expect(result.current.backEventContext.onBackHandler({ source: 'backButton' })).toBe(false);
+    expect(handler).toHaveBeenCalledTimes(1);
+  });
+});