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

package/cli/setup/steps/sceneDelegate.js

@@ -0,0 +1,108 @@
+// @ts-check
+'use strict';
+
+/** @typedef {import('./types').StepResult} StepResult */
+
+const HOW_TO = `Let ANNSceneDelegate take the app's scene: it moves the navigation's window into the scene and passes the
+scene's links to the app delegate. React Native starts in ANNAppDelegate, not here.
+
+  import ApexNavigation
+  import UIKit
+
+  class SceneDelegate: ANNSceneDelegate {}
+
+A scene delegate of the app's own calls ApexNavigation.attach(to:) in scene(_:willConnectTo:options:) instead, as the
+deep links guide shows.`;
+
+const SET_UP = `import ApexNavigation
+import UIKit
+
+/// ANNSceneDelegate moves the navigation's window into the app's scene and passes the scene's links to the app delegate.
+class SceneDelegate: ANNSceneDelegate {}
+`;
+
+// React Native 0.88's template, without its spaces: the scene delegate that makes React Native's factory and starts
+// it in the scene's window.
+const TEMPLATE = `import React
+import React_RCTAppDelegate
+import ReactAppDependencyProvider
+import UIKit
+
+class SceneDelegate: RCTDefaultReactNativeFactoryDelegate, UIWindowSceneDelegate {
+  var window: UIWindow?
+  var reactNativeFactory: RCTReactNativeFactory?
+
+  func scene(
+    _ scene: UIScene,
+    willConnectTo session: UISceneSession,
+    options connectionOptions: UIScene.ConnectionOptions
+  ) {
+    guard let windowScene = scene as? UIWindowScene else {
+      return
+    }
+
+    dependencyProvider = RCTAppDependencyProvider()
+    reactNativeFactory = RCTReactNativeFactory(delegate: self)
+    window = UIWindow(windowScene: windowScene)
+
+    #if DEBUG
+    let devMenuConfiguration = RCTDevMenuConfiguration(
+      devMenuEnabled: true,
+      shakeGestureEnabled: true,
+      keyboardShortcutsEnabled: true
+    )
+    reactNativeFactory?.devMenuConfiguration = devMenuConfiguration
+    #endif
+
+    reactNativeFactory?.startReactNative(
+      withModuleName: "",
+      in: window,
+      connectionOptions: connectionOptions
+    )
+  }
+
+  func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
+    RCTLinkingManager.scene(scene, openURLContexts: URLContexts)
+  }
+
+  func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
+    RCTLinkingManager.scene(scene, continue: userActivity)
+  }
+
+  override func bundleURL() -> URL? {
+    #if DEBUG
+    RCTBundleURLProvider.sharedSettings().jsBundleURL(forBundleRoot: "index")
+    #else
+    Bundle.main.url(forResource: "main", withExtension: "jsbundle")
+    #endif
+  }
+}
+`;
+
+/**
+ * The text without its spaces and the app's name, to compare with the template.
+ * @param {string} text
+ */
+function shape(text) {
+  return text.replace(/withModuleName:\s*"[^"]*"/, 'withModuleName:""').replace(/\s+/g, '');
+}
+
+/**
+ * SceneDelegate.swift of React Native 0.88 and newer: the scene delegate becomes an ANNSceneDelegate, since
+ * ANNAppDelegate starts React Native and owns the window. Only the template's file changes; one with code of the app's
+ * own is changed by hand.
+ * @param {string} text
+ * @returns {StepResult}
+ */
+function planSceneDelegate(text) {
+  if (
+    /class\s+\w+\s*:\s*ANNSceneDelegate\b/.test(text) ||
+    /\bApexNavigation\.attach\s*\(/.test(text)
+  )
+    return { status: 'done', note: 'already set up' };
+  if (shape(text) !== shape(TEMPLATE))
+    return { status: 'manual', note: 'changed by hand, see below', howTo: HOW_TO };
+  return { status: 'change', next: SET_UP, note: 'ANNSceneDelegate' };
+}
+
+module.exports = { planSceneDelegate };

package/cli/splash/index.js

@@ -88,7 +88,9 @@ async function splash({
   }
   const plist = project.infoPlist && fs.readFileSync(project.infoPlist, 'utf8');
   if (plist?.includes('<key>UILaunchScreen</key>')) {
-    command.warn('Info.plist has UILaunchScreen too: remove it, so that iOS shows the storyboard.');
+    command.warn(
+      'Info.plist has UILaunchScreen too: iOS shows it instead of the storyboard; remove it, so that iOS shows the storyboard.'
+    );
   }
   return command.apply(
     [

package/cli/upgrade/changelog.js

@@ -4,8 +4,8 @@
 const { compare } = require('./versions');
 
 /**
- * What changed between two versions, from a CHANGELOG.md as release-it writes it (conventional changelog: a heading
- * per version, `## [1.2.0](…) (date)`, and in it `### BREAKING CHANGES`, `### Features`, `### Bug Fixes`).
+ * What changed between two versions, from a CHANGELOG.md as release-please writes it (conventional changelog: a
+ * heading per version, `## [1.2.0](…) (date)`, and in it `### ⚠ BREAKING CHANGES`, `### Features`, `### Bug Fixes`).
  * @typedef {{ breaking: { version: string; text: string }[]; notes: { version: string; text: string }[] }} Notes
  */
 

package/docs-md/architecture/native-screens.md

@@ -255,6 +255,10 @@ A wrong name or a missing prop is an error of the compiler, not of the app at ru
 - **Which are left out:** a screen with a required prop that is a function, and one with a prop whose type has no native form (see [Types](#types)). `codegen` names each in a warning. Native code still opens it by its name, `push("Settings", props: [:])`, with its props as a plain dictionary or map.
 - **After a change** of the screens or their props, run `codegen` again; `doctor` says when the generated code is behind.
 
+## Fast Refresh
+
+`nativeScreen` returns a component that runs `useProps`. An edit of the hook or of the options applies in place, with the app running. A change of the native name, or adding or removing `useProps`, restarts the app (a reload).
+
 ## UIKit and Android views
 
 A screen of UIKit or Android views gets the same `screen`, and follows its props as they change:

package/docs-md/architecture/theme-and-context.md

@@ -5,7 +5,7 @@ Two things every screen shares: the theme, the colors of the bars and background
 Every screen of an app shares a look and a few facts: the colors of the bars, the signed-in user, the language. The navigation keeps both for every screen. The **theme** is the colors of the bars, tabs and backgrounds. The **context** is a small object of the app that every screen reads. This page answers:
 
 1. [Why the navigation keeps them](#why), and not a React provider.
-2. [The theme](#theme): its colors, dark mode, changing it, Android's own colors.
+2. [The theme](#theme): its colors, dark mode, changing it, [Android's theme](#android).
 3. [The context](#context): filling it, reading it, typing it.
 4. [What goes in the context](#context-roles), and what goes elsewhere.
 
@@ -37,7 +37,7 @@ export const Navigation = createNavigation({
 
 Every top bar and the tab bar are navy with light titles; the buttons, the back arrow and the selected tab are orange.
 
-A color left out keeps the platform's look. On iOS 26 a theme without `bar` keeps the bars on glass. On Android the bars take the colors of the app's Material 3 theme, neutral grays by default (see [Android's colors](#android)).
+A color left out keeps the platform's look. On iOS 26 a theme without `bar` keeps the bars on glass. On Android the bars take the colors of the app's Material 3 theme, neutral grays by default (see [Android's theme](#android)).
 
 The theme is the bottom layer of the options of every screen. A screen that needs its own look sets it in its options, and they go over the theme (see [Where a screen gets them](../fundamentals/screen-options#layers)).
 
@@ -106,9 +106,9 @@ The options of the app and of a screen can be built from the theme: their functi
 
 So a color that follows the theme belongs in the theme itself, or in the app's `options`.
 
-### Android's colors
+### Android's theme
 
-(Android) The bars, tabs, search, sheets and menus are Material 3 views. What the theme and the options leave out, they take from the app's Android theme, as every Material view of the app does. On an app made from React Native's template, `setup` makes the app's theme inherit `Theme.ApexNavigation`: Material 3 in neutral grays, light and dark, with no tint of its own.
+(Android) The bars, tabs, search, sheets, menus and the floating action button are Material 3 views. What the theme and the options leave out, they take from the app's Android theme, as every Material view of the app does. On an app made from React Native's template, `setup` makes the app's theme inherit `Theme.ApexNavigation`: Material 3 in neutral grays, light and dark, with no tint of its own.
 
 An app changes any of these colors in `styles.xml`. A color that differs in dark mode is a color resource with a second value in `values-night`, so the one style serves both modes:
 
@@ -130,19 +130,138 @@ The selected tab now sits on a peach pill in light mode, and a brown one in dark
 
 | Material 3 color | What takes it |
 | --- | --- |
-| `colorSurface` | The top bar. |
-| `colorOnSurface` | The title and the back arrow. |
-| `colorOnSurfaceVariant` | The subtitle and the "⋮" of the bar. |
-| `colorSurfaceContainer`, `colorSurfaceContainerLow`, `colorSurfaceContainerHigh` | The tab bar and the menus of the bar; a sheet; the search field. |
+| `colorSurface` | The top bar, and the menus of the bar while the bar is opaque. |
+| `colorOnSurface` | The title, the large title, the back arrow, the text of the search. |
+| `colorOnSurfaceVariant` | The subtitle and the "⋮" of the bar; the hint of the search. |
+| `colorSurfaceContainer` | The tab bar; the menus of the bar when the bar lets the screen through. |
+| `colorSurfaceContainerLow` | A sheet. |
+| `colorSurfaceContainerHigh` | The search field and its suggestions. |
 | `colorSecondaryContainer` | The pill of the selected tab, the selected scope of the search. |
 | `colorPrimaryContainer` | The floating action button. |
-| `colorError` | The badges of the tabs. |
+| `colorError` | The badges of the tabs, the destructive items of the bar's menus. |
+| `android:colorBackground` | Behind a screen without `layout.backgroundColor`. It comes from the activity's own theme, Material 3 or not; a screen in a sheet shows the sheet's color. |
 
-The theme's `colors` and a screen's options go over these: `bar` over the top bar and the tab bar, `text` over the titles, `badge` over the badges.
+The theme's `colors` and a screen's options go over these: `bar` over the top bar and the tab bar, `text` over the titles, `badge` over the badges. The menus of the bar take the bar's color and the title's color while the bar is opaque; `topBar.menuBackgroundColor` and `topBar.menuTextColor` set them apart. These two are Android only: iOS draws its menus in the system's colors.
 
 - **An app with a Material 3 theme of its own** keeps it, and the navigation takes its colors.
-- **An app with a theme that isn't Material 3** keeps it too. The bars, tabs, search and sheets then take `Theme.ApexNavigation` themselves, and follow the app's light or dark mode.
-- **An app that is only light** sets it in code: `AppCompatDelegate.setDefaultNightMode(AppCompatDelegate.MODE_NIGHT_NO)`.
+- **An app with a theme that isn't Material 3** keeps it too, and the navigation's views take `Theme.ApexNavigation` (see [the next section](#android-other-themes)).
+- **An app that is only light** sets it in code: `AppCompatDelegate.setDefaultNightMode(AppCompatDelegate.MODE_NIGHT_NO)`. `Theme.ApexNavigation` follows dark mode, so without it the navigation's views turn dark with the device.
+
+#### An app with an AppCompat or MaterialComponents theme
+
+Many apps keep a theme of their own, such as `Theme.AppCompat.Light.NoActionBar` or `Theme.MaterialComponents.DayNight.NoActionBar`. `setup` leaves it as it is: it changes only the template's `Theme.AppCompat.DayNight.NoActionBar`.
+
+The navigation tells a Material 3 theme by `colorSurfaceContainerHigh`, a role only Material 3 themes have. When the activity's theme has none, each view of the navigation is made in a copy of the app's theme with `Theme.ApexNavigation` **laid over it**. Over it means it wins: the colors, text appearances and shapes it sets replace the app's, so the app's `colorPrimary` and `colorAccent` don't reach the bars, and the bars are neutral gray next to the app's own colors. The app's own views keep its theme.
+
+There are two ways to give the bars the app's colors.
+
+**Move the theme to Material 3.** The parent becomes `Theme.ApexNavigation`, or `Theme.Material3.DayNight.NoActionBar` for Material's own palette, and the brand colors go to Material 3's roles, the ones in the table above:
+
+```xml
+<!-- Before: parent="Theme.MaterialComponents.DayNight.NoActionBar" -->
+<style name="AppTheme" parent="Theme.ApexNavigation">
+  <item name="colorSecondaryContainer">@color/selected_tab</item>
+  <item name="colorPrimaryContainer">@color/brand</item>
+</style>
+```
+
+The selected tab and the floating action button take the brand colors. Attributes Material 3 has no role for, such as `colorAccent`, `colorPrimaryDark` or `colorPrimaryVariant`, do nothing in the navigation. The app's own native views change with the theme too: its AppCompat and Material widgets and dialogs take the Material 3 look.
+
+**Keep the theme, and color the navigation from JavaScript.** The colors of the [theme](#theme) are options, not Android theme attributes, so they paint the bars with any Android theme:
+
+```ts
+export const Navigation = createNavigation({
+  // … screens and root
+  theme: {
+    colors: {
+      primary: '#E76F51',
+      bar: '#1E2A44',
+      text: '#F3E9D2',
+      badge: '#E63946',
+    },
+  },
+});
+```
+
+The bars, the titles, the buttons, the selected tab and the badges take the brand colors. The rest stays in `Theme.ApexNavigation`'s grays: the pill of the selected tab, a sheet, the search field, the floating action button. The navigation has **no theme attribute or overlay of its own** for them. Two of them have an option of their color: `fab.backgroundColor` and `topBar.searchBar.backgroundColor`; the pill of the selected tab and a sheet have none.
+
+The way to recolor them in resources is to replace `Theme.ApexNavigation` itself: a style of the same name in the app wins over the library's when the build merges the resources. It replaces the whole style, so it has Material 3's parent, and it goes in `values` and again in `values-night`, or dark mode keeps the library's grays:
+
+```xml
+<style name="Theme.ApexNavigation"
+  parent="Theme.Material3.DayNight.NoActionBar">
+  <item name="colorSecondaryContainer">#FCE4D6</item>
+</style>
+```
+
+```xml
+<style name="Theme.ApexNavigation"
+  parent="Theme.Material3.DayNight.NoActionBar">
+  <item name="colorSecondaryContainer">#5C3B2E</item>
+</style>
+```
+
+A role the app's style leaves out takes Material 3's own palette, with its violet tint, and not the navigation's grays.
+
+#### Fonts and shapes
+
+An app with a font of its own sets it in the options, which work with any Android theme. The app's `options` give it to every screen:
+
+```ts
+export const Navigation = createNavigation({
+  // … screens and root
+  options: {
+    topBar: {
+      title: { fontFamily: 'Inter', fontWeight: '600' },
+      subtitle: { fontFamily: 'Inter' },
+      largeTitle: { fontFamily: 'Inter' },
+    },
+    bottomTab: { fontFamily: 'Inter' },
+  },
+});
+```
+
+The family is the name a `Text` style takes: a font in `assets/fonts/` or a `res/font` resource React Native knows. Without options, each text takes its font from the app's theme, or from Material 3's text appearances:
+
+| Text | Without options | Options over it |
+| --- | --- | --- |
+| The title and the subtitle | 22 sp and 14 sp, set in code; the theme's `android:fontFamily`, else the system font. | `topBar.title.fontFamily`, `fontSize`, `fontWeight`, `fontStyle`; the same in `topBar.subtitle`. |
+| The large title | 28 sp, set in code; the font as the title. | The same in `topBar.largeTitle`. |
+| A text button of the bar | The theme's `actionMenuTextAppearance`. | `fontFamily`, `fontSize`, `fontWeight`, `fontStyle` of the button. |
+| The labels of the tabs | `textAppearanceLabelMedium`, through Material 3's style of the tab bar. | `bottomTab.fontFamily`, `fontWeight`, `fontStyle`; `fontSize` and `selectedFontSize`. |
+| The items of the bar's menus | `textAppearanceLargePopupMenu`, which Material 3 points to `textAppearanceBodyLarge`; the title of a submenu `textAppearancePopupMenuHeader`. | None. |
+| The text of the search | 16 sp. The field in the bar takes the font as the title; the pill under the title, Material's `SearchBar`, its own `TextAppearance.Material3.SearchBar`. | None. |
+| The scopes of the search | `textAppearanceLabelLarge`. | None. |
+
+The shapes come mostly from code, not from `shapeAppearance…` attributes:
+
+| Shape | Without options | Option over it |
+| --- | --- | --- |
+| A sheet | 28 dp, the top corners only, set in code. | `modal.sheet.cornerRadius`. |
+| The menus of the bar | The theme's `popupMenuBackground`, a drawable: 4 dp in Material 3. | None. |
+| The search field | A capsule: set in code in the bar, Material's `SearchBar` style under the title; the suggestions 16 dp, set in code. While the search fills the screen, Material's `SearchView` has no corners. | None. |
+| The scopes of the search | `shapeAppearanceCornerSmall`. | None. |
+| The tab bar | Square. | `bottomTabs.cornerRadius`. |
+| The floating action button | `shapeAppearanceCornerLarge`. | None. |
+
+An app with a Material 3 theme changes the theme's part in `styles.xml`. These attributes are the app's own: its other views that use them change too.
+
+```xml
+<style name="AppTheme" parent="Theme.ApexNavigation">
+  <item name="android:fontFamily">@font/inter</item>
+  <item name="textAppearanceLabelMedium">@style/TabLabel</item>
+  <item name="popupMenuBackground">@drawable/menu</item>
+</style>
+
+<style name="TabLabel" parent="TextAppearance.Material3.LabelMedium">
+  <item name="fontFamily">@font/inter</item>
+  <item name="android:fontFamily">@font/inter</item>
+</style>
+```
+
+The title, the large title and the labels of the tabs are in Inter, and so is the search field in the bar from Android 8 on: before it, a plain text field can't load a font resource. The menus of the bar take the shape of `menu.xml`, in the bar's color while the bar is opaque.
+
+In an app whose theme isn't Material 3, `Theme.ApexNavigation` lies over the app's theme, so the text appearances, `popupMenuBackground` and the shapes are `Theme.ApexNavigation`'s whatever the app's theme says. `Theme.ApexNavigation` doesn't set `android:fontFamily`, so the app's own still reaches the title, the large title and the search field in the bar. For the rest, the options are the way.
 
 ## The context
 

package/docs-md/architecture/transitions.md

@@ -46,6 +46,8 @@ navigation.showModal('Player', {
 });
 ```
 
+The top bar of a pushed screen goes with the screen on Android and stays in place on iOS: see [the bar in a transition of your own](#custom-bar).
+
 `presentation` of `createNavigation` gives every push or modal of the app its transition: see [Defaults for the whole app](../fundamentals/moving-between-screens#presentation). New roots have presets of their own: see [How a new root comes in](../fundamentals/switching-roots#transitions).
 
 ## Transitions out of a view
@@ -78,9 +80,11 @@ navigation.push('Person', {
 });
 ```
 
-The avatar of the row moves and grows into the photo of the profile, and the name into its larger title. The views can differ in size and style. `type` and `duration` next to `shared` change how the rest of the screen comes, `'fade'` by default.
+The avatar of the row moves and grows into the photo of the profile, and the name into its larger title. The views can differ in size and style. A pair that isn't found is skipped (the transition waits for it first); one that fails on the way is skipped with a warning in the log. Either way its views show with their screens, and the other pairs move. `type` and `duration` next to `shared` change how the rest of the screen comes, `'fade'` by default.
+
+A view turned or scaled by its own `transform`, or by a parent's, flies from where it shows and lands as the other view shows, turning the shorter way. The angle is the one React Native draws, from −180° to 180°: `rotate: '270deg'` turns back a quarter, and no pair spins a full turn; a spin is an animation of the view's own.
 
-Both platforms. (Android) The next screen waits until it is drawn, so its views are there to move into; a `type` other than a fade gives way to a fade.
+What flies is a copy: pictures of the two views, taken as the transition starts, while the views wait hidden in their places. Both platforms. (Android) The next screen waits until it is drawn, so its views are there to take pictures of; an image flies as its own image, from its fit in one view to its fit in the other; a `type` other than a fade gives way to a fade. A skew and a tilt (`skewX`, `rotateX`, …) don't fly: the view flies without them and has them again at the end.
 
 ### Zoom
 
@@ -119,7 +123,7 @@ function Tile({ id, uri }: { id: string; uri: string }) {
 }
 ```
 
-The preview goes when the component unmounts. On Android a long press on the view does nothing of the navigation's: the view has no preview.
+The previewed screen renders when the press starts, not when the component mounts ([when the screen renders](/api/transitions/usePreview#time)). The preview goes when the component unmounts. On Android a long press on the view does nothing of the navigation's: the view has no preview.
 
 ## Animations of your own
 
@@ -144,17 +148,60 @@ navigation.push('Details', {
 
 Details rises 300 points as it fades in. Each property animates from a value to a value over a time, with a delay and an interpolation if it needs them; the [API](#api) lists every one.
 
-The same goes for `pop`, `showModal`, `dismissModal`, `setStackRoot` and `setRoot`. The swipe back is the exception: (iOS) it always follows the finger with the system's slide, so a custom `pop` plays for the back button and `pop()` only.
+(iOS) Once the move starts, the system draws it on its own, as it draws UIKit's animations: work on the main thread, such as a screen that mounts a long list, doesn't stop it.
+
+The same goes for `pop`, `showModal`, `dismissModal`, `setStackRoot` and `setRoot`. The swipe back is the exception: (iOS) by default it follows the finger with the system's slide, so a custom `pop` plays for the back button and `pop()` only. (Android) A pop with an animation of its own shows no preview under the swipe: the screen pops when the swipe ends.
+
+### The swipe back with a pop of your own
+
+(iOS) A screen that leaves with a move of its own, such as a card that shrinks away, looks wrong when the swipe back slides it out like any other screen. `interactive` on its pop plays its own move under the finger instead:
+
+```ts
+navigation.push('Details', {
+  options: {
+    animations: {
+      pop: {
+        interactive: true,
+        content: {
+          exit: {
+            scaleX: { from: 1, to: 0.8, duration: 400 },
+            scaleY: { from: 1, to: 0.8, duration: 400 },
+            alpha: { from: 1, to: 0, duration: 400 },
+          },
+        },
+      },
+    },
+  },
+});
+```
+
+The swipe from the edge now shrinks Details as far as the finger has gone across the screen. The user can stop halfway; letting go past half way, or a flick back, finishes the pop, and letting go before half way, or a flick the other way, grows the screen back. After a quick flick the rest plays faster, never slower. The elements and the shared elements of the pop move with it, so a [shared element](#views) flies home under the finger.
+
+- It applies only to a pop with an animation of its own, and `transition` presets get it through `options.animations.pop.interactive`.
+- The swipe moves the time of the animation, not a point: a move with an easing doesn't stay exactly under the finger.
+- On iOS 26 the swipe from the content stays off for a screen with a pop of its own; the swipe from the edge works.
+- The top bar shows the screen under from the start of the swipe, as it does in any move of your own, and comes back if the user gives the swipe up.
+- While the finger is down, the system's animations inside the two screens, such as an activity indicator, hold still.
+
+(Android) It doesn't apply: a pop with an animation of its own plays when the back gesture ends.
+
+### The top bar
+
+The top bar goes its platform's way in a preset or an animation of your own. (Android) It goes with its screen, as if it were part of it: with `slideUp` the new screen comes up with its bar over the old one and its bar, and on the way back it goes down with its bar, uncovering the bar below. With `fade` or `scale` the bar fades or grows with its screen. (iOS) UIKit keeps the bar in place and changes its title and buttons as the transition starts; only the screens under it move.
+
+### When the user reduces motion
+
+The system's setting to reduce motion wins over a move of your own, with nothing to set. (iOS) With Reduce Motion on, the move becomes a fade of the same length: the screen that comes fades in on a push, a modal's show and `setRoot`, and the screen that goes fades out on a pop and a dismissal. No element moves. (Android) With Remove animations on, every animation of the app ends at once: the move jumps to its end, no element moves and the push doesn't wait for one, a side menu opens and closes without its slide, and a sheet shows and closes without it.
 
 ## Which to pick
 
 | The move | Pick | What it costs |
 | --- | --- | --- |
 | Most moves | The platform's | Nothing: it follows the finger and the system. |
-| A move that means something else, such as a fading modal | A preset | The swipe back on iOS still slides. |
+| A move that means something else, such as a fading modal | A preset | The swipe back on iOS still slides, unless the pop is [`interactive`](#custom-swipe). |
 | A view that becomes the next screen | Shared elements, or the zoom on iOS 18+ | A `nativeID` on both views. The zoom shows on iOS 18+ only. |
 | A look at a screen before opening it | The preview | iOS only. |
-| A move no preset has | `options.animations` | Every property spelled out; the swipe back on iOS still slides. |
+| A move no preset has | `options.animations` | Every property spelled out; the swipe back on iOS still slides, unless the pop is [`interactive`](#custom-swipe). |
 
 ## Waiting for the content
 
@@ -162,11 +209,10 @@ A screen can come in before its React content has drawn, or wait for it. Coming
 
 | | By default |
 | --- | --- |
-| (iOS) push | Doesn't wait for the content: the screen slides in with its bar, and the content draws as it comes. It waits only for components in the bar. |
-| (Android) push | Doesn't wait. With `appProvider` a React screen is rendered before the push starts, so it comes in drawn from the first frame. A screen with a React root of its own comes in at once, and its content draws as it comes; so does a native screen. The components of the bar draw as the screen comes in. |
+| Push | Waits for the screen's first mount, half a second at most, so it comes in drawn, with what it set as it rendered (a title from `useScreenOptions`) already in its bar. A native screen comes in at once. (iOS) The components of the bar wait too, each to its own limit from the start of the wait. (Android) The components of the bar draw as the screen comes in; with `appProvider` the screen is rendered before the push starts ([below](#wait-one-tree)). |
 | (Android) modal | Waits for the content and the components of the bar, half a second at most, so the screen comes in drawn. |
 
-`waitForRender` of an animation changes it. `true` waits as long as it takes; `false` comes in at once (a push on Android with `appProvider` [still renders the screen first](#wait-one-tree)):
+`waitForRender` of an animation changes it. `true` waits as long as it takes; `false` comes in at once, the content drawing as it comes (a push on Android with `appProvider` [still renders the screen first](#wait-one-tree)):
 
 ```ts
 navigation.push('Details', {
@@ -174,15 +220,15 @@ navigation.push('Details', {
 });
 ```
 
-A screen that draws nothing at first doesn't hold its transition back: it comes in empty, with its bar.
+A screen that draws nothing at first holds its transition back half a second at most, then comes in with its bar.
 
 ### A push on Android, in one tree
 
-(Android) With `appProvider` a push doesn't wait for the screen, and the screen still comes in drawn: nothing of it mounts during the transition, which would drop frames. It goes in three steps:
+(Android) With `appProvider` the screen comes in drawn without a wait of its own: nothing of it mounts during the transition, which would drop frames. It goes in three steps:
 
 1. The native side lays the screen out in its stack, out of sight, and gives React its size and its safe area.
 2. React renders the screen at that size with its content, at once.
-3. The push starts in the frame in which that content appears; if it doesn't appear, after half a second.
+3. The push starts right after that content appears, once what the screen set as it rendered (its `useScreenOptions`) is applied; if it doesn't appear, after half a second.
 
 So the push starts later by the time React takes to render the screen, as a push in a native app starts once its screen is built. `waitForRender: false` goes the same way here; `true` waits for the content as long as it takes, and for the components of the bar, half a second at most.
 

package/docs-md/containers/modals.md

@@ -52,8 +52,8 @@ Compose shows with a close button at the leading edge of its top bar. The settin
 
 | Setting | What it does |
 | --- | --- |
-| `closeButton` | A close button on the first screen: the system one on iOS, an icon on Android. Needs the stack. |
-| `onDismiss` | Called once the modal is gone, whatever closed it: a swipe, a command, a new root. |
+| `closeButton` | A close button on the first screen: the system one on iOS, an icon on Android. Needs the stack. A new first screen from `setStack` or `replace` in the modal's stack gets it too. |
+| `onDismiss` | Called once the modal is gone, whatever closed it: a swipe, a command, a new root. `setStack` and `replace` in the modal's stack replace its first screen and call it too. |
 | `stack` | `false`: the screen alone, without a stack and its top bar. |
 | `style`, `sheet`, `popover`, `contentSize` | How it looks: see [How a modal looks](#styles). |
 | `transition`, `options` | The animation, and the screen's options for this show. |
@@ -70,6 +70,8 @@ navigation.showModal('Compose', { style: 'fullScreen' });
 
 Without `style`, a modal is a sheet on (iOS) and covers the whole screen on (Android).
 
+`'pageSheet'` and `'formSheet'` are sheets on both platforms: on (Android) the Material bottom sheet over the dimmed screen, at the full height under the status bar and at most 640 dp wide. `'fullScreen'` and `'overFullScreen'` come up from the bottom over the whole screen; on Android with the system's motion of a window opening over another, without a fade.
+
 `'overFullScreen'` keeps the screen under the modal in place, so it shows through wherever the modal draws nothing: a dialog of your own, a card over a dimmed app. Give the modal's screen `backgroundColor('transparent')` in its options, so its own background doesn't hide the screen under it.
 
 ### A form on iPad
@@ -83,7 +85,7 @@ navigation.showModal('EditProfile', {
 });
 ```
 
-On iPhone a form sheet is a sheet, and `contentSize` does nothing.
+On iPhone and on Android a form sheet is a sheet, and `contentSize` does nothing.
 
 ### A popover
 
@@ -95,7 +97,7 @@ navigation.showModal('Filters', {
 });
 ```
 
-On iPhone it becomes a sheet, unless `adaptive: false` keeps it a popover. (Android) has no popovers: the modal covers the whole screen, as without `style`.
+On iPhone it becomes a sheet, unless `adaptive: false` keeps it a popover. (Android) has no popovers: the modal is the bottom sheet of `'pageSheet'`.
 
 ## Sheets
 
@@ -124,6 +126,8 @@ navigation.setOptions({
 
 On (Android) a sheet is the Material bottom sheet. It stops at half (`'medium'`) and full (`'large'`) height and at heights of its own; `'content'` stops at half.
 
+(Android) 14+ The back gesture over a sheet shows it sliding down before the user lets go: [the preview of a sheet closing](../screen-ui/back-and-gestures#sheet-preview).
+
 Sheets in a real app, step by step: [Bottom sheets](../flows/bottom-sheets).
 
 ## How a modal closes

package/docs-md/containers/overlays.md

@@ -24,7 +24,9 @@ This page answers:
 
 A push or a modal moves the user somewhere. An overlay doesn't move anyone: it puts a screen **on top of everything**, and the app goes on under it.
 
-An overlay is a screen of `screens` like any other: a component, its props, its options. It shows above the tabs, the bars and the modals; on (iOS) it is in a window of its own. Its background is transparent, so the app shows wherever the overlay draws nothing. What overlays are for:
+An overlay is a screen of `screens` like any other: a component, its props, its options. It shows above the tabs, the bars and the modals; on (iOS) it is in a window of its own. Its background is transparent, so the app shows wherever the overlay draws nothing.
+
+An overlay covers the whole window, **the status bar included**: a dialog's dimmed backdrop dims the status bar too, as a system dialog does. Its safe area keeps the top and the sides off the bars, so a toast at the top of the overlay sits below the status bar. On (Android) a status bar with a color of its own (`statusBar.backgroundColor`) stays over the backdrop, and `statusBar.drawBehind: false` starts the overlay below the status bar. What overlays are for:
 
 ## Showing and closing
 

package/docs-md/containers/side-menu.md

@@ -74,7 +74,7 @@ A tap on the button opens the menu. A button of the options gets the navigation
 
 ## A pick in the menu
 
-A menu is a screen without a stack, so **its commands act on the center**, and the menu closes once the center has changed. A pick usually switches the section, so the center starts over with it:
+A menu is a screen without a stack, so **its commands act on the center**, and the menu closes as the center changes: it starts to slide away at the tap, and a push slides in as it goes. The command resolves once both are done. A pick usually switches the section, so the center starts over with it:
 
 ```tsx
 import { Button, View } from 'react-native';
@@ -94,7 +94,7 @@ function Menu() {
 }
 ```
 
-A tap on Settings shows Settings in the center, and the menu closes. Which command to use depends on the way back:
+A tap on Settings closes the menu and shows Settings in the center as it goes. Which command to use depends on the way back:
 
 | From the menu | The center |
 | --- | --- |
@@ -108,6 +108,8 @@ A tap on Settings shows Settings in the center, and the menu closes. Which comma
 | (iOS) | Over the content, which dims: `openMode: 'aboveContent'` of the side, the default. Or under it, with the content moved aside: `'pushContent'`. Then `animation(…)` says how the menu appears: `'parallax'`, `'slide'`, `'slide-and-scale'` or `'door'`. |
 | (Android) | The drawer of the platform: over the content, which dims. |
 
+The menu's color is its screen's `layout.backgroundColor`: it fills the whole height of the menu, behind the status bar and the navigation bar, while the menu's content keeps its top and sides clear of them (the bottom goes down to the edge: a list adds `insets.bottom`). A background on the React content stops at the safe area.
+
 `.ios()` keeps the settings that only iOS has apart from the others:
 
 ```ts
@@ -122,6 +124,21 @@ On iOS the content moves aside, and the menu comes in under it with a parallax;
 
 (iOS) 26: `left({ glass: true })` puts the menu on Liquid Glass. The glass shows where the menu's screen has no background of its own.
 
+## When the menus are created
+
+The screens of the menus are created with the side menu by default, with their React content. A heavy menu competes
+with the first render of the center. `options({ menusAttachMode })` moves the creation:
+
+```ts
+SideMenu({ left: 'Menu', center: 'Home' }).options({ menusAttachMode: 'onOpen' });
+```
+
+- `'together'` (the default): with the center.
+- `'afterCenter'`: right after the side menu first appears. The menus don't compete with the first render of the center and are ready at the first open.
+- `'onOpen'`: each menu the first time it starts to open, from a swipe, `openMenu`, `visible: true` or `visible` in the layout. Until React draws the menu, it shows its background (`backgroundColor`). A second open reuses it.
+
+The trade-off of `'onOpen'`: the first open of a menu doesn't wait for its render and shows its background for a moment, while a menu not opened yet runs no code. A push into the stack of such a menu and `mergeOptions` on its screen wait for the menu, like a tab not yet selected. The screens of the menus get appear events only when the menu opens, in every mode. The mode is read once, when the side menu is created, from its own options, else the default options; `mergeOptions` doesn't change it. With `appProvider` the screens render in the app's React tree at once in every mode, and the mode delays only their native containers. It means the same on iOS and Android.
+
 ## Where the swipe is off
 
 A swipe from the edge can clash with the content, such as a map or a carousel. A screen turns it off **while it is on top of the center**, in its options:

package/docs-md/containers/tabs.md

@@ -90,6 +90,10 @@ This is the app's `navigation`: its `push` goes to the stack the user sees, now
 
 Inbox shows, and Chat comes in over it, in the stack of the Inbox tab.
 
+On (Android) the content changes with Material's fade through, as in the system's Phone app: the tab that goes fades out, then the new one fades in and grows to its size, in 300 ms; the tab bar stays. On (iOS) the new tab shows at once, as the system's tab bar does.
+
+To switch at once on Android too, give `bottomTabs.switchAnimation: 'none'`: to every tabs node in the app's default `options`, to these tabs with `Tabs().options({ switchAnimation: 'none' })`, or to a screen. The tab that is selected decides, by the screen on top of it: a tab whose top screen says `'none'` comes in at once, and leaving it fades as usual. A screen's `setOptions` changes it from the next switch.
+
 ### A press on a tab
 
 A second tap on the selected tab is a convention of both platforms: **back to the start of the tab**. The navigation does it without code:
@@ -144,7 +148,7 @@ From a screen of the tab, `setTabBadge(count)` needs no id: it sets the badge of
 
 ## When tabs are created
 
-By default every tab is created with the tabs, so a switch shows it at once. `Tabs().lazy()` creates each tab the first time it shows. The app starts faster when its tabs are heavy, and a tab the user never opens costs nothing.
+By default every tab is created with the tabs, so a switch shows it at once. On (iOS) a text input's `autoFocus` in a tab not selected yet does nothing then: focus the field in `useScreenAppear`. `Tabs().lazy()` creates each tab the first time it shows. The app starts faster when its tabs are heavy, and a tab the user never opens costs nothing.
 
 ```ts
 const main = Tabs(/* … */).lazy();

package/docs-md/flows/bottom-sheets.md

@@ -152,7 +152,7 @@ navigation.showModal('PhotoActions', {
 });
 ```
 
-The content is measured after every render, so the sheet follows it when it grows. It needs (iOS) 16; on (Android) the sheet stops at half the height instead, as the Material sheet has no height of its content. A screen that fills its parent (`flex: 1`) has no height of its own, so give the content of this screen its natural height.
+The content is measured after every render, so the sheet follows it when it grows. It needs (iOS) 16. A screen that fills its parent (`flex: 1`) has no height of its own, so give the content of this screen its natural height. The sheet adds the bottom safe area to the height of a `'content'` sheet itself (UIKit on (iOS), the navigation bar on (Android)), so don't add `insets.bottom` to its content: the gap would come twice.
 
 ## 8. Close it with a pick
 
@@ -218,8 +218,10 @@ The sheet is (iOS) UIKit's sheet, and on (Android) the Material bottom sheet. Th
 | --- | --- | --- |
 | `'medium'`, `'large'` | Half and full height. | Half height, and full height under the status bar. |
 | A number | That height, in points. iOS 16+: iOS 15 leaves it out. | That height, in dp. |
-| `'content'` | The height of the content. iOS 16+: iOS 15 leaves it out. | Half the height: the Material sheet has no height of its content. |
+| How many stops | Every detent of the list. | Three at most: the lowest, the highest, and one between them (`selectedDetent` when it stands there, else the lowest of the others). |
+| `'content'` | The height of the content. iOS 16+: iOS 15 leaves it out. | The height of the content. |
 | The screen under it | Shrinks back a little at full height, as UIKit does. | Stays in place. |
+| The keyboard | The sheet rises and stands on it. | The sheet rises and stands on it at every stop, unless the screen in it has `layout.adjustResize: false`. |
 
 ## The whole code
 

package/docs-md/flows/forms-in-a-modal.md

@@ -299,7 +299,7 @@ navigation.showModal('EditProfile', {
 });
 ```
 
-On iPhone a form sheet is the same sheet as before, and on Android the modal is unchanged.
+On iPhone a form sheet is the same sheet as before. On Android it is the Material bottom sheet, where the modal without a style covered the whole screen.
 
 ## The whole code