@granite-js/react-native 0.0.1

package/src/router/utils/screen.tsx

@@ -0,0 +1,111 @@
+import { getRoutePath } from './path';
+import { routeMap } from '../createRoute';
+import { RequireContext, RouteScreen } from '../types';
+
+/**
+ * @kind function
+ * @name getRouteScreens
+ * @description
+ * Gets screens from the pages folder.
+ *
+ * @param {RequireContext} context - Object containing information about screens in Router
+ * @returns {RouteScreen[]} screens - Returns a list of screens that can be navigated to.
+ *
+ * @example
+ * ```tsx
+ * import { getRouteScreens } from '@granite-js/react-native';
+ *
+ * const context = require.context('../pages');
+ * const screens = getRouteScreens(context);
+ * ```
+ */
+export function getRouteScreens(context: RequireContext): RouteScreen[] {
+  const screens = context.keys().map((key) => {
+    const path = getRoutePath(key);
+
+    /**
+     * Keep export default option for backward compatibility.
+     * If migrated to type-safe, only export Route will be needed.
+     */
+    const component = context(key)?.default ?? routeMap.get(context(key)?.Route?._path)?.component;
+
+    if (component == null) {
+      throw new Error(`Page component not found in ${key}.`);
+    }
+
+    return {
+      path,
+      component,
+    };
+  });
+
+  return screens;
+}
+
+/**
+ * @kind function
+ * @name getScreenPathMapConfig
+ * @description Maps paths of screens.
+ *
+ * @param {RouteScreen[]} routeScreens - List of screens that can be navigated to
+ *
+ * @example
+ * ```tsx
+ * import { registerPage, getRouteScreens, getScreenPathMapConfig, Router } from '@granite-js/react-native';
+ * import { context } from '../require.context';
+ *
+ * function App() {
+ *   return <Router context={context} prefix={'scheme://minibench'} />;
+ * }
+ *
+ * export default registerPage(
+ *   App,
+ *   'minibench',
+ *   getScreenPathMapConfig(getRouteScreens(context))
+ * );
+ * ```
+ */
+export function getScreenPathMapConfig(routeScreens: RouteScreen[]) {
+  const screensConfig: ScreenPath = {};
+
+  routeScreens.forEach((routeScreen) => {
+    const routePath = routeScreen.path;
+
+    if (screensConfig[routePath] != null) {
+      throw new Error(`${routePath} is already registered. Please check for duplicate paths.`);
+    }
+
+    screensConfig[routePath] = {
+      path: routePath,
+    };
+  });
+
+  // @see https://reactnavigation.org/docs/configuring-links/#matching-exact-paths
+  // This is a mapping for the root path ('/') for deep link handling.
+  // Example: To handle URLs like scheme://{service_name}?name=John,
+  // map the root path to an empty string to correctly extract query parameters.
+  screensConfig['/'] = {
+    path: '',
+  };
+
+  // https://reactnavigation.org/docs/configuring-links/#handling-unmatched-routes-or-404
+  screensConfig['/_404'] = {
+    path: '*',
+  };
+
+  return screensConfig;
+}
+
+/**
+ * @name ScreenPath
+ * @description
+ * Type representing screen paths.
+ *
+ * @typedef {Record<string, { path?: string }>} ScreenPath
+ */
+export type ScreenPath = Record<
+  string,
+  {
+    path?: string;
+  }
+>;

package/src/scroll-view-inertial-background/ScrollViewInertialBackground.tsx

