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

package/src/api/hooks/useNavigation.ts

@@ -0,0 +1,267 @@
+import { useContext, useMemo } from 'react';
+import { setPressEvent } from '../../engine/buttons';
+import * as commands from '../commands/commands';
+import type { SplitColumn } from '../commands/commands';
+import { command } from '../commands/errors';
+import type {
+  ColumnConfig,
+  ModalConfig,
+  OverlayConfig,
+  PushConfig,
+} from '../commands/presentation';
+import type { StackEntry } from '../layout/Stack';
+import { type AppNavigation, navigation, type CheckedEntries } from '../navigation';
+import type { ScreenOptionsInput } from '../screens/defineScreen';
+import { ScreenContext, type ScreenInfo } from '../screens/registerScreens';
+import { whenTabShows } from '../state/navigationState';
+import { placeOf } from '../../engine/places';
+import { centerOf, closeMenu, openMenu } from '../commands/sideMenus';
+import type { ScreenName, ShowArgs } from '../types';
+
+/** The commands that act from the screen, so they take no ids. */
+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. */
+  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
+   * (a phone) goes back to the list.
+   */
+  pop(): Promise<string>;
+  /** Goes back to a screen of this stack, by its id. */
+  popTo(screenId: string): Promise<string>;
+  /** Goes back to the first screen of this stack. */
+  popToRoot(): Promise<string>;
+  /**
+   * Shows a screen in place of the whole history of this stack: it comes in as a push does and is alone in the stack,
+   * so there is no back. For a point the user shouldn't go back from, such as a payment once it is made. Resolves with
+   * the id of the screen shown.
+   */
+  replace<Name extends ScreenName>(
+    name: Name,
+    ...args: ShowArgs<Name, PushConfig>
+  ): Promise<string>;
+  /** Replaces the screens of this stack: the last one shows, back goes to the one before. */
+  setStack<const Entries extends readonly StackEntry[]>(
+    ...entries: CheckedEntries<Entries>
+  ): Promise<string>;
+  /**
+   * Shows a screen in a column of the split view this screen is in, in place of what the column shows: Details beside
+   * a list. The column comes into view: a sidebar over it goes away; collapsed into one stack (iPhone, a narrow
+   * window) the screen goes on top, and back comes here; on Android the secondary pane comes over the primary one.
+   * With a `compact` layout on screen and outside a split view the screen is pushed over this one.
+   *
+   * @example
+   * // Settings: sections in the sidebar, the picked one beside them.
+   * navigation.switchTo(
+   *   SplitView({ primary: Screen('Settings'), secondary: Screen('Details') })
+   * );
+   *
+   * function Settings() {
+   *   const navigation = useNavigation();
+   *   const open = (section: string) =>
+   *     navigation.showInColumn('Details', { props: { section } });
+   *   return <Button title="Profile" onPress={() => open('profile')} />;
+   * }
+   */
+  showInColumn<Name extends ScreenName>(
+    name: Name,
+    ...args: ShowArgs<Name, ColumnConfig>
+  ): Promise<string>;
+  /** Shows a screen over everything, in a stack of its own unless `stack: false`. */
+  showModal<Name extends ScreenName>(
+    name: Name,
+    ...args: ShowArgs<Name, ModalConfig>
+  ): Promise<string>;
+  /** Closes the modal or the overlay this screen is in, with all its screens. */
+  dismiss(): Promise<string>;
+  /**
+   * There is a screen under this one in its stack, or this one is the first of a split view column shown over the list
+   * (a phone), so `pop()` has one to go back to. Answers at once.
+   */
+  canPop(): boolean;
+  /** This screen is in a modal or an overlay, so `dismiss()` has one to close. Answers at once. */
+  canDismiss(): boolean;
+  /**
+   * What the back button would do here: `pop()` when there is a screen under this one in its stack, `dismiss()` when it
+   * is the first screen of a modal. For a screen that opens both ways, pushed in one place and in a modal in another.
+   */
+  goBack(): Promise<string>;
+  /** `goBack()` has something to do: `canPop()` or `canDismiss()`. Answers at once. */
+  canGoBack(): boolean;
+  /** Shows a screen over everything, without taking the place of any. */
+  showOverlay<Name extends ScreenName>(
+    name: Name,
+    ...args: ShowArgs<Name, OverlayConfig>
+  ): Promise<string>;
+  /**
+   * Shows a column of the split view this screen is in, as the platform does for the split behavior: the sidebar
+   * (`'primary'`), the middle column (`'supplementary'`), the inspector. Resolves once the columns have moved. On
+   * Android the primary pane: beside the secondary one it comes back, under it the secondary pane goes away.
+   */
+  showColumn(column: SplitColumn): Promise<void>;
+  /** Hides a column of the split view this screen is in: `hideColumn('primary')` leaves the item alone. */
+  hideColumn(column: SplitColumn): Promise<void>;
+  /** Opens a menu of the side menu this screen is in; resolves once it is open and `getState()` shows its screen. */
+  openMenu(side: 'left' | 'right'): Promise<void>;
+  /**
+   * Closes the menu that is open in the side menu this screen is in; resolves once it is closed and `getState()` shows
+   * the center.
+   */
+  closeMenu(): Promise<void>;
+  /** Changes the options of this screen. */
+  setOptions(options: ScreenOptionsInput<object>): void;
+  /**
+   * Selects a tab of the tabs this screen is in: by its index, or by the id of the tab (`Tab().id()`). Resolves once the
+   * state shows it, as `navigation.selectTab` does.
+   */
+  selectTab(tab: number | string): Promise<void>;
+  /** The badge of this screen's tab, or of the tab with the id; `null` and the number `0` take it away. */
+  setTabBadge(badge: string | number | null, tab?: string): Promise<void>;
+}
+
+/**
+ * The navigation of a screen: its own commands act from it and take no ids, and the commands of the whole app are
+ * here too (`switchTo`, `dismissAllModals`, `getState`, `on`, the theme and the context), so a screen needs nothing
+ * else.
+ */
+export interface ScreenNavigation
+  extends Omit<AppNavigation, keyof ScreenCommands>, ScreenCommands {}
+
+/** The navigation of the screen the component is in. */
+export function useNavigation(): ScreenNavigation {
+  const screen = useContext(ScreenContext);
+  if (!screen) {
+    throw new Error(
+      '[navigation] useNavigation is for the screens of createNavigation, and this component is not in one'
+    );
+  }
+  return useMemo(() => screenNavigation(screen), [screen]);
+}
+
+// The commands of a stack, which a screen makes from where it is.
+type StackCommands = Pick<
+  ScreenNavigation,
+  | 'push'
+  | 'pop'
+  | 'popToRoot'
+  | 'replace'
+  | 'setStack'
+  | 'showInColumn'
+  | 'selectTab'
+  | 'setTabBadge'
+>;
+
+function stackCommands(id: string): StackCommands {
+  return {
+    push: ((name: string, config?: PushConfig) =>
+      commands.push(id, name, config)) as StackCommands['push'],
+    pop: () => commands.pop(id),
+    popToRoot: () => commands.popToRoot(id),
+    replace: ((name: string, config?: PushConfig) =>
+      commands.replace(id, name, config)) as StackCommands['replace'],
+    setStack: ((...entries: StackEntry[]) =>
+      commands.setStack(id, entries)) as StackCommands['setStack'],
+    showInColumn: ((name: string, config?: ColumnConfig) =>
+      commands.showInColumn(id, name, config)) as StackCommands['showInColumn'],
+    // Resolves once the state shows the tab, so the next command acts in it.
+    selectTab: (tab) =>
+      command('selectTab', async () => {
+        const shown = whenTabShows(tab);
+        commands.selectTab(id, tab);
+        await shown;
+      }),
+    setTabBadge: (badge, tab) =>
+      command('setTabBadge', async () => commands.setTabBadge(id, badge, tab)),
+  };
+}
+
+/** The commands of the center for a menu screen: the menu closes once the center has changed. */
+function fromCenter(center: string, menuScreen: string): StackCommands {
+  const centerCommands = stackCommands(center);
+  const closing =
+    <Args extends unknown[], Result>(run: (...args: Args) => Promise<Result>) =>
+    async (...args: Args) => {
+      const result = await run(...args);
+      await closeMenu(menuScreen);
+      return result;
+    };
+  return {
+    push: closing(
+      centerCommands.push as (...args: unknown[]) => Promise<string>
+    ) as StackCommands['push'],
+    pop: closing(centerCommands.pop),
+    popToRoot: closing(centerCommands.popToRoot),
+    replace: closing(
+      centerCommands.replace as (...args: unknown[]) => Promise<string>
+    ) as StackCommands['replace'],
+    setStack: closing(
+      centerCommands.setStack as (...args: unknown[]) => Promise<string>
+    ) as StackCommands['setStack'],
+    showInColumn: closing(
+      centerCommands.showInColumn as (...args: unknown[]) => Promise<string>
+    ) as StackCommands['showInColumn'],
+    selectTab: closing(centerCommands.selectTab),
+    setTabBadge: centerCommands.setTabBadge,
+  };
+}
+
+/** The navigation of a screen, for code outside React that knows the screen. */
+export function screenNavigation(screen: ScreenInfo): ScreenNavigation {
+  const id = screen.id;
+  const own = stackCommands(id);
+  // A screen without a stack of its own acts from elsewhere: an overlay from the screen the user sees (a banner opens a
+  // chat), a menu from the center of its side menu.
+  const stack = (): StackCommands => {
+    const place = placeOf(id);
+    if (place?.container === 'overlay') return navigation;
+    if (place?.menu && place.menu.part !== 'center') {
+      const center = centerOf(place.menu.id);
+      if (center) return fromCenter(center, id);
+    }
+    return own;
+  };
+  return {
+    ...navigation,
+    screen,
+    push: ((...args: unknown[]) =>
+      (stack().push as (...args: unknown[]) => Promise<string>)(
+        ...args
+      )) as ScreenNavigation['push'],
+    pop: () => stack().pop(),
+    popTo: (screenId) => commands.popTo(screenId),
+    popToRoot: () => stack().popToRoot(),
+    replace: ((...args: unknown[]) =>
+      (stack().replace as (...args: unknown[]) => Promise<string>)(
+        ...args
+      )) as ScreenNavigation['replace'],
+    setStack: ((...args: unknown[]) =>
+      (stack().setStack as (...args: unknown[]) => Promise<string>)(
+        ...args
+      )) as ScreenNavigation['setStack'],
+    showInColumn: ((...args: unknown[]) =>
+      (stack().showInColumn as (...args: unknown[]) => Promise<string>)(
+        ...args
+      )) as ScreenNavigation['showInColumn'],
+    showModal: ((name: string, config?: ModalConfig) =>
+      commands.showModal(name, config)) as ScreenNavigation['showModal'],
+    dismiss: () => commands.dismiss(id),
+    canPop: () => commands.canPop(id),
+    canDismiss: () => commands.canDismiss(id),
+    goBack: () => commands.goBack(id),
+    canGoBack: () => commands.canPop(id) || commands.canDismiss(id),
+    showOverlay: ((name: string, config?: OverlayConfig) =>
+      commands.showOverlay(name, config)) as ScreenNavigation['showOverlay'],
+    setOptions: (options) => commands.setOptions(id, options),
+    showColumn: (column) => commands.setColumnShown(id, column, true),
+    hideColumn: (column) => commands.setColumnShown(id, column, false),
+    openMenu: (side) => openMenu(id, side),
+    closeMenu: () => closeMenu(id),
+    selectTab: (tab) => stack().selectTab(tab),
+    setTabBadge: (badge, tab) => stack().setTabBadge(badge, tab),
+  };
+}
+
+// A press of a button in the options gets the navigation of its screen.
+setPressEvent((event) => ({ ...event, navigation: screenNavigation(event.screen) }));

