Document navigator specific state

Author: satya164

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

@@ -69,6 +69,35 @@ const state = {
 
 It's important to note that even if there's a nested navigator, the `state` property on the `route` object is not added until a navigation happens, hence it's not guaranteed to exist, or maybe [stale](#stale-state-objects).
 
+## Navigator specific state
+
+Various navigators may also add additional properties to the navigation state object. Each navigator uses a [router](custom-routers.md) to manage the navigation state, and the router determines the shape of the navigation state object.
+
+Built-in navigators add the following properties:
+
+### Stack
+
+For navigators using the built-in `StackRouter`, such as [Stack](stack-navigator.md) and [Native Stack](native-stack-navigator.md) navigators, the state object has the following additional properties:
+
+- `type` - Always `stack`.
+- `preloadedRoutes` - Route objects for stack screens preloaded with [`preload`](navigation-actions.md#preload).
+
+### Tab
+
+For navigators using the built-in `TabRouter`, such as [Bottom Tabs](bottom-tab-navigator.md) and [Material Top Tabs](material-top-tab-navigator.md) navigators, the state object has the following additional properties:
+
+- `type` - Always `tab`.
+- `history` - Route history entries with `{ type: 'route', key, params? }`.
+- `preloadedRouteKeys` - Route keys for tab screens preloaded with [`preload`](navigation-actions.md#preload).
+
+### Drawer
+
+For navigators using the built-in `DrawerRouter`, such as [Drawer](drawer-navigator.md) navigator, the state object contains the same properties as the `TabRouter` with the following additional properties:
+
+- `type` - Always `drawer`.
+- `default` - The default drawer status from the `defaultStatus` option, either `open` or `closed`.
+- `history` - Drawer entries with `{ type: 'drawer', status: 'open' | 'closed' }` in addition to route history entries.
+
 ## History stack
 
 In React Navigation, each navigator may maintain a history stack to keep track of visited entries. This is used when navigating back, syncing with browser history on the Web, etc.

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

@@ -70,6 +70,37 @@ const state = {
 
 It's important to note that even if there's a nested navigator, the `state` property on the `route` object is not added until a navigation happens, hence it's not guaranteed to exist, or maybe [stale](#stale-state-objects).
 
+## Navigator specific state
+
+Various navigators may also add additional properties to the navigation state object. Each navigator uses a [router](custom-routers.md) to manage the navigation state, and the router determines the shape of the navigation state object.
+
+Built-in navigators add the following properties:
+
+### Stack
+
+For navigators using the built-in `StackRouter`, such as [Stack](stack-navigator.md) and [Native Stack](native-stack-navigator.md) navigators, the state object has the following additional properties:
+
+- `type` - Always `stack`.
+- `retainedRouteKeys` - Route keys for routes that should be [retained](stack-actions.md#retain) when they are removed from the history stack.
+
+The `routes` array contains the history of visited screens until `index`, and the route objects after `index` represent [preloaded](navigation-actions.md#preload) or [retained](stack-actions.md#retain) screens.
+
+### Tab
+
+For navigators using the built-in `TabRouter`, such as [Bottom Tabs](bottom-tab-navigator.md) and [Material Top Tabs](material-top-tab-navigator.md) navigators, the state object has the following additional properties:
+
+- `type` - Always `tab`.
+- `history` - Route history entries with `{ type: 'route', key, params? }`.
+- `preloadedRouteKeys` - Route keys for tab screens preloaded with [`preload`](navigation-actions.md#preload).
+
+### Drawer
+
+For navigators using the built-in `DrawerRouter`, such as [Drawer](drawer-navigator.md) navigator, the state object contains the same properties as the `TabRouter` with the following additional properties:
+
+- `type` - Always `drawer`.
+- `default` - The default drawer status from the `defaultStatus` option, either `open` or `closed`.
+- `history` - Drawer entries with `{ type: 'drawer', status: 'open' | 'closed' }` in addition to route history entries.
+
 ## History stack
 
 In React Navigation, each navigator may maintain a history stack to keep track of visited entries. This is used when navigating back, syncing with browser history on the Web, etc.
@@ -78,7 +109,7 @@ Unlike Web, which has a linear history stack, React Navigation uses a nested his
 
 The history stack for a navigator is determined from the following sources:
 
-- `state.history` if present, otherwise `state.routes`
+- `state.history` if present, otherwise `state.routes` until `state.index`
 - `route.history` for each route in `state.routes`
 
 When determining total length of history stack (e.g. to sync with browser history on the Web), these 2 sources are combined.