@granite-js/react-native 0.0.1

package/src/router/components/CanGoBackGuard.tsx

@@ -0,0 +1,31 @@
+import { ReactNode, useEffect } from 'react';
+import { BackHandler } from 'react-native';
+
+export function CanGoBackGuard({
+  children,
+  canGoBack,
+  onBack,
+}: {
+  canGoBack: boolean;
+  children: ReactNode;
+  onBack?: () => void;
+}) {
+  const shouldBlockGoingBack = !canGoBack;
+
+  useEffect(() => {
+    if (shouldBlockGoingBack) {
+      const subscription = BackHandler.addEventListener('hardwareBackPress', () => {
+        onBack?.();
+        return true;
+      });
+
+      return () => {
+        subscription.remove();
+      };
+    }
+
+    return;
+  }, [shouldBlockGoingBack, onBack]);
+
+  return <>{children}</>;
+}

package/src/router/components/RouterBackButton.tsx

@@ -0,0 +1,32 @@
+import { NavigationContainerRefWithCurrent } from '@granite-js/native/@react-navigation/native';
+import { BackButton } from './BackButton';
+import { closeView } from '../../native-modules';
+
+export type RouterBackButtonProps = {
+  onPress?: () => void;
+  tintColor?: string;
+  canGoBack?: boolean;
+  onBack?: () => void;
+  navigationContainerRef: NavigationContainerRefWithCurrent<any>;
+};
+
+export function RouterBackButton({ tintColor, canGoBack, onBack, navigationContainerRef }: RouterBackButtonProps) {
+  return (
+    <BackButton
+      tintColor={tintColor}
+      onPress={() => {
+        onBack?.();
+
+        if (!canGoBack) {
+          return;
+        }
+
+        if (navigationContainerRef.canGoBack()) {
+          navigationContainerRef.goBack();
+        } else {
+          closeView();
+        }
+      }}
+    />
+  );
+}

package/src/router/components/StackNavigator.tsx

@@ -0,0 +1,12 @@
+import { createNativeStackNavigator } from '@granite-js/native/@react-navigation/native-stack';
+
+function createStackNavigator() {
+  const Stack = createNativeStackNavigator();
+
+  return {
+    Navigator: Stack.Navigator,
+    Screen: Stack.Screen,
+  };
+}
+
+export const StackNavigator = createStackNavigator();

package/src/router/constants.ts

@@ -0,0 +1,3 @@
+export const RESERVED_KEYWORDS = ['_layout'];
+
+export const RESERVED_PATHS = ['/_404'];

package/src/router/createRoute.test-d.ts

@@ -0,0 +1,52 @@
+import { assertType, describe, it } from 'vitest';
+import { createRoute, useParams } from './createRoute';
+
+declare module './createRoute' {
+  interface RegisterScreen {
+    '/test': {
+      id: string;
+      name: string;
+    };
+  }
+}
+
+describe('createRoute', () => {
+  const Route = createRoute('/test', {
+    component: () => null,
+    validateParams: (params) => params as { id: string; name: string },
+  });
+
+  it('useParams', () => {
+    assertType<{
+      id: string;
+      name: string;
+    }>(Route.useParams());
+
+    assertType<Readonly<object | undefined>>(useParams({ strict: false }));
+
+    // @ts-expect-error - Type error should occur when strict is false
+    assertType<{ id: string; name: string }>(useParams({ strict: false }));
+
+    assertType<{
+      id: string;
+      name: string;
+    }>(useParams({ from: '/test', strict: true }));
+
+    assertType<{
+      id: string;
+      name: string;
+    }>(useParams({ from: '/test' }));
+
+    // @ts-expect-error Type error should occur when no options
+    assertType(useParams());
+
+    // @ts-expect-error Type error should occur when empty object
+    assertType(useParams({}));
+
+    // @ts-expect-error Type error should occur when path is not registered
+    assertType(useParams({ from: '/abcdefg' }));
+
+    // @ts-expect-error Type error should occur since 'from' and 'strict: false' are conflicting options
+    assertType(useParams({ from: '/test', strict: false }));
+  });
+});

package/src/router/createRoute.ts

@@ -0,0 +1,161 @@
+import {
+  type ParamListBase,
+  useNavigation as useNavigationNative,
+  useRoute,
+} from '@granite-js/native/@react-navigation/native';
+import { NativeStackNavigationProp } from '@granite-js/native/@react-navigation/native-stack';
+import { useMemo } from 'react';
+import { RESERVED_PATHS } from './constants';
+import { defaultParserParams } from './utils/defaultParserParams';
+
+export interface RouteOptions<T extends Readonly<object | undefined>> {
+  parserParams?: (params: Record<string, unknown>) => Record<string, unknown>;
+  validateParams?: (params: Readonly<object | undefined>) => T;
+  component: React.FC<any>;
+}
+
+export type NavigationProps = NativeStackNavigationProp<
+  // @ts-expect-error - override type
+  keyof RegisterScreen extends never ? ParamListBase : RegisterScreen
+>;
+
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface RegisterScreen {}
+
+export function useNavigation() {
+  return useNavigationNative<NavigationProps>();
+}
+
+export type RouteHooksOptions<TScreen extends keyof RegisterScreen> =
+  | {
+      from: TScreen;
+      strict?: true;
+    }
+  | {
+      strict: false;
+      from?: never;
+    };
+
+export const routeMap = new Map<
+  keyof RegisterScreen,
+  { options: Omit<RouteOptions<any>, 'component'>; component: React.FC<any> }
+>();
+
+export function useMatchOptions<TScreen extends keyof RegisterScreen>(options: RouteHooksOptions<TScreen>) {
+  const route = useRoute();
+  const from = 'from' in options ? options.from : (route.name as TScreen);
+  const strict = 'from' in options ? true : options.strict;
+
+  if (strict && from !== route.name) {
+    throw new Error(`Cannot access parameters from route '${from}' in current route '${route.name}'`);
+  }
+
+  return useMemo(() => {
+    if (!from) {
+      return null;
+    }
+
+    if (!(routeMap.has(from) || RESERVED_PATHS.includes(from))) {
+      throw new Error(`Route '${from}' is not registered`);
+    }
+
+    const routeOptions = routeMap.get(from);
+    return {
+      ...routeOptions?.options,
+      parserParams: routeOptions?.options.parserParams ?? defaultParserParams,
+    };
+  }, [from]);
+}
+
+export function useParams<TScreen extends keyof RegisterScreen>(options: {
+  from: TScreen;
+  strict?: true;
+}): RegisterScreen[TScreen];
+export function useParams(options: { strict: false }): Readonly<object | undefined>;
+
+/**
+ * @public
+ * @category Screen Control
+ * @name useParams
+ * @description
+ *
+ * `useParams` is a hook that retrieves parameters from a specified route.
+ * Using this hook, you can easily access parameters of the current route.
+ * With the `validateParams` option, you can validate parameter structure and transform types,
+ * reducing runtime errors and writing safer code.
+ *
+ * @param {RouteHooksOptions<TScreen>} options Object containing information about the route to retrieve.
+ * @param {string} [options.from] Route path to retrieve parameters from. If not specified, retrieves parameters from the current route. Must be specified when strict mode is true.
+ * @param {boolean} [options.strict] Strict mode setting. When set to true, throws an error if the specified route doesn't match the current route. When set to false, skips validateParams validation and returns parameters of the current screen as is.
+ *
+ * @example
+ * ### Retrieving Route Parameters
+ *
+ *
+ * ::: code-group
+ *
+ * ```tsx [pages/examples/use-params.tsx]
+ * import React from 'react';
+ * import { Text } from 'react-native';
+ * import { createRoute, useParams } from '@granite-js/react-native';
+ *
+ * export const Route = createRoute('/examples/use-params', {
+ *   validateParams: (params) => params as { id: string },
+ *   component: UseParamsExample,
+ * });
+ *
+ * function UseParamsExample() {
+ *   // First method: Using the useParams method of the route object
+ *   const params = Route.useParams();
+ *
+ *   // Second method: Using the useParams hook directly
+ *   const params2 = useParams({ from: '/examples/use-params' });
+ *
+ *   // Third method: Using with strict mode set to false
+ *   // When strict is false, retrieves parameters from the current route
+ *   // and skips validation even if validateParams is defined
+ *   const params3 = useParams({ strict: false }) as { id: string };
+ *
+ *   return (
+ *     <>
+ *       <Text>{params.id}</Text>
+ *       <Text>{params2.id}</Text>
+ *       <Text>{params3.id}</Text>
+ *     </>
+ *   );
+ * }
+ * ```
+ * :::
+ */
+export function useParams<TScreen extends keyof RegisterScreen>(
+  options: RouteHooksOptions<TScreen>
+): TScreen extends keyof RegisterScreen ? RegisterScreen[TScreen] : Readonly<object | undefined> {
+  const routeOptions = useMatchOptions(options);
+  const route = useRoute();
+
+  const params = useMemo(() => {
+    if (!routeOptions) {
+      return (route.params ?? {}) as Readonly<object | undefined>;
+    }
+
+    const parsedParams = routeOptions.parserParams(route.params as Record<string, string>);
+    return options.strict && routeOptions.validateParams ? routeOptions.validateParams(parsedParams) : parsedParams;
+  }, [routeOptions, route.params, options.strict]);
+
+  return params;
+}
+
+export const createRoute = <T extends Readonly<object | undefined>>(
+  path: keyof RegisterScreen,
+  options: RouteOptions<T>
+) => {
+  const { component, ...restOptions } = options;
+  routeMap.set(path, { options: restOptions, component });
+
+  const _path = path as keyof RegisterScreen;
+  return {
+    _path,
+    useNavigation,
+    useParams: () => useParams({ from: _path, strict: true }) as T,
+  };
+};

