Document behavior change regarding preloaded routes

Author: satya164

versioned_docs/version-8.x/navigation-actions.md

@@ -222,14 +222,17 @@ If you want to preserve the existing screens but only want to modify the state,
 import { CommonActions } from '@react-navigation/native';
 
 navigation.dispatch((state) => {
-  // Remove all the screens after `Profile`
-  const index = state.routes.findIndex((r) => r.name === 'Profile');
-  const routes = state.routes.slice(0, index + 1);
+  // Remove active screens after `Profile`
+  const activeRoutes = state.routes.slice(0, state.index + 1);
+  const extraRoutes = state.routes.slice(state.index + 1);
+
+  const index = activeRoutes.findIndex((r) => r.name === 'Profile');
+  const routes = [...activeRoutes.slice(0, index + 1), ...extraRoutes];
 
   return CommonActions.reset({
     ...state,
     routes,
-    index: routes.length - 1,
+    index,
   });
 });
 ```
@@ -522,8 +525,6 @@ Depending on the navigator, `preload` may work differently:
 - In a stack navigator ([stack](stack-navigator.md), [native stack](native-stack-navigator.md)), the screen will be rendered off-screen and animated in when you navigate to it. If [`getId`](screen.md#id) is specified, it'll be used for the navigation to identify the preloaded screen.
 - In a tab or drawer navigator ([bottom tabs](bottom-tab-navigator.md), [material top tabs](material-top-tab-navigator.md), [drawer](drawer-navigator.md), etc.), the existing screen will be rendered as if `lazy` was set to `false`. Calling `preload` on a screen that is already rendered will not have any effect.
 
-When a screen is preloaded in a stack navigator, it can't dispatch navigation actions (e.g. `navigate`, `goBack`, etc.) until it becomes active.
-
 ### setParams
 
 The `setParams` action allows to merge params for a certain route. It takes the following arguments:

versioned_docs/version-8.x/navigation-object.md

@@ -914,8 +914,6 @@ Depending on the navigator, `preload` may work slightly differently:
 - In a stack navigator ([stack](stack-navigator.md), [native stack](native-stack-navigator.md)), the screen will be rendered off-screen and animated in when you navigate to it. If [`getId`](screen.md#id) is specified, it'll be used for the navigation to identify the preloaded screen.
 - In a tab or drawer navigator ([bottom tabs](bottom-tab-navigator.md), [material top tabs](material-top-tab-navigator.md), [drawer](drawer-navigator.md), etc.), the existing screen will be rendered as if `lazy` was set to `false`. Calling `preload` on a screen that is already rendered will not have any effect.
 
-When a screen is preloaded in a stack navigator, it can't dispatch navigation actions (e.g. `navigate`, `goBack`, etc.) until it becomes active.
-
 ### `setParams`
 
 The `setParams` method lets us update the params (`route.params`) of the current screen. `setParams` works like React's `setState` - it shallow merges the provided params object with the current params.
@@ -1698,35 +1696,35 @@ navigation.dispatch((state) => {
   return CommonActions.reset({
     ...state,
     routes,
-    index: routes.length - 1,
+    index: state.index + 1,
   });
 });
 ```
 
-You can use this functionality to build your own helpers that you can utilize in your app. Here is an example which implements inserting a screen just before the last one:
+You can use this functionality to build your own helpers that you can utilize in your app. Here is an example which implements inserting a screen just before the focused one:
 
 ```js
 import { CommonActions } from '@react-navigation/native';
 
-const insertBeforeLast = (routeName, params) => (state) => {
+const insertBeforeFocused = (routeName, params) => (state) => {
   const routes = [
-    ...state.routes.slice(0, -1),
+    ...state.routes.slice(0, state.index),
     { name: routeName, params },
-    state.routes[state.routes.length - 1],
+    ...state.routes.slice(state.index),
   ];
 
   return CommonActions.reset({
     ...state,
     routes,
-    index: routes.length - 1,
+    index: state.index + 1,
   });
 };
 ```
 
 Then use it like:
 
 ```js
-navigation.dispatch(insertBeforeLast('Home'));
+navigation.dispatch(insertBeforeFocused('Home'));
 ```
 
 ### `canGoBack`

versioned_docs/version-8.x/navigation-state.md

@@ -27,7 +27,7 @@ There are few properties present in every navigation state object:
 - `type` - Type of the navigator that the state belongs to, e.g. `stack`, `tab`, `drawer`.
 - `key` - Unique key to identify the navigator.
 - `routeNames` - Name of the screens defined in the navigator. This is an unique array containing strings for each screen.
-- `routes` - List of route objects (screens) which are rendered in the navigator. It also represents the history in a stack navigator. There should be at least one item present in this array.
+- `routes` - List of route objects (screens) which are rendered in the navigator. In a stack or native stack navigator, the entries up to and including `index` also represent the history. There should be at least one item present in this array.
 - `index` - Index of the focused route object in the `routes` array.
 - `history` - An optional list of visited items. See [History stack](#history-stack) for more details.
 - `stale` - A navigation state is assumed to be stale unless the `stale` property is explicitly set to `false`. This means that the state object needs to be ["rehydrated"](#stale-state-objects).

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

@@ -301,7 +301,39 @@ createBottomTabNavigator({
 </TabItem>
 </Tabs>
 
-#### Preloaded screens now behave differently
+#### Preloaded routes in Stack have been reworked
+
+Preloaded routes in Stack and Native Stack Navigators have been reworked to remove various restrictions.
+
+The rework has 2 main consequences:
+
+##### Stack navigation state shape has changed
+
+Previously, the navigation state for Stack and Native Stack Navigators was as follows:
+
+- `state.routes` - array of route objects for active screens in the stack, limited by `state.index`.
+- `state.preloadedRoutes` - array of route objects for preloaded screens in the stack.
+
+After, the rework:
+
+- `state.routes` - array of route objects for all screens, including preloaded screens, which can extend beyond `state.index` and the routes after `state.index` are considered preloaded.
+- `state.preloadedRoutes` - no longer exists.
+
+So if your code had assumptions about `state.routes` being limited by `state.index` (e.g. determining focused route by checking if it's the last route in `state.routes` instead of using `state.index`), you may need to update it to check for `state.index` instead.
+
+```diff lang=js
+- const focusedRoute = state.routes[state.routes.length - 1];
++ const focusedRoute = state.routes[state.index];
+```
+
+Similarly, if you were using `state.preloadedRoutes` to get the preloaded routes, you can now get them by slicing `state.routes`:
+
+```diff lang=js
+- const preloadedRoutes = state.preloadedRoutes;
++ const preloadedRoutes = state.routes.slice(state.index + 1);
+```
+
+##### Preloaded screens behave closer to regular screens
 
 Previously, when a screen was preloaded in Stack and Native Stack Navigators, there were a few restrictions: