@granite-js/react-native 0.0.1

package/src/visibility/useIsAppForeground.tsx

@@ -0,0 +1,73 @@
+import { createContext, ReactElement, ReactNode, useContext, useEffect, useState } from 'react';
+import { AppState, AppStateStatus } from 'react-native';
+
+interface Props {
+  children: ReactNode;
+}
+
+const AppStateContext = createContext<AppStateStatus | undefined>(undefined);
+
+/**
+ * @name AppStateProvider
+ * @description
+ * A Provider that manages the `AppState` of React Native screens. This Provider manages the app's state (active, background, etc.) and passes it to child components that subscribe to it.
+ * @link https://reactnative.dev/docs/appstate
+ * @param {Props} children - Child components to be wrapped by `AppStateProvider`. These components can detect and respond to changes in `AppState`.
+ * @returns {ReactElement} - A React Provider component wrapped with `AppStateProvider`.
+ * @example
+ * ```tsx
+ * export function App() {
+ *   return (
+ *     <AppStateProvider>
+ *      <MyApp />
+ *     </AppStateProvider>
+ *   );
+ * }
+ * ```
+ */
+export function AppStateProvider({ children }: Props): ReactElement {
+  const [appState, setAppState] = useState<AppStateStatus>(AppState.currentState);
+
+  const handleAppStateChange = (status: AppStateStatus) => {
+    setAppState(status);
+  };
+
+  useEffect(() => {
+    const subscription = AppState.addEventListener('change', handleAppStateChange);
+
+    return () => {
+      subscription.remove();
+    };
+  }, []);
+
+  return <AppStateContext.Provider value={appState}>{children}</AppStateContext.Provider>;
+}
+
+/**
+ * @category Hooks
+ * @name useIsAppForeground
+ * @description
+ * Returns whether the React Native app is in the foreground state.
+ *
+ * @see https://reactnative.dev/docs/0.72/appstate#app-states
+ * @returns {boolean} - Returns whether the app is in the foreground state.
+ * @throws {Error} Throws an error when the managed AppState is `null`.
+ * @example
+ * ```typescript
+ *  const isForeground = useIsAppForeground();
+ * ```
+ */
+export const useIsAppForeground = (): boolean => {
+  const appState = useContext(AppStateContext);
+
+  if (appState == null) {
+    throw new Error('useIsAppForeground must be used within a AppStateProvider');
+  }
+
+  /**
+   * In iOS, the 'inactive' state is also considered as foreground.
+   * 'inactive' is a state that only exists in iOS, for example, when the control center or notification panel is open.
+   * @see https://reactnative.dev/docs/0.72/appstate#app-states
+   */
+  return appState === 'active' || appState === 'inactive';
+};

package/src/visibility/useVisibility.tsx

@@ -0,0 +1,54 @@
+import { Platform } from 'react-native';
+import { useIsFocusedSafely } from './react-navigation/useIsFocusedSafely';
+import { useIsAppForeground } from './useIsAppForeground';
+import { useVisibilityChanged } from './useVisibilityChanged';
+
+/**
+ * @public
+ * @category Screen Control
+ * @name useVisibility
+ * @description
+ * Returns whether the screen is visible to the user.
+ * Returns `true` if the app's screen is currently visible to the user, and `false` if it's not. However, the screen visibility state does not change when opening and closing the system share modal ([share](/reference/react-native/Share/share)).
+ *
+ * Usage examples:
+ * - Returns `false` when switching to another app or pressing the home button.
+ * - Returns `true` when returning to the granite app or when the screen becomes visible.
+ * - Returns `false` when navigating to another service within the granite app.
+ *
+ * @returns {boolean} - Whether the current screen is visible to the user.
+ * @example
+ *
+ * ### Example of checking screen visibility
+ *
+ * ```tsx
+ * import { useEffect } from 'react';
+ * import { Text } from 'react-native';
+ * import { useVisibility } from '@granite-js/react-native';
+ *
+ * export function UseVisibilityExample() {
+ *   const visibility = useVisibility();
+ *
+ *   useEffect(() => {
+ *     console.log({ visibility });
+ *   }, [visibility]);
+ *
+ *   return <Text>Logs are created when leaving and returning to the home screen.</Text>;
+ * }
+ * ```
+ */
+export function useVisibility(): boolean {
+  const visible = useVisibilityChanged();
+  const isForeground = useIsAppForeground();
+  const isReactNavigationFocused = useIsFocusedSafely();
+
+  /**
+   * We don't use AppState in Android. (AppState uses `onHostPause` and `onHostResume`.)
+   * From Android version 5.172.0, `visibilityChanged` uses `onHostStop` and `onHostStart`.
+   *  - For example, in Android, the `visible` state is maintained even when the share modal appears (share app bridge call).
+   */
+  const androidCondition = visible && isReactNavigationFocused;
+  const iOSCondition = visible && isForeground && isReactNavigationFocused;
+
+  return Platform.OS === 'android' ? androidCondition : iOSCondition;
+}

package/src/visibility/useVisibilityChange.ts

