@apexnative/navigation 1.0.0-alpha.1 → 1.0.0-alpha.11

package/src/api/commands/commands.ts

@@ -19,7 +19,7 @@ import { stackChild, type StackEntry } from '../layout/Stack';
 import { badgeText } from '../layout/Tabs';
 import { mergeOptions } from '../../engine/mergeOptions';
 import { buildScreenOptions, type ScreenOptionsInput } from '../screens/defineScreen';
-import { coversColumn, placeOf } from '../../engine/places';
+import { coversColumn, firstScreenOf, placeOf, type ScreenPlace } from '../../engine/places';
 import { command, placeFor } from './errors';
 import type { ColumnConfig, ModalConfig, OverlayConfig, PushConfig } from './presentation';
 import { defined, modalAnimations, pushAnimations } from './transitions';
@@ -30,6 +30,10 @@ const CLOSE_BUTTON = 'CloseButton';
 // The modals shown by `showModal`, for the ids of their first screens.
 let modals = 0;
 
+// The stacks of the modals shown with a close button, by id: `setStack` and `replace` there give it to the new first
+// screen. A stack's id is its modal's layer.
+const closeButtonStacks = new Set<string>();
+
 // The settings of a command with the props of the screen it shows.
 type WithProps<Config> = Config & { props?: object };
 