package/src/router/hooks/useInitialRouteName.tsx

@@ -0,0 +1,22 @@
+import { Platform } from 'react-native';
+import { getSchemeUri } from '../../native-modules';
+
+export function useInitialRouteName(prefix: string) {
+  const initialScheme = getInitialScheme();
+  const pathname = initialScheme?.slice(prefix.length).split('?')[0];
+  const shouldUseIndex = initialScheme == null || pathname?.length === 0;
+
+  return shouldUseIndex ? '/' : pathname;
+}
+function getInitialScheme() {
+  const scheme = getSchemeUri();
+
+  /**
+   * Removes trailing '/' on Android.
+   */
+  if (Platform.OS === 'android') {
+    return scheme?.replaceAll(/\/+$/g, '');
+  }
+
+  return scheme;
+}

package/src/router/hooks/useIsInitialScreen.ts

@@ -0,0 +1,7 @@
+import { useNavigationState } from '@granite-js/native/@react-navigation/native';
+
+export function useIsInitialScreen() {
+  const index = useNavigationState((state) => state?.index ?? 0);
+
+  return index === 0;
+}

package/src/router/hooks/useRouterControls.tsx

@@ -0,0 +1,72 @@
+import { NavigationContainer } from '@granite-js/native/@react-navigation/native';
+import { useMemo, type ComponentProps, type ComponentType, type PropsWithChildren } from 'react';
+import { getSchemeUri } from '../../native-modules';
+import { StackNavigator } from '../components/StackNavigator';
+import { RESERVED_KEYWORDS } from '../constants';
+import { RequireContext } from '../types/RequireContext';
+import { getRouteScreens, getScreenPathMapConfig } from '../utils';
+import { createParentRouteScreenMap } from '../utils/createParentRouteScreenMap';
+import { mergeParentLayoutScreen } from '../utils/mergeParentLayoutScreen';
+import { getFileNameFromPath } from '../utils/path';
+
+type NavigationContainerProps = ComponentProps<typeof NavigationContainer>;
+
+export interface RouterControlsConfig {
+  prefix: string;
+  context: RequireContext;
+  screenContainer?: ComponentType<PropsWithChildren<any>>;
+}
+
+export function useRouterControls({ prefix, context, screenContainer: ScreenContainer }: RouterControlsConfig) {
+  const routeScreens = useMemo(() => getRouteScreens(context), [context]);
+
+  const registerScreens = useMemo(() => {
+    return routeScreens.filter(
+      (screen) => !RESERVED_KEYWORDS.includes(getFileNameFromPath(screen.path, { withExtension: false }))
+    );
+  }, [routeScreens]);
+
+  const layoutScreenMap = useMemo(() => createParentRouteScreenMap(routeScreens, '_layout'), [routeScreens]);
+
+  const Screens = useMemo(() => {
+    return registerScreens.map((routeScreen) => {
+      const Layout = mergeParentLayoutScreen(layoutScreenMap, routeScreen.path);
+
+      const Component = function Component() {
+        const element = (
+          <Layout>
+            <routeScreen.component />
+          </Layout>
+        );
+
+        return ScreenContainer == null ? element : <ScreenContainer>{element}</ScreenContainer>;
+      };
+
+      const routePath = routeScreen.path;
+      const screenOptions = routeScreen.component?.screenOptions ?? {};
+
+      return <StackNavigator.Screen key={routePath} name={routePath} component={Component} options={screenOptions} />;
+    });
+  }, [registerScreens, layoutScreenMap, ScreenContainer]);
+
+  const linkingOptions: NavigationContainerProps['linking'] = useMemo(() => {
+    return {
+      prefixes: [prefix],
+      config: {
+        screens: getScreenPathMapConfig(registerScreens),
+      },
+      async getInitialURL() {
+        const initialURL = getSchemeUri();
+
+        if (initialURL == null) {
+          return;
+        }
+
+        /** @NOTE Korean paths need to be decoded. */
+        return decodeURI(initialURL);
+      },
+    };
+  }, [prefix, registerScreens]);
+
+  return { Screens, linkingOptions };
+}

