@apexnative/navigation 1.0.0-alpha.5 → 1.0.0-alpha.7

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

@@ -82,7 +82,9 @@ 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. 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.
 
-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.
+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.
+
+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
 
@@ -121,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
 
@@ -146,21 +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. (Android) A pop with an animation of its own shows no preview under the swipe: the screen pops when the swipe ends.
+(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
 

package/docs-md/containers/modals.md

@@ -126,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

@@ -26,7 +26,7 @@ A push or a modal moves the user somewhere. An overlay doesn't move anyone: it p
 
 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 content 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:
+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

@@ -108,7 +108,7 @@ A tap on Settings closes the menu and shows Settings in the center as it goes. W
 | (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 clear of them. A background on the React content stops at the safe area.
+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:
 

package/docs-md/containers/tabs.md

@@ -92,6 +92,8 @@ 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:

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/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

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
 
@@ -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
 

package/docs-md/help/troubleshooting.md

@@ -439,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.
@@ -543,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"
@@ -856,6 +864,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"
@@ -978,6 +990,10 @@
         "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"
@@ -1175,9 +1191,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"
@@ -1327,10 +1351,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"
@@ -1410,6 +1442,10 @@
         "heading": "Typed commands",
         "anchor": "typed-commands"
       },
+      {
+        "heading": "Fast Refresh",
+        "anchor": "fast-refresh"
+      },
       {
         "heading": "UIKit and Android views",
         "anchor": "imperative"
@@ -4092,6 +4128,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

@@ -779,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

@@ -85,6 +85,8 @@ 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. |
 
+(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
@@ -115,7 +117,21 @@ defineScreen({
 });
 ```
 
-iOS ignores it: the swipe back there is UIKit's.
+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