@@ -0,0 +1,69 @@
+import { useEffect } from 'react';
+import { useVisibility } from './useVisibility';
+import { usePrevious } from './utils/usePrevious';
+
+/**
+ * String representing whether the screen is visible.
+ * @typedef {string} VisibilityState
+ * @property {'visible'} visible - The screen is visible.
+ * @property {'hidden'} hidden - The screen is not visible.
+ */
+export type VisibilityState = 'visible' | 'hidden';
+
+/**
+ * @callback VisibilityCallback
+ * @param {VisibilityState} state - String representing the visibility state of the screen.
+ */
+export type VisibilityCallback = (state: VisibilityState) => void;
+
+/**
+ * @public
+ * @category Screen Control
+ * @name useVisibilityChange
+ * @kind function
+ * @description
+ * Calls a callback function with the visibility state when the screen's visibility changes.
+ * The callback function receives the return value from [useVisibility](/en/reference/react-native/Screen%20Control/useVisibility). If the return value is `true`, it passes 'visible', and if `false`, it passes 'hidden'.
+ *
+ * @param {VisibilityCallback} callback - Calls a callback function that receives visibility changes when the screen's visibility changes.
+ * @example
+ *
+ * ### Example of logging when screen visibility changes
+ *
+ * ```tsx
+ * import { useState } from 'react';
+ * import { Text, View } from 'react-native';
+ * import { useVisibilityChange, VisibilityState } from '@granite-js/react-native';
+ *
+ * export function UseVisibilityChangeExample() {
+ *   const [visibilityHistory, setVisibilityHistory] = useState<VisibilityState[]>([]);
+ *
+ *   useVisibilityChange((visibility) => {
+ *     setVisibilityHistory((prev) => [...prev, visibility]);
+ *   });
+ *
+ *   return (
+ *     <View>
+ *       <Text>Logs are created when leaving and returning to the home screen.</Text>
+ *
+ *       {visibilityHistory.map((visibility, index) => (
+ *         <Text key={index}>{JSON.stringify(visibility)}</Text>
+ *       ))}
+ *     </View>
+ *   );
+ * }
+ * ```
+ */
+export function useVisibilityChange(callback: VisibilityCallback) {
+  const isVisible = useVisibility();
+
+  const prevValue = usePrevious<boolean>(isVisible) ?? false;
+
+  useEffect(() => {
+    if (prevValue === isVisible) {
+      return;
+    }
+
+    callback(isVisible ? 'visible' : 'hidden');
+  }, [callback, isVisible, prevValue]);
+}

package/src/visibility/useVisibilityChanged.tsx

@@ -0,0 +1,69 @@
+import { createContext, PropsWithChildren, ReactElement, useContext, useEffect, useState } from 'react';
+import { nativeEventEmitter } from '../native-event-emitter';
+
+const VisibilityChangedContext = createContext<boolean | undefined>(undefined);
+
+/**
+ * @name VisibilityChangedProvider
+ * @kind function
+ * @description
+ * A Provider that manages whether a React Native screen is visible.
+ * It subscribes to the app's `visibilityChanged` event to detect and manage screen visibility.
+ *
+ * @param {ReactNode | undefined} children - Child components that check screen visibility.
+ * @param {boolean} isVisible - A boolean value indicating whether the screen is visible.
+ * @returns {ReactElement} - A React Provider component wrapped with `VisibilityChangedContext.Provider`.
+ * @example
+ * ```typescript
+ * export function VisibilityProvider({ isVisible, children }: Props) {
+ *   return (
+ *     <VisibilityChangedProvider isVisible={isVisible}>
+ *       {children}
+ *     </VisibilityChangedProvider>
+ *   );
+ * }
+ * ```
+ */
+export function VisibilityChangedProvider({
+  children,
+  isVisible,
+}: PropsWithChildren<{ isVisible: boolean }>): ReactElement {
+  const [visible, setVisible] = useState(isVisible);
+
+  useEffect(() => {
+    const subscription = nativeEventEmitter.addListener('visibilityChanged', (nextVisible) => {
+      setVisible(nextVisible);
+    });
+
+    return () => {
+      subscription.remove();
+    };
+  }, []);
+
+  return <VisibilityChangedContext.Provider value={visible}>{children}</VisibilityChangedContext.Provider>;
+}
+
+/**
+ * @name useVisibilityChanged
+ * @category Hooks
+ * @kind function
+ * @description
+ * A Hook that returns whether a React Native screen is visible.
+ * @returns {boolean} - Returns whether the screen is visible.
+ * @throws {Error} Throws an error when not used within a `VisibilityChangedProvider`.
+ * @example
+ * ```typescript
+ * const isVisible = useVisibilityChanged();
+ * console.log(isVisible);
+ * // true or false
+ * ```
+ */
+export function useVisibilityChanged(): boolean {
+  const isVisible = useContext(VisibilityChangedContext);
+
+  if (isVisible == null) {
+    throw new Error('useVisibilityChanged must be used within a VisibilityChangedProvider');
+  }
+
+  return isVisible;
+}

package/src/visibility/utils/usePrevious.tsx

@@ -0,0 +1,24 @@
+import { useEffect, useRef } from 'react';
+
+/**
+ * @name usePrevious
+ * @category Hooks
+ * @kind function
+ * @description
+ * A Hook that returns the previous value.
+ * @param {T} value - The value to return the previous value of.
+ * @returns {T} - Returns the previous value.
+ * @example
+ * ```typescript
+ *  const isVisible = useVisibility();
+ *  const prevValue = usePrevious<boolean>(isVisible) ?? false;
+ * ```
+ */
+export function usePrevious<T>(value: T): T {
+  const ref: any = useRef<T>();
+  useEffect(() => {
+    ref.current = value;
+  }, [value]);
+
+  return ref.current;
+}