package/src/api/hooks/usePendingLink.ts

@@ -0,0 +1,11 @@
+import { useSyncExternalStore } from 'react';
+import { getPendingLink, subscribePendingLink } from '../linking/pendingLinks';
+import type { PendingLink } from '../linking/types';
+
+/**
+ * The link that waits for `when` of `linking`, or null: the component renders again when one starts waiting and when
+ * it runs or is forgotten. For a screen that offers it after a sign-in.
+ */
+export function usePendingLink(): PendingLink | null {
+  return useSyncExternalStore(subscribePendingLink, getPendingLink);
+}

package/src/api/hooks/usePreview.ts

@@ -0,0 +1,111 @@
+import { useEffect, useLayoutEffect, useRef } from 'react';
+import { Platform } from 'react-native';
+import { dismissPreview } from '../../engine/commands';
+import { nextId } from '../../engine/ids';
+import { pushPreview } from '../commands/commands';
+import { onNavigationEvent } from '../events/navigationEvents';
+import type { ScreenName, ScreenProps } from '../types';
+import { useScreen } from './screenHooks';
+
+/** An item of the menu under a preview; with `actions`, a submenu. */
+export interface PreviewAction {
+  id: string;
+  title: string;
+  style?: 'default' | 'selected' | 'destructive';
+  onPress?: () => void;
+  actions?: PreviewAction[];
+}
+
+/** What a view previews: the screen with its props, and the menu under it. */
+export type PreviewConfig<Name extends ScreenName> = {
+  screen: Name;
+  actions?: PreviewAction[];
+  /** The width of the preview; the width of the screen without it. */
+  width?: number;
+  /** The height of the preview; the height of the screen without it. */
+  height?: number;
+} & (Partial<ScreenProps<Name>> extends ScreenProps<Name>
+  ? { props?: ScreenProps<Name> }
+  : { props: ScreenProps<Name> });
+
+/**
+ * (iOS) A long press on the view with `nativeID` in this screen (a right click with a pointer on iPad) shows `screen`
+ * small, with `actions` as a menu under it; a tap on the preview pushes the screen. UIKit's context menu. The preview
+ * goes when the component unmounts. Elsewhere the view has no preview.
+ */
+export function usePreview<Name extends ScreenName>(
+  nativeID: string,
+  config: PreviewConfig<Name>
+): void {
+  const { id: screenId } = useScreen();
+  const {
+    screen,
+    props,
+    actions = [],
+    width,
+    height,
+  } = config as PreviewConfig<ScreenName> & {
+    props?: object;
+  };
+  const latest = useRef(actions);
+  useLayoutEffect(() => {
+    latest.current = actions;
+  });
+  // A new preview when what it shows changes; the handlers of the menu are read when it is pressed.
+  const shown = JSON.stringify([screen, props ?? null, menuOf(actions), width, height]);
+  useEffect(() => {
+    if (Platform.OS !== 'ios') return undefined;
+    const [name, previewProps, menu, previewWidth, previewHeight] = JSON.parse(shown);
+    let active = true;
+    let current: string | undefined;
+    const stop = onNavigationEvent('buttonPressed', (event) => {
+      if (event.screen?.id === current) findAction(latest.current, event.buttonId)?.onPress?.();
+    });
+    // A preview stands for one push: once a tap opened the screen, the view previews it again. The push ends with an
+    // error when the preview goes, which is not one here.
+    const arm = () => {
+      const previewId = nextId('Preview');
+      current = previewId;
+      pushPreview(
+        screenId,
+        name,
+        previewProps ?? undefined,
+        { nativeID, commit: true, actions: menu, width: previewWidth, height: previewHeight },
+        previewId,
+        () => active
+      ).then(
+        () => {
+          if (active) arm();
+        },
+        () => {}
+      );
+    };
+    arm();
+    // The preview goes with the component, or when what it shows changes: otherwise it and its screen stay until the
+    // screen it is in closes. One a tap has just pushed stays, the native side tells them apart.
+    return () => {
+      active = false;
+      stop();
+      if (current) dismissPreview(current);
+    };
+  }, [screenId, nativeID, shown]);
+}
+
+// The menu as the native side takes it: the titles and the ids, without the handlers.
+function menuOf(actions: PreviewAction[]): object[] {
+  return actions.map(({ id, title, style, actions: submenu }) => ({
+    id,
+    title,
+    ...(style && { style }),
+    ...(submenu && { actions: menuOf(submenu) }),
+  }));
+}
+
+function findAction(actions: PreviewAction[], id: string): PreviewAction | undefined {
+  for (const action of actions) {
+    if (action.id === id) return action;
+    const inner = action.actions && findAction(action.actions, id);
+    if (inner) return inner;
+  }
+  return undefined;
+}