package/src/router/index.ts

@@ -0,0 +1,3 @@
+export * from './Router';
+export { getRouteScreens, getScreenPathMapConfig, defaultParserParams } from './utils';
+export * from './types';

package/src/router/types/RequireContext.ts

@@ -0,0 +1,7 @@
+export interface RequireContext {
+  keys(): string[];
+  (id: string): any;
+  <T>(id: string): T;
+  resolve(id: string): string;
+  id: string;
+}

package/src/router/types/RouteScreen.ts

@@ -0,0 +1,17 @@
+import { Screen } from './Screen';
+
+/**
+ * @name RouteScreen
+ */
+export interface RouteScreen {
+  /**
+   * @name path
+   * @description Path information (e.g. "/", "/list", "/list/:id", etc.)
+   */
+  path: string;
+  /**
+   * @name component
+   * @description Screen component
+   */
+  component: Screen;
+}

package/src/router/types/Screen.tsx

@@ -0,0 +1,24 @@
+import type { NativeStackNavigationOptions } from '@granite-js/native/@react-navigation/native-stack';
+import type { ComponentType } from 'react';
+
+/**
+ * @name Screen
+ * @description A Screen that serves as a unit of navigation
+ * @example
+ *
+ * ```ts
+ * function Page() {
+ *  // ...
+ * }
+ *
+ * Page.screenOptions = {
+ *   // ...
+ * }
+ * ```
+ */
+export type Screen = ComponentType & GraniteScreenOptions;
+
+interface GraniteScreenOptions {
+  /** @description Add this when customization is needed for NativeStack Screen's screenOptions */
+  screenOptions?: NativeStackNavigationOptions;
+}

package/src/router/types/index.ts

@@ -0,0 +1,3 @@
+export * from './RequireContext';
+export * from './RouteScreen';
+export * from './Screen';

package/src/router/types/screen-option.ts

@@ -0,0 +1,23 @@
+import { NativeStackNavigationOptions } from '@granite-js/native/@react-navigation/native-stack';
+import { Platform } from 'react-native';
+
+export const DEFAULT_BACKGROUND_COLOR = '#ffffff';
+export const DEFAULT_HEADER_TINT_COLOR = '#333d4b';
+export const BASE_STACK_NAVIGATOR_STYLE: NativeStackNavigationOptions = {
+  contentStyle: {
+    backgroundColor: DEFAULT_BACKGROUND_COLOR,
+  },
+  headerTintColor: DEFAULT_HEADER_TINT_COLOR,
+  headerTitleStyle: {
+    color: 'transparent',
+  },
+  headerStyle: {
+    backgroundColor: DEFAULT_BACKGROUND_COLOR,
+  },
+  headerShadowVisible: false,
+
+  // FIX
+  // According to the docs, react-navigation's Android transition behavior should follow the OS default, but in reality, it doesn't.
+  // We've decided to solve this issue by unifying the animation to slide up from bottom.
+  animation: Platform.OS === 'android' ? 'fade_from_bottom' : 'default',
+};

