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

package/docs-md/flows/a-search-screen.md

@@ -0,0 +1,311 @@
+# A search screen
+
+A screen that searches with the search field of the platform: filtering as the user types, recent searches, results that open a screen, a search on the server that keeps up with the typing, suggestions, and a search tab.
+
+A search screen finds what the user types: notes, places, people. In this guide you build it with the platform's own field in the top bar, so it opens, cancels and looks as in system apps, and your screen only shows what matches. You end with:
+
+- a field in the top bar that filters a list as the user types;
+- recent searches while the field is empty, and a line when nothing matches;
+- results that open a screen, with back to the same results;
+- a search on the server that sends one request per pause, and never shows an old answer;
+- suggestions under the field, and a search tab.
+
+## What you need
+
+- An app set up with [Installation](../start/installation), with a Search screen and a Details screen.
+- Your own data: `useNotes()` for the notes on the device, or `searchNotes(text)` for a search on your server.
+- iOS 16 or later for suggestions; the rest works from iOS 15.
+- [Search](../screen-ui/search) explains the field: where it sits, scopes, tokens, a results screen of its own.
+
+## How it will work
+
+```text
+┌ Search ─────────────────────┐
+│ [ Notes                 ]   │ ← the platform's field, in the top bar
+├─────────────────────────────┤
+│ empty     → recent searches │
+│ text      → what matches    │ ── tap ──▶ push('Details')
+│ no match  → "Nothing found" │
+└─────────────────────────────┘
+```
+
+- **The field belongs to the top bar**: `UISearchController` on (iOS), the Material 3 search on (Android). The screen turns it on in its options.
+- **The screen gets the text** with `useSearchBar`, keeps it in its own state, and renders what matches.
+- **The query is the screen's**, not the app's: `useState`, not the app's context or a store. The screen stays mounted under Details, so the query and the results are there on the way back.
+
+In React Navigation the search field of the header is `headerSearchBarOptions` of native-stack, with the same platform fields underneath. Here it is the `searchBar` option, and the events come to `useSearchBar`.
+
+## 1. Add the field
+
+A screen turns the field on in its options:
+
+```tsx
+import { Text } from 'react-native';
+import { defineScreen } from '@apexnative/navigation';
+
+function Search() {
+  return <Text>Type to search your notes</Text>;
+}
+
+export const SearchScreen = defineScreen({
+  component: Search,
+  options: (s) =>
+    s
+      .title('Search')
+      .searchBar({ visible: true, placeholder: 'Notes' }),
+});
+```
+
+The field shows under the title. Tap it: it opens with the keyboard, and Cancel (iOS) or back (Android) closes it.
+
+## 2. Filter as the user types
+
+`useSearchBar` gives the screen the text. Keep it in state, and filter with it:
+
+```tsx
+import { useState } from 'react';
+import { FlatList, Text } from 'react-native';
+import { defineScreen, useSearchBar } from '@apexnative/navigation';
+import { useNotes } from '../notes';
+
+function Search() {
+  const notes = useNotes(); // your own data
+  const [query, setQuery] = useState('');
+
+  useSearchBar({
+    onChange: ({ text }) => setQuery(text),
+    onCancel: () => setQuery(''),
+  });
+
+  const words = query.trim().toLowerCase();
+  const results = notes.filter((note) =>
+    note.title.toLowerCase().includes(words),
+  );
+
+  return (
+    <FlatList
+      data={results}
+      renderItem={({ item }) => <Text>{item.title}</Text>}
+    />
+  );
+}
+```
+
+Type "sh": the list narrows with each letter. `onCancel` comes when the search closes, so the whole list comes back.
+
+## 3. Show something for an empty field
+
+An empty field and a search with no result are two different moments: the first is a place for recent searches, the second for a line that says so.
+
+```tsx
+if (words === '') {
+  return <RecentSearches onPick={setQuery} />; // your own list
+}
+if (results.length === 0) {
+  return <Text>Nothing found for “{query}”</Text>;
+}
+```
+
+A pick in the recent searches runs that search. To show its text in the field too, set it in the options, as [Suggestions](#suggestions) below does.
+
+## 4. Open a result
+
+A result opens its screen with a push, as any list does:
+
+```tsx
+const navigation = useNavigation();
+
+const open = (id: string) =>
+  navigation.push('Details', { props: { id } });
+```
+
+Tap a note: Details comes in. Back returns to the search screen, which stayed mounted under Details, **with the same results**: its query is state of the screen.
+
+## 5. Search on the server
+
+A search on the server shouldn't send a request for every letter. Two ways:
+
+- **On the Search key.** `onSubmit` comes when the user taps Search on the keyboard. One request per search, and the user decides when.
+- **As the user types,** after a pause. One request when the user stops typing for a moment, not one per letter.
+
+```tsx
+const [results, setResults] = useState<Note[]>([]);
+
+useSearchBar({
+  onSubmit: async ({ text }) => {
+    setResults(await searchNotes(text)); // your own request
+  },
+  onCancel: () => setResults([]),
+});
+```
+
+The user types, taps Search, and the results show. For the search as the user types, see the next section: it has a trap.
+
+## Answers that come out of order
+
+The user types "sh", waits, then types "shop". Two requests go out, and the server may answer "shop" first and "sh" second: the screen then shows the results of "sh" under "shop" in the field. Number the requests, and keep only the answer to the last one:
+
+```tsx
+type Timer = ReturnType<typeof setTimeout>;
+
+const [results, setResults] = useState<Note[]>([]);
+const timer = useRef<Timer | undefined>(undefined);
+const last = useRef(0);
+
+const search = (text: string) => {
+  clearTimeout(timer.current);
+  timer.current = setTimeout(async () => {
+    const asked = ++last.current;
+    const found = await searchNotes(text); // your own request
+    if (asked === last.current) setResults(found);
+  }, 300);
+};
+
+useSearchBar({
+  onChange: ({ text }) => search(text),
+  onCancel: () => {
+    clearTimeout(timer.current);
+    last.current++; // an answer still on its way is dropped
+    setResults([]);
+  },
+});
+```
+
+Type "shop" fast: one request goes out, 300 ms after the last letter. Type "sh", wait, then "op": two go out, and only the answer to "shop" shows. A query library such as React Query does the same by keying the query on the text: see [Data fetching](../guides/data-fetching).
+
+## 6. Offer suggestions
+
+(iOS) 16+ and (Android). Suggestions are a list under the field while the user types: completions, recent searches. The screen sets them from the text with `useScreenOptions`, and a pick comes to `onSuggestion` with its id:
+
+```tsx
+const navigation = useNavigation();
+
+useScreenOptions((s) =>
+  s.searchBar({
+    // completions: your own list of words for the text
+    suggestions: completions(query).map((title) => ({
+      id: title,
+      title,
+    })),
+  }),
+);
+
+useSearchBar({
+  onChange: ({ text }) => setQuery(text),
+  onSuggestion: (id) => {
+    setQuery(id);
+    navigation.setOptions({
+      topBar: { searchBar: { text: id } },
+    });
+  },
+});
+```
+
+Type "sh": "shopping" and "shoes" show under the field. Tap one: the field takes it, and the list shows its notes. A pick keeps the text the user typed, so `onSuggestion` puts the picked one in the field with `text`, which sends no `onChange`: the screen sets the query itself. The list goes when the user picks one or types on, and the next render sets new ones.
+
+## 7. Make it a search tab
+
+In an app with tabs, search is often a tab of its own. `focus: true` opens the field with the keyboard when the screen is created, as on a screen made for searching:
+
+```ts
+Tab('Search')
+  .label('Search')
+  .icon({ ios: 'magnifyingglass', android: 'ic_search' })
+  .ios((tab) => tab.role('search')),
+```
+
+```ts
+s.searchBar({ visible: true, placeholder: 'Notes', focus: true });
+```
+
+Tap the Search tab: the field opens with the keyboard. (iOS) 26 draws a tab with the `'search'` role as a separate round button, and the tab bar gives its place to the search field when the tab is selected. Before iOS 26 the tab takes the system's search look. The role is for iOS only, so it goes in `.ios(…)`: on (Android) the tab is a usual one. More tabs: [An app with tabs](./an-app-with-tabs).
+
+## Recent searches across launches
+
+The recent searches of step 3 are the user's, and they should outlive a restart. Keep them in the device's storage, read them as the screen mounts, and add the query on `onSubmit` or on a tap on a result. They don't belong in the app's context: only this screen reads them. A store fits when another screen shows them too, such as a Home with "Search again".
+
+## The whole code
+
+Filtering on the device, with recent searches and suggestions.
+
+```tsx
+import { useState } from 'react';
+import { FlatList, Pressable, Text } from 'react-native';
+import {
+  defineScreen,
+  useNavigation,
+  useScreenOptions,
+  useSearchBar,
+} from '@apexnative/navigation';
+import { completions, useNotes } from '../notes';
+import { RecentSearches } from './RecentSearches';
+
+function Search() {
+  const navigation = useNavigation();
+  const notes = useNotes();
+  const [query, setQuery] = useState('');
+
+  useScreenOptions((s) =>
+    s.searchBar({
+      suggestions: completions(query).map((title) => ({
+        id: title,
+        title,
+      })),
+    }),
+  );
+
+  useSearchBar({
+    onChange: ({ text }) => setQuery(text),
+    onCancel: () => setQuery(''),
+    onSuggestion: (id) => {
+      setQuery(id);
+      navigation.setOptions({
+        topBar: { searchBar: { text: id } },
+      });
+    },
+  });
+
+  const words = query.trim().toLowerCase();
+  const results = notes.filter((note) =>
+    note.title.toLowerCase().includes(words),
+  );
+
+  if (words === '') {
+    return <RecentSearches onPick={setQuery} />;
+  }
+  if (results.length === 0) {
+    return <Text>Nothing found for “{query}”</Text>;
+  }
+  return (
+    <FlatList
+      data={results}
+      renderItem={({ item }) => (
+        <Pressable
+          onPress={() =>
+            navigation.push('Details', { props: { id: item.id } })
+          }
+        >
+          <Text>{item.title}</Text>
+        </Pressable>
+      )}
+    />
+  );
+}
+
+export const SearchScreen = defineScreen({
+  component: Search,
+  options: (s) =>
+    s
+      .title('Search')
+      .searchBar({ visible: true, placeholder: 'Notes' }),
+});
+```
+
+`useNotes`, `completions` and `RecentSearches` are your own.
+
+## What's next
+
+- [Search](../screen-ui/search): where the field sits, scopes, tokens, a results screen of its own.
+- [List and details](./list-and-details): opening the results, on the phone and side by side.
+- [An app with tabs](./an-app-with-tabs): the tabs a search tab sits in.
+- [Data fetching](../guides/data-fetching): a search on the server with a query library.

package/docs-md/flows/an-app-with-tabs.md

@@ -0,0 +1,380 @@
+# An app with tabs
+
+Tabs with a stack each, icons and badges, a tap on the current tab, a screen without the tab bar, a tab that opens a modal, and switching tabs from code.
+
+Most apps are a few sections side by side: Home, Inbox, Profile. In this guide you build them as tabs, each with its own history, and make them behave as users expect from the apps of their platform. You end with:
+
+- three tabs with icons, where each keeps where the user left it;
+- a badge with the number of unread messages, set from outside the screens;
+- a chat that takes the whole height, without the tab bar;
+- a New tab that opens a modal instead of a section;
+- code that opens a tab and a screen in it, from a button or a notification.
+
+## What you need
+
+- An app set up with [Installation](../start/installation).
+- The screens Home, Inbox, Chat, Profile and Compose, each made with `defineScreen`.
+- Icons: SF Symbol names for iOS, drawables of your Android app (`ic_home` and so on in `android/app/src/main/res/drawable`).
+- For the badge, the number of unread messages somewhere outside the screens: a store. The example uses [Zustand](https://zustand.docs.pmnd.rs) 5; any store with a subscription works.
+- [Tabs](../containers/tabs) and [Stack](../containers/stack) explain the parts this guide puts together.
+
+## How it will work
+
+```text
+Tabs ─┬─ Home    → a stack: Home → …
+      ├─ Inbox   → a stack: Inbox → Chat   (id 'inbox', a badge)
+      ├─ New     → no stack: a button that shows Compose as a modal
+      └─ Profile → a stack: Profile → …
+```
+
+- **Each tab has a stack of its own.** A push goes into the stack of the tab the screen is in, and stays there when the user switches tabs.
+- **The tab bar is native**: the system tab bar on iOS, the Material 3 bottom navigation on Android. The app gives it labels, icons and badges; it isn't a React component.
+- **Code that knows no screen** (a notification, a store) acts through `navigation` of the package, by the id of a tab.
+
+In React Navigation each tab is a screen of a tab navigator, and a stack inside it is a nested navigator you set up. Here `Tab('Inbox')` puts the stack around the screen for you.
+
+## 1. Build the tabs
+
+`Tabs` takes its tabs in order; each `Tab` takes a screen of `screens` by its name, and puts a stack around it:
+
+```ts
+import { createNavigation, Tab, Tabs } from '@apexnative/navigation';
+import { ChatScreen } from './src/screens/Chat';
+import { HomeScreen } from './src/screens/Home';
+import { InboxScreen } from './src/screens/Inbox';
+import { ProfileScreen } from './src/screens/Profile';
+
+export const Navigation = createNavigation({
+  screens: {
+    Home: HomeScreen,
+    Inbox: InboxScreen,
+    Chat: ChatScreen,
+    Profile: ProfileScreen,
+  },
+  root: Tabs(
+    Tab('Home').label('Home'),
+    Tab('Inbox').label('Inbox').id('inbox'),
+    Tab('Profile').label('Profile'),
+  ),
+});
+```
+
+Run the app: the system tab bar shows three tabs, Home selected. `id('inbox')` names the Inbox tab, so the code below can address it without knowing its place.
+
+## 2. Give them icons
+
+An icon is an image, or a symbol of each platform: an SF Symbol on iOS, a drawable of the app on Android.
+
+```ts
+Tab('Home')
+  .label('Home')
+  .icon({ ios: 'house', android: 'ic_home' }),
+```
+
+The tab bar shows the icon over each label. (iOS) `selectedIcon` gives the selected tab another symbol, such as `'house.fill'`. The colors come from the [theme](../architecture/theme-and-context#theme): the selected tab takes its primary color.
+
+## 3. Push inside a tab
+
+A push from a screen goes into the stack of **the tab it is in**. Inbox opens a chat:
+
+```tsx
+import { Button, FlatList } from 'react-native';
+import { defineScreen, useNavigation } from '@apexnative/navigation';
+import { useMessages } from '../messages';
+
+function Inbox() {
+  const navigation = useNavigation();
+  const { messages } = useMessages(); // your own data
+
+  const open = (userId: string) =>
+    navigation.push('Chat', { props: { userId } });
+
+  return (
+    <FlatList
+      data={messages}
+      renderItem={({ item }) => (
+        <Button
+          title={item.from}
+          onPress={() => open(item.userId)}
+        />
+      )}
+    />
+  );
+}
+
+export const InboxScreen = defineScreen({
+  component: Inbox,
+  options: (s) => s.title('Inbox'),
+});
+```
+
+Open a chat in Inbox, tap Home, then Inbox again: the chat is still there. Each tab keeps its history until the user goes back in it, and its screens stay mounted, with their state.
+
+## 4. Hide the tab bar on a screen
+
+A chat needs the whole height for its messages and its keyboard. `hideBottomTabs()` hides the tab bar while the screen is on top:
+
+```tsx
+import { Text } from 'react-native';
+import { defineScreen } from '@apexnative/navigation';
+
+function Chat({ userId }: { userId: string }) {
+  return <Text>Chat with {userId}</Text>;
+}
+
+export const ChatScreen = defineScreen({
+  component: Chat,
+  options: (s) => s.title('Chat').hideBottomTabs(),
+});
+```
+
+The tab bar goes as the chat comes in, and comes back as the user goes back to Inbox.
+
+## 5. Show a badge
+
+A badge is a number or a short text on a tab's icon. The count of unread messages changes all the time, and it changes while the user is in another tab, so it doesn't belong to the Inbox screen. Keep it in a store, and let the store set the badge by the tab's id:
+
+```ts
+import { navigation } from '@apexnative/navigation';
+import { create } from 'zustand';
+
+export const useUnread = create<{ count: number }>()(() => ({
+  count: 0,
+}));
+
+// the badge follows the count, wherever it changes
+useUnread.subscribe(({ count }, previous) => {
+  if (count === previous.count) return;
+  navigation.setTabBadge(count, 'inbox');
+});
+```
+
+```ts
+// your socket or your push handler
+useUnread.setState((s) => ({ count: s.count + 1 }));
+```
+
+A new message comes, and the Inbox tab shows 1, whatever tab the user is in. At 0 the badge goes: the number `0` shows none, as `null` does. `Tab('Inbox').badge(3)` sets the first one, and `Tab('Inbox').dot()` shows a dot without text.
+
+Not the app's context: it is made for what changes rarely, and each change renders every component that reads it, on every mounted screen. See [What goes in the context](../architecture/theme-and-context#context-roles).
+
+## 6. Handle a tap on the current tab
+
+A second tap on the selected tab goes back to the first screen of the tab, and on the first screen scrolls it to the top. Both platforms do it in their own apps, and the navigation does it without code.
+
+A screen that does more on that tap, such as reloading, listens with `useTabPress`:
+
+```tsx
+import { useTabPress } from '@apexnative/navigation';
+
+function Inbox() {
+  const { messages, refetch } = useMessages(); // your own data
+  useTabPress(({ wasSelected }) => {
+    if (wasSelected) refetch();
+  });
+  // …
+}
+```
+
+Tap Inbox while it shows: the list goes to the top and reloads. `wasSelected` tells a second tap from the tap that selected the tab.
+
+## 7. Open a tab from code
+
+A notification about a message opens the chat in Inbox, whatever tab the user is on. `selectTab` resolves once the tab shows, and `navigation.push` acts from the screen the user sees, so a push after it goes into Inbox. A modal open over the tabs would take the push, so it closes first:
+
+```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 } });
+}
+```
+
+Tap the notification: Inbox shows, then the chat comes in over it, and back goes to Inbox.
+
+Use the `navigation` of the package here, not the one of `useNavigation()`: a screen's own `push` goes into the stack of that screen, so a push from Home after `selectTab` would still land in Home.
+
+## 8. A tab that opens a modal
+
+A New tab that opens a screen to write is a button, not a section. A `Tab()` without content never becomes the current tab, and `onPress` says what it does:
+
+```ts
+import { navigation } from '@apexnative/navigation';
+
+Tab()
+  .label('New')
+  .icon({ ios: 'square.and.pencil', android: 'ic_edit' })
+  .onPress(() => navigation.showModal('Compose')),
+```
+
+Tap New: Compose comes up as a modal, and the tab the user was on stays selected under it. Compose goes into `screens` like the others.
+
+## 9. Back on Android
+
+(Android) On the first screen of a tab, the system back leaves the app by default (`'exit'`). `backBehavior` changes it: `'first'` goes to the first tab, `'previous'` to the tab the user came from.
+
+```ts
+Tabs(/* … */).backBehavior('first');
+```
+
+Open Profile, press back: Home shows; press back again: the app goes to the background. iOS has no system back; the option is for Android only.
+
+## The chat that is open already
+
+The notification of step 7 opens a chat with a person whose chat is already in the Inbox stack. Each push is a new screen, so the user would go back from the chat to the same chat. A `key` makes Chat one screen per person: a push of the same person goes back to the one in the stack.
+
+```tsx
+export const ChatScreen = defineScreen({
+  component: Chat,
+  key: (props) => props.userId,
+  options: (s) => s.title('Chat').hideBottomTabs(),
+});
+```
+
+More: [One screen per item](../fundamentals/screens-and-props#key).
+
+## What every tab reads
+
+Each screen is a React root of its own, and each tab holds its screens: a React provider in Home doesn't reach Profile. What every tab shows the same, such as the signed-in user, goes in the app's context or a store, which every screen reads; data of one tab stays in that tab. See [The app's context](../guides/app-context) and [State management](../guides/state-management).
+
+## Heavy tabs and a fast start
+
+By default every tab is created with the tabs. With many heavy tabs, `Tabs(…).lazy()` creates each the first time it shows, so the app starts faster. A tab not created yet runs none of its code: its `useTabPress` and its effects wait for the first visit. That is one more reason the badge of step 5 comes from a store, not from the Inbox screen. More: [When tabs are created](../containers/tabs#lazy).
+
+## On iPad and iOS 26
+
+The tab bar looks as each platform draws it: Liquid Glass on iOS 26, a bar at the top on iPad that can turn into a sidebar, Material 3 bottom navigation on Android. Nothing in the code above changes. See [The tab bar on each platform](../containers/tabs#platforms).
+
+## The whole code
+
+```ts
+import {
+  createNavigation,
+  navigation,
+  Tab,
+  Tabs,
+} from '@apexnative/navigation';
+import { ChatScreen } from './src/screens/Chat';
+import { ComposeScreen } from './src/screens/Compose';
+import { HomeScreen } from './src/screens/Home';
+import { InboxScreen } from './src/screens/Inbox';
+import { ProfileScreen } from './src/screens/Profile';
+import './src/unread';
+
+export const Navigation = createNavigation({
+  screens: {
+    Home: HomeScreen,
+    Inbox: InboxScreen,
+    Chat: ChatScreen,
+    Compose: ComposeScreen,
+    Profile: ProfileScreen,
+  },
+  root: Tabs(
+    Tab('Home')
+      .label('Home')
+      .icon({ ios: 'house', android: 'ic_home' }),
+    Tab('Inbox')
+      .label('Inbox')
+      .icon({ ios: 'tray', android: 'ic_inbox' })
+      .id('inbox'),
+    Tab()
+      .label('New')
+      .icon({ ios: 'square.and.pencil', android: 'ic_edit' })
+      .onPress(() => navigation.showModal('Compose')),
+    Tab('Profile')
+      .label('Profile')
+      .icon({ ios: 'person', android: 'ic_person' }),
+  ).backBehavior('first'),
+});
+```
+
+```ts
+import { navigation } from '@apexnative/navigation';
+import { create } from 'zustand';
+
+export const useUnread = create<{ count: number }>()(() => ({
+  count: 0,
+}));
+
+useUnread.subscribe(({ count }, previous) => {
+  if (count === previous.count) return;
+  navigation.setTabBadge(count, 'inbox');
+});
+```
+
+```tsx
+import { Button, FlatList } from 'react-native';
+import {
+  defineScreen,
+  useNavigation,
+  useTabPress,
+} from '@apexnative/navigation';
+import { useMessages } from '../messages';
+
+function Inbox() {
+  const navigation = useNavigation();
+  const { messages, refetch } = useMessages();
+
+  useTabPress(({ wasSelected }) => {
+    if (wasSelected) refetch();
+  });
+
+  return (
+    <FlatList
+      data={messages}
+      renderItem={({ item }) => (
+        <Button
+          title={item.from}
+          onPress={() =>
+            navigation.push('Chat', {
+              props: { userId: item.userId },
+            })
+          }
+        />
+      )}
+    />
+  );
+}
+
+export const InboxScreen = defineScreen({
+  component: Inbox,
+  options: (s) => s.title('Inbox'),
+});
+```
+
+```tsx
+import { Text } from 'react-native';
+import { defineScreen } from '@apexnative/navigation';
+
+function Chat({ userId }: { userId: string }) {
+  return <Text>Chat with {userId}</Text>;
+}
+
+export const ChatScreen = defineScreen({
+  component: Chat,
+  key: (props) => props.userId,
+  options: (s) => s.title('Chat').hideBottomTabs(),
+});
+```
+
+```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 } });
+}
+```
+
+`useMessages` is your own data. The drawables `ic_home`, `ic_inbox`, `ic_edit` and `ic_person` are images of your Android app.
+
+## What's next
+
+- [List and details](./list-and-details): what a tab often holds.
+- [A search screen](./a-search-screen): a search tab.
+- [Notifications](../guides/notifications): the tap that calls `openChat`.
+- [Tabs](../containers/tabs): building, selecting, badges, lazy tabs, the tab bars of iOS 26, iPad and Android.
+- [Lifecycle and events](../fundamentals/lifecycle-and-events#events): `tabSelected`, `tabPressed`.