package/src/api/hooks/useReservedRegions.ts

@@ -0,0 +1,26 @@
+import { useCallback, useSyncExternalStore } from 'react';
+import {
+  getScreenRegions,
+  type ReservedRegions,
+  subscribeScreenRegions,
+} from '../safeArea/screenRegions';
+import { useScreen } from './screenHooks';
+
+/**
+ * The parts of this screen the hardware takes, in the screen's coordinates: `division`, the fold of a partly folded
+ * device, and `occlusion`, a camera or a hinge over the screen. Only what is active now: the fold of a device opened
+ * flat is not there. Empty where the platform has none (before iOS 27.1, a device without a fold). Changes as the
+ * device folds, as the safe area does.
+ *
+ * @example
+ * const { division } = useReservedRegions();
+ * const fold = division[0]; // keep the buttons on one side of it
+ */
+export function useReservedRegions(): ReservedRegions {
+  const { id } = useScreen();
+  const subscribe = useCallback(
+    (onChange: () => void) => subscribeScreenRegions(id, onChange),
+    [id]
+  );
+  return useSyncExternalStore(subscribe, () => getScreenRegions(id));
+}

package/src/api/hooks/useSafeAreaInsets.ts

@@ -0,0 +1,23 @@
+import { useCallback, useSyncExternalStore } from 'react';
+import { type EdgeInsets, getScreenInsets, subscribeScreenInsets } from '../safeArea/screenInsets';
+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
+ * `appProvider`.
+ *
+ * @example
+ * const insets = useSafeAreaInsets();
+ * <ScrollView contentContainerStyle={{ paddingLeft: 16 + insets.left, paddingRight: 16 + insets.right }} />
+ */
+export function useSafeAreaInsets(): EdgeInsets {
+  const { id } = useScreen();
+  const subscribe = useCallback(
+    (onChange: () => void) => subscribeScreenInsets(id, onChange),
+    [id]
+  );
+  return useSyncExternalStore(subscribe, () => getScreenInsets(id));
+}

