@granite-js/react-native 2.5.0 → 2.5.1

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @granite-js/react-native
 
+## 2.5.1
+
+### Patch Changes
+
+- a686133: Read navigation focus through `useSyncExternalStore` so focus changes between rendering and subscription are not missed by `useIsFocusedSafely`, `useVisibility`, or visibility effects. Preserve the focused fallback when no navigation context is available.
+
+  Visibility effects follow committed visibility snapshots with React's effect setup and cleanup lifecycle.
+  - @granite-js/blur-view@2.5.1
+  - @granite-js/brownfield-module@2.5.1
+  - @granite-js/cli@2.5.1
+  - @granite-js/jest@2.5.1
+  - @granite-js/mpack@2.5.1
+  - @granite-js/plugin-core@2.5.1
+  - @granite-js/style-utils@2.5.1
+  - @granite-js/video@2.5.1
+
 ## 2.5.0
 
 ### Minor Changes

package/dist/visibility/react-navigation/useIsFocusedSafely.d.ts

@@ -9,6 +9,7 @@
  * A Hook that safely uses `useIsFocused` provided by `@react-navigation/native`.
  * This Hook is based on `useIsFocused` from `@react-navigation/native`, but modified to not throw errors when `navigation` or `root` objects are `null` or `undefined`.
  * It ensures that users don't see errors even when the code is used in environments where `@react-navigation/native` is not used.
+ * Focus is read as an external store snapshot so changes between rendering and subscription are observed.
  *
  * @returns {boolean} - Returns the focus state of the current screen.
  * @example

package/dist/visibility/useVisibilityEffect.d.ts

@@ -8,7 +8,9 @@ import { type EffectCallback } from 'react';
  * 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.
+ * Effects follow the visibility snapshot from the committed render; later focus changes apply on a subsequent commit.
  * Unlike `useVisibilityChange`, a returned cleanup function is registered with React.
+ * Effect ordering between different screens is not guaranteed; navigation events do not invoke this callback synchronously.
  *
  * @param {EffectCallback} effect - Sets up the effect and optionally returns its cleanup function.
  * @example

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@granite-js/react-native",
-  "version": "2.5.0",
+  "version": "2.5.1",
   "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.5.0",
-    "@granite-js/vitest": "2.5.0",
+    "@granite-js/native": "2.5.1",
+    "@granite-js/vitest": "2.5.1",
     "@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.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",
+    "@granite-js/blur-view": "2.5.1",
+    "@granite-js/brownfield-module": "2.5.1",
+    "@granite-js/cli": "2.5.1",
+    "@granite-js/jest": "2.5.1",
+    "@granite-js/mpack": "2.5.1",
+    "@granite-js/plugin-core": "2.5.1",
+    "@granite-js/style-utils": "2.5.1",
+    "@granite-js/video": "2.5.1",
     "@standard-schema/spec": "^1.0.0",
     "es-toolkit": "^1.39.8",
     "react-native-url-polyfill": "3.0.0"

package/src/visibility/react-navigation/useIsFocusedSafely.spec.tsx

