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

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;

package/src/interfaces/options/system.ts

@@ -34,20 +34,24 @@ export interface OptionsLayout {
    * indicator or navigation bar, the camera cutout. `[]` lets the content reach every edge. The array replaces the
    * one from a lower layer. The screen adds the padding itself; `useSafeAreaInsets()` returns what is still covered,
    * which is 0 on an edge the screen keeps and the whole covered size on an edge where the content goes under a bar.
-   * Edges listed here always win, also for a screen with a large title.
+   * Edges listed here win, but the top under a large title: there the list keeps its first rows clear of the bar
+   * itself and scrolls under it, which collapses the title, so a `'top'` listed here counts for nothing.
    *
-   * Without it, on iOS: every edge except those where the content goes under a bar that shows (the top bar, a tab
-   * bar or toolbar at the bottom, the side of a vertical bar); a screen with a large title keeps the top free so its
-   * list can scroll under the bar. On Android: all four edges, except the top under a top bar that hides on scroll
-   * or under a large title, and the bottom under tabs that hide on scroll.
+   * Without it the screen keeps the top and the sides, and its content goes down to the bottom: under the home
+   * indicator or the navigation bar, and under a tab bar or toolbar it goes under. A list keeps its last rows clear
+   * with `useSafeAreaInsets().bottom`. The top is free where the content goes under a top bar: on iOS under a bar
+   * that shows, on Android under a bar that hides on scroll; on both under a large title, so the list scrolls under
+   * the bar. On iOS the side of a vertical bar is free too. To have the screen keep the bottom, list every edge it
+   * keeps: listed edges replace the default.
    */
   safeAreaEdges?: SafeAreaEdge[];
   /**
    * 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 +156,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;
   /**
@@ -177,9 +183,10 @@ export interface OptionsStatusBar {
    */
   hideWithTopBar?: boolean;
   /**
-   * (iOS) Whether a blur shows under the status bar, drawn over the screen in the frame the status bar has when the
-   * option applies. It applies when the screen appears and through `mergeOptions`; `false` removes it. The blur does
-   * not follow a rotation or a change of window size.
+   * (iOS) Whether a blur shows under the status bar, drawn over the screen in the status bar's frame. It applies when
+   * the screen appears and through `mergeOptions`; `false` removes it. The blur follows the status bar's frame as it
+   * changes: a rotation, a new window size, the status bar hidden or shown. Android has no blur under the status bar,
+   * so it does nothing there.
    * @default false
    */
   blur?: boolean;

package/src/interfaces/options/toolbar.ts

@@ -4,7 +4,7 @@ import type { OptionsTopBarButton } from './buttons';
 export interface OptionsToolbarSpace {
   /**
    * `'flexibleSpace'` takes the free width and pushes the next buttons to the far edge; `'fixedSpace'` is a gap of zero
-   * width that starts a new capsule on iOS 26.
+   * width that starts a new capsule with the glass design (iOS 26+).
    */
   systemItem: 'flexibleSpace' | 'fixedSpace';
 }
@@ -36,7 +36,7 @@ export interface OptionsToolbar {
    * The buttons from the leading edge, in the format of the bar buttons: text, icon, SF Symbol, `systemItem`, a
    * component (drawn before the screen shows), `enabled`, `color`, `style`, `menu` (it opens upward), `toggle`,
    * `showText`, `group`; also spaces and the search field. A press sends a button press. The color of a side doesn't
-   * apply to them, and badges are not drawn. On iOS 26 each button has its own capsule, neighbor icons with the same
+   * apply to them, and badges are not drawn. With the glass design (iOS 26+, see `UIDesignRequiresCompatibility`) each button has its own capsule, neighbor icons with the same
    * `group` share one (the toolbar has no real groups, so text buttons never share), and a zero-width space is put
    * between neighbors of different groups unless an explicit space is there. The list is replaced as a whole;
    * `mergeOptions` animates it.

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;
@@ -46,7 +50,7 @@ export interface OptionsTopBarTitleDocument {
 export interface OptionsTopBarTitle {
   /**
    * The text of the title. Setting it removes a React title. On iOS it is the title of the screen's navigation item,
-   * the label the system shows on the next screen's back button before iOS 26, and what Rename edits. On Android it
+   * the label the system shows on the next screen's back button without the glass design, and what Rename edits. On Android it
    * is one line cut with an ellipsis, and also the text of the large title; a title component set together with the
    * text drops the text and the subtitle (with a warning in development).
    */
@@ -90,9 +94,9 @@ export interface OptionsTopBarTitle {
    */
   document?: OptionsTopBarTitleDocument;
   /**
-   * (iOS 26+) Puts the title on a Liquid Glass capsule like the buttons: `'regular'` or `'clear'`; `'none'` and any
+   * (iOS 26+, glass design) Puts the title on a Liquid Glass capsule like the buttons: `'regular'` or `'clear'`; `'none'` and any
    * other value mean no capsule. A text title and the subtitle are two lines on the capsule; a component title sits on
-   * it as it is, the capsule taking its size. Before iOS 26 and on Android it does nothing.
+   * it as it is, the capsule taking its size. Without the glass design (see `UIDesignRequiresCompatibility`) and on Android it does nothing.
    */
   glass?: 'regular' | 'clear' | 'none';
   /** (Android) The height of the row of title and buttons, in dp. By default 64, regardless of `topBar.height`. */
@@ -114,15 +118,15 @@ export interface OptionsTopBarTitle {
 /** The subtitle: a second line under the title. */
 export interface OptionsTopBarSubtitle {
   /**
-   * The text of the second line. An empty text removes it. On iOS 26 it is the system subtitle, under the title, the
-   * large title and the collapsed bar, and on the capsule when the title has `glass`; a React title hides it. Before
-   * iOS 26 it makes a two-line title view, only without a large title or a React title. On Android it is the line under
+   * The text of the second line. An empty text removes it. With the glass design (iOS 26+, see `UIDesignRequiresCompatibility`) it is the system subtitle, under the title, the
+   * large title and the collapsed bar, and on the capsule when the title has `glass`; a React title hides it. Without
+   * it, it makes a two-line title view, only without a large title or a React title. On Android it is the line under
    * the title, hidden when empty and dropped when the title is a component.
    */
   text?: string;
   /**
-   * The size of the font. On iOS 26 only what is set goes to the system subtitle, and any font option sets the whole
-   * font; before iOS 26 the size is 12. On Android it is in sp, 14 by default.
+   * The size of the font. With the glass design only what is set goes to the system subtitle, and any font option sets the whole
+   * font; without it the size is 12. On Android it is in sp, 14 by default.
    */
   fontSize?: number;
   /** The color of the subtitle. On Android the theme's on-surface-variant color by default. */
@@ -173,14 +177,14 @@ export interface OptionsTopBarBackButton {
    */
   visible?: boolean;
   /**
-   * (iOS) The text of the back button. On iOS 26 the system button without it is an arrow alone, since the title of
-   * the screen below is never shown; before iOS 26 it is that title while it fits. It is set on the screen below, as
+   * (iOS) The text of the back button. With the glass design (iOS 26+, see `UIDesignRequiresCompatibility`) the system button without it is an arrow alone,
+   * since the title of the screen below is never shown; without it, it is that title while it fits. It is set on the screen below, as
    * its back button title.
    */
   title?: string;
   /**
    * (iOS) `true` shows the title of the screen below (or `title`), `false` shows an arrow alone (the minimal mode).
-   * Without it the system decides; on iOS 26 that is the arrow.
+   * Without it the system decides; with the glass design that is the arrow.
    */
   showTitle?: boolean;
   /**
@@ -203,7 +207,7 @@ export interface OptionsTopBarBackButton {
   /**
    * A shape behind the icon, as for a button. It takes effect with a `color` of the shape. On iOS the icon (the
    * chevron by default) is drawn on it and the back button becomes an own button that keeps the history menu unless
-   * `enableMenu` is `false`; without a capsule on iOS 26 by default. On Android the arrow sits on the shape.
+   * `enableMenu` is `false`; without a capsule with the glass design by default. On Android the arrow sits on the shape.
    */
   iconBackground?: IconBackgroundOptions;
   /**
@@ -224,7 +228,7 @@ export interface OptionsTopBarBackButton {
    */
   displayMode?: 'default' | 'generic' | 'minimal';
   /**
-   * (iOS 26+) Whether the Liquid Glass capsule under the back button is hidden. It works only for an own button with
+   * (iOS 26+, glass design) Whether the Liquid Glass capsule under the back button is hidden. It works only for an own button with
    * an `iconBackground`, where the shape is already drawn into the icon; the system button ignores it.
    * @default true
    */
@@ -241,9 +245,9 @@ export interface OptionsTopBarBackButton {
 /** The background of the bar: a color, a component, translucency and blur. */
 export interface OptionsTopBarBackground {
   /**
-   * The color of the bar. On iOS it fills both the standard look and the one at the scroll edge; on iOS 26 the bar is
-   * then solid in this color instead of glass. A transparent color makes a transparent bar. It beats `blur` and
-   * `translucent`. With a large title on iOS 26 the color is drawn into the list under the title, and the collapsed bar
+   * The color of the bar. On iOS it fills both the standard look and the one at the scroll edge; with the glass design the bar is
+   * then solid in this color instead of glass; without it (`UIDesignRequiresCompatibility`) it is the opaque bar of before iOS 26. A transparent color makes a transparent bar. It beats `blur` and
+   * `translucent`. With a large title and the glass design the color is drawn into the list under the title, and the collapsed bar
    * paints itself. On Android it is the background of the bar with the status bar strip, by default the theme's
    * surface color, changing at once on push and pop. Together with `component` the color lies under the component.
    */
@@ -262,8 +266,8 @@ export interface OptionsTopBarBackground {
    */
   component?: OptionsTopBarBackgroundComponent;
   /**
-   * (iOS) Whether content shows through the bar. By default `true` on iOS 26 (glass) and `false` before. With `true`
-   * the bar is glass on iOS 26 and the system translucent bar before; with `false` it is solid in the system color.
+   * (iOS) Whether content shows through the bar. By default `true` with the glass design (iOS 26+, see `UIDesignRequiresCompatibility`) and `false` without it. With `true`
+   * the bar is glass with the glass design and the system translucent bar without it; with `false` it is solid in the system color.
    * `color` and `blur` beat it. Only an explicit `true` puts the screen under the bar.
    */
   translucent?: boolean;
@@ -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;
@@ -293,7 +301,7 @@ export interface OptionsTopBarBackgroundComponent {
 export interface OptionsTopBarScrollEdgeAppearanceTitle {
   /** The size of the font, handled like `topBar.title.fontSize`. */
   fontSize?: number;
-  /** The color of the title at the edge. On iOS 26 it is fixed during a push, like the usual title color. */
+  /** The color of the title at the edge. With the glass design it is fixed during a push, like the usual title color. */
   color?: Color;
   /** The font family, handled like `topBar.title.fontFamily`. */
   fontFamily?: FontFamily;
@@ -319,7 +327,7 @@ export interface OptionsTopBarScrollEdgeAppearanceBackground {
 
 /**
  * (iOS) How the bar looks while the list is at its top edge. Without `active` the edge looks as the usual bar, except
- * for the transparency under a large title on iOS 26; the title and the border at the edge still come from the fields
+ * for the transparency under a large title with the glass design; the title and the border at the edge still come from the fields
  * here or from the usual ones. Android doesn't read it.
  */
 export interface OptionsTopBarScrollEdgeAppearance {
@@ -329,7 +337,7 @@ export interface OptionsTopBarScrollEdgeAppearance {
   background?: OptionsTopBarScrollEdgeAppearanceBackground;
   /**
    * Whether the bar has a background of its own at the edge (`background`). With it the edge isn't made transparent
-   * under a large title, and on iOS 26 an opaque color covers the large title. A change by `mergeOptions` applies at
+   * under a large title, and with the glass design an opaque color covers the large title. A change by `mergeOptions` applies at
    * once.
    * @default false
    */
@@ -365,7 +373,7 @@ export interface OptionsTopBarLargeTitle {
    * Whether the large title collapses into the bar as the list scrolls. With `false` on iOS the bar follows an empty
    * scroll view instead of the list, so the title stays as at the top of the list; under the row it then needs a
    * background (`background.color`, else a system blur), and `searchBar.hideOnScroll` doesn't work. On Android `false`
-   * leaves the bar as it is and stops listening to the list. On iOS 26 in a right-to-left layout nothing collapses.
+   * leaves the bar as it is and stops listening to the list. With the glass design in a right-to-left layout nothing collapses.
    * @default true
    */
   collapseOnScroll?: boolean;
@@ -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[];
   /**
@@ -624,7 +637,7 @@ export interface OptionsTopBar {
   /**
    * The shape color behind the icons of the left buttons that have an `icon` image and no `iconBackground.color`; the
    * size and corners come from the button's `iconBackground`, or the icon's size without corners. On iOS only image
-   * buttons, not SF Symbols, and without a capsule on iOS 26. A color sent by `mergeOptions` repaints all the side's
+   * buttons, not SF Symbols, and without a capsule with the glass design. A color sent by `mergeOptions` repaints all the side's
    * image buttons, those with their own shape color too.
    */
   leftButtonBackgroundColor?: Color;
@@ -641,6 +654,20 @@ export interface OptionsTopBar {
   centerButtonColor?: Color;
   /** (iOS 16+) The color of the disabled center buttons that have no `disabledColor` of their own. */
   centerButtonDisabledColor?: Color;
+  /**
+   * (Android) The background of the bar's menus: "⋮" and the menus of the buttons, their submenus too. Without it the
+   * bar's color (`background.color`, else the theme's surface), unless the bar lets something through; then the
+   * theme's surface container color. It follows light and dark mode; an open menu closes as the mode switches. iOS
+   * draws its system menus in the system's colors.
+   */
+  menuBackgroundColor?: Color;
+  /**
+   * (Android) The color of the text and the icons of the items of the bar's menus, and of the titles of their
+   * submenus. Without it the title's color (`title.color`) when the menu takes the bar's color, else the theme's
+   * colors. A destructive item stays red, and a button moved into "⋮" keeps its own color or the side's
+   * (`rightButtonColor`). A disabled item is dimmed. An open menu closes when either menu color is merged.
+   */
+  menuTextColor?: Color;
   /**
    * Whether the content of the screen goes under the bar, starting at the top of the screen. The screen goes under the
    * bar by itself in some cases (a large title that may show, `hideOnScroll`, a hidden bar, an explicit translucent
@@ -802,12 +829,15 @@ export interface OptionsScrollEdge {
 
 /**
  * (iOS 26+) The scroll edge effect of the scroll views of a screen: how the content fades or blurs where it scrolls
- * under a bar. The scroll views draw it, and only where content goes under a bar. It applies to every scroll view in
- * the view of the screen when the screen appears; after React mounts it applies to the main list of the screen only; on
- * `mergeOptions` all is reset and applied again. Other scroll views mounted later get it at the next appearance or
- * `mergeOptions`. When the screen leaves, its scroll views get the system effect back. Under a bar with
- * `background.color` or `background.component` there is no effect at the top unless the screen sets one for the top or
- * for all edges. Before iOS 26 and on Android it does nothing.
+ * under a bar. The scroll views draw it, and only where content goes under a bar. When the screen appears, it applies
+ * to the vertical lists and text views (a multi-line `TextInput`) in the view of the screen, except in hidden views
+ * (`display: none`). A list inside another vertical list gets none (UIKit draws no edge effect there); a scroll view
+ * that doesn't scroll vertically, like a pager, is searched for its lists. A list nested very deep in the screen's
+ * views may not get it. After React mounts, the main list of the screen gets it; a list mounted later gets it at the
+ * next appearance, or at a `mergeOptions` of `scrollEdgeEffect` or of the bar's background. The lists get the system
+ * effect back when the screen leaves or is destroyed, and a list React removes from the screen gets it back too. Under
+ * a bar with `background.color` or `background.component` there is no effect at the top unless the screen sets one for
+ * the top or for all edges. Before iOS 26 and on Android it does nothing.
  */
 export interface OptionsScrollEdgeEffect {
   /** Whether the effect is hidden on all four edges. The value of an edge beats it. */

package/android/src/main/java/dev/apexnative/navigation/react/ArrangementStates.kt

@@ -1,41 +0,0 @@
-package dev.apexnative.navigation.react
-
-import android.content.Context
-import com.facebook.react.ReactApplication
-import com.facebook.react.bridge.Arguments
-import com.facebook.react.bridge.WritableMap
-import dev.apexnative.navigation.react.events.EventEmitter
-import java.util.concurrent.ConcurrentHashMap
-
-/**
- * The state of each screen of a pair (`useArrangement`): which screen of the pair it is, how the pair lies, whether it
- * lies over the other one and whether it is out of the window. Set on the main thread as the pair lays out; JavaScript
- * reads it from its own thread for a screen's first render, and gets every change as `ANN.ArrangementChanged`. A
- * screen outside a pair has none.
- */
-internal object ArrangementStates {
-    data class State(val placement: String, val layout: String, val front: Boolean, val hidden: Boolean)
-
-    private val states = ConcurrentHashMap<String, State>()
-
-    /** Keeps the screen's state, and tells JavaScript when it changed and [notify] holds. Main thread only. */
-    fun set(context: Context, screenId: String, state: State, notify: Boolean) {
-        if (states.put(screenId, state) == state || !notify) return
-        val reactContext = (context.applicationContext as? ReactApplication)?.reactHost?.currentReactContext ?: return
-        EventEmitter(reactContext).emitArrangementChanged(screenId, toMap(state))
-    }
-
-    /** `{ placement, layout, front, hidden }`, empty for a screen outside a pair. Any thread. */
-    fun get(screenId: String): WritableMap = states[screenId]?.let(::toMap) ?: Arguments.createMap()
-
-    fun remove(screenId: String) {
-        states.remove(screenId)
-    }
-
-    private fun toMap(state: State): WritableMap = Arguments.createMap().apply {
-        putString("placement", state.placement)
-        putString("layout", state.layout)
-        putBoolean("front", state.front)
-        putBoolean("hidden", state.hidden)
-    }
-}