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

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';
@@ -53,24 +59,27 @@ 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 `'content'` takes its place by
+   * the height of the content, again whenever that changes; 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 `'medium'` between them when the list has both `'medium'` and `'large'`. A stop without a place is
+   * dropped.
    * @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;
   /**

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;
   /**
@@ -177,9 +180,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;