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

package/lib/typescript/interfaces/options/modals.d.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' | 'formSheet' | 'fullScreen' | 'overFullScreen' | 'overCurrentContext' | 'currentContext' | 'popover';
 /**
@@ -44,7 +48,8 @@ export type OptionsModalSheetDetent = 'medium' | 'large' | 'content' | number;
 /**
  * The settings of a sheet: a modal that comes from below and rests on one of several heights, its stops (detents). On
  * iOS they configure the system sheet of a modal presented as `'pageSheet'`, `'formSheet'` or without a style. On
- * Android any one of them turns the modal into a Material bottom sheet, again for those styles only. They are read when
+ * Android they configure the Material bottom sheet of `'pageSheet'`, `'formSheet'` and `'popover'`, and without a style
+ * any one of them turns the modal into that sheet. They are read when
  * the modal shows, and a `mergeOptions` on any screen of the modal changes them while it is shown, with an animation.
  * Objects merge key by key; `detents` is replaced as a whole.
  */

package/lib/typescript/interfaces/options/modals.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"modals.d.ts","sourceRoot":"","sources":["../../../../src/interfaces/options/modals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,MAAM,6BAA6B,GACrC,WAAW,GACX,WAAW,GACX,YAAY,GACZ,gBAAgB,GAChB,oBAAoB,GACpB,gBAAgB,GAChB,SAAS,CAAC;AAEd;;;;;;;;;GASG;AACH,MAAM,MAAM,2BAA2B,GACrC,eAAe,GAAG,eAAe,GAAG,gBAAgB,GAAG,aAAa,CAAC;AAEvE;;;;;;;;GAQG;AACH,MAAM,MAAM,uBAAuB,GAAG,QAAQ,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;AAE9E;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,uBAAuB,EAAE,CAAC;IACpC;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,uBAAuB,CAAC;IACzC;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,uBAAuB,GAAG,IAAI,CAAC;IACvD;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,mCAAmC;AACnC,MAAM,MAAM,qBAAqB,GAAG,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAErE;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACtC,gFAAgF;IAChF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,eAAe,CAAC,EAAE,qBAAqB,EAAE,CAAC;IAC1C;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,kFAAkF;IAClF,KAAK,CAAC,EAAE,iBAAiB,CAAC;IAC1B,mEAAmE;IACnE,WAAW,CAAC,EAAE,uBAAuB,CAAC;IACtC,mDAAmD;IACnD,OAAO,CAAC,EAAE,mBAAmB,CAAC;IAC9B;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;;OAMG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB"}
+{"version":3,"file":"modals.d.ts","sourceRoot":"","sources":["../../../../src/interfaces/options/modals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,MAAM,6BAA6B,GACrC,WAAW,GACX,WAAW,GACX,YAAY,GACZ,gBAAgB,GAChB,oBAAoB,GACpB,gBAAgB,GAChB,SAAS,CAAC;AAEd;;;;;;;;;GASG;AACH,MAAM,MAAM,2BAA2B,GACrC,eAAe,GAAG,eAAe,GAAG,gBAAgB,GAAG,aAAa,CAAC;AAEvE;;;;;;;;GAQG;AACH,MAAM,MAAM,uBAAuB,GAAG,QAAQ,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;AAE9E;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,uBAAuB,EAAE,CAAC;IACpC;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,uBAAuB,CAAC;IACzC;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,uBAAuB,GAAG,IAAI,CAAC;IACvD;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,mCAAmC;AACnC,MAAM,MAAM,qBAAqB,GAAG,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAErE;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACtC,gFAAgF;IAChF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,eAAe,CAAC,EAAE,qBAAqB,EAAE,CAAC;IAC1C;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,kFAAkF;IAClF,KAAK,CAAC,EAAE,iBAAiB,CAAC;IAC1B,mEAAmE;IACnE,WAAW,CAAC,EAAE,uBAAuB,CAAC;IACtC,mDAAmD;IACnD,OAAO,CAAC,EAAE,mBAAmB,CAAC;IAC9B;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;;OAMG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB"}

package/lib/typescript/interfaces/options/system.d.ts

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

package/lib/typescript/interfaces/options/system.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"system.d.ts","sourceRoot":"","sources":["../../../../src/interfaces/options/system.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAU,CAAC;AAEtC;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;AAE/D;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GACzB,KAAK,GACL,SAAS,GACT,UAAU,GACV,WAAW,GACX,YAAY,GACZ,QAAQ,GACR,iBAAiB,GACjB,gBAAgB,CAAC;AAErB;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;;;;;;;OAWG;IACH,aAAa,CAAC,EAAE,YAAY,EAAE,CAAC;IAC/B;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,KAAK,CAAC;IACxB;;;OAGG;IACH,wBAAwB,CAAC,EAAE,KAAK,CAAC;IACjC;;;;;;;;;OASG;IACH,WAAW,CAAC,EAAE,iBAAiB,EAAE,CAAC;IAClC;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;;;OAMG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC;;;;;OAKG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,YAAY,EAAE,CAAC;IACrC;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;;;;OASG;IACH,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IACzB;;;;;;;OAOG;IACH,eAAe,CAAC,EAAE,KAAK,CAAC;IACxB;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;;;;;;;;OAYG;IACH,eAAe,CAAC,EAAE,KAAK,CAAC;IACxB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,qHAAqH;AACrH,MAAM,MAAM,yBAAyB,GAAG,SAAS,GAAG,OAAO,GAAG,QAAQ,GAAG,WAAW,GAAG,SAAS,CAAC;AAEjG;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAChC,8FAA8F;IAC9F,EAAE,EAAE,MAAM,CAAC;IACX;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IACd,+GAA+G;IAC/G,SAAS,CAAC,EAAE,yBAAyB,EAAE,CAAC;IACxC;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB"}
+{"version":3,"file":"system.d.ts","sourceRoot":"","sources":["../../../../src/interfaces/options/system.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAU,CAAC;AAEtC;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;AAE/D;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GACzB,KAAK,GACL,SAAS,GACT,UAAU,GACV,WAAW,GACX,YAAY,GACZ,QAAQ,GACR,iBAAiB,GACjB,gBAAgB,CAAC;AAErB;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;;;;;;;OAWG;IACH,aAAa,CAAC,EAAE,YAAY,EAAE,CAAC;IAC/B;;;;;;;OAOG;IACH,eAAe,CAAC,EAAE,KAAK,CAAC;IACxB;;;OAGG;IACH,wBAAwB,CAAC,EAAE,KAAK,CAAC;IACjC;;;;;;;;;OASG;IACH,WAAW,CAAC,EAAE,iBAAiB,EAAE,CAAC;IAClC;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;;;OAMG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC;;;;;OAKG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,YAAY,EAAE,CAAC;IACrC;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;;;;OASG;IACH,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IACzB;;;;;;;OAOG;IACH,eAAe,CAAC,EAAE,KAAK,CAAC;IACxB;;;;;;;;;OASG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;;;;;;;;OAYG;IACH,eAAe,CAAC,EAAE,KAAK,CAAC;IACxB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,qHAAqH;AACrH,MAAM,MAAM,yBAAyB,GAAG,SAAS,GAAG,OAAO,GAAG,QAAQ,GAAG,WAAW,GAAG,SAAS,CAAC;AAEjG;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAChC,8FAA8F;IAC9F,EAAE,EAAE,MAAM,CAAC;IACX;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IACd,+GAA+G;IAC/G,SAAS,CAAC,EAAE,yBAAyB,EAAE,CAAC;IACxC;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apexnative/navigation",
-  "version": "1.0.0-alpha.2",
+  "version": "1.0.0-alpha.3",
   "description": "Native navigation for React Native: platform stacks, tabs, modals and side menus on iOS, iPadOS and Android",
   "keywords": [
     "react-native",

package/src/api/hooks/useNavigation.ts

@@ -177,14 +177,19 @@ function stackCommands(id: string): StackCommands {
   };
 }
 
-/** The commands of the center for a menu screen: the menu closes once the center has changed. */
+/**
+ * The commands of the center for a menu screen: the menu closes as the center changes, and the command resolves once
+ * both are done.
+ */
 function fromCenter(center: string, menuScreen: string): StackCommands {
   const centerCommands = stackCommands(center);
+  // As in the system's apps, the menu starts to close at the pick and the center changes as it goes, so a push is seen
+  // sliding in. The command settles after both, so the next one acts from the center; either one's error rejects it.
   const closing =
     <Args extends unknown[], Result>(run: (...args: Args) => Promise<Result>) =>
     async (...args: Args) => {
-      const result = await run(...args);
-      await closeMenu(menuScreen);
+      const closed = closeMenu(menuScreen);
+      const [result] = await Promise.all([run(...args), closed]);
       return result;
     };
   return {

package/src/interfaces/options/animations.ts

@@ -361,15 +361,18 @@ export interface StackAnimationOptions {
   /**
    * The animation of the screens: `enter` for the screen that comes (on a pop, the one that was below), `exit` for the
    * one that goes. A property with a `from` or a `to` makes it an animation of its own, which replaces the platform's
-   * transition; the side left out stays still. (Android) With one of its own, the title and buttons of the bar and the
-   * tab bar don't travel with the screens. (Android) When the transition has elements, a push plays only `enter` and a
+   * transition; the side left out stays still. With one of its own, (Android) the top bar goes with its screen: the
+   * bar of the screen that goes leaves with it, and the bar of the screen that comes moves, scales and fades with it;
+   * (iOS) UIKit keeps the bar in place and changes its title and buttons at once. (Android) The tab bar doesn't travel
+   * with the screens. (Android) When the transition has elements, a push plays only `enter` and a
    * pop only `exit`, and only when that side is a single `alpha`; any other side is not played, and the screen fades in
    * or out in 300 ms around the elements instead. iOS plays the sides as they are set.
    */
   content?: EnterExitAnimationOptions;
   /**
    * (Android) The animation of the top bar when it shows or hides because the screens differ in `topBar.visible`.
-   * Without it, the bar slides up by its height and back in 300 ms. iOS animates the bar with UIKit.
+   * Without it, the bar slides up by its height and back in 300 ms; with a `content` of its own it shows or hides
+   * with its screen. iOS animates the bar with UIKit.
    */
   topBar?: EnterExitAnimationOptions<TopBarAnimationOptions>;
   /**
@@ -420,8 +423,10 @@ export interface SetStackRootAnimationOptions extends StackAnimationOptions {
  * screen under it. The screen under a modal takes part (iOS) only under a modal that covers the full screen.
  *
  * A sheet keeps the system's sheet motion on both platforms: (iOS) a modal shown as `'pageSheet'`, `'formSheet'` or
- * without a style, (Android) a Material bottom sheet. The sides `enter` and `exit` and the lists of elements set here
- * don't apply to it.
+ * without a style, (Android) the Material bottom sheet of `'pageSheet'`, `'formSheet'`, `'popover'`, or of
+ * `modal.sheet` without a style. The sides `enter` and `exit` and the lists of elements set here don't apply to it.
+ * Without them a modal over the whole screen comes up from the bottom: on iOS by UIKit's `modalTransitionStyle`, on
+ * Android with the system's motion of a window over another, 300 ms up and 250 ms down, without a fade.
  *
  * (Android) When the modal has elements, `enter` of a show and `exit` of a dismiss play only when that side is a single
  * `alpha`; any other side is not played, and the modal fades in or out in 300 ms around the elements instead.

package/src/interfaces/options/modals.ts

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

package/src/interfaces/options/system.ts

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