@granite-js/react-native 0.0.0-dev-20250725013859

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