Document createScreenFactory for 7.x

Author: satya164

versioned_docs/version-7.x/custom-navigators.md

@@ -22,6 +22,7 @@ A very basic example looks like this:
 import {
   useNavigationBuilder,
   createNavigatorFactory,
+  createScreenFactory,
   StackRouter,
 } from '@react-navigation/native';
 
@@ -38,6 +39,8 @@ function MyNavigator(props) {
 }
 
 export const createMyNavigator = createNavigatorFactory(MyNavigator);
+
+export const createMyScreen = createScreenFactory();
 ```
 
 Now, we have an already working navigator, even though it doesn't do anything special yet.
@@ -202,6 +205,50 @@ function App() {
 }
 ```
 
+### `createScreenFactory`
+
+This `createScreenFactory` function is used to create a typed screen factory function, which takes a screen configuration object for proper type-checking in static configuration.
+
+Custom navigators should use `createScreenFactory` with appropriate types to create the screen factory function and export it.
+
+Example:
+
+```js
+import { createScreenFactory } from '@react-navigation/native';
+
+// ...
+
+export const createMyScreen = createScreenFactory();
+```
+
+The [Type-checking navigators](#type-checking-navigators) section covers an example of how the API is used with types.
+
+Then it can be used like this:
+
+```js static2dynamic
+import { createStaticNavigation } from '@react-navigation/native';
+import { createMyNavigator, createMyScreen } from './myNavigator';
+
+const MyTabs = createMyNavigator({
+  screens: {
+    Home: HomeScreen,
+    Feed: createMyScreen({
+      screen: FeedScreen,
+      linking: 'feed/:sort',
+      options: ({ navigation, route }) => ({
+        title: `Feed - ${route.params.sort}`,
+      }),
+    }),
+  },
+});
+
+const Navigation = createStaticNavigation(MyTabs);
+
+function App() {
+  return <Navigation />;
+}
+```
+
 ## Type-checking navigators
 
 To type-check navigators, we need to provide few types:
@@ -212,7 +259,7 @@ To type-check navigators, we need to provide few types:
 - The type of the navigation object for each screen
 - The type of the props for each screen
 
-We also need to export a function to create the navigator configuration with proper types.
+We also need to export functions to create the navigator and screen configurations with proper types.
 
 For example, to type-check our custom tab navigator, we can do something like this:
 
@@ -228,6 +275,7 @@ import {
 } from 'react-native';
 import {
   createNavigatorFactory,
+  createScreenFactory,
   CommonActions,
   type DefaultNavigatorOptions,
   type NavigatorTypeBagBase,
@@ -362,29 +410,40 @@ function TabNavigator({ tabBarStyle, contentStyle, ...rest }: Props) {
   );
 }
 
+// Type bag used for type-checking the navigator
+export type MyTabTypeBag<
+  ParamList extends ParamListBase = ParamListBase,
+  NavigatorID extends string | undefined = string | undefined,
+> = {
+  ParamList: ParamList;
+  NavigatorID: NavigatorID;
+  State: TabNavigationState<ParamList>;
+  ScreenOptions: MyNavigationOptions;
+  EventMap: MyNavigationEventMap;
+  NavigationList: {
+    [RouteName in keyof ParamList]: MyNavigationProp<
+      ParamList,
+      RouteName,
+      NavigatorID
+    >;
+  };
+  Navigator: typeof TabNavigator;
+};
+
 // The factory function with overloads for static and dynamic configuration
 export function createMyNavigator<
   const ParamList extends ParamListBase,
   const NavigatorID extends string | undefined = string | undefined,
-  const TypeBag extends NavigatorTypeBagBase = {
-    ParamList: ParamList;
-    NavigatorID: NavigatorID;
-    State: TabNavigationState<ParamList>;
-    ScreenOptions: MyNavigationOptions;
-    EventMap: MyNavigationEventMap;
-    NavigationList: {
-      [RouteName in keyof ParamList]: MyNavigationProp<
-        ParamList,
-        RouteName,
-        NavigatorID
-      >;
-    };
-    Navigator: typeof TabNavigator;
-  },
+  const TypeBag extends NavigatorTypeBagBase = MyTabTypeBag<
+    ParamList,
+    NavigatorID
+  >,
   const Config extends StaticConfig<TypeBag> = StaticConfig<TypeBag>,
 >(config?: Config): TypedNavigator<TypeBag, Config> {
   return createNavigatorFactory(TabNavigator)(config);
 }
+
+export const createMyScreen = createScreenFactory<MyTabTypeBag>();
 ```
 
 ## Extending Navigators
@@ -396,6 +455,7 @@ import * as React from 'react';
 import {
   useNavigationBuilder,
   createNavigatorFactory,
+  createScreenFactory,
   TabRouter,
 } from '@react-navigation/native';
 import { BottomTabView } from '@react-navigation/bottom-tabs';
@@ -442,6 +502,8 @@ function MyBottomTabNavigator({
 export function createMyNavigator(config) {
   return createNavigatorFactory(MyBottomTabNavigator)(config);
 }
+
+export const createMyBottomTabScreen = createScreenFactory();
 ```
 
 Now, we can customize it to add additional functionality or change the behavior. For example, use a [custom router](custom-routers.md) instead of the default [`TabRouter`](custom-routers.md#built-in-routers):

versioned_docs/version-7.x/static-configuration.md

@@ -121,6 +121,42 @@ const RootStack = createNativeStackNavigator({
 
 The configuration object for a screen accepts the [properties described in the Screen page](screen.md). In addition, the following properties are available when using static configuration:
 
+#### `createXScreen`
+
+Each navigator exports a helper function to create screen configurations with proper TypeScript types. These helpers enable type inference for the params in the configuration callbacks such as `options` and `listeners`.
+
+Example usage:
+
+```js
+import {
+  createNativeStackNavigator,
+  createNativeStackScreen,
+} from '@react-navigation/native-stack';
+
+const Stack = createNativeStackNavigator({
+  screens: {
+    Profile: createNativeStackScreen({
+      screen: ProfileScreen,
+      options: ({ route }) => {
+        const userId = route.params.userId;
+
+        return {
+          title: `${userId}'s profile`,
+        };
+      },
+    }),
+  },
+});
+```
+
+Each navigator exports its own helper function:
+
+- `createNativeStackScreen` from `@react-navigation/native-stack`
+- `createStackScreen` from `@react-navigation/stack`
+- `createBottomTabScreen` from `@react-navigation/bottom-tabs`
+- `createDrawerScreen` from `@react-navigation/drawer`
+- `createMaterialTopTabScreen` from `@react-navigation/material-top-tabs`
+
 #### `linking`
 
 [Linking configuration](configuring-links.md) for the screen. It can be either a string for a path or an object with the linking configuration:

versioned_docs/version-7.x/static-vs-dynamic.md

@@ -147,9 +147,14 @@ All props passed to `<Stack.Screen>` except `name` and `component` become proper
 ```
 
 ```js title="Static API"
+import {
+  createNativeStackNavigator,
+  createNativeStackScreen,
+} from '@react-navigation/native-stack';
+
 const RootStack = createNativeStackNavigator({
   screens: {
-    Profile: {
+    Profile: createNativeStackScreen({
       screen: ProfileScreen,
       options: ({ route }) => ({
         title: route.params.userId,
@@ -158,11 +163,13 @@ const RootStack = createNativeStackNavigator({
         focus: () => console.log('focused'),
       },
       getId: ({ params }) => params.userId,
-    },
+    }),
   },
 });
 ```
 
