@apexnative/navigation 1.0.0-alpha.1 → 1.0.0-alpha.10

package/docs-md/fundamentals/screens-and-props.md

@@ -70,7 +70,7 @@ What `screens` takes, from the simplest:
 | Entry | When |
 | --- | --- |
 | A component | A screen without options of its own: `Settings`. |
-| `defineScreen({ component, options })` | A screen with its options next to it: see [Options](#options). |
+| `defineScreen({ component, options })` | A screen with its options next to it: see [Options](#options). It returns a component that renders the screen. |
 | `{ load: () => import('./screens/Settings') }` | A screen whose code runs the first time it shows: see [Loading later](#lazy). |
 | `nativeScreen('ProfileScreen', …)` | A screen written in SwiftUI, UIKit or Compose: see [Native screens](../architecture/native-screens). |
 | `defineArrangement({ primary, secondary })` | Two screens shown as one, side by side in a large window: see [Arrangement](../containers/arrangement). |
@@ -172,10 +172,18 @@ export const DetailsScreen = defineScreen({
 | `props` | The props of this showing, typed from the component. |
 | `{ theme, context }` | The theme of the navigation and the app's context, as they are when the screen shows. |
 
+`defineScreen` returns a component of its own, typed `DefinedScreen`, which renders your component and carries the definition; your component stays as it is, for any other use of it. Put the result in `screens` as it is. Rendered alone, in a test, it renders the screen.
+
 The options go to the native side with the command, so they apply **before the screen appears**: the title is there from the first frame, not set after a render.
 
 Options come from several places, and the later go over the earlier: the screen's [group](#groups), its `defineScreen`, the `options` of the command, and `setOptions` or `useScreenOptions` from the screen itself. The whole order, with the theme and the defaults of the app: [Screen options](./screen-options).
 
+### Fast Refresh
+
+An edit of a screen file updates the screen in place, with its state, when the file is a Fast Refresh boundary: it exports only screens and components. A constant or an object exported from it makes it not a boundary. With `withApexNavigation` in `metro.config.js` ([Installation](../start/installation#fast-refresh)) such an edit still doesn't reload the app: it goes up to the module of the app's `createNavigation`, which updates the running app.
+
+An edit of `options` reaches the screens of it at once, a tab not rendered yet too. Changed and added options are merged in; an option taken out is cleared. An option the command gave the screen, or one the screen set since (`useScreenOptions`, `mergeOptions`), stays as it is. An edit of `key` or `arrangement` applies from the next show.
+
 ## The life of a screen
 
 A screen isn't only mounted or not. Under another screen it is **still mounted but not seen**: its state and scroll stay, and it comes back as it was. So a screen has two lines of life: React's, from mount to unmount, and the user's, each time it appears and disappears.

package/docs-md/fundamentals/starting-the-app.md

@@ -176,7 +176,7 @@ More: [Errors and loading](../architecture/errors-and-loading).
 
 Keys of the system; the defaults suit most apps.
 
-- `safeArea` — the edges on which every screen keeps its content out of the safe area: `{ edges: ['top', 'bottom'] }`.
+- `safeArea` — the edges on which every screen keeps its content out of the safe area: `{ edges: ['top', 'left', 'right', 'bottom'] }`. Listed edges replace the default, so list every edge the screens keep. Without it the screens keep the top and the sides, and the bottom is free.
 - `window` — (iOS) the color behind the screens, seen around a modal as it comes in: `{ backgroundColor: '#000000' }`.
 - `direction` — `'ltr'`, `'rtl'`, or `'locale'` for the language of the app; `navigation.setDirection` changes it.
 

package/docs-md/guides/cli.md

@@ -107,7 +107,7 @@ A new app doesn't have the package yet, so `init` runs through the package's nam
 
 ## setup
 
-Sets the app you have up for the navigation: the native entry points of both platforms, `index.js`, a new `Navigation.ts` with your `App` as the first screen, and `navigation-env.d.ts`, the [typed commands](../start/installation#typed-commands). Each change and why: [What setup changes, and why](../start/installation#why-native).
+Sets the app you have up for the navigation: the native entry points of both platforms, `index.js`, a new `Navigation.ts` with your `App` as the first screen, `navigation-env.d.ts`, the [typed commands](../start/installation#typed-commands). It also wraps `metro.config.js` in `withApexNavigation`, for [Fast Refresh](../start/installation#fast-refresh). Each change and why: [What setup changes, and why](../start/installation#why-native).
 
 ```bash
 npx apex-navigation setup
@@ -169,6 +169,8 @@ npx apex-navigation doctor --fix
 | `--fix` | Makes the fixes the CLI has, for errors and warnings alike: `setup`, `links`, `icons`, `codegen` and `pod install`, asking before each. It needs a terminal to ask in. |
 | `--json` | `{ ok, checks: [{ group, title, status, detail, fix }] }`; `status` is `ok`, `warn`, `error` or `info`, and `fix` is `{ label, run }`, where `run` names the command `--fix` runs. Not with `--fix`. |
 
+It warns under Fast Refresh when the app's `metro.config.js` doesn't use `withApexNavigation`; the fix is `setup`.
+
 It exits with 1 when a check finds an error; warnings leave it at 0.
 
 ## info
@@ -311,7 +313,7 @@ Each file and why: [What the command writes](./splash-screen#files).
 - **The settings** go into `package.json`, under `apexNavigation.splash`. An option given replaces its saved value; to drop the dark logo or color, remove `darkLogo` or `darkBackground` there and run the command again.
 - **A logo whose corners leave the circle** of Android 12's splash icon, 192 dp, gets a warning: Android cuts them. Make `--logo-width` smaller, or give the logo room around it.
 - **A file it can't change** is listed as `manual`, with the change to make: an app without `Images.xcassets` next to `Info.plist`, a manifest whose `MainActivity` and `<application>` have no theme to go over.
-- **`Info.plist` with `UILaunchScreen`** as well gets a warning: remove that dictionary, so that iOS shows the storyboard.
+- **`Info.plist` with `UILaunchScreen`** as well gets a warning: iOS shows that dictionary instead of the storyboard, so remove it.
 - **Its errors** in the JSON: `splash-settings` for a setting it can't take, `splash-image` for a logo it can't read or that doesn't fit (too tall at its width, a dark logo of other proportions), and `sharp-missing`, as for `icons`.
 
 `doctor` checks the splash in the App group:
@@ -320,7 +322,6 @@ Each file and why: [What the command writes](./splash-screen#files).
 | --- | --- |
 | Splash | The files of iOS or Android aren't made from the settings in `package.json`: changed by hand, made on one platform only, or by an older version of the command. Or the settings themselves are wrong, such as a logo that isn't there. |
 | Splash logo | The logo's corners leave Android 12's circle. |
-| Launch screen | Without settings: `Info.plist` has `UILaunchScreen` and no storyboard. iOS shows it at launch, but the navigation can only keep a storyboard on screen, so an empty window shows between it and the first screen. |
 
 Each warning names its fix, such as `npx apex-navigation splash`; `--fix` leaves these to you. What the user sees, and a splash of your own after the native one: [Splash screen](./splash-screen).
 

package/docs-md/guides/deep-links.md

@@ -522,57 +522,39 @@ The launch link is read once per launch of the app, and the cases differ:
 
 ## An app with its own scene delegate
 
-(iOS) `ANNAppDelegate` gives the app's scene `ANNSceneDelegate`, which moves the navigation's window into the scene and passes the scene's links on. An app whose `Info.plist` names a scene delegate of its own does both itself. The links that launched the app come with the options of `scene(_:willConnectTo:options:)`, and they count as the launch link when they're passed on in that same call, with the window moved into the scene:
+(iOS) `ANNAppDelegate` gives the app's scene `ANNSceneDelegate`, which moves the navigation's window into the scene and passes the scene's links on: to the app delegate's methods, then to `Linking`. An app whose `Info.plist` names a scene delegate of its own, as React Native 0.88's template does, extends `ANNSceneDelegate`; a method it overrides calls `super`:
 
 ```swift
 import ApexNavigation
 import UIKit
 
-class SceneDelegate: UIResponder, UIWindowSceneDelegate {
-  var window: UIWindow?
-
-  func scene(
+class SceneDelegate: ANNSceneDelegate {
+  override func scene(
     _ scene: UIScene,
     willConnectTo session: UISceneSession,
     options connectionOptions: UIScene.ConnectionOptions
   ) {
-    guard let windowScene = scene as? UIWindowScene else { return }
-    window = ApexNavigation.attach(to: windowScene)
-    // The links that launched the app: passed on in this same
-    // call, so the first root can come from one of them.
-    for context in connectionOptions.urlContexts {
-      openLink(context.url)
-    }
-    for activity in connectionOptions.userActivities {
-      if let url = activity.webpageURL { openLink(url) }
-    }
+    // Moves the window into the scene and passes on the links
+    // that launched the app.
+    super.scene(scene, willConnectTo: session, options: connectionOptions)
+    window?.tintColor = .systemIndigo
   }
 
-  // Links while the app runs.
-  func scene(
+  override func scene(
     _ scene: UIScene,
     openURLContexts URLContexts: Set<UIOpenURLContext>
   ) {
-    for context in URLContexts {
-      openLink(context.url)
-    }
-  }
-
-  func scene(
-    _ scene: UIScene,
-    continue userActivity: NSUserActivity
-  ) {
-    if let url = userActivity.webpageURL { openLink(url) }
-  }
-
-  private func openLink(_ url: URL) {
-    let app = UIApplication.shared.delegate as? ANNAppDelegate
-    app?.dispatchDeepLinkURL(url)
+    print("Opened:", URLContexts.map(\.url))
+    super.scene(scene, openURLContexts: URLContexts)
   }
 }
 ```
 
-`ApexNavigation.attach(to:)` is `attachToWindowScene:` in Objective-C.
+`super` passes each link on with its scene: React Native 0.88 and newer take a scene's links only with it. `setup` turns the scene delegate of React Native 0.88's template into `class SceneDelegate: ANNSceneDelegate {}`.
+
+A scene delegate that extends another class calls `ApexNavigation.attach(to:)` (`attachToWindowScene:` in Objective-C) in `scene(_:willConnectTo:options:)` and passes the URLs to `dispatchDeepLinkURL(_:)` of the app delegate.
+
+A link the app dispatches itself with `dispatchDeepLinkURL(_:)`, such as the link of a push notification, comes with no scene. Where React Native's `Linking` doesn't take it from the native side (React Native 0.88 and newer, in an app with a scene delegate), the navigation hands it to `Linking` from JavaScript, as a `url` event like any other.
 
 ## Testing
 

package/docs-md/help/glossary.md

@@ -194,7 +194,7 @@ A description of what the platform shows: a screen name, or a tree of [builders]
 
 ### Liquid Glass
 
-(iOS) 26: the see-through material of the bars, the tab bar and the buttons. A background color in the options takes it away. More: [The background and the border](../screen-ui/top-bar#background).
+(iOS) 26: the see-through material of the bars, the tab bar and the buttons; the app gets this look, "the glass design", unless it is in the compatibility mode (`UIDesignRequiresCompatibility` in Info.plist), which keeps the look of before iOS 26. A background color in the options takes the glass away. More: [The glass design and the compatibility mode](../screen-ui/top-bar#glass-design), [The background and the border](../screen-ui/top-bar#background).
 
 ### listeners
 
@@ -266,7 +266,7 @@ Two screens shown as one entry of a stack: the primary, whose bar shows, and the
 
 ### Popover
 
-(iPadOS) A modal that points at the bar button or the view that opened it. On iPhone it becomes a sheet; on Android the modal covers the screen. More: [A popover](../containers/modals#popover).
+(iPadOS) A modal that points at the bar button or the view that opened it. On iPhone and on Android it becomes a sheet. More: [A popover](../containers/modals#popover).
 
 ### Presentation
 
@@ -314,7 +314,7 @@ An entry of `linking.routes`: a path pattern, such as `'user/:userId'`, and what
 
 ### Safe area
 
-The part of the screen that nothing covers: not the bars, the status bar, the cutout or the home indicator. The navigation keeps every screen in it by default, measured on the native side. More: [The safe area](../screen-ui/system-ui#safe-area).
+The part of the screen that nothing covers: not the bars, the status bar, the cutout or the home indicator. The navigation keeps every screen's top and sides in it by default, and the bottom is free, measured on the native side. More: [The safe area](../screen-ui/system-ui#safe-area).
 
 ### Screen
 
@@ -370,7 +370,7 @@ The system bar at the top of the screen, with the time and the battery. Each scr
 
 ### Swipe back
 
-(iOS) The swipe from the left edge, and on iOS 26 from the content, that goes back following the finger. `popGesture` narrows it or turns it off. More: [The swipe back](../screen-ui/back-and-gestures#swipe).
+(iOS) The swipe from the left edge, and on iOS 26 from the content, that goes back following the finger. `popGesture` narrows it or turns it off. (Android) 14+ The swipe of the system back shows the pop under the finger, and the user can stop halfway. More: [The swipe back](../screen-ui/back-and-gestures#swipe).
 
 ### System back
 

package/docs-md/help/troubleshooting.md

@@ -73,13 +73,30 @@ Options set in `static options` on a component no longer apply.
 
 **Fix:** move them into `defineScreen({ component, options })`; the object carries over as it is. More: [Options next to the screen](../migration/from-react-native-navigation#options).
 
+### The Android app crashes at start: React Native isn't loaded
+
+(Android) The app closes at once with `NavigationApplication needs React Native loaded first`, and `doctor` reports `MainApplication.kt doesn't call loadReactNative(this) in onCreate`.
+
+**Why:** `NavigationApplication` leaves the load of React Native to the template's `loadReactNative(this)`, which loads it as the app's Gradle files say (the New Architecture, edge-to-edge). Without the call nothing loads it.
+
+**Fix:** keep the template's `onCreate`, or run `npx apex-navigation setup`, which adds it:
+
+```kotlin
+override fun onCreate() {
+  super.onCreate()
+  loadReactNative(this)
+}
+```
+
+More: [Android files](../start/installation#android-files).
+
 ### The Android app crashes at start: React Native loads twice
 
-(Android) The app closes at once, and `doctor` reports `MainApplication.kt calls loadReactNative(this), NavigationApplication loads it too`.
+(Android) The app closes at once, and `doctor` reports `MainApplication.kt loads React Native itself … next to loadReactNative(this)`.
 
-**Why:** `NavigationApplication` loads React Native itself, and a second load crashes the app.
+**Why:** the application loads React Native on its own as well, with `SoLoader.init` or the New Architecture's entry point (`load()`, as apps from react-native-navigation have it), and a second load crashes the app.
 
-**Fix:** remove the `loadReactNative(this)` call from `MainApplication.kt`. More: [Android files](../start/installation#android-files).
+**Fix:** keep only `loadReactNative(this)` in `onCreate`; `npx apex-navigation setup` removes the other load. More: [Android files](../start/installation#android-files).
 
 ### doctor warns about the JDK
 
@@ -215,9 +232,9 @@ A signed-in user sees Login for a moment, then the app.
 
 (iOS) Between the launch screen and the first screen, the window is empty for a moment.
 
-**Why:** the launch screen is made with the `UILaunchScreen` dictionary of `Info.plist`, not a storyboard. The navigation keeps a copy of a storyboard on screen until the first root, and can't make one of the dictionary. `doctor` warns about it under Launch screen.
+**Why:** the app has no launch screen the navigation can copy: `Info.plist` names no storyboard and has no `UILaunchScreen` dictionary (or `UILaunchScreens` default), and no legacy launch images.
 
-**Fix:** run `npx apex-navigation splash`, or name a storyboard in `UILaunchStoryboardName` and remove `UILaunchScreen`. More: [Make the native splash](../guides/splash-screen#command).
+**Fix:** run `npx apex-navigation splash`, or name a storyboard in `UILaunchStoryboardName`. More: [Make the native splash](../guides/splash-screen#command).
 
 ### Android brings the app back without its pushed screens
 
@@ -422,6 +439,27 @@ return (
 
 More: [Hiding the bar](../screen-ui/top-bar#hide), [The large title](../screen-ui/top-bar#large-title).
 
+### The last rows of a list sit under the home indicator or the tab bar
+
+The last row of a list can't be scrolled above the home indicator, the navigation bar or the tab bar.
+
+**Why:** the bottom edge of a screen is not padded by default, so the content goes down to the edge, under the system and under the tab bar or toolbar.
+
+**Fix:** add the bottom inset to the padding of the list; on (iOS) `contentInsetAdjustmentBehavior="automatic"` does it by itself. Or have the screen pad it: list every edge the screen keeps (`safeArea('top', 'left', 'right', 'bottom')`), since listed edges replace the default. An explicit `'top'` also keeps the top under a large title, so a large-title screen usually pads its list with `insets.bottom` instead:
+
+```tsx
+const insets = useSafeAreaInsets();
+return (
+  <FlatList
+    data={items}
+    contentContainerStyle={{ paddingBottom: 16 + insets.bottom }}
+    renderItem={renderItem}
+  />
+);
+```
+
+More: [The safe area](../screen-ui/system-ui#safe-area).
+
 ### A pick in the overflow menu does nothing
 
 The user picks Export in the overflow menu, and nothing happens.
@@ -526,7 +564,7 @@ More: [Ask before changes are lost](../flows/forms-in-a-modal#prevent).
 
 A sheet with the detent `'content'` isn't as tall as what it shows.
 
-**Why:** a screen that fills its parent (`flex: 1`) has no height of its own to measure. On (Android) `'content'` stops at half the height, as the Material sheet has no height of its content.
+**Why:** a screen that fills its parent (`flex: 1`) has no height of its own to measure.
 
 **Fix:** give the content of the screen its natural height, without `flex: 1`. More: [A sheet as tall as its content](../flows/bottom-sheets#content).
 

package/docs-md/index.json

@@ -87,6 +87,10 @@
         "heading": "JavaScript files",
         "anchor": "js-files"
       },
+      {
+        "heading": "Fast Refresh",
+        "anchor": "fast-refresh"
+      },
       {
         "heading": "Typed commands",
         "anchor": "typed-commands"
@@ -276,6 +280,10 @@
         "heading": "Options",
         "anchor": "options"
       },
+      {
+        "heading": "Fast Refresh",
+        "anchor": "fast-refresh"
+      },
       {
         "heading": "The life of a screen",
         "anchor": "lifecycle"
@@ -731,6 +739,10 @@
         "heading": "How it looks",
         "anchor": "look"
       },
+      {
+        "heading": "When the menus are created",
+        "anchor": "attach"
+      },
       {
         "heading": "Where the swipe is off",
         "anchor": "swipe"
@@ -856,6 +868,10 @@
         "heading": "What the top bar is",
         "anchor": "what"
       },
+      {
+        "heading": "The glass design and the compatibility mode",
+        "anchor": "glass-design"
+      },
       {
         "heading": "The title",
         "anchor": "title"
@@ -974,6 +990,14 @@
         "heading": "The system back of Android",
         "anchor": "system-back"
       },
+      {
+        "heading": "The preview of a pop",
+        "anchor": "pop-preview"
+      },
+      {
+        "heading": "The preview of a sheet closing",
+        "anchor": "sheet-preview"
+      },
       {
         "heading": "Back to the home screen",
         "anchor": "system-animation"
@@ -1171,9 +1195,17 @@
         "anchor": "theme-options"
       },
       {
-        "heading": "Android's colors",
+        "heading": "Android's theme",
         "anchor": "android"
       },
+      {
+        "heading": "An app with an AppCompat or MaterialComponents theme",
+        "anchor": "android-other-themes"
+      },
+      {
+        "heading": "Fonts and shapes",
+        "anchor": "android-fonts-shapes"
+      },
       {
         "heading": "The context",
         "anchor": "context"
@@ -1323,6 +1355,18 @@
         "heading": "Animations of your own",
         "anchor": "custom"
       },
+      {
+        "heading": "The swipe back with a pop of your own",
+        "anchor": "custom-swipe"
+      },
+      {
+        "heading": "The top bar",
+        "anchor": "custom-bar"
+      },
+      {
+        "heading": "When the user reduces motion",
+        "anchor": "reduce-motion"
+      },
       {
         "heading": "Which to pick",
         "anchor": "which"
@@ -1402,6 +1446,10 @@
         "heading": "Typed commands",
         "anchor": "typed-commands"
       },
+      {
+        "heading": "Fast Refresh",
+        "anchor": "fast-refresh"
+      },
       {
         "heading": "UIKit and Android views",
         "anchor": "imperative"
@@ -3944,6 +3992,10 @@
         "heading": "A screen ignores its static options",
         "anchor": "static-options"
       },
+      {
+        "heading": "The Android app crashes at start: React Native isn't loaded",
+        "anchor": "not-loaded"
+      },
       {
         "heading": "The Android app crashes at start: React Native loads twice",
         "anchor": "loads-twice"
@@ -4080,6 +4132,10 @@
         "heading": "The first rows of a list hide under the top bar",
         "anchor": "rows-under-bar"
       },
+      {
+        "heading": "The last rows of a list sit under the home indicator or the tab bar",
+        "anchor": "rows-under-bottom"
+      },
       {
         "heading": "A pick in the overflow menu does nothing",
         "anchor": "overflow-pick"

package/docs-md/migration/from-expo-router.md

@@ -425,7 +425,7 @@ The route patterns of `linking` are typed too: in `'user/:userId'` the handler g
 | `useNavigation` | `useNavigation`: the commands of this screen. |
 | `useIsFocused` | `useIsFocused`. |
 
-Every screen keeps clear of the bars by itself, so a `SafeAreaView` around the content can go; `useSafeAreaInsets` of this package gives what still covers the content, 0 on an edge the screen keeps clear, so padding by it never comes twice. More: [Lifecycle and events](../fundamentals/lifecycle-and-events#hooks), [The safe area](../screen-ui/system-ui#safe-area).
+The bottom edge of a screen is not padded by default, as with `react-native-safe-area-context`: a list adds `useSafeAreaInsets().bottom` to its bottom padding, or the screen lists `'bottom'` in `safeArea(…)`. Every screen keeps its top and sides clear of the bars by itself, so a `SafeAreaView` around the content can go; `useSafeAreaInsets` of this package gives what still covers the content, 0 on an edge the screen keeps clear, so padding by it never comes twice. More: [Lifecycle and events](../fundamentals/lifecycle-and-events#hooks), [The safe area](../screen-ui/system-ui#safe-area).
 
 ## What has no direct equivalent
 

package/docs-md/migration/from-react-native-navigation.md

@@ -140,7 +140,7 @@ Each piece of `react-native-navigation`, and what takes its place. The [steps](#
 | `AppRegistry` left out of `index.js` | `AppRegistry.registerComponent(name, Navigation)` of the package. |
 | `RNNAppDelegate`, `import ReactNativeNavigation` | `ANNAppDelegate`, `import ApexNavigation`. |
 | `com.reactnativenavigation.*` | `dev.apexnative.navigation.*`. |
-| `NavigationReactNativeHost` in `MainApplication` | The template's `reactHost`; `NavigationApplication` loads React Native itself. |
+| `NavigationReactNativeHost` in `MainApplication` | The template's `reactHost`, and its `loadReactNative(this)` in `onCreate`. |
 | `RNNKotlinVersion` in `android/build.gradle` | Nothing: the library reads `kotlinVersion`. |
 
 ## The move, step by step
@@ -212,11 +212,12 @@ import dev.apexnative.navigation.NavigationActivity
 class MainActivity : NavigationActivity()
 ```
 
-The application drops `NavigationReactNativeHost` and keeps the `reactHost` of the React Native template. `NavigationApplication` loads React Native in its `onCreate`, so the app doesn't call `loadReactNative` again.
+The application drops `NavigationReactNativeHost` and keeps the `reactHost` of the React Native template. react-native-navigation loaded React Native itself; the navigation leaves it to the template's `loadReactNative(this)` in `onCreate`, which `migrate` adds.
 
 ```kotlin
 import com.facebook.react.PackageList
 import com.facebook.react.ReactHost
+import com.facebook.react.ReactNativeApplicationEntryPoint.loadReactNative
 import com.facebook.react.defaults.DefaultReactHost.getDefaultReactHost
 import dev.apexnative.navigation.NavigationApplication
 
@@ -227,6 +228,11 @@ class MainApplication : NavigationApplication() {
       packageList = PackageList(this).packages,
     )
   }
+
+  override fun onCreate() {
+    super.onCreate()
+    loadReactNative(this)
+  }
 }
 ```
 
@@ -773,7 +779,7 @@ The whole list of options, with what each does on each platform: [Where each opt
 | `react-native-navigation` | What to do here |
 | --- | --- |
 | `Navigation.updateProps` | Props are given once. What changes goes in the screen's state, or the app's context or store. |
-| `Navigation.constants()` | `useSafeAreaInsets()` of a screen: what the bars and the system still cover of its content, measured for that screen; 0 on an edge the screen keeps clear itself. A screen that needs the height of its top bar goes under it (`drawBehind`) and reads the top inset. |
+| `Navigation.constants()` | `useSafeAreaInsets()` of a screen (the bottom is not padded by default: a list adds `insets.bottom` to its bottom padding): what the bars and the system still cover of its content, measured for that screen; 0 on an edge the screen keeps clear itself. A screen that needs the height of its top bar goes under it (`drawBehind`) and reads the top inset. |
 | `componentId` in a class component | Hooks need a function component: wrap the class in one that passes `useNavigation()` down as a prop. |
 | `topTabs` | No container for it. A pager component inside one screen does the same. |
 | `Navigation.handleDeepLink(url)` | Run the command the route would run, such as `navigation.push('Profile', { props })`. |

package/docs-md/migration/from-react-navigation.md

@@ -64,7 +64,7 @@ The left side renders the navigation. The right side describes it: `createNaviga
 | **State** | A React object: routes, params, indexes. | The platform's. JavaScript hears events and reads a small state: the screen the user sees and the selected tab. |
 | **Params** | `route.params`, changed with `setParams`. | Props of the component, given by the command that shows the screen. |
 | **Options** | Props of a screen, with React elements for the header. | Data the platform reads before the screen shows. A component in a bar is registered in `screens`, as a screen is. |
-| **Safe area** | `SafeAreaView` or a safe area library. | Every screen keeps clear of the bars by itself. See [The safe area](../screen-ui/system-ui#safe-area). |
+| **Safe area** | `SafeAreaView` or a safe area library. | Every screen keeps its top and sides clear of the bars by itself; the bottom is yours (`insets.bottom`). See [The safe area](../screen-ui/system-ui#safe-area). |
 
 Because options are data, a title is there from the first frame, and because the state is the platform's, a move renders nothing in React by itself. More on the model: [Introduction](../start/introduction#models).
 
@@ -605,7 +605,7 @@ Once no file imports them, remove `@react-navigation/*`, and `react-native-scree
 npx apex-navigation doctor
 ```
 
-Screens wrapped in `SafeAreaView` can drop it, since every screen keeps clear of the bars by itself; `useSafeAreaInsets` of this package gives what still covers the content of the screen. Code such as `paddingTop: insets.top` keeps working with it: on an edge the screen keeps clear the inset is 0, so nothing is padded twice.
+The bottom edge of a screen is not padded by default, as with `react-native-safe-area-context`: a list adds `useSafeAreaInsets().bottom` to its bottom padding, or the screen lists `'bottom'` in `safeArea(…)`. Screens wrapped in `SafeAreaView` can drop it, since every screen keeps its top and sides clear of the bars by itself; `useSafeAreaInsets` of this package gives what still covers the content of the screen. Code such as `paddingTop: insets.top` keeps working with it: on an edge the screen keeps clear the inset is 0, so nothing is padded twice.
 
 ## What has no direct equivalent
 

package/docs-md/screen-ui/back-and-gestures.md

@@ -17,7 +17,7 @@ On iOS the back button of Details reads "Inbox". This page answers:
 
 1. [The ways back](#ways) on each platform.
 2. [The back button](#back-button): [its title](#title) and [its look](#look).
-3. [The swipe back](#swipe) of iOS, and [the system back](#system-back) of Android.
+3. [The swipe back](#swipe) of both platforms, and [the system back](#system-back) of Android.
 4. [How to keep the user on a screen](#prevent) with unsaved changes.
 
 ## The ways back
@@ -85,7 +85,9 @@ export const MapScreen = defineScreen({
 | `'edge'` | From the edge only: a swipe on the content stays with the content. |
 | `false` | Off. The back button still works. |
 
-(Android) The system back swipes from either edge; the app doesn't change it.
+(iOS) The swipe slides the screen out the system's way, also for a screen that leaves with a move of its own. `animations.pop.interactive` plays that move under the finger instead: [the swipe back with a pop of your own](../architecture/transitions#custom-swipe).
+
+(Android) The swipe is the system's back, from either edge, and `popGesture` doesn't apply to it. On Android 14+ it shows the pop before the user lets go: both screens shrink, the screen under comes in behind a dim, and the screen on top follows the finger. The user can stop halfway and stay, as on iOS. On Android 13 and older the screen pops when the swipe ends. When the preview shows and when it doesn't: [the preview of a pop](#pop-preview).
 
 ## The system back of Android
 
@@ -100,6 +102,37 @@ export const MapScreen = defineScreen({
 | The first screen of a tab | What `Tabs().backBehavior(…)` says: leave the app, go to the first tab, or to the tab before. See [Back on Android](../containers/tabs#back). |
 | The first screen of the app | Leaves the app, as every Android app does, with the system's own animation ([below](#system-animation)). `usePreventLeave` doesn't hold it; to ask first, see [Asking before the user leaves the app](/api/back-and-gestures/usePreventLeave#leaving-the-app). |
 
+### The preview of a pop
+
+(Android) 14+ The back gesture on a pushed screen shows where it goes before the user lets go, as the system does between apps' screens: the screen shrinks toward the side of the swipe with rounded corners and follows the finger, and the screen under it shows behind it, dimmed, with its own bar. Letting go pops the screen; swiping back cancels, and the screen grows back into place.
+
+The preview shows when back pops the screen with the default transition. It doesn't when back does something else first, or when the app takes it: a menu or a search that closes, a screen that holds back (`hardwareBackButton.popStackOnPress: false`, a [`BackHandler` listener](#back-handler), `usePreventLeave`), or a pop with an animation of its own (`animations.pop`). On Android 13 and older the screen pops when the swipe ends.
+
+`animations.pop.preview: false` turns the preview off for a screen: the gesture shows nothing, and the screen pops when the user lets go, as on Android 13. It is read from the screen that goes, so the app's `options` turn it off everywhere:
+
+```ts
+defineScreen({
+  component: Checkout,
+  options: { animations: { pop: { preview: false } } },
+});
+```
+
+iOS ignores it: the swipe back there is UIKit's, or the pop's own move under the finger with `animations.pop.interactive`.
+
+### The preview of a sheet closing
+
+(Android) 14+ The back gesture over a modal sheet that back would close shows the close before the user lets go: the sheet shrinks a little toward the bottom as the swipe goes on, and the dimming behind it follows. Letting go slides the sheet down and closes it exactly as a swipe down does, with the same events and the same answers (`onDismiss`, `modalDismissed`). Swiping back cancels, and the sheet returns.
+
+There is no preview, and the sheet closes when the swipe ends (at once for a button press), when:
+
+- the sheet has several detents and is above its lowest one: the sheet can be hidden only at the lowest detent, so back closes it right there, as before;
+- its screen holds back: `hardwareBackButton.dismissModalOnPress: false`, a [`BackHandler` listener](#back-handler), `usePreventLeave`;
+- a screen pushed inside the sheet pops first: that pop keeps [its own preview](#pop-preview);
+- the modal can't be swiped down (`swipeToDismiss: false`);
+- the sheet is the only modal over no root.
+
+On Android 13 and older the sheet closes when the swipe ends. iOS keeps UIKit's sheet: nothing changes there.
+
 ### Back to the home screen
 
 (Android) On the first screen of the app, with nothing left to go back to, the navigation leaves the back to the system. The system then plays its predictive back animation: as the user swipes, the app shrinks and the home screen shows behind it, and the user can still change their mind halfway. The system decides this as the swipe starts, so the navigation takes the back only while it has something to do with it: a screen to pop, a modal, a menu or a search to close, a tab to go to (`backBehavior`), or a [`BackHandler` listener](#back-handler) of the app.
@@ -116,6 +149,17 @@ Without it, back on the first screen still leaves the app, at once. See [What se
 
 With the animation on, the system leaves the app itself: an `invokeDefaultOnBackPressed` of the app's `MainActivity` (such as `moveTaskToBack(true)`) isn't called on the first screen. Without it, and before Android 13, the back goes through the activity as before.
 
+`hardwareBackButton.systemAnimation: false` keeps the back in the app on the first screen too, so the system plays no animation there: the gesture shows nothing, and on release the press goes to the [`BackHandler` listeners](#back-handler), then to the activity's own back, `invokeDefaultOnBackPressed` included. It is read from the screen back acts on; for the whole app, set it in the app's `options`:
+
+```ts
+createNavigation({
+  // …
+  options: { hardwareBackButton: { systemAnimation: false } },
+});
+```
+
+iOS ignores it.
+
 ### Handling back yourself: BackHandler
 
 (Android) React Native's `BackHandler` works on every screen, as in any React Native app. A listener runs before the navigation's own back: returning `true` takes the press, `false` passes it on to the next listener, then to the navigation.

package/docs-md/screen-ui/bar-buttons.md

@@ -64,8 +64,8 @@ The look and the state of a button:
 | --- | --- |
 | `color` | The color of this button. |
 | `enabled: false` | Dimmed; a press does nothing. |
-| `style: 'prominent'` | (iOS) The main action, such as Done or Send. On iOS 26 a filled capsule in the button's `color`; before, a bold title. |
-| `group` | (iOS) 26: buttons with the same group share one glass capsule; each other button has a capsule of its own. |
+| `style: 'prominent'` | (iOS) The main action, such as Done or Send. With the glass design a filled capsule in the button's `color`; without it, a bold title. See [the glass design](./top-bar#glass-design). |
+| `group` | (iOS) Glass design: buttons with the same group share one glass capsule; each other button has a capsule of its own. |
 | `badge` | (iOS) 26: a number, a short text, or `true` for a dot. |
 | `toggle`, `selected` | (iOS) A button that switches on and off at each tap; the press carries the new state as `selected`. |
 
@@ -148,7 +148,7 @@ useNavigationButton('sort-name', () => setSort('name'));
 | Platform | The menu |
 | --- | --- |
 | (iOS) | The system menu, with SF Symbols, submenus and a check on the picked item. |
-| (Android) | The Material popup menu under the button, with the same items, without the `title` of the menu. |
+| (Android) | The Material popup menu under the button, with the same items, without the `title` of the menu. `topBar.menuBackgroundColor` and `topBar.menuTextColor` color it and "⋮"; without them it takes the bar's color and the title's color, in light and dark mode. |
 
 ## The overflow menu
 
@@ -248,7 +248,7 @@ s.rightButtons({
 });
 ```
 
-The bar sends no press for it: the component's own `onPress` is the press. On (iOS) 26 it has no glass capsule; `hideSharedBackground: false` puts it on one. On (Android) `component.width` and `height` size it.
+The bar sends no press for it: the component's own `onPress` is the press. On (iOS) with the glass design it has no glass capsule; `hideSharedBackground: false` puts it on one. On (Android) `component.width` and `height` size it.
 
 ## Buttons that change
 
@@ -273,7 +273,7 @@ function NewNote() {
 
 The options are built on each render and applied before the screen paints when they changed, so the bar never lags behind the state. `onPress` sees the state of the same render. A full form in a modal, with Cancel and Save, is walked through in [Forms in a modal](../flows/forms-in-a-modal).
 
-On (iOS) `animateRightButtons` and `animateLeftButtons` fade the new buttons in. On iOS 26 buttons that share a capsule (several with one `group`) change at once: UIKit has no animation for groups of buttons.
+On (iOS) `animateRightButtons` and `animateLeftButtons` fade the new buttons in. With the glass design buttons that share a capsule (several with one `group`) change at once: UIKit has no animation for groups of buttons.
 
 ## Buttons on iPhone Duo
 

package/docs-md/screen-ui/search.md

@@ -171,7 +171,7 @@ The component gets the search events itself, with `useSearchBar`, as a screen of
 
 | Platform | The results screen |
 | --- | --- |
-| (iOS) | Covers the whole screen, under the search field and to the bottom edge, so its background fills it. It keeps its content clear of the bar itself: a list with `contentInsetAdjustmentBehavior="automatic"`, other content with `useSafeAreaInsets`. |
+| (iOS) | Covers the whole screen, under the search field and to the bottom edge, so its background fills it. It keeps its content clear of the bar itself: a list with `contentInsetAdjustmentBehavior="automatic"`, other content with `useSafeAreaInsets`. The results screen has no padding of its own. |
 | (Android) | The search opens over the whole screen, the field at the top and the component under it. |
 
 ## In the toolbar