@granite-js/react-native 2.4.0 → 2.5.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @granite-js/react-native
 
+## 2.5.0
+
+### Minor Changes
+
+- f9086dc: Add `useVisibilityEffect` to run an effect while a screen is visible and clean it up when visibility is lost, the callback changes, or the component unmounts.
+
+  Deprecate `useVisibilityChange` without changing its behavior. Use `useVisibilityEffect` for effects with cleanup, or `useVisibility` with React's `useEffect` for explicit visibility change handling.
+
+### Patch Changes
+
+- @granite-js/blur-view@2.5.0
+- @granite-js/brownfield-module@2.5.0
+- @granite-js/cli@2.5.0
+- @granite-js/jest@2.5.0
+- @granite-js/mpack@2.5.0
+- @granite-js/plugin-core@2.5.0
+- @granite-js/style-utils@2.5.0
+- @granite-js/video@2.5.0
+
 ## 2.4.0
 
 ### Patch Changes

package/dist/visibility/index.d.ts

@@ -3,5 +3,6 @@ export * from './useIsAppForeground';
 export * from './useVisibility';
 export * from './useVisibilityChanged';
 export * from './useVisibilityChange';
+export * from './useVisibilityEffect';
 export * from './VisibilityProvider';
 export * from './onVisibilityChanged';

package/dist/visibility/useVisibilityChange.d.ts

@@ -14,6 +14,7 @@ export type VisibilityCallback = (state: VisibilityState) => void;
  * @public
  * @category Screen Control
  * @name useVisibilityChange
+ * @deprecated Use `useVisibilityEffect` for effects with cleanup, or `useVisibility` with React's `useEffect` to handle visibility changes.
  * @kind function
  * @description
  * Calls a callback function with the visibility state when the screen's visibility changes.

package/dist/visibility/useVisibilityEffect.d.ts

@@ -0,0 +1,32 @@
+import { type EffectCallback } from 'react';
+/**
+ * @public
+ * @category Screen Control
+ * @name useVisibilityEffect
+ * @description
+ * Runs an effect while the screen is visible, using the visibility state from `useVisibility`.
+ * Cleans up when the screen becomes hidden, the effect callback changes, or the component unmounts.
+ * Like `useEffect`, setup and cleanup run after a render is committed. The callback must be synchronous
+ * and may return a cleanup function. Use `useCallback` to avoid restarting on unrelated renders.
+ * Unlike `useVisibilityChange`, a returned cleanup function is registered with React.
+ *
+ * @param {EffectCallback} effect - Sets up the effect and optionally returns its cleanup function.
+ * @example
+ * ```tsx
+ * import { useCallback } from 'react';
+ * import { BackHandler } from 'react-native';
+ * import { useVisibilityEffect } from '@granite-js/react-native';
+ *
+ * function Screen({ onBack }: { onBack: () => boolean }) {
+ *   useVisibilityEffect(
+ *     useCallback(() => {
+ *       const subscription = BackHandler.addEventListener('hardwareBackPress', onBack);
+ *       return () => subscription.remove();
+ *     }, [onBack])
+ *   );
+ *
+ *   return null;
+ * }
+ * ```
+ */
+export declare function useVisibilityEffect(effect: EffectCallback): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@granite-js/react-native",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "description": "The Granite Framework",
   "bin": {
     "granite": "./bin/cli.js"
@@ -91,8 +91,8 @@
     "@babel/core": "7.28.5",
     "@babel/preset-env": "7.28.5",
     "@babel/preset-typescript": "7.28.5",
-    "@granite-js/native": "2.4.0",
-    "@granite-js/vitest": "2.4.0",
+    "@granite-js/native": "2.5.0",
+    "@granite-js/vitest": "2.5.0",
     "@testing-library/dom": "^10.4.0",
     "@testing-library/react": "^16.1.0",
     "@types/babel__core": "^7",
@@ -121,14 +121,14 @@
     "react-native": "*"
   },
   "dependencies": {
-    "@granite-js/blur-view": "2.4.0",
-    "@granite-js/brownfield-module": "2.4.0",
-    "@granite-js/cli": "2.4.0",
-    "@granite-js/jest": "2.4.0",
-    "@granite-js/mpack": "2.4.0",
-    "@granite-js/plugin-core": "2.4.0",
-    "@granite-js/style-utils": "2.4.0",
-    "@granite-js/video": "2.4.0",
+    "@granite-js/blur-view": "2.5.0",
+    "@granite-js/brownfield-module": "2.5.0",
+    "@granite-js/cli": "2.5.0",
+    "@granite-js/jest": "2.5.0",
+    "@granite-js/mpack": "2.5.0",
+    "@granite-js/plugin-core": "2.5.0",
+    "@granite-js/style-utils": "2.5.0",
+    "@granite-js/video": "2.5.0",
     "@standard-schema/spec": "^1.0.0",
     "es-toolkit": "^1.39.8",
     "react-native-url-polyfill": "3.0.0"

package/src/visibility/index.ts

@@ -3,5 +3,6 @@ export * from './useIsAppForeground';
 export * from './useVisibility';
 export * from './useVisibilityChanged';
 export * from './useVisibilityChange';
+export * from './useVisibilityEffect';
 export * from './VisibilityProvider';
-export * from './onVisibilityChanged';
+export * from './onVisibilityChanged';

package/src/visibility/useVisibilityChange.ts

@@ -20,6 +20,7 @@ export type VisibilityCallback = (state: VisibilityState) => void;
  * @public
  * @category Screen Control
  * @name useVisibilityChange
+ * @deprecated Use `useVisibilityEffect` for effects with cleanup, or `useVisibility` with React's `useEffect` to handle visibility changes.
  * @kind function
  * @description
  * Calls a callback function with the visibility state when the screen's visibility changes.
@@ -67,4 +68,3 @@ export function useVisibilityChange(callback: VisibilityCallback) {
     callback(isVisible ? 'visible' : 'hidden');
   }, [callback, isVisible, prevValue]);
 }
-

package/src/visibility/useVisibilityEffect.spec.tsx

@@ -0,0 +1,160 @@
+import { cleanup, render } from '@testing-library/react';
+import { type EffectCallback, type ReactNode } from 'react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { AppStateProvider } from './useIsAppForeground';
+import { VisibilityChangedProvider } from './useVisibilityChanged';
+import * as visibility from './useVisibilityEffect';
+
+const navigation = vi.hoisted(() => ({ focused: true }));
+vi.mock('./react-navigation/useIsFocusedSafely', () => ({
+  useIsFocusedSafely: () => navigation.focused,
+}));
+
+function Consumer({ effect }: { readonly effect: EffectCallback }) {
+  visibility.useVisibilityEffect(effect);
+  return null;
+}
+
+function Boundary({ visible, children }: { readonly visible: boolean; readonly children: ReactNode }) {
+  return (
+    <AppStateProvider>
+      <VisibilityChangedProvider isVisible={visible}>{children}</VisibilityChangedProvider>
+    </AppStateProvider>
+  );
+}
+
+function screen(visible: boolean, effect: EffectCallback) {
+  return (
+    <Boundary visible={visible}>
+      <Consumer effect={effect} />
+    </Boundary>
+  );
+}
+
+afterEach(() => {
+  cleanup();
+  navigation.focused = true;
+});
+
+describe('useVisibilityEffect', () => {
+  it('exports a visibility effect hook', () => {
+    expect(visibility).toHaveProperty('useVisibilityEffect', expect.any(Function));
+  });
+
+  it('does not set up or clean up an effect when mounted and unmounted hidden', () => {
+    const dispose = vi.fn();
+    const effect = vi.fn(() => dispose);
+    const { unmount } = render(screen(false, effect));
+    unmount();
+    expect(effect).not.toHaveBeenCalled();
+    expect(dispose).not.toHaveBeenCalled();
+  });
+
+  it('sets up on visible mount and cleans up on direct unmount', () => {
+    const dispose = vi.fn();
+    const effect = vi.fn(() => dispose);
+    const { unmount } = render(screen(true, effect));
+    expect(effect).toHaveBeenCalledTimes(1);
+    unmount();
+    expect(dispose).toHaveBeenCalledTimes(1);
+  });
+
+  it('cleans up when hidden and sets up again when visible', () => {
+    const dispose = vi.fn();
+    const effect = vi.fn(() => dispose);
+    const { rerender, unmount } = render(screen(true, effect));
+    rerender(screen(false, effect));
+    expect(dispose).toHaveBeenCalledTimes(1);
+    rerender(screen(true, effect));
+    expect(effect).toHaveBeenCalledTimes(2);
+    unmount();
+    expect(dispose).toHaveBeenCalledTimes(2);
+  });
+
+  it('does not clean up again when unmounted after becoming hidden', () => {
+    const dispose = vi.fn();
+    const { rerender, unmount } = render(screen(true, () => dispose));
+    rerender(screen(false, () => dispose));
+    unmount();
+    expect(dispose).toHaveBeenCalledTimes(1);
+  });
+
+  it('keeps a stable effect running across visible rerenders', () => {
+    const dispose = vi.fn();
+    const effect = vi.fn(() => dispose);
+    const { rerender } = render(screen(true, effect));
+    rerender(screen(true, effect));
+    expect(effect).toHaveBeenCalledTimes(1);
+    expect(dispose).not.toHaveBeenCalled();
+  });
+
+  it('cleans up the previous callback before running its replacement while visible', () => {
+    const events: string[] = [];
+    const first = () => {
+      events.push('first setup');
+      return () => {
+        events.push('first cleanup');
+      };
+    };
+    const second = () => {
+      events.push('second setup');
+    };
+    const { rerender } = render(screen(true, first));
+    rerender(screen(true, second));
+    expect(events).toEqual(['first setup', 'first cleanup', 'second setup']);
+  });
+
+  it('uses the latest callback when it becomes visible after a hidden update', () => {
+    const first = vi.fn();
+    const second = vi.fn();
+    const { rerender } = render(screen(false, first));
+    rerender(screen(false, second));
+    expect(first).not.toHaveBeenCalled();
+    expect(second).not.toHaveBeenCalled();
+    rerender(screen(true, second));
+    expect(first).not.toHaveBeenCalled();
+    expect(second).toHaveBeenCalledTimes(1);
+  });
+
+  it('allows an effect without a cleanup function', () => {
+    const effect = vi.fn(() => {});
+    const { rerender, unmount } = render(screen(true, effect));
+    rerender(screen(false, effect));
+    unmount();
+    expect(effect).toHaveBeenCalledTimes(1);
+  });
+
+  it('cleans up when navigator focus is lost while native visibility stays true', () => {
+    const dispose = vi.fn();
+    const effect = vi.fn(() => dispose);
+    const { rerender } = render(screen(true, effect));
+    navigation.focused = false;
+    rerender(screen(true, effect));
+    expect(dispose).toHaveBeenCalledTimes(1);
+    navigation.focused = true;
+    rerender(screen(true, effect));
+    expect(effect).toHaveBeenCalledTimes(2);
+  });
+
+  it('keeps sibling visibility boundaries independent', () => {
+    const firstDispose = vi.fn();
+    const secondDispose = vi.fn();
+    const first = vi.fn(() => firstDispose);
+    const second = vi.fn(() => secondDispose);
+    const tree = (firstVisible: boolean) => (
+      <>
+        <Boundary visible={firstVisible}>
+          <Consumer effect={first} />
+        </Boundary>
+        <Boundary visible={true}>
+          <Consumer effect={second} />
+        </Boundary>
+      </>
+    );
+    const { rerender } = render(tree(true));
+    rerender(tree(false));
+    expect(firstDispose).toHaveBeenCalledTimes(1);
+    expect(secondDispose).not.toHaveBeenCalled();
+    expect(second).toHaveBeenCalledTimes(1);
+  });
+});

