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

package/src/api/screens/defineScreen.ts

@@ -0,0 +1,57 @@
+import type { ComponentType } from 'react';
+import type { Options } from '../../interfaces/Options';
+import { getAppContext } from '../context/appContext';
+import { readScreenOptions, ScreenOptions } from '../options/ScreenOptions';
+import { getTheme, type NavigationTheme } from '../theme/theme';
+import type { RegisteredContext } from '../types';
+import type { ScreenArrangement } from './arrangement';
+
+/** What the options of a screen can read besides its props, as they are when a command shows the screen. */
+export interface OptionsEnvironment {
+  theme: NavigationTheme;
+  context: RegisteredContext;
+}
+
+/** The options of a screen: options as they are, or a chain built from its props, the theme and the context. */
+export type ScreenOptionsInput<Props> =
+  Options | ((options: ScreenOptions, props: Props, app: OptionsEnvironment) => ScreenOptions);
+
+/** A screen with what goes with it. */
+export interface ScreenDefinition<Props = any> {
+  component: ComponentType<Props>;
+  /** Applied when a command shows the screen, before it appears. */
+  options?: ScreenOptionsInput<Props>;
+  /**
+   * One screen per item, such as the chat with one person: a push of this screen goes back to the screen of the same
+   * stack with the same key, closing the screens over it, instead of showing a second one. The name of the screen goes
+   * in front of the key, so two screens never share one. In another stack it shows as usual.
+   */
+  key?: (props: Props) => string | number;
+  /**
+   * A second screen beside or under this one in a large window (iPad, iPhone Duo open, Android tablets and open
+   * foldables); anywhere else this screen shows alone, as it does without it. Shown by its own name, the screen is the
+   * primary of the pair: its bar is the pair's. For a pair with every setting, `defineArrangement`.
+   *
+   * @example
+   * defineScreen({ component: ProfileScreen, arrangement: { secondary: 'Details' } });
+   */
+  arrangement?: ScreenArrangement<Props & object>;
+}
+
+/**
+ * Describes a screen next to its component, so its registration stays one line. The same object can go right into
+ * `screens` of createNavigation.
+ */
+export function defineScreen<Props>(definition: ScreenDefinition<Props>): ScreenDefinition<Props> {
+  return definition;
+}
+
+export function buildScreenOptions<Props>(
+  input: ScreenOptionsInput<Props> | undefined,
+  props: Props
+): Options {
+  if (!input) return {};
+  if (typeof input !== 'function') return input;
+  const app: OptionsEnvironment = { theme: getTheme(), context: getAppContext() };
+  return readScreenOptions(input(new ScreenOptions(), props, app));
+}

package/src/api/screens/nativeScreenCalls.ts

@@ -0,0 +1,59 @@
+import {
+  answerNativeScreenCall,
+  callNativeScreenFunction,
+  nativeScreenInfo,
+} from '../../engine/nativeScreens';
+import { onNativeEvent } from '../../engine/native';
+import type { NativeScreenCallEvent } from '../../interfaces/Events';
+import { screenNavigation, type ScreenNavigation } from '../hooks/useNavigation';
+
+// The commands a native screen runs from itself, as `useNavigation()` of a React screen does.
+const COMMANDS = [
+  'push',
+  'pop',
+  'popTo',
+  'popToRoot',
+  'showInColumn',
+  'showModal',
+  'dismiss',
+  'showOverlay',
+  'setOptions',
+  'selectTab',
+  'setTabBadge',
+] as const satisfies readonly (keyof ScreenNavigation)[];
+
+let listening = false;
+
+/** Runs what the native screens call: the functions of their props, and the commands of the navigation from them. */
+export function listenToNativeScreenCalls(): void {
+  if (listening) return;
+  listening = true;
+  onNativeEvent<NativeScreenCallEvent>(
+    'NativeScreenCall',
+    ({ componentId, callId, kind, name, args }) => {
+      answerNativeScreenCall(
+        callId,
+        new Promise((resolve) =>
+          resolve(
+            kind === 'command'
+              ? command(componentId, name, args)
+              : callNativeScreenFunction(componentId, name, args)
+          )
+        )
+      );
+    }
+  );
+}
+
+function command(componentId: string, name: string, args: unknown[]): unknown {
+  const screen = nativeScreenInfo(componentId);
+  if (!screen) throw new Error(`[navigation] No native screen has the id '${componentId}'`);
+  if (!(COMMANDS as readonly string[]).includes(name)) {
+    throw new Error(`[navigation] '${name}' is not a command of a screen: ${COMMANDS.join(', ')}`);
+  }
+  const navigation = screenNavigation(screen) as unknown as Record<
+    string,
+    (...args: unknown[]) => unknown
+  >;
+  return navigation[name](...args);
+}

