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

package/src/interfaces/contract/errors.json

@@ -0,0 +1,275 @@
+{
+  "description": "Every text the native side rejects a command with, or logs for a command without a promise: one sentence per case, the values in single quotes, {name} for a parameter. scripts/contract.mjs makes ios/Contract/ANNErrorTexts.{h,mm} and android/.../react/ErrorTexts.kt from it; `platforms` limits a text to one platform.",
+  "groups": [
+    {
+      "title": "Where the screen is",
+      "texts": [
+        {
+          "name": "screenNotShown",
+          "params": ["componentId"],
+          "text": "the screen '{componentId}' is not shown"
+        },
+        {
+          "name": "notInStack",
+          "params": ["componentId"],
+          "text": "the screen '{componentId}' is not in a stack"
+        },
+        {
+          "name": "firstScreenOfStack",
+          "params": ["componentId"],
+          "text": "the screen '{componentId}' is the first screen of its stack"
+        },
+        {
+          "name": "notInThisStack",
+          "params": ["componentId"],
+          "text": "the screen '{componentId}' is not in this stack"
+        },
+        {
+          "name": "notInModal",
+          "params": ["componentId"],
+          "text": "the screen '{componentId}' is not in a modal"
+        },
+        {
+          "name": "notInOverlay",
+          "params": ["componentId"],
+          "text": "the screen '{componentId}' is not in an overlay"
+        },
+        {
+          "name": "notInSplitView",
+          "params": ["componentId"],
+          "text": "the screen '{componentId}' is not in a split view"
+        },
+        {
+          "name": "neitherSplitViewNorStack",
+          "params": ["componentId"],
+          "text": "the screen '{componentId}' is neither in a split view nor in a stack"
+        },
+        {
+          "name": "noSuchColumn",
+          "params": ["componentId", "column"],
+          "text": "the split view of the screen '{componentId}' has no '{column}' column"
+        },
+        {
+          "name": "columnIsStack",
+          "params": ["componentId", "column"],
+          "text": "the '{column}' column of the split view of the screen '{componentId}' is a stack: it takes a screen, not a stack"
+        },
+        {
+          "name": "columnNotStack",
+          "params": ["componentId", "column"],
+          "text": "the '{column}' column of the split view of the screen '{componentId}' is not a stack"
+        },
+        {
+          "name": "noScreensForStack",
+          "params": ["componentId"],
+          "text": "there are no screens to put in the stack of the screen '{componentId}'"
+        },
+        {
+          "name": "alreadyShown",
+          "params": ["componentId"],
+          "text": "the screen '{componentId}' shows already: an id goes to one screen"
+        }
+      ]
+    },
+    {
+      "title": "Root, modals, the app",
+      "texts": [
+        {
+          "name": "setRootReplaced",
+          "params": ["rootId"],
+          "text": "setRoot was replaced by a newer setRoot before the root '{rootId}' finished showing"
+        },
+        {
+          "name": "rootDestroyed",
+          "params": ["rootId"],
+          "text": "the root '{rootId}' was destroyed before it showed"
+        },
+        {
+          "name": "modalWithoutRoot",
+          "params": ["componentId"],
+          "text": "the modal '{componentId}' can't be dismissed: there is no root under it"
+        },
+        {
+          "name": "nowhereToShow",
+          "params": [],
+          "text": "the navigation has nowhere to show screens: the app has no activity or window"
+        }
+      ]
+    },
+    {
+      "title": "Native screens",
+      "texts": [
+        {
+          "name": "nativeScreenNotRegistered",
+          "params": ["name"],
+          "text": "no native screen is registered as '{name}'"
+        },
+        {
+          "name": "nativeScreenNotCreated",
+          "params": ["name"],
+          "text": "the native screen '{name}' could not be created: its creator returned nothing"
+        },
+        {
+          "name": "nativeCallReloaded",
+          "params": ["name", "componentId"],
+          "text": "JavaScript reloaded before the call '{name}' of the screen '{componentId}' was answered",
+          "doc": "The error of a call of a native screen whose JavaScript reloaded before it answered."
+        },
+        {
+          "name": "nativeCallNotRunning",
+          "params": ["name", "componentId"],
+          "text": "the navigation is not running: the call '{name}' of the screen '{componentId}' can't be answered",
+          "doc": "The error of a call of a native screen while no JavaScript can answer it."
+        }
+      ]
+    },
+    {
+      "title": "The layout",
+      "texts": [
+        {
+          "name": "unknownNodeType",
+          "params": ["type"],
+          "text": "the layout has a node of unknown type '{type}'"
+        },
+        {
+          "name": "nodeWithoutId",
+          "params": ["type"],
+          "text": "the layout has a node of type '{type}' without an id"
+        },
+        {
+          "name": "sideMenuChild",
+          "params": ["menuId", "type"],
+          "text": "the side menu '{menuId}' has a child of type '{type}': it takes SideMenuLeft, SideMenuCenter and SideMenuRight"
+        },
+        {
+          "name": "stackTakesScreens",
+          "params": ["stackId", "type"],
+          "text": "the stack '{stackId}' takes screens, not a '{type}'"
+        },
+        {
+          "name": "emptyStack",
+          "params": ["stackId"],
+          "text": "the stack '{stackId}' has no screens"
+        },
+        {
+          "name": "emptyTabs",
+          "params": ["tabsId"],
+          "text": "the tabs '{tabsId}' have no tabs"
+        },
+        {
+          "name": "tooManyTabs",
+          "params": [
+            "tabsId",
+            {
+              "name": "count",
+              "type": "int"
+            }
+          ],
+          "text": "the tabs '{tabsId}' have {count} tabs: Android shows at most 5",
+          "doc": "Only Android checks it: its tab bar shows at most 5 tabs."
+        },
+        {
+          "name": "splitViewColumns",
+          "params": ["splitViewId"],
+          "text": "the split view '{splitViewId}' needs its primary and its secondary column"
+        },
+        {
+          "name": "pairUnsupported",
+          "params": ["pairId"],
+          "text": "the pair '{pairId}' needs iOS 27.1 and an app built with its SDK",
+          "doc": "Only iOS checks it: Android has pairs on every version."
+        },
+        {
+          "name": "pairNeedsTwoScreens",
+          "params": ["pairId"],
+          "text": "the pair '{pairId}' needs two screens: its primary and its secondary"
+        },
+        {
+          "name": "nodeWithoutName",
+          "params": ["type", "nodeId"],
+          "text": "the layout has a node '{nodeId}' of type '{type}' without a name"
+        },
+        {
+          "name": "rootMissing",
+          "params": [],
+          "text": "the layout of setRoot has no root"
+        },
+        {
+          "name": "tabsInTabs",
+          "params": ["tabsId"],
+          "text": "the tabs '{tabsId}' have a tab of type 'BottomTabs': tabs don't go inside tabs"
+        },
+        {
+          "name": "sideMenuSides",
+          "params": ["menuId"],
+          "text": "the side menu '{menuId}' takes one SideMenuCenter and at most one SideMenuLeft and one SideMenuRight"
+        },
+        {
+          "name": "sideChildCount",
+          "params": ["sideId", "menuId"],
+          "text": "the side '{sideId}' of the side menu '{menuId}' needs exactly one child"
+        },
+        {
+          "name": "sideMenuInSide",
+          "params": ["menuId"],
+          "text": "the side menu '{menuId}' has a side menu in a side: a side menu doesn't go inside a side menu"
+        },
+        {
+          "name": "sideOutsideMenu",
+          "params": ["nodeId", "type"],
+          "text": "the layout has a node '{nodeId}' of type '{type}' outside a side menu"
+        },
+        {
+          "name": "splitViewInColumn",
+          "params": ["splitViewId"],
+          "text": "the split view '{splitViewId}' has a column of type 'SplitView': a split view doesn't go inside a split view"
+        },
+        {
+          "name": "idGivenTwice",
+          "params": ["nodeId"],
+          "text": "the layout gives the id '{nodeId}' to two nodes"
+        }
+      ]
+    },
+    {
+      "title": "Options, previews, any other failure",
+      "texts": [
+        {
+          "name": "unreadableOption",
+          "params": ["path", "componentId"],
+          "text": "the option '{path}' of the screen '{componentId}' has a value the navigation can't read"
+        },
+        {
+          "name": "unreadableDefaultOption",
+          "params": ["path"],
+          "text": "the option '{path}' of the default options has a value the navigation can't read",
+          "doc": "An unreadable value of `setDefaultOptions`: the default options belong to no screen."
+        },
+        {
+          "name": "previewGone",
+          "params": ["previewId"],
+          "text": "the preview '{previewId}' went without being opened"
+        },
+        {
+          "name": "couldNot",
+          "params": ["what", "reason"],
+          "text": "could not {what}: {reason}",
+          "doc": "Any other failure: what could not be done and why, `could not <what>: <reason>`."
+        },
+        {
+          "name": "notDoneYet",
+          "params": ["method"],
+          "text": "could not run '{method}': the native core doesn't do it yet",
+          "doc": "A command whose part of the native core is not written yet."
+        },
+        {
+          "name": "notAnswered",
+          "params": ["method"],
+          "text": "could not run '{method}': the native core let it go without an answer",
+          "doc": "A command that nothing in the native core answered: what took it let it go, or nothing took it.",
+          "platforms": ["ios"]
+        }
+      ]
+    }
+  ]
+}