@@ -0,0 +1,99 @@
+import type { ComponentProps } from 'react';
+import { useWindowDimensions, View } from 'react-native';
+
+interface ScrollViewInertialBackgroundProps {
+  topColor?: string;
+  bottomColor?: string;
+  spacer?: number;
+}
+
+/**
+ * @public
+ * @category UI
+ * @name ScrollViewInertialBackground
+ * @description
+ * Adds background colors to the top and bottom spaces of iOS `ScrollView` content to provide a natural visual effect when scrolling.
+ * In iOS, when scrolling reaches the end, a slight bouncing effect occurs, known as the [Bounce effect](https://medium.com/@wcandillon/ios-bounce-list-effect-with-react-native-5102e3a83999). Setting background colors in the spaces above and below the content can provide a more consistent user experience.
+ *
+ * @param {object} [props] - `props` object passed to the component.
+ * @param {string} [props.topColor] - Background color to apply to the top area of the scroll. Default is `adaptive.background` which is automatically applied based on the system theme.
+ * @param {string} [props.bottomColor] - Background color to apply to the bottom area of the scroll. Default is `adaptive.background` which is automatically applied based on the system theme.
+ * @param {number} [props.spacer] - Specifies the size of the space between the top and bottom areas where the background color is applied. Default uses the screen height obtained from [`useWindowDimensions`](https://reactnative.dev/docs/next/usewindowdimensions).
+ *
+ * @example
+ *
+ * ### Adding background colors to the top and bottom of a scroll view
+ *
+ * Adds red background color to the top and blue to the bottom of the scroll view. The background color is applied to areas outside the scroll.
+ *
+ * ```tsx
+ * import { ScrollView, View, Text } from 'react-native';
+ * import { ScrollViewInertialBackground } from '@granite-js/react-native';
+ *
+ * const dummies = Array.from({ length: 20 }, (_, i) => i);
+ *
+ * export function InertialBackgroundExample() {
+ *   return (
+ *     <ScrollView>
+ *       <ScrollViewInertialBackground topColor="red" bottomColor="blue" />
+ *       {dummies.map((i) => (
+ *         <View
+ *           key={`dummy-${i}`}
+ *           style={{ width: '100%', height: 100, borderBottomColor: 'black', borderBottomWidth: 1 }}
+ *         >
+ *           <Text>Try scrolling.</Text>
+ *         </View>
+ *       ))}
+ *     </ScrollView>
+ *   );
+ * }
+ * ```
+ */
+export function ScrollViewInertialBackground({
+  topColor,
+  bottomColor,
+  spacer: _spacer,
+}: ScrollViewInertialBackgroundProps) {
+  const windowHeight = useWindowDimensions().height;
+
+  const spacer = _spacer ?? windowHeight;
+  const topBackgroundColor = topColor ?? DEFAULT_BACKGROUND_COLOR;
+  const bottomBackgroundColor = bottomColor ?? DEFAULT_BACKGROUND_COLOR;
+
+  return (
+    <>
+      <HiddenView
+        style={{
+          height: spacer,
+          top: -spacer,
+          backgroundColor: topBackgroundColor,
+        }}
+      />
+      <HiddenView
+        style={{
+          height: spacer,
+          /** Reduces by the CTA GradientHeight area. */
+          bottom: -spacer + GRADIENT_HEIGHT,
+          backgroundColor: bottomBackgroundColor,
+        }}
+      />
+    </>
+  );
+}
+
+function HiddenView({ style, pointerEvents = 'none', ...props }: ComponentProps<typeof View>) {
+  return (
+    <View
+      pointerEvents={pointerEvents}
+      style={[{ position: 'absolute', width: '100%', zIndex: -1, left: 0, right: 0 }, style]}
+      {...props}
+    />
+  );
+}
+
+/**
+ * FIXME:
+ * Gradient value for BottomCTA. Set as a fixed value to avoid peerDeps.
+ */
+const GRADIENT_HEIGHT = 37;
+const DEFAULT_BACKGROUND_COLOR = '#ffffff';

package/src/scroll-view-inertial-background/index.ts

@@ -0,0 +1 @@
+export * from './ScrollViewInertialBackground';

package/src/types/global.ts

@@ -0,0 +1,31 @@
+/* eslint-disable @typescript-eslint/naming-convention */
+/* eslint-disable no-var */
+import type { ComponentType } from 'react';
+
+export interface GraniteGlobal {
+  shared: {
+    buildNumber: string;
+  };
+  app: {
+    name: string;
+    scheme: string;
+    buildNumber: string;
+  };
+}
+
+declare global {
+  // @internal
+  var __SPLIT_CHUNK_ENABLED__: boolean;
+
+  // @internal
+  var __granite_require__: (id: string) => any;
+
+  // @internal
+  var __granite: GraniteGlobal;
+
+  // @internal
+  var Page: ComponentType<any>;
+
+  var window: { __granite: GraniteGlobal };
+  var global: { __granite: GraniteGlobal };
+}

package/src/use-back-event/index.ts

@@ -0,0 +1 @@
+export * from './useBackEvent';

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

@@ -0,0 +1,260 @@
+import { createContext, ReactNode, useCallback, useContext, useEffect, useMemo, useRef, useState } from 'react';
+import { useVisibility } from '../visibility';
+
+export interface BackEventControls {
+  addEventListener: (...handlers: Array<() => void>) => void;
+  removeEventListener: (...handlers: Array<() => void>) => void;
+}
+
+interface PrivateBackEventControls extends BackEventControls {
+  handlersRef: Set<() => void>;
+  hasBackEvent: boolean;
+  onBack: () => void;
+}
+
+const BackEventContext = createContext<PrivateBackEventControls | null>(null);
+
+/**
+ * @component
+ * @name BackEventProvider
+ * @description
+ * A component that provides a `Context` for handling back events within the app. Using this component, child components can subscribe to and manage back events. Placing `BackEventProvider` at the top of the tree allows all back events to be handled centrally.
+ *
+ * @param {ReactNode} children Child components that will control back events.
+ * @param {BackEventControls} backEvent Control object for handling back events. You can register back events using the `addEventListener` method and remove registered back events using the `removeEventListener` method.
+ * @returns {JSX.Element} A component that can handle back events.
+ *
+ * By adding `BackEventProvider` as shown below, child components can handle back events.
+ *
+ * @example
+ * ```jsx
+ * const backEventControls = {
+ *   addEventListener: (handler) => { ... },
+ *   removeEventListener: (handler) => { ... },
+ * };
+ *
+ * <BackEventProvider backEvent={backEventControls}>
+ *   <App />
+ * </BackEventProvider>
+ * ```
+ */
+export function BackEventProvider({
+  children,
+  backEvent,
+}: {
+  children: ReactNode;
+  backEvent: PrivateBackEventControls;
+}) {
+  return <BackEventContext.Provider value={backEvent}>{children}</BackEventContext.Provider>;
+}
+
+/**
+ * @name useBackEventState
+ * @description
+ * A hook that returns the current back event state and control methods managed by `BackEventProvider`. Using this hook, you can add or remove back event handlers and check the current state.
+ *
+ * @returns {{ handlers: Array<() => void>, backEvent: BackEventControls, routerProps: { canGoBack: boolean, onBack: () => void } }} Returns an array of back event handlers, the event control method `backEvent`, and `routerProps` that can be used when handling back functionality in the router.
+ *
+ * Using this Hook, you can add or remove back event handlers and integrate with the router.
+ *
+ * @example
+ * ```javascript
+ * const { backEvent, routerProps } = useBackEventState();
+ * // Handle back events in the router through routerProps
+ * backEvent.addEventListener(() => {
+ *   console.log('Back event triggered');
+ * });
+ *
+ * return (
+ *   <BackEventProvider backEvent={backEvent}>
+ *     <GraniteRouter {...routerProps} context={context} prefix={'scheme://testbench'} />
+ *   </BackEventProvider>
+ * );
+ *
+ * ```
+ */
+export function useBackEventState() {
+  const handlersRef = useRef<Set<() => void>>(new Set()).current;
+  const [hasBackEvent, setHasBackEvent] = useState(false);
+
+  const addEventListener = useCallback(
+    (...handlers: Array<() => void>) => {
+      for (const handler of handlers) {
+        handlersRef.add(handler);
+      }
+
+      if (handlersRef.size > 0) {
+        setHasBackEvent(true);
+      }
+    },
+    [handlersRef]
+  );
+
+  const removeEventListener = useCallback(
+    (...handlers: Array<() => void>) => {
+      for (const handler of handlers) {
+        handlersRef.delete(handler);
+      }
+
+      if (handlersRef.size === 0) {
+        setHasBackEvent(false);
+      }
+    },
+    [handlersRef]
+  );
+
+  const backEvent = useMemo((): PrivateBackEventControls => {
+    return {
+      addEventListener,
+      removeEventListener,
+      handlersRef,
+      hasBackEvent,
+      onBack: () => {
+        handlersRef.forEach((handler) => handler());
+      },
+    };
+  }, [addEventListener, handlersRef, hasBackEvent, removeEventListener]);
+
+  return backEvent;
+}
+
+/**
+ * @public
+ * @category Screen Control
+ * @name useBackEvent
+ * @description
+ * A Hook that returns a controller object for registering and removing back events. Using this Hook, you can handle back events only when a specific component is active.
+ * Use `addEventListener` to register back events and `removeEventListener` to remove them.
+ * Registered back events are only active when the user is viewing the screen. The condition for viewing the screen is determined using [useVisibility](/en/reference/react-native/Screen%20Control/useVisibility).
+ *
+ * Using this Hook, you can define logic to handle back events in specific components.
+ *
+ * @returns {BackEventControls} An object that can control back events. This object includes the `addEventListener` method for registering events and the `removeEventListener` method for removing them.
+ *
+ * @throws {Error} Throws an error if this hook is not used within a `BackEventProvider`.
+ *
+ * @example
+ *
+ * ### Example of Registering and Removing Back Events
+ *
+ * - **When the "Add BackEvent" button is pressed, a back event is registered.** After that, pressing the back button shows an alert with "back" and prevents actual navigation.
+ * - **When the "Remove BackEvent" button is pressed, the registered event is removed.** After that, pressing the back button navigates back normally as per default behavior.
+ *
+ * ```tsx
+ * import { useEffect, useState } from 'react';
+ * import { Alert, Button, View } from 'react-native';
+ * import { useBackEvent } from '@granite-js/react-native';
+ *
+ * export function UseBackEventExample() {
+ *   const backEvent = useBackEvent();
+ *
+ *   const [handler, setHandler] = useState<{ callback: () => void } | undefined>(undefined);
+ *
+ *   useEffect(() => {
+ *     const callback = handler?.callback;
+ *
+ *     if (callback != null) {
+ *       backEvent.addEventListener(callback);
+ *
+ *       return () => {
+ *         backEvent.removeEventListener(callback);
+ *       };
+ *     }
+ *
+ *     return;
+ *   }, [backEvent, handler]);
+ *
+ *   return (
+ *     <View>
+ *       <Button
+ *         title="Add BackEvent"
+ *         onPress={() => {
+ *           setHandler({ callback: () => Alert.alert('back') });
+ *         }}
+ *       />
+ *       <Button
+ *         title="Remove BackEvent"
+ *         onPress={() => {
+ *           setHandler(undefined);
+ *         }}
+ *       />
+ *     </View>
+ *   );
+ * }
+ * ```
+ */
+export function useBackEvent() {
+  const context = useContext(BackEventContext);
+  const handlersRef = useRef<Set<() => void>>(new Set()).current;
+
+  const isVisible = useVisibility();
+
+  if (context == null) {
+    throw new Error('useBackEvent must be used within a BackEventProvider');
+  }
+
+  const contextAddEventListener = context.addEventListener;
+  const contextRemoveEventListener = context.removeEventListener;
+
+  const addEventListener = useCallback(
+    (...handlers: Array<() => void>) => {
+      for (const handler of handlers) {
+        handlersRef.add(handler);
+        contextAddEventListener(handler);
+      }
+    },
+    [contextAddEventListener, handlersRef]
+  );
+
+  const removeEventListener = useCallback(
+    (...handlers: Array<() => void>) => {
+      for (const handler of handlers) {
+        handlersRef.delete(handler);
+        contextRemoveEventListener(handler);
+      }
+    },
+    [contextRemoveEventListener, handlersRef]
+  );
+
+  /**
+   * Events must be removed when navigating to another page.
+   * If events are not removed, interference will occur.
+   */
+  useEffect(() => {
+    if (!isVisible) {
+      return;
+    }
+
+    /** Re-register handlers stored locally. */
+    for (const handler of handlersRef) {
+      contextAddEventListener(handler);
+    }
+
+    return () => {
+      for (const handler of handlersRef) {
+        contextRemoveEventListener(handler);
+      }
+    };
+  }, [contextAddEventListener, contextRemoveEventListener, handlersRef, isVisible]);
+
+  const backEvent = useMemo((): BackEventControls => {
+    return {
+      addEventListener,
+      removeEventListener,
+    };
+  }, [addEventListener, removeEventListener]);
+
+  return backEvent;
+}
+
+export function useBackEventContext() {
+  const context = useContext(BackEventContext);
+  if (context == null) {
+    throw new Error('useBackEvent must be used within a BackEventProvider');
+  }
+
+  return {
+    onGoBack: context.onBack,
+    hasBackEvent: context.hasBackEvent,
+  };
+}

