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

package/src/engine/options.ts

@@ -0,0 +1,165 @@
+import { DynamicColorIOS, Image, Platform, processColor } from 'react-native';
+import type { ColorValue, ImageSourcePropType } from 'react-native';
+import { nextId } from './ids';
+import { rememberButtonRoot, setProps } from './props';
+
+type Fields = Record<string, unknown>;
+
+/**
+ * The options as the native side reads them: colors in the format of the platform, images resolved, and every
+ * component in them with an id of its own (its props stay in JavaScript). Options come in their own form only:
+ * animations with `enter` and `exit`, `searchBar` and `interpolation` as objects.
+ */
+export function toNativeOptions<T>(options: T): T {
+  return convert(options) as T;
+}
+
+/**
+ * Options as the native side reads them over others, merged as the native side merges them: groups key by key, while
+ * a color or an image, an object here too, replaces what was there as any value does. `undefined` keeps it.
+ */
+export function mergeNativeOptions<T extends object>(base: T, over: T): T {
+  const result = { ...base } as Fields;
+  for (const [key, next] of Object.entries(over)) {
+    if (next === undefined) continue;
+    const previous = result[key];
+    result[key] =
+      !isColor(key) && !isImage(key) && isGroup(previous) && isGroup(next)
+        ? mergeNativeOptions(previous, next)
+        : next;
+  }
+  return result as T;
+}
+
+function isGroup(value: unknown): value is Fields {
+  return isFields(value) && !Array.isArray(value);
+}
+
+function convert(value: unknown, key?: string): unknown {
+  if (key !== undefined && isColor(key)) return nativeColor(value);
+  if (key !== undefined && isImage(key)) return nativeImage(value);
+  if (Array.isArray(value)) {
+    const items = value.map((item) => convert(item));
+    if (key?.endsWith('Buttons') || key === 'buttons') items.forEach(noteButtonRoot);
+    return key?.endsWith('Buttons') ? items.map(takeButtonProps) : items;
+  }
+  if (!isFields(value)) return value;
+  const result: Fields = {};
+  for (const [name, item] of Object.entries(withSymbols(value))) {
+    // The props of a component are its own, not options.
+    result[name] = name === 'passProps' ? item : convert(item, name);
+  }
+  return key === 'component' || key === 'resultsComponent' ? takeComponentProps(result) : result;
+}
+
+function isColor(key: string): boolean {
+  return (key === 'color' || key.endsWith('Color')) && key !== 'bkgColor';
+}
+
+function isImage(key: string): boolean {
+  return key === 'icon' || key === 'image' || key.endsWith('Icon') || key.endsWith('Image');
+}
+
+// The SF Symbol of an icon goes in the field the native side draws symbols from (a tab draws its filled variant).
+const SYMBOL_FIELDS = { icon: 'sfSymbol', selectedIcon: 'sfSelectedSymbol' } as const;
+
+/** An icon for each platform (`{ ios, android }`), as opposed to an image source. */
+function isPlatformIcon(value: unknown): value is { ios?: unknown; android?: unknown } {
+  return (
+    isFields(value) &&
+    !Array.isArray(value) &&
+    !('uri' in value) &&
+    ('ios' in value || 'android' in value)
+  );
+}
+
+/** The fields with the icon of this platform in place of each `{ ios, android }` icon. */
+function withSymbols(fields: Fields): Fields {
+  let result = fields;
+  for (const [field, symbolField] of Object.entries(SYMBOL_FIELDS)) {
+    const icon = fields[field];
+    if (!isPlatformIcon(icon)) continue;
+    const own = Platform.OS === 'ios' ? icon.ios : icon.android;
+    result = { ...result };
+    delete result[field];
+    if (own === undefined) continue;
+    if (Platform.OS === 'ios' && typeof own === 'string') result[symbolField] = own;
+    else result[field] = own;
+  }
+  return result;
+}
+
+// An image: a source to resolve, the name of an Android drawable, or an icon for each platform.
+function nativeImage(value: unknown): unknown {
+  if (!value || typeof value === 'string') return value;
+  if (isPlatformIcon(value)) {
+    const own = Platform.OS === 'ios' ? value.ios : value.android;
+    if (own === undefined) return undefined;
+    if (typeof own === 'string') return Platform.OS === 'ios' ? { system: own } : own;
+    return Image.resolveAssetSource(own as ImageSourcePropType);
+  }
+  return Image.resolveAssetSource(value as ImageSourcePropType);
+}
+
+function isFields(value: unknown): value is Fields {
+  return typeof value === 'object' && value !== null;
+}
+
+// A component in the options gets an id; the native side creates it with that id, and its props wait here.
+function takeComponentProps({ passProps, ...component }: Fields): Fields {
+  const componentId = (component.id as string | undefined) || nextId('CustomComponent');
+  if (passProps) setProps(componentId, passProps as object);
+  return { ...component, componentId };
+}
+
+// The component of a bar button (the top bar's `*Buttons`, the toolbar's `buttons`) is a root the native side only
+// sizes: its wrapper centers the content in the button's slot.
+function noteButtonRoot(button: unknown): void {
+  const component = isFields(button) ? button.component : undefined;
+  if (isFields(component) && typeof component.componentId === 'string') {
+    rememberButtonRoot(component.componentId);
+  }
+}
+
+// The props of a button with a component of its own go with the button's id.
+function takeButtonProps(button: unknown): unknown {
+  if (!isFields(button) || !button.passProps || !button.id) return button;
+  const { passProps, ...rest } = button;
+  setProps(button.id as string, passProps as object);
+  return rest;
+}
+
+function nativeColor(value: unknown): unknown {
+  if (value === undefined) return undefined;
+  return Platform.OS === 'ios' ? iosColor(value) : androidColor(value);
+}
+
+// One color, a pair for the light and the dark appearance, or a semantic color; null takes the color away.
+function iosColor(value: unknown): unknown {
+  if (value === null) return 'NoColor';
+  if (!isFields(value)) return processColor(value as ColorValue);
+  if ('semantic' in value) return value;
+  const pair = ('dynamic' in value ? value.dynamic : value) as {
+    light: ColorValue;
+    dark: ColorValue;
+  };
+  return DynamicColorIOS({
+    light: processColor(pair.light) as ColorValue,
+    dark: processColor(pair.dark) as ColorValue,
+  });
+}
+
+// Android always takes a pair; one color goes to both, and the side without a color has none.
+function androidColor(value: unknown): unknown {
+  const pair: Fields = { dark: 'NoColor', light: 'NoColor' };
+  if (value === null) return pair;
+  if (!isFields(value)) {
+    const color = processColor(value as ColorValue);
+    return { dark: color, light: color };
+  }
+  if ('semantic' in value || 'resource_paths' in value) return value;
+  for (const [appearance, color] of Object.entries(value)) {
+    pair[appearance] = processColor(color as ColorValue);
+  }
+  return pair;
+}

