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

package/docs-md/architecture/theme-and-context.md

@@ -0,0 +1,368 @@
+# Theme and context
+
+Two things every screen shares: the theme, the colors of the bars and backgrounds, and the context, what every screen can rely on. Why the navigation keeps them, how to use them, and what belongs in them.
+
+Every screen of an app shares a look and a few facts: the colors of the bars, the signed-in user, the language. The navigation keeps both for every screen. The **theme** is the colors of the bars, tabs and backgrounds. The **context** is a small object of the app that every screen reads. This page answers:
+
+1. [Why the navigation keeps them](#why), and not a React provider.
+2. [The theme](#theme): its colors, dark mode, changing it, Android's own colors.
+3. [The context](#context): filling it, reading it, typing it.
+4. [What goes in the context](#context-roles), and what goes elsewhere.
+
+## Why the navigation keeps them
+
+Each screen renders in a React root of its own, as the platform shows it (see [What a screen is](../fundamentals/screens-and-props#what)). A React provider around one screen doesn't reach the next one, and the bars aren't React at all. So what every screen shares sits **above the screens**, with the navigation. From there it reaches every screen, the options of every screen, and the native bars.
+
+Providers of your own, such as a store or a query client, have a place of their own: see [One tree](./one-tree).
+
+## The theme
+
+The theme is the colors of the navigation: the bars, the tabs, the backgrounds. It is set once in `createNavigation`, and every screen takes it:
+
+```ts
+import { createNavigation } from '@apexnative/navigation';
+
+export const Navigation = createNavigation({
+  // … screens and root
+  theme: {
+    colors: {
+      primary: '#E76F51',
+      bar: '#1E2A44',
+      text: '#F3E9D2',
+      background: '#F3E9D2',
+    },
+  },
+});
+```
+
+Every top bar and the tab bar are navy with light titles; the buttons, the back arrow and the selected tab are orange.
+
+A color left out keeps the platform's look. On iOS 26 a theme without `bar` keeps the bars on glass. On Android the bars take the colors of the app's Material 3 theme, neutral grays by default (see [Android's colors](#android)).
+
+The theme is the bottom layer of the options of every screen. A screen that needs its own look sets it in its options, and they go over the theme (see [Where a screen gets them](../fundamentals/screen-options#layers)).
+
+### Dark mode
+
+A color can have a value for each appearance, `{ light, dark }`. The native side picks the one of the system's appearance, and **switches by itself** when the user turns dark mode on, with no render in JavaScript:
+
+```ts
+colors: {
+  bar: { light: '#FFFAF0', dark: '#101828' },
+  text: { light: '#1E2A44', dark: '#F3E9D2' },
+}
+```
+
+### Changing the theme
+
+`navigation.setTheme` changes the theme while the app runs, such as when the user picks another one in the settings. The screens already shown take it too. It **replaces the whole theme**, so a color left out goes back to the platform's look. Keep each theme as a whole object, and pass one:
+
+```ts
+import type { NavigationTheme } from '@apexnative/navigation';
+
+export const ocean: NavigationTheme = {
+  colors: {
+    primary: '#2A9D8F',
+    bar: '#0B3C49',
+    text: '#F1FAEE',
+    background: '#F1FAEE',
+  },
+};
+```
+
+```ts
+navigation.setTheme(ocean);
+```
+
+A screen whose own options set a color keeps it: its options go over the theme.
+
+### The theme in React content
+
+React content that should match the bars reads the theme with `useNavigationTheme()`. Each color comes resolved for the current appearance, so it goes straight into a style. The component renders again when the theme changes, and when the appearance turns light or dark:
+
+```tsx
+import { Text, View } from 'react-native';
+import { useNavigationTheme } from '@apexnative/navigation';
+
+export function Card({ title }: { title: string }) {
+  const { colors } = useNavigationTheme();
+  return (
+    <View style={{ backgroundColor: colors.bar, padding: 16 }}>
+      <Text style={{ color: colors.text }}>{title}</Text>
+    </View>
+  );
+}
+```
+
+A color the theme leaves out is `undefined` here, so the style falls back to its default.
+
+### The theme in options
+
+The options of the app and of a screen can be built from the theme: their function gets `{ theme, context }` (see [The chain and plain objects](../fundamentals/screen-options#chain)). They differ in when they are built:
+
+| Options | Built |
+| --- | --- |
+| `options` of `createNavigation` | At the start, and again on every `setTheme`. |
+| A screen's own options | When a command shows the screen. A later `setTheme` doesn't build them again. |
+
+So a color that follows the theme belongs in the theme itself, or in the app's `options`.
+
+### Android's colors
+
+(Android) The bars, tabs, search, sheets and menus are Material 3 views. What the theme and the options leave out, they take from the app's Android theme, as every Material view of the app does. On an app made from React Native's template, `setup` makes the app's theme inherit `Theme.ApexNavigation`: Material 3 in neutral grays, light and dark, with no tint of its own.
+
+An app changes any of these colors in `styles.xml`. A color that differs in dark mode is a color resource with a second value in `values-night`, so the one style serves both modes:
+
+```xml
+<style name="AppTheme" parent="Theme.ApexNavigation">
+  <item name="colorSecondaryContainer">@color/selected_tab</item>
+</style>
+```
+
+```xml
+<color name="selected_tab">#FCE4D6</color>
+```
+
+```xml
+<color name="selected_tab">#5C3B2E</color>
+```
+
+The selected tab now sits on a peach pill in light mode, and a brown one in dark mode. What each Material 3 color paints:
+
+| Material 3 color | What takes it |
+| --- | --- |
+| `colorSurface` | The top bar. |
+| `colorOnSurface` | The title and the back arrow. |
+| `colorOnSurfaceVariant` | The subtitle and the "⋮" of the bar. |
+| `colorSurfaceContainer`, `colorSurfaceContainerLow`, `colorSurfaceContainerHigh` | The tab bar and the menus of the bar; a sheet; the search field. |
+| `colorSecondaryContainer` | The pill of the selected tab, the selected scope of the search. |
+| `colorPrimaryContainer` | The floating action button. |
+| `colorError` | The badges of the tabs. |
+
+The theme's `colors` and a screen's options go over these: `bar` over the top bar and the tab bar, `text` over the titles, `badge` over the badges.
+
+- **An app with a Material 3 theme of its own** keeps it, and the navigation takes its colors.
+- **An app with a theme that isn't Material 3** keeps it too. The bars, tabs, search and sheets then take `Theme.ApexNavigation` themselves, and follow the app's light or dark mode.
+- **An app that is only light** sets it in code: `AppCompatDelegate.setDefaultNightMode(AppCompatDelegate.MODE_NIGHT_NO)`.
+
+## The context
+
+The context is a small object of the app that **every screen, every option and the start of the app** can read: who the user is, the language, the flags of the app. The app gives its first value in `createNavigation`, and a component reads it with `useAppContext`:
+
+```ts
+import { createNavigation } from '@apexnative/navigation';
+
+export type AppContext = {
+  language: string;
+  user: { name: string } | null;
+};
+
+const context: AppContext = { language: 'en', user: null };
+
+export const Navigation = createNavigation({
+  // … screens and root
+  context,
+});
+```
+
+```tsx
+import { Text } from 'react-native';
+import { useAppContext } from '@apexnative/navigation';
+import type { AppContext } from '../../Navigation';
+
+export function Home() {
+  const user = useAppContext((c: AppContext) => c.user);
+  return <Text>Hello, {user?.name ?? 'guest'}</Text>;
+}
+```
+
+Home shows "Hello, guest", and the user's name once a sign-in puts the user in the context. Once `Navigation.ts` exports the type, [the generated file registers it](#types): `useAppContext`, `setContext` and the options know it by themselves, and the `AppContext` annotation goes; the examples below assume it.
+
+### Why it exists
+
+Some values are needed before any screen renders, and by every screen after it. Whether the user is signed in decides the first screen; the user's name goes into the title of a bar; the language changes every screen at once.
+
+In a React app such values sit in a provider at the top of the tree. Here each screen is a React root of its own, so a provider doesn't reach them, and the start of the app and the options of a screen aren't React at all. The context is **the one place all of them read**:
+
+| Who reads it | How |
+| --- | --- |
+| The start of the app | `root(context)`, `initialRoot(context)`: the first screen from the context. |
+| The options of a screen | `(s, props, { context })`: a title or a button from the context. |
+| A component of any screen | `useAppContext()`, which renders again when it changes. |
+| Code outside React | `navigation.getContext()`. |
+
+### Filling it
+
+The context has a first value, and one way to change it:
+
+| Where | The context |
+| --- | --- |
+| `context` of `createNavigation` | The first value, there at once: while `willMount` runs, and in an app without `willMount`. Its type is the type of the context. |
+| `navigation.setContext` | **The only way to change it**: in `willMount` before the first screen, after a sign-in, from the settings. |
+
+A value the first screen depends on goes in during `willMount`, which runs while the splash screen shows. The first root is then built from it:
+
+```ts
+import { createNavigation, navigation } from '@apexnative/navigation';
+
+export const Navigation = createNavigation({
+  // … screens and roots
+  context,
+  willMount: async () => {
+    const user = await loadUser(); // your own check
+    navigation.setContext((previous) => ({ ...previous, user }));
+  },
+  initialRoot: (context) => (context.user ? 'main' : 'login'),
+});
+```
+
+A signed-in user starts on `main`, anyone else on `login`, and no screen shows before the check is done.
+
+`setContext` takes the new value, or a function of the value before. The function keeps the other keys:
+
+```ts
+const signIn = async (email: string, password: string) => {
+  const user = await logIn(email, password); // your own request
+  navigation.setContext((previous) => ({ ...previous, user }));
+  await navigation.switchTo('main');
+};
+```
+
+```ts
+const changeLanguage = (language: string) =>
+  navigation.setContext((previous) => ({ ...previous, language }));
+```
+
+### Reading it
+
+`useAppContext` with a function picks the part a component needs, so the component renders only when that part changes. A change of the language doesn't render a component that reads the user. Without the function, it renders on every change of the context.
+
+The options of a screen read the context too, **once, when a command shows the screen**:
+
+```tsx
+export const HomeScreen = defineScreen({
+  component: Home,
+  options: (s, props, { context }) =>
+    s.title(context.user?.name ?? 'Home'),
+});
+```
+
+A later `setContext` doesn't change the title of a screen already shown. A title that should follow the context reads it in the component, with `useScreenOptions`, which applies options again on each render (see [From the state](../fundamentals/screen-options#use-screen-options)):
+
+```tsx
+function Home() {
+  const user = useAppContext((c) => c.user);
+  useScreenOptions((s) => s.title(user ? `Hi, ${user.name}` : 'Home'));
+  return <Feed />;
+}
+```
+
+The title changes the moment the user signs in or out, on every screen that shows Home.
+
+### Typing it
+
+TypeScript learns the type of the context from `navigation-env.d.ts`, the file `setup` and `init` write to type the commands (see [Typed commands](../start/installation#typed-commands)). It registers the app from `typeof Navigation`, and the context from the type or interface that `Navigation.ts` exports under the name `AppContext`, as above. A type of another name isn't picked up. Nothing to add by hand:
+
+```ts
+// Made by apex-navigation setup: the types of the app's screens
+// for the navigation's commands. Don't edit.
+declare module '@apexnative/navigation' {
+  interface Register {
+    app: typeof import('./Navigation').Navigation;
+    context: import('./Navigation').AppContext;
+  }
+}
+export {};
+```
+
+Then `useAppContext()`, `getContext()`, `setContext()` and the options are typed with it. The context is registered on its own, not read from the app's type, because the options of the screens are part of that type and would refer to it in a circle.
+
+## What goes in the context
+
+The context is made for **what the whole app depends on, and what changes rarely**. In an app it has four roles:
+
+| Role | For example |
+| --- | --- |
+| Where the user goes | Signed in or not, the onboarding done or not: the first root, and the root after a sign-in or a sign-out. |
+| What every screen shows the same | The user's name and avatar, the language, the plan of the account. |
+| What the app turns on and off | Feature flags and remote configuration, read once at the start. |
+| Services the screens use | Objects the app creates once at the start and every screen calls: dependency injection, without a global import. |
+
+### What to keep in it
+
+### In code
+
+The same three cases, each as it goes wrong and as it goes right.
+
+**Data that keeps coming**, such as new messages, goes to a store. In the context, each message would render every screen that reads it:
+
+```ts
+socket.on('message', (message) =>
+  navigation.setContext((c) => ({
+    ...c,
+    messages: [...c.messages, message],
+  })),
+);
+```
+
+```ts
+socket.on('message', (message) =>
+  messages.add(message), // your own store
+);
+```
+
+**What one screen edits**, such as a draft, stays in that screen. In the context, each letter would render every screen that reads it:
+
+```tsx
+<TextInput
+  onChangeText={(draft) =>
+    navigation.setContext((c) => ({
+      ...c,
+      draft,
+    }))
+  }
+/>
+```
+
+```tsx
+const [draft, setDraft] = useState('');
+
+<TextInput onChangeText={setDraft} />;
+```
+
+**Who the user is** goes to the context once, when it changes, instead of every screen loading it again on its own:
+
+```tsx
+function Profile() {
+  const [user, setUser] = useState(null);
+  useEffect(() => {
+    loadUser().then(setUser);
+  }, []);
+  return <Text>{user?.name}</Text>;
+}
+```
+
+```tsx
+function Profile() {
+  const user = useAppContext((c) => c.user);
+  return <Text>{user?.name}</Text>;
+}
+```
+
+### Why not everything
+
+The context is made for few values that change rarely, and it behaves so:
+
+- **A change renders its readers on every screen.** A component that reads the changed part renders again on every mounted screen: the screens under the one on top and in the other tabs too. A list kept here renders the whole app on each new message.
+- **It isn't saved.** A new start of the app begins from `context` again. What should outlive a restart, the app saves itself, and puts back in `willMount`.
+- **It has no tools of a store.** No middleware, no devtools, no history of changes. A store has them, and the context can hold the store itself as a service.
+
+### Compared with the other places
+
+| | The app's context | A store | React context in `appProvider` | `useState` |
+| --- | --- | --- | --- | --- |
+| Read by | Every screen, the options, the start, code outside React | Components, and code that imports it | Components inside the provider | One component |
+| Before the first screen | Yes | Yes | No | No |
+| Changes | Rarely, with `setContext` | Often, by its actions | By its provider | Often |
+| For | Who the user is, the language, the flags, services | The data of the app | State shared through React | One screen |
+
+## API

package/docs-md/architecture/transitions.md

@@ -0,0 +1,191 @@
+# Transitions
+
+How screens come and go: the platform's transitions, presets for a command, transitions out of a view (shared elements, zoom, preview), animations of your own, and waiting for the content. Which to pick, and what each costs.
+
+A transition is how a screen comes in and goes. By default it is the platform's own, with its gestures. A command can ask for another one with `transition`:
+
+```ts
+import { navigation } from '@apexnative/navigation';
+
+navigation.push('Details', { transition: 'fade' });
+```
+
+Details fades in over the screen before it, and fades out on the way back. This page answers:
+
+1. [The platform's transitions](#platform), and why they are the default.
+2. [Presets](#presets) for a command, or for the whole app.
+3. [Transitions out of a view](#views): shared elements, zoom, preview.
+4. [Animations of your own](#custom).
+5. [Which to pick](#which).
+6. [Waiting for the content](#wait).
+
+## The platform's transitions
+
+Without a `transition`, every move is the platform's: a push slides in from the edge, a sheet rises from the bottom, a new tab shows at once. They **follow the finger**: the swipe back of iOS moves the screen as the user drags, and the user can stop halfway. They also follow the system: on Android a push plays the transition the system gives to a move between screens.
+
+So the platform's transitions are the right choice for most moves. A preset or an animation of your own is for a move that means something else: a modal that should fade, a screen that grows out of a photo.
+
+## Presets
+
+`transition` of `push` and `showModal` takes a preset. The way back is the same in reverse:
+
+| Preset | The screen |
+| --- | --- |
+| `'platform'` | The platform's own transition: the default. |
+| `'fade'` | Fades in, and out on the way back. |
+| `'slideUp'` | Comes from the bottom, goes down. |
+| `'slideFromEnd'` | Comes from the trailing edge: the right, or the left in a right-to-left app. |
+| `'scale'` | Grows in place, and shrinks on the way back. |
+| `'none'` | Shows at once. |
+
+A preset takes 300 ms. `{ type, duration }` sets another time, in milliseconds:
+
+```ts
+navigation.showModal('Player', {
+  transition: { type: 'slideUp', duration: 450 },
+});
+```
+
+`presentation` of `createNavigation` gives every push or modal of the app its transition: see [Defaults for the whole app](../fundamentals/moving-between-screens#presentation). New roots have presets of their own: see [How a new root comes in](../fundamentals/switching-roots#transitions).
+
+## Transitions out of a view
+
+Some moves start from a view: a photo opens out of its tile, an avatar grows into a profile. The view on the screen has a `nativeID`, and the transition names it:
+
+### Shared elements
+
+Views move from one screen into the other. Each pair names a view of this screen and a view of the next; the rest of the screen fades. Back moves them home.
+
+```tsx
+<Image nativeID={`avatar-${person.id}`} source={person.photo} />
+<Text nativeID={`name-${person.id}`}>{person.name}</Text>
+```
+
+```tsx
+<Image nativeID="person-avatar" source={photo} />
+<Text nativeID="person-name">{name}</Text>
+```
+
+```ts
+navigation.push('Person', {
+  props: { id: person.id },
+  transition: {
+    shared: [
+      [`avatar-${person.id}`, 'person-avatar'],
+      [`name-${person.id}`, 'person-name'],
+    ],
+  },
+});
+```
+
+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. `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.
+
+### Zoom
+
+(iOS) 18+ The next screen opens out of a view and shrinks back into it, as photos do in the system apps. The swipe back, and the swipe down of a sheet, shrink it with the finger:
+
+```ts
+navigation.push('Photo', {
+  props: { id: photo.id },
+  transition: { zoom: `photo-${photo.id}` },
+});
+```
+
+The tile has the same `nativeID`: `photo-` and the id of the photo. `showModal` takes the zoom too. On Android and older iOS the screen comes in with the platform's transition.
+
+### Preview
+
+(iOS) A long press on a view shows the screen it opens, small, with a menu under it; a tap on the preview pushes the screen. A screen says which views preview what with `usePreview`, by the view's `nativeID`:
+
+```tsx
+import { Image, Share } from 'react-native';
+import { usePreview } from '@apexnative/navigation';
+
+function Tile({ id, uri }: { id: string; uri: string }) {
+  usePreview(`photo-${id}`, {
+    screen: 'Photo',
+    props: { id },
+    actions: [
+      {
+        id: 'share',
+        title: 'Share',
+        onPress: () => Share.share({ url: uri }),
+      },
+    ],
+  });
+  return <Image nativeID={`photo-${id}`} source={{ uri }} />;
+}
+```
+
+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
+
+`options.animations` describes a move property by property: the screen that comes in, and the one that goes. It is for a move a preset doesn't have, and it goes over the `transition` of the command:
+
+```ts
+navigation.push('Details', {
+  options: {
+    animations: {
+      push: {
+        content: {
+          enter: {
+            translationY: { from: 300, to: 0, duration: 300 },
+            alpha: { from: 0, to: 1, duration: 300 },
+          },
+        },
+      },
+    },
+  },
+});
+```
+
+Details rises 300 points as it fades in. Each property animates from a value to a value over a time, with a delay and an interpolation if it needs them; the [API](#api) lists every one.
+
+The same goes for `pop`, `showModal`, `dismissModal`, `setStackRoot` and `setRoot`. The swipe back is the exception: (iOS) it always follows the finger with the system's slide, so a custom `pop` plays for the back button and `pop()` only.
+
+## Which to pick
+
+| The move | Pick | What it costs |
+| --- | --- | --- |
+| Most moves | The platform's | Nothing: it follows the finger and the system. |
+| A move that means something else, such as a fading modal | A preset | The swipe back on iOS still slides. |
+| A view that becomes the next screen | Shared elements, or the zoom on iOS 18+ | A `nativeID` on both views. The zoom shows on iOS 18+ only. |
+| A look at a screen before opening it | The preview | iOS only. |
+| A move no preset has | `options.animations` | Every property spelled out; the swipe back on iOS still slides. |
+
+## Waiting for the content
+
+A screen can come in before its React content has drawn, or wait for it. Coming in at once keeps the move fast; waiting keeps the user from seeing an empty screen slide in.
+
+| | By default |
+| --- | --- |
+| (iOS) push | Doesn't wait for the content: the screen slides in with its bar, and the content draws as it comes. It waits only for components in the bar. |
+| (Android) push | Doesn't wait. With `appProvider` a React screen is rendered before the push starts, so it comes in drawn from the first frame. A screen with a React root of its own comes in at once, and its content draws as it comes; so does a native screen. The components of the bar draw as the screen comes in. |
+| (Android) modal | Waits for the content and the components of the bar, half a second at most, so the screen comes in drawn. |
+
+`waitForRender` of an animation changes it. `true` waits as long as it takes; `false` comes in at once (a push on Android with `appProvider` [still renders the screen first](#wait-one-tree)):
+
+```ts
+navigation.push('Details', {
+  options: { animations: { push: { waitForRender: true } } },
+});
+```
+
+A screen that draws nothing at first doesn't hold its transition back: it comes in empty, with its bar.
+
+### A push on Android, in one tree
+
+(Android) With `appProvider` a push doesn't wait for the screen, and the screen still comes in drawn: nothing of it mounts during the transition, which would drop frames. It goes in three steps:
+
+1. The native side lays the screen out in its stack, out of sight, and gives React its size and its safe area.
+2. React renders the screen at that size with its content, at once.
+3. The push starts in the frame in which that content appears; if it doesn't appear, after half a second.
+
+So the push starts later by the time React takes to render the screen, as a push in a native app starts once its screen is built. `waitForRender: false` goes the same way here; `true` waits for the content as long as it takes, and for the components of the bar, half a second at most.
+
+The size and the safe area come from the options the screen is pushed with. Options the screen changes as it renders for the first time, such as hiding the top bar or its safe area edges, apply as it comes in, and its content lays out once more during the transition. Put such options in the screen's own options instead.
+
+## API