package/src/visibility/useVisibilityEffect.ts

@@ -0,0 +1,44 @@
+import { type EffectCallback, useEffect } from 'react';
+import { useVisibility } from './useVisibility';
+
+/**
+ * @public
+ * @category Screen Control
+ * @name useVisibilityEffect
+ * @description
+ * Runs an effect while the screen is visible, using the visibility state from `useVisibility`.
+ * Cleans up when the screen becomes hidden, the effect callback changes, or the component unmounts.
+ * Like `useEffect`, setup and cleanup run after a render is committed. The callback must be synchronous
+ * and may return a cleanup function. Use `useCallback` to avoid restarting on unrelated renders.
+ * Unlike `useVisibilityChange`, a returned cleanup function is registered with React.
+ *
+ * @param {EffectCallback} effect - Sets up the effect and optionally returns its cleanup function.
+ * @example
+ * ```tsx
+ * import { useCallback } from 'react';
+ * import { BackHandler } from 'react-native';
+ * import { useVisibilityEffect } from '@granite-js/react-native';
+ *
+ * function Screen({ onBack }: { onBack: () => boolean }) {
+ *   useVisibilityEffect(
+ *     useCallback(() => {
+ *       const subscription = BackHandler.addEventListener('hardwareBackPress', onBack);
+ *       return () => subscription.remove();
+ *     }, [onBack])
+ *   );
+ *
+ *   return null;
+ * }
+ * ```
+ */
+export function useVisibilityEffect(effect: EffectCallback): void {
+  const isVisible = useVisibility();
+
+  useEffect(() => {
+    if (!isVisible) {
+      return;
+    }
+
+    return effect();
+  }, [effect, isVisible]);
+}