package/src/engine/places.ts

@@ -0,0 +1,205 @@
+import type { SplitViewColumnsStackedEvent } from '../interfaces/Events';
+import type { LayoutNode } from './layout';
+import { onNativeEvent } from './native';
+import { screenNameOf } from './slots';
+
+// Where each screen is, noted as the engine builds the layouts of the commands: what it shows in and its place in its
+// stack. A screen keeps its place while it lives (a command can only put screens over it or take it away), so the
+// navigation answers about it at once, without asking the native side.
+
+/** Where a screen is. */
+export interface ScreenPlace {
+  /** Its name, as the native side knows it. */
+  name: string;
+  /** What it shows in: the root (with its tabs, menus and columns), a modal, or an overlay. */
+  container: 'root' | 'modal' | 'overlay';
+  /** The id of its stack, null outside a stack. */
+  stack: string | null;
+  /** Its index in its stack: 0 for the first screen and outside a stack. */
+  index: number;
+  /** The side menu it is in, and its part there: a menu or the center. */
+  menu?: { id: string; part: 'left' | 'center' | 'right' };
+  /**
+   * The layer it shows in: `'root'`, or the id of the layout of its modal or overlay. A screen of a layer under the one
+   * the user sees is covered, by a sheet too, though it doesn't disappear then.
+   */
+  layer: string;
+  /** The pair it is a view of; `alone`: its primary, shown alone where the native side shows no pairs. */
+  arrangement?: { id: string; placement: 'primary' | 'secondary'; alone?: boolean };
+}
+
+const MENU_PARTS: Partial<Record<LayoutNode['type'], 'left' | 'center' | 'right'>> = {
+  SideMenuLeft: 'left',
+  SideMenuCenter: 'center',
+  SideMenuRight: 'right',
+};
+
+/** A column of a split view: the split view's id and the column's name. */
+export interface SplitColumn {
+  split: string;
+  column: string;
+}
+
+const places = new Map<string, ScreenPlace>();
+// The column each stack of a split view shows, by the stack's id, and the column of a screen alone in one; the stack
+// of each column, by the split view's id. A screen pushed in a column's stack is in that column too.
+const columnOfStack = new Map<string, SplitColumn>();
+const columnOfScreen = new Map<string, SplitColumn>();
+const stacksOfSplit = new Map<string, Partial<Record<string, string>>>();
+// The split views whose columns show as one stack, one over another, as the native side tells.
+const stackedSplits = new Set<string>();
+let listeningToSplitViews = false;
+// The primaries of pairs shown alone, noted as their node is built, until their place is noted.
+const alone = new Set<string>();
+// The last screens that went, so a command from one of them can say so; a screen the engine never saw is not one.
+const gone = new Set<string>();
+const GONE_KEPT = 200;
+
+export function placeOf(screenId: string): ScreenPlace | undefined {
+  return places.get(screenId);
+}
+
+/** Notes that a screen is the primary of a pair shown alone, where the native side shows no pairs. */
+export function noteAlone(screenId: string): void {
+  alone.add(screenId);
+}
+
+/** The screen was shown and is gone. */
+export function isGone(screenId: string): boolean {
+  return gone.has(screenId);
+}
+
+/**
+ * Notes the screens of a layout, the first of a stack at `index`. A modal or an overlay given as a whole is a layer of
+ * its own; screens added to one, such as a push, take the layer of the screen they come from.
+ */
+export function notePlaces(
+  node: LayoutNode,
+  container: ScreenPlace['container'],
+  stack: string | null = null,
+  index = 0,
+  menu?: ScreenPlace['menu'],
+  layer: string = container === 'root' ? 'root' : node.id
+): void {
+  if (node.type === 'Component' || node.type === 'ExternalComponent') {
+    const name = node.data.name ?? '';
+    gone.delete(node.id);
+    columnOfScreen.delete(node.id);
+    places.set(node.id, {
+      name: screenNameOf(name),
+      container,
+      stack,
+      index,
+      ...(menu && { menu }),
+      layer,
+      ...(alone.delete(node.id)
+        ? { arrangement: { id: node.id, placement: 'primary' as const, alone: true } }
+        : {}),
+    });
+  } else if (node.type === 'Arrangement') {
+    // One entry of its stack: both screens have its place there, and each knows the pair.
+    node.children.forEach((child, childIndex) => {
+      notePlaces(child, container, stack, index, menu, layer);
+      const place = places.get(child.id);
+      if (place) {
+        const placement = childIndex === 0 ? 'primary' : 'secondary';
+        places.set(child.id, { ...place, arrangement: { id: node.id, placement } });
+      }
+    });
+  } else if (node.type === 'Stack') {
+    columnOfStack.delete(node.id);
+    node.children.forEach((child, childIndex) =>
+      notePlaces(child, container, node.id, childIndex, menu, layer)
+    );
+  } else if (node.type === 'SplitView') {
+    // A split view sent again with its id starts anew: its columns are noted again, and it isn't one stack until the
+    // native side says so.
+    forgetSplit(node.id);
+    const columns = node.data.columns ?? [];
+    const stacks: Partial<Record<string, string>> = {};
+    node.children.forEach((child, childIndex) => {
+      notePlaces(child, container, null, 0, menu, layer);
+      const column = columns[childIndex];
+      if (!column) return;
+      if (child.type === 'Stack') stacks[column] = child.id;
+      noteColumn(child, { split: node.id, column });
+    });
+    stacksOfSplit.set(node.id, stacks);
+  } else if (node.type === 'SideMenuRoot') {
+    for (const part of node.children) {
+      const side = MENU_PARTS[part.type];
+      part.children.forEach((child) =>
+        notePlaces(child, container, null, 0, side ? { id: node.id, part: side } : menu, layer)
+      );
+    }
+  } else {
+    node.children.forEach((child) => notePlaces(child, container, null, 0, menu, layer));
+  }
+}
+
+// The column of every stack and every screen out of a stack under a column of a split view, also in its tabs or menus.
+function noteColumn(node: LayoutNode, column: SplitColumn): void {
+  if (node.type === 'Stack') columnOfStack.set(node.id, column);
+  else if (node.type === 'Component' || node.type === 'ExternalComponent') {
+    columnOfScreen.set(node.id, column);
+  } else node.children.forEach((child) => noteColumn(child, column));
+}
+
+function forgetSplit(split: string): void {
+  stackedSplits.delete(split);
+  stacksOfSplit.delete(split);
+  for (const columns of [columnOfStack, columnOfScreen]) {
+    for (const [id, column] of columns) if (column.split === split) columns.delete(id);
+  }
+}
+
+/** The column of a split view the screen shows in, through its stack or alone; undefined outside a split view. */
+export function columnOf(screenId: string): SplitColumn | undefined {
+  const place = places.get(screenId);
+  if (!place) return undefined;
+  return place.stack !== null ? columnOfStack.get(place.stack) : columnOfScreen.get(screenId);
+}
+
+/** The id of the stack a column of the split view shows, when it shows one. */
+export function stackOfColumn(split: string, column: string): string | undefined {
+  return stacksOfSplit.get(split)?.[column];
+}
+
+/**
+ * Whether the screen is the first of its column's stack and that column is over the column before it: the columns of
+ * its split view show as one stack (a phone), so back goes to the column before.
+ */
+export function coversColumn(screenId: string): boolean {
+  const place = places.get(screenId);
+  const column = columnOf(screenId);
+  return (
+    place !== undefined &&
+    place.stack !== null &&
+    place.index === 0 &&
+    column !== undefined &&
+    (column.column === 'secondary' || column.column === 'supplementary') &&
+    stackOfColumn(column.split, column.column) === place.stack &&
+    stackedSplits.has(column.split)
+  );
+}
+
+/** Listens to the split views telling whether their columns show as one stack, once for the app. */
+export function listenToSplitViews(): void {
+  if (listeningToSplitViews) return;
+  listeningToSplitViews = true;
+  onNativeEvent<SplitViewColumnsStackedEvent>(
+    'SplitViewColumnsStacked',
+    ({ componentId, stacked }) => {
+      if (stacked) stackedSplits.add(componentId);
+      else stackedSplits.delete(componentId);
+    }
+  );
+}
+
+/** The screen is gone. */
+export function forgetPlace(screenId: string): void {
+  places.delete(screenId);
+  columnOfScreen.delete(screenId);
+  gone.add(screenId);
+  if (gone.size > GONE_KEPT) gone.delete(gone.values().next().value!);
+}

