@rn-tools/navigation 2.1.0 → 2.2.1

package/README.md

@@ -18,6 +18,8 @@ A set of useful navigation components for React Native. Built with `react-native
   - [Tabs](#tabs)
 - [Guides](#guides)
   - [Authentication](#authentication)
+  - [Deep Links](#deep-links)
+  - [Preventing going back](#preventing-going-back)
 
 ## Installation
 
@@ -301,6 +303,8 @@ Use the `Stack.Header` component to render a native header in a screen.
 
 Under the hood this is using `react-native-screens` header - [here is a reference for the available props](https://github.com/software-mansion/react-native-screens/blob/main/guides/GUIDE_FOR_LIBRARY_AUTHORS.md#screenstackheaderconfig)
 
+You can provide custom left, center, and right views in the header by using the `Stack.HeaderLeft`, `Stack.HeaderCenter`, and `Stack.HeaderRight` view container components as children of `Stack.Header`.
+
 **Note:** Wrap your App in a `SafeAreaProvider` to ensure your screen components are rendered correctly with the header
 
 **Note:**: The header component **has to be the first child** of a `Stack.Screen` component.
@@ -308,7 +312,7 @@ Under the hood this is using `react-native-screens` header - [here is a referenc
 ```tsx
 import { navigation, Stack } from "@rn-tools/navigation";
 import * as React from "react";
