@apexnative/navigation 1.0.0-alpha.1 → 1.0.0-alpha.11

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;

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'
@@ -32,9 +36,11 @@ export type OptionsModalPresentationStyle =
  * (iOS) The system transition a modal comes and goes with: `'coverVertical'` (from below), `'crossDissolve'` (a fade),
  * `'flipHorizontal'` (a flip) or `'partialCurl'`. It is read when the modal shows and doesn't change afterwards;
  * `animations.showModal` with values of its own, and the zoom of iOS 18, go over it. UIKit flips only a modal over the
- * whole screen (`'fullScreen'`, `'overFullScreen'`): a sheet comes in as usual and flips only on its way out, and
- * `'partialCurl'` is accepted by UIKit only for a full-screen modal. An unknown string means `'coverVertical'`. Android
- * doesn't read it.
+ * whole screen (`'fullScreen'`, `'overFullScreen'`): a sheet comes in as usual and flips only on its way out. UIKit
+ * curls only a `'fullScreen'` modal over a screen that fills the window, so `'partialCurl'` with any other
+ * `modalPresentationStyle` (or without one), or over a modal that doesn't fill the screen, shows as `'coverVertical'`.
+ * A modal shown with `'partialCurl'` can't show another modal over it: that `showModal` rejects. An unknown string
+ * means `'coverVertical'`. Android doesn't read it.
  */
 export type OptionsModalTransitionStyle =
   'coverVertical' | 'crossDissolve' | 'flipHorizontal' | 'partialCurl';
@@ -45,32 +51,34 @@ export type OptionsModalTransitionStyle =
  *
  * On iOS `'medium'` and `'large'` are the system stops; a number and `'content'` need iOS 16 and are left out below it
  * with a warning in the log. On Android `'medium'` is half of the window, `'large'` the full height under the status