package/src/utils/noop.ts

@@ -0,0 +1 @@
+export const noop = () => {};

package/src/utils/usePreservedCallback.ts

@@ -0,0 +1,16 @@
+import { useCallback, useEffect, useRef } from 'react';
+
+export function usePreservedCallback<Callback extends (...args: any[]) => any>(callback: Callback) {
+  const callbackRef = useRef<Callback>(callback);
+
+  useEffect(() => {
+    callbackRef.current = callback;
+  }, [callback]);
+
+  return useCallback(
+    (...args: any[]) => {
+      return callbackRef.current(...args);
+    },
+    [callbackRef]
+  ) as Callback;
+}

package/src/visibility/VisibilityProvider.tsx

@@ -0,0 +1,36 @@
+import { ReactElement, ReactNode } from 'react';
+import { AppStateProvider } from './useIsAppForeground';
+import { VisibilityChangedProvider } from './useVisibilityChanged';
+
+interface Props {
+  isVisible: boolean;
+  children: ReactNode;
+}
+
+/**
+ * @name VisibilityProvider
+ * @description
+ * A Provider that manages whether a ReactNative view is currently in the foreground state.
+ * @param {boolean} isVisible - Whether the app is in the foreground state.
+ * @param {ReactNode | undefined} children - Child components that observe `AppState`.
+ * @returns {ReactElement} - A React Provider component wrapped with `VisibilityChangedProvider`.
+ * @example
+ * ```typescript
+ *
+ * function App() {
+ *  return (
+ *   <VisibilityProvider isVisible={true}>
+ *     <MyApp />
+ *   </VisibilityProvider>
+ *  );
+ * }
+ *
+ * ```
+ */
+export function VisibilityProvider({ isVisible, children }: Props): ReactElement {
+  return (
+    <VisibilityChangedProvider isVisible={isVisible}>
+      <AppStateProvider>{children}</AppStateProvider>
+    </VisibilityChangedProvider>
+  );
+}

