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

package/cli/doctor/checks/splash.js

@@ -17,34 +17,16 @@ const CIRCLE = 192;
 const LOGO_HEIGHT = /<dimen name="apex_navigation_splash_logo_height">([\d.]+)dp<\/dimen>/;
 
 /**
- * The native splash: made from its settings in package.json on both platforms, its logo whole on Android 12+; without
- * settings, a launch screen the navigation can't keep on screen until the first screen draws.
+ * The native splash: made from its settings in package.json on both platforms, its logo whole on Android 12+. Without
+ * settings there is nothing to check: the navigation keeps a copy of a storyboard and of `UILaunchScreen` alike.
  * @param {string} root
  * @param {Project} project
  * @returns {Check[]}
  */
 function splashChecks(root, project) {
-  const plist = project.infoPlist && fs.readFileSync(project.infoPlist, 'utf8');
   const saved = readConfig(root).splash;
-  if (!saved) {
-    // UILaunchScreen alone: iOS shows it, but the navigation keeps only a storyboard while the first screen renders.
-    if (
-      plist?.includes('<key>UILaunchScreen</key>') &&
-      !plist.includes('<key>UILaunchStoryboardName</key>')
-    ) {
-      return [
-        {
-          group: 'app',
-          title: 'Launch screen',
-          status: 'warn',
-          detail:
-            'UILaunchScreen in Info.plist: an empty window shows between it and the first screen',
-          fix: SPLASH,
-        },
-      ];
-    }
-    return [];
-  }
+  if (!saved) return [];
+  const plist = project.infoPlist && fs.readFileSync(project.infoPlist, 'utf8');
   const resolved = resolveSettings(root, {}, saved);
   if ('errors' in resolved) {
     return [

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/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.
+
+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.
 
 ### 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
 

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. |
@@ -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; 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.
 
 ## 8. Close it with a pick
 

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

@@ -311,7 +311,7 @@ Each file and why: [What the command writes](./splash-screen#files).
 - **The settings** go into `package.json`, under `apexNavigation.splash`. An option given replaces its saved value; to drop the dark logo or color, remove `darkLogo` or `darkBackground` there and run the command again.
 - **A logo whose corners leave the circle** of Android 12's splash icon, 192 dp, gets a warning: Android cuts them. Make `--logo-width` smaller, or give the logo room around it.
 - **A file it can't change** is listed as `manual`, with the change to make: an app without `Images.xcassets` next to `Info.plist`, a manifest whose `MainActivity` and `<application>` have no theme to go over.
-- **`Info.plist` with `UILaunchScreen`** as well gets a warning: remove that dictionary, so that iOS shows the storyboard.
+- **`Info.plist` with `UILaunchScreen`** as well gets a warning: iOS shows that dictionary instead of the storyboard, so remove it.
 - **Its errors** in the JSON: `splash-settings` for a setting it can't take, `splash-image` for a logo it can't read or that doesn't fit (too tall at its width, a dark logo of other proportions), and `sharp-missing`, as for `icons`.
 
 `doctor` checks the splash in the App group:
@@ -320,7 +320,6 @@ Each file and why: [What the command writes](./splash-screen#files).
 | --- | --- |
 | Splash | The files of iOS or Android aren't made from the settings in `package.json`: changed by hand, made on one platform only, or by an older version of the command. Or the settings themselves are wrong, such as a logo that isn't there. |
 | Splash logo | The logo's corners leave Android 12's circle. |
-| Launch screen | Without settings: `Info.plist` has `UILaunchScreen` and no storyboard. iOS shows it at launch, but the navigation can only keep a storyboard on screen, so an empty window shows between it and the first screen. |
 
 Each warning names its fix, such as `npx apex-navigation splash`; `--fix` leaves these to you. What the user sees, and a splash of your own after the native one: [Splash screen](./splash-screen).
 

package/docs-md/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

@@ -232,9 +232,9 @@ A signed-in user sees Login for a moment, then the app.
 
 (iOS) Between the launch screen and the first screen, the window is empty for a moment.
 
-**Why:** the launch screen is made with the `UILaunchScreen` dictionary of `Info.plist`, not a storyboard. The navigation keeps a copy of a storyboard on screen until the first root, and can't make one of the dictionary. `doctor` warns about it under Launch screen.
+**Why:** the app has no launch screen the navigation can copy: `Info.plist` names no storyboard and has no `UILaunchScreen` dictionary (or `UILaunchScreens` default), and no legacy launch images.
 
-**Fix:** run `npx apex-navigation splash`, or name a storyboard in `UILaunchStoryboardName` and remove `UILaunchScreen`. More: [Make the native splash](../guides/splash-screen#command).
+**Fix:** run `npx apex-navigation splash`, or name a storyboard in `UILaunchStoryboardName`. More: [Make the native splash](../guides/splash-screen#command).
 
 ### Android brings the app back without its pushed screens
 
@@ -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.

package/docs-md/index.json

@@ -856,6 +856,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 +982,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"
@@ -4092,6 +4100,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

@@ -106,6 +106,31 @@ export const MapScreen = defineScreen({
 
 The preview shows when back pops the screen with the default transition. It doesn't when back does something else first, or when the app takes it: a menu or a search that closes, a screen that holds back (`hardwareBackButton.popStackOnPress: false`, a [`BackHandler` listener](#back-handler), `usePreventLeave`), or a pop with an animation of its own (`animations.pop`). On Android 13 and older the screen pops when the swipe ends.
 
+`animations.pop.preview: false` turns the preview off for a screen: the gesture shows nothing, and the screen pops when the user lets go, as on Android 13. It is read from the screen that goes, so the app's `options` turn it off everywhere:
+
+```ts
+defineScreen({
+  component: Checkout,
+  options: { animations: { pop: { preview: false } } },
+});
+```
+
+iOS ignores it: the swipe back there is UIKit's.
+
+### The preview of a sheet closing
+
+(Android) 14+ The back gesture over a modal sheet that back would close shows the close before the user lets go: the sheet shrinks a little toward the bottom as the swipe goes on, and the dimming behind it follows. Letting go slides the sheet down and closes it exactly as a swipe down does, with the same events and the same answers (`onDismiss`, `modalDismissed`). Swiping back cancels, and the sheet returns.
+
+There is no preview, and the sheet closes when the swipe ends (at once for a button press), when:
+
+- the sheet has several detents and is above its lowest one: the sheet can be hidden only at the lowest detent, so back closes it right there, as before;
+- its screen holds back: `hardwareBackButton.dismissModalOnPress: false`, a [`BackHandler` listener](#back-handler), `usePreventLeave`;
+- a screen pushed inside the sheet pops first: that pop keeps [its own preview](#pop-preview);
+- the modal can't be swiped down (`swipeToDismiss: false`);
+- the sheet is the only modal over no root.
+
+On Android 13 and older the sheet closes when the swipe ends. iOS keeps UIKit's sheet: nothing changes there.
+
 ### Back to the home screen
 
 (Android) On the first screen of the app, with nothing left to go back to, the navigation leaves the back to the system. The system then plays its predictive back animation: as the user swipes, the app shrinks and the home screen shows behind it, and the user can still change their mind halfway. The system decides this as the swipe starts, so the navigation takes the back only while it has something to do with it: a screen to pop, a modal, a menu or a search to close, a tab to go to (`backBehavior`), or a [`BackHandler` listener](#back-handler) of the app.
@@ -122,6 +147,17 @@ Without it, back on the first screen still leaves the app, at once. See [What se
 
 With the animation on, the system leaves the app itself: an `invokeDefaultOnBackPressed` of the app's `MainActivity` (such as `moveTaskToBack(true)`) isn't called on the first screen. Without it, and before Android 13, the back goes through the activity as before.
 
+`hardwareBackButton.systemAnimation: false` keeps the back in the app on the first screen too, so the system plays no animation there: the gesture shows nothing, and on release the press goes to the [`BackHandler` listeners](#back-handler), then to the activity's own back, `invokeDefaultOnBackPressed` included. It is read from the screen back acts on; for the whole app, set it in the app's `options`:
+
+```ts
+createNavigation({
+  // …
+  options: { hardwareBackButton: { systemAnimation: false } },
+});
+```
+
+iOS ignores it.
+
 ### Handling back yourself: BackHandler
 
 (Android) React Native's `BackHandler` works on every screen, as in any React Native app. A listener runs before the navigation's own back: returning `true` takes the press, `false` passes it on to the next listener, then to the navigation.

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

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

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

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

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

@@ -29,12 +29,12 @@ The status bar sits at the top, with the camera cutout in it; the home indicator
 
 ## The safe area
 
-The safe area is where nothing covers the content: not the bars of the navigation, not the status bar, not the cutout, not the home indicator. **The navigation keeps every screen in it by default**, so a screen doesn't need its own padding:
+The safe area is where nothing covers the content: not the bars of the navigation, not the status bar, not the cutout, not the home indicator. **The navigation keeps every screen's top and sides in it by default**, so a screen doesn't need its own padding there. The bottom is not padded: the content goes down to the edge, under the home indicator, the navigation bar and a tab bar or toolbar, and a list adds `useSafeAreaInsets().bottom` to its own padding, as with `react-native-safe-area-context`.
 
 | Platform | By default |
 | --- | --- |
-| (iOS) | Every edge, except one under a bar that shows: a list goes under the top bar and keeps its rows clear itself, so the bar's glass shows the content scrolling under it. A screen with a large title leaves the top out too, and on iPhone Duo the side of the [vertical bar](#vertical-bar). |
-| (Android) | All four edges: under the status bar, out of the cutout, above the navigation bar. |
+| (iOS) | The top and the sides, but not the top under a top bar that shows: a list goes under the bar and keeps its rows clear itself, so the bar's glass shows the content scrolling under it. A screen with a large title leaves the top out too, and on iPhone Duo the side of the [vertical bar](#vertical-bar). The bottom goes under the home indicator and under a tab bar or toolbar. |
+| (Android) | The top and the sides: under the status bar, out of the cutout. The top is free under a top bar that hides on scroll and under a large title. The bottom goes under the navigation bar, when the screen draws under it (not with an opaque bar), and under the tabs only with `bottomTabs.drawBehind` or `hideOnScroll`. |
 
 > **Tip**
 >
@@ -47,6 +47,12 @@ A screen that should go under the system, such as a photo or a map, says which e
 ```ts
 s.safeArea('bottom'); // only the bottom: the photo goes under the top
 s.safeArea(); // no edge: the content goes everywhere
+s.safeArea('top', 'left', 'right', 'bottom'); // all four: a form above the home indicator
+
+// listed edges replace the default: this one loses
+// the sides; under a large title the top stays free,
+// because the list keeps clear of the bar itself
+s.safeArea('top', 'bottom');
 ```
 
 The edges for every screen of the app go in `createNavigation`, and a screen's own `safeArea` wins over them:
@@ -54,11 +60,11 @@ The edges for every screen of the app go in `createNavigation`, and a screen's o
 ```ts
 export const Navigation = createNavigation({
   // …
-  safeArea: { edges: ['top', 'bottom'] },
+  safeArea: { edges: ['top', 'left', 'right', 'bottom'] },
 });
 ```
 
-Content that keeps clear of the system itself, such as a list that scrolls under the home indicator, reads what still covers it with `useSafeAreaInsets()`. The insets are **what is left after the screen's own padding**: 0 on an edge the screen keeps, all of what covers it on an edge its content goes under. So the content adds them to its own padding, and no edge is padded twice. Here the screen keeps the top only, and the list pads its own bottom:
+Content that keeps clear of the system itself, such as a list that scrolls under the home indicator, reads what still covers it with `useSafeAreaInsets()`. The insets are **what is left after the screen's own padding**: 0 on an edge the screen keeps, all of what covers it on an edge its content goes under. So the content adds them to its own padding, and no edge is padded twice. Here the screen keeps the top and the sides by default, and the list pads its own bottom:
 
 ```tsx
 import { ScrollView } from 'react-native';
@@ -71,7 +77,7 @@ function Inbox() {
   const insets = useSafeAreaInsets();
   return (
     <ScrollView
-      contentContainerStyle={{ paddingBottom: insets.bottom }}
+      contentContainerStyle={{ paddingBottom: 16 + insets.bottom }}
     >
       {/* the rows scroll under the home indicator,
           and the last one ends above it */}
@@ -80,12 +86,11 @@ function Inbox() {
 }
 
 export const InboxScreen = defineScreen({
-  component: Inbox,
-  options: (s) => s.safeArea('top'),
+  component: Inbox, // the default edges: the top and the sides
 });
 ```
 
-On a screen that keeps the bottom edge, the default on Android and on iOS without a bar at the bottom, `insets.bottom` is 0, so the same code works there: the content is already above the home indicator. Below a top bar the top inset is 0; on a screen drawn behind the bars it is their height. On (iOS) a scroll view with `contentInsetAdjustmentBehavior="automatic"` keeps clear of the bars by itself: leave the inset out on those edges. More: [The insets and the safe area of the screen](/api/system-ui/useSafeAreaInsets#safe-area).
+On a screen that lists `'bottom'` in its edges, `insets.bottom` is 0, so the same code works there: the content is already above the home indicator. Below a top bar the top inset is 0; on a screen drawn behind the bars it is their height. On (iOS) a scroll view with `contentInsetAdjustmentBehavior="automatic"` keeps clear of the bars by itself: leave the inset out on those edges. More: [The insets and the safe area of the screen](/api/system-ui/useSafeAreaInsets#safe-area).
 
 ### The vertical bar of iPhone Duo
 
@@ -231,7 +236,7 @@ export const PhotoScreen = defineScreen({
 | Platform | The bottom |
 | --- | --- |
 | (iOS) | The home indicator. `layout.autoHideHomeIndicator` fades it out while the screen isn't touched, as in a video. `layout.deferSystemGestures` makes the first swipe on those edges go to the app, for a game or a drawing; the second swipe goes home. |
-| (Android) | The navigation bar: a handle, or three buttons. The screen goes under it, and its safe area keeps the content above it. `navigationBar` sets its `backgroundColor`, hides it with `visible: false`, or puts the screen above it with `drawBehind: false`. |
+| (Android) | The navigation bar: a handle, or three buttons. The screen goes under it, and by default so does the content; a list adds `insets.bottom`. With an opaque bar or `drawBehind: false` the screen ends above it. `navigationBar` sets its `backgroundColor`, hides it with `visible: false`, or puts the screen above it with `drawBehind: false`. |
 
 (Android) The screen goes edge to edge as the platform says: always on Android 16+ for apps targeting SDK 36, on Android 15 for SDK 35, and on every version with `edgeToEdgeEnabled=true` in `android/gradle.properties`, the default of new React Native apps.
 
@@ -274,7 +279,7 @@ export const Navigation = createNavigation({
 s.scrollEdgeEffect({ top: { style: 'hard' } });
 ```
 
-The effect belongs to the scroll views of the screen, so a list that mounts after the screen shows gets it the next time the screen appears. Render the list at once, and fill it when the data comes.
+The effect applies to the vertical lists and text views of the screen when it shows, so a list that mounts after the screen shows gets it the next time the screen appears. A list nested very deep in the screen's views may not get it. A list inside another vertical list, like a horizontal carousel in a feed, gets none: UIKit draws no edge effect there. Render the list at once, and fill it when the data comes.
 
 ## Keyboard shortcuts
 

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

@@ -46,10 +46,10 @@ Filter sits at the leading edge and Compose at the trailing one. The buttons are
 | Item | What it does |
 | --- | --- |
 | `{ systemItem: 'flexibleSpace' }` | Takes the free width, and pushes the next buttons to the far side. |
-| `{ systemItem: 'fixedSpace' }` | A gap. On iOS 26 it also starts a new glass capsule. |
+| `{ systemItem: 'fixedSpace' }` | A gap. With the glass design it also starts a new glass capsule. |
 | `{ systemItem: 'searchField' }` | iOS 26: the search field of the screen, between the buttons. See [Search](./search#toolbar). |
 
-On iOS 26 icons next to each other share one glass capsule; a text button has one of its own, and a `badge` doesn't show in the toolbar. `visible: false` hides the toolbar with its buttons.
+With the glass design ([what it is](./top-bar#glass-design)) icons next to each other share one glass capsule; a text button has one of its own, and a `badge` doesn't show in the toolbar. `visible: false` hides the toolbar with its buttons.
 
 On iPhone with iOS 26 the floating tab bar takes the same place at the bottom. A screen with a toolbar inside [tabs](../containers/tabs) hides the tab bar with `hideBottomTabs()`.
 

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

@@ -31,6 +31,10 @@ The top bar belongs to **the stack, not to a screen**: one bar for all the scree
 
 The platform draws the bar: `UINavigationBar` on (iOS), with Liquid Glass on iOS 26, and the Material 3 top app bar on (Android). Its colors come from the [theme](../architecture/theme-and-context) until a screen sets its own.
 
+## The glass design and the compatibility mode
+
+On (iOS) the look of iOS 26 (Liquid Glass) is *the glass design*, and this page and [the bar buttons](./bar-buttons) call it that. An app in the compatibility mode (`UIDesignRequiresCompatibility = YES` in Info.plist) doesn't get it: the mode applies on iOS 26, and on iOS 27 only to an app built with an SDK before iOS 27. There the bar looks and behaves as before iOS 26: a title with a subtitle as two lines only when no large title can show (with a large title the subtitle shows nowhere), no capsules (`title.glass`, `hideSharedBackground` and `group` do nothing), `style: 'prominent'` is a bold Done button, the back button shows the title of the screen below, `background.color` gives an opaque bar, and a large title is drawn in the bar. [The bottom tabs](../containers/tabs) follow the same mode.
+
 ## The title
 
 The title is the name of the screen. The subtitle is a second line under it, such as a status or a count. Both can come from the props of the screen:
@@ -84,20 +88,20 @@ s.title('Details').largeTitle({ displayMode: 'never' });
 
 ## The background and the border
 
-On iOS 26 the bar is Liquid Glass, and the content shows through it as it scrolls under. **A color takes the glass away**, so set one only when the design needs it:
+With the glass design the bar is Liquid Glass, and the content shows through it as it scrolls under. **A color takes the glass away**, so set one only when the design needs it:
 
 ```ts
 s.topBar({ background: { color: '#F3E9D2' }, noBorder: true });
 ```
 
-`background.color` colors the bar on both platforms. With a large title on iOS 26 the color goes behind the title in the list, and fills the bar once the title collapses. Under a bar with a color the list has no edge effect at the top: see [The edge of the scroll](./system-ui#scroll-edge).
+`background.color` colors the bar on both platforms. With a large title and the glass design the color goes behind the title in the list, and fills the bar once the title collapses. Under a bar with a color the list has no edge effect at the top: see [The edge of the scroll](./system-ui#scroll-edge).
 
 The other keys of the background are rarer:
 
 | Option | What it does |
 | --- | --- |
 | `background.component` | A component of `screens` drawn behind the bar, such as a gradient. It is registered as the [title component](#title-component) is. |
-| `background.translucent` | (iOS) `true`: the content shows through; Liquid Glass on iOS 26, where it is the default. `false`: a solid bar, white in the light theme and black in the dark one. |
+| `background.translucent` | (iOS) `true`: the content shows through; Liquid Glass with the glass design, where it is the default. `false`: a solid bar, white in the light theme and black in the dark one. |
 | `background.blur` | (iOS) The system's frosted blur, plainer than the glass. A `color` wins over it, and it wins over `translucent`. |
 | `scrollEdgeAppearance` | (iOS) The look of the bar while the content is at its top, with `active: true`. The bar takes its usual look once the content scrolls under it. |
 
@@ -132,7 +136,7 @@ The bar can also hide and show by itself:
 | `hideOnKeyboard` | (iOS) Hides while the keyboard shows. |
 | `animate` | `false`: hides and shows at once, without the animation. |
 
-With `hideOnScroll` the screen goes under the bar, so its rows show where the bar was. Its list keeps its first rows clear: on (iOS) with `contentInsetAdjustmentBehavior="automatic"`, on (Android) with `paddingTop: useSafeAreaInsets().top`.
+With `hideOnScroll` the screen goes under the bar, so its rows show where the bar was. Its list keeps its first rows clear: on (iOS) with `contentInsetAdjustmentBehavior="automatic"`, on (Android) with `paddingTop: useSafeAreaInsets().top`. The bottom edge is not padded by default, so the list also adds `useSafeAreaInsets().bottom` to its bottom padding (an iOS list with `contentInsetAdjustmentBehavior="automatic"` does it itself).
 
 `drawBehind: true` keeps the bar and puts the content under it, as a map or a photo under a glass bar.
 

package/docs-md/start/installation.md

@@ -215,7 +215,7 @@ export {};
 
 | Group | What it checks |
 | --- | --- |
-| App | React Native and the New Architecture, the package, the files `setup` sets up, the entry point, React Native loaded twice, the status bar of the template, the generated code of native screens. Typed commands: `navigation-env.d.ts` there, pointing to the navigation, with its `context` line, and read by `tsconfig.json`. The splash screen made from its settings, with its logo inside the circle of Android's splash icon, and an iOS launch screen made with `UILaunchScreen` and no storyboard, which the navigation can't keep on screen. The app icon made from its settings, and an iOS icon set with no image, which the App Store refuses. |
+| App | React Native and the New Architecture, the package, the files `setup` sets up, the entry point, React Native loaded twice, the status bar of the template, the generated code of native screens. Typed commands: `navigation-env.d.ts` there, pointing to the navigation, with its `context` line, and read by `tsconfig.json`. The splash screen made from its settings, with its logo inside the circle of Android's splash icon. The app icon made from its settings, and an iOS icon set with no image, which the App Store refuses. |
 | Navigation | From the app's code. Screens: no name given twice in `screens` and the groups, and no file of the screens' folder with a `defineScreen` or `nativeScreen` that no file imports, a screen made and never added. Links: each prefix of `linking` declared on both platforms, the declarations no prefix has, a main activity that isn't `singleTask`. Screen names, in a JavaScript app only: a name that `push`, `replace`, `showModal` or `showInColumn` gives and no screen has, with its file and line. |
 | (Android) | JDK 17 in use, the Android SDK, `minSdk`, how edge-to-edge works in the app. |
 | (iOS) | Xcode 26 or newer, CocoaPods, the pods of the navigation and whether they are out of date, the iOS version of the Podfile. |

package/ios/Animations/ANNFrameDriver.mm

@@ -1,6 +1,7 @@
 #import "ANNFrameDriver.h"
 #import "ANNAssert.h"
 #import "ANNCurve.h"
+#import "ANNTransformParts.h"
 #import <QuartzCore/QuartzCore.h>
 
 // The display link holds its target strongly and the run loop holds the link: the driver is reached weakly, so a driver
@@ -57,6 +58,7 @@
     ANNAssertMainQueue();
 #if DEBUG
     ANNCurveSelfCheck();
+    ANNTransformPartsSelfCheck();
 #endif
     if (_link) {
         return;