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

package/src/engine/layout.ts

@@ -0,0 +1,247 @@
+import { Platform } from 'react-native';
+import { mergeOptions } from './mergeOptions';
+import type {
+  ExternalComponent,
+  Layout,
+  LayoutBottomTabs,
+  LayoutComponent,
+  LayoutSideMenu,
+  LayoutSplitView,
+} from '../interfaces/Layout';
+import type { Options } from '../interfaces/Options';
+import { takeButtonHandlers } from './buttons';
+import { nextId } from './ids';
+import { showNativeScreen } from './nativeScreens';
+import { toNativeOptions } from './options';
+import { setProps } from './props';
+import { getStartInfo } from './native';
+import { noteAlone } from './places';
+import {
+  arrangementOf,
+  checkArrangement,
+  type EngineArrangement,
+  isReactScreen,
+  nativeScreenName,
+  rendersInSlot,
+  screenKey,
+  screenOptions,
+} from './screens';
+import { slotName } from './slots';
+import { showTabs, TAB_PRESS_HANDLERS, type WithTabPressHandlers } from './tabs';
+
+export type LayoutType =
+  | 'Component'
+  | 'ExternalComponent'
+  | 'Stack'
+  | 'BottomTabs'
+  | 'SideMenuRoot'
+  | 'SideMenuLeft'
+  | 'SideMenuCenter'
+  | 'SideMenuRight'
+  | 'SplitView'
+  | 'Arrangement';
+
+/** A node of the layout as the native side reads it. */
+export interface LayoutNode {
+  id: string;
+  type: LayoutType;
+  data: {
+    name?: string;
+    options?: Options;
+    passProps?: object;
+    /** The names of the functions in the props of a native screen, which it calls in JS. */
+    functions?: string[];
+    /** The key of a screen: a push of a screen with the same key goes back to it in its stack. */
+    key?: string;
+    columns?: string[];
+    /** A pair: how it lies (`arrangement` of a screen, `defineArrangement`). */
+    style?: 'split' | 'overlay';
+    axes?: 'horizontal' | 'vertical' | 'both';
+    fraction?: number;
+    primaryEdge?: 'leading' | 'trailing' | 'top' | 'bottom';
+    compact?: 'primary' | 'pair';
+  };
+  children: LayoutNode[];
+}
+
+// The Android bottom navigation bar can't hold more tabs; the native side would crash.
+const MAX_ANDROID_BOTTOM_TABS = 5;
+
+/**
+ * The layout as the native side reads it. Each screen gets its id and its own options under those of the show; the
+ * press handlers of its buttons stay here, a native screen goes as an external component, and in one tree a React
+ * screen goes as a slot. The props of the React screens wait here for them. The layout passed stays as it was.
+ */
+export function toNativeLayout(layout: Layout): LayoutNode {
+  if (layout.sideMenu) return sideMenu(layout.sideMenu);
+  if (layout.bottomTabs) return bottomTabs(layout.bottomTabs);
+  if (layout.stack) {
+    const { id, options, children } = layout.stack;
+    return parent('Stack', id, options, children);
+  }
+  if (layout.component) return screen(layout.component);
+  if (layout.externalComponent) return external(layout.externalComponent);
+  if (layout.splitView) return splitView(layout.splitView);
+  throw new Error(
+    `[navigation] The layout is of no known kind (keys: ${Object.keys(layout).join(', ')})`
+  );
+}
+
+// `inPair`: a screen of a pair, whose own `arrangement` is not used; nor its key (`keyed`), as its place is the pair's,
+// unless it shows alone.
+function screen(component: LayoutComponent, inPair = false, keyed = !inPair): LayoutNode {
+  const name = String(component.name);
+  const pair = inPair ? undefined : arrangementOf(name);
+  if (pair) return arrangement(component, name, pair);
+  const id = component.id || nextId('Component');
+  const props = component.passProps;
+  const nativeName = nativeScreenName(name);
+  // The native side would show an empty screen, or fail far from the command that named it.
+  if (!nativeName && !isReactScreen(name)) {
+    throw new Error(`[navigation] There is no screen '${name}' in screens`);
+  }
+  if (nativeName) {
+    // A native screen: its props go to the native side as data, its own options over those of the show.
+    const options = takeButtonHandlers(id, component.options ?? {});
+    const node = external({
+      id,
+      name: nativeName,
+      options: mergeOptions(screenOptions(name, props ?? {}), options),
+    });
+    showNativeScreen(node, name, props ?? {});
+    return node;
+  }
+  // The screen's own options under those of the show (a command has them there already: merging again changes
+  // nothing).
+  const own = screenOptions(name, props ?? {});
+  const options = takeButtonHandlers(id, mergeOptions(own, component.options ?? {}));
+  const key = keyed ? screenKey(name, props ?? {}) : undefined;
+  setProps(id, props);
+  return {
+    id,
+    type: 'Component',
+    data: {
+      name: rendersInSlot(name) ? slotName(id, name) : name,
+      options: toNativeOptions(options),
+      ...(key !== undefined && { key }),
+    },
+    children: [],
+  };
+}
+
+/**
+ * Two screens as one screen of a stack. The props of the show go to the primary and, through `secondaryProps`, to the
+ * secondary; the options of the show to the primary, whose bar and options are the pair's. Where the native side shows
+ * no pair, the primary alone. An id given to the show is the primary's on every device, so what goes by it (the close
+ * button of a modal, its `onDismiss`, a held leave) finds the same screen; the pair gets one of its own.
+ */
+function arrangement(
+  component: LayoutComponent,
+  name: string,
+  pair: EngineArrangement
+): LayoutNode {
+  checkArrangement(name, pair);
+  const props = component.passProps;
+  const secondaryProps = props && pair.secondaryProps ? pair.secondaryProps(props) : props;
+  const part = (partName: string, partProps?: object, options?: Options): LayoutComponent => ({
+    name: partName,
+    ...(partProps && { passProps: partProps }),
+    ...(options && { options }),
+  });
+  const primary = {
+    ...part(pair.primary, props, component.options),
+    ...(component.id && { id: component.id }),
+  };
+  if (!getStartInfo().arrangements) {
+    const alone = screen(primary, true, true);
+    noteAlone(alone.id);
+    return alone;
+  }
+  const { style, axes, fraction, primaryEdge, compact } = pair;
+  return {
+    id: nextId('Arrangement'),
+    type: 'Arrangement',
+    data: { name, style, axes, fraction, primaryEdge, compact },
+    children: [screen(primary, true), screen(part(pair.secondary, secondaryProps), true)],
+  };
+}
+
+function external(component: ExternalComponent): LayoutNode {
+  return {
+    id: component.id || nextId('ExternalComponent'),
+    type: 'ExternalComponent',
+    data: {
+      name: String(component.name),
+      options: toNativeOptions(component.options),
+      passProps: component.passProps,
+    },
+    children: [],
+  };
+}
+
+function parent(
+  type: LayoutType,
+  id: string | undefined,
+  options: Options | undefined,
+  children: Layout[] = []
+): LayoutNode {
+  return {
+    id: id || nextId(type),
+    type,
+    data: { options: toNativeOptions(options) },
+    children: children.map(toNativeLayout),
+  };
+}
+
+function bottomTabs(tabs: LayoutBottomTabs): LayoutNode {
+  const count = tabs.children?.length ?? 0;
+  if (Platform.OS === 'android' && count > MAX_ANDROID_BOTTOM_TABS) {
+    throw new Error(
+      `[navigation] Tabs show at most ${MAX_ANDROID_BOTTOM_TABS} tabs on Android; the layout has ${count}`
+    );
+  }
+  const node = parent('BottomTabs', tabs.id, tabs.options, tabs.children);
+  // The press handlers of the tabs stay here, under the id the native side names the tabs with.
+  showTabs(node, (tabs as WithTabPressHandlers)[TAB_PRESS_HANDLERS]);
+  return node;
+}
+
+function sideMenu(menu: LayoutSideMenu): LayoutNode {
+  const side = (type: LayoutType, content: Layout): LayoutNode => ({
+    id: nextId(type),
+    type,
+    data: {},
+    children: [toNativeLayout(content)],
+  });
+  return {
+    id: menu.id || nextId('SideMenuRoot'),
+    type: 'SideMenuRoot',
+    data: { options: toNativeOptions(menu.options) },
+    children: [
+      ...(menu.left ? [side('SideMenuLeft', menu.left)] : []),
+      side('SideMenuCenter', menu.center),
+      ...(menu.right ? [side('SideMenuRight', menu.right)] : []),
+    ],
+  };
+}
+
+// The children with the column of each: `master` is the primary column, `detail` the secondary one. A split view
+// needs both.
+function splitView(split: LayoutSplitView): LayoutNode {
+  const columns = (
+    [
+      ['primary', split.master],
+      ['secondary', split.detail],
+      ['supplementary', split.supplementary],
+      ['compact', split.compact],
+      ['inspector', split.inspector],
+    ] as [string, Layout | undefined][]
+  ).filter((column): column is [string, Layout] => column[1] !== undefined);
+  const present = split.master && split.detail ? columns : [];
+  return {
+    id: split.id || nextId('SplitView'),
+    type: 'SplitView',
+    data: { options: toNativeOptions(split.options), columns: present.map(([column]) => column) },
+    children: present.map(([, content]) => toNativeLayout(content)),
+  };
+}

