@apexnative/navigation 0.0.0-stage → 1.0.0-alpha.1

package/docs-md/guides/error-reporting.md

@@ -0,0 +1,290 @@
+# Error reporting
+
+Every error of the app in Sentry, Bugsnag or Crashlytics, with the screen it happened on: onError, an error screen with Try again, the screens the user went through, and native crashes.
+
+A screen fails to render on a user's phone. The user should see a message and "Try again" under the screen's own bar, and you should see the error in your crash reporter, with the screen it happened on and the screens the user went through before it. You end with:
+
+- every error the navigation catches sent from one place, `onError`, with its screen;
+- an error screen with a retry, in place of a screen that failed;
+- the screens the user saw, as breadcrumbs of each report;
+- native crashes, from the first moment of the launch.
+
+The guide wires Sentry step by step, then shows the same steps for [Bugsnag](#bugsnag) and [Firebase Crashlytics](#crashlytics).
+
+> **Info**
+>
+>
+> Written against `@sentry/react-native` 8.31, `@bugsnag/react-native` 9.1 and `@react-native-firebase/crashlytics` 26 with its modular API. Know [Errors and loading](../architecture/errors-and-loading) first: where each kind of error goes.
+>
+
+## How it will work
+
+Each kind of error reaches the reporter by its own way:
+
+| The error | Reaches the reporter through |
+| --- | --- |
+| A screen fails to render | `onError` of `createNavigation`, with the screen |
+| `willMount` or the first root fails | `onError`, with `type: 'start'` |
+| A route of `linking` fails | `onError`, with the link |
+| A press handler or a promise throws | React Native's global error handler, which the reporter's SDK hooks |
+| A command can't be made | Its own promise rejects: you catch it where it matters |
+| A native crash | The reporter's native SDK |
+
+The first three are caught by the navigation and never reach React Native's global handler, so **a reporter sees them only through `onError`**. That is the one line every reporter needs here.
+
+## 1. Start Sentry before anything else
+
+```sh
+npx @sentry/wizard@latest -i reactNative
+```
+
+The wizard installs `@sentry/react-native`, sets up the upload of source maps and debug symbols, and adds `Sentry.init`. Keep the init in a module of its own, imported first in `index.js`:
+
+```ts
+import * as Sentry from '@sentry/react-native';
+
+Sentry.init({
+  dsn: 'https://<key>@<org>.ingest.sentry.io/<project>',
+});
+
+export { Sentry };
+```
+
+```js
+import './src/sentry';
+import { AppRegistry } from '@apexnative/navigation';
+import { Navigation } from './src/Navigation';
+
+AppRegistry.registerComponent('MyApp', () => Navigation);
+```
+
+Imports run in order, so Sentry starts before the modules of the screens load, and an error there is reported too. With `Sentry.init` in the body of `index.js`, after the imports, it would start after them.
+
+From now on Sentry reports by itself what reaches React Native's global handler: an error in a press handler, a promise nobody catches.
+
+## 2. Report what the navigation catches
+
+`onError` gets every error the navigation catches, with its source. Send it on, with the screen as a tag, so the reports of one screen group together:
+
+```ts
+import { createNavigation } from '@apexnative/navigation';
+import { Sentry } from './sentry';
+
+export const Navigation = createNavigation({
+  screens: { Home: HomeScreen, Profile: ProfileScreen },
+  root: 'Home',
+  onError: (error, source) => {
+    Sentry.captureException(error, (scope) => {
+      scope.setTag('source', source.type);
+      if (source.type === 'screen') {
+        scope.setTag('screen', source.screen.name);
+        scope.setContext('react', {
+          componentStack: source.componentStack,
+        });
+      }
+      if (source.type === 'link') {
+        scope.setContext('link', { url: source.url });
+      }
+      return scope;
+    });
+  },
+});
+```
+
+Profile throws while it renders: the user sees the error screen of the next step, and Sentry gets the error tagged `screen: Profile`, with the components React was in. A start that fails comes as `source: start`; a link whose route failed, with its URL.
+
+## 3. Show an error screen with a retry
+
+Without `errorFallback`, a screen that failed is empty under its bar. With it, the user sees what happened and tries again:
+
+```tsx
+import { Button, Text, View } from 'react-native';
+import type { ErrorFallbackProps } from '@apexnative/navigation';
+
+export function ErrorFallback({ retry }: ErrorFallbackProps) {
+  return (
+    <View style={{ flex: 1, justifyContent: 'center' }}>
+      <Text>Something went wrong. We have been told.</Text>
+      <Button title="Try again" onPress={retry} />
+    </View>
+  );
+}
+```
+
+```ts
+export const Navigation = createNavigation({
+  // …
+  errorFallback: ErrorFallback,
+});
+```
+
+`retry` renders the screen again; if the cause is still there, the fallback comes back, and `onError` gets the error again. When the start failed, the fallback is the first screen and `retry` runs the start again from `willMount`. More: [A screen that fails](../architecture/errors-and-loading#error).
+
+## Where Sentry.wrap goes
+
+Sentry's setup wraps the root component of the app: `export default Sentry.wrap(App)`. This app has no root component: `AppRegistry` takes the navigation, and each screen renders on its own.
+
+What `Sentry.wrap` adds is not error reporting. It wraps the component in Sentry's touch event boundary (taps as breadcrumbs), its profiler, and the provider of its feedback form. Errors don't need it; Sentry's docs say it isn't required for an app without one root component.
+
+- **With [one tree](../architecture/one-tree)**, `appProvider` is the root component of the screens' React content. Wrap it there:
+
+  ```ts
+  appProvider: Sentry.wrap(AppProvider),
+  ```
+
+  `Sentry.wrap` passes its props through, so the screens render inside it as before.
+
+- **With a root per screen**, leave it out. Wrapping `screenProvider` would start one profiler and one feedback provider for each screen.
+
+### Not Sentry.ErrorBoundary
+
+A `Sentry.ErrorBoundary` in `screenProvider` or `appProvider` looks like the place for errors of the screens, but it never sees them. Each screen has a boundary of its own, **inside** `screenProvider`, which catches the error first, shows `errorFallback`, and calls `onError`. Report through `onError`, as in step 2, and show the error with `errorFallback`.
+
+A boundary of your own deeper in a screen, around a widget that may fail, works as usual: it catches first, and the screen goes on.
+
+## 4. Breadcrumbs of the screens
+
+A report is easier to read with the screens the user went through before it. `listeners` hear every screen that appears, from the first one, for as long as the app runs:
+
+```ts
+export const Navigation = createNavigation({
+  // …
+  listeners: {
+    screenDidAppear: ({ screen }) => {
+      Sentry.addBreadcrumb({
+        category: 'navigation',
+        message: screen.name,
+        data: { id: screen.id },
+      });
+      Sentry.setTag('screen', screen.name);
+    },
+  },
+});
+```
+
+The user opens Home, Profile, then Settings, and Settings fails: the report lists the three screens, and every error, even one from a press handler, carries the tag of the screen last shown. A sheet over a screen appears as a screen of its own, so its name is the tag while it shows.
+
+Sentry's navigation integrations are written for other navigation libraries and don't hear this one's events; these listeners take their place. The names, and data of a screen worth adding, are covered in [Screen analytics](./analytics).
+
+## 5. Errors of commands
+
+A command that can't be made, such as a push to a screen that isn't in `screens`, rejects its promise and leaves the app as it was. It doesn't go to `onError`. Where a failure matters, catch it:
+
+```ts
+navigation
+  .push('Profile', { props: { id } })
+  .catch((error) => Sentry.captureException(error));
+```
+
+A rejection nobody catches is reported by Sentry as an unhandled rejection. See [When a move is done](../fundamentals/moving-between-screens#done).
+
+## 6. Native crashes
+
+`@sentry/react-native` comes with Sentry's iOS and Android SDKs, and `Sentry.init` starts them: a crash of native code, the navigation's included, is reported with the native stack.
+
+They start when the JavaScript runs `Sentry.init`. A crash before that, early in the launch, needs the native SDKs started natively: put the options in `sentry.options.json` at the root of the project, and start them first thing in the launch:
+
+- (iOS) `[RNSentrySDK start];` at the top of `application:didFinishLaunchingWithOptions:` in `AppDelegate`, before React Native starts.
+- (Android) `RNSentrySDK.init(this)` in `onCreate` of `MainApplication`.
+
+Sentry's guide "Capture App Start Errors" has the details. Check the native side with `Sentry.nativeCrash()` in a release build.
+
+## Check it
+
+1. In a screen, `throw new Error('test')` in the render. The screen shows the error screen under its bar, and Sentry gets the error with `screen` set.
+2. Tap "Try again" after removing the throw (Fast Refresh): the screen renders.
+3. Go through three screens and throw in the third: the report has the three breadcrumbs.
+
+In development, LogBox reports the caught error too; the error screen is under it.
+
+## Bugsnag
+
+```sh
+npx @bugsnag/react-native-cli init
+```
+
+The CLI installs `@bugsnag/react-native` and puts the API key in the native projects. Bugsnag starts natively, then in JavaScript:
+
+- (iOS) `[Bugsnag start];` in `application:didFinishLaunchingWithOptions:` of `AppDelegate`.
+- (Android) `Bugsnag.start(this)` in `onCreate` of `MainApplication`, after `super.onCreate()`.
+
+```ts
+import Bugsnag from '@bugsnag/react-native';
+
+Bugsnag.start();
+
+export { Bugsnag };
+```
+
+Import it first in `index.js`, as with Sentry. Then the same three places:
+
+```ts
+export const Navigation = createNavigation({
+  // …
+  onError: (error, source) => {
+    Bugsnag.notify(error as Error, (event) => {
+      event.addMetadata('navigation', { source: source.type });
+      if (source.type === 'screen') {
+        event.context = source.screen.name;
+        event.addMetadata('react', {
+          componentStack: source.componentStack,
+        });
+      }
+    });
+  },
+  listeners: {
+    screenDidAppear: ({ screen }) => {
+      Bugsnag.leaveBreadcrumb(screen.name, {}, 'navigation');
+    },
+  },
+});
+```
+
+`event.context` is what Bugsnag groups and shows a report by, so the screen's name there makes a failing screen stand out. Native crashes come from the native start above. Bugsnag's own navigation plugins are for other libraries; the listener takes their place.
+
+## Firebase Crashlytics
+
+```sh
+npm install @react-native-firebase/app
+npm install @react-native-firebase/crashlytics
+```
+
+React Native Firebase needs its native setup (the `GoogleService-Info.plist` and `google-services.json` files, the Crashlytics Gradle plugin): follow its install guide. Native crashes are then reported by Crashlytics itself. Errors the navigation catches go through `onError`:
+
+```ts
+import {
+  getCrashlytics,
+  log,
+  recordError,
+  setAttribute,
+} from '@react-native-firebase/crashlytics';
+
+const crashlytics = getCrashlytics();
+
+export const Navigation = createNavigation({
+  // …
+  onError: (error, source) => {
+    if (source.type === 'screen') {
+      setAttribute(crashlytics, 'screen', source.screen.name);
+    }
+    recordError(
+      crashlytics,
+      error instanceof Error ? error : new Error(String(error)),
+    );
+  },
+  listeners: {
+    screenDidAppear: ({ screen }) => {
+      log(crashlytics, `screen ${screen.name}`);
+    },
+  },
+});
+```
+
+`recordError` takes an `Error`, so a thrown value of another kind is wrapped. The lines of `log` go with the next report, as breadcrumbs. Crashlytics doesn't send reports from debug builds unless `crashlytics_debug_enabled` is set in `firebase.json`.
+
+## Related
+
+- [Errors and loading](../architecture/errors-and-loading): `errorFallback`, `loadingFallback`, `onError`.
+- [`onError`](/api/starting-the-app/createNavigation#onError) and [`errorFallback`](/api/starting-the-app/createNavigation#errorFallback) in the reference.
+- [Screen analytics](./analytics): the names of the screens, from the same listeners.
+- [Data fetching](./data-fetching#errors): request errors and Suspense.

package/docs-md/guides/gestures-and-animations.md

@@ -0,0 +1,381 @@
+# Gestures and animations
+
+Wire React Native Gesture Handler, Reanimated, @gorhom/bottom-sheet and Keyboard Controller into an app whose screens are native: where each provider goes, what they do next to the transitions and gestures of the platform, and what to test.
+
+> **Info**
+>
+>
+> Written against react-native-gesture-handler 3.3, react-native-reanimated 4.7 with react-native-worklets 0.13, @gorhom/bottom-sheet 5.2 and react-native-keyboard-controller 1.22. Reanimated 4.7 needs React Native 0.86 or later; on 0.85 use Reanimated 4.6 with react-native-worklets 0.12.
+>
+
+A card the user swipes away, a list that slides in, a bottom sheet of your own, a form that rises with the keyboard: these come from four libraries most React Native apps have. Each of them asks you to wrap "the root of the app". Here the screens are the platform's, and each one has React content of its own, so this guide shows where each wrapper goes and why. You end with:
+
+- gestures that work on every screen, next to the swipe back;
+- animations that start with the transition, or after it;
+- the sheets of @gorhom/bottom-sheet, and when to use the platform's sheet instead;
+- a keyboard provider that reaches every screen.
+
+## What you need
+
+- An app with `createNavigation`, and the screens of [Building a screen](./building-a-screen).
+- [One tree](../architecture/one-tree): how screens render, and the difference between `appProvider` and `screenProvider`. This guide uses both.
+- [Transitions](../architecture/transitions): the moves the platform makes between screens.
+
+## How it fits
+
+The native side moves the screens: a push, the swipe back, a sheet are UIKit's and Android's own, not JavaScript animations. React draws what is inside each screen. So:
+
+1. **Gestures and animations inside a screen** are yours, with Gesture Handler and Reanimated, as in any React Native app.
+2. **Moves between screens** are the navigation's: [presets, shared elements and the zoom](../architecture/transitions).
+3. **Each screen's content is a React root of its own** by default. With `appProvider` the screens render in one hidden React tree, and the native side moves each screen's views into its native screen.
+
+Point 3 decides where a wrapper goes. A provider that only holds React context reaches the screens from `appProvider`. A wrapper that is a native view the screen's touches must pass through, or a place where it draws, has to be inside each screen: `screenProvider`. The steps below go through each library with this rule.
+
+## 1. Gesture Handler in every screen
+
+Gesture Handler needs a `GestureHandlerRootView` above every view with a gesture, for two reasons:
+
+- `GestureDetector` checks for it in React context, and in development throws "GestureDetector must be used as a descendant of GestureHandlerRootView" without it.
+- (Android) The root view is a native view that sends the touches inside it to Gesture Handler. A gesture on a view that isn't inside one never sees a touch.
+
+Each screen is a root of its own, so a root view at the top of one screen doesn't reach the others. `screenProvider` wraps every screen:
+
+```tsx
+import type { ReactNode } from 'react';
+import { GestureHandlerRootView } from 'react-native-gesture-handler';
+
+export function ScreenProvider({ children }: { children: ReactNode }) {
+  return (
+    <GestureHandlerRootView style={{ flex: 1 }}>
+      {children}
+    </GestureHandlerRootView>
+  );
+}
+```
+
+```ts
+import { createNavigation } from '@apexnative/navigation';
+import { ScreenProvider } from './src/ScreenProvider';
+
+export const Navigation = createNavigation({
+  screens: { Home: HomeScreen, Details: DetailsScreen },
+  root: 'Home',
+  screenProvider: ScreenProvider,
+});
+```
+
+Every screen now has its own root view, and a gesture works on any of them. Modals, sheets and overlays are screens too, so they get it as well. `style={{ flex: 1 }}` lets the root view fill the screen; without a style it does the same by default, but a style of your own replaces that default.
+
+Gesture Handler 2 had `gestureHandlerRootHOC` to wrap each screen of a native navigation; version 3 has no such function. `screenProvider` does the same for every screen, with any version.
+
+### In one tree
+
+With `appProvider` all screens render in one React tree, so a `GestureHandlerRootView` in `appProvider` looks like it is above every screen. **Put it in `screenProvider` anyway**:
+
+```ts
+export const Navigation = createNavigation({
+  screens: { Home: HomeScreen, Details: DetailsScreen },
+  root: 'Home',
+  appProvider: AppProvider, // your query client, store, theme
+  screenProvider: ScreenProvider, // the root view of step 1
+});
+```
+
+In one tree the native side takes each screen's views out of the hidden tree and puts them into the native screen. A root view in `appProvider` stays behind in the hidden tree: the React context still reaches the screens, so `GestureDetector` doesn't complain, but (Android) the screen's touches never pass through that root view, and its gestures don't start. A root view in `screenProvider` moves with the screen's views, and finds the screen as its React Native root.
+
+(iOS) Gestures start without the root view's help: each one is a UIKit gesture recognizer on its own view. When a gesture starts, Gesture Handler also cancels the touch of React Native's own touchables, such as a `Pressable`, under it: it finds that touch on the root of the screen's React content, which in one tree is a React Native surface view too. A drag across a `Pressable` inside a pan doesn't fire the press, in both modes.
+
+### A first gesture
+
+A card the user drags sideways, and that springs back when let go. Gesture Handler 3 runs the callbacks on the UI thread with Reanimated:
+
+```tsx
+import Animated, {
+  useAnimatedStyle,
+  useSharedValue,
+  withSpring,
+} from 'react-native-reanimated';
+import {
+  GestureDetector,
+  usePanGesture,
+} from 'react-native-gesture-handler';
+
+export function Card() {
+  const x = useSharedValue(0);
+
+  const pan = usePanGesture({
+    activeOffsetX: [-10, 10],
+    onUpdate: (event) => {
+      x.value = event.translationX;
+    },
+    onDeactivate: () => {
+      x.value = withSpring(0);
+    },
+  });
+
+  const style = useAnimatedStyle(() => ({
+    transform: [{ translateX: x.value }],
+  }));
+
+  return (
+    <GestureDetector gesture={pan}>
+      <Animated.View style={[{ height: 120 }, style]} />
+    </GestureDetector>
+  );
+}
+```
+
+`activeOffsetX` starts the pan only after a sideways move of 10 points, so a vertical scroll of the screen around the card stays a scroll.
+
+## 2. Gestures and the swipe back
+
+(iOS) The swipe back goes from the left edge, and on iOS 26 from anywhere on the content too. A sideways gesture of your own, such as the card above, a carousel or a slider, competes with the swipe from the content. `popGesture` of the screen's options narrows the swipe back:
+
+```tsx
+import { defineScreen } from '@apexnative/navigation';
+
+export const HomeScreen = defineScreen({
+  component: Home,
+  options: (s) => s.popGesture('edge'),
+});
+```
+
+| `popGesture` | The swipe back |
+| --- | --- |
+| `true` | From the edge and from the content: the default. |
+| `'edge'` | From the edge only: a sideways drag on the content goes to your gesture. |
+| `false` | Off. The back button still works. |
+
+`'edge'` is the right choice for a screen with sideways gestures: the user still goes back from the edge. `false` is for a screen where a swipe from the edge is the content's own, such as a drawing canvas. A screen can change it while it shows, such as only while the user draws:
+
+```ts
+navigation.setOptions({ popGesture: false });
+```
+
+(Android) The system back swipes from either edge of the screen, and the app doesn't change it. Keep sideways gestures away from the very edges, or let the user start them from the middle.
+
+The ways back and `usePreventLeave`, which holds every one of them, are on [Back and gestures](../screen-ui/back-and-gestures#swipe).
+
+## 3. Gestures in a sheet
+
+A screen shown as the platform's sheet (`showModal` with `sheet`) moves with a vertical drag. A vertical gesture of yours inside it competes with that drag:
+
+- **A sideways gesture** doesn't compete: the card of step 1 works in a sheet as it is.
+- **A list** in a sheet: `expandsOnScroll: false` gives the drag to the list, and only the top of the sheet moves it. See [Put a list in it](../flows/bottom-sheets#list).
+- **A vertical pan of your own**, such as a slider that moves up and down: (Android) with `expandsOnScroll: false` the sheet takes only drags that start in its top 48 dp, and the rest go to the content. Test it on both platforms, at every detent of the sheet.
+
+## 4. Reanimated
+
+Reanimated has no provider, so a screen's content uses it with no setup of the navigation's, in a root of its own and in one tree alike. What it needs is the Babel plugin of react-native-worklets, last in the list:
+
+```js
+module.exports = {
+  presets: ['module:@react-native/babel-preset'],
+  plugins: ['react-native-worklets/plugin'],
+};
+```
+
+### Animations as the screen comes in
+
+An `entering` animation runs when its view mounts. A pushed screen mounts its content as the push starts, so the two run together: (iOS) the screen slides in while its rows fade in, and (Android) in one tree the push starts once the content has rendered, so again both start together (see [Waiting for the content](../architecture/transitions#wait)).
+
+```tsx
+import Animated, { FadeInDown } from 'react-native-reanimated';
+
+function Row({ title, index }: { title: string; index: number }) {
+  return (
+    <Animated.Text entering={FadeInDown.delay(index * 50)}>
+      {title}
+    </Animated.Text>
+  );
+}
+```
+
+Short and small animations look right during the push. For one the user should see from its start, such as a chart that grows, start it once the screen is in place. `useScreenAppear` runs after the transition has ended:
+
+```tsx
+import Animated, {
+  useAnimatedStyle,
+  useSharedValue,
+  withTiming,
+} from 'react-native-reanimated';
+import { useScreenAppear } from '@apexnative/navigation';
+
+function Chart() {
+  const progress = useSharedValue(0);
+
+  useScreenAppear(() => {
+    progress.value = withTiming(1, { duration: 600 });
+  });
+
+  const style = useAnimatedStyle(() => ({
+    transform: [{ scaleY: progress.value }],
+  }));
+
+  return <Animated.View style={[{ height: 200 }, style]} />;
+}
+```
+
+The chart stays flat while Details slides in, and grows once it is in place. `useScreenAppear` runs each time the screen appears, also when the user comes back to it from a screen over it; to grow the chart only the first time, keep a ref and return early after the first call. More on the moment each event comes: [What a screen goes through](../fundamentals/lifecycle-and-events#screen).
+
+### Animations as the screen goes
+
+The way out is native too: the back button or the swipe moves the screen out, and its React content unmounts after. So an `exiting` animation on the screen's views runs when nothing of the screen shows anymore. Use `exiting` for views that leave while the screen stays, such as a row removed from a list.
+
+### Shared elements
+
+Reanimated has shared element transitions (`sharedTransitionTag`), behind a feature flag. They are built for the screens of react-native-screens, which Reanimated finds in the React tree; the screens of this navigation are not those, so a `sharedTransitionTag` doesn't move a view from one screen into the next here.
+
+Use the navigation's own: a `nativeID` on each view, and `transition: { shared: [...] }` on the push. They work on both platforms, follow the swipe back, and need no feature flag. On (iOS) 18+ the zoom opens a screen out of a view as the system apps do. Both are on [Transitions out of a view](../architecture/transitions#views).
+
+## 5. @gorhom/bottom-sheet
+
+`BottomSheet` and `BottomSheetModal` are drawn with Gesture Handler and Reanimated, so they need step 1. `BottomSheetModal` also needs a `BottomSheetModalProvider` above it, and it goes in `screenProvider`, inside the root view, in both modes:
+
+```tsx
+import type { ReactNode } from 'react';
+import { GestureHandlerRootView } from 'react-native-gesture-handler';
+import { BottomSheetModalProvider } from '@gorhom/bottom-sheet';
+
+export function ScreenProvider({ children }: { children: ReactNode }) {
+  return (
+    <GestureHandlerRootView style={{ flex: 1 }}>
+      <BottomSheetModalProvider>{children}</BottomSheetModalProvider>
+    </GestureHandlerRootView>
+  );
+}
+```
+
+`BottomSheetModalProvider` draws its sheets in a host it renders after its children, where the provider is. In `screenProvider` that host is in the screen, so the sheet shows over the screen's content. In `appProvider` the host would be in the hidden tree of one tree, outside every screen, and a presented sheet wouldn't show.
+
+A screen presents one as the library's docs show, with a ref:
+
+```tsx
+import { useRef } from 'react';
+import { Button, Text } from 'react-native';
+import {
+  BottomSheetModal,
+  BottomSheetView,
+} from '@gorhom/bottom-sheet';
+
+function Home() {
+  const sheet = useRef<BottomSheetModal>(null);
+  return (
+    <>
+      <Button
+        title="Filters"
+        onPress={() => sheet.current?.present()}
+      />
+      <BottomSheetModal ref={sheet}>
+        <BottomSheetView>
+          <Text>Filters</Text>
+        </BottomSheetView>
+      </BottomSheetModal>
+    </>
+  );
+}
+```
+
+The sheet rises over Home's content. It is part of the screen, so it stays inside the screen: **it can't cover the top bar or the tab bar**, which are native views around the screen's content, and it goes away with the screen when the user goes back.
+
+### The platform's sheet or this one
+
+`showModal` with `sheet` shows a screen in UIKit's sheet on iOS and the Material bottom sheet on Android:
+
+```ts
+navigation.showModal('Filters', {
+  stack: false,
+  sheet: { detents: ['medium', 'large'], grabber: true },
+});
+```
+
+| You want | Pick |
+| --- | --- |
+| A sheet over everything, the bars too, that the user drags down to close | The platform's sheet |
+| The look and the detents of the system, with no code of your own | The platform's sheet |
+| A sheet that is a screen: its own options, events, a stack inside | The platform's sheet |
+| A sheet that stays inside the screen, such as a panel under a map | @gorhom/bottom-sheet's `BottomSheet` |
+| The same look of your own on both platforms, with custom handles and backdrops | @gorhom/bottom-sheet |
+
+The platform's sheet is walked through in [Bottom sheets](../flows/bottom-sheets): detents, a map kept usable under it, a list inside it, the detent the user picked.
+
+## 6. Keyboard Controller
+
+`KeyboardProvider` gives its hooks and components, such as `useKeyboardHandler` and `KeyboardAwareScrollView`, the keyboard's height as it moves. Its native view follows the keyboard of the whole window, not the touches of a screen, so where it goes depends on the mode:
+
+- **In one tree**, put it in `appProvider`, once: every screen reads the same provider.
+
+  ```tsx
+  import type { ReactNode } from 'react';
+  import { KeyboardProvider } from 'react-native-keyboard-controller';
+
+  export function AppProvider({ children }: { children: ReactNode }) {
+    return <KeyboardProvider>{children}</KeyboardProvider>;
+  }
+  ```
+
+  Its native view is in the hidden tree; it listens to the keyboard of the app's window from there. Test a form with `KeyboardAwareScrollView` on both platforms, and the interactive dismiss of the keyboard on iOS.
+
+- **With a root per screen**, put it in `screenProvider`, next to the root view of step 1. Each screen then has a provider of its own, and each one follows the keyboard while its screen is mounted, also the screens under the top one. A listener of `KeyboardEvents` outside the screens can hear the same keyboard event once for each of them; listen inside the screen that needs it, with the library's hooks.
+
+## A library asks you to wrap the app root
+
+The same questions place any library that says "wrap your app in ``":
+
+1. **It holds state in React context**, such as a store, a query client, a theme, a language. With one tree, `appProvider`: every screen shares it. Without, `screenProvider`, and each screen has a copy of its own; state the screens share then lives in a module, as [A root per screen](../architecture/one-tree#root-per-screen) shows.
+2. **It is a native view that touches pass through**, such as `GestureHandlerRootView`. `screenProvider`, in both modes: in `appProvider` the view stays in the hidden tree, away from the screens' touches.
+3. **It draws in a host of its own**: a portal, a toast, a modal of its own (`BottomSheetModalProvider`, a portal provider). `screenProvider`, in both modes: in `appProvider` the host is in the hidden tree, and what it draws doesn't show. What must show above the bars and every screen, such as a toast, belongs in an [overlay](../containers/overlays#what) instead.
+4. **It listens to the window or the app**, such as the keyboard, the orientation, the network. Once in `appProvider` with one tree; in `screenProvider` without, knowing that each mounted screen has an instance. Test it.
+5. **Its hooks need its context.** A hook works only in a screen inside its provider. `screenProvider` renders inside the screen, so the screen's own hooks, such as `useNavigation`, work in it too; `appProvider` is above every screen, and has none.
+
+When unsure, `screenProvider` is the safe place: everything in it is inside the screen, in both modes.
+
+## The whole setup
+
+The two providers of an app with one tree and all four libraries:
+
+```tsx
+import type { ReactNode } from 'react';
+import { KeyboardProvider } from 'react-native-keyboard-controller';
+
+export function AppProvider({ children }: { children: ReactNode }) {
+  return <KeyboardProvider>{children}</KeyboardProvider>;
+}
+```
+
+```tsx
+import type { ReactNode } from 'react';
+import { GestureHandlerRootView } from 'react-native-gesture-handler';
+import { BottomSheetModalProvider } from '@gorhom/bottom-sheet';
+
+export function ScreenProvider({ children }: { children: ReactNode }) {
+  return (
+    <GestureHandlerRootView style={{ flex: 1 }}>
+      <BottomSheetModalProvider>{children}</BottomSheetModalProvider>
+    </GestureHandlerRootView>
+  );
+}
+```
+
+```ts
+import { createNavigation } from '@apexnative/navigation';
+import { AppProvider } from './src/AppProvider';
+import { ScreenProvider } from './src/ScreenProvider';
+
+export const Navigation = createNavigation({
+  screens: { Home: HomeScreen, Details: DetailsScreen },
+  root: 'Home',
+  appProvider: AppProvider,
+  screenProvider: ScreenProvider,
+});
+```
+
+Without one tree, leave out `appProvider` and move `KeyboardProvider` into `ScreenProvider`, around the `BottomSheetModalProvider`.
+
+## What's next
+
+- [One tree](../architecture/one-tree): the two modes, and which to pick.
+- [Transitions](../architecture/transitions): presets, shared elements, the zoom, animations of your own.
+- [Bottom sheets](../flows/bottom-sheets): the platform's sheet, step by step.
+- [Back and gestures](../screen-ui/back-and-gestures): every way back, and how to hold it.
+- The reference: [`appProvider`](/api/starting-the-app/createNavigation#appProvider), [`screenProvider`](/api/starting-the-app/createNavigation#screenProvider), [`useScreenAppear`](/api/lifecycle-and-events/useScreenAppear).