package/src/api/index.ts

@@ -0,0 +1,139 @@
+export { AppRegistry } from './app/AppRegistry';
+export { createNavigation } from './app/createNavigation';
+export type {
+  NavigationApp,
+  NavigationConfig,
+  NavigationErrorSource,
+} from './app/createNavigation';
+export type { RootParam, RootsMap, RootTarget, RootValue } from './app/roots';
+export { Root } from './layout/Root';
+export type { RootElement, RootLayout, RootTransition } from './layout/Root';
+export { Screen } from './layout/Screen';
+export type { ScreenElement } from './layout/Screen';
+export { SideMenu } from './layout/SideMenu';
+export type { SideMenuElement, SideMenuParts } from './layout/SideMenu';
+export { SplitView } from './layout/SplitView';
+export type { SplitViewColumns, SplitViewElement } from './layout/SplitView';
+export { Stack } from './layout/Stack';
+export type { StackElement, StackEntry } from './layout/Stack';
+export { Tab, Tabs } from './layout/Tabs';
+export type { TabElement, TabItemStyle, TabsElement } from './layout/Tabs';
+export type { LayoutContent, LayoutElement } from './layout/element';
+export type {
+  ColumnConfig,
+  ModalConfig,
+  OverlayConfig,
+  Presentation,
+  PushConfig,
+} from './commands/presentation';
+export type { SplitColumn } from './commands/commands';
+export type { Transition, TransitionPreset } from './commands/transitions';
+export type {
+  ButtonPressEvent,
+  ButtonPressHandler,
+  NavigationButton,
+  NavigationButtonMenu,
+  NavigationFab,
+  NavigationMenuItem,
+  NavigationSubmenu,
+} from './options/buttons';
+export type { TabPressEvent, TabPressHandler } from './events/tabPresses';
+export type {
+  AccessoryPlacementChangedEvent,
+  ButtonPressedEvent,
+  KeyCommandPressedEvent,
+  ModalDismissAttemptedEvent,
+  ModalDismissedEvent,
+  NavigationEventName,
+  NavigationEvents,
+  NavigationListeners,
+  PreviewCompletedEvent,
+  ScreenDidAppearEvent,
+  ScreenDidDisappearEvent,
+  ScreenPoppedEvent,
+  ScreenWillAppearEvent,
+  SearchCancelledEvent,
+  SearchChangedEvent,
+  SearchSubmittedEvent,
+  SearchSuggestionPickedEvent,
+  SheetDetentChangedEvent,
+  SplitViewDisplayModeChangedEvent,
+  TabLongPressedEvent,
+  TabPressedEvent,
+  TabSelectedEvent,
+  TitleRenamedEvent,
+} from './events/navigationEvents';
+export {
+  useFocusEffect,
+  useIsFocused,
+  useNavigationButton,
+  useNavigationEvent,
+  useNavigationState,
+  usePreventLeave,
+  useScreen,
+  useScreenAppear,
+  useScreenDisappear,
+  useScreenEvent,
+  useScreenOptions,
+  useSearchBar,
+  useTabPress,
+} from './hooks/screenHooks';
+export type { ScreenEventName } from './hooks/screenHooks';
+export { useAppContext, useNavigationTheme } from './hooks/appHooks';
+export { useSafeAreaInsets } from './hooks/useSafeAreaInsets';
+export { useReservedRegions } from './hooks/useReservedRegions';
+export { useArrangement } from './hooks/useArrangement';
+export { useHinge, useHingeChange } from './hooks/useHinge';
+export { usePreview } from './hooks/usePreview';
+export { usePendingLink } from './hooks/usePendingLink';
+export { useSplash } from './app/splash';
+export type { Splash, SplashConfig, SplashLogo } from './app/splash';
+export type {
+  LinkHandler,
+  LinkInfo,
+  LinkingConfig,
+  LinkParams,
+  LinkRoute,
+  LinkRouteConfig,
+  PendingLink,
+} from './linking/types';
+export type { PreviewAction, PreviewConfig } from './hooks/usePreview';
+export { screenNavigation, useNavigation } from './hooks/useNavigation';
+export type { ScreenNavigation } from './hooks/useNavigation';
+export { navigation } from './navigation';
+export type { AppNavigation } from './navigation';
+export { defineScreen } from './screens/defineScreen';
+export { TestIDs } from './testIDs';
+export { nativeScreen } from './screens/nativeScreens';
+export type { NativeScreen } from './screens/nativeScreens';
+export { defineArrangement } from './screens/arrangement';
+export type { Arrangement, ArrangementDefinition, ScreenArrangement } from './screens/arrangement';
+export type {
+  OptionsEnvironment,
+  ScreenDefinition,
+  ScreenOptionsInput,
+} from './screens/defineScreen';
+export type { OptionsChain } from './options/OptionsChain';
+export type { ScreenOptions, ToolbarOptions } from './options/ScreenOptions';
+export type {
+  LoadingFallback,
+  ScreenEntry,
+  ScreenGroup,
+  ScreenInfo,
+  ScreenProvider,
+  Screens,
+} from './screens/registerScreens';
+export type { ErrorFallbackProps } from './screens/ScreenBoundary';
+export type { EdgeInsets } from './safeArea/screenInsets';
+export type { ReservedRegion, ReservedRegions } from './safeArea/screenRegions';
+export type { ArrangementState } from './arrangement/arrangementState';
+export type { Hinge } from './hinge/hinge';
+export type {
+  AppOptionsInput,
+  NavigationDirection,
+  NavigationTheme,
+  ResolvedNavigationTheme,
+} from './theme/theme';
+export type { AppProvider } from '../engine/slots';
+export type { NavigationState } from './state/navigationState';
+export type { Register, RegisteredContext, ScreenName, ScreenProps, ShowArgs } from './types';