package/src/engine/mergeOptions.ts

@@ -0,0 +1,20 @@
+/**
+ * Merges options over the ones before: objects merge key by key, anything else — arrays such as buttons, values,
+ * images — replaces what was there. `undefined` keeps the value before.
+ */
+export function mergeOptions<T extends object>(base: T, override: T): T {
+  const result = { ...base } as Record<string, unknown>;
+  for (const [key, next] of Object.entries(override)) {
+    if (next === undefined) continue;
+    const previous = result[key];
+    result[key] =
+      isPlainObject(previous) && isPlainObject(next) ? mergeOptions(previous, next) : next;
+  }
+  return result as T;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== 'object' || value === null) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}

package/src/engine/native.ts

@@ -0,0 +1,51 @@
+import { NativeEventEmitter } from 'react-native';
+import NativeModule, { type Spec } from '../adapters/NativeANNTurboModule';
+import NativeEmitter from '../adapters/NativeANNTurboEventEmitter';
+
+/** The commands of the native side; missing without it (Jest). */
+export const commands: Spec = NativeModule;
+
+// iOS sends its events through the module; Android sends them without one, so the emitter goes without it there.
+// Without the native side (Jest) there is nothing to listen to.
+const emitter = createEmitter();
+
+function createEmitter(): NativeEventEmitter | undefined {
+  try {
+    return new NativeEventEmitter(NativeEmitter);
+  } catch {
+    return undefined;
+  }
+}
+
+/** The URL that launched the native side, given once; null without one, and without the native side (Jest). */
+export function getLaunchLink(): Promise<string | null> {
+  return commands?.getLaunchLink?.() ?? Promise.resolve(null);
+}
+
+/** What the native side tells the JavaScript at its start. */
+export interface StartInfo {
+  /** The first JavaScript runtime of the process: a cold start, not a reload. */
+  coldStart: boolean;
+  /** The size of the native splash's logo as the CLI wrote it, in points (dp); null without it. */
+  splashLogo: { width: number; height: number } | null;
+  /** Whether the native side shows two screens as a pair: iOS 27.1+ built with its SDK, Android. */
+  arrangements: boolean;
+}
+
+let startInfo: StartInfo | undefined;
+
+/** What the native side tells at the start, asked once; without the native side (Jest) a cold start without a logo. */
+export function getStartInfo(): StartInfo {
+  startInfo ??= (commands?.getStartInfo?.() as StartInfo | undefined) ?? {
+    coldStart: true,
+    splashLogo: null,
+    arrangements: false,
+  };
+  return startInfo;
+}
+
+/** Listens to an event of the native side, `ANN.<name>`; returns the function that stops listening. */
+export function onNativeEvent<Event>(name: string, listener: (event: Event) => void): () => void {
+  const subscription = emitter?.addListener(`ANN.${name}`, listener as (event: unknown) => void);
+  return () => subscription?.remove();
+}