package/src/api/screens/nativeScreens.ts

@@ -0,0 +1,58 @@
+import type { ScreenArrangement } from './arrangement';
+import type { ScreenOptionsInput } from './defineScreen';
+
+const NATIVE_SCREEN = Symbol('apexnative.navigation.nativeScreen');
+
+/** A screen made on the native side (SwiftUI, UIKit, Compose, Android views), registered there under `nativeName`. */
+export interface NativeScreen<Props extends object = {}> {
+  readonly [NATIVE_SCREEN]: true;
+  readonly nativeName: string;
+  readonly options?: ScreenOptionsInput<Props>;
+  readonly useProps?: (props: Props) => object;
+  readonly arrangement?: ScreenArrangement<Props>;
+  /** Carries the type of the props; never set. */
+  readonly props?: Props;
+}
+
+/** How a native screen shows: its options, and the hook that gives it the app's data. */
+export interface NativeScreenDefinition<Props extends object> {
+  options?: ScreenOptionsInput<Props>;
+  /**
+   * Gives the screen props from the app while it is open: data of the stores and of the app's context, functions the
+   * native side calls (`dispatch`, the API client). A hook: it runs in a component of its own, inside the app's
+   * providers and with the navigation of the screen, so any hook works in it. What it returns goes over the props of
+   * the command; the command shows the screen once it has returned, and every change goes to the native side.
+   */
+  useProps?: (props: Props) => object;
+  /** A second screen beside or under this one in a large window, as `arrangement` of `defineScreen`. */
+  arrangement?: ScreenArrangement<Props>;
+}
+
+/**
+ * A native screen for `screens`: commands and layouts name it like any other screen, and its props go to the native
+ * creator. `nativeName` is the name it is registered under natively (`ApexNavigation.registerNativeScreen`).
+ *
+ * @example
+ * const Settings = nativeScreen('Settings', {
+ *   useProps: () => {
+ *     const notifications = useSelector(selectNotifications);
+ *     const dispatch = useDispatch();
+ *     return {
+ *       notifications,
+ *       onNotificationsChange: (on: boolean) =>
+ *         dispatch(setNotifications(on)),
+ *     };
+ *   },
+ * });
+ */
+export function nativeScreen<Props extends object = {}>(
+  nativeName: string,
+  definition: NativeScreenDefinition<Props> = {}
+): NativeScreen<Props> {
+  const { options, useProps, arrangement } = definition;
+  return { [NATIVE_SCREEN]: true, nativeName, options, useProps, arrangement };
+}
+
+export function isNativeScreen(value: unknown): value is NativeScreen<any> {
+  return typeof value === 'object' && value !== null && NATIVE_SCREEN in value;
+}

package/src/api/screens/registerScreens.tsx

