@apexnative/navigation 1.0.0-alpha.0 → 1.0.0-alpha.10

package/src/engine/rememberedOptions.ts

@@ -29,9 +29,77 @@ export function rememberMergedOptions(id: string, options: Options): void {
   remembered.set(id, before ? mergeOptions(before, kept) : kept);
 }
 
+/** Takes the options at the paths, such as `['topBar', 'subtitle']`, out of those remembered for the node with the id. */
+export function forgetMergedPaths(id: string, paths: readonly string[][]): void {
+  const own = ownOptions.get(id);
+  if (own) own.options = withoutPaths(own.options, paths);
+  const options = remembered.get(id);
+  if (options) remembered.set(id, withoutPaths(options, paths));
+}
+
+// A copy of the options without the values at the paths.
+function withoutPaths(options: Options, paths: readonly string[][]): Options {
+  const kept = structuredCopy(options);
+  for (const path of paths) {
+    const parent = path
+      .slice(0, -1)
+      .reduce<Record<string, unknown> | undefined>(
+        (group, key) => group?.[key] as Record<string, unknown> | undefined,
+        kept
+      );
+    if (parent) delete parent[path[path.length - 1]!];
+  }
+  return kept as Options;
+}
+
+// A copy of the plain objects of options, the other values shared.
+function structuredCopy(options: Options): Record<string, unknown> {
+  return Object.fromEntries(
+    Object.entries(options).map(([key, value]) => [
+      key,
+      isGroup(value) ? structuredCopy(value as Options) : value,
+    ])
+  );
+}
+
+function isGroup(value: unknown): boolean {
+  return (
+    typeof value === 'object' && value !== null && Object.getPrototypeOf(value) === Object.prototype
+  );
+}
+
 /** 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);
+  ownOptions.delete(id);
+}
+
+// The own options of each screen as JavaScript sent them, in development: those it showed with, and every merge and
+// clear since. An edit of a screen's options (Fast Refresh) changes only what still has the old definition's value.
+const ownOptions = new Map<string, { name: string; options: Options }>();
+
+/** Notes the own options a screen of the name shows with (development). */
+export function noteOwnOptions(id: string, name: string, options: Options): void {
+  if (__DEV__) ownOptions.set(id, { name, options });
+}
+
+/** Notes a merge into a screen's own options (development). */
+export function noteMergedOwnOptions(id: string, options: Options): void {
+  const noted = __DEV__ ? ownOptions.get(id) : undefined;
+  if (noted) noted.options = mergeOptions(noted.options, options);
+}
+
+/** The own options of a screen as JavaScript sent them (development); undefined for a screen it didn't note. */
+export function ownOptionsOf(id: string): Options | undefined {
+  return ownOptions.get(id)?.options;
+}
+
+/**
+ * The ids of the screens of the name the native side has, mounted in React or not yet (a tab not selected yet), as
+ * development notes them.
+ */
+export function notedScreens(name: string): string[] {
+  return [...ownOptions].filter(([, noted]) => noted.name === name).map(([id]) => id);
 }
 
 /** The options merged into the node with the id, as remembered; undefined without any. */
@@ -55,12 +123,17 @@ export function rootGoesOut(nodes: LayoutNode[], again: SentRoot | undefined): v
   const before = lastRoot;
   lastRoot = { nodes, ids: new Set(nodes.flatMap(idsOf)) };
   if (!before) return;
+  // The screens of the root before go with it, the tabs React never mounted too.
+  for (const id of before.ids) if (!lastRoot.ids.has(id)) ownOptions.delete(id);
   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));
+      node.data.options = mergeNativeOptions(
+        node.data.options ?? {},
+        toNativeOptions(options, node.id)
+      );
       moved.set(node.id, options);
     });
   }

package/src/engine/screens.tsx