package/src/engine/props.ts

@@ -0,0 +1,45 @@
+// The props of the screens and of the components in options, by their ids. A command puts them here before the native
+// side creates the views, and each view takes its own as it mounts: React Native passes a root only its id. New props
+// under the id of a view already shown (options that name the same component again) render it again with them.
+const byId = new Map<string, object>();
+const watchers = new Map<string, Set<() => void>>();
+// The same object each time, so a view without props is not told they changed.
+const none = {};
+// The roots that are the components of bar buttons: their wrapper centers the content in the button's slot.
+const buttonRoots = new Set<string>();
+
+export function setProps(id: string, props: object | undefined): void {
+  if (props === undefined) byId.delete(id);
+  else byId.set(id, props);
+  watchers.get(id)?.forEach((watcher) => watcher());
+}
+
+export function propsOf(id: string): object {
+  return byId.get(id) ?? none;
+}
+
+/** Calls back when the props under the id change; returns what stops it. */
+export function watchProps(id: string, watcher: () => void): () => void {
+  let set = watchers.get(id);
+  if (!set) watchers.set(id, (set = new Set()));
+  set.add(watcher);
+  return () => {
+    set.delete(watcher);
+    if (set.size === 0) watchers.delete(id);
+  };
+}
+
+export function rememberButtonRoot(id: string): void {
+  buttonRoots.add(id);
+}
+
+/** Whether the root under the id is the component of a bar button (top bar or toolbar). */
+export function isButtonRoot(id: string): boolean {
+  return buttonRoots.has(id);
+}
+
+/** The view is gone: its props, and whether it is a button's root, are not needed again. */
+export function forgetProps(id: string): void {
+  byId.delete(id);
+  buttonRoots.delete(id);
+}