package/src/engine/nativeScreens.ts

@@ -0,0 +1,263 @@
+import type { ComponentType } from 'react';
+import type { NativeScreenReleasedEvent } from '../interfaces/Events';
+import type { LayoutNode } from './layout';
+import { commands as native, onNativeEvent } from './native';
+import { forgetPlace } from './places';
+import { forgetMergedOptions } from './rememberedOptions';
+import { nativeScreenController } from './screens';
+
+// The native screens shown with `nativeScreen`, by their ids. Their props go to the native side as plain data; the
+// functions in them stay here, and the native side calls them by name. A screen with `useProps` has a hook that the
+// hidden host runs while the screen is open: what it returns goes over the props of the command, the command waits for
+// its first result, and each change after goes to the native side. The native side tells when a screen is gone.
+
+/** What the hidden host renders for a native screen with `useProps`. */
+export interface NativeControllerProps {
+  componentId: string;
+  /** The props of the command that showed the screen. */
+  props: object;
+  /** What the hook returned, after each render React committed. */
+  onProps(props: object): void;
+  /** The hook failed: a command still waiting for it fails. */
+  onError(error: unknown): void;
+}
+
+/** The hook of a native screen, as the hidden host renders it. */
+export interface NativeScreenHook extends NativeControllerProps {
+  /** Tells apart two screens shown under one id, so the later one starts with a hook of its own. */
+  key: string;
+  Controller: ComponentType<NativeControllerProps>;
+}
+
+// The props of a screen as the native side reads them: the JSON of each data prop, and the functions by name.
+interface NativeProps {
+  data: Map<string, string>;
+  functions: Map<string, (...args: unknown[]) => unknown>;
+}
+
+interface OpenScreen {
+  id: string;
+  name: string;
+  props: NativeProps;
+  /** The data the native side has, and the names of the functions; none before the command sends the screen. */
+  sent?: { data: Map<string, string>; functions: string };
+  hook?: NativeScreenHook;
+  first?: Deferred;
+}
+
+interface Deferred {
+  promise: Promise<void>;
+  resolve(): void;
+  reject(error: unknown): void;
+}
+
+// The host starts in milliseconds; past this a command fails with the reason instead of waiting for ever.
+const HOST_TIMEOUT_MS = 5000;
+
+const screens = new Map<string, OpenScreen>();
+let shown = 0;
+let hooks: readonly NativeScreenHook[] = [];
+const listeners = new Set<() => void>();
+let hostMounted = false;
+const hostWaiters = new Set<() => void>();
+let listening = false;
+
+/** The hooks of the open native screens, for the hidden host. */
+export const nativeScreenHooks = {
+  subscribe(listener: () => void) {
+    listeners.add(listener);
+    return () => {
+      listeners.delete(listener);
+    };
+  },
+  get: (): readonly NativeScreenHook[] => hooks,
+};
+
+/**
+ * A native screen a command shows. Its props go into the node, the data apart from the names of the functions; a
+ * screen with `useProps` starts its hook, and its props go in once the hook has returned (`whenNativeScreensReady`).
+ */
+export function showNativeScreen(node: LayoutNode, name: string, props: object): void {
+  const screen: OpenScreen = { id: node.id, name, props: toNativeProps(props) };
+  const Controller = nativeScreenController(name);
+  if (Controller) {
+    screen.first = deferred();
+    screen.hook = {
+      key: `${node.id}#${++shown}`,
+      Controller,
+      componentId: node.id,
+      props,
+      onProps: (result) => propsChanged(screen, { ...props, ...result }),
+      onError: (error) => screen.first?.reject(error),
+    };
+  } else {
+    writeProps(node, screen);
+  }
+  screens.set(node.id, screen);
+  if (screen.hook) updateHooks();
+}
+
+/**
+ * Sends a command once the native screens it shows have their props: those with `useProps` wait for the first result
+ * of the hook, the others go at once. When the command fails, its native screens go.
+ */
+export function whenNativeScreensReady(
+  nodes: LayoutNode[],
+  send: () => Promise<string>
+): Promise<string> {
+  const shownScreens = externalNodes(nodes).flatMap((node) => {
+    const screen = screens.get(node.id);
+    return screen ? [{ node, screen }] : [];
+  });
+  if (shownScreens.length === 0) return send();
+  const release = (error: unknown): never => {
+    shownScreens.forEach(({ screen }) => forget(screen));
+    throw error;
+  };
+  const waiting = shownScreens.filter(({ screen }) => screen.first && !screen.sent);
+  if (waiting.length === 0) return send().catch(release);
+  return startHost()
+    .then(() => Promise.all(waiting.map(({ screen }) => screen.first!.promise)))
+    .then(() => {
+      // The latest props: a hook may have rendered again while another was not ready.
+      waiting.forEach(({ node, screen }) => writeProps(node, screen));
+      return send();
+    })
+    .catch(release);
+}
+
+/** Runs a function of the props of a native screen, which the native side called by its name. */
+export function callNativeScreenFunction(id: string, name: string, args: unknown[]): unknown {
+  const screen = screens.get(id);
+  if (!screen) throw new Error(`[navigation] No native screen has the id '${id}'`);
+  const fn = screen.props.functions.get(name);
+  if (!fn) throw new Error(`[navigation] The props of '${screen.name}' have no function '${name}'`);
+  return fn(...args);
+}
+
+/** The native screen with the id, for the navigation of its calls. */
+export function nativeScreenInfo(id: string): { id: string; name: string } | undefined {
+  const screen = screens.get(id);
+  return screen && { id: screen.id, name: screen.name };
+}
+
+/** Gives the native side what its call came to: what it returned, as plain data, or the error's message. */
+export function answerNativeScreenCall(callId: string, outcome: Promise<unknown>): void {
+  outcome
+    .then((value) => ({ value: JSON.parse(JSON.stringify(value) ?? 'null') }))
+    .catch((error) => ({ error: error instanceof Error ? error.message : String(error) }))
+    .then((result) => native.resolveNativeScreenCall(callId, result));
+}
+
+/** The hidden host renders, or is gone (a reload); the commands waiting for it go on. */
+export function hostMountedChanged(mounted: boolean): void {
+  hostMounted = mounted;
+  if (!mounted) return;
+  hostWaiters.forEach((started) => started());
+  hostWaiters.clear();
+}
+
+/** Starts the hidden host that runs the hooks (in one tree it runs already); resolves once it renders. */
+export function startHost(): Promise<void> {
+  if (hostMounted) return Promise.resolve();
+  native.startHost();
+  return new Promise((resolve, reject) => {
+    const started = () => {
+      clearTimeout(timer);
+      resolve();
+    };
+    const timer = setTimeout(() => {
+      hostWaiters.delete(started);
+      reject(new Error("[navigation] The host of the native screens' hooks did not start"));
+    }, HOST_TIMEOUT_MS);
+    hostWaiters.add(started);
+  });
+}
+
+/** Listens to the native side letting its screens go, once for the app. */
+export function listenToNativeScreens(): void {
+  if (listening) return;
+  listening = true;
+  onNativeEvent<NativeScreenReleasedEvent>('NativeScreenReleased', ({ componentId }) => {
+    forgetPlace(componentId);
+    forgetMergedOptions(componentId);
+    const screen = screens.get(componentId);
+    if (screen) forget(screen);
+  });
+}
+
+// What the hook returned: before the command sends the screen, it waits in the screen; after, the changes go.
+function propsChanged(screen: OpenScreen, props: object) {
+  if (screens.get(screen.id) !== screen) return;
+  screen.props = toNativeProps(props);
+  if (!screen.sent) {
+    screen.first?.resolve();
+    return;
+  }
+  const sent = screen.sent;
+  const { data, functions } = screen.props;
+  const changed: Record<string, unknown> = {};
+  data.forEach((json, key) => {
+    if (sent.data.get(key) !== json) changed[key] = JSON.parse(json);
+  });
+  const removed = [...sent.data.keys()].filter((key) => !data.has(key));
+  const names = [...functions.keys()];
+  const namesJson = JSON.stringify(names);
+  if (Object.keys(changed).length === 0 && removed.length === 0 && namesJson === sent.functions) {
+    return;
+  }
+  screen.sent = { data, functions: namesJson };
+  native.updateNativeScreenProps(screen.id, { props: changed, removed, functions: names });
+}
+
+function writeProps(node: LayoutNode, screen: OpenScreen) {
+  const { data, functions } = screen.props;
+  node.data.passProps = Object.fromEntries([...data].map(([key, json]) => [key, JSON.parse(json)]));
+  const names = [...functions.keys()];
+  if (names.length > 0) node.data.functions = names;
+  screen.sent = { data, functions: JSON.stringify(names) };
+}
+
+// Data goes as JSON, as the native side reads it: a date as its string, nothing for undefined.
+function toNativeProps(props: object): NativeProps {
+  const data = new Map<string, string>();
+  const functions = new Map<string, (...args: unknown[]) => unknown>();
+  for (const [key, value] of Object.entries(props)) {
+    if (typeof value === 'function') {
+      functions.set(key, value);
+    } else {
+      const json = JSON.stringify(value);
+      if (json !== undefined) data.set(key, json);
+    }
+  }
+  return { data, functions };
+}
+
+function forget(screen: OpenScreen) {
+  if (screens.get(screen.id) !== screen) return;
+  screens.delete(screen.id);
+  if (screen.hook) updateHooks();
+}
+
+function updateHooks() {
+  hooks = [...screens.values()].flatMap(({ hook }) => (hook ? [hook] : []));
+  listeners.forEach((listener) => listener());
+}
+
+function externalNodes(nodes: LayoutNode[]): LayoutNode[] {
+  return nodes.flatMap((node) =>
+    node.type === 'ExternalComponent' ? [node] : externalNodes(node.children)
+  );
+}
+
+function deferred(): Deferred {
+  let resolve!: () => void;
+  let reject!: (error: unknown) => void;
+  const promise = new Promise<void>((onResolve, onReject) => {
+    resolve = onResolve;
+    reject = onReject;
+  });
+  // The command that waited has failed already; nobody waits again.
+  promise.catch(() => {});
+  return { promise, resolve, reject };
+}