+The [`createXScreen`](static-configuration.md#createxscreen) helper is for type inference in `options` and `listeners` callbacks. Each navigator exports its own screen helper: [`createNativeStackScreen`](native-stack-navigator.md), [`createStackScreen`](stack-navigator.md), [`createBottomTabScreen`](bottom-tab-navigator.md), [`createDrawerScreen`](drawer-navigator.md), [`createMaterialTopTabScreen`](material-top-tab-navigator.md).
+
 ## Conditional screens
 
 In the dynamic API, screens can be conditionally defined by rendering `Screen` components conditionally. In the static API, the [`if`](static-configuration.md#if) property can be used to conditionally render screens based on a hook returning a boolean.
@@ -590,6 +597,10 @@ function ProfileScreen({ route }: ProfileScreenProps) {
 
 ```ts title="Static API"
 import type { StaticScreenProps } from '@react-navigation/native';
+import {
+  createNativeStackNavigator,
+  createNativeStackScreen,
+} from '@react-navigation/native-stack';
 
 type Props = StaticScreenProps<{ userId: string }>;
 
@@ -599,7 +610,9 @@ function ProfileScreen({ route }: Props) {
 
 const RootStack = createNativeStackNavigator({
   screens: {
-    Profile: ProfileScreen,
+    Profile: createNativeStackScreen({
+      screen: ProfileScreen,
+    }),
   },
 });
 

versioned_docs/version-7.x/typescript.md

@@ -63,6 +63,36 @@ There are 2 steps to configure TypeScript with the static API:
 
    This is needed to type-check the [`useNavigation`](use-navigation.md) hook.
 
+The `createXScreen` helper functions enable type inference in screen configuration callbacks like `options`, `listeners`, etc. Each navigator exports its own version of the helper function:
+
+- `createNativeStackScreen` from `@react-navigation/native-stack`
+- `createStackScreen` from `@react-navigation/stack`
+- `createBottomTabScreen` from `@react-navigation/bottom-tabs`
+- `createDrawerScreen` from `@react-navigation/drawer`
+- `createMaterialTopTabScreen` from `@react-navigation/material-top-tabs`
+
+For example:
+
+```ts
+import {
+  createNativeStackNavigator,
+  createNativeStackScreen,
+} from '@react-navigation/native-stack';
+
+const RootStack = createNativeStackNavigator({
+  screens: {
+    Profile: createNativeStackScreen({
+      screen: ProfileScreen,
+      options: ({ route }) => ({
+        title: route.params.username,
+      }),
+    }),
+  },
+});
+```
+
+See [Static configuration](static-configuration.md#createxscreen) for more details.
+
 ## Navigator specific types
 
 Generally, we recommend using the default types for the [`useNavigation`](use-navigation.md) prop to access the navigation object in a navigator-agnostic manner. However, if you need to use navigator-specific APIs, e.g. `setOptions` to update navigator options, `push`, `pop`, `popTo` etc. with stacks, `openDrawer`, `closeDrawer` etc. with drawer and so on, you need to manually annotate [`useNavigation`](use-navigation.md):

versioned_docs/version-8.x/upgrading-from-7.x.md

@@ -136,45 +136,6 @@ If you're using dynamic configuration, you can use `as`:
 + const focusedRouteName = useNavigationState((state) => state.routes[state.index].name as keyof RootStackParamList);
 ```
 
-#### New `createXScreen` API for creating screen config
-
-One of the limitations of the static config API is that the type of `route` object can't be inferred in screen callback, listeners callback etc. This made it difficult to use route params in these callbacks.
-
-To address this, we added a new `createXScreen` API for each navigator to create screen config with proper types:
-
-```diff lang=js
-const Stack = createStackNavigator({
-  screens: {
--     Profile: {
--       screen: ProfileScreen,
--       options: ({ route }) => {
--         const userId = route.params.userId; // Don't know the type of route params
--
--         return { title: `User ${userId}` };
--       },
--     },
-+     Profile: createStackScreen({
-+       screen: ProfileScreen,
-+       options: ({ route }) => {
-+         const userId = route.params.userId; // Now correctly inferred
-+
-+         return { title: `User ${userId}` };
-+       },
-+     });
-  }
-});
-```
-
-When using the `createXScreen` API, the type of params are automatically inferred based on the type annotation for the component specified in `screen` (e.g. `(props: StaticScreenProps<ProfileParams>)`) and the path pattern specified in the linking config (e.g. `linking: 'profile/:userId'`).
-
-Each navigator exports its own helper function, e.g. `createNativeStackScreen` for Native Stack Navigator, `createBottomTabScreen` for Bottom Tab Navigator, `createDrawerScreen` for Drawer Navigator etc.
-
-:::note
-
-This is technically not a breaking change. It's not required to use this API and your existing code will continue to work as before. You can incrementally adopt this API for new screens to get proper types for `route` object in various callbacks such as `options`, `listeners`, etc.
-
-:::
-
 See [Static configuration docs](static-configuration.md#createxscreen) for more details.
 
 #### Custom navigators have a simpler type API
@@ -1040,6 +1001,47 @@ See the [`server rendering guide`](server-rendering.md) for a detailed guide and
 
 ## New features
 
+### `createXScreen` let's you create screen config with proper types
+
+One of the limitations of the static config API is that the type of `route` object can't be inferred in screen callback, listeners callback etc. This made it difficult to use route params in these callbacks.
+
+To address this, we added a new `createXScreen` API for each navigator to create screen config with proper types:
+
+```diff lang=js
+const Stack = createStackNavigator({
+  screens: {
+-     Profile: {
+-       screen: ProfileScreen,
+-       options: ({ route }) => {
+-         const userId = route.params.userId; // Don't know the type of route params
+-
+-         return { title: `User ${userId}` };
+-       },
+-     },
++     Profile: createStackScreen({
++       screen: ProfileScreen,
++       options: ({ route }) => {
++         const userId = route.params.userId; // Now correctly inferred
++
++         return { title: `User ${userId}` };
++       },
++     });
+  }
+});
+```
+
+When using the `createXScreen` API, the type of params are automatically inferred based on the type annotation for the component specified in `screen` (e.g. `(props: StaticScreenProps<ProfileParams>)`) and the path pattern specified in the linking config (e.g. `linking: 'profile/:userId'`).
+
+Each navigator exports its own helper function, e.g. `createNativeStackScreen` for Native Stack Navigator, `createBottomTabScreen` for Bottom Tab Navigator, `createDrawerScreen` for Drawer Navigator etc.
+
+This API has also been backported to React Navigation 7.
+
+:::note
+
+It's not required to use this API and your existing code will continue to work as before. You can incrementally adopt this API to get proper types for `route` object in various callbacks such as `options`, `listeners`, etc.
+
+:::
+
 ### Common hooks now accept name of the screen
 
 The `useNavigation`, `useRoute`, and `useNavigationState` hooks can now optionally accept the name of the screen: