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

package/docs-md/architecture/native-screens.md

@@ -0,0 +1,290 @@
+# Native screens
+
+Screens written in SwiftUI, UIKit, Jetpack Compose or Android views, as full screens of the navigation next to React ones: how they talk to the app, when to make one, one screen from the command to the device, types, functions and commands.
+
+A screen of the app doesn't have to be React. A native screen is written in SwiftUI or UIKit on iOS, in Jetpack Compose or Android views on Android, and it is **a full screen of the navigation**: pushed, presented, put in a tab or made the root, like any React screen. In JavaScript it is one line in `screens`:
+
+```ts
+import { nativeScreen } from '@apexnative/navigation';
+
+export const MapScreen = nativeScreen('Map', {
+  options: (s) => s.title('Map'),
+});
+```
+
+`'Map'` is the name the native view is registered under; `navigation.push('Map')` shows it, with the bar and the back gesture of any screen. This page answers:
+
+1. [What a native screen is](#what), and how it talks to the app.
+2. [When to make one](#when).
+3. [One screen, step by step](#example): from the command to the device.
+4. [What happens when it shows](#flow).
+5. [Types](#types), [functions with results](#results) and [commands](#commands).
+6. [UIKit and Android views](#imperative), and [native screens in layouts](#layouts).
+
+## What a native screen is
+
+The navigation shows screens natively anyway: a React screen is the platform's screen with a React root inside. A native screen is the same platform's screen with **your SwiftUI view or Compose function inside** instead. The navigation draws its bar, moves it, and takes it back with the gesture, as for any screen; the user can't tell which is which.
+
+The app is still a React Native app: its data, its stores, its logic are in JavaScript. So a native screen keeps a line to it:
+
+- **Props go to it**: from the command that shows it, and from `useProps`, a hook that gives it the data of the app while it is open.
+- **Function calls come back**: a prop can be a function of the app, such as one that saves; the native screen calls it, and awaits its result.
+- **Commands come back**: it pushes, presents and goes back as a React screen does.
+
+## When to make one
+
+| A native screen for | For example |
+| --- | --- |
+| What the platform does best natively | A map, a camera, a chart with thousands of points, a screen of SwiftUI-only APIs. |
+| Code the app already has | A screen of the native app it grew from, kept as it is. |
+| A team that writes Swift or Kotlin | Each screen in the language its author knows best. |
+
+A screen that is a list, a form or a detail page is as fast in React. A native screen costs more: its UI is written twice, once per platform, and everything it gets from the app crosses as plain data. Make one when a reason above holds.
+
+## One screen, step by step
+
+A Settings screen in SwiftUI and Compose, with a switch for notifications. The switch shows a value of the app's store, and turning it saves through a function of the app.
+
+### 1. The command
+
+```bash
+npx apex-navigation screen Settings --native
+```
+
+It shows what it will write, asks, and writes:
+
+| File | What it is |
+| --- | --- |
+| `src/screens/Settings.ts` | The definition: the props and the options. |
+| `ios//Screens/SettingsScreen.swift` | The SwiftUI view, next to `AppDelegate.swift`; added to the Xcode project. |
+| `android/…/screens/SettingsScreen.kt` | The Compose function, in the app's package. With the first Compose screen, Compose is turned on in Gradle. |
+| `ApexNavigation.generated.swift`, `ApexNavigationGenerated.kt` | The props as native types, the registration of the screen, and `Screens`, the screens of the app for the [typed commands](#typed-commands) of native code. |
+| `Navigation.ts` | `Settings` added to `screens`. |
+| `package.json` | Under `apexNavigation`, what each native screen is made with. |
+
+### 2. The definition in TypeScript
+
+The props are declared once, here. `useProps` fills them from the app while the screen is open:
+
+```ts
+import { nativeScreen } from '@apexnative/navigation';
+import { useSettings } from '../settings'; // your own store
+
+export interface SettingsProps {
+  notifications: boolean;
+  onNotificationsChange: (on: boolean) => Promise<void>;
+}
+
+export const SettingsScreen = nativeScreen<SettingsProps>(
+  'Settings',
+  {
+    options: (s) => s.title('Settings'),
+    useProps: () => {
+      const notifications = useSettings((state) => state.notifications);
+      const save = useSettings((state) => state.saveNotifications);
+      return {
+        notifications,
+        onNotificationsChange: (on: boolean) => save(on),
+      };
+    },
+  },
+);
+```
+
+`useProps` is a hook, so any hook works in it: a store, a query, `useAppContext`. It runs inside `appProvider` and `screenProvider` (see [One tree](./one-tree)). What it returns goes over the props of the command.
+
+### 3. The generated code
+
+`codegen` makes native types of the props, so the screen reads them typed. It runs with the command, and again after each change of the props:
+
+```bash
+npx apex-navigation codegen
+```
+
+```swift
+struct SettingsProps {
+  let notifications: Bool
+  let onNotificationsChange: (Bool) async throws -> Void
+}
+```
+
+It also registers the screen under its name: the navigation finds it as it starts, with nothing to add in `AppDelegate` or `MainApplication`. `doctor` tells when the generated code is behind the props.
+
+### 4. The screen in SwiftUI
+
+```swift
+struct SettingsScreen: View {
+  @ObservedObject var screen: NativeScreen<SettingsProps>
+
+  var body: some View {
+    List {
+      Toggle("Notifications", isOn: Binding(
+        get: { screen.props.notifications },
+        set: { on in
+          Task { try await screen.props.onNotificationsChange(on) }
+        }
+      ))
+    }
+  }
+}
+```
+
+`screen.props` is published: when the store changes, `useProps` returns new props, and the view draws again.
+
+### 5. The screen in Compose
+
+```kotlin
+@Composable
+fun SettingsScreen(screen: NativeScreen<SettingsProps>) {
+  val props = screen.props
+  val scope = rememberCoroutineScope()
+  Switch(
+    checked = props.notifications,
+    onCheckedChange = { on ->
+      scope.launch { props.onNotificationsChange(on) }
+    },
+  )
+}
+```
+
+`screen.props` is Compose state: a new value composes the function again.
+
+### 6. Opening it
+
+From React, as any screen; TypeScript checks it as any screen:
+
+```ts
+navigation.push('Settings');
+```
+
+Settings slides in with its title in the bar, and the switch already shows the value of the store.
+
+## What happens when it shows
+
+1. A command names the screen. `push('Settings')`
+2. useProps runs, in a component of its own inside the app’s providers, and returns the props. `useProps()`
+3. The native side creates the screen with them: the first frame already has the data. `SettingsScreen(screen:)`
+4. The user turns the switch: the screen calls the function of its props, and the app saves. `onNotificationsChange(on)`
+5. The store changes, useProps returns new props, and the screen draws them. `screen.props`
+6. The user goes back: the hook stops with the screen. `pop`
+
+The command waits for the first result of `useProps`, so the screen never shows without its data. A `useProps` that throws makes the command waiting for it fail; later, the screen keeps the props it has. Either way the error goes to `onError` as an error of the screen (see [Where the errors go](./errors-and-loading#on-error)).
+
+## Types
+
+Each prop of TypeScript becomes a type of Swift and Kotlin:
+
+| TypeScript | Swift | Kotlin |
+| --- | --- | --- |
+| `string` | `String` | `String` |
+| `number` | `Double`; `Int` with the JSDoc tag `@int` | `Double`; `Int` with `@int` |
+| `boolean` | `Bool` | `Boolean` |
+| `'light' \| 'dark'` | `enum` | `enum class` |
+| `{ … }` | a `struct` of its own | a `data class` of its own |
+| `T[]` | `[T]` | `List` |
+| `(x: T) => Promise` | `(T) async throws -> R` | `suspend (T) -> R` |
+| `name?: T` | `T?` | `T?` |
+
+Every function is asynchronous on the native side, since its call goes to JavaScript and back. A type with no native form stops `codegen` with the prop it is in: `any` and `unknown`, a union of different types, a tuple, a function inside an object.
+
+## Functions with results
+
+A function of the props that returns a promise gives its result to the native side, and its error:
+
+```swift
+do {
+  items = try await screen.props.loadItems()
+} catch {
+  message = error.localizedDescription // the promise rejected
+}
+```
+
+```kotlin
+try {
+  items = screen.props.loadItems()
+} catch (error: Exception) {
+  message = error.message // the promise rejected
+}
+```
+
+## Commands from a native screen
+
+A native screen gets `navigation` with the commands of the screen it is, as `useNavigation()` gives a React screen:
+
+```swift
+Button("Edit") {
+  Task { try await screen.navigation.push("EditSettings") }
+}
+Button("Close") {
+  Task { try await screen.navigation.pop() }
+}
+```
+
+Kotlin has the same as `suspend` functions. The commands:
+
+- **Show:** `push`, `showModal`, `showOverlay`, `showInColumn`, each with a screen of the app, typed as below, or with a screen name and its props.
+- **Go back:** `pop`, `popTo`, `popToRoot`, and `dismiss` for the modal or the overlay the screen is in.
+- **Change:** `setOptions`, `selectTab`, `setTabBadge`.
+
+### Typed commands
+
+`codegen` also writes the screens of the app as a type of each platform. A command from native code then names a screen and gives its props the way Swift and Kotlin check them, as TypeScript checks a command in JavaScript:
+
+```swift
+Button("Open") {
+  Task {
+    try await screen.navigation.push(.details(title: "Item"))
+  }
+}
+```
+
+```kotlin
+import dev.apexnative.navigation.generated.Screens
+import dev.apexnative.navigation.generated.push
+
+scope.launch {
+  screen.navigation.push(Screens.Details(title = "Item"))
+}
+```
+
+A wrong name or a missing prop is an error of the compiler, not of the app at run time.
+
+- **Swift:** `enum Screens`, a case for each screen with its props as values: `.details(title: "Item")`, or `.home` for a screen without props. The types of a screen's props, an enum or an object, are under its name: `Screens.Details.Tab`.
+- **Kotlin:** `sealed class Screens`, a `data class` for each screen with props and an `object` for each without: `Screens.Details(title = "Item")`, `Screens.Home`. The types of its props are inside it: `Screens.Details.Tab`.
+- **Which screens:** every screen of `screens` and of the groups, React and native, in an app that has native screens. An optional prop that is a function isn't in the value, as native code can't give a function.
+- **Which are left out:** a screen with a required prop that is a function, and one with a prop whose type has no native form (see [Types](#types)). `codegen` names each in a warning. Native code still opens it by its name, `push("Settings", props: [:])`, with its props as a plain dictionary or map.
+- **After a change** of the screens or their props, run `codegen` again; `doctor` says when the generated code is behind.
+
+## UIKit and Android views
+
+A screen of UIKit or Android views gets the same `screen`, and follows its props as they change:
+
+```swift
+updates = screen.$props.sink { [weak self] props in
+  self?.toggle.isOn = props.notifications
+}
+```
+
+```kotlin
+init {
+  show(screen.props)
+  screen.onChange(::show)
+}
+```
+
+Make one with `--ios uikit` or `--android views`; `--ios` or `--android` alone makes it for one platform.
+
+## In layouts
+
+A native screen goes wherever a screen goes: in a stack, as a tab, as the content of a modal, in a column of a split view, in a [pair](../containers/arrangement) beside another screen:
+
+```ts
+const main = Tabs(
+  Tab('Map').label('Map'), // a native screen
+  Tab('Inbox').label('Inbox'), // a React screen
+);
+```
+
+It can also be **the first screen of the app**, such as a native sign-in. Its `useProps` runs in a hidden React root that starts with the app, while `willMount` runs, so the first screen doesn't wait for anything else.
+
+## API

package/docs-md/architecture/one-tree.md

@@ -0,0 +1,164 @@
+# One tree
+
+How screens render: a React root per screen by default, a provider around every screen, or one tree with every screen inside the app's provider. How it differs from navigation in the React tree, and when to pick which.
+
+A React app usually has its providers at the top of one tree: a store, a query client, the theme of a UI kit. Screens of this navigation are the platform's own screens, each with React content of its own, so the app says where its providers go. A provider that every screen shares goes in `appProvider`:
+
+```tsx
+import type { ReactNode } from 'react';
+import {
+  QueryClient,
+  QueryClientProvider,
+} from '@tanstack/react-query';
+
+const queryClient = new QueryClient();
+
+export function AppProvider({ children }: { children: ReactNode }) {
+  return (
+    <QueryClientProvider client={queryClient}>
+      {children}
+    </QueryClientProvider>
+  );
+}
+```
+
+```ts
+import { createNavigation } from '@apexnative/navigation';
+import { AppProvider } from './src/AppProvider';
+
+export const Navigation = createNavigation({
+  screens: { Inbox: InboxScreen, Message: MessageScreen },
+  root: 'Inbox',
+  appProvider: AppProvider,
+});
+```
+
+Every screen now renders inside `AppProvider`, and reads the one query client. This page answers:
+
+1. [How it differs](#compare) from navigation that lives in the React tree.
+2. [How screens render](#modes): a root per screen, or one tree.
+3. [A root per screen](#root-per-screen), the default, and [a provider around every screen](#screen-provider).
+4. [One tree](#one-tree), with every screen inside the app's provider.
+5. [Which to pick](#which).
+
+## How it differs
+
+When the navigation lives in the React tree, the screens are React components inside it, under the app's providers. A provider at the top reaches every screen by itself, because every screen is its child.
+
+Here the screens are the platform's. The platform's screen is created when a command shows it, and goes when the user leaves it. Each one needs React content of its own, and by default each gets **a React root of its own**. A provider at the top of one root doesn't reach the others, so the app says where its providers go:
+
+```tsx
+<QueryClientProvider client={client}>
+  <NavigationRoot>
+    <Screen name="Inbox" />
+    <Screen name="Message" />
+  </NavigationRoot>
+</QueryClientProvider>
+```
+
+```tsx
+createNavigation({
+  screens: { Inbox, Message },
+  root: 'Inbox',
+  // every screen renders inside it
+  appProvider: AppProvider,
+});
+```
+
+| | Navigation in the React tree | Here: a root per screen | Here: one tree |
+| --- | --- | --- | --- |
+| Where a screen renders | In the app's tree | In a React root of its own, inside its native screen | In the app's tree, shown in its native screen |
+| A provider at the top | Reaches every screen | Reaches nothing: `screenProvider` wraps each screen | Reaches every screen: `appProvider` |
+| Who moves the screens | React, with its state | The platform | The platform |
+| A screen that goes | Unmounts from the tree | Its root unmounts with the native screen | Its part of the tree unmounts with the native screen |
+
+So one tree gives back what a router in the React tree has, one set of providers for every screen, while the screens stay native.
+
+## How screens render
+
+The mode is set once, in `createNavigation`. With `appProvider` the app runs in one tree; without it each screen is a root of its own.
+
+## A root per screen
+
+Without providers in `createNavigation`, each screen is a React root of its own. A store kept in a module is shared anyway, because every screen imports the same module:
+
+```ts
+import { create } from 'zustand';
+
+type Cart = { count: number; add(): void };
+
+export const useCart = create<Cart>((set) => ({
+  count: 0,
+  add: () => set((cart) => ({ count: cart.count + 1 })),
+}));
+```
+
+```ts
+export const Navigation = createNavigation({
+  screens: { Products: ProductsScreen, Cart: CartScreen },
+  root: 'Products',
+});
+```
+
+Products adds to the cart, and the Cart screen pushed later shows the same count: both read `useCart`, and nothing wraps them. The same goes for Redux with its store imported, or MobX.
+
+### A provider around every screen
+
+`screenProvider` wraps every screen on its own. It is the place for providers that hold no state the screens share, such as the theme of a UI kit or the language of a translation library:
+
+```tsx
+export function ScreenProvider({ children }: { children: ReactNode }) {
+  // the provider of your UI kit
+  return <UiKitProvider theme={uiTheme}>{children}</UiKitProvider>;
+}
+```
+
+```ts
+export const Navigation = createNavigation({
+  screens: { Products: ProductsScreen, Cart: CartScreen },
+  root: 'Products',
+  screenProvider: ScreenProvider,
+});
+```
+
+Each screen has its own copy of it, so state kept inside it is the screen's alone: a counter in it starts from zero on every screen, and is gone when the screen goes.
+
+`screenProvider` also gets the screen as `screen: { id, name }`, so it can differ for one screen. It renders inside the screen, so the screen's hooks, such as `useScreen` and `useNavigation`, work in it; `appProvider` is above every screen, and has none.
+
+## One tree
+
+`appProvider` wraps the whole app once, and every screen renders inside it. It is the place for providers that hold **state the screens share in React context**, such as the query client of the example at the top of this page.
+
+The Inbox loads the messages; the Message screen pushed later reads the same query, and shows the message at once from the cache the Inbox filled:
+
+```tsx
+function Message({ id }: { id: string }) {
+  const { data } = useQuery({
+    queryKey: ['messages'],
+    queryFn: loadMessages, // your own request, the same as in Inbox
+  });
+  const message = data?.find((item) => item.id === id);
+  return <Text>{message?.body}</Text>;
+}
+```
+
+With a root per screen, each screen would need a client of its own: Message would start empty, and load the messages again.
+
+- **The screens stay native.** Each one is pushed, presented and put in tabs as any other, with its bars and gestures. Only its React content renders inside the app's tree, and its views show in the native screen.
+- **What `appProvider` holds lives as long as the app.** Screens come and go under it; a reload of the JavaScript starts it again.
+- **An error stays in its screen.** Each screen has an error boundary of its own, so one screen that fails doesn't take the tree down (see [A screen that fails](./errors-and-loading#error)).
+- **Native screens share it too.** The `useProps` hook of a [native screen](./native-screens#what) runs inside `appProvider`, so it reads the same query client.
+
+`appProvider` and `screenProvider` go together: the app's providers once, and inside them what each screen needs on its own.
+
+## Which to pick
+
+| The app has | Pick |
+| --- | --- |
+| No providers, or a store kept in a module | A root per screen: nothing to set. |
+| Providers without shared state, such as the theme of a UI kit | A root per screen, with `screenProvider`. |
+| State in React context that screens share, such as a query client or a provider-based store | One tree, with `appProvider`. |
+
+Every feature of the navigation works the same way in both: the Showcase runs each of its sections in either mode. One difference is in timing. (Android) A push in one tree renders the screen before it starts, so the screen comes in drawn, and the push starts later by the time React takes to render it (see [A push on Android, in one tree](./transitions#wait-one-tree)).
+
+## API