@rn-tools/navigation 2.0.0 → 2.2.0

package/README.md

@@ -1,6 +1,25 @@
 # @rn-tools/navigation
 
-A set of useful navigation components for React Native. Built with `react-native-screens`. Designed with flexibility in mind.
+A set of useful navigation components for React Native. Built with `react-native-screens` and designed with flexibility in mind.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Basic Usage](#basic-usage)
+  - [Stack Navigator](#stack-navigator)
+  - [Tab Navigator](#tab-navigator)
+  - [Rendering a stack inside of a tabbed screen](#rendering-a-stack-inside-of-a-tabbed-screen)
+  - [Targeting a specific stack](#targeting-a-specific-stack)
+  - [Pushing a screen once](#pushing-a-screen-once)
+  - [Targeting specific tabs](#targeting-specific-tabs)
+  - [Rendering a header](#rendering-a-header)
+- [Components](#components)
+  - [Stack](#stack)
+  - [Tabs](#tabs)
+- [Guides](#guides)
+  - [Authentication](#authentication)
+  - [Deep Links](#deep-links)
+  - [Preventing going back](#preventing-going-back)
 
 ## Installation
 
@@ -8,13 +27,23 @@ A set of useful navigation components for React Native. Built with `react-native
 yarn expo install @rn-tools/navigation react-native-screens
 ```
 
+**Note:** It's recommended that you install and wrap your app in a `SafeAreaProvider` to ensure components are rendered correctly based on the device's insets:
+
+```bash
+yarn expo install react-native-safe-area-context
+```
+
 ## Basic Usage
 
-For basic usage, the exported `Stack.Navigator` and `Tabs.Navigator` will get you up and running quickly. The [Guides](#guides) section covers how to use lower-level `Stack` and `Tabs` components in a variety of navigation patterns.
+For basic usage, the exported `Stack.Navigator` and `Tabs.Navigator` will get you up and running quickly.
+
+The [Guides](#guides) section covers how to use lower-level `Stack` and `Tabs` components in a variety of navigation patterns.
+
+`Stack` and `Tabs` are composable components that can be safely nested within each other without any additional configuration or setup.
 
 ### Stack Navigator
 
-The `Stack.Navigator` component manages stacks of screens. Under the hood this is using `react-native-screens` to handle pushing and popping natively.
+The `Stack.Navigator` component manages screens. Under the hood this is using `react-native-screens` to handle pushing and popping natively.
 
 Screens are pushed and popped by the exported navigation methods:
 
@@ -22,6 +51,8 @@ Screens are pushed and popped by the exported navigation methods:
 
 - `navigation.popScreen(numberOfScreens: number) => void`
 
+In the majority of cases, these methods will determine the right stack without you needing to specify. But you can target a specific stacks as well if you need to! This is covered in the [Targeting a specific stack](#targeting-a-specific-stack) section.
+
 ```tsx
 import { Stack, navigation } from "@rn-tools/navigation";
 import * as React from "react";
@@ -33,15 +64,17 @@ export function BasicStack() {
 
 function MyScreen({
   title,
-  showPopButton = false,
+  children,
 }: {
   title: string;
-  showPopButton?: boolean;
+  children?: React.ReactNode;
 }) {
   function pushScreen() {
     navigation.pushScreen(
       <Stack.Screen>
-        <MyScreen title="Pushed screen" showPopButton />
+        <MyScreen title="Pushed screen">
+          <Button title="Pop screen" onPress={popScreen} />
+        </MyScreen>
       </Stack.Screen>
     );
   }
@@ -54,13 +87,13 @@ function MyScreen({
     <View style={{ flex: 1, justifyContent: "center", alignItems: "center" }}>
       <Text>{title}</Text>
       <Button title="Push screen" onPress={pushScreen} />
-      {showPopButton && <Button title="Pop screen" onPress={popScreen} />}
+      {children}
     </View>
   );
 }
 ```
 
-**Note**: The components passed to `navigation.pushScreen` need to be wrapped in a `Stack.Screen` component. Create a wrapper to simplify your usage if you'd like:
+**Note**: The components passed to `navigation.pushScreen` need to be wrapped in a `Stack.Screen`. Create a wrapper to simplify your usage if you'd like:
 
 ```tsx
 function myPushScreen(
@@ -73,39 +106,31 @@ function myPushScreen(
 
 ### Tab Navigator
 
-The `Tabs.Navigator` component also uses `react-native-screens` to handle the tab switching natively. The active tab can be changed via the `navigation.setTabIndex` method, however the build in tabbar already handles switching between screens.
+The `Tabs.Navigator` component also uses `react-native-screens` to handle switching between tabs natively.
+
+The active tab can be changed via the `navigation.setTabIndex` method, however the built in tabbar handles switching between screens out of the box.
 
 ```tsx
-import {
-  Stack,
-  Tabs,
-  navigation,
-  Stack,
-  defaultTabbarStyle,
-} from "@rn-tools/navigation";
+import { Tabs, navigation, Stack } from "@rn-tools/navigation";
 import * as React from "react";
 import { View, Text, Button } from "react-native";
-import { useSafeAreaInsets } from "react-native-safe-area-context";
+
+// It's recommended to wrap your App in a SafeAreaProvider once
+import { SafeAreaProvider } from "react-native-safe-area-context";
 
 export function BasicTabs() {
-  return <Stack.Navigator rootScreen={<MyTabs />} />;
+  return (
+    <SafeAreaProvider>
+      <Stack.Navigator rootScreen={<MyTabs />} />
+    </SafeAreaProvider>
+  );
 }
 
 function MyTabs() {
-  // This hook requires you to wrap your app in a SafeAreaProvider component - see the `react-native-safe-area-context` package
-  let insets = useSafeAreaInsets();
-
-  let tabbarStyle = React.useMemo(() => {
-    return {
-      ...defaultTabbarStyle,
-      bottom: insets.bottom,
-    };
-  }, [insets.bottom]);
-
   return (
     <Tabs.Navigator
       tabbarPosition="bottom"
-      tabbarStyle={tabbarStyle}
+      tabbarStyle={{ backgroundColor: "blue" }}
       screens={[
         {
           key: "1",
@@ -147,17 +172,19 @@ function MyTab({
 
 function MyScreen({
   title,
-  showPopButton = false,
+  children,
   bg,
 }: {
   title: string;
-  showPopButton?: boolean;
+  children?: React.ReactNode;
   bg?: string;
 }) {
   function pushScreen() {
     navigation.pushScreen(
       <Stack.Screen>
-        <MyScreen title="Pushed screen" showPopButton />
+        <MyScreen title="Pushed screen" bg={bg}>
+          <Button title="Pop screen" onPress={popScreen} />
+        </MyScreen>
       </Stack.Screen>
     );
   }
@@ -177,7 +204,7 @@ function MyScreen({
     >
       <Text>{title}</Text>
       <Button title="Push screen" onPress={pushScreen} />
-      {showPopButton && <Button title="Pop screen" onPress={popScreen} />}
+      {children}
     </View>
   );
 }
@@ -187,8 +214,6 @@ function MyScreen({
 
 Each tab can have its own stack by nesting the `Stack.Navigator` component.
 
-- `navigation.pushScreen` will still work relative by pushing to the relative parent stack of the screen. See the next section for how to push a screen onto a specific stack.
-
 ```tsx
 function MyTabs() {
   return (
@@ -272,9 +297,76 @@ function switchMainTabsToTab(tabIndex: number) {
 }
 ```
 
+### Rendering a header
+
+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.
+
+```tsx
+import { navigation, Stack } from "@rn-tools/navigation";
+import * as React from "react";
+import { Button, View, TextInput, Text } from "react-native";
+
+export function HeaderExample() {
+  return (
+    <View>
+      <Button
+        title="Push screen with header"
+        onPress={() => navigation.pushScreen(<MyScreenWithHeader />)}
+      />
+    </View>
+  );
+}
+
+function MyScreenWithHeader() {
+  let [title, setTitle] = React.useState("");
+
+  return (
+    <Stack.Screen>
+      {/* Header must be the first child */}
+      <Stack.Header
+        title={title}
+        // Some potentially useful props - see the reference posted above for all available props
+        backTitle="Custom back title"
+        backTitleFontSize={16}
+        hideBackButton={false}
+      >
+        <Stack.HeaderRight>
+          <Text>Custom right text!</Text>
+        </Stack.HeaderRight>
+      </Stack.Header>
+
+      <View
+        style={{
+          flex: 1,
+          alignItems: "center",
+          paddingVertical: 48,
+        }}
+      >
+        <TextInput
+          style={{ fontSize: 26, fontWeight: "semibold" }}
+          value={title}
+          onChangeText={setTitle}
+          placeholder="Enter header text"
+        />
+      </View>
+    </Stack.Screen>
+  );
+}
+```
+
 ## Components
 
-The `Navigator` components in the previous examples are convenience wrappers around other lower level `Stack` and `Tabs` components. This section will briefly cover each of the underlying components so that you can build your own wrappers if needed
+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.
 
 ### Stack
 
@@ -311,30 +403,47 @@ export function StackNavigator({
   - Reference for props that can be passed: [Screen Props](https://github.com/software-mansion/react-native-screens/blob/main/guides/GUIDE_FOR_LIBRARY_AUTHORS.md#screen)
 - `Stack.Slot` - A slot for screens to be pushed into.
   - This component is used to render screens that are pushed using `navigation.pushScreen` - don't forget to render this somewhere in `Stack.Screens`!
+- `Stack.Header` - A header for a screen.
+  - **Must be rendered as the first child of a `Stack.Screen` component.**
+  - This is a `react-native-screens` StackHeader component under the hood.
+  - Reference for props that can be passed: [Header Props](https://github.com/software-mansion/react-native-screens/blob/main/guides/GUIDE_FOR_LIBRARY_AUTHORS.md#screenstackheaderconfig)
 
 ## Tabs
 
 This is the implementation of the exported `Tabs.Navigator` component:
 
 ```tsx
-type TabsNavigatorProps = Omit<TabsRootProps, "children"> & {
-  screens: Tabs.NavigatorScreenOptions[];
+export type TabNavigatorProps = Omit<TabsRootProps, "children"> & {
+  screens: TabNavigatorScreenOptions[];
   tabbarPosition?: "top" | "bottom";
   tabbarStyle?: ViewProps["style"];
 };
 
-type TabsNavigatorScreenOptions = {
+export type TabNavigatorScreenOptions = {
   key: string;
-  screen: React.ReactElement<ScreenProps>;
+  screen: React.ReactElement<unknown>;
   tab: (props: { isActive: boolean; onPress: () => void }) => React.ReactNode;
 };
 
-export function Tabs.Navigator({
+let TabNavigator = React.memo(function TabNavigator({
   screens,
   tabbarPosition = "bottom",
-  tabbarStyle,
+  tabbarStyle: tabbarStyleProp,
   ...rootProps
-}: TabsNavigatorProps) {
+}: TabNavigatorProps) {
+  let insets = useSafeAreaInsetsSafe();
+
+  let tabbarStyle = React.useMemo(() => {
+    return [
+      defaultTabbarStyle,
+      {
+        paddingBottom: tabbarPosition === "bottom" ? insets.bottom : 0,
+        paddingTop: tabbarPosition === "top" ? insets.top : 0,
+      },
+      tabbarStyleProp,
+    ];
+  }, [tabbarPosition, tabbarStyleProp, insets]);
+
   return (
     <Tabs.Root {...rootProps}>
       {tabbarPosition === "top" && (
@@ -360,7 +469,7 @@ export function Tabs.Navigator({
       )}
     </Tabs.Root>
   );
-}
+});
 ```
 
 - `Tabs.Root` - The root component for a tabs navigator.
@@ -419,4 +528,218 @@ let useUser = () => {
 };
 ```
 
-**Note:** Screens that are pushed using `pushScreen` are rendered in the `Slot` component
+### 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. 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.0.0",
+  "version": "2.2.0",
   "main": "./src/index.ts",
   "license": "MIT",
   "files": [
@@ -30,9 +30,11 @@
   "peerDependencies": {
     "react": "*",
     "react-native": "*",
+    "react-native-safe-area-context": "*",
     "react-native-screens": "*"
   },
   "dependencies": {
+    "path-to-regexp": "^6.2.2",
     "zustand": "^4.5.2"
   },
   "jest": {

package/src/contexts.tsx

@@ -1,4 +1,4 @@
-import * as React from 'react'
+import * as React from "react";
 
 export let StackIdContext = React.createContext<string>("");
 export let ScreenIdContext = React.createContext<string>("");

package/src/deep-links.tsx

@@ -0,0 +1,39 @@
+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(() => {
+    matchers.current.forEach(({ fn, handler }) => {
+      let match = fn(path);
+      if (match) {
+        return setImmediate(() => handler(match.params as T));
+      }
+    });
+  }, [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";
@@ -365,37 +372,45 @@ export function reducer(
       }
 
       let nextState: NavigationState = Object.assign({}, state);
+      let currentIndex = tab.activeIndex;
       nextState.tabs.lookup[tabId] = Object.assign(
         {},
         {
           ...nextState.tabs.lookup[tabId],
           activeIndex: index,
-          history: tab.history.filter((i) => i !== index).concat(index),
+          history: tab.history.filter((i) => i !== index).concat(currentIndex),
         }
       );
 
-      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,10 +457,15 @@ export function reducer(
       let nextState: NavigationState = Object.assign({}, state);
 
       let tab = nextState.tabs.lookup[tabId];
-      let last = tab.history.pop();
-      if (last != null) {
-        tab.activeIndex = last;
-      }
+
+      let lastActiveIndex = tab.history[tab.history.length - 1];
+
+      nextState.tabs.lookup = Object.assign({}, nextState.tabs.lookup, {
+        [tabId]: Object.assign({}, nextState.tabs.lookup[tabId], {
+          activeIndex: lastActiveIndex,
+          history: tab.history.filter((i) => i !== lastActiveIndex),
+        }),
+      });
 
       return nextState;
     }

package/src/navigation-store.ts

@@ -17,20 +17,18 @@ export function createNavigationStore() {
 
   let reducer = (state: NavigationState, action: NavigationAction) => {
     let nextState = navigationReducer(state, action, { renderCharts });
+    if (nextState.debugModeEnabled) {
+      console.debug(
+        `[@rntoolkit/navigation] action: ${action.type}`,
+        state,
+        nextState
+      );
+    }
     return { ...nextState };
   };
 
   let store = createStore(devtools(redux(reducer, initialState)));
 
-  store.subscribe((state) => {
-    if (state.debugModeEnabled) {
-      console.debug("[@rntoolkit/navigation] state updated: ", {
-        state,
-        renderCharts,
-      });
-    }
-  });
-
   return {
     store: store,
     dispatch: store.dispatch,
@@ -53,3 +51,8 @@ export function useNavigationDispatch() {
   let dispatch = React.useContext(NavigationDispatchContext);
   return dispatch;
 }
+
+export function useGetNavigationStore() {
+  let context = React.useContext(NavigationStateContext);
+  return context.getState
+}

package/src/navigation.tsx

@@ -13,7 +13,8 @@ import type { PushScreenOptions } from "./types";
 /**
  * Ideas:
  *  - lifecycles / screen tracking
- *  - testing - internal and jest plugin
+ *  - testing guide
+ *  - routing example -> fragments to ids
  */
 
 export function createNavigation() {

package/src/stack.tsx

@@ -1,11 +1,26 @@
 import * as React from "react";
-import { BackHandler, StyleSheet, type ViewStyle } from "react-native";
+import {
+  BackHandler,
+  PixelRatio,
+  Platform,
+  StyleSheet,
+  useWindowDimensions,
+  View,
+  type ImageProps,
+  type LayoutRectangle,
+  type ViewProps,
+  type ViewStyle,
+} from "react-native";
 import {
   ScreenStackProps as RNScreenStackProps,
   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";
 
@@ -18,16 +33,18 @@ import {
 import { DEFAULT_SLOT_NAME } from "./navigation-reducer";
 import { useNavigationDispatch, useNavigationState } from "./navigation-store";
 import type { StackItem } from "./types";
-import { generateStackId } from "./utils";
+import { generateStackId, useSafeAreaInsetsSafe } from "./utils";
 
 let StackIdContext = React.createContext<string>("");
 let ScreenIdContext = React.createContext<string>("");
 
-const RNScreenStack = React.memo(function RNScreenStack(
+// Component returned from `react-native-screens` references `react-navigation` data structures in recent updates
+// This is a workaround to make it work with our custom navigation
+let RNScreenStack = React.memo(function RNScreenStack(
   props: RNScreenStackProps
 ) {
-  const { children, gestureDetectorBridge, ...rest } = props;
-  const ref = React.useRef(null);
+  let { children, gestureDetectorBridge, ...rest } = props;
+  let ref = React.useRef(null);
 
   React.useEffect(() => {
     if (gestureDetectorBridge) {
@@ -112,18 +129,13 @@ function StackRoot({ children, id }: StackRootProps) {
   );
 }
 
-function StackScreens({
-  style: styleProp,
-  ...props
-}: RNScreenStackProps) {
+function StackScreens({ style: styleProp, ...props }: RNScreenStackProps) {
   let style = React.useMemo(
     () => styleProp || StyleSheet.absoluteFill,
     [styleProp]
   );
 
-  return (
-    <RNScreenStack {...props} style={style} />
-  );
+  return <RNScreenStack {...props} style={style} />;
 }
 
 let defaultScreenStyle: ViewStyle = {
@@ -180,7 +192,7 @@ let StackScreen = React.memo(function StackScreen({
     <RNScreen
       {...props}
       style={style}
-      // activityState={isActive ? 2 : 0}
+      activityState={isActive ? 2 : 0}
       gestureEnabled={gestureEnabled}
       onDismissed={onDismissed}
     >
@@ -224,9 +236,49 @@ let StackSlot = React.memo(function StackSlot({
 let StackScreenHeader = React.memo(function StackScreenHeader({
   ...props
 }: RNScreenStackHeaderConfigProps) {
-  return <RNScreenStackHeaderConfig {...props} />;
+  let layout = useWindowDimensions();
+  let insets = useSafeAreaInsetsSafe();
+
+  let headerHeight = React.useMemo(() => {
+    if (Platform.OS === "android") {
+      return 0;
+    }
+
+    return getDefaultHeaderHeight(layout, false, insets.top);
+  }, [layout, insets]);
+
+  return (
+    <React.Fragment>
+      <RNScreenStackHeaderConfig {...props} />
+      <View style={{ height: headerHeight }} />
+    </React.Fragment>
+  );
 });
 
+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>;
 };
@@ -250,6 +302,54 @@ export let Stack = {
   Screens: StackScreens,
   Screen: StackScreen,
   Header: StackScreenHeader,
+  HeaderLeft: StackScreenHeaderLeft,
+  HeaderCenter: StackScreenHeaderCenter,
+  HeaderRight: StackScreenHeaderRight,
+  HeaderBackImage: ScreenStackHeaderBackButtonImage,
   Slot: StackSlot,
   Navigator: StackNavigator,
 };
+
+// `onLayout` event does not return a value for the native header component
+// This function is copied from react-navigation to get the default header heights
+// Ref: https://github.com/react-navigation/react-navigation/blob/main/packages/elements/src/Header/getDefaultHeaderHeight.tsx#L5
+function getDefaultHeaderHeight(
+  layout: Pick<LayoutRectangle, "width" | "height">,
+  // TODO - handle modal headers and substacks
+  modalPresentation: boolean,
+  topInset: number
+): number {
+  let headerHeight;
+
+  // On models with Dynamic Island the status bar height is smaller than the safe area top inset.
+  let hasDynamicIsland = Platform.OS === "ios" && topInset > 50;
+  let statusBarHeight = hasDynamicIsland
+    ? topInset - (5 + 1 / PixelRatio.get())
+    : topInset;
+
+  let isLandscape = layout.width > layout.height;
+
+  if (Platform.OS === "ios") {
+    if (Platform.isPad || Platform.isTV) {
+      if (modalPresentation) {
+        headerHeight = 56;
+      } else {
+        headerHeight = 50;
+      }
+    } else {
+      if (isLandscape) {
+        headerHeight = 32;
+      } else {
+        if (modalPresentation) {
+          headerHeight = 56;
+        } else {
+          headerHeight = 44;
+        }
+      }
+    }
+  } else {
+    headerHeight = 64;
+  }
+
+  return headerHeight + statusBarHeight;
+}

package/src/tabs.tsx

@@ -21,8 +21,12 @@ import {
   TabIdContext,
   TabScreenIndexContext,
 } from "./contexts";
-import { useNavigationDispatch, useNavigationState } from "./navigation-store";
-import { generateTabId } from "./utils";
+import {
+  useGetNavigationStore,
+  useNavigationDispatch,
+  useNavigationState,
+} from "./navigation-store";
+import { generateTabId, useSafeAreaInsetsSafe } from "./utils";
 
 type TabsRootProps = {
   children: React.ReactNode;
@@ -121,6 +125,7 @@ let TabsScreen = React.memo(function TabsScreen({
 
   let tabId = React.useContext(TabIdContext);
   let tabs = useTabsInternal(tabId);
+  let getNavigationStore = useGetNavigationStore();
   let index = React.useContext(TabScreenIndexContext);
 
   let parentIsActive = React.useContext(ActiveContext);
@@ -129,6 +134,9 @@ let TabsScreen = React.memo(function TabsScreen({
 
   React.useEffect(() => {
     function backHandler() {
+      // Use getter to register the handler once on mount
+      // Prevents it from overriding child screen handlers
+      let tabs = getNavigationStore().tabs.lookup[tabId];
       if (tabs && tabs.history.length > 0) {
         dispatch({ type: "TAB_BACK", tabId });
         return true;
@@ -142,7 +150,7 @@ let TabsScreen = React.memo(function TabsScreen({
     return () => {
       BackHandler.removeEventListener("hardwareBackPress", backHandler);
     };
-  }, [tabId, dispatch, tabs]);
+  }, [tabId, dispatch, getNavigationStore]);
 
   let style = React.useMemo(
     () => styleProp || StyleSheet.absoluteFill,
@@ -217,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;
@@ -242,12 +254,37 @@ let TabsTab = React.memo(function TabsTab({
 });
 
 
+export type TabNavigatorProps = Omit<TabsRootProps, "children"> & {
+  screens: TabNavigatorScreenOptions[];
+  tabbarPosition?: "top" | "bottom";
+  tabbarStyle?: ViewProps["style"];
+};
+
+export type TabNavigatorScreenOptions = {
+  key: string;
+  screen: React.ReactElement<unknown>;
+  tab: (props: { isActive: boolean; onPress: () => void }) => React.ReactNode;
+};
+
 let TabNavigator = React.memo(function TabNavigator({
   screens,
   tabbarPosition = "bottom",
-  tabbarStyle,
+  tabbarStyle: tabbarStyleProp,
   ...rootProps
 }: TabNavigatorProps) {
+  let insets = useSafeAreaInsetsSafe();
+
+  let tabbarStyle = React.useMemo(() => {
+    return [
+      defaultTabbarStyle,
+      {
+        paddingBottom: tabbarPosition === "bottom" ? insets.bottom : 0,
+        paddingTop: tabbarPosition === "top" ? insets.top : 0,
+      },
+      tabbarStyleProp,
+    ];
+  }, [tabbarPosition, tabbarStyleProp, insets]);
+
   return (
     <Tabs.Root {...rootProps}>
       {tabbarPosition === "top" && (
@@ -283,15 +320,3 @@ export let Tabs = {
   Tab: TabsTab,
   Navigator: TabNavigator,
 };
-
-export type TabNavigatorProps = Omit<TabsRootProps, "children"> & {
-  screens: TabNavigatorScreenOptions[];
-  tabbarPosition?: "top" | "bottom";
-  tabbarStyle?: ViewProps["style"];
-};
-
-export type TabNavigatorScreenOptions = {
-  key: string;
-  screen: React.ReactElement<unknown>;
-  tab: (props: { isActive: boolean; onPress: () => void }) => React.ReactNode;
-};

package/src/utils.ts

@@ -1,3 +1,6 @@
+import { Platform } from 'react-native';
+import { useSafeAreaInsets, type EdgeInsets } from 'react-native-safe-area-context'
+
 export let generateStackId = createIdGenerator("stack");
 export let generateScreenId = createIdGenerator("screen");
 export let generateTabId = createIdGenerator("tab");
@@ -12,3 +15,27 @@ function createIdGenerator(name: string) {
 
 export let serializeTabIndexKey = (tabId: string, index: number) =>
   `${tabId}-${index}`;
+
+
+
+
+let baseInsets: EdgeInsets = {
+  top: Platform.OS === "ios" ? 59 : 49,
+  bottom: Platform.OS === "ios" ? 34 : 0,
+  right: 0,
+  left: 0,
+};
+
+export function useSafeAreaInsetsSafe() {
+  let insets = baseInsets;
+
+  try {
+    // Linter thinks this is conditional but it seems fine
+    // eslint-disable-next-line
+    insets = useSafeAreaInsets();
+  } catch (error) {
+    console.log("useSafeAreaInsets is not available");
+  }
+
+  return insets;
+}