@@ -0,0 +1,216 @@
+import { act, cleanup, render, renderHook } from '@testing-library/react';
+import { type EffectCallback, type ReactNode, useEffect, useLayoutEffect } from 'react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { useIsFocusedSafely } from './useIsFocusedSafely';
+import { AppStateProvider } from '../useIsAppForeground';
+import { VisibilityChangedProvider } from '../useVisibilityChanged';
+import { useVisibilityEffect } from '../useVisibilityEffect';
+
+function createNavigation(initialFocus: boolean) {
+  let focused = initialFocus;
+  const listeners = { focus: new Set<() => void>(), blur: new Set<() => void>() };
+  return {
+    isFocused: () => focused,
+    addListener(event: 'focus' | 'blur', listener: () => void) {
+      listeners[event].add(listener);
+      return () => {
+        listeners[event].delete(listener);
+      };
+    },
+    setFocused(value: boolean) {
+      focused = value;
+      listeners[value ? 'focus' : 'blur'].forEach((listener) => listener());
+    },
+    listenerCount: () => listeners.focus.size + listeners.blur.size,
+  };
+}
+
+let navigation: ReturnType<typeof createNavigation> | undefined;
+vi.mock('./useNavigationSafely', () => ({ useNavigationSafely: () => navigation }));
+
+beforeEach(() => {
+  navigation = undefined;
+});
+afterEach(cleanup);
+
+describe('useIsFocusedSafely', () => {
+  it('returns true without a navigation context', () => {
+    const { result } = renderHook(useIsFocusedSafely);
+    expect(result.current).toBe(true);
+  });
+
+  it.each([false, true])('reads the initial focus snapshot (%s)', (focused) => {
+    navigation = createNavigation(focused);
+    const { result } = renderHook(useIsFocusedSafely);
+    expect(result.current).toBe(focused);
+  });
+
+  it.each([false, true])('detects a change from %s before its subscription starts', (initiallyFocused) => {
+    const store = createNavigation(initiallyFocused);
+    navigation = store;
+    function CommitChange({ children }: { readonly children: ReactNode }) {
+      useLayoutEffect(() => {
+        expect(store.listenerCount()).toBe(0);
+        store.setFocused(!initiallyFocused);
+      }, []);
+      return children;
+    }
+    const { result } = renderHook(useIsFocusedSafely, { wrapper: CommitChange });
+    expect(result.current).toBe(!initiallyFocused);
+  });
+
+  it('reads the current snapshot for focus and blur notifications', () => {
+    const store = createNavigation(false);
+    navigation = store;
+    const { result } = renderHook(useIsFocusedSafely);
+    act(() => store.setFocused(true));
+    expect(result.current).toBe(true);
+    act(() => store.setFocused(false));
+    expect(result.current).toBe(false);
+  });
+
+  it('replaces subscriptions when navigation changes and removes them on unmount', () => {
+    const first = createNavigation(true);
+    const second = createNavigation(false);
+    navigation = first;
+    const { result, rerender, unmount } = renderHook(useIsFocusedSafely);
+    expect(first.listenerCount()).toBe(2);
+    navigation = second;
+    rerender();
+    expect(first.listenerCount()).toBe(0);
+    expect(second.listenerCount()).toBe(2);
+    expect(result.current).toBe(false);
+    act(() => first.setFocused(false));
+    expect(result.current).toBe(false);
+    act(() => second.setFocused(true));
+    expect(result.current).toBe(true);
+    unmount();
+    expect(second.listenerCount()).toBe(0);
+  });
+
+  it('restores the fallback when navigation is removed', () => {
+    const store = createNavigation(false);
+    navigation = store;
+    const { result, rerender } = renderHook(useIsFocusedSafely);
+    navigation = undefined;
+    rerender();
+    expect(result.current).toBe(true);
+    expect(store.listenerCount()).toBe(0);
+  });
+
+  it.each([false, true])('follows committed focus snapshots for visibility effects (initially %s)', (initiallyFocused) => {
+    const store = createNavigation(initiallyFocused);
+    navigation = store;
+    const dispose = vi.fn();
+    const effect = vi.fn(() => dispose);
+    function Consumer() {
+      useVisibilityEffect(effect);
+      return null;
+    }
+    function CommitChange() {
+      useLayoutEffect(() => store.setFocused(!initiallyFocused), []);
+      return null;
+    }
+    const { unmount } = render(
+      <AppStateProvider>
+        <VisibilityChangedProvider isVisible={true}>
+          <Consumer />
+          <CommitChange />
+        </VisibilityChangedProvider>
+      </AppStateProvider>
+    );
+    expect(effect).toHaveBeenCalledTimes(1);
+    expect(dispose).toHaveBeenCalledTimes(initiallyFocused ? 1 : 0);
+    unmount();
+    expect(dispose).toHaveBeenCalledTimes(1);
+    expect(store.listenerCount()).toBe(0);
+  });
+
+  it.each(['mount', 'callback replacement'] as const)(
+    'keeps the committed visibility effect active across rapid refocus during %s',
+    (scenario) => {
+      const store = createNavigation(true);
+      navigation = store;
+      const firstDispose = vi.fn();
+      const firstEffect = vi.fn(() => firstDispose);
+      const dispose = vi.fn();
+      const effect = vi.fn(() => dispose);
+      function Consumer({ callback }: { readonly callback: EffectCallback }) {
+        useVisibilityEffect(callback);
+        return null;
+      }
+      function CommitChange({ changeFocus }: { readonly changeFocus: boolean }) {
+        useLayoutEffect(() => {
+          if (changeFocus) {
+            store.setFocused(false);
+          }
+        }, [changeFocus]);
+        useEffect(() => {
+          if (changeFocus) {
+            expect(effect).toHaveBeenCalledTimes(1);
+            store.setFocused(true);
+            // Refocusing must not restart the effect from the visible commit.
+            expect(effect).toHaveBeenCalledTimes(1);
+            expect(dispose).not.toHaveBeenCalled();
+          }
+        }, [changeFocus]);
+        return null;
+      }
+      const screen = (changeFocus: boolean) => (
+        <AppStateProvider>
+          <VisibilityChangedProvider isVisible={true}>
+            <Consumer callback={changeFocus ? effect : firstEffect} />
+            <CommitChange changeFocus={changeFocus} />
+          </VisibilityChangedProvider>
+        </AppStateProvider>
+      );
+      const { rerender, unmount } = render(screen(scenario === 'mount'));
+      rerender(screen(true));
+      expect(effect).toHaveBeenCalledTimes(1);
+      expect(firstDispose).toHaveBeenCalledTimes(scenario === 'mount' ? 0 : 1);
+      expect(store.listenerCount()).toBe(2);
+
+      rerender(screen(true));
+      expect(effect).toHaveBeenCalledTimes(1);
+      expect(dispose).not.toHaveBeenCalled();
+
+      unmount();
+      expect(dispose).toHaveBeenCalledTimes(1);
+      expect(store.listenerCount()).toBe(0);
+    }
+  );
+
+  it('cleans up and restarts visibility effects as focus snapshots are committed', () => {
+    const store = createNavigation(true);
+    navigation = store;
+    const dispose = vi.fn();
+    const effect = vi.fn(() => dispose);
+    function Consumer() {
+      useVisibilityEffect(effect);
+      return null;
+    }
+    function CommitChange() {
+      useLayoutEffect(() => store.setFocused(false), []);
+      return null;
+    }
+    const { unmount } = render(
+      <AppStateProvider>
+        <VisibilityChangedProvider isVisible={true}>
+          <Consumer />
+          <CommitChange />
+        </VisibilityChangedProvider>
+      </AppStateProvider>
+    );
+    expect(effect).toHaveBeenCalledTimes(1);
+    expect(dispose).toHaveBeenCalledTimes(1);
+    expect(store.listenerCount()).toBe(2);
+
+    act(() => store.setFocused(true));
+    expect(effect).toHaveBeenCalledTimes(2);
+    act(() => store.setFocused(false));
+    expect(dispose).toHaveBeenCalledTimes(2);
+    unmount();
+    expect(dispose).toHaveBeenCalledTimes(2);
+    expect(store.listenerCount()).toBe(0);
+  });
+});