-import { Button, View, TextInput } from "react-native";
+import { Button, View, TextInput, Text } from "react-native";
 
 export function HeaderExample() {
   return (
@@ -333,7 +337,11 @@ function MyScreenWithHeader() {
         backTitle="Custom back title"
         backTitleFontSize={16}
         hideBackButton={false}
-      />
+      >
+        <Stack.HeaderRight>
+          <Text>Custom right text!</Text>
+        </Stack.HeaderRight>
+      </Stack.Header>
 
       <View
         style={{
@@ -356,7 +364,7 @@ function MyScreenWithHeader() {
 
 ## Components
 
-The `Navigator` components in the previous examples are fairly straightforward wrappers around other lower level `Stack` and `Tabs` components. 
+The `Navigator` components in the previous examples are fairly straightforward wrappers around other lower level `Stack` and `Tabs` components.
 
 If you need to customize behaviour, design a component API you prefer to use, or just enjoy writing your own components, you can use these implementations as a reference to build your own.
 
@@ -462,7 +470,6 @@ let TabNavigator = React.memo(function TabNavigator({
     </Tabs.Root>
   );
 });
-
 ```
 
 - `Tabs.Root` - The root component for a tabs navigator.
@@ -475,8 +482,6 @@ let TabNavigator = React.memo(function TabNavigator({
 - `Tabs.Tab` - A tab in a tabs navigator
   - This is a Pressable component that switches the active screen
 
-
-
 ## Guides
 
 ### Authentication
@@ -522,3 +527,220 @@ let useUser = () => {
   return user;
 };
 ```
+
+### Deep Links
+
+This section will cover how to respond to deep links in your app. Deep links usually have some extra setup required - use Expo's [Deep Linking Guide](https://docs.expo.dev/guides/deep-linking/) to get started.
+
+Once you are able to receive deep links, use the `DeepLinks` component exported from this library to handle them. In this example we will have a basic 3 tab view. We want to response to the link `home/items/:id` by navigating to the home tab and then pushing a detail screen with the corresponding id.
+
+The deep link component takes an array of handlers which are functions that will be invoked when their `path` matches the deep link that was opened. 
+  - Only the first matching handler will be invoked. 
+  - The handler function will receive the params from the deep link - these use the same token syntax as libraries like `react-router` and `express` for path params.
+
+```tsx
+import { DeepLinks, navigation, Stack, Tabs } from "@rn-tools/navigation";
+import * as React from "react";
+import { View, Text, TouchableOpacity } from "react-native";
+import * as Linking from "expo-linking";
+
+export function DeepLinksExample() {
+  // You'll likely want to use Expo's Linking API to get the current URL and path
+  // let url = Linking.useURL()
+  // let { path } = Linking.parse(url)
+
+  // But it's easier to test hardcoded strings for the sake of this example
+  let path = "/testing/home/item/4";
+
+  return (
+    <DeepLinks
+      path={path}
+      handlers={[
+        {
+          path: "/testing/home/item/:itemId",
+          handler: (params: { itemId: string }) => {
+            let itemId = params.itemId;
+
+            // Go to home tab
+            navigation.setTabIndex(0);
+
+            // Push the screen we want
+            navigation.pushScreen(
+              <Stack.Screen>
+                <MyScreen title={`Item: ${itemId}`} />
+              </Stack.Screen>
+            );
+          },
+        },
+      ]}
+    >
+      <MyTabs />
+    </DeepLinks>
+  );
+}
+
+function MyTabs() {
+  return (
+    <Tabs.Navigator
+      tabbarPosition="bottom"
+      screens={[
+        {
+          key: "1",
+          screen: (
+            <Stack.Navigator
+              rootScreen={<MyScreen bg="red" title="Home screen" isRoot />}
+            />
+          ),
+          tab: ({ isActive }) => <MyTab text="Home" isActive={isActive} />,
+        },
+        {
+          key: "2",
+          screen: (
+            <Stack.Navigator
+              rootScreen={<MyScreen bg="blue" title="Search screen" isRoot />}
+            />
+          ),
+          tab: ({ isActive }) => <MyTab text="Search" isActive={isActive} />,
+        },
+        {
+          key: "3",
+          screen: (
+            <Stack.Navigator
+              rootScreen={
+                <MyScreen bg="purple" title="Settings screen" isRoot />
+              }
+            />
+          ),
+          tab: ({ isActive }) => <MyTab text="Settings" isActive={isActive} />,
+        },
+      ]}
+    />
+  );
+}
+
+function MyTab({ isActive, text }: { isActive?: boolean; text: string }) {
+  return (
+    <View
+      style={{
+        padding: 16,
+        justifyContent: "center",
+        alignItems: "center",
+      }}
+    >
+      <Text style={{ fontSize: 12, fontWeight: isActive ? "bold" : "normal" }}>
+        {text}
+      </Text>
+    </View>
+  );
+}
+
+function MyScreen({
+  bg = "white",
+  title = "",
+  isRoot = false,
+}: {
+  title?: string;
+  bg?: string;
+  isRoot?: boolean;
+}) {
+  return (
+    <View style={{ flex: 1, backgroundColor: bg }}>
+      <View className="flex-1 items-center justify-center gap-4">
+        <Text style={{ fontSize: 26, fontWeight: "semibold" }}>{title}</Text>
+
+        {!isRoot && (
+          <TouchableOpacity
+            onPress={() => {
+              navigation.popScreen();
+            }}
+          >
+            <Text>Pop</Text>
+          </TouchableOpacity>
+        )}
+      </View>
+    </View>
+  );
+}
+```
+
+### Preventing going back
+
+If you want to prevent users from popping a screen and potentially losing unsaved data, you can stop the screen from being dismissed by a gesture or pressing the back button.
+
+**Note:**: The native header component does not provide a reliable way to prevent going back on iOS, so you'll have to provide your own custom back button by using the `Stack.HeaderLeft` component
+
+```tsx
+import { navigation, Stack } from "@rn-tools/navigation";
+import * as React from "react";
+import {
+  Text,
+  TextInput,
+  TouchableOpacity,
+  Button,
+  View,
+  Alert,
+} from "react-native";
+
+export function PreventGoingBack() {
+  return (
+    <Button
+      title="Push screen"
+      onPress={() => navigation.pushScreen(<MyScreen />)}
+    />
+  );
+}
+
+function MyScreen() {
+  let [input, setInput] = React.useState("");
+
+  let canGoBack = input.length === 0;
+
+  let onPressBackButton = React.useCallback(() => {
+    if (canGoBack) {
+      navigation.popScreen();
+    } else {
+      Alert.alert("Are you sure you want to go back?", "", [
+        {
+          text: "Cancel",
+          style: "cancel",
+        },
+        {
+          text: "Yes",
+          onPress: () => navigation.popScreen(),
+        },
+      ]);
+    }
+  }, [canGoBack]);
+
+  return (
+    <Stack.Screen
+      preventNativeDismiss={!canGoBack}
+      nativeBackButtonDismissalEnabled={!canGoBack}
+      gestureEnabled={canGoBack}
+    >
+      <Stack.Header title="Prevent going back">
+        <Stack.HeaderLeft>
+          <TouchableOpacity
+            onPress={onPressBackButton}
+            style={{ opacity: canGoBack ? 1 : 0.4 }}
+          >
+            <Text>Back</Text>
+          </TouchableOpacity>
+        </Stack.HeaderLeft>
+      </Stack.Header>
+      <View style={{ paddingVertical: 48, paddingHorizontal: 16, gap: 16 }}>
+        <Text style={{ fontSize: 22, fontWeight: "medium" }}>
+          Enter some text and try to go back
+        </Text>
+        <TextInput
+          value={input}
+          onChangeText={setInput}
+          placeholder="Enter some text"
+          onSubmitEditing={() => setInput("")}
+        />
+        <Button title="Submit" onPress={() => setInput("")} />
+      </View>
+    </Stack.Screen>
+  );
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rn-tools/navigation",
-  "version": "2.1.0",
+  "version": "2.2.1",
   "main": "./src/index.ts",
   "license": "MIT",
   "files": [
@@ -34,6 +34,7 @@
     "react-native-screens": "*"
   },
   "dependencies": {
+    "path-to-regexp": "^6.2.2",
     "zustand": "^4.5.2"
   },
   "jest": {

package/src/deep-links.tsx

@@ -0,0 +1,41 @@
+import { match } from "path-to-regexp";
+import * as React from "react";
+
+export type DeepLinkHandler<T> = {
+  path: string;
+  handler: (params: T) => void;
+};
+
+function buildMatchers<T>(handlers: DeepLinkHandler<T>[]) {
+  return handlers.map(({ path, handler }) => {
+    let fn = match(path, { decode: decodeURIComponent });
+    return { fn, handler };
+  });
+}
+
+type DeepLinksProps<T> = {
+  path: string;
+  handlers: DeepLinkHandler<T>[];
+  children: React.ReactNode;
+};
+
+export function DeepLinks<T>({ path, handlers, children }: DeepLinksProps<T>) {
+  let matchers = React.useRef(buildMatchers(handlers));
+
+  React.useLayoutEffect(() => {
+    matchers.current = buildMatchers(handlers);
+  }, [handlers]);
+
+  React.useEffect(() => {
+    for (let matcher of matchers.current) {
+      let { fn, handler } = matcher;
+      let match = fn(path);
+      if (match) {
+        setImmediate(() => handler(match.params as T));
+        break;
+      }
+    }
+  }, [path]);
+
+  return <>{children}</>;
+}

package/src/index.ts

@@ -1,3 +1,4 @@
 export * from "./navigation";
 export * from "./stack";
-export * from "./tabs";
+export * from "./tabs";
+export * from './deep-links'

package/src/navigation-reducer.ts

@@ -103,6 +103,12 @@ type SetTabIndexAction = {
   tabId: string;
 };
 
+type PopActiveTabAction = {
+  type: "POP_ACTIVE_TAB";
+  tabId: string;
+  index: number;
+};
+
 type RegisterTabAction = {
   type: "REGISTER_TAB";
   depth: number;
@@ -126,7 +132,8 @@ type TabActions =
   | SetTabIndexAction
   | RegisterTabAction
   | UnregisterTabAction
-  | TabBackAction;
+  | TabBackAction
+  | PopActiveTabAction;
 
 type SetDebugModeAction = {
   type: "SET_DEBUG_MODE";
@@ -375,28 +382,35 @@ export function reducer(
         }
       );
 
-      if (tab.activeIndex === index) {
-        let tabKey = serializeTabIndexKey(tabId, index);
-        let stackIds = renderCharts.stacksByTabIndex[tabKey];
+      return nextState;
+    }
+
+    case "POP_ACTIVE_TAB": {
+      let { tabId, index } = action;
+      let { renderCharts } = context;
+
+      let tabKey = serializeTabIndexKey(tabId, index);
+      let stackIds = renderCharts.stacksByTabIndex[tabKey];
 
-        if (stackIds?.length > 0) {
-          stackIds.forEach((stackId) => {
-            let stack = nextState.stacks.lookup[stackId];
-            let screenIdsToRemove = stack.screens;
+      let nextState: NavigationState = Object.assign({}, state);
 
-            let nextScreensLookup = Object.assign({}, nextState.screens.lookup);
+      if (stackIds?.length > 0) {
+        stackIds.forEach((stackId) => {
+          let stack = nextState.stacks.lookup[stackId];
+          let screenIdsToRemove = stack.screens;
 
-            screenIdsToRemove.forEach((id) => {
-              delete nextScreensLookup[id];
-            });
+          let nextScreensLookup = Object.assign({}, nextState.screens.lookup);
 
-            nextState.stacks.lookup[stackId].screens = [];
-            nextState.screens.ids = nextState.screens.ids.filter(
-              (id) => !screenIdsToRemove.includes(id)
-            );
-            nextState.screens.lookup = nextScreensLookup;
+          screenIdsToRemove.forEach((id) => {
+            delete nextScreensLookup[id];
           });
-        }
+
+          nextState.stacks.lookup[stackId].screens = [];
+          nextState.screens.ids = nextState.screens.ids.filter(
+            (id) => !screenIdsToRemove.includes(id)
+          );
+          nextState.screens.lookup = nextScreensLookup;
+        });
       }
 
       return nextState;
@@ -442,7 +456,7 @@ export function reducer(
       let { tabId } = action;
       let nextState: NavigationState = Object.assign({}, state);
 
-      let tab  = nextState.tabs.lookup[tabId];
+      let tab = nextState.tabs.lookup[tabId];
 
       let lastActiveIndex = tab.history[tab.history.length - 1];
 

package/src/navigation.tsx

@@ -12,9 +12,9 @@ import type { PushScreenOptions } from "./types";
 
 /**
  * Ideas:
- *  - pull in safe area provider and use as default props to tabs
  *  - lifecycles / screen tracking
- *  - testing - internal and jest plugin
+ *  - testing guide
+ *  - routing example -> fragments to ids
  */
 
 export function createNavigation() {

package/src/stack.tsx

@@ -6,7 +6,9 @@ import {
   StyleSheet,
   useWindowDimensions,
   View,
+  type ImageProps,
   type LayoutRectangle,
+  type ViewProps,
   type ViewStyle,
 } from "react-native";
 import {
@@ -14,7 +16,11 @@ import {
   Screen as RNScreen,
   ScreenProps as RNScreenProps,
   ScreenStackHeaderConfig as RNScreenStackHeaderConfig,
+  ScreenStackHeaderLeftView as RNScreenStackHeaderLeftView,
+  ScreenStackHeaderRightView as RNScreenStackHeaderRightView,
+  ScreenStackHeaderCenterView as RNScreenStackHeaderCenterView,
   ScreenStackHeaderConfigProps as RNScreenStackHeaderConfigProps,
+  ScreenStackHeaderBackButtonImage as RNScreenStackHeaderBackButtonImage,
 } from "react-native-screens";
 import ScreenStackNativeComponent from "react-native-screens/src/fabric/ScreenStackNativeComponent";
 
@@ -249,6 +255,30 @@ let StackScreenHeader = React.memo(function StackScreenHeader({
   );
 });
 
+let StackScreenHeaderLeft = React.memo(function StackScreenHeaderLeft({
+  ...props
+}: ViewProps) {
+  return <RNScreenStackHeaderLeftView {...props} />;
+});
+
+let StackScreenHeaderCenter = React.memo(function StackScreenHeaderCenter({
+  ...props
+}: ViewProps) {
+  return <RNScreenStackHeaderCenterView {...props} />;
+});
+
+let StackScreenHeaderRight = React.memo(function StackScreenHeaderRight({
+  ...props
+}: ViewProps) {
+  return <RNScreenStackHeaderRightView {...props} />;
+});
+
+let ScreenStackHeaderBackButtonImage = React.memo(
+  function ScreenStackHeaderBackButtonImage(props: ImageProps) {
+    return <RNScreenStackHeaderBackButtonImage {...props} />;
+  }
+);
+
 type StackNavigatorProps = Omit<StackRootProps, "children"> & {
   rootScreen: React.ReactElement<unknown>;
 };
@@ -272,6 +302,10 @@ export let Stack = {
   Screens: StackScreens,
   Screen: StackScreen,
   Header: StackScreenHeader,
+  HeaderLeft: StackScreenHeaderLeft,
+  HeaderCenter: StackScreenHeaderCenter,
+  HeaderRight: StackScreenHeaderRight,
+  HeaderBackImage: ScreenStackHeaderBackButtonImage,
   Slot: StackSlot,
   Navigator: StackNavigator,
 };

package/src/tabs.tsx

@@ -225,7 +225,11 @@ let TabsTab = React.memo(function TabsTab({
 
   let onPress: () => void = React.useCallback(() => {
     dispatch({ type: "SET_TAB_INDEX", tabId, index });
-  }, [tabId, index, dispatch]);
+
+    if (isActive) {
+      dispatch({ type: "POP_ACTIVE_TAB", tabId, index });
+    }
+  }, [tabId, index, dispatch, isActive]);
 
   let style = React.useMemo(() => {
     let baseStyle = props.style || defaultTabStyle;