@apexnative/navigation 1.0.0-alpha.6 → 1.0.0-alpha.8

package/cli/setup/steps/metro.js

@@ -0,0 +1,46 @@
+// @ts-check
+'use strict';
+
+/** @typedef {import('./types').StepResult} StepResult */
+
+const REQUIRE = "const { withApexNavigation } = require('@apexnative/navigation/metro');";
+
+// The config the file exports: `module.exports = …;`, its last statement.
+const EXPORT = /^module\.exports\s*=\s*([\s\S]+?);?\s*$/m;
+
+const HOW_TO = `Wrap the config metro.config.js exports, so an edit updates the app by Fast Refresh instead of
+reloading it:
+
+  ${REQUIRE}
+
+  module.exports = withApexNavigation(mergeConfig(getDefaultConfig(__dirname), config));`;
+
+/**
+ * metro.config.js: the config it exports goes through withApexNavigation, which puts the navigation's Babel
+ * transformer in front of the app's own.
+ * @param {string} text
+ * @returns {StepResult}
+ */
+function planMetro(text) {
+  if (text.includes('withApexNavigation')) return { status: 'done', note: 'already set up' };
+  const found = EXPORT.exec(text);
+  // Only an export that ends the file: one in the middle may be changed by what comes after it.
+  if (!found || text.slice(found.index + found[0].length).trim() !== '') {
+    return { status: 'manual', note: 'changed by hand, see below', howTo: HOW_TO };
+  }
+  const exported = found[1].trim();
+  const before = text.slice(0, found.index);
+  const requires = [...before.matchAll(/^.*require\(.*\);?$/gm)];
+  const last = requires[requires.length - 1];
+  const head =
+    last === undefined
+      ? `${REQUIRE}\n\n${before}`
+      : `${before.slice(0, last.index + last[0].length)}\n${REQUIRE}${before.slice(last.index + last[0].length)}`;
+  return {
+    status: 'change',
+    next: `${head}module.exports = withApexNavigation(${exported});\n`,
+    note: 'Fast Refresh for every edit',
+  };
+}
+
+module.exports = { planMetro, HOW_TO };

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

@@ -84,7 +84,7 @@ The avatar of the row moves and grows into the photo of the profile, and the nam
 
 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. A skew and a tilt (`skewX`, `rotateX`, …) don't fly: the view flies without them and has them again at the end.
+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
 
@@ -148,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/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. On (iOS) UIKit adds the bottom safe area to the height of a `'content'` sheet itself, so don't add `insets.bottom` to its content: the gap would come twice.
+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/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/troubleshooting.md

@@ -564,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"
@@ -1183,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"
@@ -1335,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"
@@ -1418,6 +1442,10 @@
         "heading": "Typed commands",
         "anchor": "typed-commands"
       },
