@granite-js/react-native 1.0.31 → 1.0.33

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

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

@@ -0,0 +1,114 @@
+import { useCallback, useEffect, useMemo, useRef } from 'react';
+import { useVisibility } from '../visibility';
+import type { BackEvent } from './useBackEvent';
+import { useBackEventContext } from './useBackEventContext';
+
+export type BackHandlerCallback = (event: BackEvent) => boolean | void;
+
+export interface BackHandlerSubscription {
+  remove: () => void;
+}
+
+export interface BackHandlerControls {
+  addEventListener: (handler: BackHandlerCallback) => BackHandlerSubscription;
+}
+
+/**
+ * @public
+ * @category Screen Control
+ * @name useBackHandler
+ * @description
+ * A Hook that registers back handlers. Back handlers run before handlers registered through `useBackEvent`.
+ * Return `true` to stop bubbling and prevent default back navigation. Return `false` or return nothing to continue bubbling to the next handler.
+ *
+ * @example
+ *
+ * ### Example of Closing an Overlay First
+ *
+ * ```tsx
+ * import { useEffect, useState } from 'react';
+ * import { Button, View } from 'react-native';
+ * import { useBackHandler } from '@granite-js/react-native';
+ *
+ * export function OverlayExample() {
+ *   const backHandler = useBackHandler();
+ *   const [isOverlayOpen, setIsOverlayOpen] = useState(false);
+ *
+ *   useEffect(() => {
+ *     const subscription = backHandler.addEventListener(() => {
+ *       if (isOverlayOpen) {
+ *         setIsOverlayOpen(false);
+ *         return true;
+ *       }
+ *
+ *       return undefined;
+ *     });
+ *
+ *     return () => {
+ *       subscription.remove();
+ *     };
+ *   }, [backHandler, isOverlayOpen]);
+ *
+ *   return (
+ *     <View>
+ *       <Button title="Open Overlay" onPress={() => setIsOverlayOpen(true)} />
+ *     </View>
+ *   );
+ * }
+ * ```
+ */
+export function useBackHandler() {
+  const context = useBackEventContext();
+  const handlersRef = useRef<Set<BackHandlerCallback>>(new Set()).current;
+
+  const isVisible = useVisibility();
+
+  const contextAddBackHandler = context.addBackHandler;
+  const contextRemoveBackHandler = context.removeBackHandler;
+
+  const removeHandler = useCallback(
+    (...handlers: Array<BackHandlerCallback>) => {
+      for (const handler of handlers) {
+        handlersRef.delete(handler);
+        contextRemoveBackHandler(handler);
+      }
+    },
+    [contextRemoveBackHandler]
+  );
+
+  const addEventListener = useCallback(
+    (handler: BackHandlerCallback) => {
+      handlersRef.add(handler);
+      contextAddBackHandler(handler);
+
+      return {
+        remove: () => removeHandler(handler),
+      };
+    },
+    [contextAddBackHandler, removeHandler]
+  );
+
+  useEffect(() => {
+    if (!isVisible) {
+      return;
+    }
+
+    for (const handler of handlersRef) {
+      contextAddBackHandler(handler);
+    }
+
+    return () => {
+      for (const handler of handlersRef) {
+        contextRemoveBackHandler(handler);
+      }
+    };
+  }, [contextAddBackHandler, contextRemoveBackHandler, isVisible]);
+
+  const backHandler = useMemo((): BackHandlerControls => {
+    return {
+      addEventListener,
+    };
+  }, [addEventListener]);
+
+  return backHandler;
+}