package/src/router/utils/createParentRouteScreenMap.spec.ts

@@ -0,0 +1,166 @@
+import { describe, it, expect } from 'vitest';
+import { createParentRouteScreenMap } from './createParentRouteScreenMap';
+import type { RouteScreen } from '../types/RouteScreen';
+
+describe('createParentRouteScreenMap', () => {
+  describe('When there are nested layouts', () => {
+    it('Each page is mapped to its nearest parent layout', () => {
+      const paths: RouteScreen[] = [
+        { path: './granite-module/_layout', component: () => null },
+        { path: './granite-module/test', component: () => null },
+        { path: './about/_layout', component: () => null },
+        { path: './about/test', component: () => null },
+        { path: './about', component: () => null },
+        { path: './image', component: () => null },
+      ];
+
+      const layoutMap = createParentRouteScreenMap(paths, '_layout');
+
+      // Pages in granite-module directory are mapped to their layout
+      expect(layoutMap.get('./granite-module/test')?.path).toBe('./granite-module/_layout');
+
+      // Pages in about directory are mapped to their layout
+      expect(layoutMap.get('./about')?.path).toBe('./about/_layout');
+      expect(layoutMap.get('./about/test')?.path).toBe('./about/_layout');
+
+      // Pages without layout are undefined
+      expect(layoutMap.get('./image')).toBeUndefined();
+
+      // Layout files are not mapped because there's no layout at the root
+      expect(layoutMap.get('./granite-module/_layout')).toBeUndefined();
+      expect(layoutMap.get('./about/_layout')).toBeUndefined();
+    });
+
+    it('If there is a root layout, pages without layout are mapped to the root layout', () => {
+      const paths: RouteScreen[] = [
+        { path: './_layout', component: () => null },
+        { path: './image', component: () => null },
+        { path: './granite-module/_layout', component: () => null },
+        { path: './granite-module/test', component: () => null },
+        { path: './about/_layout', component: () => null },
+        { path: './about', component: () => null },
+        { path: './about/test', component: () => null },
+      ];
+
+      const layoutMap = createParentRouteScreenMap(paths, '_layout');
+
+      // Pages in each directory are mapped to their layout
+      expect(layoutMap.get('./granite-module/test')?.path).toBe('./granite-module/_layout');
+      expect(layoutMap.get('./about')?.path).toBe('./about/_layout');
+      expect(layoutMap.get('./about/test')?.path).toBe('./about/_layout');
+
+      // Pages without layout are mapped to root layout
+      expect(layoutMap.get('./image')?.path).toBe('./_layout');
+      expect(layoutMap.get('./_layout')).toBeUndefined();
+      expect(layoutMap.get('./granite-module/_layout')?.path).toBe('./_layout');
+      expect(layoutMap.get('./about/_layout')?.path).toBe('./_layout');
+    });
+
+    it('Layout mapping works correctly in nested directory structure', () => {
+      const paths: RouteScreen[] = [
+        { path: './nested', component: () => null },
+        { path: './nested/_layout', component: () => null },
+        { path: './nested/test', component: () => null },
+      ];
+
+      const layoutMap = createParentRouteScreenMap(paths, '_layout');
+
+      // nested is mapped to nested/_layout
+      expect(layoutMap.get('./nested')?.path).toBe('./nested/_layout');
+
+      // nested/test is mapped to nested/_layout
+      expect(layoutMap.get('./nested/test')?.path).toBe('./nested/_layout');
+
+      expect(layoutMap.get('./nested/_layout')?.path).toBeUndefined();
+    });
+
+    it('Layout mapping works correctly in double nested directory structure', () => {
+      const paths: RouteScreen[] = [
+        { path: './nested/_layout', component: () => null },
+        { path: './nested/test', component: () => null },
+        { path: './nested/deep/_layout', component: () => null },
+        { path: './nested/deep/test', component: () => null },
+      ];
+
+      const layoutMap = createParentRouteScreenMap(paths, '_layout');
+
+      // nested/test is mapped to nested/_layout
+      expect(layoutMap.get('./nested/test')?.path).toBe('./nested/_layout');
+
+      // nested/deep/test is mapped to nested/deep/_layout
+      expect(layoutMap.get('./nested/deep/test')?.path).toBe('./nested/deep/_layout');
+
+      // nested/deep/_layout is mapped to nested/_layout
+      expect(layoutMap.get('./nested/deep/_layout')?.path).toBe('./nested/_layout');
+
+      // nested/_layout is not mapped
+      expect(layoutMap.get('./nested/_layout')?.path).toBeUndefined();
+    });
+
+    it('Layout mapping works correctly in triple nested directory structure', () => {
+      const paths: RouteScreen[] = [
+        { path: './nested/_layout', component: () => null },
+        { path: './nested/test', component: () => null },
+        { path: './nested/deep/_layout', component: () => null },
+        { path: './nested/deep/test', component: () => null },
+        { path: './nested/deep/deeper/_layout', component: () => null },
+        { path: './nested/deep/deeper/test', component: () => null },
+      ];
+
+      const layoutMap = createParentRouteScreenMap(paths, '_layout');
+
+      // nested/test is mapped to nested/_layout
+      expect(layoutMap.get('./nested/test')?.path).toBe('./nested/_layout');
+
+      // nested/deep/test is mapped to nested/deep/_layout
+      expect(layoutMap.get('./nested/deep/test')?.path).toBe('./nested/deep/_layout');
+
+      // nested/deep/deeper/test is mapped to nested/deep/deeper/_layout
+      expect(layoutMap.get('./nested/deep/deeper/test')?.path).toBe('./nested/deep/deeper/_layout');
+
+      // nested/deep/deeper/_layout is mapped to nested/deep/_layout
+      expect(layoutMap.get('./nested/deep/deeper/_layout')?.path).toBe('./nested/deep/_layout');
+
+      // nested/deep/_layout is mapped to nested/_layout
+      expect(layoutMap.get('./nested/deep/_layout')?.path).toBe('./nested/_layout');
+
+      // nested/_layout is not mapped
+      expect(layoutMap.get('./nested/_layout')?.path).toBeUndefined();
+    });
+  });
+
+  describe('When there are no layouts', () => {
+    it('All pages are mapped to undefined', () => {
+      const paths: RouteScreen[] = [
+        { path: './page1', component: () => null },
+        { path: './page2', component: () => null },
+        { path: './nested/page3', component: () => null },
+        { path: './nested/deep/page4', component: () => null },
+      ];
+
+      const layoutMap = createParentRouteScreenMap(paths, '_layout');
+
+      // All pages are undefined
+      expect(layoutMap.get('./page1')).toBeUndefined();
+      expect(layoutMap.get('./page2')).toBeUndefined();
+      expect(layoutMap.get('./nested/page3')).toBeUndefined();
+      expect(layoutMap.get('./nested/deep/page4')).toBeUndefined();
+    });
+  });
+
+  it('Nested _layout is mapped to parent _layout', () => {
+    const paths: RouteScreen[] = [
+      { path: './_layout', component: () => null },
+      { path: './nested/_layout', component: () => null },
+      { path: './nested/test', component: () => null },
+      { path: './nested/deep/_layout', component: () => null },
+      { path: './nested/deep/test', component: () => null },
+    ];
+
+    const layoutMap = createParentRouteScreenMap(paths, '_layout');
+    expect(layoutMap.get('./nested/deep/test')?.path).toBe('./nested/deep/_layout');
+    expect(layoutMap.get('./nested/deep/_layout')?.path).toBe('./nested/_layout');
+    expect(layoutMap.get('./nested/_layout')?.path).toBe('./_layout');
+    expect(layoutMap.get('./_layout')?.path).toBeUndefined();
+  });
+});