+      {
+        "heading": "Fast Refresh",
+        "anchor": "fast-refresh"
+      },
       {
         "heading": "UIKit and Android views",
         "anchor": "imperative"

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

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

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

package/docs-md/screen-ui/toolbar-and-fab.md

@@ -75,6 +75,8 @@ A round button with a pencil floats at the bottom right; a press opens Compose.
 | `backgroundColor`, `iconColor` | Its colors. Without them, the colors of the app's Material 3 theme. |
 | `visible: false` | Hides it. |
 
+The FAB belongs to its screen. A push brings the new screen's FAB in with it and takes the old one out with the screen it covers; a pop does the same the other way, and the back gesture shows the FAB of the screen under the top with that screen. Two screens with the same `id` share one button: it stays in place while the screens move.
+
 ### Actions
 
 A FAB with `actions` opens them above it on a press, each a small FAB with its own press:

package/docs-md/start/installation.md

@@ -129,7 +129,7 @@ In an app as the React Native template makes it, the window shows **one React vi
 | `MainApplication.kt` | Extends `NavigationApplication`; keeps the template's `loadReactNative(this)` in `onCreate`, or adds it. | It keeps one React host for all screens, made after `loadReactNative(this)` loaded React Native. Native screens made by `codegen` are registered there, before JS opens them. |
 | `MainActivity.kt` | Extends `NavigationActivity`. | The activity holds the containers of the navigation instead of one React view. It gets the back press, edge-to-edge and configuration changes first. |
 | `AndroidManifest.xml` | Adds `android:enableOnBackInvokedCallback="true"` to `<application>`. | On the first screen the system plays its own animation back to the home screen as the user swipes back (predictive back). Android 16 turns it on for apps that target API 36; an app that targets less opts in here. A value the app set itself stays. See [Back to the home screen](../screen-ui/back-and-gestures#system-animation). |
-| `styles.xml` | `AppTheme` inherits `Theme.ApexNavigation`. | The bars, tabs and search are Material 3 views and take their colors from the app's theme. This one is Material 3 in neutral grays, light and dark; change any color in the same file. A theme of the app's own stays as it is. See [Android's colors](../architecture/theme-and-context#android). |
+| `styles.xml` | `AppTheme` inherits `Theme.ApexNavigation`. | The bars, tabs and search are Material 3 views and take their colors from the app's theme. This one is Material 3 in neutral grays, light and dark; change any color in the same file. A theme of the app's own stays as it is. See [Android's theme](../architecture/theme-and-context#android). |
 
 The main activity keeps the template's `android:configChanges="keyboard|keyboardHidden|orientation|screenLayout|screenSize|smallestScreenSize|uiMode"`. Without `orientation`, `screenSize`, `smallestScreenSize`, `screenLayout` or `uiMode` Android recreates the activity on a rotation, a resize, a fold or a light/dark switch, and every screen goes with it; `doctor` warns about it under Config changes.
 
@@ -150,8 +150,23 @@ These files are the same on both platforms.
 | `index.js` | Starts the app through the navigation. | `AppRegistry` of the package starts `createNavigation` instead of mounting one root component. |
 | `Navigation.ts` | New: shows `App` as the first screen. | The app keeps working as it was, now as the first screen of a stack. |
 | `App.tsx` | Takes out the template's ``. | React Native's `StatusBar` logs an error on iOS once the screens set the status bar. |
+| `metro.config.js` | Wraps the exported config in `withApexNavigation`. | Fast Refresh: an edit of a screen updates the running app in place, with its state, instead of reloading it. See [Fast Refresh](#fast-refresh). |
 | `navigation-env.d.ts` | New: ties the commands to the screens of `Navigation.ts`. | The commands come from the package and can't see the app's screens. This declaration links them, so names and props are checked. See [Typed commands](#typed-commands). |
 
+### Fast Refresh
+
+`setup` wraps your `metro.config.js` in `withApexNavigation`; in a new app `init` has done it. By hand:
+
+```js
+const { withApexNavigation } = require('@apexnative/navigation/metro');
+
+module.exports = withApexNavigation(mergeConfig(getDefaultConfig(__dirname), config));
+```
+
+It does two things. React Native 0.87's transformer doesn't apply React Refresh's Babel plugin (Metro no longer passes it `hot`), and without the plugin a component that its module doesn't export loses its state at every edit. And it makes the module that imports `createNavigation` accept hot updates, so an edit of the `screens` map or of the app's config updates the running app without a reload: the screens, the default options (when `theme` or `options` changed), the roots, the listeners and the link routes. What only the start reads isn't run again: the first root, `willMount`, the splash and the context. The app's module itself runs again, as a component's module does in Fast Refresh: code at its top level (an SDK's `init`, a listener added there) runs again too, so keep such code in a module of its own that doesn't change, or make it safe to run twice. The same holds for a module the app's module imports that isn't a component, such as a store: its edit runs it and the app's module again instead of reloading the app, so a store made at the top of that module is made anew while the screens that didn't run again keep the old one. Reload the app (R) after such an edit.
+
+`doctor` warns under Fast Refresh when the Metro config doesn't use it. What to write in a screen file so that its edits update in place: [Fast Refresh](../fundamentals/screens-and-props#fast-refresh).
+
 ### Typed commands
 
 `navigation.push('Details', { props })` comes from the package, and the package doesn't know the screens of your app. One declaration links them: `setup` and `init` write it in `navigation-env.d.ts` at the root of the app.