@@ -2,7 +2,7 @@ import React, { type ComponentType, useCallback, useEffect, useSyncExternalStore
 import { AppRegistry } from 'react-native';
 import type { Options } from '../interfaces/Options';
 import { forgetPlace } from './places';
-import { forgetProps, propsOf, watchProps } from './props';
+import { forgetProps, isOptionsComponent, propsOf, watchProps } from './props';
 import { forgetMergedOptions } from './rememberedOptions';
 import { hasSlot } from './slots';
 import type { NativeControllerProps } from './nativeScreens';
@@ -52,14 +52,50 @@ export type EngineScreen =
 /** What the root of a React screen renders: the screen's id, and the props the command gave it. */
 export type ScreenRootProps = { componentId: string } & Record<string, unknown>;
 
+/**
+ * What React Native gives the root of a React screen: the screen's id, its root tag (none in a slot of the app's one
+ * tree), and the props the native side gives that root, a tab cell's `tabIndex`, `selected`, `badge`, `dot` and
+ * `dotColor`.
+ */
+export type NativeRootProps = { componentId: string; rootTag?: number } & Record<string, unknown>;
+
 const screens = new Map<string, EngineScreen>();
-const roots = new Map<string, ComponentType<{ componentId: string; rootTag?: number }>>();
+const roots = new Map<string, ComponentType<NativeRootProps>>();
 let unmounted: ((screenId: string) => void) | undefined;
-// The React root that shows each screen, by its root tag. After a JavaScript reload React Native starts the roots of
-// the old screens again in the new runtime, under the ids the new screens get too, and unmounts them once the new ones
-// show; their root tags are older, as the native side counts them up for as long as the app runs. A slot of the app's
-// one tree has no tag: while the one tree shows a screen with the id, no root of that id lets it go.
-const owners = new Map<string, number>();
+// The React roots mounted under each id, by their root tags. One id can have several: after a JavaScript reload React
+// Native starts the roots of the old screens again in the new runtime, under the ids the new screens get too, and
+// unmounts them once the new ones show; a component of the default or a stack's options has one id and a root in the
+// bar of every screen that shows it. The id lets its props go only with the last of them. A slot of the app's one tree
+// has no tag: while the one tree shows a screen with the id, no root of that id lets it go.
+const owners = new Map<string, Set<number>>();
+// The screens that show by their ids: the name, and how many roots or slots of the id are mounted (a component of the
+// options has a root in the bar of every screen that shows it).
+const shown = new Map<string, { name: string; mounts: number }>();
+
+/**
+ * Notes a screen as shown, a React root or slot of it or the controller of a native screen, until the function it
+ * gives is called.
+ */
+export function noteShown(componentId: string, name: string): () => void {
+  const entry = shown.get(componentId);
+  if (entry?.name === name) entry.mounts++;
+  else shown.set(componentId, { name, mounts: 1 });
+  return () => {
+    const current = shown.get(componentId);
+    if (current?.name !== name) return;
+    if (--current.mounts === 0) shown.delete(componentId);
+  };
+}
+
+/** The ids of the screens with the name that show now. */
+export function shownScreens(name: string): string[] {
+  return [...shown].filter(([, entry]) => entry.name === name).map(([id]) => id);
+}
+
+/** Whether a React root of the screen with the id is mounted now (a slot of the app's one tree doesn't count). */
+export function hasRoot(componentId: string): boolean {
+  return owners.has(componentId);
+}
 
 /** What runs when the root of a screen unmounts: the screen is gone. */
 export function onScreenUnmounted(listener: (screenId: string) => void): void {
@@ -192,20 +228,29 @@ export function isReactScreen(name: string): boolean {
   return screen !== undefined && 'component' in screen;
 }
 
+/**
+ * The props a screen's component renders with: those a command left under its id ([stored]), the props the native side
+ * gave its root over them ([root]: a tab cell's state, which the docs promise arrives on top of `passProps`), and its
+ * id. The root tag stays with the root.
+ */
+export function screenProps(stored: object, root: NativeRootProps): ScreenRootProps {
+  const props: ScreenRootProps = { ...stored, ...root, componentId: root.componentId };
+  delete props.rootTag;
+  return props;
+}
+
 /**
  * The root a React screen runs in: the screen with the props a command left for it under its id, and the new ones when
- * options give its id new props. React Native gives a root only its id (and its own root props, which stay here); the
- * slot of the app's one tree renders the same root.
+ * options give its id new props, under the props the native side gives the root ([screenProps]). The slot of the app's
+ * one tree renders the same root.
  */
-export function screenRoot(
-  name: string
-): ComponentType<{ componentId: string; rootTag?: number }> | undefined {
+export function screenRoot(name: string): ComponentType<NativeRootProps> | undefined {
   const screen = screens.get(name);
   if (!screen || !('component' in screen)) return undefined;
   let root = roots.get(name);
   if (!root) {
     const Screen = screen.component();
-    root = function ScreenRoot(rootProps: { componentId: string; rootTag?: number }) {
+    root = function ScreenRoot(rootProps: NativeRootProps) {
       // In the app's one tree the slot renders the root, without a tag of its own.
       const { componentId, rootTag } = rootProps;
       const watch = useCallback(
@@ -213,24 +258,34 @@ export function screenRoot(
         [componentId]
       );
       const props = useSyncExternalStore(watch, () => propsOf(componentId));
+      useEffect(() => noteShown(componentId, name), [componentId]);
       useEffect(() => {
-        if (rootTag !== undefined && rootTag > (owners.get(componentId) ?? -1)) {
-          owners.set(componentId, rootTag);
+        if (rootTag !== undefined) {
+          const tags = owners.get(componentId) ?? new Set<number>();
+          tags.add(rootTag);
+          owners.set(componentId, tags);
         }
         return () => {
-          // An old root of the same id leaves the screen alone, and so does any root while the one tree still has a slot
-          // with the id: a later screen under the id, the restarted root of a screen after a reload into the one tree
-          // (its slot may mount only once the app's provider lets it), the screen rendering again under the provider.
-          if (rootTag !== undefined && owners.get(componentId) !== rootTag) return;
+          // A root while another root of the id is mounted leaves the screen alone, and so does any root while the one
+          // tree still has a slot with the id: a later screen under the id, the restarted root of a screen after a
+          // reload into the one tree (its slot may mount only once the app's provider lets it), the screen rendering
+          // again under the provider.
+          const tags = owners.get(componentId);
+          if (rootTag !== undefined && tags) {
+            tags.delete(rootTag);
+            if (tags.size > 0) return;
+          }
           if (hasSlot(componentId)) return;
           owners.delete(componentId);
-          forgetProps(componentId);
+          // A component the library named in options keeps its props for the next root under its id (the node shows
+          // it again, or another screen shows the same default): they go with the node.
+          if (!isOptionsComponent(componentId)) forgetProps(componentId);
           forgetPlace(componentId);
           forgetMergedOptions(componentId);
           unmounted?.(componentId);
         };
       }, [componentId, rootTag]);
-      return <Screen {...props} componentId={componentId} />;
+      return <Screen {...screenProps(props, rootProps)} />;
     };
     root.displayName = `ScreenRoot(${name})`;
     roots.set(name, root);

package/src/interfaces/ComponentEvents.ts

@@ -10,7 +10,7 @@ export type ComponentType =
 
 /** The fields every appearance event has. */
 interface ComponentAppearanceEvent {
-  /** The id of the component: the screen, or the screen the bar component belongs to. */
+  /** The id of the component: of the screen, or the bar component's own id. */
   componentId: string;
   /** The name of the component: for a screen, its name without any internal prefix. */
   componentName: string;
@@ -60,7 +60,7 @@ export interface NavigationButtonPressedEvent {
    * `ApexNavigation.back`; the hardware back of a modal has `ApexNavigation.hardwareBackButton`.
    */
   buttonId: string;
-  /** (iOS) For a button with `toggle`: its new state, already written into the options of the screen. */
+  /** (iOS) For a button with `toggle`: its new state, which the screen keeps. */
   selected?: boolean;
 }
 
@@ -95,8 +95,8 @@ export interface SheetDetentChangedEvent {
   /** The id of the visible screen of the modal. */
   componentId: string;
   /**
-   * The detent the sheet stopped at: `'medium'`, `'large'`, or a height (points on iOS, dp on Android). `'content'`
-   * is sent on iOS for a detent that fits the content; Android names such a detent `'medium'`.
+   * The detent the sheet stopped at: `'medium'`, `'large'`, `'content'` (the detent that fits the content), or a
+   * height (points on iOS, dp on Android).
    */
   detent: 'medium' | 'large' | 'content' | number;
 }

package/src/interfaces/Events.ts

@@ -54,8 +54,12 @@ export interface NavigationStateChangedEvent {
 
 /**
  * A tab was selected by the user: a press on the tab, a pick from the "More" list or a press on "More" that showed a
- * tab (iOS). It is sent after the selection, and only when the tab changed; a press on the current tab is reported by
- * `BottomTabPressedEvent` alone. Selecting a tab from code sends nothing.
+ * tab (iOS). It goes right after the `ComponentDidAppear` of the new tab's screen, before the navigation state and
+ * before the tab that was left goes back to its first screen (`popToRootOnBlur`), and only when the tab changed: a
+ * press on the selected tab or on a `selectTabOnPress: false` tab is reported by `BottomTabPressedEvent` alone.
+ * Selecting a tab from code sends nothing. A switch still running when another press, long press or choice from code
+ * comes ends first, with this event, so the events of one press never mix with the next; when that tab's screen
+ * hasn't drawn yet, this event goes before its held `ComponentDidAppear`.
  */
 export interface BottomTabSelectedEvent {
   /** The index of the tab that is now selected. */
@@ -67,24 +71,28 @@ export interface BottomTabSelectedEvent {
 }
 
 /**
- * A tab was pressed, the selected one too. It is sent before the tab is selected; with `selectTabOnPress: false` it is
- * the only thing that happens. A long press sends `BottomTabLongPressedEvent` instead.
+ * A tab was pressed, on the bar or on a cell of `bottomTabs.customRow`, the selected one too. It goes first, before
+ * anything the press does. Another tab: then the switch's `ComponentWillAppear`, `ComponentDidDisappear` and
+ * `ComponentDidAppear`, then `BottomTabSelectedEvent`. The selected tab again (`wasSelected: true`): its stack goes
+ * back to its first screen with the events of the user's back (`ScreenPopped`), or, on the first screen, its content
+ * scrolls to the top; with `popToRootOnPress: false` nothing follows. With `selectTabOnPress: false` it is the only
+ * event and the selection stays. A long press sends `BottomTabLongPressedEvent` instead.
  */
 export interface BottomTabPressedEvent {
   /** The index of the tab that was pressed. */
   tabIndex: number;
   /** The id of the tabs. */
   bottomTabsId: string;
-  /** The id of the screen the tab shows: the top of its stack. */
+  /** The id of the screen the tab shows: the top of its stack, or the tab itself when it is a screen. */
   screenId?: string;
   /** Whether the tab was the selected one already; a press on the selected tab scrolls its content to the top. */
   wasSelected: boolean;
 }
 
 /**
- * A tab was pressed and held. The tab is not selected and gets no press event. On iOS it is not sent for the tabs
- * that are components (`bottomTab.component`, `bottomTabs.customRow`), for "More", or for the tab strip at the top of an
- * iPad. On Android it replaces the tooltip of the tab.
+ * A tab was pressed and held, on the bar or on a cell of `bottomTabs.customRow`. The tab is not selected and gets no
+ * press event. On iOS it is not sent for "More" or for the tab strip at the top of an iPad. On Android it replaces the
+ * tooltip of the tab.
  */
 export interface BottomTabLongPressedEvent {
   /** The index of the tab that was pressed. */
@@ -105,6 +113,16 @@ export interface SplitViewColumnsStackedEvent {
   stacked: boolean;
 }
 
+/**
+ * (iOS) A link the app dispatched (`dispatchDeepLinkURL`) that React Native's `Linking` doesn't take from the native
+ * side: on React Native 0.88 and newer, in an app whose Info.plist names a scene delegate, it takes only the links a
+ * scene opened. JavaScript hands it to `Linking` as a `url` event.
+ */
+export interface DeepLinkDispatchedEvent {
+  /** The link. */
+  url: string;
+}
+
 /**
  * A screen of the single React tree was destroyed and the slot still belongs to it: JavaScript removes the slot from
  * its tree. It is not sent for a prepared screen that was never pushed, nor when JavaScript reloads.
@@ -185,11 +203,12 @@ export type HingeState = 'closed' | 'partiallyOpen' | 'fullyOpen' | 'unknown';
  */
 export interface HingeChangedEvent {
   /**
-   * The state of the hinge. On Android `closed` means the device has no fold, or its angle is below 90 degrees.
+   * The state of the hinge. On Android `closed` means the app's window has no fold, or the angle is below 90 degrees,
+   * so a device open flat with a window off the fold (split screen) reports `closed`; Android never gives `unknown`.
    */
   state?: HingeState;
   /**
-   * The angle of the hinge in degrees (on iOS to tenths). Missing when the state is `unknown` and where the system
+   * The angle of the hinge in degrees, to tenths. Missing when the state is `unknown` and where the system
    * gives no angle.
    */
   angle?: number;

package/src/interfaces/Options.ts

@@ -107,6 +107,7 @@ export type {
   ScreenAnimationOptions,
   SharedElementTransition,
   StackAnimationOptions,
+  StackPopAnimationOptions,
   StackPushAnimationOptions,
   TopBarAnimationOptions,
   ViewAnimationOptions,

package/src/interfaces/contract/commands.json

@@ -0,0 +1,101 @@
+{
+  "description": "Every command with a promise (an async method of src/adapters/NativeANNTurboModule.ts): what it resolves with, whether the navigation state goes before its answer (`state`), and whether `ANN.CommandCompleted` follows the answer (`completed`). scripts/contract.mjs makes ios/Contract/ANNCommandContract.{h,mm} and android/.../react/CommandContract.kt from it, and fails when a command of the spec is missing here or a command here is not in the spec.",
+  "commands": [
+    {
+      "name": "setRoot",
+      "resolves": "the id of the root, once the root and the layout's modals and overlays show",
+      "state": true,
+      "completed": true
+    },
+    {
+      "name": "push",
+      "resolves": "the id of the screen that shows; of a pair, the pair's id",
+      "state": true,
+      "completed": true
+    },
+    {
+      "name": "preparePush",
+      "resolves": "the frame `{ width, height, padding }` of the prepared screen, or null; always null on iOS",
+      "state": false,
+      "completed": false
+    },
+    {
+      "name": "pop",
+      "resolves": "the id of the screen that went",
+      "state": true,
+      "completed": true
+    },
+    {
+      "name": "popTo",
+      "resolves": "the id of the screen it went back to",
+      "state": true,
+      "completed": true
+    },
+    {
+      "name": "popToRoot",
+      "resolves": "the id of the first screen of the stack",
+      "state": true,
+      "completed": true
+    },
+    {
+      "name": "setStackRoot",
+      "resolves": "the id of the new top screen",
+      "state": true,
+      "completed": true
+    },
+    {
+      "name": "showModal",
+      "resolves": "the id of the modal's root",
+      "state": true,
+      "completed": true
+    },
+    {
+      "name": "dismissModal",
+      "resolves": "the id of the modal's root",
+      "state": true,
+      "completed": true
+    },
+    {
+      "name": "dismissAllModals",
+      "resolves": "an empty string",
+      "state": true,
+      "completed": true
+    },
+    {
+      "name": "showOverlay",
+      "resolves": "the id of the overlay's root",
+      "state": true,
+      "completed": true
+    },
+    {
+      "name": "dismissOverlay",
+      "resolves": "the id of the overlay's root",
+      "state": true,
+      "completed": true
+    },
+    {
+      "name": "dismissAllOverlays",
+      "resolves": "an empty string",
+      "state": true,
+      "completed": true
+    },
+    {
+      "name": "showInColumn",
+      "resolves": "the id of the screen that shows",
+      "state": true,
+      "completed": true
+    },
+    {
+      "name": "setColumnShown",
+      "resolves": "nothing once the columns stopped moving (`undefined` on iOS, `null` on Android)",
+      "state": true,
+      "completed": false
+    },
+    {
+      "name": "getLaunchLink",
+      "resolves": "the link that launched the app, or null",
+      "state": false,
+      "completed": false
+    }
+  ]
+}