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

package/docs-md/fundamentals/lifecycle-and-events.md

@@ -0,0 +1,224 @@
+# Lifecycle and events
+
+The events of a screen and of the whole app, their order in one move, where to listen to them, what the user sees now, and every event the navigation sends.
+
+An inbox loads new messages each time the user comes back to it; a video stops when another screen covers it; analytics logs every screen the user opens. The platform runs the navigation, so JavaScript learns what happened from events: a screen appeared, the user pressed a button of the bar, picked a tab, swiped a sheet down. A screen hears its own with hooks:
+
+```tsx
+import { useScreenAppear } from '@apexnative/navigation';
+
+function Inbox() {
+  useScreenAppear(() => {
+    refetch(); // your own request
+  });
+  // …
+}
+```
+
+Inbox loads its messages when it first shows, and again each time the user comes back to it. This page answers:
+
+1. [What a screen goes through](#screen), and the order of the events in one move.
+2. [The hooks of a screen](#hooks): to refresh on appear, to stop work while covered.
+3. [Where to listen](#where): in a screen, in any component, outside React, for the whole run.
+4. [What the user sees now](#state).
+5. [Every event](#events) the navigation sends.
+
+## What a screen goes through
+
+A screen mounts once and appears many times: each time the user comes back to it from a screen over it, from another tab, from a modal. **Mounted and on screen are two different lines**, as [The life of a screen](./screens-and-props#lifecycle) shows. The events follow the second line:
+
+| Event | When |
+| --- | --- |
+| `screenWillAppear` | The screen starts to come in: the move begins. |
+| `screenDidAppear` | The screen is in place: the move has ended. |
+| `screenDidDisappear` | The screen is covered, or has left. |
+
+### The order in one move
+
+Home pushes Details. Each screen and the app get their events in this order:
+
+- **Details** gets `screenWillAppear` when the move starts, and `screenDidAppear` when it ends.
+- **Home** gets `screenDidDisappear` once Details covers it. It stays mounted.
+- **The app**: once the move has ended, `stateChanged` tells that Details is now the screen the user sees, and then `push` resolves. Code after `await navigation.push('Details')` reads Details in `getState()`.
+
+Back from Details plays it in reverse: Home appears again, Details disappears and unmounts.
+
+## The hooks of a screen
+
+Inside a screen, hooks listen to the events of that screen only, and stop when it unmounts:
+
+| Hook | Runs |
+| --- | --- |
+| `useFocusEffect(effect)` | The effect each time the screen gets the focus; its cleanup each time it loses it. |
+| `useScreenAppear(handler)` | Each time the screen appears. |
+| `useScreenDisappear(handler)` | Each time it disappears. |
+| `useIsFocused()` | Not an event: `true` while the user is on this screen. |
+| `useScreenEvent(name, handler)` | Any other event of this screen, by its name in [Every event](#events). |
+
+**Work that goes on only while the user is on the screen**, such as a timer, a subscription, a camera, belongs in `useFocusEffect`. It starts when the screen gets **the focus**: the screen has appeared, and nothing covers it. It stops when the screen loses it: a screen pushed over it, another tab, a modal or a sheet over it. A covered screen costs nothing.
+
+```tsx
+import {
+  useFocusEffect,
+  useIsFocused,
+  useScreenEvent,
+} from '@apexnative/navigation';
+
+// in a screen
+useFocusEffect(() => {
+  const timer = setInterval(reload, 30_000); // your own reload
+  return () => clearInterval(timer);
+});
+```
+
+The timer stops while a pushed screen or a sheet covers this one, and starts again when the user comes back. Screens side by side in a split view keep the focus, each of them: see [When the effect runs](/api/lifecycle-and-events/useFocusEffect#timing).
+
+**Fresh data each time the user comes back** is `useScreenAppear`, as in Inbox at the top of this page.
+
+**What renders differently while the screen isn't in front** reads `useIsFocused()`: `true` while this is the screen the user sees, the one of [the navigation state](#state). Under a sheet the screen still shows and doesn't disappear, but the user is in the sheet: `useIsFocused()` is `false`, and `useFocusEffect` has cleaned up.
+
+```tsx
+const focused = useIsFocused();
+return <Player paused={!focused} />; // your own player
+```
+
+**Any other event of the screen** has its name. Here a screen in a sheet shows more once the user drags the sheet to full height:
+
+```tsx
+useScreenEvent('sheetDetentChanged', ({ detent }) => {
+  setExpanded(detent === 'large');
+});
+```
+
+The events of the parts of a screen have hooks of their own on their pages: `useNavigationButton` on [Bar buttons](../screen-ui/bar-buttons), `useSearchBar` on [Search](../screen-ui/search), `useTabPress` on [Tabs](../containers/tabs).
+
+## Where to listen
+
+The same events can be heard in four places. Each one is **a narrower scope** than the one around it:
+
+**For the whole run**, such as the screens for analytics, `listeners` of `createNavigation`. They work from the first screen, before any component mounts:
+
+```ts
+export const Navigation = createNavigation({
+  // …
+  listeners: {
+    // your own analytics
+    screenDidAppear: ({ screen }) => trackScreen(screen.name),
+  },
+});
+```
+
+**From code outside React**, such as a store, `navigation.on`. It returns the function that stops listening:
+
+```ts
+import { navigation } from '@apexnative/navigation';
+
+const stop = navigation.on('modalDismissed', () => {
+  refreshBadge(); // your own step
+});
+// later
+stop();
+```
+
+**In a component that isn't a screen**, or for the events of every screen, `useNavigationEvent`. It listens while the component is mounted:
+
+```tsx
+import { useNavigationEvent } from '@apexnative/navigation';
+
+// in any component
+useNavigationEvent('tabSelected', ({ selectedTabIndex }) => {
+  setLastTab(selectedTabIndex);
+});
+```
+
+**In a screen**, for its own events, the [hooks above](#hooks).
+
+### Why the events are outside React
+
+When the navigation lives in the React tree, its state is React state. Every move updates it at the top of the tree, the navigators render again, and code that wants to know the current screen reaches it through a ref passed around the app.
+
+Here the platform moves the screens, and the events come from it. JavaScript only hears them, so **listening costs no render and no provider**:
+
+```tsx
+const ref =
+  createNavigationContainerRef();
+
+<NavigationContainer
+  ref={ref}
+  onStateChange={() => {
+    const route =
+      ref.current?.getCurrentRoute();
+    trackScreen(route?.name);
+  }}
+>
+```
+
+```ts
+createNavigation({
+  // …
+  listeners: {
+    screenDidAppear: ({ screen }) =>
+      trackScreen(screen.name),
+  },
+});
+```
+
+- **A move renders nothing by itself.** No React state changes when the user goes from screen to screen. A component renders on a move only when it reads `useNavigationState`, and only when the part it picked changes.
+- **No ref and no provider.** Listeners are plain functions, in `createNavigation`, a store or a service. Code outside React needs nothing passed down to it.
+- **From the first screen, across the whole app.** `listeners` are attached before the first root shows, so the first screen is heard too. They don't belong to a root, a tab or a modal, so they don't unmount with one: one listener hears every screen of the app, for as long as it runs.
+
+## What the user sees now
+
+The navigation keeps one small state: **the screen the user sees, and the selected tab**. It is the screen of the top modal, or of the root down to the visible one; overlays don't count.
+
+```ts
+navigation.getState();
+// { screen: { id: 'Component12', name: 'Details' }, tab: 1 }
+```
+
+The state changes at the end of a move, and a command resolves after it: after `await navigation.showModal('Login')`, `getState()` names Login, and the next command acts from there.
+
+`useNavigationState` gives it to a component and renders again when it changes. A function picks the part the component needs, so it renders only when that part changes:
+
+```tsx
+import { useNavigationState } from '@apexnative/navigation';
+
+function MiniPlayer() {
+  const name = useNavigationState((state) => state.screen?.name);
+  if (name === 'Player') return null; // the full player shows
+  return <PlayerBar />;
+}
+```
+
+`stateChanged` is the same as an event, for `listeners` and `navigation.on`.
+
+## Every event
+
+Every event has a name, the same in `listeners`, `navigation.on`, `useNavigationEvent` and `useScreenEvent`. The events of a screen carry it as `screen`: `{ id, name }`.
+
+| Event | When | Page |
+| --- | --- | --- |
+| `screenWillAppear` | A screen starts to come in. | [This page](#screen) |
+| `screenDidAppear` | A screen is in place. | [This page](#screen) |
+| `screenDidDisappear` | A screen is covered, or has left. | [This page](#screen) |
+| `screenPopped` | A screen left its stack: back, a swipe, `pop`. | [Stack](../containers/stack) |
+| `buttonPressed` | A button of the top bar or the toolbar. | [Bar buttons](../screen-ui/bar-buttons) |
+| `tabSelected` | A tab became current. | [Tabs](../containers/tabs) |
+| `tabPressed`, `tabLongPressed` | A press on a tab. | [Tabs](../containers/tabs) |
+| `modalDismissed` | A modal is gone, whatever closed it. | [Modals](../containers/modals) |
+| `modalDismissAttempted` | A swipe tried to close a modal that doesn't let it. | [Modals](../containers/modals) |
+| `sheetDetentChanged` | The user dragged a sheet to a detent. | [Modals](../containers/modals) |
+| `searchChanged`, `searchSubmitted`, `searchCancelled` | The search field. | [Search](../screen-ui/search) |
+| `searchSuggestionPicked` | The user picked a suggestion of the search field (iOS 16+ and Android). | [Search](../screen-ui/search) |
+| `splitViewDisplayModeChanged` | (iOS) The columns of a split view showed or hid. | [Split view](../containers/split-view) |
+| `accessoryPlacementChanged` | (iOS) 26+: the accessory of the tab bar moved. | [Tabs](../containers/tabs) |
+| `titleRenamed` | (iOS) The user renamed the title. | [Top bar](../screen-ui/top-bar) |
+| `previewCompleted` | (iOS) A preview opened into its screen. | [Transitions](../architecture/transitions) |
+| `keyCommandPressed` | (iOS) A keyboard shortcut. | [System UI](../screen-ui/system-ui) |
+| `stateChanged` | What the user sees changed. | [This page](#state) |
+
+## Next: the containers
+
+That is the core of the navigation: screens, moves, options, roots and events. The containers that hold the screens come next, from the main one: [Stack](../containers/stack), then [Tabs](../containers/tabs) and [Modals](../containers/modals).
+
+## API

package/docs-md/fundamentals/moving-between-screens.md

@@ -0,0 +1,267 @@
+# Moving between screens
+
+The moves between screens, where the commands come from, how a move finishes, how a screen gives a result back, and the defaults of every move.
+
+A list opens an item, a button opens a form over the app, a toast says that a message went out. Each is a move: a command that names a screen, and the platform shows it. A screen makes its moves with `useNavigation()`:
+
+```tsx
+import { Button } from 'react-native';
+import { useNavigation } from '@apexnative/navigation';
+
+export function Home() {
+  const navigation = useNavigation();
+  const open = () =>
+    navigation.push('Details', { props: { id: '42' } });
+  return <Button title="Open Details" onPress={open} />;
+}
+```
+
+A tap slides Details in over Home; the back button and the swipe back return to Home, with no code. This page is the map of the moves. It answers:
+
+1. [What moves there are](#moves), and what takes the user back from each.
+2. [Where the commands come from](#where): in a screen, and anywhere else.
+3. [How the app goes back](#back), and how it knows it can.
+4. [When a move is done](#done), and what happens when it can't be made.
+5. [How a screen gives a result back](#results).
+6. [How to set a move up](#settings), once for the whole app or for one command.
+
+Each move is shown here as it looks and works; its own page has the rest of the details.
+
+## The moves
+
+A move **names a screen**, and the platform shows it in its own way. Six kinds cover every app; pick one to see it:
+
+The way back is the platform's: the back button and the swipe of the stack, the swipe down of a sheet, the back button of Android. They work without any code; when the app goes back itself, see [Going back](#back).
+
+### Push a screen
+
+The stack is the main move of an app: the list opens an item, the item opens its comments. Each screen goes over the one before, and the user goes back one by one. **The screen under it stays mounted**, with its state and scroll.
+
+```ts
+navigation.push('Details', { props: { id: '42' } });
+```
+
+A stack is the root of the app, a tab, or the content of a modal. Going back to a screen further down, replacing the screens of a stack, the transitions: [Stack](../containers/stack).
+
+### Show a modal
+
+A modal is a task of its own over the app: writing a message, a form, the sign-in. It has a stack of its own, so it can push its screens too, and it ends as a whole: **the user finishes or cancels it**, and the app is as it was.
+
+```ts
+navigation.showModal('Compose', { closeButton: true });
+```
+
+Compose slides up over the app, with a close button that dismisses the modal. Under an (iOS) sheet the screen below still shows, so it doesn't disappear (see [The life of a screen](./screens-and-props#lifecycle)). The styles, the sheet with detents, a popover on iPad, a swipe that asks before closing: [Modals](../containers/modals).
+
+### Show an overlay
+
+An overlay shows over everything **without taking the place of any screen**: a toast, a banner, a call in progress. The user goes on with the screens under it.
+
+```ts
+navigation.showOverlay('Toast', { props: { text: 'Saved' } });
+```
+
+The touches, the keyboard and an overlay that closes itself: [Overlays](../containers/overlays).
+
+### Select a tab
+
+Tabs are the sections of the app, side by side. **Each keeps its own stack**, so the user leaves Inbox deep in a thread, looks at Home, and comes back to the thread. The user picks a tab; the app picks one with `selectTab`, by its index or by the id the layout gave it, `Tab('Inbox').id('inbox')`.
+
+```ts
+await navigation.selectTab('inbox');
+```
+
+The tab bar, badges, a second press on a tab, the iPad sidebar: [Tabs](../containers/tabs).
+
+### Show beside a list
+
+On iPad, a split view shows a list and the item next to it: the settings and the section, the mail and the message. `showInColumn` puts a screen into the column beside the list. **Where there is one column**, on iPhone, in a narrow window, on an Android phone, it pushes the screen over the list instead, so the same call works everywhere.
+
+```ts
+navigation.showInColumn('Privacy');
+```
+
+Two or three columns and the sidebar: [Split view](../containers/split-view).
+
+### Replace everything
+
+`switchTo` replaces the whole navigation with another root: from the sign-in to the app, and back when the user signs out. **There is no way back** to the old root: its screens unmount.
+
+```ts
+navigation.switchTo('main');
+```
+
+The roots of the app and a root made on the go, such as the screens of a deep link: [Switching roots](./switching-roots). The whole sign-in flow: [Sign in and sign out](../flows/sign-in-and-sign-out).
+
+## Where the commands come from
+
+### In a screen: useNavigation
+
+`useNavigation()`, as in Home at the top of this page, gives the commands of the screen the component is in. They **act from this screen**: `push` goes into its stack, `dismiss` closes its modal, so they need no ids.
+
+The same object has the commands of the whole app too: `switchTo`, `dismissAllModals`, `getState`. A screen needs nothing else.
+
+### Anywhere else: navigation
+
+Code outside the screens, such as a timer, a store or the handler of a push notification, imports `navigation` from the package. It has the same commands, and they **act from the screen the user sees**: `push` goes into the stack the user is looking at, a modal's if one shows. Only `dismiss` and `setOptions` are missing: they need a screen of their own.
+
+```ts
+import { navigation } from '@apexnative/navigation';
+
+export async function openChat(userId: string) {
+  await navigation.dismissAllModals();
+  await navigation.selectTab('inbox');
+  await navigation.push('Chat', { props: { userId } });
+}
+```
+
+Once the app is launching, a command waits for the first root, so a notification that launched the app is handled after it shows. Two places are too early:
+
+- **The top level of a module**, run while the bundle loads, before the launch: the command rejects.
+- **Inside `willMount`**: an awaited command never resolves, because the first root waits for `willMount`. Set the context there instead, and let `root` pick the screen.
+
+### Which one
+
+| | `useNavigation()` | `navigation` |
+| --- | --- | --- |
+| Where | In the components of a screen. | Anywhere: stores, notifications, code outside React. |
+| Acts from | This screen. | The screen the user sees. |
+| Before the app starts | Can't be called: there is no screen yet. | Waits for the first root. |
+
+The difference shows when the user moves on before the code runs. A screen loads data and then pushes Details; meanwhile the user selected another tab. `useNavigation()` pushes into the stack of the screen that asked, in the tab the user left; `navigation` pushes where the user is now. **In a screen, use `useNavigation()`**: the move stays where it was asked for.
+
+Code outside React that knows its screen, such as a class that a screen creates, gets the same object with `screenNavigation(screen)`. The `screen` is `{ id, name }`, as [`useScreen()`](./screens-and-props#use-screen) returns it.
+
+## Going back
+
+The user goes back with the platform's controls. The app goes back itself with the commands of a screen, after a save for example:
+
+| Command | What it does |
+| --- | --- |
+| `pop()` | Back to the screen under this one in its stack. |
+| `popTo(id)` | Back to a screen of this stack, by the id `push` resolved with. |
+| `popToRoot()` | Back to the first screen of this stack. |
+| `dismiss()` | Closes the modal or the overlay this screen is in, with all its screens. |
+| `goBack()` | **What the back button would do here**: `pop()` when there is a screen under this one, `dismiss()` when it is the first screen of a modal. |
+
+`goBack()` is for a screen that opens both ways, pushed in one place and in a modal in another: it doesn't need to know which.
+
+```tsx
+function Compose() {
+  const navigation = useNavigation();
+  const send = async () => {
+    await sendMessage(); // your own request
+    // pushed: back to the screen under it; in a modal: it closes
+    await navigation.goBack();
+  };
+  return <Button title="Send" onPress={send} />;
+}
+```
+
+### Can it go back?
+
+Each way back has its check. They answer at once, without `await`, so a screen can choose what to render with them:
+
+| Check | `true` when |
+| --- | --- |
+| `canPop()` | There is a screen under this one in its stack. |
+| `canDismiss()` | The screen is in a modal or an overlay. |
+| `canGoBack()` | `goBack()` has something to do: one of the two above. |
+
+```tsx
+{navigation.canDismiss() && (
+  <Button title="Close" onPress={() => navigation.dismiss()} />
+)}
+```
+
+On `navigation` they answer for the screen the user sees.
+
+### Replacing a screen
+
+`replace` shows a screen in place of the whole history of the stack: it comes in as a push does, and **it is alone in the stack**, so there is no back. It is for a point the user shouldn't go back from, such as a payment once it is made:
+
+```ts
+// on Payment, once the payment went through
+navigation.replace('OrderPlaced', { props: { orderId } });
+```
+
+To give the stack several screens at once, with back between them, `setStack('Inbox', 'Chat')` sets them: the last shows, back goes to the one before. See [Stack](../containers/stack#commands).
+
+## When a move is done
+
+Every command returns a promise, and it resolves **once the move is done**: the animation has ended, the screen is in place, and `navigation.getState()` already names it. `await` puts moves one after another, as in `openChat` above: each starts when the last has ended, from the screen the last one showed.
+
+`push` resolves with the id of the screen it showed; `showModal` and `showOverlay` with the id of what they showed, which `dismissModal` and `dismissOverlay` take.
+
+A command that can't be made rejects, with the command and the screen in the error, the same on iOS and Android:
+
+```ts
+await navigation.pop(); // on the first screen of its stack:
+// Error: [navigation] pop: Home is the first screen of its stack,
+// there is nothing to go back to
+```
+
+The other cases: the screen the command acts from is gone (closed while the code waited), or a name that isn't in `screens`.
+
+## A result back
+
+A screen that picks something, such as a color, a contact, a date, gives it back through a callback in its props. Props stay in JavaScript, so a function is a prop like any other (see [Props stay in JavaScript](./screens-and-props#props-in-js)):
+
+```tsx
+function ColorPicker({ onPick }: { onPick: (color: string) => void }) {
+  const navigation = useNavigation();
+  const pick = (color: string) => {
+    onPick(color);
+    navigation.pop();
+  };
+  return <Button title="Red" onPress={() => pick('red')} />;
+}
+```
+
+```ts
+// on the screen that asks; setColor is its own state
+navigation.push('ColorPicker', { props: { onPick: setColor } });
+```
+
+A tap on Red sets the color on the screen that asked, and the user is back on it. A result that more screens need, such as the signed-in user, belongs in the app's state: a context or a store.
+
+## Setting a move up
+
+Each command that shows a screen takes, besides the props, the settings of this move and the options of the screen for this show:
+
+| Command | Its settings | Page |
+| --- | --- | --- |
+| `push`, `replace` | `transition`: how the screen comes in. | [Stack](../containers/stack), [Transitions](../architecture/transitions) |
+| `showModal` | `style`, `sheet`, `closeButton`, `onDismiss`, `transition`… | [Modals](../containers/modals) |
+| `showOverlay` | `blockTouches`: the app under it gets no touches. | [Overlays](../containers/overlays) |
+| `showInColumn` | `column`: which column of the split view. | [Split view](../containers/split-view) |
+| All of them | `options`: the screen's options for this show, over its own. | [Screen options](./screen-options) |
+
+Here Compose comes up as a sheet at half height; the user drags it to full height, and the close button dismisses it:
+
+```ts
+navigation.showModal('Compose', {
+  // a sheet that stops at half and at full height
+  sheet: { detents: ['medium', 'large'] },
+  closeButton: true,
+});
+```
+
+### Defaults for the whole app
+
+`presentation` of `createNavigation` sets every move up once, so the commands don't repeat it. A command's own settings go over it. Here every modal gets a close button:
+
+```ts
+export const Navigation = createNavigation({
+  // …
+  presentation: {
+    modal: { closeButton: true },
+  },
+});
+```
+
+## Next: screen options
+
+A move shows a screen with its options: the title, the buttons, the bars. [Screen options](./screen-options) shows where they come from, which win, and how a shown screen changes them.
+
+## API