package/src/visibility/index.ts

@@ -0,0 +1,6 @@
+export * from './react-navigation';
+export * from './useIsAppForeground';
+export * from './useVisibility';
+export * from './useVisibilityChanged';
+export * from './useVisibilityChange';
+export * from './VisibilityProvider';

package/src/visibility/react-navigation/index.ts

@@ -0,0 +1,2 @@
+export * from './useIsFocusedSafely';
+export * from './useNavigationSafely';

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

@@ -0,0 +1,58 @@
+import { useDebugValue, useEffect, useState } from 'react';
+import { useNavigationSafely } from './useNavigationSafely';
+
+/**
+ * @name useIsFocusedSafely
+ * @category Hooks
+ * @kind function
+ * @link https://github.com/react-navigation/react-navigation/blob/%40react-navigation/native%406.1.18/packages/core/src/useIsFocused.tsx
+ * @description
+ * Returns whether the current screen is in focus.
+ *
+ * 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.
+ *
+ * @returns {boolean} - Returns the focus state of the current screen.
+ * @example
+ * ```typescript
+ *  const isFocused = useIsFocusedSafely();
+ *  console.log(isFocused); // true or false
+ * ```
+ */
+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;
+}

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

@@ -0,0 +1,30 @@
+import {
+  NavigationContainerRefContext,
+  NavigationContext,
+  NavigationProp,
+} from '@granite-js/native/@react-navigation/native';
+import { useContext } from 'react';
+
+/**
+ * @name useNavigationSafely
+ * @category Hooks
+ * @kind function
+ * @link https://github.com/react-navigation/react-navigation/blob/d1cd940d9a3fb46bec0eb6bf4f8023789fc93b28/packages/core/src/useNavigation.tsx#L13
+ * @description
+ * A Hook that safely uses [`useNavigation`](https://reactnavigation.org/docs/use-navigation/) from `@react-navigation/native` for managing navigation between screens.
+ * This Hook is based on `useNavigation` provided by `@react-navigation/native`, but operates more safely by not throwing errors when `navigation` or `root` objects are `null` or `undefined`.
+ * It also ensures the code runs safely in environments where `@react-navigation/native` is not used, preventing users from experiencing errors.
+ *
+ * @returns {NavigationProp<ReactNavigation.RootParamList> | undefined} - The screen is in a visible state.
+ * @example
+ * ```typescript
+ *  const navigation = useNavigationSafely();
+ *  const isNavigationFocused = () => navigation?.isFocused() ?? true;
+ * ```
+ */
+export function useNavigationSafely(): NavigationProp<ReactNavigation.RootParamList> | undefined {
+  const root = useContext(NavigationContainerRefContext);
+  const navigation = useContext(NavigationContext);
+
+  return (navigation ?? root ?? undefined) as NavigationProp<ReactNavigation.RootParamList> | undefined;
+}