@@ -115,7 +119,19 @@ export function popToRoot(fromId: string): Promise<string> {
 export function setStack(fromId: string, entries: StackEntry[]): Promise<string> {
   return command('setStack', () => {
     placeFor('setStack', fromId, { stack: true });
-    return withSlots(() => engine.setStackRoot(fromId, entries.map(stackChild)));
+    const children = entries.map(stackChild);
+    const first = children[0]?.component;
+    if (!first || !hasCloseButton(placeOf(fromId))) {
+      return withSlots(() => engine.setStackRoot(fromId, children));
+    }
+    return afterLoading([first.name], () => {
+      // The screen's own buttons stay after the close button: the options of the layout replace them.
+      const id = first.id ?? nextId('Component');
+      const own = screenOptions(first.name, first.passProps ?? {});
+      const options = withCloseButton(mergeOptions(own, first.options ?? {}), id);
+      const withButton = { component: { ...first, id, options } };
+      return withSlots(() => engine.setStackRoot(fromId, [withButton, ...children.slice(1)]));
+    });
   });
 }
 
@@ -133,11 +149,12 @@ export function replace(
     return afterLoading([name], () => {
       const { props } = config;
       const base = getActiveApp()?.presentation?.push;
-      const options = showOptions(name, props, AS_PUSH, base?.options, config.options, {
+      const id = nextId('Component');
+      let options = showOptions(name, props, AS_PUSH, base?.options, config.options, {
         app: pushAnimations(base?.transition),
         call: pushAnimations(config.transition),
       });
-      const id = nextId('Component');
+      if (hasCloseButton(placeOf(fromId))) options = withCloseButton(options, id);
       return withSlots(() =>
         engine.setStackRoot(fromId, [screenLayout(name, props, options, id)])
       ).then(() => id);
@@ -192,16 +209,25 @@ function showModalNow(name: string, config: WithProps<ModalConfig>): Promise<str
     app: modalAnimations(base.transition),
     call: modalAnimations(call.transition),
   });
-  if (settings.closeButton && settings.stack !== false)
+  // The stack gets its id here, so that the commands in it later know the modal had a close button.
+  const stackId = nextId('Stack');
+  const closeButton = settings.closeButton && settings.stack !== false;
+  if (closeButton) {
     options = withCloseButton(options, screenId);
+    closeButtonStacks.add(stackId);
+    forgetWithStack(stackId, screenId);
+  }
   if (call.onDismiss) whenScreenUnmounts(screenId, call.onDismiss);
   const screen = screenLayout(name, props, options, screenId);
   const presentation = presentationOptions(settings);
   const layout: Layout =
     settings.stack === false
       ? mergeLayoutOptions(screen, presentation)
-      : { stack: { children: [screen], options: presentation } };
-  return withSlots(() => engine.showModal(layout));
+      : { stack: { id: stackId, children: [screen], options: presentation } };
+  const shown = withSlots(() => engine.showModal(layout));
+  // A modal that never showed has no stack to remember.
+  if (closeButton) shown.catch(() => closeButtonStacks.delete(stackId));
+  return shown;
 }
 
 export function dismissModal(modalId: string): Promise<string> {
@@ -340,6 +366,21 @@ export function holdLeave(screenId: string, onAttempt: () => void): () => void {
   };
 }
 
+// Whether a screen is in the stack of a modal shown with a close button: the modal's own stack, not one in it.
+function hasCloseButton(place: ScreenPlace | undefined): boolean {
+  return place?.stack != null && place.stack === place.layer && closeButtonStacks.has(place.stack);
+}
+
+// The stack of a modal is gone with its last first screen: one that unmounts with no other first screen noted after
+// it (`setStack`, `replace` note theirs before the old one goes).
+function forgetWithStack(stackId: string, screenId: string): void {
+  whenScreenUnmounts(screenId, () => {
+    const next = firstScreenOf(stackId);
+    if (next) forgetWithStack(stackId, next);
+    else closeButtonStacks.delete(stackId);
+  });
+}
+
 /** The options with a close button first at the leading edge, which dismisses the modal of the screen. */
 function withCloseButton(options: Options, screenId: string): Options {
   const close: NavigationButton = {

package/src/api/commands/presentation.ts

@@ -43,12 +43,13 @@ export interface ModalConfig {
   stack?: boolean;
   /**
    * A close button at the leading edge of the modal's first screen, which dismisses the modal: the system one on iOS,
-   * an icon on Android. Its id and testID are `CloseButton`. Needs the stack.
+   * an icon on Android. Its id and testID are `CloseButton`. Needs the stack. A new first screen of that stack, from
+   * `setStack` or `replace`, gets it too.
    */
   closeButton?: boolean;
   /**
-   * Called once the modal is gone, whatever dismissed it: a command, a swipe, a new root. `setStack` inside the
-   * modal replaces its first screen, and calls it too.
+   * Called once the modal is gone, whatever dismissed it: a command, a swipe, a new root. `setStack` and `replace`
+   * inside the modal replace its first screen, and call it too.
    */
   onDismiss?: () => void;
   /**

package/src/api/events/navigationEvents.ts

@@ -48,7 +48,7 @@ export interface NavigationEvents {
   searchCancelled: ScreenEventOf<SearchBarCancelPressedEvent>;
   /** #### (iOS 16+, Android) The user picked a suggestion of `searchBar.suggestions`; the text stays. */
   searchSuggestionPicked: ScreenEventOf<NativeSearchSuggestionPickedEvent>;
-  /** #### (iOS specific) */
+  /** The user dragged a sheet to another detent. */
   sheetDetentChanged: ScreenEventOf<NativeSheetDetentChangedEvent>;
   /** #### (iOS specific) */
   splitViewDisplayModeChanged: NativeSplitViewDisplayModeChangedEvent;
@@ -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/hooks/useNavigation.ts

@@ -22,7 +22,7 @@ import type { ScreenName, ShowArgs } from '../types';
 interface ScreenCommands {
   /** The screen the commands act from. */
   readonly screen: ScreenInfo;
-  /** Shows a screen over this one in its stack; resolves with the id of the screen shown. */
+  /** Shows a screen over this one in its stack; resolves with the id of the screen shown (for a pair, the pair's id). */
   push<Name extends ScreenName>(name: Name, ...args: ShowArgs<Name, PushConfig>): Promise<string>;
   /**
    * Goes back to the screen before this one in its stack. The first screen of a split view column shown over the list
@@ -177,14 +177,19 @@ function stackCommands(id: string): StackCommands {
   };
 }
 
-/** The commands of the center for a menu screen: the menu closes once the center has changed. */
+/**
+ * The commands of the center for a menu screen: the menu closes as the center changes, and the command resolves once
+ * both are done.
+ */
 function fromCenter(center: string, menuScreen: string): StackCommands {
   const centerCommands = stackCommands(center);
+  // As in the system's apps, the menu starts to close at the pick and the center changes as it goes, so a push is seen
+  // sliding in. The command settles after both, so the next one acts from the center; either one's error rejects it.
   const closing =
     <Args extends unknown[], Result>(run: (...args: Args) => Promise<Result>) =>
     async (...args: Args) => {
-      const result = await run(...args);
-      await closeMenu(menuScreen);
+      const closed = closeMenu(menuScreen);
+      const [result] = await Promise.all([run(...args), closed]);
       return result;
     };
   return {

package/src/api/hooks/useSafeAreaInsets.ts

@@ -5,13 +5,14 @@ import { useScreen } from './screenHooks';
 /**
  * How much of this screen's content the bars and the system still cover on each side, past what the screen keeps its
  * content off itself (`layout.safeAreaEdges`): 0 on an edge the screen pads, the whole inset on an edge its content goes
- * under — under a top bar, under the vertical bar at the side of iPhone Duo, every edge with `safeAreaEdges: []`. A list
- * adds exactly this to its own padding. The native side measures every screen on its own, also the screens of
+ * under — the bottom by default (the home indicator, the navigation bar, a tab bar or toolbar the screen goes under),
+ * under a top bar, under the vertical bar at the side of iPhone Duo, every edge with `safeAreaEdges: []`. A list adds
+ * exactly this to its own padding. The native side measures every screen on its own, also the screens of
  * `appProvider`.
  *
  * @example
  * const insets = useSafeAreaInsets();
- * <ScrollView contentContainerStyle={{ paddingLeft: 16 + insets.left, paddingRight: 16 + insets.right }} />
+ * <ScrollView contentContainerStyle={{ paddingBottom: 16 + insets.bottom }} />
  */
 export function useSafeAreaInsets(): EdgeInsets {
   const { id } = useScreen();

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/dispatchedLinks.ts

@@ -0,0 +1,18 @@
+import { DeviceEventEmitter, Platform } from 'react-native';
+import { onNativeEvent } from '../../engine/native';
+import type { DeepLinkDispatchedEvent } from '../../interfaces/Events';
+
+let listening = false;
+
+/**
+ * (iOS) Hands `Linking` the links the app dispatched that it didn't take from the native side: on React Native 0.88
+ * and newer, in an app with a scene delegate, it takes only the links a scene opened. `Linking` listens to its `url`
+ * events through `DeviceEventEmitter`, so every listener of the app gets them, the navigation's links too.
+ */
+export function listenToDispatchedLinks() {
+  if (listening || Platform.OS !== 'ios') return;
+  listening = true;
+  onNativeEvent<DeepLinkDispatchedEvent>('DeepLinkDispatched', ({ url }) => {
+    DeviceEventEmitter.emit('url', { url });
+  });
+}

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/navigation.ts

@@ -55,7 +55,10 @@ export interface AppNavigation {
   switchTo<const Layout extends Exclude<RootLayout, string>>(
     layout: Layout & NoInfer<CheckedScreens<UsesOfRoot<Layout>, RegisteredScreens>>
   ): Promise<void>;
-  /** Shows a screen in the stack of the screen the user sees; resolves with the id of the screen shown. */
+  /**
+   * Shows a screen in the stack of the screen the user sees; resolves with the id of the screen shown (for a pair, the
+   * pair's id).
+   */
   push<Name extends ScreenName>(name: Name, ...args: ShowArgs<Name, PushConfig>): Promise<string>;
   /** Goes back in the stack of the screen the user sees; see `useNavigation().pop`. */
   pop(): Promise<string>;

package/src/api/options/OptionsChain.ts

@@ -68,8 +68,8 @@ export abstract class OptionsChain {
 
   /**
    * The edges on which the screen keeps its content out of its safe area (bars, status bar, home indicator, cutout);
-   * none with no edge. Without it: all four on Android, and on iOS every edge but those where the content goes under
-   * a bar. On iOS a large title leaves the top out by itself.
+   * none with no edge. Without it: the top and the sides, but those where the content goes under a bar; the bottom is
+   * free, and a list keeps clear of it with `useSafeAreaInsets()`. A large title leaves the top out by itself.
    */
   safeArea(...edges: SafeAreaEdge[]): this {
     return this.layout({ safeAreaEdges: edges });

package/src/api/screens/arrangement.ts

@@ -26,13 +26,23 @@ export interface ScreenArrangement<Props extends object = {}> {
 
 /** A pair under a name of its own, with every setting: `defineArrangement`. */
 export interface ArrangementDefinition<Props extends object = {}> extends ScreenArrangement<Props> {
-  /** The screen that owns the bar: its title, buttons, toolbar and status bar are the pair's. A name of `screens`. */
+  /**
+   * The screen that owns the bar: its title, buttons, toolbar and status bar are the pair's. It shows alone outside a
+   * large window (`compact: 'primary'`), and `primaryEdge` puts it on either side. A name of `screens`.
+   */
   primary: string;
   /** The axes the pair may use. Where the window allows none of them, only the primary shows. @default 'both' */
   axes?: 'horizontal' | 'vertical' | 'both';
   /** `split`: the primary's share along the split, above 0 and below 1, where the fold does not decide. @default 0.5 */
   fraction?: number;
-  /** `overlay`: the edge the primary takes when the pair goes side by side. @default 'trailing' */
+  /**
+   * The edge the primary takes. `split`: `leading` or `top` puts the primary first, at the leading side or on top;
+   * `trailing` or `bottom` puts it second, at the trailing side or at the bottom (one setting for both ways the pair
+   * may lie). `overlay`: the primary's edge when the pair goes side by side; an edge of the other axis counts as the
+   * nearest one (`top` as leading, `bottom` as trailing). Whatever the edge, the primary is the screen that shows
+   * alone outside a large window with `compact: 'primary'`: to show the other screen there, make it the primary.
+   * @default 'leading' for split, 'trailing' for overlay
+   */
   primaryEdge?: 'leading' | 'trailing' | 'top' | 'bottom';
   /**
    * Outside a large window: `primary` — the primary alone, as a plain screen; `pair` — the pair as the system lays it
@@ -85,14 +95,17 @@ export function toEngineArrangement(
 ): EngineArrangement {
   const full = arrangement as ArrangementDefinition<any>;
   checkFraction(full.fraction);
+  const style = arrangement.style ?? 'split';
   return {
     primary,
     secondary: arrangement.secondary,
     secondaryProps: arrangement.secondaryProps,
-    style: arrangement.style ?? 'split',
+    style,
     axes: full.axes ?? 'both',
     fraction: full.fraction ?? 0.5,
-    primaryEdge: full.primaryEdge ?? 'trailing',
+    // Where UIKit puts the primary of each style without an edge set: first in a split, at the trailing side of an
+    // overlay that goes side by side.
+    primaryEdge: full.primaryEdge ?? (style === 'split' ? 'leading' : 'trailing'),
     compact: full.compact ?? 'primary',
   };
 }

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
+  );
 }