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

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;

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
+    }
+  ]
+}

package/src/interfaces/options/animations.ts

@@ -354,22 +354,28 @@ export interface StackAnimationOptions {
   enabled?: boolean;
   /**
    * Whether to wait for the new top screen to be drawn before the transition. Without it, the transition waits for the
-   * content of a screen with an animation of its own for half a second at most, `true` waits as long as it takes,
-   * `false` starts at once, also with an animation of its own.
+   * first mount of the new top's content, half a second at most, with the platform's transition as with an animation
+   * of its own; on a push the options the screen sets as it renders for the first time (`useScreenOptions`, such as
+   * its title) are in its bar from the first frame. `true` waits as long as it takes, `false` starts at once, the
+   * content drawing as it comes ((Android) a push with `appProvider` still renders the screen first). (iOS) The
+   * components of the bar are waited for too, each to its own limit.
    */
   waitForRender?: boolean;
   /**
    * The animation of the screens: `enter` for the screen that comes (on a pop, the one that was below), `exit` for the
    * one that goes. A property with a `from` or a `to` makes it an animation of its own, which replaces the platform's
-   * transition; the side left out stays still. (Android) With one of its own, the title and buttons of the bar and the
-   * tab bar don't travel with the screens. (Android) When the transition has elements, a push plays only `enter` and a
+   * transition; the side left out stays still. With one of its own, (Android) the top bar goes with its screen: the
+   * bar of the screen that goes leaves with it, and the bar of the screen that comes moves, scales and fades with it;
+   * (iOS) UIKit keeps the bar in place and changes its title and buttons at once. (Android) The tab bar doesn't travel
+   * with the screens. (Android) When the transition has elements, a push plays only `enter` and a
    * pop only `exit`, and only when that side is a single `alpha`; any other side is not played, and the screen fades in
    * or out in 300 ms around the elements instead. iOS plays the sides as they are set.
    */
   content?: EnterExitAnimationOptions;
   /**
    * (Android) The animation of the top bar when it shows or hides because the screens differ in `topBar.visible`.
-   * Without it, the bar slides up by its height and back in 300 ms. iOS animates the bar with UIKit.
+   * Without it, the bar slides up by its height and back in 300 ms; with a `content` of its own it shows or hides
+   * with its screen. iOS animates the bar with UIKit.
    */
   topBar?: EnterExitAnimationOptions<TopBarAnimationOptions>;
   /**
@@ -420,8 +426,10 @@ export interface SetStackRootAnimationOptions extends StackAnimationOptions {
  * screen under it. The screen under a modal takes part (iOS) only under a modal that covers the full screen.
  *
  * A sheet keeps the system's sheet motion on both platforms: (iOS) a modal shown as `'pageSheet'`, `'formSheet'` or
- * without a style, (Android) a Material bottom sheet. The sides `enter` and `exit` and the lists of elements set here
- * don't apply to it.
+ * without a style, (Android) the Material bottom sheet of `'pageSheet'`, `'formSheet'`, `'popover'`, or of
+ * `modal.sheet` without a style. The sides `enter` and `exit` and the lists of elements set here don't apply to it.
+ * Without them a modal over the whole screen comes up from the bottom: on iOS by UIKit's `modalTransitionStyle`, on
+ * Android with the system's motion of a window over another, 300 ms up and 250 ms down, without a fade.
  *
  * (Android) When the modal has elements, `enter` of a show and `exit` of a dismiss play only when that side is a single
  * `alpha`; any other side is not played, and the modal fades in or out in 300 ms around the elements instead.

package/src/interfaces/options/buttons.ts

@@ -138,8 +138,10 @@ export type OptionsTopBarButtonMenuElement =
 /**
  * A menu of the top bar: the menu of a button, the overflow menu, the menu of the title. A list of `items` sent with
  * `mergeOptions` replaces the earlier list as a whole, and `items: []` removes the menu; `title` and
- * `singleSelection` merge field by field (iOS). What the user picks in a `singleSelection` menu is written back into
- * the options of the screen and survives the screen showing again.
+ * `singleSelection` merge field by field (iOS). What the user picks in a `singleSelection` menu stays with the screen,
+ * through it showing again, a `mergeOptions` that sends the same items again and `setDefaultOptions`; a `mergeOptions`
+ * into the screen that changes the checks of that menu's level, or takes the item away, replaces it. A merge into the
+ * stack or the tabs around the screen doesn't.
  */
 export interface OptionsTopBarButtonMenu {
   /** The title above the items. (iOS) Android doesn't show it. */
@@ -285,8 +287,10 @@ export interface OptionsTopBarButton {
   badgeTextColor?: Color;
   /**
    * (iOS) Whether the button is a toggle: every press flips `selected` and sends a press with the new state. The state
-   * is written into the options of the screen under the button's id, so it survives the screen showing again, and a
-   * button set again without `selected` takes the state of the button with the same id. Not for component buttons,
+   * stays with the screen under the button's id, through it showing again, a `mergeOptions` that sends the same
+   * buttons again and `setDefaultOptions`; a `mergeOptions` into the screen that changes `selected` replaces it (a merge
+   * into the stack around it doesn't). A button set again
+   * without `selected` takes the state of the button with the same id. Not for component buttons,
    * buttons with `iconBackground`, and `showText` buttons.
    */
   toggle?: boolean;
@@ -351,7 +355,11 @@ export interface OptionsTopBarButton {
  * replaces it.
  */
 export interface OptionsTopBarButtonComponent {
-  /** The id of the component. Without it, the library gives one. The same `name` and `id` mean the same component. */
+  /**
+   * The id of the component. Without it, the library gives one made of the screen, the component's place in the
+   * options and its `name`: it stays the same for every `mergeOptions` of the screen, so the mounted component stays
+   * and only its props change. The same `name` and `id` mean the same component.
+   */
   id?: string;
   /** The name of the registered component. */
   name: string;

package/src/interfaces/options/modals.ts

@@ -3,21 +3,25 @@
  * `'overCurrentContext'`, `'currentContext'` or `'popover'`. It is read once, when the modal shows, from the modal's
  * final options; `mergeOptions` afterwards doesn't change it, and neither does a change of theme or a rotation. Without
  * it the platform decides: on iOS the automatic style of UIKit (a sheet on iPhone, a card on iPad), on Android the
- * whole screen. An unknown string shows a full-screen modal on iOS and counts as not set on Android.
+ * whole screen, or the Material bottom sheet when `modal.sheet` is set. An unknown string shows a full-screen modal on
+ * iOS and counts as not set on Android.
  *
- * - `'pageSheet'`: (iOS) a sheet that leaves the screen below visible and pushed back; on iPad a wide card. Android
- *   shows the whole screen, or the Material bottom sheet when `modal.sheet` is set.
- * - `'formSheet'`: (iOS) a sheet on iPhone, a card in the middle on iPad whose size is `modal.contentSize`. Android
- *   shows the whole screen, or the bottom sheet when `modal.sheet` is set.
- * - `'fullScreen'`, `'currentContext'`: the whole screen; the screen below is taken off. Both platforms treat the two
- *   alike.
- * - `'overFullScreen'`, `'overCurrentContext'`: the whole screen with the screen below kept in place. It shows
- *   through only where the modal screen is transparent (`layout.backgroundColor` and `layout.componentBackgroundColor`
- *   both `'transparent'`); the style does not make anything transparent by itself.
+ * - `'pageSheet'`: a sheet that leaves the screen below visible. On iOS the screen below is pushed back, and on iPad
+ *   the sheet is a wide card. On Android it is the Material modal bottom sheet over a dimmed screen, at the full height
+ *   under the status bar (`modal.sheet` changes its stops), at most 640 dp wide and in the middle of a wider window.
+ * - `'formSheet'`: on iOS a sheet on iPhone, a card in the middle on iPad whose size is `modal.contentSize`. On Android
+ *   the same bottom sheet as `'pageSheet'`; `modal.contentSize` does nothing there.
+ * - `'fullScreen'`, `'currentContext'`: the whole screen; the screen below is taken off once the modal has come in.
+ *   Both platforms treat the two alike. The modal comes up from the bottom: on Android with the system's motion of a
+ *   window over another (300 ms up, 250 ms down), without a fade.
+ * - `'overFullScreen'`, `'overCurrentContext'`: the same, with the screen below kept in place under the modal. It
+ *   shows through only where the modal screen is transparent (`layout.backgroundColor` and
+ *   `layout.componentBackgroundColor` both `'transparent'`); the style does not make anything transparent by itself.
  * - `'popover'`: (iOS) a popover with an arrow on iPad, a sheet on iPhone unless `modal.popover.adaptive` is `false`.
- *   Android has no popovers and shows the whole screen.
+ *   Android has no popovers and shows the bottom sheet of `'pageSheet'`.
  *
- * The options of the sheet (`modal.sheet`) apply with `'pageSheet'`, `'formSheet'` and without a style.
+ * The options of the sheet (`modal.sheet`) apply with `'pageSheet'`, `'formSheet'` and without a style, and on
+ * Android with `'popover'` too.
  */
 export type OptionsModalPresentationStyle =
   | 'pageSheet'
@@ -55,7 +59,8 @@ export type OptionsModalSheetDetent = 'medium' | 'large' | 'content' | number;
 /**
  * The settings of a sheet: a modal that comes from below and rests on one of several heights, its stops (detents). On
  * iOS they configure the system sheet of a modal presented as `'pageSheet'`, `'formSheet'` or without a style. On
- * Android any one of them turns the modal into a Material bottom sheet, again for those styles only. They are read when
+ * Android they configure the Material bottom sheet of `'pageSheet'`, `'formSheet'` and `'popover'`, and without a style
+ * any one of them turns the modal into that sheet. They are read when
  * the modal shows, and a `mergeOptions` on any screen of the modal changes them while it is shown, with an animation.
  * Objects merge key by key; `detents` is replaced as a whole.
  */

package/src/interfaces/options/system.ts

@@ -46,8 +46,9 @@ export interface OptionsLayout {
    * The color of the screen, also under its React content. On iOS it is the background of the screen's view (the
    * system background without it); stacks, tabs and side menus paint their view with the color of the screen that
    * shows, seen behind transparent bars and around screens during transitions. On Android it fills the screen and
-   * its containers but leaves room at the top for the status bar while it shows. `null` makes the background
-   * transparent. Without it, Android shows the window's background (the app theme).
+   * its containers but leaves room at the top for the status bar while it shows; without it a React screen takes
+   * `android:colorBackground` of the app's theme (in a sheet it shows the sheet's surface, and a native screen paints
+   * its own view), so the screen below never shows through. `null` makes the background transparent.
    */
   backgroundColor?: Color;
   /**
@@ -152,7 +153,9 @@ export interface OptionsStatusBar {
    * and buttons sits below the bar), and a screen without a top bar starts below the bar. `true` lets a screen without
    * a top bar start at the top of the window, with its safe area keeping content below. `false` starts the top bar
    * below the status bar, which keeps its own color. A sheet modal has no status bar above it, so this does not apply
-   * there. On iOS the screen is always under the status bar and the safe area keeps the content below.
+   * there. An overlay covers the whole window, so its screens go under the status bar without it (a dimmed backdrop
+   * dims the status bar too), and `false`, in its options or in the default options, starts them below. On iOS the
+   * screen is always under the status bar and the safe area keeps the content below.
    */
   drawBehind?: boolean;
   /**

package/src/interfaces/options/topBar.ts

@@ -11,7 +11,11 @@ import type { Color, FontFamily, FontStyle, FontWeight, ImageResource } from './
  * `name` replaces it.
  */
 export interface OptionsTopBarTitleComponent {
-  /** The id of the component. Without it, the library gives one. The same `name` and `id` mean the same component. */
+  /**
+   * The id of the component. Without it, the library gives one made of the screen, the component's place in the
+   * options and its `name`: it stays the same for every `mergeOptions` of the screen, so the mounted component stays
+   * and only its props change. The same `name` and `id` mean the same component.
+   */
   id?: string;
   /** The name of the registered component. */
   name: string;
@@ -276,7 +280,11 @@ export interface OptionsTopBarBackground {
 
 /** The React component that is the background of the bar. */
 export interface OptionsTopBarBackgroundComponent {
-  /** The id of the component. Without it, the library gives one. The same `name` and `id` mean the same component. */
+  /**
+   * The id of the component. Without it, the library gives one made of the screen, the component's place in the
+   * options and its `name`: it stays the same for every `mergeOptions` of the screen, so the mounted component stays
+   * and only its props change. The same `name` and `id` mean the same component.
+   */
   id?: string;
   /** The name of the registered component. */
   name: string;
@@ -432,7 +440,11 @@ export interface OptionsSearchBarSuggestion {
  * component; a different `id` or `name` replaces the component, and so the search.
  */
 export interface OptionsSearchBarResultsComponent {
-  /** The id of the component. Without it, the library gives one. The same `name` and `id` mean the same component. */
+  /**
+   * The id of the component. Without it, the library gives one made of the screen, the component's place in the
+   * options and its `name`: it stays the same for every `mergeOptions` of the screen, so the mounted component stays
+   * and only its props change. The same `name` and `id` mean the same component.
+   */
   id?: string;
   /** The name of the registered component. */
   name: string;
@@ -518,8 +530,9 @@ export interface OptionsSearchBar {
    */
   scopes?: OptionsSearchBarScope[];
   /**
-   * The id of the selected scope; without it, or with an unknown id, the first. The user's pick is written into the
-   * options of the screen and stays after coming back. `mergeOptions` switches the scope without an event.
+   * The id of the selected scope; without it, or with an unknown id, the first. The user's pick stays with the screen,
+   * after coming back, through a `mergeOptions` that sends the same value again and `setDefaultOptions`. A
+   * `mergeOptions` into the screen with another value switches the scope without an event.
    */
   selectedScope?: string;
   /**
@@ -531,15 +544,15 @@ export interface OptionsSearchBar {
   scopeBarActivation?: 'automatic' | 'onTextEntry' | 'onSearchActivation';
   /**
    * (iOS) Tokens in front of the text of the field. The search events carry the ids of the tokens in the field as
-   * `tokens`; deleting a token sends a search-updated event, and the deleted tokens (and ones brought back with Undo)
-   * are written to the options of the screen. Closing the search clears the field and its tokens. An empty list removes
+   * `tokens`; deleting a token sends a search-updated event, and what the user deleted (or brought back with Undo)
+   * stays with the screen until a `mergeOptions` gives other tokens. Closing the search clears the field and its tokens. An empty list removes
    * them all.
    */
   tokens?: OptionsSearchBarToken[];
   /**
    * (iOS 16+, Android) The suggestions shown while searching. Picking one sends a suggestion-picked event with its id
-   * to the screen; the text stays and the list goes. They also go when the user types on, and new ones come with
-   * `mergeOptions`, usually on a search-updated event. An empty list removes them.
+   * to the screen; the text stays and the list goes. They also go when the user types on; the list a `mergeOptions`
+   * gives shows again, the same one too, usually on a search-updated event. An empty list removes them.
    */
   suggestions?: OptionsSearchBarSuggestion[];
   /**