package/src/visibility/react-navigation/useIsFocusedSafely.tsx

@@ -1,4 +1,4 @@
-import { useDebugValue, useEffect, useState } from 'react';
+import { useCallback, useDebugValue, useSyncExternalStore } from 'react';
 import { useNavigationSafely } from './useNavigationSafely';
 
 /**
@@ -12,6 +12,7 @@ import { useNavigationSafely } from './useNavigationSafely';
  * A Hook that safely uses `useIsFocused` provided by `@react-navigation/native`.
  * This Hook is based on `useIsFocused` from `@react-navigation/native`, but modified to not throw errors when `navigation` or `root` objects are `null` or `undefined`.
  * It ensures that users don't see errors even when the code is used in environments where `@react-navigation/native` is not used.
+ * Focus is read as an external store snapshot so changes between rendering and subscription are observed.
  *
  * @returns {boolean} - Returns the focus state of the current screen.
  * @example
@@ -22,37 +23,22 @@ import { useNavigationSafely } from './useNavigationSafely';
  */
 export function useIsFocusedSafely(): boolean {
   const navigation = useNavigationSafely();
-  const isNavigationFocused = () => navigation?.isFocused() ?? true;
-
-  const [isFocused, setIsFocused] = useState(isNavigationFocused());
-
-  const valueToReturn = isNavigationFocused();
-
-  if (isFocused !== valueToReturn) {
-    // If the value has changed since the last render, we need to update it.
-    // This could happen if we missed an update from the event listeners during re-render.
-    // React will process this update immediately, so the old subscription value won't be committed.
-    // It is still nice to avoid returning a mismatched value though, so let's override the return value.
-    // This is the same logic as in https://github.com/facebook/react/tree/master/packages/use-subscription
-    setIsFocused(valueToReturn);
-  }
-
-  useEffect(() => {
-    if (navigation == null) {
-      return;
-    }
-
-    const unsubscribeFocus = navigation.addListener('focus', () => setIsFocused(true));
-
-    const unsubscribeBlur = navigation.addListener('blur', () => setIsFocused(false));
-
-    return () => {
-      unsubscribeFocus();
-      unsubscribeBlur();
-    };
-  }, [navigation]);
-
-  useDebugValue(valueToReturn);
-
-  return valueToReturn;
+  const getSnapshot = useCallback(() => navigation?.isFocused() ?? true, [navigation]);
+  const subscribe = useCallback(
+    (onStoreChange: () => void) => {
+      const unsubscribeFocus = navigation?.addListener('focus', onStoreChange);
+      const unsubscribeBlur = navigation?.addListener('blur', onStoreChange);
+
+      return () => {
+        unsubscribeFocus?.();
+        unsubscribeBlur?.();
+      };
+    },
+    [navigation]
+  );
+
+  const isFocused = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+  useDebugValue(isFocused);
+
+  return isFocused;
 }

package/src/visibility/useVisibilityEffect.ts

@@ -10,7 +10,9 @@ import { useVisibility } 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.
+ * Effects follow the visibility snapshot from the committed render; later focus changes apply on a subsequent commit.
  * Unlike `useVisibilityChange`, a returned cleanup function is registered with React.
+ * Effect ordering between different screens is not guaranteed; navigation events do not invoke this callback synchronously.
  *
  * @param {EffectCallback} effect - Sets up the effect and optionally returns its cleanup function.
  * @example