@@ -0,0 +1,364 @@
+import React, {
+  Component,
+  type ComponentType,
+  createContext,
+  type ErrorInfo,
+  lazy,
+  type ReactNode,
+  Suspense,
+  useEffect,
+  useMemo,
+  useState,
+} from 'react';
+import { Platform, StyleSheet } from 'react-native';
+import ANNTurboModule from '../../adapters/NativeANNTurboModule';
+import type { NativeControllerProps } from '../../engine/nativeScreens';
+import { isButtonRoot } from '../../engine/props';
+import {
+  checkArrangements,
+  type EngineArrangement,
+  onScreenUnmounted,
+  registerScreen as registerEngineScreen,
+  type ScreenRootProps,
+} from '../../engine/screens';
+import { screenUnmounted } from '../events/screenLifecycle';
+import { mergeOptions } from '../../engine/mergeOptions';
+import { preparedPadding } from '../../engine/slots';
+import { buildScreenOptions, type ScreenDefinition, type ScreenOptionsInput } from './defineScreen';
+import { isNativeScreen, type NativeScreen } from './nativeScreens';
+import {
+  type Arrangement,
+  isArrangement,
+  type ScreenArrangement,
+  toEngineArrangement,
+} from './arrangement';
+import { type ErrorFallbackProps, ScreenBoundary } from './ScreenBoundary';
+import ANNSafeAreaView from '../safeArea/ANNSafeAreaViewNativeComponent';
+
+type ScreenComponent = ComponentType<any>;
+type ScreenModule =
+  ScreenComponent | ScreenDefinition | { default: ScreenComponent | ScreenDefinition };
+
+/**
+ * A screen: its component, its definition (`{ component, options }`, see `defineScreen`), `{ load }` to load its
+ * module the first time a command shows it (`() => import('./screens/Settings')`, the screen is its default export),
+ * or a screen of the native side (`nativeScreen`).
+ */
+export type ScreenEntry =
+  | ScreenComponent
+  | ScreenDefinition
+  | { load: () => ScreenModule | PromiseLike<ScreenModule> }
+  | NativeScreen<any>
+  | Arrangement<any>;
+
+export type Screens = Record<string, ScreenEntry>;
+
+/** A screen: the id of this showing of it, and its name in `screens`. */
+export interface ScreenInfo {
+  /** The id of this showing: two screens pushed one over the other have the same name and different ids. */
+  id: string;
+  /** Its name in `screens`. */
+  name: string;
+}
+
+/** Wraps every screen on its own. */
+export type ScreenProvider = ComponentType<{ children: ReactNode; screen: ScreenInfo }>;
+
+/** What a screen shows while it waits for a lazy component or data. */
+export type LoadingFallback = ComponentType<{ screen: ScreenInfo }>;
+
+/** What the app wraps each of its screens in. */
+export interface ScreenWrapper {
+  provider?: ScreenProvider;
+  errorFallback?: ComponentType<ErrorFallbackProps>;
+  loadingFallback?: LoadingFallback;
+  /** An error of a screen's render, with the screen and React's component stack. */
+  onError?: (error: unknown, screen: ScreenInfo, componentStack: string | null | undefined) => void;
+}
+
+export const ScreenContext = createContext<ScreenInfo | null>(null);
+
+/** Screens sharing options, such as the sign-in screens without a top bar. */
+export interface ScreenGroup {
+  /** The options of every screen of the group; the screen's own options go over them. */
+  options?: ScreenOptionsInput<object>;
+  screens: Screens;
+}
+
+/** Screens to register: those of `screens`, or of a group. */
+export interface ScreenSet {
+  /** Where the screens come from, for the errors. */
+  source: string;
+  screens: Screens;
+  options?: ScreenOptionsInput<object>;
+  /** The screens render as React roots of their own, in the app's one tree too. */
+  ownRoot?: boolean;
+}
+
+// The root of a screen tells when it unmounts: what the screen left behind goes.
+onScreenUnmounted(screenUnmounted);
+
+export function registerScreens(sets: ScreenSet[], wrapper: ScreenWrapper = {}) {
+  // The screens of every set are in one namespace: a command names a screen without its group.
+  const sources = new Map<string, string>();
+  for (const { source, screens, options, ownRoot } of sets) {
+    for (const [name, entry] of Object.entries(screens)) {
+      const other = sources.get(name);
+      if (other) {
+        throw new Error(
+          `[navigation] The screen '${name}' is in ${other} and in ${source}: a name goes once`
+        );
+      }
+      sources.set(name, source);
+      registerScreen(name, entry, wrapper, options, ownRoot);
+    }
+  }
+  // A pair names screens of any set.
+  checkArrangements();
+}
+
+function registerScreen(
+  name: string,
+  entry: ScreenEntry,
+  wrapper: ScreenWrapper,
+  groupOptions: ScreenOptionsInput<object> | undefined,
+  ownRoot: boolean | undefined
+) {
+  if (isArrangement(entry)) {
+    registerEngineScreen(name, {
+      pair: toEngineArrangement(entry.definition.primary, entry.definition),
+    });
+    return;
+  }
+  if (isNativeScreen(entry)) {
+    registerEngineScreen(name, {
+      nativeName: entry.nativeName,
+      options: (props) =>
+        mergeOptions(
+          buildScreenOptions(groupOptions, props),
+          buildScreenOptions(entry.options, props)
+        ),
+      controller: entry.useProps && wrapNativeScreen(name, entry.useProps, wrapper),
+      arrangement: pairOf(name, entry.arrangement),
+    });
+    return;
+  }
+  // React.memo and forwardRef components are objects, so the kind of entry is told by its keys.
+  if (isObject(entry) && 'load' in entry) {
+    const screen = lazyScreen(entry.load);
+    registerEngineScreen(name, {
+      component: () => wrapScreen(name, screen.component, wrapper),
+      // A command loads the screen before it reads its options.
+      options: (props) =>
+        mergeOptions(
+          buildScreenOptions(groupOptions, props),
+          buildScreenOptions(screen.definition()?.options, props)
+        ),
+      key: (props) => screen.definition()?.key?.(props),
+      load: screen.load,
+      ownRoot,
+      arrangement: () => {
+        const arrangement = screen.definition()?.arrangement;
+        return arrangement && toEngineArrangement(name, arrangement);
+      },
+    });
+    return;
+  }
+  const definition = toDefinition(entry);
+  registerEngineScreen(name, {
+    component: () => wrapScreen(name, definition.component, wrapper),
+    options: (props) =>
+      mergeOptions(
+        buildScreenOptions(groupOptions, props),
+        buildScreenOptions(definition.options, props)
+      ),
+    key: definition.key && ((props) => definition.key!(props)),
+    ownRoot,
+    arrangement: pairOf(name, definition.arrangement),
+  });
+}
+
+// The pair of a screen whose `arrangement` is known at registration: checked and filled in once.
+function pairOf(
+  name: string,
+  arrangement: ScreenArrangement<any> | undefined
+): (() => EngineArrangement) | undefined {
+  if (!arrangement) return undefined;
+  const pair = toEngineArrangement(name, arrangement);
+  return () => pair;
+}
+
+function toDefinition(value: ScreenComponent | ScreenDefinition): ScreenDefinition {
+  return isObject(value) && 'component' in value ? value : { component: value };
+}
+
+/**
+ * A screen whose module loads the first time a command shows it. A failed load is tried again by the next command.
+ * The component renders the loaded screen; one that renders before (a bar's component in the options of another
+ * screen) waits for it in Suspense.
+ */
+function lazyScreen(loadModule: () => ScreenModule | PromiseLike<ScreenModule>) {
+  let definition: ScreenDefinition | undefined;
+  let loading: Promise<void> | undefined;
+  const load = (): Promise<void> | undefined => {
+    if (definition) return undefined;
+    if (!loading) {
+      loading = Promise.resolve()
+        .then(loadModule)
+        .then((module) => {
+          definition = toDefinition(unwrapModule(module));
+        });
+      loading.catch(() => {
+        loading = undefined;
+      });
+    }
+    return loading;
+  };
+  const Loaded = lazy(async () => {
+    await load();
+    return { default: definition!.component };
+  });
+  function LazyScreen(props: object) {
+    // The same component for the life of the view, so that the load doesn't mount it again.
+    const [Screen] = useState(() => definition?.component ?? Loaded);
+    return <Screen {...props} />;
+  }
+  return { load, definition: () => definition, component: LazyScreen };
+}
+
+function unwrapModule(loaded: ScreenModule): ScreenComponent | ScreenDefinition {
+  return isObject(loaded) && 'default' in loaded ? loaded.default : loaded;
+}
+
+function isObject(value: unknown): value is object {
+  return typeof value === 'object' && value !== null;
+}
+
+// Without the native side (tests with the mock) nothing lays the safe area view out: the content renders at once.
+const WAITS_FOR_LAYOUT = ANNTurboModule != null;
+
+function wrapScreen(name: string, Screen: ScreenComponent, wrapper: ScreenWrapper) {
+  const { provider: Provider, errorFallback, loadingFallback: Loading, onError } = wrapper;
+  // The component gets the props of the command, nothing else: its id comes from useScreen().
+  function NavigationScreen({ componentId, ...props }: ScreenRootProps) {
+    const screen = useMemo(() => ({ id: componentId, name }), [componentId]);
+    // The content renders once the safe area view is laid out in its place, as react-native-safe-area-context does:
+    // a list that is there before the first layout of the top bar makes UIKit start the large title collapsed. A
+    // screen the native side laid out before its push (Android, one tree) knows its padding: it renders at once.
+    const [initialPadding] = useState(() => preparedPadding(componentId));
+    const [ready, setReady] = useState(!WAITS_FOR_LAYOUT || initialPadding !== undefined);
+    // On iOS the native side only sizes a bar button's slot to the content and moves nothing inside it: the content is
+    // centered here. Android's cell centers the component itself.
+    const [barButton] = useState(() => Platform.OS === 'ios' && isButtonRoot(componentId));
+    // One boundary inside the provider, so the fallback has what it provides, and one outside for the provider itself.
+    const boundary = (children: ReactNode) => (
+      <ScreenBoundary
+        screen={screen}
+        fallback={errorFallback}
+        onError={onError && ((error, stack) => onError(error, screen, stack))}
+      >
+        {children}
+      </ScreenBoundary>
+    );
+    const content = boundary(
+      <Suspense fallback={Loading ? <Loading screen={screen} /> : null}>
+        <Screen {...props} />
+      </Suspense>
+    );
+    return (
+      // Outside the providers, so the screen's navigation works inside them and in the fallbacks too.
+      <ScreenContext.Provider value={screen}>
+        {/* Keeps everything of the screen, the fallbacks too, out of its safe area on the edges of its options.
+            box-none: an overlay lets the touches outside its content through. */}
+        <ANNSafeAreaView
+          screenId={componentId}
+          initialPadding={initialPadding}
+          onReady={() => setReady(true)}
+          contentRendered={ready}
+          pointerEvents="box-none"
+          style={barButton ? [styles.safeArea, styles.barButton] : styles.safeArea}
+        >
+          {ready
+            ? Provider
+              ? boundary(<Provider screen={screen}>{content}</Provider>)
+              : content
+            : null}
+        </ANNSafeAreaView>
+      </ScreenContext.Provider>
+    );
+  }
+  NavigationScreen.displayName = `Screen(${name})`;
+  return NavigationScreen;
+}
+
+/**
+ * The controller of a native screen's `useProps`: the hook in a component of its own, with the screen's navigation
+ * and inside the screen provider, as a React screen has them. It renders nothing.
+ */
+function wrapNativeScreen(
+  name: string,
+  useProps: (props: object) => object,
+  { provider: Provider, onError }: ScreenWrapper
+): ComponentType<NativeControllerProps> {
+  function Hook({ props, onProps }: Pick<NativeControllerProps, 'props' | 'onProps'>) {
+    const result = useProps(props);
+    // After each render React committed, so the native side never shows what the app did not.
+    useEffect(() => onProps(result));
+    return null;
+  }
+  function NativeScreenProps({
+    componentId,
+    props,
+    onProps,
+    onError: failed,
+  }: NativeControllerProps) {
+    const screen = useMemo(() => ({ id: componentId, name }), [componentId]);
+    const hook = <Hook props={props} onProps={onProps} />;
+    return (
+      <ScreenContext.Provider value={screen}>
+        <HookBoundary
+          onError={(error, componentStack) => {
+            failed(error);
+            onError?.(error, screen, componentStack);
+          }}
+        >
+          {/* A hook that waits (Suspense) holds back its own command and nothing else. */}
+          <Suspense fallback={null}>
+            {Provider ? <Provider screen={screen}>{hook}</Provider> : hook}
+          </Suspense>
+        </HookBoundary>
+      </ScreenContext.Provider>
+    );
+  }
+  NativeScreenProps.displayName = `NativeScreenProps(${name})`;
+  return NativeScreenProps;
+}
+
+// A hook that failed renders nothing again: the screen keeps the props it has.
+class HookBoundary extends Component<
+  {
+    children: ReactNode;
+    onError(error: unknown, componentStack: string | null | undefined): void;
+  },
+  { failed: boolean }
+> {
+  state = { failed: false };
+
+  static getDerivedStateFromError() {
+    return { failed: true };
+  }
+
+  componentDidCatch(error: unknown, info: ErrorInfo) {
+    this.props.onError(error, info.componentStack);
+  }
+
+  render() {
+    return this.state.failed ? null : this.props.children;
+  }
+}
+
+const styles = StyleSheet.create({
+  safeArea: { flex: 1 },
+  // Centered, not stretched: the content keeps its own size, so the slot still measures the content's width.
+  barButton: { justifyContent: 'center', alignItems: 'center' },
+});