package/src/engine/reactMeasures.ts

@@ -0,0 +1,24 @@
+// In development React records a `performance.measure` for every render of a component, for the performance tracks of
+// React DevTools, and React Native keeps every entry: a long session of navigation runs out of memory. A trace that
+// records takes the entries as they come, so dropping them from the buffer loses nothing.
+
+// React names the measure of a component's render after the component with this mark in front; nothing else does.
+const RENDER_MARK = '​';
+
+// The part of React Native's Performance API this uses.
+interface Measures {
+  getEntriesByType?(type: 'measure'): readonly { name: string }[];
+  clearMeasures?(name?: string): void;
+}
+
+/** Drops React's measures of component renders (development only); the app's own measures stay. */
+export function dropReactRenderMeasures(): void {
+  if (!__DEV__) return;
+  const performance = (globalThis as { performance?: Measures }).performance;
+  if (!performance?.getEntriesByType || !performance.clearMeasures) return;
+  const names = new Set<string>();
+  for (const entry of performance.getEntriesByType('measure')) {
+    if (entry.name.startsWith(RENDER_MARK)) names.add(entry.name);
+  }
+  names.forEach((name) => performance.clearMeasures?.(name));
+}

package/src/engine/rememberedOptions.ts

@@ -0,0 +1,111 @@
+import type { Options } from '../interfaces/Options';
+import type { LayoutNode } from './layout';
+import { mergeOptions } from './mergeOptions';
+import { mergeNativeOptions, toNativeOptions } from './options';
+
+// The options every mergeOptions sent to a node, merged over one another, by the node's id. Android destroys the
+// activity with every screen while JavaScript lives on, and the last root, set again for the next activity, shows them
+// again. Only the nodes of that root keep them, until another root goes out: the activity takes the screens of the
+// root with it before the root is set again, so they keep them past their unmount.
+
+/** The nodes of the root the native side got last, as it read them. */
+export interface SentRoot {
+  nodes: LayoutNode[];
+  ids: Set<string>;
+}
+
+const remembered = new Map<string, Options>();
+let lastRoot: SentRoot | undefined;
+
+/**
+ * Remembers the options a mergeOptions sent to the node with the id, over those remembered for it before. Only the
+ * nodes of the last root are shown again, so only theirs are kept: a screen pushed or shown in a modal later is not
+ * in that root. The options that act once (a tab to select, a menu to open) stay in no node and are not remembered.
+ */
+export function rememberMergedOptions(id: string, options: Options): void {
+  if (!lastRoot?.ids.has(id)) return;
+  const kept = withoutOneTimeOptions(options);
+  const before = remembered.get(id);
+  remembered.set(id, before ? mergeOptions(before, kept) : kept);
+}
+
+/** Forgets the merged options of a node that went; a node of the last root keeps them until another root goes out. */
+export function forgetMergedOptions(id: string): void {
+  if (!lastRoot?.ids.has(id)) remembered.delete(id);
+}
+
+/** The options merged into the node with the id, as remembered; undefined without any. */
+export function mergedOptionsOf(id: string): Options | undefined {
+  return remembered.get(id);
+}
+
+/** The root the native side got last; undefined before the first one. */
+export function sentRoot(): SentRoot | undefined {
+  return lastRoot;
+}
+
+/**
+ * Notes the layouts of a root going out to the native side now: the root, its modals and its overlays. `again` is the
+ * root the native side had when the last root was set again for a new launch of the native side (Android: a new
+ * activity), undefined for any other root. While it is still the last one, each node of the new layout in the place of
+ * one of its nodes takes the options merged into that one over its own, and keeps them under its own id. Otherwise the
+ * nodes of the root before drop theirs: they all go.
+ */
+export function rootGoesOut(nodes: LayoutNode[], again: SentRoot | undefined): void {
+  const before = lastRoot;
+  lastRoot = { nodes, ids: new Set(nodes.flatMap(idsOf)) };
+  if (!before) return;
+  const moved = new Map<string, Options>();
+  if (again === before) {
+    pairNodes(before.nodes, nodes, (old, node) => {
+      const options = remembered.get(old.id);
+      if (!options) return;
+      node.data.options = mergeNativeOptions(node.data.options ?? {}, toNativeOptions(options));
+      moved.set(node.id, options);
+    });
+  }
+  before.ids.forEach((id) => remembered.delete(id));
+  moved.forEach((options, id) => remembered.set(id, options));
+}
+
+function idsOf(node: LayoutNode): string[] {
+  return [node.id, ...node.children.flatMap(idsOf)];
+}
+
+// The same root built again has the same nodes in the same places, the same kind with the same name; those the app gave
+// no id to get new ids.
+function pairNodes(
+  before: LayoutNode[],
+  after: LayoutNode[],
+  pair: (old: LayoutNode, node: LayoutNode) => void
+): void {
+  before.forEach((old, index) => {
+    const node = after[index];
+    if (!node || node.type !== old.type || node.data.name !== old.data.name) return;
+    pair(old, node);
+    pairNodes(old.children, node.children, pair);
+  });
+}
+
+// Selecting a tab and opening or closing a menu act when they arrive and stay in no node's options: the root set again
+// neither selects the tab nor opens the menu once more.
+function withoutOneTimeOptions(options: Options): Options {
+  let result = options;
+  if (options.bottomTabs) {
+    const bottomTabs = { ...options.bottomTabs };
+    delete bottomTabs.currentTabIndex;
+    delete bottomTabs.currentTabId;
+    result = { ...result, bottomTabs };
+  }
+  if (options.sideMenu) {
+    const sideMenu = { ...options.sideMenu };
+    for (const side of ['left', 'right'] as const) {
+      const settings = sideMenu[side] && { ...sideMenu[side] };
+      if (!settings) continue;
+      delete settings.visible;
+      sideMenu[side] = settings;
+    }
+    result = { ...result, sideMenu };
+  }
+  return result;
+}