@apexnative/navigation 1.0.0-alpha.3 → 1.0.0-alpha.4

package/src/api/hooks/useNavigation.ts

@@ -22,7 +22,7 @@ import type { ScreenName, ShowArgs } from '../types';
 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. */
+  /** Shows a screen over this one in its stack; resolves with the id of the screen shown (for a pair, the pair's id). */
   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

package/src/api/navigation.ts

@@ -55,7 +55,10 @@ export interface AppNavigation {
   switchTo<const Layout extends Exclude<RootLayout, string>>(
     layout: Layout & NoInfer<CheckedScreens<UsesOfRoot<Layout>, RegisteredScreens>>
   ): Promise<void>;
-  /** Shows a screen in the stack of the screen the user sees; resolves with the id of the screen shown. */
+  /**
+   * Shows a screen in the stack of the screen the user sees; resolves with the id of the screen shown (for a pair, the
+   * pair's id).
+   */
   push<Name extends ScreenName>(name: Name, ...args: ShowArgs<Name, PushConfig>): Promise<string>;
   /** Goes back in the stack of the screen the user sees; see `useNavigation().pop`. */
   pop(): Promise<string>;

package/src/engine/commands.ts

@@ -9,7 +9,7 @@ import { whenNativeScreensReady } from './nativeScreens';
 import { commands as native } from './native';
 import { toNativeOptions } from './options';
 import { dropReactRenderMeasures } from './reactMeasures';
-import { columnOf, forgetPlace, notePlaces, placeOf, stackOfColumn } from './places';
+import { columnOf, forgetPlace, layoutsOf, notePlaces, placeOf, stackOfColumn } from './places';
 import { forgetProps } from './props';
 import {
   forgetMergedOptions,
@@ -122,7 +122,7 @@ export function setRoot(root: LayoutRoot): Promise<string> {
 
 export function setDefaultOptions(options: Options): void {
   rememberDefaultOptions(options);
-  native.setDefaultOptions(toNativeOptions(options));
+  native.setDefaultOptions(toNativeOptions(options, 'defaultOptions'));
 }
 
 // The show commands that wait in JS, by number: for lazy screens to load, for the first props of native screens, for a
@@ -141,7 +141,7 @@ const preparedScreens = new Set<string>();
  * engine remembers them by the node's id, so the root set again for a new launch of the native side shows them too.
  */
 export function mergeOptions(componentId: string, options: Options): void {
-  const nativeOptions = toNativeOptions(options);
+  const nativeOptions = toNativeOptions(options, componentId);
   const send = () => {
     rememberMergedOptions(componentId, options);
     native.mergeOptions(componentId, nativeOptions);
@@ -225,7 +225,8 @@ export function push(
         from?.stack ?? null,
         (from?.index ?? 0) + 1,
         from?.menu,
-        from?.layer
+        from?.layer,
+        layoutsOf(componentId)
       );
       return whenNativeScreensReady([node], () =>
         sendPush(commandId, componentId, node, prepares, wanted, goneOut).then((shownId) => {
@@ -363,7 +364,8 @@ export function setStackRoot(componentId: string, children: Layout[]): Promise<s
           from?.stack ?? null,
           index,
           from?.menu,
-          from?.layer
+          from?.layer,
+          layoutsOf(componentId)
         )
       );
       return whenNativeScreensReady(nodes, () =>
@@ -383,7 +385,17 @@ export function showInColumn(componentId: string, column: string, layout: Layout
       showScreensFrom(componentId, node);
       const from = placeOf(componentId);
       const at = columnPlace(componentId, column);
-      notePlaces(node, from?.container ?? 'root', at.stack, at.index, from?.menu, from?.layer);
+      // In the split view of the screen it comes from, and in the column's stack.
+      const within = at.stack ? [...layoutsOf(componentId), at.stack] : layoutsOf(componentId);
+      notePlaces(
+        node,
+        from?.container ?? 'root',
+        at.stack,
+        at.index,
+        from?.menu,
+        from?.layer,
+        within
+      );
       return whenNativeScreensReady([node], () =>
         inOrder(() =>
           sendShow(goneOut, () => native.showInColumn(commandId, componentId, column, node))
@@ -431,7 +443,7 @@ export function dismissModal(componentId: string, options?: Options): Promise<st
   dropReactRenderMeasures();
   const commandId = nextId('dismissModal');
   return inOrder(() =>
-    native.dismissModal(commandId, componentId, options && toNativeOptions(options))
+    native.dismissModal(commandId, componentId, options && toNativeOptions(options, componentId))
   );
 }
 

package/src/engine/layout.ts

@@ -122,7 +122,7 @@ function screen(component: LayoutComponent, inPair = false, keyed = !inPair): La
     type: 'Component',
     data: {
       name: rendersInSlot(name) ? slotName(id, name) : name,
-      options: toNativeOptions(options),
+      options: toNativeOptions(options, id),
       ...(key !== undefined && { key }),
     },
     children: [],
@@ -167,12 +167,13 @@ function arrangement(
 }
 
 function external(component: ExternalComponent): LayoutNode {
+  const id = component.id || nextId('ExternalComponent');
   return {
-    id: component.id || nextId('ExternalComponent'),
+    id,
     type: 'ExternalComponent',
     data: {
       name: String(component.name),
-      options: toNativeOptions(component.options),
+      options: toNativeOptions(component.options, id),
       passProps: component.passProps,
     },
     children: [],
@@ -185,10 +186,11 @@ function parent(
   options: Options | undefined,
   children: Layout[] = []
 ): LayoutNode {
+  const nodeId = id || nextId(type);
   return {
-    id: id || nextId(type),
+    id: nodeId,
     type,
-    data: { options: toNativeOptions(options) },
+    data: { options: toNativeOptions(options, nodeId) },
     children: children.map(toNativeLayout),
   };
 }
@@ -213,10 +215,11 @@ function sideMenu(menu: LayoutSideMenu): LayoutNode {
     data: {},
     children: [toNativeLayout(content)],
   });
+  const id = menu.id || nextId('SideMenuRoot');
   return {
-    id: menu.id || nextId('SideMenuRoot'),
+    id,
     type: 'SideMenuRoot',
-    data: { options: toNativeOptions(menu.options) },
+    data: { options: toNativeOptions(menu.options, id) },
     children: [
       ...(menu.left ? [side('SideMenuLeft', menu.left)] : []),
       side('SideMenuCenter', menu.center),
@@ -238,10 +241,14 @@ function splitView(split: LayoutSplitView): LayoutNode {
     ] as [string, Layout | undefined][]
   ).filter((column): column is [string, Layout] => column[1] !== undefined);
   const present = split.master && split.detail ? columns : [];
+  const id = split.id || nextId('SplitView');
   return {
-    id: split.id || nextId('SplitView'),
+    id,
     type: 'SplitView',
-    data: { options: toNativeOptions(split.options), columns: present.map(([column]) => column) },
+    data: {
+      options: toNativeOptions(split.options, id),
+      columns: present.map(([column]) => column),
+    },
     children: present.map(([, content]) => toNativeLayout(content)),
   };
 }

package/src/engine/options.ts

@@ -1,17 +1,27 @@
 import { DynamicColorIOS, Image, Platform, processColor } from 'react-native';
 import type { ColorValue, ImageSourcePropType } from 'react-native';
 import { nextId } from './ids';
-import { rememberButtonRoot, setProps } from './props';
+import { rememberButtonRoot, rememberOptionsComponent, 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.
+ * animations with `enter` and `exit`, `searchBar` and `interpolation` as objects. `owner` is the id of the node the
+ * options are for, or `'defaultOptions'`: a component without an id of its own gets one made of the owner, its place
+ * in the options and its name, the same for every `mergeOptions` of the node, so the native side keeps the mounted
+ * component and only its props change. Without an owner each conversion gives it a new one.
  */
-export function toNativeOptions<T>(options: T): T {
-  return convert(options) as T;
+export function toNativeOptions<T>(options: T, owner?: string): T {
+  return convert(options, undefined, { owner, path: '' }) as T;
+}
+
+// Where a value is in the options being converted: the node they are for, and the path to the value
+// (`topBar.rightButtons[0].component`).
+interface Place {
+  owner: string | undefined;
+  path: string;
 }
 
 /**
@@ -35,11 +45,16 @@ function isGroup(value: unknown): value is Fields {
   return isFields(value) && !Array.isArray(value);
 }
 
-function convert(value: unknown, key?: string): unknown {
+function convert(value: unknown, key: string | undefined, place: Place): 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));
+    // An item is known by its id where it has one (a button, a suggestion), so a component keeps its root when the
+    // list around it changes; by its place in the list otherwise.
+    const items = value.map((item, index) => {
+      const id = isFields(item) && typeof item.id === 'string' && item.id ? item.id : index;
+      return convert(item, undefined, { ...place, path: `${place.path}[${id}]` });
+    });
     if (key?.endsWith('Buttons') || key === 'buttons') items.forEach(noteButtonRoot);
     return key?.endsWith('Buttons') ? items.map(takeButtonProps) : items;
   }
@@ -47,9 +62,12 @@ function convert(value: unknown, key?: string): unknown {
   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);
+    const path = place.path ? `${place.path}.${name}` : name;
+    result[name] = name === 'passProps' ? item : convert(item, name, { ...place, path });
   }
-  return key === 'component' || key === 'resultsComponent' ? takeComponentProps(result) : result;
+  return key === 'component' || key === 'resultsComponent'
+    ? takeComponentProps(result, place)
+    : result;
 }
 
 function isColor(key: string): boolean {
@@ -105,13 +123,23 @@ 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');
+// A component in the options gets an id; the native side creates it with that id, and its props wait here. Without
+// an id of its own it is the owner's, the place of the component (`topBar.title`, `topBar.rightButtons[Save]` by the
+// button's id, `topBar.searchBar.resultsComponent`) and its name: another name there is another component.
+function takeComponentProps({ passProps, ...component }: Fields, place: Place): Fields {
+  const componentId = (component.id as string | undefined) || componentIdAt(place, component.name);
   if (passProps) setProps(componentId, passProps as object);
   return { ...component, componentId };
 }
 
+function componentIdAt({ owner, path }: Place, name: unknown): string {
+  if (owner === undefined) return nextId('CustomComponent');
+  const at = path.endsWith('.component') ? path.slice(0, -'.component'.length) : path;
+  const id = `${owner}/${at}/${String(name)}`;
+  rememberOptionsComponent(owner, id);
+  return id;
+}
+
 // 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 {

package/src/engine/places.ts

@@ -1,6 +1,7 @@
 import type { SplitViewColumnsStackedEvent } from '../interfaces/Events';
 import type { LayoutNode } from './layout';
 import { onNativeEvent } from './native';
+import { forgetProps } from './props';
 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
@@ -51,6 +52,11 @@ 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 layouts each screen shows in (its stack, pair, tabs, menu, split view, and the root of its layer), and how many
+// live screens each layout holds. A layout whose last screen went is gone, and with it the props of the components the
+// library named in its options: they stay as long as any of its screens may show them again.
+const layoutsOfScreen = new Map<string, readonly string[]>();
+const screensInLayout = new Map<string, number>();
 // 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;
@@ -69,9 +75,15 @@ export function isGone(screenId: string): boolean {
   return gone.has(screenId);
 }
 
+/** The layouts the screen shows in, outermost first: those whose screens come with it in a command go in it too. */
+export function layoutsOf(screenId: string): readonly string[] {
+  return layoutsOfScreen.get(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.
+ * its own; screens added to one, such as a push, take the layer of the screen they come from, and `within`, the
+ * layouts they show in (`layoutsOf` that screen).
  */
 export function notePlaces(
   node: LayoutNode,
@@ -79,12 +91,14 @@ export function notePlaces(
   stack: string | null = null,
   index = 0,
   menu?: ScreenPlace['menu'],
-  layer: string = container === 'root' ? 'root' : node.id
+  layer: string = container === 'root' ? 'root' : node.id,
+  within: readonly string[] = []
 ): void {
   if (node.type === 'Component' || node.type === 'ExternalComponent') {
     const name = node.data.name ?? '';
     gone.delete(node.id);
     columnOfScreen.delete(node.id);
+    noteLayouts(node.id, within);
     places.set(node.id, {
       name: screenNameOf(name),
       container,
@@ -99,7 +113,7 @@ export function notePlaces(
   } 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);
+      notePlaces(child, container, stack, index, menu, layer, [...within, node.id]);
       const place = places.get(child.id);
       if (place) {
         const placement = childIndex === 0 ? 'primary' : 'secondary';
@@ -109,7 +123,7 @@ export function notePlaces(
   } else if (node.type === 'Stack') {
     columnOfStack.delete(node.id);
     node.children.forEach((child, childIndex) =>
-      notePlaces(child, container, node.id, childIndex, menu, layer)
+      notePlaces(child, container, node.id, childIndex, menu, layer, [...within, node.id])
     );
   } 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
@@ -118,7 +132,7 @@ export function notePlaces(
     const columns = node.data.columns ?? [];
     const stacks: Partial<Record<string, string>> = {};
     node.children.forEach((child, childIndex) => {
-      notePlaces(child, container, null, 0, menu, layer);
+      notePlaces(child, container, null, 0, menu, layer, [...within, node.id]);
       const column = columns[childIndex];
       if (!column) return;
       if (child.type === 'Stack') stacks[column] = child.id;
@@ -128,12 +142,46 @@ export function notePlaces(
   } else if (node.type === 'SideMenuRoot') {
     for (const part of node.children) {
       const side = MENU_PARTS[part.type];
+      const parts = [...within, node.id, part.id];
       part.children.forEach((child) =>
-        notePlaces(child, container, null, 0, side ? { id: node.id, part: side } : menu, layer)
+        notePlaces(
+          child,
+          container,
+          null,
+          0,
+          side ? { id: node.id, part: side } : menu,
+          layer,
+          parts
+        )
       );
     }
   } else {
-    node.children.forEach((child) => notePlaces(child, container, null, 0, menu, layer));
+    node.children.forEach((child) =>
+      notePlaces(child, container, null, 0, menu, layer, [...within, node.id])
+    );
+  }
+}
+
+// A screen noted again under its id (a layout sent again) leaves the layouts it was in before.
+function noteLayouts(screenId: string, within: readonly string[]): void {
+  leaveLayouts(screenId);
+  const layouts = [...new Set(within)];
+  layoutsOfScreen.set(screenId, layouts);
+  for (const layout of layouts) screensInLayout.set(layout, (screensInLayout.get(layout) ?? 0) + 1);
+}
+
+function leaveLayouts(screenId: string): void {
+  const layouts = layoutsOfScreen.get(screenId);
+  if (!layouts) return;
+  layoutsOfScreen.delete(screenId);
+  for (const layout of layouts) {
+    const count = (screensInLayout.get(layout) ?? 1) - 1;
+    if (count > 0) {
+      screensInLayout.set(layout, count);
+      continue;
+    }
+    screensInLayout.delete(layout);
+    forgetProps(layout);
   }
 }
 
@@ -198,6 +246,7 @@ export function listenToSplitViews(): void {
 
 /** The screen is gone. */
 export function forgetPlace(screenId: string): void {
+  leaveLayouts(screenId);
   places.delete(screenId);
   columnOfScreen.delete(screenId);
   gone.add(screenId);

package/src/engine/props.ts

@@ -7,6 +7,11 @@ const watchers = new Map<string, Set<() => void>>();
 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>();
+// The ids the library gave components in options, by the node whose options they are in. Such an id stays the same
+// for every show of the node and may have several roots at once (a component of the default or a stack's options):
+// its props go with the node, not with a root.
+const optionComponents = new Map<string, Set<string>>();
+const optionComponentIds = new Set<string>();
 
 export function setProps(id: string, props: object | undefined): void {
   if (props === undefined) byId.delete(id);
@@ -38,8 +43,32 @@ 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. */
+/** Notes an id the library gave a component in the options of the node `owner`. */
+export function rememberOptionsComponent(owner: string, id: string): void {
+  let ids = optionComponents.get(owner);
+  if (!ids) optionComponents.set(owner, (ids = new Set()));
+  ids.add(id);
+  optionComponentIds.add(id);
+}
+
+/** Whether the library gave the id to a component in options: its props go with the node, not with a root. */
+export function isOptionsComponent(id: string): boolean {
+  return optionComponentIds.has(id);
+}
+
+/**
+ * The view is gone: its props, and whether it is a button's root, are not needed again; nor are those of the
+ * components the library named in its options.
+ */
 export function forgetProps(id: string): void {
   byId.delete(id);
   buttonRoots.delete(id);
+  const ids = optionComponents.get(id);
+  if (!ids) return;
+  optionComponents.delete(id);
+  for (const component of ids) {
+    byId.delete(component);
+    buttonRoots.delete(component);
+    optionComponentIds.delete(component);
+  }
 }

package/src/engine/rememberedOptions.ts

@@ -60,7 +60,10 @@ export function rootGoesOut(nodes: LayoutNode[], again: SentRoot | undefined): v
     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';
@@ -55,11 +55,12 @@ export type ScreenRootProps = { componentId: string } & Record<string, unknown>;
 const screens = new Map<string, EngineScreen>();
 const roots = new Map<string, ComponentType<{ componentId: string; rootTag?: number }>>();
 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>>();
 
 /** What runs when the root of a screen unmounts: the screen is gone. */
 export function onScreenUnmounted(listener: (screenId: string) => void): void {
@@ -214,17 +215,26 @@ export function screenRoot(
       );
       const props = useSyncExternalStore(watch, () => propsOf(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);

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;
 }
 

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. */
@@ -195,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;