- * bar, a number is capped at `'large'`, and `'content'` stands in as `'medium'` because the Material sheet has no
- * height by content.
+ * bar, a number is capped at `'large'`, and `'content'` is the height of the content, measured as on iOS.
  */
 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.
  */
 export interface OptionsModalSheet {
   /**
-   * The stops the sheet can rest on, and the user drags it between. On Android they are sorted by height and repeats
-   * dropped; the Material sheet has three resting places at most: the lowest stop of the list, the highest, and
-   * `'medium'` between them when the list has both `'medium'` and `'large'`. A stop without a place is dropped. On iOS
-   * the stops are handed to UIKit in the order given, which wants them from the lowest to the highest; a list left
-   * empty by unsupported values gives `['large']`.
+   * The stops the sheet can rest on, and the user drags it between, in any order: on both platforms they are sorted by
+   * height and repeats dropped. On iOS `'medium'` counts as half of `'large'` there, and on both `'content'` takes its
+   * place by the height of the content, again whenever that changes; on iOS a list left empty by unsupported values
+   * gives `['large']`. On Android the Material sheet has three resting places at most: the lowest stop of the list, the
+   * highest, and one between them, `selectedDetent` when it stands there, else the lowest of the others; the rest are
+   * dropped. Stops of the same height there are one.
    * @default ['large']
    */
   detents?: OptionsModalSheetDetent[];
   /**
-   * The stop the sheet opens on; a new value in `mergeOptions` moves the sheet there with an animation, and doesn't
-   * send `sheetDetentChanged`. A value that isn't among `detents` opens on the lowest stop on iOS and is ignored on
-   * Android.
+   * The stop the sheet opens on; a `mergeOptions` that names it moves the sheet there with an animation, and doesn't
+   * send `sheetDetentChanged`. Nothing else moves the sheet off the stop it stands at, the one the user dragged it to
+   * included: a `mergeOptions` without it, a new layout or new content. A value that isn't among `detents` opens on
+   * the lowest stop on iOS and is ignored on Android.
    * Without it, the lowest stop.
    */
   selectedDetent?: OptionsModalSheetDetent;

package/src/interfaces/options/sideMenu.ts

@@ -18,8 +18,8 @@ export interface SideMenuSide {
   visible?: boolean;
   /**
    * Whether the opening or closing that `visible` asks for is animated. With `false` it happens at once and the
-   * screens of the menu get the same appearance events in the same order, except that on Android a menu that opens at
-   * once sends its screens DidAppear without WillAppear. It acts only together with `visible` in the same merge.
+   * screens of the menu get the same appearance events in the same order: WillAppear, then DidAppear. It acts only
+   * together with `visible` in the same merge.
    * @default true
    */
   animate?: boolean;
@@ -32,15 +32,16 @@ export interface SideMenuSide {
   enabled?: boolean;
   /**
    * The width of the menu, in points on iOS and dp on Android. It is capped at the width of the side menu (iOS) and at
-   * that width less 64 dp (Android). On iOS a change applies at once, also to an open menu. On Android it applies the
-   * next time a screen in the side menu appears, the center's or a menu's.
+   * that width less 64 dp (Android). A change in `mergeOptions` applies at once, also to an open menu. A width set by
+   * a screen of the center acts while that screen shows.
    * Without it, 280 points on iOS and the width of the side menu less 64 dp on Android (the least gap the Material
    * drawer leaves).
    */
   width?: number;
   /**
-   * (Android) The height of the menu in dp; a menu lower than the container is pinned to the top. It is read only when
-   * the side menu is created. Without it, the menu takes the full height under the status bar. iOS doesn't read it.
+   * (Android) The height of the menu in dp; a menu lower than the container is pinned to the top. A change in
+   * `mergeOptions` applies at once, also to an open menu. Without it, the menu takes the full height under the status
+   * bar. iOS doesn't read it.
    */
   height?: number;
   /**
@@ -94,6 +95,9 @@ export type SideMenuOpenGestureMode = 'bezel' | 'entireScreen';
  */
 export type SideMenuAnimationType = 'parallax' | 'slide' | 'slide-and-scale' | 'door';
 
+/** When the screens of the menus of a side menu are created: see `sideMenu.menusAttachMode`. */
+export type SideMenuAttachMode = 'together' | 'afterCenter' | 'onOpen';
+
 /**
  * The options of a side menu: a center with a menu on the left, on the right or on both sides. They are set in the
  * options of the side menu, in the options of the screens inside it (through `mergeOptions` or the screen definition)
@@ -121,6 +125,20 @@ export interface OptionsSideMenu {
    * the center moves. It does nothing in `'aboveContent'` mode. A change applies at once. Android doesn't read it.
    */
   animationType?: SideMenuAnimationType;
+  /**
+   * When the screens of the menus are created, together with their React content: `'together'` creates them with the
+   * center; `'afterCenter'` creates them right after the center first appears, so they don't compete with its first
+   * render and still show at once on the first open; `'onOpen'` creates a menu the first time it starts to open — from
+   * a swipe, from `visible: true` or from `visible` in the layout — and until React draws its screen the menu shows its
+   * background. A command to a screen of a menu not created yet works: a push into its stack and `mergeOptions` wait
+   * for the menu like a tab not yet selected. The screens of a menu get appear events only when it opens, in every
+   * mode. With `appProvider` the screens render in the app's React tree at once in every mode, and the mode delays only
+   * their native containers. On iOS a menu's test identifier (`<testID>.left`, `<testID>.right`) is there once the menu
+   * is created; on Android from the start. It applies when the side menu is created, from its own options or the default options;
+   * `mergeOptions` does not change it.
+   * @default 'together'
+   */
+  menusAttachMode?: SideMenuAttachMode;
   /**
    * The test identifier of the side menu's container (on iOS its view, on Android the drawer). The parts derive from
    * it: `<testID>.center`, `<testID>.left`, `<testID>.right`, and on iOS `<testID>.scrim` for the dimming over the

package/src/interfaces/options/stack.ts

@@ -26,17 +26,31 @@ export interface HardwareBackButtonOptions {
    * @internal
    */
   dismissModalOnPress?: boolean;
+  /**
+   * (Android) Whether back on the first screen of the app, with nothing left to go back to, plays the system's
+   * animation of going home. The system decides it as the gesture starts, so with `false` the navigation keeps the
+   * back on that screen too: the gesture shows no animation, and on release the press goes to `BackHandler` listeners,
+   * then to the activity's own back (`invokeDefaultOnBackPressed` of the app's activity, such as `moveTaskToBack`).
+   * Read from the screen back acts on; set it in the default options for the whole app. iOS ignores it.
+   * @default true
+   */
+  systemAnimation?: boolean;
 }
 
 /**
  * (Android) A floating action button over the screen, or an entry of its menu. The button shows while its screen is
- * on top of the stack; without the option there is none. `mergeOptions` and the default options of the app apply, and
- * the colors of the theme are read again when the theme changes.
+ * on top of the stack; without the option there is none. It changes as a push or a pop starts and moves with its
+ * screen, as the tab bar does: the new screen's button comes in with it, the old one goes out with the screen it
+ * belongs to, and an open menu closes. With an animation of the screens' own the old button shrinks away and the new
+ * one grows as it starts; during the back gesture the button of the screen under the top shows with that screen.
+ * `mergeOptions` and the default options of the app apply, and the colors of the theme are read again when the theme
+ * changes.
  */
 export interface OptionsFab {
   /**
    * The identifier of the button. A press reports it, and the app finds the `onPress` of the button by it. A button
-   * without an `id` doesn't show. The same `id` on a later show or merge updates the button; another `id` replaces it.
+   * without an `id` doesn't show. The same `id` on a later show or merge updates the button, which stays in place
+   * while the screens move; another `id` replaces it.
    * For an entry of `actions` it is the id of that entry's own press.
    */
   id: string;