package/src/api/slots/ANNSlotNativeComponent.ts

@@ -0,0 +1,23 @@
+import {
+  codegenNativeComponent,
+  type CodegenTypes,
+  type HostComponent,
+  type ViewProps,
+} from 'react-native';
+
+// `nativeID` is the slot id.
+export interface NativeProps extends ViewProps {
+  /**
+   * `[width, height]` in dp: the size of the container its screen was laid out in before the push (Android), so the
+   * first layout already has it. Empty: the container gives it once it is laid out.
+   */
+  initialSize?: ReadonlyArray<CodegenTypes.Float>;
+}
+
+/**
+ * Shows its children inside the native container with the same slot id (`nativeID`), at the container's size. The
+ * children stay in the app's one React tree, so they read its providers.
+ */
+export default codegenNativeComponent<NativeProps>('ANNSlot', {
+  interfaceOnly: true,
+}) as HostComponent<NativeProps>;

package/src/api/slots/SlotHost.tsx

@@ -0,0 +1,64 @@
+import React, { memo, useEffect, useLayoutEffect, useMemo, useSyncExternalStore } from 'react';
+import { StyleSheet } from 'react-native';
+import {
+  hostMountedChanged,
+  type NativeScreenHook,
+  nativeScreenHooks,
+} from '../../engine/nativeScreens';
+import { screenRoot } from '../../engine/screens';
+import { type Slot, slotCommitted, slotStore } from '../../engine/slots';
+import ANNSlot from './ANNSlotNativeComponent';
+
+// The native side sizes a slot to its container and positions it absolutely; it starts at the corner of the host.
+const styles = StyleSheet.create({ slot: { left: 0, top: 0 } });
+
+// One per screen: a screen shown or gone does not render the others again.
+const SlotScreen = memo(function SlotContent({ slot }: { slot: Slot }) {
+  const Screen = screenRoot(slot.name);
+  const { key, held, frame } = slot;
+  const initialSize = useMemo(() => frame && [frame.width, frame.height], [frame]);
+  // A screen laid out before its push is pushed once React committed it.
+  useLayoutEffect(() => {
+    if (frame && !held) slotCommitted(key);
+  }, [key, held, frame]);
+  if (!Screen || held) return null;
+  return (
+    <ANNSlot nativeID={slot.id} style={styles.slot} initialSize={initialSize}>
+      <Screen componentId={slot.id} />
+    </ANNSlot>
+  );
+});
+
+// One per native screen with `useProps`: its hook, which renders nothing.
+const NativeScreenProps = memo(function NativeScreenContent({ hook }: { hook: NativeScreenHook }) {
+  const { Controller, componentId, props, onProps, onError } = hook;
+  return <Controller componentId={componentId} props={props} onProps={onProps} onError={onError} />;
+});
+
+function NativeScreenHooks() {
+  const hooks = useSyncExternalStore(nativeScreenHooks.subscribe, nativeScreenHooks.get);
+  return hooks.map((hook) => <NativeScreenProps key={hook.key} hook={hook} />);
+}
+
+/**
+ * The app's hidden React root, which the native side runs as `SLOT_HOST_MODULE`: in one tree, the app's provider
+ * around a slot for every screen shown; in any mode, the hooks of the native screens (`useProps`), inside the app's
+ * provider when there is one. Before the app starts, as after a reload, it renders no screens.
+ */
+export function SlotHost() {
+  const { provider: Provider, slots } = useSyncExternalStore(slotStore.subscribe, slotStore.get);
+  useEffect(() => {
+    hostMountedChanged(true);
+    return () => hostMountedChanged(false);
+  }, []);
+  // The app sets its provider as it launches, before a command shows a screen: the hooks never move under it.
+  if (!Provider) return <NativeScreenHooks />;
+  return (
+    <Provider>
+      {slots.map((slot) => (
+        <SlotScreen key={slot.key} slot={slot} />
+      ))}
+      <NativeScreenHooks />
+    </Provider>
+  );
+}