@apexnative/navigation 1.0.0-alpha.6 → 1.0.0-alpha.7

package/src/api/app/AppRegistry.ts

@@ -1,8 +1,14 @@
 import { AppRegistry as ReactNativeAppRegistry } from 'react-native';
 import { onNativeEvent } from '../../engine/native';
+import { familyOf } from '../../engine/refresh';
 import { SLOT_HOST_MODULE } from '../../engine/slots';
 import { SlotHost } from '../slots/SlotHost';
-import { isNavigationApp, type NavigationApp, startApp } from './createNavigation';
+import {
+  isNavigationApp,
+  type NavigationApp,
+  noteReplacingApp,
+  startApp,
+} from './createNavigation';
 
 type NavigationAppProvider = () => NavigationApp<any, any>;
 
@@ -35,7 +41,15 @@ function registerComponent(
   navigation: NavigationApp<any, any> | NavigationAppProvider
 ): string {
   if (__DEV__ && registered) {
-    console.warn(`[navigation] '${key}' replaces the app registered as '${appKey}'`);
+    // The entry file running again after an edit (Fast Refresh) registers its new version of the same app under the
+    // same name; Metro puts one it exports in the family of the old one once the file ran.
+    if (key === appKey) noteReplacingApp(navigation);
+    const before = { key: appKey, app: registered };
+    Promise.resolve().then(() => {
+      const family = familyOf(before.app);
+      if (key === before.key || (family && family === familyOf(navigation))) return;
+      console.warn(`[navigation] '${key}' replaces the app registered as '${before.key}'`);
+    });
   }
   appKey = key;
   registered = navigation;

package/src/api/app/createNavigation.ts

@@ -1,7 +1,10 @@
 import type { ComponentType } from 'react';
+import { DevSettings } from 'react-native';
 import { setDefaultOptions, setRoot } from '../../engine/commands';
 import { type AppProvider, enableSlots, withSlots } from '../../engine/slots';
 import { listenToNativeScreens, startHost } from '../../engine/nativeScreens';
+import { sameValue } from '../../engine/optionsChange';
+import { familyOf, keepStateOf, refreshRuns } from '../../engine/refresh';
 import { listenToSplitViews } from '../../engine/places';
 import { hasNativeScreenHooks } from '../../engine/screens';
 import type { LayoutRoot } from '../../interfaces/Layout';
@@ -24,7 +27,10 @@ import type { ErrorFallbackProps } from '../screens/ScreenBoundary';
 import { getAppContext, setAppContext } from '../context/appContext';
 import {
   type AppOptionsInput,
+  getDirection,
+  getTheme,
   initTheme,
+  setTheme,
   type NavigationDirection,
   type NavigationTheme,
   themedDefaultOptions,
@@ -51,6 +57,7 @@ import {
   linksStarted,
   reportLink,
   setupLinking,
+  updateLinking,
 } from '../linking/linking';
 import type { LinkMatch } from '../linking/linkPaths';
 import type { LinkingConfig } from '../linking/types';
@@ -86,6 +93,9 @@ const starts = new WeakMap<NavigationApp<any, any>, () => Promise<void>>();
 
 /** Starts the app, or brings back its root when the native side launches again. */
 export function startApp(app: NavigationApp<any, any>): Promise<void> {
+  // An app made after another launched knows once its module ran whether it is that app's next version.
+  const waiting = pending.get(app);
+  if (waiting) return waiting.then(() => startApp(app));
   const start = starts.get(app);
   if (!start) throw new Error('[navigation] Not an app made by createNavigation');
   return start();
@@ -240,7 +250,11 @@ type CheckedRoots<Root, Roots, AppScreens> = {
 };
 
 export function isNavigationApp(value: unknown): value is NavigationApp {
-  return typeof value === 'object' && value !== null && starts.has(value as NavigationApp);
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    (starts.has(value as NavigationApp) || pending.has(value as NavigationApp))
+  );
 }
 
 /**
@@ -277,14 +291,18 @@ export function createNavigation<
   > &
     NoInfer<CheckedRoots<FirstLayout, Roots, AllScreens<AppScreens, Groups>>>
 ): NavigationApp<Roots, AllScreens<AppScreens, Groups>> {
+  // The app that launched before, when this call may be its module running again after an edit (Fast Refresh): what
+  // the call starts waits until that is known.
+  const launched = __DEV__ ? hotCandidate() : undefined;
   // Counted from here: a "back again to leave" listener of the app's entry file comes after this call.
-  watchBackListeners();
+  if (!launched) watchBackListeners();
   // idle: not started yet, or the last start failed. mounting: the first root is on its way. mounted: it is shown.
   let phase: 'idle' | 'mounting' | 'mounted' = 'idle';
   let screensRegistered = false;
   // The splash shows at the first start of this runtime only: a start that failed and runs again goes without it.
   let splashChecked = false;
   let listening = false;
+  let removeListeners: (() => void) | undefined;
   let prepared: Promise<void> | undefined;
   let markMounted!: () => void;
   // A new activity came while the first root was on its way (Android): its link is taken once that root is shown.
@@ -325,6 +343,62 @@ export function createNavigation<
     return buildRoot(typeof root === 'function' ? root(context) : root);
   }
 
+  // The screens of the app, its groups, the screen of a failed start and the splash, with what wraps each of them.
+  function registerAppScreens() {
+    const wrapper = {
+      errorFallback: config.errorFallback,
+      loadingFallback: config.loadingFallback,
+      onError:
+        config.onError &&
+        ((error: unknown, screen: ScreenInfo, componentStack: string | null | undefined) =>
+          config.onError?.(error, { type: 'screen', screen, componentStack })),
+    };
+    registerScreens(
+      [
+        { source: 'screens', screens: config.screens ?? {} },
+        ...Object.entries(config.groups ?? {}).map(([group, { screens, options }]) => ({
+          source: `the group '${group}'`,
+          screens,
+          options,
+        })),
+        ...(config.errorFallback
+          ? [
+              {
+                source: 'the start',
+                screens: { [START_FAILURE_SCREEN]: startFailureScreen(config.errorFallback) },
+              },
+            ]
+          : []),
+      ],
+      { ...wrapper, provider: config.screenProvider }
+    );
+    // The splash renders before willMount ends: a root of its own, without the app's providers, which may need what
+    // willMount prepares.
+    if (config.splash) {
+      registerScreens(
+        [
+          {
+            source: 'the splash',
+            screens: { [SPLASH_SCREEN]: config.splash.component },
+            ownRoot: true,
+          },
+        ],
+        {
+          ...wrapper,
+          // A splash that failed to render can't call hide(): the start goes on without waiting for it.
+          onError: (
+            error: unknown,
+            screen: ScreenInfo,
+            componentStack: string | null | undefined
+          ) => {
+            releaseSplash();
+            wrapper.onError?.(error, screen, componentStack);
+          },
+        }
+      );
+    }
+  }
+
   async function mount() {
     phase = 'mounting';
     // The state before the first root: the links wait for a newer one, which tells the screen they act from.
@@ -333,54 +407,7 @@ export function createNavigation<
     let linkHandled = false;
     try {
       if (!screensRegistered) {
-        const wrapper = {
-          errorFallback: config.errorFallback,
-          loadingFallback: config.loadingFallback,
-          onError:
-            config.onError &&
-            ((error: unknown, screen: ScreenInfo, componentStack: string | null | undefined) =>
-              config.onError?.(error, { type: 'screen', screen, componentStack })),
-        };
-        registerScreens(
-          [
-            { source: 'screens', screens: config.screens ?? {} },
-            ...Object.entries(config.groups ?? {}).map(([group, { screens, options }]) => ({
-              source: `the group '${group}'`,
-              screens,
-              options,
-            })),
-            ...(config.errorFallback
-              ? [
-                  {
-                    source: 'the start',
-                    screens: { [START_FAILURE_SCREEN]: startFailureScreen(config.errorFallback) },
-                  },
-                ]
-              : []),
-          ],
-          { ...wrapper, provider: config.screenProvider }
-        );
-        // The splash renders before willMount ends: a root of its own, without the app's providers, which may need what
-        // willMount prepares.
-        if (config.splash) {
-          registerScreens(
-            [
-              {
-                source: 'the splash',
-                screens: { [SPLASH_SCREEN]: config.splash.component },
-                ownRoot: true,
-              },
-            ],
-            {
-              ...wrapper,
-              // A splash that failed to render can't call hide(): the start goes on without waiting for it.
-              onError: (error: unknown, screen: ScreenInfo, componentStack: string | null | undefined) => {
-                releaseSplash();
-                wrapper.onError?.(error, screen, componentStack);
-              },
-            }
-          );
-        }
+        registerAppScreens();
         screensRegistered = true;
       }
       // The link that launched the app is asked for first: on iOS the first React content to appear (the host below,
@@ -485,20 +512,13 @@ export function createNavigation<
   }
 
   async function launch() {
+    if (__DEV__) launchedApp = app;
     setActiveApp({ roots: config.roots, presentation: config.presentation, mounted });
     if (!listening) {
       listening = true;
       // The edges of `safeArea` go under the app's options; the window's color goes with them, as the native side
       // takes it from the default options.
-      initTheme(
-        config.theme,
-        {
-          under: config.safeArea && { layout: { safeAreaEdges: config.safeArea.edges } },
-          options: config.options,
-          over: config.window && { window: config.window },
-        },
-        config.direction
-      );
+      initTheme(config.theme, appDefaults(), config.direction);
       if (config.context !== undefined) setAppContext(config.context);
       if (config.appProvider) enableSlots(config.appProvider);
       listenToNavigationState();
@@ -507,7 +527,7 @@ export function createNavigation<
       listenToNativeScreens();
       listenToSplitViews();
       listenToNativeScreenCalls();
-      if (config.listeners) addNavigationListeners(config.listeners);
+      if (config.listeners) removeListeners = addNavigationListeners(config.listeners);
     }
     launchState.launch++;
     // A new activity has no default options: the last ones set come back, else the theme's and the app's.
@@ -528,19 +548,131 @@ export function createNavigation<
     relaunchWaiters.splice(0).forEach((resume) => resume());
   }
 
-  // The links listen from now on: one that comes before the native side launches waits for the first root.
-  if (config.linking) {
-    setupLinking(config.linking, {
+  // The routes of the links, the roots they name and where their errors go.
+  function linkingOptions() {
+    return {
       roots: config.roots,
-      onError: config.onError && ((error, url) => config.onError?.(error, { type: 'link', url })),
-    });
+      onError:
+        config.onError &&
+        ((error: unknown, url: string) => config.onError?.(error, { type: 'link', url })),
+    };
+  }
+
+  // Fast Refresh ran the module that makes the app again (development): its new config takes the place of the old.
+  // What only the start reads (the first root, willMount, the splash, the context) has done its part; the screens, the
+  // default options, the roots, the listeners and the links take the new one. A theme the same as before leaves the one
+  // the app set since. The providers and fallbacks are in the families of the ones before (`keepStateOf`): React
+  // Refresh puts the new ones in place, with the state of what they wrap.
+  function update(next: typeof config) {
+    const before = config;
+    // The app's one tree is set up at the start, or not: a provider added or taken out starts the app again.
+    if (!before.appProvider !== !next.appProvider) {
+      DevSettings.reload('[navigation] appProvider was added or taken out');
+      return;
+    }
+    config = next;
+    if (screensRegistered) registerAppScreens();
+    setActiveApp({ roots: config.roots, presentation: config.presentation, mounted });
+    // A direction the app set since stays too, unless the edit changes the config's.
+    const defaultsBefore = themedDefaultOptions();
+    const direction = sameValue(before.direction, next.direction) ? getDirection() : next.direction;
+    initTheme(getTheme(), appDefaults(), direction);
+    if (!sameValue(before.theme, next.theme)) {
+      setTheme(next.theme ?? {});
+    } else {
+      const defaults = themedDefaultOptions();
+      if (!sameValue(defaultsBefore, defaults)) setDefaultOptions(defaults ?? {});
+    }
+    if (listening) {
+      removeListeners?.();
+      removeListeners = config.listeners && addNavigationListeners(config.listeners);
+    }
+    if (config.linking && linkingStarted) updateLinking(config.linking, linkingOptions());
+    else startLinking();
+  }
+
+  // The default options of the app, under and over the theme's.
+  function appDefaults() {
+    return {
+      under: config.safeArea && { layout: { safeAreaEdges: config.safeArea.edges } },
+      options: config.options,
+      over: config.window && { window: config.window },
+    };
+  }
+
+  // The links listen from now on: one that comes before the native side launches waits for the first root.
+  let linkingStarted = false;
+  function startLinking() {
+    if (!config.linking || linkingStarted) return;
+    linkingStarted = true;
+    setupLinking(config.linking, linkingOptions());
+  }
+
+  // The components of the app keep their state across Fast Refresh, as the screens' do.
+  function keepComponentsState() {
+    if (!__DEV__) return;
+    keepStateOf(app, config.appProvider, 'appProvider');
+    keepStateOf(app, config.screenProvider, 'screenProvider');
+    keepStateOf(app, config.errorFallback, 'errorFallback');
+    keepStateOf(app, config.loadingFallback, 'loadingFallback');
+    keepStateOf(app, config.splash?.component, 'splash');
   }
 
   const app: NavigationApp<Roots, AllScreens<AppScreens, Groups>> = { [NAVIGATION_APP]: true };
-  starts.set(app, () => reportStart(launch));
+  keepComponentsState();
+  const start = () => {
+    startLinking();
+    starts.set(app, () => reportStart(launch));
+    if (__DEV__) updates.set(app, update as (config: unknown) => void);
+  };
+  if (!launched) {
+    start();
+    return app;
+  }
+  // Once the module ran, Metro has put its exports in the families of the ones of its run before: the same family as
+  // the app that launched, or the app's entry registering it under the app's name again (an app it doesn't export),
+  // means this is its module again, and the app that runs takes the new config.
+  pending.set(
+    app,
+    Promise.resolve().then(() => {
+      pending.delete(app);
+      const family = familyOf(app);
+      if ((family && family === familyOf(launched)) || replacing.delete(app)) {
+        updates.get(launched)?.(config);
+        starts.set(app, starts.get(launched)!);
+        updates.set(app, updates.get(launched)!);
+        return;
+      }
+      watchBackListeners();
+      start();
+    })
+  );
   return app;
 }
 
+// The app that launched in this runtime, and what takes the config of its module when it runs again (development).
+let launchedApp: NavigationApp<any, any> | undefined;
+const updates = new WeakMap<NavigationApp<any, any>, (config: unknown) => void>();
+// The apps made after the launch until their module ran, and those the app's entry registered again under its name.
+const pending = new WeakMap<NavigationApp<any, any>, Promise<void>>();
+const replacing = new WeakSet<NavigationApp<any, any>>();
+
+/**
+ * Notes an app the entry file registers under the name of the app that launched: the entry ran again after an edit
+ * (development), and the new app is the old one's next version.
+ */
+export function noteReplacingApp(app: unknown): void {
+  if (__DEV__ && launchedApp && typeof app === 'object' && app !== null && NAVIGATION_APP in app) {
+    replacing.add(app as NavigationApp<any, any>);
+  }
+}
+
+// The app that launched, when React Refresh runs and a new app may be its module running again: one its module
+// exports (Metro gives it a family), or one the entry registers again under the app's name.
+function hotCandidate(): NavigationApp<any, any> | undefined {
+  return launchedApp && refreshRuns() ? launchedApp : undefined;
+}
+
 // A willMount that never ends keeps the splash screen for good: in development the app hears of it.
 function warnIfLong(willMount: Promise<void>) {
   const timer = setTimeout(

package/src/api/events/navigationEvents.ts

@@ -166,10 +166,16 @@ export function onNavigationEvent<Name extends NavigationEventName>(
   return onNativeEvent(nativeName, deliver);
 }
 
-/** Listens to the events of `listeners`, for as long as the app runs. */
-export function addNavigationListeners(listeners: NavigationListeners) {
+/** Listens to the events of `listeners` until the function it gives is called. */
+export function addNavigationListeners(listeners: NavigationListeners): () => void {
+  const removers: (() => void)[] = [];
   for (const name of Object.keys(listeners) as NavigationEventName[]) {
     const handler = listeners[name];
-    if (handler) onNavigationEvent(name, handler as (event: NavigationEvents[typeof name]) => void);
+    if (handler) {
+      removers.push(
+        onNavigationEvent(name, handler as (event: NavigationEvents[typeof name]) => void)
+      );
+    }
   }
+  return () => removers.forEach((remove) => remove());
 }

package/src/api/index.ts

@@ -109,6 +109,7 @@ export type { NativeScreen } from './screens/nativeScreens';
 export { defineArrangement } from './screens/arrangement';
 export type { Arrangement, ArrangementDefinition, ScreenArrangement } from './screens/arrangement';
 export type {
+  DefinedScreen,
   OptionsEnvironment,
   ScreenDefinition,
   ScreenOptionsInput,

package/src/api/linking/linking.ts

@@ -6,7 +6,11 @@ import { commandsStarted, whenCommandsSettle } from '../commands/errors';
 import { getAppContext, subscribeAppContext } from '../context/appContext';
 import { buildRoot, type RootLayout } from '../layout/Root';
 import { navigation } from '../navigation';
-import { getNavigationState, whenScreenAfter, type NavigationState } from '../state/navigationState';
+import {
+  getNavigationState,
+  whenScreenAfter,
+  type NavigationState,
+} from '../state/navigationState';
 import {
   compileRoutes,
   matchLink,
@@ -68,6 +72,23 @@ export function setupLinking(
   setPendingLinkOpener((link) => run(link, routeOf(link), false));
 }
 
+/**
+ * Takes the routes, the roots and `onError` of an app whose module ran again after an edit (Fast Refresh, development):
+ * the links that come from now on find the new routes.
+ */
+export function updateLinking(
+  linking: Config,
+  options: {
+    roots: RootsMap | undefined;
+    onError: ((error: unknown, url: string) => void) | undefined;
+  }
+): void {
+  config = linking;
+  roots = options.roots;
+  onError = options.onError;
+  routes = compileRoutes(Object.keys(linking.routes));
+}
+
 /**
  * The link that launched the app, matched as the app starts (`unmatched` may run commands then); the same one for
  * every try of the first start.

package/src/api/screens/defineScreen.ts

@@ -1,5 +1,6 @@
-import type { ComponentType } from 'react';
+import { type ComponentType, createElement } from 'react';
 import type { Options } from '../../interfaces/Options';
+import { keepStateOf, newestType, redefined } from '../../engine/refresh';
 import { getAppContext } from '../context/appContext';
 import { readScreenOptions, ScreenOptions } from '../options/ScreenOptions';
 import { getTheme, type NavigationTheme } from '../theme/theme';
@@ -38,12 +39,55 @@ export interface ScreenDefinition<Props = any> {
   arrangement?: ScreenArrangement<Props & object>;
 }
 
+const SCREEN_DEFINITION = Symbol('apexnative.navigation.screenDefinition');
+
+/**
+ * A screen of `defineScreen`: a component of its own, which renders the screen's component and carries the screen's
+ * definition. It goes right into `screens` of createNavigation, and rendered on its own (a test) it renders the screen.
+ */
+export type DefinedScreen<Props> = ComponentType<Props> & {
+  readonly [SCREEN_DEFINITION]: ScreenDefinition<Props>;
+};
+
+/**
+ * Describes a screen next to its component, so its registration stays one line. It gives a component that renders the
+ * screen and goes right into `screens` of createNavigation: a file that exports only its screens stays a boundary of
+ * Fast Refresh, so an edit of the screen, its options too, updates it in place instead of reloading the app.
+ */
+export function defineScreen<Props>(definition: ScreenDefinition<Props>): DefinedScreen<Props> {
+  const { component } = definition;
+  // A component of each definition, so the app's own component stays as it is for any other use of it.
+  const Component = component as ComponentType<object>;
+  function Screen(props: Props) {
+    return createElement(Component, props as object);
+  }
+  Screen.displayName = component.displayName ?? component.name;
+  Object.defineProperty(Screen, SCREEN_DEFINITION, { value: definition });
+  keepStateOf(Screen, component);
+  redefined(Screen);
+  return Screen as DefinedScreen<Props>;
+}
+
 /**
- * Describes a screen next to its component, so its registration stays one line. The same object can go right into
- * `screens` of createNavigation.
+ * The definition a screen of `defineScreen` carries, the newest one after Fast Refresh ran the screen's module again;
+ * undefined for anything else.
  */
-export function defineScreen<Props>(definition: ScreenDefinition<Props>): ScreenDefinition<Props> {
-  return definition;
+export function definitionOf(value: unknown): ScreenDefinition | undefined {
+  return isDefinedScreen(value) ? ownDefinitionOf(newestType(value)) : undefined;
+}
+
+/** The definition a screen of `defineScreen` carries itself, not a newer one; undefined for anything else. */
+export function ownDefinitionOf(value: unknown): ScreenDefinition | undefined {
+  return isDefinedScreen(value) ? value[SCREEN_DEFINITION] : undefined;
+}
+
+/** Whether the value is a screen of `defineScreen`. */
+export function isDefinedScreen(value: unknown): value is DefinedScreen<any> {
+  return (
+    (typeof value === 'function' || typeof value === 'object') &&
+    value !== null &&
+    SCREEN_DEFINITION in value
+  );
 }
 
 export function buildScreenOptions<Props>(

package/src/api/screens/nativeScreens.ts

@@ -1,3 +1,5 @@
+import { useEffect } from 'react';
+import { redefined, resetOnEdit } from '../../engine/refresh';
 import type { ScreenArrangement } from './arrangement';
 import type { ScreenOptionsInput } from './defineScreen';
 
@@ -30,7 +32,9 @@ export interface NativeScreenDefinition<Props extends object> {
 
 /**
  * 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`).
+ * creator. `nativeName` is the name it is registered under natively (`ApexNavigation.registerNativeScreen`). It is a
+ * component that runs `useProps`, so a file that exports only its screens updates by Fast Refresh, the hook and the
+ * options too.
  *
  * @example
  * const Settings = nativeScreen('Settings', {
@@ -49,10 +53,42 @@ 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 };
+  const { options, useProps = noProps, arrangement } = definition;
+  // A component that runs the hook, so that a file exporting only its screens stays a boundary of Fast Refresh: React
+  // Refresh puts the new version in place, with the edited hook.
+  function NativeScreen({ props, onProps }: NativeScreenHookProps<Props>) {
+    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;
+  }
+  const screen = Object.assign(NativeScreen, {
+    [NATIVE_SCREEN]: true as const,
+    nativeName,
+    options,
+    useProps: definition.useProps,
+    arrangement,
+  });
+  // The hook is the app's and may have other hooks after an edit: its new version mounts anew.
+  resetOnEdit(screen);
+  redefined(screen);
+  return screen;
+}
+
+function noProps(): object {
+  return {};
+}
+
+/** What the component of a native screen renders with: the props of the command, and where the hook's result goes. */
+export interface NativeScreenHookProps<Props> {
+  props: Props;
+  onProps(result: object): void;
 }
 
 export function isNativeScreen(value: unknown): value is NativeScreen<any> {
-  return typeof value === 'object' && value !== null && NATIVE_SCREEN in value;
+  return (
+    (typeof value === 'function' || typeof value === 'object') &&
+    value !== null &&
+    NATIVE_SCREEN in value
+  );
 }