package/src/interfaces/options/animations.ts

@@ -254,13 +254,16 @@ export type ElementAnimation = AppearingElementAnimation | DisappearingElementAn
 /**
  * An animation of one view of a screen that moves together with the transition, with or without a counterpart on the
  * other screen. The view is found by its `nativeID`, first on the screen that goes, then on the one that comes; one
- * that is not found is skipped while the rest plays. The transition waits until it is found. Without an animation of
- * the screens of its own, the screen that comes fades in (or the one that goes fades out) in 300 ms around the
- * elements. When the transition ends or is cancelled, the element gets its own values back. `x` and `y` are the
- * position in the parent of the element on both platforms. As on a side of a screen, don't set `x` with `translationX`
- * or `y` with `translationY` on one element: the translation plays and the position doesn't. (Android) A view whose
- * parent is a React view with `removeClippedSubviews` turned on, such as a child of a clipping list, is not moved: it
- * counts as not found.
+ * that is not found is skipped while the rest plays. The transition waits until it is found. An element that fails on
+ * the way (an error in its animation) is skipped too, with a warning in the log: it shows and hides with its screen,
+ * and the transition and its command go on. Without an animation of the screens of its own, the screen that comes fades
+ * in (or the one that goes fades out) in 300 ms around the elements. When the transition ends or is cancelled, the
+ * element gets its own values back. The element's own `transform` counts: a property that doesn't animate keeps the
+ * element's value, and a missing end is that value (a turn read from −180° to 180°, as React Native draws it). `x`
+ * and `y` are the position in the parent of the element on both platforms. As on a side of a screen, don't set `x`
+ * with `translationX` or `y` with `translationY` on one element: the translation plays and the position doesn't.
+ * The element plays where it is, in its screen: it moves with its screen, its parents clip it, and the views drawn
+ * after it in its screen stay over it.
  */
 export interface ElementTransition {
   /** The `nativeID` of the view to animate. */
@@ -288,12 +291,23 @@ export interface ElementTransition {
 }
 
 /**
- * A view that flies from the screen that goes to the screen that comes, changing its place, size, corners and look
- * on the way. A pair whose view is not found on either screen is skipped while the rest plays, and the transition
- * waits until the views are found. Without an animation of the screens of its own, the screen that comes fades in (or
- * the one that goes fades out) in 300 ms around the pair. Text keeps its proportions and changes its picture within a
- * quarter of the flight. (Android) A picture that doesn't load within a second drops out of the transition, and so does
- * a pair with a view whose parent is a React view with `removeClippedSubviews` turned on: it counts as not found.
+ * A view that flies from the screen that goes to the screen that comes, changing its place, size, corners and look on
+ * the way. A pair whose view is not found on either screen is skipped while the rest plays, and the transition waits
+ * until the views are found. A pair that fails on the way (an error in its start or its flight) is skipped too, with a
+ * warning in the log: its views show and hide with their screens, and the transition and its command go on. So is a
+ * pair with a view without a size, or one whose picture can't be taken. Without an animation of the screens of its
+ * own, the screen that comes fades in (or the one that goes fades out) in 300 ms around the pair. What flies is a copy:
+ * pictures of the two views taken as the transition starts, while the views stay hidden in their places; what changes
+ * in them meanwhile shows when they are back. A view its parents cut (`overflow: hidden`, a scroll view, the edge of
+ * its screen) shows only the part they leave visible, and that part goes to the one of the other view on the way.
+ * Text keeps its proportions, flies whole and changes its picture within a quarter of the flight. A view turned or
+ * scaled by its own `transform` or by a parent's flies from where it shows, and its angle goes to the other view's
+ * along the shorter arc. The angle is the one React Native draws, from −180° to 180°:
+ * `rotate: '270deg'` turns back a quarter, and no pair spins a full turn. (Android) An image without a background or a
+ * border flies as the image of the view that comes, from the part and place the fit (`resizeMode`) shows in one view
+ * to those in the other, and an animated image plays on; images of other proportions fly as pictures. An image that
+ * doesn't load within a second drops out of the transition. A skew and a tilt (`skewX`, `rotateX`, …) don't fly: the
+ * view flies without them and has them again at the end.
  */
 export interface SharedElementTransition {
   /** The `nativeID` of the view on the screen that goes. */
@@ -350,22 +364,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>;
   /**
@@ -395,6 +415,33 @@ export interface StackPushAnimationOptions extends StackAnimationOptions {
   zoom?: ZoomTransitionOptions;
 }
 
+/**
+ * The animation of a pop, read from the screen that goes. As {@link StackAnimationOptions}, with the swipe back of iOS
+ * and the preview of the back gesture on Android.
+ */
+export interface StackPopAnimationOptions extends StackAnimationOptions {
+  /**
+   * (iOS) Whether the swipe back plays this pop under the finger. Without it, the swipe back plays UIKit's slide, and
+   * the pop's own animation plays only for the back button and `pop`. With `true`, the swipe from the edge plays the
+   * pop's own animation as far as the finger has gone across the screen: the user can stop halfway, and letting go
+   * finishes the pop or puts the screen back, the rest playing faster after a quick flick. It applies only when the pop
+   * has an animation of its own (`content`, `elementTransitions`, `sharedElementTransitions`). The top bar shows the
+   * screen under from the start of the swipe, as UIKit does in a transition of its own, and comes back when the swipe
+   * is given up. On iOS 26 the swipe from the content stays off for a screen with an own pop.
+   * Android ignores it: a pop with an animation of its own plays when the back gesture ends.
+   * @default false
+   */
+  interactive?: boolean;
+  /**
+   * (Android 14+) Whether the back gesture on a pushed screen previews its pop as the user swipes: the screen shrinks
+   * and follows the finger, the screen under it shows behind. `false` pops the screen when the gesture is released,
+   * as on Android 13 and older; back still pops it. iOS ignores it: its swipe back is UIKit's, or the pop's own
+   * animation with `interactive`.
+   * @default true
+   */
+  preview?: boolean;
+}
+
 /**
  * The animation of `setStackRoot`, read from the new top screen. As {@link StackAnimationOptions}: without an animation
  * of its own, iOS plays the push animation of the new top screen or UIKit's transition, and Android plays a fade
@@ -416,8 +463,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.
@@ -443,6 +492,12 @@ export interface ModalAnimationOptions extends EnterExitAnimationOptions {
  * options of the command. A change by `mergeOptions` is for the next command and animates nothing itself. A theme
  * switch or a rotation does not change an animation. Without a key, the transition is the platform's own.
  *
+ * The system's setting to reduce motion is respected, with no option to turn that off. (iOS) With Reduce Motion on, a
+ * transition of these keys is a fade of the same length: the screen that comes fades in (a push, `setStackRoot`, a
+ * modal's show, `setRoot`), the screen that goes fades out (a pop, a dismissal); no element moves. (Android) With
+ * Remove animations on (or the animator duration scale at 0), the transitions end at once, no element moves and none
+ * is waited for, a side menu opens and closes without its slide, and a sheet shows and closes without it.
+ *
  * ```ts
  * const options: Options = {
  *   animations: {
@@ -456,8 +511,12 @@ export interface ModalAnimationOptions extends EnterExitAnimationOptions {
 export interface AnimationOptions {
   /** The push of a screen, read from the screen that comes. */
   push?: StackPushAnimationOptions;
-  /** The pop of a screen, also `popTo` and `popToRoot`, read from the screen that goes. A swipe back is always the system's. */
-  pop?: StackAnimationOptions;
+  /**
+   * The pop of a screen, also `popTo` and `popToRoot`, read from the screen that goes. The swipe back of iOS is
+   * UIKit's, or the pop's own animation under the finger (`interactive`); the back gesture of Android previews the pop
+   * (`preview`).
+   */
+  pop?: StackPopAnimationOptions;
   /** The replacing of the screens of a stack, read from the new top screen. */
   setStackRoot?: SetStackRootAnimationOptions;
   /**

package/src/interfaces/options/bottomTabs.ts

@@ -73,8 +73,10 @@ export interface OptionsBottomTabsAccessoryComponent {
 /**
  * (iOS 26+) The accessory above the tab bar, like the mini player of a music app. The system sizes it (48 points high)
  * and the component fills that size. It is placed above the bar, or beside the bar when the bar is minimized; on an
- * iPad with the bar at the top it sits at the bottom over the full width, always above the bar. The accessory stops
- * together with the tabs. Android has no accessory.
+ * iPad with the bar at the top it sits at the bottom over the full width, always above the bar. A hidden accessory
+ * (`visible: false`, or no name) keeps its React root and its state, and shows again with them. When another accessory
+ * (another `componentId`) shows, the replaced one stops once it has left the window and its state is gone. The last
+ * accessory stops together with the tabs. Android has no accessory.
  */
 export interface OptionsBottomTabsAccessory {
   /**
@@ -155,6 +157,16 @@ export interface OptionsBottomTabs {
    * @default true
    */
   animate?: boolean;
+  /**
+   * How the content changes when another tab is selected on screen, by a press, by back or from code. `'platform'`
+   * does what the platform does: on Android the tab that goes fades out and the new one fades in and grows (Material's
+   * fade through, 300 ms), on iOS the content changes at once. `'none'` changes it at once on both platforms. The
+   * appear events of a switch and `ANN.BottomTabSelected` come at its end, so with `'none'` right away. The tab that is
+   * selected decides: the value of the screen it shows, over its own, the tabs' and the default options. A
+   * `mergeOptions` applies from the next switch. Off screen the content always changes at once.
+   * @default 'platform'
+   */
+  switchAnimation?: 'platform' | 'none';
   /**
    * The tab to select, as an index from 0. It selects once, when the options arrive, at creation (the first tab to
    * show) or in `mergeOptions`; it is not kept. An index out of range selects nothing (or the first tab at creation)
@@ -187,9 +199,10 @@ export interface OptionsBottomTabs {
    */
   drawBehind?: boolean;
   /**
-   * The background color of the bar; `null` gives the default one. On Android the default is the surface color of the
-   * Material 3 theme. Before iOS 26 (and with `UIDesignRequiresCompatibility`) the bar is opaque with the color, or
-   * system opaque without it, and a transparent color makes it transparent. On iOS 26 with glass the color is ignored
+   * The background color of the bar; `null` gives the default one. On Android the default is the surface container color
+   * (`colorSurfaceContainer`) of the Material 3 theme. Before iOS 26, and in the compatibility mode (`UIDesignRequiresCompatibility` in Info.plist: iOS 26, and iOS 27
+   * only for an app built with an SDK before iOS 27), the bar is opaque with the color, or system opaque without it,
+   * and a transparent color makes it transparent. On iOS 26 and later with glass the color is ignored
    * with one warning, since the system has no color for glass, while a transparent color gives a transparent bar. The
    * theme color `bar` is its default option.
    */
@@ -198,7 +211,8 @@ export interface OptionsBottomTabs {
    * When the screens of the tabs are created: `'together'` creates and draws every tab at the start, and the tabs are
    * ready when all of them are; `'afterInitialTab'` creates the selected tab first and the others right after it;
    * `'onSwitchToTab'` creates a tab the first time it is selected. The screens of tabs not yet selected get no appear
-   * events in any mode. It applies when the tabs are created; `mergeOptions` does not change it.
+   * events in any mode. On iOS a text input's `autoFocus` in a tab drawn before it is selected does nothing: focus it in
+   * `useScreenAppear`. It applies when the tabs are created; `mergeOptions` does not change it.
    * @default 'together'
    */
   tabsAttachMode?: 'together' | 'afterInitialTab' | 'onSwitchToTab';
@@ -396,7 +410,7 @@ export interface OptionsBottomTab {
   selectedFontSize?: number;
   /**
    * (iOS) The insets of the icon. Each side is independent. They apply before iOS 26 only; iOS 26 and the compatibility
-   * mode ignore them, and so does a system role before iOS 18.
+   * mode (see `backgroundColor`) ignore them, and so does a system role before iOS 18.
    */
   iconInsets?: IconInsets;
   /**

package/src/interfaces/options/buttons.ts

@@ -60,7 +60,7 @@ export interface IconInsets {
  * a color the other fields are ignored.
  *
  * On iOS the icon is drawn onto the shape and the button becomes a button of its own (the back button keeps its
- * history menu), without the glass capsule on iOS 26 by default. On Android the icon sits on the shape, mirrored in a
+ * history menu), without the glass capsule (glass design, iOS 26+) by default. On Android the icon sits on the shape, mirrored in a
  * right-to-left layout. Layers merge differently: on iOS an object merges field by field like any other, on Android
  * an `iconBackground` that has a `color` replaces the earlier one as a whole.
  */
@@ -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. */
@@ -157,7 +159,7 @@ export interface OptionsTopBarButtonMenu {
  * A button of the top bar (`leftButtons`, `rightButtons`, `centerButtons`) or of the toolbar (`toolbar.buttons`). The
  * kinds are picked by the fields that are set. On iOS, the first that fits wins: a `component`, then an icon with text
  * and `showText`, then an icon with `iconBackground` or `iconInsets`, then an SF Symbol, an image `icon`, a `text`,
- * a `systemItem`; a button with none of them is not shown. On Android a button is a menu item of the bar: text, icon
+ * a `systemItem`; a button with none of them is not shown. On Android a button is a button of the bar's row: text, icon
  * or a component. Lists of buttons are replaced as a whole and take nothing from the lists of lower layers.
  *
  * Text, icon, color and similar fields are the same in all four places; where a place or a side differs, the field
@@ -187,7 +189,7 @@ export interface OptionsTopBarButton {
    */
   icon?: ImageResource;
   /**
-   * (iOS) The space around the image of `icon`; the button becomes a button of its own, without a capsule on iOS 26.
+   * (iOS) The space around the image of `icon`; the button becomes a button of its own, without a capsule with the glass design (iOS 26+, see `UIDesignRequiresCompatibility`).
    */
   iconInsets?: IconInsets;
   /**
@@ -202,7 +204,7 @@ export interface OptionsTopBarButton {
   systemItem?: SystemItemIcon;
   /**
    * The text of the button. A button with an icon keeps it as a label for the overflow menu, the customization panel
-   * and VoiceOver (iOS) or as the text of the menu item (Android, where it also shows when there is room).
+   * and VoiceOver (iOS), or for TalkBack, the tooltip of a long press and the overflow menu (Android).
    */
   text?: string;
   /** The text a screen reader says for the button. */
@@ -236,14 +238,14 @@ export interface OptionsTopBarButton {
   disabledColor?: Color;
   /**
    * A shape behind the icon. It works with an `icon` image and a `color` of the shape; on iOS the button becomes a
-   * button of its own without menu, toggle or style, and without a capsule on iOS 26 by default. The color of a whole
+   * button of its own without menu, toggle or style, and without a capsule with the glass design by default. The color of a whole
    * side is `leftButtonBackgroundColor` / `rightButtonBackgroundColor`.
    */
   iconBackground?: IconBackgroundOptions;
   /**
-   * (iOS) `'plain'` or `'prominent'`, the main action of the bar (Done, Send). On iOS 26 a prominent button is a
+   * (iOS) `'plain'` or `'prominent'`, the main action of the bar (Done, Send). With the glass design (iOS 26+, see `UIDesignRequiresCompatibility`) a prominent button is a
    * capsule in the button's tint with bold text or icon on it (the tint is `color`, the bar's tint without it);
-   * before iOS 26 it is the system's done style with bold text. Not for component buttons, buttons with
+   * without it, it is the system's done style with bold text. Not for component buttons, buttons with
    * `iconBackground`, and `showText` buttons.
    * @default 'plain'
    */
@@ -255,7 +257,7 @@ export interface OptionsTopBarButton {
    */
   testID?: string;
   /**
-   * (iOS 26+) Whether the button has no glass capsule under it; neighbors keep theirs. By default `true` for
+   * (iOS 26+, glass design) Whether the button has no glass capsule under it; neighbors keep theirs. By default `true` for
    * component buttons and for icon buttons with a background or insets, `false` for the rest. In a `group` of several
    * buttons the capsule is shared and this has no effect. A change by `mergeOptions` builds the buttons anew.
    */
@@ -268,8 +270,8 @@ export interface OptionsTopBarButton {
    */
   showText?: boolean;
   /**
-   * (iOS 26+) Buttons next to each other with the same group share one capsule; a button without a group has its
-   * own. Before iOS 26 it does nothing, on iOS 15 there are no groups. A side that has a group of several buttons
+   * (iOS 26+, glass design) Buttons next to each other with the same group share one capsule; a button without a group has its
+   * own. Without the glass design it does nothing, on iOS 15 there are no groups. A side that has a group of several buttons
    * doesn't animate button changes. The toolbar has no groups: only icons share a capsule there. For center buttons
    * the group is a section of the overflow menu, and its name is the id the customization is saved under.
    */
@@ -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;