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

package/docs-md/containers/arrangement.md

@@ -0,0 +1,320 @@
+# Arrangement
+
+Two screens as one screen of a stack: side by side on iPad, iPhone Duo open, Android tablets and open foldables, each on its side of the fold, and the main one alone on a phone.
+
+A profile and its details, a photo and the facts about it: on a phone the user sees one at a time, but a big screen has room for both. A pair puts a second screen beside the first **where the window is large**, and leaves the first alone everywhere else. A screen gets its pair with `arrangement`:
+
+```tsx
+import { Text } from 'react-native';
+import { defineScreen } from '@apexnative/navigation';
+
+function Profile({ id }: { id: string }) {
+  return <Text>Profile {id}</Text>;
+}
+
+export const ProfileScreen = defineScreen({
+  component: Profile,
+  options: (s) => s.title('Profile'),
+  arrangement: { secondary: 'Details' },
+});
+```
+
+```ts
+import { createNavigation } from '@apexnative/navigation';
+import { DetailsScreen } from './src/screens/Details';
+import { HomeScreen } from './src/screens/Home';
+import { ProfileScreen } from './src/screens/Profile';
+
+export const Navigation = createNavigation({
+  screens: {
+    Home: HomeScreen,
+    Profile: ProfileScreen,
+    Details: DetailsScreen,
+  },
+  root: 'Home',
+});
+```
+
+```ts
+// in Home, on a tap
+navigation.push('Profile', { props: { id: '7' } });
+```
+
+On a phone Profile slides in alone, as it would without `arrangement`. On iPad and on an open iPhone Duo, Details comes in beside it, under Profile's bar; back takes both. This page answers:
+
+1. [What a pair is](#what).
+2. [Two ways to make one](#two-ways): on the screen, or under a name of its own.
+3. [What each device shows](#devices).
+4. [Split and overlay](#style), and [the props of the second screen](#secondary-props).
+5. [How the pair lies now](#use-arrangement), and [when the window changes](#time).
+6. [The bar of the pair](#bar), [native screens in a pair](#native), and [a pair or a split view](#split-view).
+
+## What a pair is
+
+A pair is **one entry of a stack with two screens in it**: the primary, the screen the command names, and the secondary, beside it, under it or behind it. The native side lays the two out by the size of the window and by the fold of a device that folds, and the stack treats them as one screen:
+
+```text
+[Home]  ── push('Profile') ──▶  [Home, Profile + Details]
+        ◀──────── back ────────
+```
+
+- **Both are screens.** Each has its own id, props, events and hooks. `useNavigation()` in either acts on the stack, so a push from Details goes over the pair.
+- **The bar is the primary's**: its title, buttons, search field and toolbar. See [The bar of the pair](#bar).
+- **They come and go together.** The push shows both, back takes both.
+
+(iOS) 27.1 The pair is UIKit's `UIArrangementViewController`, which the system lays out on iPhone Duo and iPad. (Android) A container of the library does the same with the size of the window and the fold of a foldable.
+
+```tsx
+// one screen renders both parts,
+// and measures the window itself
+function Profile({ route }) {
+  const { width } = useWindowDimensions();
+  const { id } = route.params;
+  return (
+    <View style={{ flexDirection: 'row' }}>
+      <ProfileContent id={id} />
+      {width >= 700 && <Details id={id} />}
+    </View>
+  );
+}
+```
+
+```ts
+// two screens; the native side
+// places them, at the fold too
+defineScreen({
+  component: Profile,
+  arrangement: { secondary: 'Details' },
+});
+```
+
+React Navigation has no pair: one screen renders both parts and decides by the width. Here the two stay screens of their own, Details can be pushed alone too, and on a device that folds the system puts the boundary on the fold.
+
+## Two ways to make a pair
+
+| | `arrangement` of a screen | `defineArrangement` |
+| --- | --- | --- |
+| Shown by | The screen's own name: `push('Profile')`. | A name of its own: `push('ProfileWithDetails')`. |
+| Settings | The secondary, its props, `style`. | Every setting: also `axes`, `fraction`, `primaryEdge`, `compact`. |
+| A window that isn't large | The primary alone, a plain screen. | The primary alone, or the pair with `compact: 'pair'`. |
+
+### On the screen
+
+`arrangement` of `defineScreen` makes a screen the primary of a pair wherever it is shown by its name: `push`, `setStack`, `replace`, a layout, a link. It has no settings to tune: **outside a large window the screen is a plain screen**, as it is without `arrangement`, so it works on every device without a second thought. A [native screen](../architecture/native-screens) takes it too:
+
+```ts
+nativeScreen('Map', { arrangement: { secondary: 'Details' } });
+```
+
+### A pair of its own
+
+`defineArrangement` pairs two screens of `screens` under a name of its own, with every setting. The two stay screens of their own: `push('Profile')` shows Profile as its own definition says, and `push('ProfileWithDetails')` shows this pair.
+
+```ts
+import {
+  createNavigation,
+  defineArrangement,
+} from '@apexnative/navigation';
+// … the screens
+
+export const Navigation = createNavigation({
+  screens: {
+    Home: HomeScreen,
+    Profile: ProfileScreen,
+    Details: DetailsScreen,
+    ProfileWithDetails: defineArrangement<{ id: string }>({
+      primary: 'Profile',
+      secondary: 'Details',
+      compact: 'pair', // a phone shows both too
+    }),
+  },
+  root: 'Home',
+});
+```
+
+```ts
+navigation.push('ProfileWithDetails', { props: { id: '7' } });
+```
+
+The type argument is the props of the pair, which the commands check as for any screen. The settings:
+
+- **`axes`**: `'horizontal'` side by side only, `'vertical'` one above the other only, `'both'` by default. Where the window allows neither, only the primary shows.
+- **`fraction`**: the primary's share of a split, above 0 and below 1, half by default. At a fold the fold decides.
+- **`primaryEdge`**: where the primary goes when an overlay goes side by side, `'trailing'` by default.
+- **`compact`**: what a window that isn't large shows: `'primary'`, the default, or `'pair'`.
+
+A pair has two screens, never more: in a `defineArrangement`, the primary's own `arrangement` doesn't count. Every key: [`defineArrangement`](/api/arrangement/defineArrangement).
+
+## What each device shows
+
+A pair shows both screens in a **large window**: on (iOS) a window whose size classes are both regular, on (Android) a window at least 600 dp wide and 480 dp high, the sizes Material calls neither compact. With `arrangement`, or `compact: 'primary'`:
+
+| Device | What shows |
+| --- | --- |
+| iPhone, portrait and landscape | The primary alone. |
+| iPhone Duo folded | The primary alone. |
+| iPhone Duo open; iPad | The pair. An iPad window narrow enough to be compact shows the primary alone. |
+| Android phone, portrait and landscape | The primary alone. |
+| Android tablet; a foldable open | The pair. |
+| Partly folded in a large window: iPhone Duo, a foldable that opens like a book | The pair, each screen on its side of the fold. |
+| iOS before 27.1, or an app built with an older SDK | The primary alone. |
+
+Where only the primary shows, the secondary is still there, out of the window, and comes in when the window grows, as when the user opens iPhone Duo. Before iOS 27.1 there is no secondary at all: the primary is a plain screen.
+
+With `compact: 'pair'` of `defineArrangement` the pair shows everywhere: on a phone held upright, one above the other.
+
+## Split and overlay
+
+`style` says how the two share the window:
+
+- **`'split'`**, the default: side by side, or one above the other in a tall window; neither covers the other. On a partly folded device each takes one side of the fold.
+- **`'overlay'`**: the primary over the secondary, both full size, so the user sees the primary. On a partly folded device they go side by side, the primary at the trailing side.
+
+An overlay fits a screen that fills the window, and whose facts are worth the other half once the device is folded:
+
+```ts
+export const PhotoScreen = defineScreen({
+  component: Photo,
+  arrangement: { secondary: 'Details', style: 'overlay' },
+});
+```
+
+Open flat, the photo fills the window. Folded halfway, the photo takes one side and its details the other. On a phone, as with any pair of `arrangement`, the photo is alone.
+
+## The props of the second screen
+
+The props of the command go to both screens. When the secondary takes other props, `secondaryProps` makes them from those of the show:
+
+```ts
+export const ProfileScreen = defineScreen({
+  component: Profile,
+  arrangement: {
+    secondary: 'Details',
+    secondaryProps: (props) => ({ itemId: props.id }),
+  },
+});
+```
+
+`push('Profile', { props: { id: '7' } })` gives Profile `{ id: '7' }` and Details `{ itemId: '7' }`. TypeScript checks the props of the command against Profile; what `secondaryProps` returns isn't checked against Details, so keep the two in line.
+
+**The two screens share no React state.** Each screen is a React root of its own, so a `useState` of Profile doesn't reach Details. Give both the same id and read the data from a store or the app's context, as two screens of a stack do (see [State management](../guides/state-management)). With `appProvider` both render inside it, so its providers reach both (see [One tree](../architecture/one-tree)).
+
+## How the pair lies now
+
+A screen of a pair reads how it shows with `useArrangement()`. Here Profile offers a Details button only where Details isn't on screen already:
+
+```tsx
+import { Button, View } from 'react-native';
+import {
+  defineScreen,
+  useArrangement,
+  useNavigation,
+} from '@apexnative/navigation';
+
+function Profile({ id }: { id: string }) {
+  const navigation = useNavigation();
+  const pair = useArrangement();
+  // Details is beside or under Profile
+  const detailsShown =
+    pair?.layout === 'sideBySide' || pair?.layout === 'stacked';
+
+  return (
+    <View>
+      {/* … the profile */}
+      {!detailsShown && (
+        <Button
+          title="Details"
+          onPress={() =>
+            navigation.push('Details', { props: { itemId: id } })
+          }
+        />
+      )}
+    </View>
+  );
+}
+
+export const ProfileScreen = defineScreen({
+  component: Profile,
+  arrangement: {
+    secondary: 'Details',
+    secondaryProps: (props) => ({ itemId: props.id }),
+  },
+});
+```
+
+On a phone the button pushes Details; on iPad Details is beside Profile, and the button is gone.
+
+| Field | What it says |
+| --- | --- |
+| `placement` | `'primary'` or `'secondary'`: which screen of the pair this one is. |
+| `layout` | `'sideBySide'`, `'stacked'` (one above the other), `'overlay'` (one over the other, both full size), or `'single'` (one screen in the window). |
+| `front` | In an overlay: this screen lies over the other one. |
+| `hidden` | With `'single'`: this screen is the one out of the window. |
+
+The hook gives `null` in a screen outside a pair. Where there is no secondary, before iOS 27.1, the primary gets `layout: 'single'`. It works in a component of a screen, as the other hooks of a screen do. Every value: [`useArrangement`](/api/arrangement/useArrangement).
+
+## When the window changes
+
+The user opens iPhone Duo, folds it halfway, makes an iPad window narrower, or unfolds an Android foldable: the pair lays its screens out again, and `useArrangement` renders with the new state.
+
+- **A secondary that leaves the window disappears**, and appears again when it comes back: `useScreenDisappear` and `useScreenAppear` run. It stays mounted meanwhile, with its state.
+- **The first render already has a state**: the one the shape of the window makes likely, side by side in a wide window, one above the other in a tall one, the primary alone outside a large window. The first layout gives the real one, and the screen renders again when it differs.
+
+## The bar of the pair
+
+The stack shows one bar, and in a pair it is **the primary's**: its title, its buttons, its search field, its toolbar, and the options that change them later (`useScreenOptions`, `setOptions`). The system around the screen follows the primary too. What the secondary sets there has no effect:
+
+| Options of the secondary | Effect |
+| --- | --- |
+| `topBar`, `toolbar` | None: the bar and the toolbar are the primary's. |
+| `statusBar`, `layout.orientation` | None: the primary decides. |
+| (iOS) `layout.autoHideHomeIndicator`, `deferSystemGestures`, `verticalBars` | None: the primary decides. |
+| (Android) `navigationBar` | None: the primary decides. |
+| `layout.backgroundColor` | The secondary's own background, as on any screen. |
+
+A button that acts on Details goes in Profile's options, and reaches Details through the data they share, such as a store.
+
+## Native screens in a pair
+
+Either screen of a pair can be a [native screen](../architecture/native-screens): `nativeScreen` takes `arrangement` as `defineScreen` does, and `primary` and `secondary` can name a native screen. The bar is the primary's, as for React screens.
+
+`useArrangement` and `useReservedRegions` are React hooks, so a native screen doesn't get them. (iOS) Native code asks UIKit: the screen's view controller has `arrangementViewController` (iOS 27.1), the pair UIKit lays out, and its `stateForPlacement:` says how it lies. (Android) A native screen has no state of its pair.
+
+## A pair or a split view
+
+Both put screens side by side on a big screen. They answer different needs:
+
+| | [Split view](./split-view) | A pair |
+| --- | --- | --- |
+| What it is | The columns of the app, each with a stack of its own. | One entry of a stack: two screens. |
+| Where it goes | The root: `root`, `roots`, `switchTo`. | Wherever a screen is shown by its name: `push`, a layout, a link. |
+| The bar | One for each column. | One, the primary's. |
+| Back | Within a column. | Takes both screens. |
+| A pick | `showInColumn` shows it in the column beside. | The secondary stays the same: another pick pushes another pair. |
+| A phone | The `compact` layout, or the columns as one stack. | The primary alone. |
+| (iOS) | `UISplitViewController`. | `UIArrangementViewController`, iOS 27.1. |
+
+The mailboxes and messages of a mail app are a split view: the user picks, and the column beside shows the pick. A profile with its details, pushed from anywhere in the app, is a pair.
+
+## A pair that names a screen not in screens
+
+`primary` and `secondary` are names of `screens`. A name that isn't there, or one that is a `defineArrangement` itself, stops the start of the app, and the error names the pair:
+
+```text
+[navigation] The pair of 'ProfileWithDetails' names 'Detail',
+which is not in screens
+```
+
+For a screen that [loads later](../fundamentals/screens-and-props#lazy), the check runs when a command shows it, and the command fails. A secondary's own `arrangement` doesn't count: a pair has two screens, and its secondary shows as a plain screen.
+
+## A screen with a key in a pair
+
+A screen's [`key`](../fundamentals/screens-and-props#key) is its place in a stack, and in a pair that place is the pair's: the screens of a pair go without their keys. A push of a screen with both `key` and `arrangement` shows a new pair each time, and doesn't go back to one in the stack. Where the native side shows no pairs, before iOS 27.1, the primary shows alone and keeps its key, as a plain screen does: a push with the same key goes back to it.
+
+## Read next
+
+- [The fold and the camera](../screen-ui/system-ui#reserved-regions): the fold within one screen, and the hinge.
+- [Split view](./split-view): the columns of an app on iPad.
+- [Native screens](../architecture/native-screens).
+
+## API

package/docs-md/containers/modals.md

@@ -0,0 +1,195 @@
+# Modals
+
+What a modal is, how to show one, the presentation styles, sheets with detents, popovers, how a modal closes and how to ask before it does.
+
+A modal is a task of its own over the app: writing a message, a form, the sign-in, a picker. The user finishes it or cancels it, and the app is as it was. `showModal` shows one, and `dismiss` closes it:
+
+```tsx
+import { Button } from 'react-native';
+import { useNavigation } from '@apexnative/navigation';
+
+function Inbox() {
+  const navigation = useNavigation();
+  return (
+    <Button
+      title="Write"
+      onPress={() => navigation.showModal('Compose')}
+    />
+  );
+}
+```
+
+Compose comes up from the bottom over Inbox: a sheet on iOS, the whole screen on Android. A swipe down on iOS, or the system back on Android, closes it.
+
+This page answers:
+
+1. [What a modal is](#what), and how it differs from a push.
+2. [How to show one](#show).
+3. [How it looks](#styles): a sheet, full screen, a form, a popover.
+4. [Sheets](#sheets) that stop at half and full height.
+5. [How a modal closes](#close), and [how to ask before it does](#ask).
+
+## What a modal is
+
+A push continues the way the user is going; a modal **interrupts it** for a moment. That is why a modal shows over everything, tabs and bars too, and why it ends as a whole: closing it closes all its screens at once.
+
+- **It has a stack of its own,** so its screens can push: a form with several steps is one modal. With `stack: false` the screen shows alone, without a top bar.
+- **The screen under it stays mounted.** Under a full-screen modal it is out of sight. Under a sheet it still shows, so it doesn't disappear at all. See [The life of a screen](../fundamentals/screens-and-props#lifecycle).
+- **Modals go one over another.** A modal can show another; each closes on its own, or all at once.
+
+## Showing a modal
+
+`showModal` takes the screen, then its props and the settings of the modal in one object:
+
+```ts
+navigation.showModal('Compose', {
+  props: { replyTo: messageId },
+  closeButton: true,
+});
+```
+
+Compose shows with a close button at the leading edge of its top bar. The settings:
+
+| 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. |
+| `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. |
+
+`presentation.modal` of `createNavigation` sets these for every modal of the app, such as a close button everywhere: see [Defaults for the whole app](../fundamentals/moving-between-screens#presentation).
+
+## How a modal looks
+
+`style` picks how the platform presents the modal:
+
+```ts
+navigation.showModal('Compose', { style: 'fullScreen' });
+```
+
+Without `style`, a modal is a sheet on (iOS) and covers the whole screen on (Android).
+
+`'overFullScreen'` keeps the screen under the modal in place, so it shows through wherever the modal draws nothing: a dialog of your own, a card over a dimmed app. Give the modal's screen `backgroundColor('transparent')` in its options, so its own background doesn't hide the screen under it.
+
+### A form on iPad
+
+(iPadOS) A form sheet is a card in the middle of the screen. `contentSize` sets its width and height, or a height that follows the content:
+
+```ts
+navigation.showModal('EditProfile', {
+  style: 'formSheet',
+  contentSize: { width: 540, height: 'content' },
+});
+```
+
+On iPhone a form sheet is a sheet, and `contentSize` does nothing.
+
+### A popover
+
+(iPadOS) A popover points at what opened it: a button of the bar by its id (`sourceButtonId`), or a view by its `nativeID` (`sourceNativeID`):
+
+```ts
+navigation.showModal('Filters', {
+  popover: { sourceButtonId: 'filter', arrowDirections: ['up'] },
+});
+```
+
+On iPhone it becomes a sheet, unless `adaptive: false` keeps it a popover. (Android) has no popovers: the modal covers the whole screen, as without `style`.
+
+## Sheets
+
+A sheet can stop at several heights, its detents, as the sheets of the system apps do. The user drags it between them:
+
+```ts
+navigation.showModal('Places', {
+  sheet: { detents: ['medium', 'large'] },
+});
+```
+
+Places opens at half the height, the smallest detent, and the user drags it to the full height. A detent is `'medium'`, `'large'`, a height in points, or `'content'`, the height of the screen's content. The other keys of `sheet`:
+
+- **`selectedDetent`:** the detent the sheet opens at.
+- **`largestUndimmedDetent`:** up to this detent the screen under the sheet isn't dimmed and takes touches, as under the sheet of Maps.
+- **`grabber`:** the handle at the top.
+- **`expandsOnScroll: false`:** only the top drags the sheet, so a list inside it scrolls first.
+
+Each detent the user drags to sends `sheetDetentChanged`. The screen moves the sheet itself by changing its options, and the sheet follows with an animation:
+
+```ts
+navigation.setOptions({
+  modal: { sheet: { selectedDetent: 'large' } },
+});
+```
+
+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.
+
+Sheets in a real app, step by step: [Bottom sheets](../flows/bottom-sheets).
+
+## How a modal closes
+
+| Who | How |
+| --- | --- |
+| The user | A swipe down on a sheet, the system back on Android, the close button. |
+| The modal itself | `dismiss()` from any of its screens closes the whole modal. |
+| Other code | `navigation.dismissModal(id)` by the id `showModal` resolved with; `dismissAllModals()` closes every one. |
+
+Most often a modal closes itself once its task is done: the message is sent, the form is saved. Here a modal to write a message closes after Send:
+
+```tsx
+import { useState } from 'react';
+import { Button, TextInput, View } from 'react-native';
+import { useNavigation } from '@apexnative/navigation';
+
+function Compose() {
+  const navigation = useNavigation();
+  const [text, setText] = useState('');
+
+  const send = async () => {
+    await sendMessage(text); // your own request
+    await navigation.dismiss(); // the whole modal closes
+  };
+
+  return (
+    <View>
+      <TextInput value={text} onChangeText={setText} />
+      <Button title="Send" onPress={send} />
+    </View>
+  );
+}
+```
+
+In a modal of several steps, `dismiss()` on the last step closes them all at once: the user is back where they opened the modal.
+
+Whatever closed it, `onDismiss` of `showModal` runs, and the event `modalDismissed` follows. `onDismiss` is the place to update the screen that opened the modal:
+
+```ts
+navigation.showModal('Compose', {
+  onDismiss: () => refresh(), // your own step
+});
+```
+
+A new root closes the modals too: see [What a switch does](../fundamentals/switching-roots#switch).
+
+### Asking before closing
+
+A modal with unsaved changes shouldn't close on a careless swipe. `usePreventLeave` keeps it on screen while its condition is true. The swipe down, the close button and the system back on Android call its handler instead, so the screen can ask:
+
+```tsx
+import { Alert } from 'react-native';
+import { usePreventLeave } from '@apexnative/navigation';
+
+// in Compose, after its state
+usePreventLeave(text.length > 0, () => {
+  Alert.alert('Discard the draft?', undefined, [
+    { text: 'Keep editing' },
+    { text: 'Discard', onPress: () => navigation.dismiss() },
+  ]);
+});
+```
+
+While the draft is empty, the modal closes as any other. Commands aren't held, so `dismiss()` in Discard closes it. The same hook holds the back of a stack: see [Keeping the user on a screen](../screen-ui/back-and-gestures#prevent).
+
+A form in a modal, step by step: [Forms in a modal](../flows/forms-in-a-modal).
+
+## API

package/docs-md/containers/overlays.md

@@ -0,0 +1,109 @@
+# Overlays
+
+What an overlay is and what it is for, how to show and close one, where the touches go, the keyboard, and how overlays live with modals and roots.
+
+An overlay shows over the whole app **without taking the place of any screen**: a toast, a dialog of your own, a mini player, a banner. The user goes on with the app under it. `showOverlay` shows one:
+
+```ts
+import { navigation } from '@apexnative/navigation';
+
+navigation.showOverlay('Toast', { props: { text: 'Saved' } });
+```
+
+The Toast screen shows over everything, and the screen under it still scrolls and takes taps.
+
+This page answers:
+
+1. [What an overlay is](#what), and what it is for.
+2. [How to show and close one](#show).
+3. [Where the touches go](#touches).
+4. [The keyboard](#keyboard) in an overlay.
+5. [Overlays, modals and roots](#layers).
+
+## What an overlay is
+
+A push or a modal moves the user somewhere. An overlay doesn't move anyone: it puts a screen **on top of everything**, and the app goes on under it.
+
+An overlay is a screen of `screens` like any other: a component, its props, its options. It shows above the tabs, the bars and the modals; on (iOS) it is in a window of its own. Its background is transparent, so the app shows wherever the overlay draws nothing. What overlays are for:
+
+## Showing and closing
+
+`showOverlay` takes the screen and its props, and resolves with the id of the overlay. An overlay usually closes itself: a toast after a moment, a dialog when the user answers. `dismiss()` from the overlay's own screen closes it:
+
+```tsx
+import { useEffect } from 'react';
+import { Text } from 'react-native';
+import { useNavigation } from '@apexnative/navigation';
+
+function Toast({ text }: { text: string }) {
+  const navigation = useNavigation();
+
+  useEffect(() => {
+    const timer = setTimeout(() => navigation.dismiss(), 2000);
+    return () => clearTimeout(timer);
+  }, [navigation]);
+
+  return <Text style={{ padding: 16 }}>{text}</Text>;
+}
+```
+
+The toast shows for two seconds and goes. Other code closes an overlay by the id `showOverlay` resolved with, `navigation.dismissOverlay(id)`, or all of them with `dismissAllOverlays()`.
+
+## Where the touches go
+
+An overlay covers the whole window, but only its views take touches. **Where it draws nothing, the touches reach the app under it**, so a toast or a mini player doesn't stop the user:
+
+| The overlay | Touches outside its views |
+| --- | --- |
+| A toast, a mini player, a banner | Reach the app: the user scrolls and taps under it. |
+| A dialog with a dimmed backdrop | Land on the backdrop, which is a view of the overlay: the app gets nothing until the user answers. |
+
+A view that fills the overlay only to place its content, such as a wrapper that puts a toast at the bottom, takes the touches too. `pointerEvents="box-none"` on it lets them through to the app.
+
+A small overlay that should still stop the app, without drawing a backdrop, says so with `blockTouches: true`:
+
+```ts
+navigation.showOverlay('Confirm', { blockTouches: true });
+```
+
+## The keyboard
+
+A text field in an overlay gets the keyboard as one on a screen does: the user taps it, and the keyboard comes up for the overlay. A form in an overlay, such as a quick note over the app, needs no setting.
+
+## Overlays, modals and roots
+
+Overlays stay on top whatever the app does under them:
+
+| When | The overlays |
+| --- | --- |
+| A modal shows | Stay over it. |
+| The user pushes, switches tabs | Stay on top; the app moves under them. |
+| `switchTo` replaces the root | Stay: a call in progress goes on while the user signs out. See [What a switch does](../fundamentals/switching-roots#switch). |
+| `dismissAllOverlays()` | Close, all of them. |
+
+Overlays don't count in what the user sees: `getState()` names the screen under them. An overlay has no stack of its own, so **its commands act on the app under it**.
+
+A banner of a new message shows over whatever the user is doing. A tap on it opens the chat in the stack the user is looking at, and the banner goes:
+
+```tsx
+import { Pressable } from 'react-native';
+import { useNavigation } from '@apexnative/navigation';
+
+function MessageBanner({ chatId }: { chatId: string }) {
+  const navigation = useNavigation();
+
+  const open = async () => {
+    // into the stack under the banner: Inbox → … → Chat
+    await navigation.push('Chat', { props: { chatId } });
+    await navigation.dismiss(); // the banner goes
+  };
+
+  return <Pressable onPress={open}>{/* … */}</Pressable>;
+}
+```
+
+Back from the chat returns to the screen the user was on.
+
+A mini player works the same way, but its full player usually opens as a modal, `showModal('Player')`. While the full player shows, the mini player hides itself: it reads what the user sees with `useNavigationState`. See [What the user sees now](../fundamentals/lifecycle-and-events#state).
+
+## API