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

package/src/api/state/navigationState.ts

@@ -0,0 +1,95 @@
+import { onNativeEvent } from '../../engine/native';
+import type {
+  ComponentDidAppearEvent,
+  ComponentDidDisappearEvent,
+} from '../../interfaces/ComponentEvents';
+import type { NavigationStateChangedEvent } from '../../interfaces/Events';
+
+/**
+ * What the user sees: the screen and the selected tab. The native side sends it when it changes, and before a command
+ * that changed it resolves.
+ */
+export type NavigationState = NavigationStateChangedEvent;
+
+let state: NavigationState = { screen: null, tab: null };
+const listeners = new Set<(state: NavigationState) => void>();
+// The screens that appeared and haven't disappeared since, for a component that mounts in one later.
+const appeared = new Set<string>();
+let listening = false;
+
+/** Keeps the last state from the native side and the screens shown; the app starts it before its first root. */
+export function listenToNavigationState() {
+  if (listening) return;
+  listening = true;
+  onNativeEvent<NavigationStateChangedEvent>('NavigationStateChanged', (next) => {
+    state = next;
+    listeners.forEach((listener) => listener(state));
+  });
+  onNativeEvent<ComponentDidAppearEvent>('ComponentDidAppear', ({ componentId }) => {
+    appeared.add(componentId);
+  });
+  onNativeEvent<ComponentDidDisappearEvent>('ComponentDidDisappear', ({ componentId }) => {
+    appeared.delete(componentId);
+  });
+}
+
+/** Whether the screen has appeared and not disappeared since, as the native side told it. */
+export function hasAppeared(screenId: string): boolean {
+  return appeared.has(screenId);
+}
+
+/** The screen is gone: a disappearance that never came doesn't count it as shown for a screen with its id later. */
+export function forgetAppeared(screenId: string): void {
+  appeared.delete(screenId);
+}
+
+export function getNavigationState(): NavigationState {
+  return state;
+}
+
+/** Calls the listener on each change; returns the function that stops it. */
+export function onNavigationStateChange(listener: (state: NavigationState) => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+/**
+ * Resolves once the native side sent a state newer than `since` with a screen in it, at the latest after `timeout`:
+ * the state then shows what the commands before it changed, such as the screen of a new root.
+ */
+export function whenScreenAfter(since: NavigationState, timeout: number): Promise<void> {
+  const shows = (next: NavigationState) => next !== since && next.screen !== null;
+  if (shows(state)) return Promise.resolve();
+  return new Promise((resolve) => {
+    const done = () => {
+      clearTimeout(timer);
+      stop();
+      resolve();
+    };
+    const timer = setTimeout(done, timeout);
+    const stop = onNavigationStateChange((next) => {
+      if (shows(next)) done();
+    });
+  });
+}
+
+/**
+ * Resolves once the state shows the tab: a tab by index at once when it shows already, otherwise on the next change of
+ * the state, and at the latest after `timeout` (a tab by id that shows already changes nothing).
+ */
+export function whenTabShows(tab: number | string, timeout = 300): Promise<void> {
+  if (typeof tab === 'number' && state.tab === tab) return Promise.resolve();
+  return new Promise((resolve) => {
+    const done = () => {
+      clearTimeout(timer);
+      stop();
+      resolve();
+    };
+    const timer = setTimeout(done, timeout);
+    const stop = onNavigationStateChange((next) => {
+      if (typeof tab !== 'number' || next.tab === tab) done();
+    });
+  });
+}

package/src/api/testIDs.ts

@@ -0,0 +1,11 @@
+/**
+ * Ids of the views the navigation shows without an id from the app, for end-to-end tests (Detox, Maestro, Appium) to
+ * find them by.
+ */
+export const TestIDs = {
+  /**
+   * The back button of a stack's top bar: UIKit gives the system button this id on iOS, and the navigation gives the
+   * same one on Android. `topBar.backButton.testID` sets another on Android.
+   */
+  backButton: 'BackButton',
+} as const;

package/src/api/theme/theme.ts

@@ -0,0 +1,184 @@
+import type { ColorValue } from 'react-native';
+import { setDefaultOptions } from '../../engine/commands';
+import type { Color, Options, WindowOptions } from '../../interfaces/Options';
+import { launchState } from '../../engine/launchState';
+import { mergeOptions } from '../../engine/mergeOptions';
+import { getAppContext } from '../context/appContext';
+import { readScreenOptions, ScreenOptions } from '../options/ScreenOptions';
+import type { OptionsEnvironment } from '../screens/defineScreen';
+
+/**
+ * The look of the navigation: its bars, tabs and screen backgrounds. A color can be `{ light, dark }`: the native side
+ * picks the one of the system's appearance. A color left out keeps the platform's look: on iOS 26 the glass bars, on
+ * Android the colors of the app's Material 3 theme (`Theme.ApexNavigation`: neutral grays).
+ */
+export interface NavigationTheme {
+  colors?: {
+    /** Buttons of the top bar, the back button, the selected tab, the cursor of the search. */
+    primary?: Color;
+    /** Behind every screen. */
+    background?: Color;
+    /** The top bar and the tab bar. */
+    bar?: Color;
+    /** Titles. */
+    text?: Color;
+    /** The lines under the top bar and over the tab bar. */
+    border?: Color;
+    /** The badges of the tabs. */
+    badge?: Color;
+  };
+}
+
+/**
+ * The theme as React content takes it: each color for the current appearance, ready for a style. A color the theme
+ * leaves out is undefined.
+ */
+export interface ResolvedNavigationTheme {
+  colors: { [Key in keyof NonNullable<NavigationTheme['colors']>]?: ColorValue };
+}
+
+/**
+ * The default options of every screen: options as they are, or a chain built from the theme and the app's context. A
+ * chain is built again when the theme changes.
+ */
+export type AppOptionsInput =
+  Options | ((options: ScreenOptions, app: OptionsEnvironment) => ScreenOptions);
+
+/** The direction of the app: right to left, left to right, or as the language of the app. */
+export type NavigationDirection = 'ltr' | 'rtl' | 'locale';
+
+/**
+ * The default options as the native side takes them: the color of the app's window goes with them (iOS), and the
+ * direction of the app.
+ */
+export type DefaultOptions = Options & {
+  window?: WindowOptions;
+  layout?: { direction?: NavigationDirection };
+};
+
+/** The app's own default options, over those of the theme: `options` between what goes under and over them. */
+export interface AppDefaults {
+  under?: DefaultOptions;
+  options?: AppOptionsInput;
+  over?: DefaultOptions;
+}
+
+let theme: NavigationTheme = {};
+let appDefaults: AppDefaults = {};
+let direction: NavigationDirection | undefined;
+const listeners = new Set<() => void>();
+
+export function getTheme(): NavigationTheme {
+  return theme;
+}
+
+/** The theme's colors for the light or the dark appearance: of a `{ light, dark }` pair the one, others as they are. */
+export function resolveTheme(
+  { colors = {} }: NavigationTheme,
+  scheme: 'light' | 'dark'
+): ResolvedNavigationTheme {
+  const resolved: ResolvedNavigationTheme['colors'] = {};
+  for (const [key, color] of Object.entries(colors) as [keyof typeof resolved, Color][]) {
+    const value = resolveColor(color, scheme);
+    if (value !== undefined) resolved[key] = value;
+  }
+  return { colors: resolved };
+}
+
+function resolveColor(color: Color | undefined, scheme: 'light' | 'dark'): ColorValue | undefined {
+  if (typeof color === 'string') return color;
+  if (color === null || typeof color !== 'object') return undefined;
+  if ('light' in color || 'dark' in color) {
+    const picked = (color as { light?: unknown; dark?: unknown })[scheme];
+    return typeof picked === 'string' ? picked : undefined;
+  }
+  // A color of the platform (PlatformColor, DynamicColorIOS): a style takes it as it is.
+  return color as ColorValue;
+}
+
+export function subscribeTheme(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+/** The theme, the default options and the direction of the app, before its first launch. */
+export function initTheme(
+  initial: NavigationTheme | undefined,
+  defaults: AppDefaults,
+  initialDirection?: NavigationDirection
+) {
+  theme = initial ?? {};
+  appDefaults = defaults;
+  direction = initialDirection;
+}
+
+/** The default options of the theme with the app's own over them; undefined when there are none. */
+export function themedDefaultOptions(): DefaultOptions | undefined {
+  const { under, options, over } = appDefaults;
+  const own =
+    typeof options === 'function'
+      ? readScreenOptions(options(new ScreenOptions(), { theme, context: getAppContext() }))
+      : options;
+  const app: DefaultOptions | undefined = direction && { layout: { direction } };
+  const layers = [themeOptions(theme), under, own, over, app].filter(
+    (layer): layer is DefaultOptions => layer !== undefined && Object.keys(layer).length > 0
+  );
+  return layers.length > 0 ? layers.reduce<DefaultOptions>(mergeOptions, {}) : undefined;
+}
+
+/** Changes the theme: the screens shown take it too. */
+export function setTheme(next: NavigationTheme) {
+  theme = next;
+  applyDefaults();
+  listeners.forEach((listener) => listener());
+}
+
+/** Changes the direction of the app: the bars, the transitions and the swipe back follow at once. */
+export function setDirection(next: NavigationDirection) {
+  direction = next;
+  applyDefaults();
+}
+
+// Before the first launch, the launch sets them.
+function applyDefaults() {
+  if (launchState.launch === 0) return;
+  const defaults = themedDefaultOptions();
+  if (defaults) setDefaultOptions(defaults);
+}
+
+function themeOptions({ colors = {} }: NavigationTheme): Options {
+  const { primary, background, bar, text, border, badge } = colors;
+  return withoutEmpty({
+    layout: { backgroundColor: background },
+    topBar: {
+      background: { color: bar },
+      title: { color: text },
+      largeTitle: { color: text },
+      backButton: { color: primary },
+      leftButtonColor: primary,
+      rightButtonColor: primary,
+      centerButtonColor: primary,
+      borderColor: border,
+      searchBar: { tintColor: primary },
+    },
+    bottomTabs: { backgroundColor: bar, borderColor: border },
+    bottomTab: { selectedIconColor: primary, selectedTextColor: primary, badgeColor: badge },
+  }) as Options;
+}
+
+/** The object without its undefined values and the objects left empty. */
+function withoutEmpty(value: Record<string, unknown>): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  for (const [key, item] of Object.entries(value)) {
+    if (item === undefined) continue;
+    if (typeof item === 'object' && item !== null && !Array.isArray(item)) {
+      const inner = withoutEmpty(item as Record<string, unknown>);
+      if (Object.keys(inner).length > 0) result[key] = inner;
+    } else {
+      result[key] = item;
+    }
+  }
+  return result;
+}

package/src/api/types.ts

@@ -0,0 +1,95 @@
+import type { ComponentType } from 'react';
+import type { NavigationApp } from './app/createNavigation';
+import type { RootsMap } from './app/roots';
+import type { Arrangement } from './screens/arrangement';
+import type { ScreenDefinition } from './screens/defineScreen';
+import type { NativeScreen } from './screens/nativeScreens';
+import type { ScreenEntry } from './screens/registerScreens';
+
+/**
+ * The app's navigation, for the types of its names and params. An app registers it once:
+ * `declare module '@apexnative/navigation' { interface Register { app: typeof App } }`.
+ */
+export interface Register {}
+
+/** The roots of the registered app; without the registration any name goes. */
+export type RegisteredRoots = Register extends { app: NavigationApp<infer Roots, any> }
+  ? Roots
+  : RootsMap;
+
+/** The screens of the registered app, those of its groups too; without the registration any name goes. */
+export type RegisteredScreens = Register extends { app: NavigationApp<any, infer Screens> }
+  ? Screens
+  : Record<string, ScreenEntry>;
+
+export type ScreenName = keyof RegisteredScreens & string;
+
+/**
+ * The type of the app's context, for `useAppContext`, `navigation.getContext` and the options. It is registered next
+ * to the app, `interface Register { app: typeof App; context: AppContext }`: read from the app it would go round,
+ * since the screens' options are part of the app's type.
+ */
+export type RegisteredContext = Register extends { context: infer Context } ? Context : unknown;
+
+/** The props a screen takes: what a command gives it. */
+export type ScreenProps<Name extends ScreenName> = PropsOf<RegisteredScreens[Name]>;
+
+/** The settings of a command with the props of the screen, which are required when the screen has required ones. */
+export type ShowArgs<Name extends ScreenName, Config> =
+  Partial<ScreenProps<Name>> extends ScreenProps<Name>
+    ? [config?: Config & { props?: ScreenProps<Name> }]
+    : [config: Config & { props: ScreenProps<Name> }];
+
+/**
+ * What is wrong with a screen a layout shows, by the screens of the app: a message, or never when it fits. A screen
+ * named alone needs all its props to be optional; an untyped element is not checked.
+ */
+type ScreenUseError<Use, AppScreens> = 0 extends 1 & Use
+  ? never
+  : Use extends { name: infer Name extends string; props: infer Props }
+    ? string extends Name
+      ? 'a screen goes by its name in screens, not by any string'
+      : Name extends keyof AppScreens
+        ? [Props] extends [undefined]
+          ? Partial<PropsOf<AppScreens[Name]>> extends PropsOf<AppScreens[Name]>
+            ? never
+            : `'${Name}' takes props: Screen('${Name}', props)`
+          : Props extends AsWritten<PropsOf<AppScreens[Name]>>
+            ? never
+            : `the props of '${Name}' are not those its component takes`
+        : `there is no screen '${Name}' in screens`
+    : never;
+
+// The props of a layout are inferred as written (`const`): readonly, with their arrays readonly too.
+type AsWritten<Value> = Value extends (...args: any[]) => unknown
+  ? Value
+  : Value extends readonly (infer Item)[]
+    ? readonly AsWritten<Item>[]
+    : Value extends object
+      ? { readonly [Key in keyof Value]: AsWritten<Value[Key]> }
+      : Value;
+
+/**
+ * A layout whose screens are screens of the app with their props: unknown. Otherwise a property named by what is
+ * wrong, which no layout has, so the type error says why.
+ */
+export type CheckedScreens<Uses, AppScreens> = [ScreenUseError<Uses, AppScreens>] extends [never]
+  ? unknown
+  : { readonly [Message in `[navigation] ${ScreenUseError<Uses, AppScreens>}`]: never };
+
+type PropsOf<Entry> =
+  Entry extends Arrangement<infer Props>
+    ? Props
+    : Entry extends NativeScreen<infer Props>
+      ? Props
+      : Entry extends ScreenDefinition<infer Props>
+        ? Props
+        : Entry extends ComponentType<infer Props>
+          ? Props
+          : Entry extends { load: () => infer Module }
+            ? PropsOfModule<Awaited<Module>>
+            : object;
+
+type PropsOfModule<Module> = Module extends { default: infer Default }
+  ? PropsOf<Default>
+  : PropsOf<Module>;

package/src/engine/backListeners.ts

@@ -0,0 +1,36 @@
+import { BackHandler, Platform } from 'react-native';
+import { commands } from './native';
+
+// The back handlers of `BackHandler`, kept as React Native keeps them: one entry per function, whatever the event name.
+const handlers = new Set<unknown>();
+let watching = false;
+
+/**
+ * Tells the native side whether JavaScript listens to the back button (Android). The navigation takes the back button
+ * only while it has something to go back to or JavaScript listens: on the first screen the system then plays its own
+ * animation back to the home screen. React Native keeps the listeners to itself, so `BackHandler.addEventListener` is
+ * wrapped to count them; a listener added before `createNavigation` was called isn't counted.
+ */
+export function watchBackListeners(): void {
+  if (watching || Platform.OS !== 'android') return;
+  watching = true;
+  const add = BackHandler.addEventListener;
+  const report = () => commands?.setBackListeners?.(handlers.size > 0);
+  Object.assign(BackHandler, {
+    addEventListener(...args: Parameters<typeof add>): ReturnType<typeof add> {
+      const [, handler] = args;
+      const subscription = add.apply(BackHandler, args);
+      if (!handlers.has(handler)) {
+        handlers.add(handler);
+        if (handlers.size === 1) report();
+      }
+      return {
+        ...subscription,
+        remove() {
+          subscription.remove();
+          if (handlers.delete(handler) && handlers.size === 0) report();
+        },
+      };
+    },
+  });
+}

package/src/engine/buttons.ts

@@ -0,0 +1,91 @@
+import type { NavigationButtonPressedEvent } from '../interfaces/ComponentEvents';
+import type {
+  Options,
+  OptionsFab,
+  OptionsTopBar,
+  OptionsTopBarButton,
+} from '../interfaces/Options';
+import { toScreenEvent } from './events';
+import { onNativeEvent } from './native';
+
+// What a press of a button or of an item of its menu calls; the API gives the event its form (see `setPressEvent`).
+type PressHandler = (event: any) => void;
+
+type WithPress = {
+  id?: string;
+  onPress?: PressHandler;
+  menu?: { items?: unknown[] };
+  items?: unknown[];
+  actions?: unknown[];
+};
+
+// The press handlers of the buttons of each screen, and of the items of their menus: screen id → id → handler.
+const handlers = new Map<string, Map<string, PressHandler>>();
+let pressEvent: (
+  event: ReturnType<typeof toScreenEvent<NavigationButtonPressedEvent>>
+) => unknown = (event) => event;
+let listening = false;
+
+/** What a press handler gets: the API adds the navigation of the screen to the event. */
+export function setPressEvent(make: typeof pressEvent): void {
+  pressEvent = make;
+}
+
+/** The options without the press handlers of their buttons, menu items and FAB, which the screen keeps. */
+export function takeButtonHandlers(screenId: string, options: Options): Options {
+  const found = new Map<string, PressHandler>();
+  // A menu item sends a press with its own id, as a button does.
+  const stripItems = (items: unknown[] | undefined): unknown[] | undefined =>
+    items?.map((item) => {
+      const { onPress, ...rest } = item as WithPress;
+      if (onPress && rest.id) found.set(rest.id, onPress);
+      return rest.items ? { ...rest, items: stripItems(rest.items) } : onPress ? rest : item;
+    });
+  const strip = (buttons: unknown[] | undefined) =>
+    buttons?.map((item) => {
+      const { onPress, ...button } = item as WithPress;
+      if (onPress && button.id) found.set(button.id, onPress);
+      const menu = button.menu?.items
+        ? { ...button.menu, items: stripItems(button.menu.items) }
+        : button.menu;
+      return onPress || menu !== button.menu ? { ...button, menu } : item;
+    });
+  let result = options;
+  if (options.topBar) {
+    const topBar: OptionsTopBar = { ...options.topBar };
+    for (const side of ['leftButtons', 'rightButtons', 'centerButtons'] as const) {
+      if (topBar[side]) topBar[side] = strip(topBar[side]) as OptionsTopBarButton[];
+    }
+    result = { ...result, topBar };
+  }
+  if (options.toolbar?.buttons) {
+    const buttons = strip(options.toolbar.buttons) as NonNullable<Options['toolbar']>['buttons'];
+    result = { ...result, toolbar: { ...options.toolbar, buttons } };
+  }
+  // The FAB and its actions send a press with their own id, as a button does.
+  const stripFab = (fab: unknown): OptionsFab => {
+    const { onPress, ...rest } = fab as WithPress & OptionsFab;
+    if (onPress && rest.id) found.set(rest.id, onPress);
+    return rest.actions ? { ...rest, actions: rest.actions.map(stripFab) } : rest;
+  };
+  if (options.fab) result = { ...result, fab: stripFab(options.fab) };
+  if (found.size > 0) {
+    listen();
+    const own = handlers.get(screenId) ?? new Map<string, PressHandler>();
+    found.forEach((handler, id) => own.set(id, handler));
+    handlers.set(screenId, own);
+  }
+  return result;
+}
+
+export function clearButtonHandlers(screenId: string) {
+  handlers.delete(screenId);
+}
+
+function listen() {
+  if (listening) return;
+  listening = true;
+  onNativeEvent<NavigationButtonPressedEvent>('NavigationButtonPressed', (event) => {
+    handlers.get(event.componentId)?.get(event.buttonId)?.(pressEvent(toScreenEvent(event)));
+  });
+}