@apexnative/navigation 0.0.0-stage → 1.0.0-alpha.1

package/src/interfaces/options/preview.ts

@@ -0,0 +1,40 @@
+/**
+ * An entry of the menu under a preview. With `actions` it opens a submenu instead of reporting a press.
+ */
+export interface PreviewMenuItem {
+  /** The identifier a press reports to the screen of the preview. */
+  id: string;
+  /** The text of the entry. */
+  title: string;
+  /** How the entry looks: `'destructive'` in the red of a destructive action, `'selected'` with a check mark. */
+  style?: 'default' | 'selected' | 'destructive';
+  /** The entries of a submenu. */
+  actions?: PreviewMenuItem[];
+}
+
+/**
+ * (iOS) The preview of a screen that is pushed, shown by a long press on a view of the screen it is pushed from: the
+ * system's context menu with the small screen and a menu under it. A tap on the preview opens the screen. Set by
+ * `usePreview` through the push of the preview; apps don't set it. Android has no previews.
+ * @internal
+ */
+export interface PreviewOptions {
+  /**
+   * The `nativeID` of the view of the source screen that shows the preview. The native side looks for that view
+   * right away and for up to 30 frames after, since a view just rendered mounts a little after the command. A preview
+   * whose view isn't found goes away at once, and its push is rejected.
+   */
+  nativeID: string;
+  /**
+   * Whether a tap on the preview opens the screen. The tap is reported with a preview-completed event; with `true` the
+   * screen is also shown: the stack goes back to the screen with the same key when the source is in a stack, else the
+   * screen is pushed without animation.
+   */
+  commit?: boolean;
+  /** The menu under the preview. */
+  actions?: PreviewMenuItem[];
+  /** The width of the preview. Without it, the width of the source screen. */
+  width?: number;
+  /** The height of the preview. Without it, the height of the source screen. */
+  height?: number;
+}

package/src/interfaces/options/sideMenu.ts

@@ -0,0 +1,132 @@
+/**
+ * The settings of one side of a side menu, the same type for `sideMenu.left` and `sideMenu.right`. The left menu opens
+ * from the left edge and the right menu from the right edge, also in right-to-left layouts. Only one menu is open at a
+ * time: opening one closes the other. The settings apply when the side menu is created, each time a screen of the side
+ * menu appears (then all of them anew, with the defaults named below), and at once when they arrive in `mergeOptions`
+ * (then only the fields that arrived). A value from a screen of the center holds while that screen is on top of the
+ * center, and afterwards the value of the side menu's own options or the default holds.
+ */
+export interface SideMenuSide {
+  /**
+   * Whether the menu opens (`true`) or closes (`false`), with an animation unless `animate` is `false`. It is a
+   * one-time command, not a state: it is carried out when it arrives and then forgotten, so a screen that appears later
+   * and applies its options again doesn't open or close the menu once more. Opening it while the other menu is open
+   * closes the other. It opens the menu also when `enabled` is `false`. It does nothing for a menu that isn't on screen
+   * to close, or for a side that has no menu, and is ignored in the default options. Set in the layout options, it
+   * opens the menu when the side menu first shows. Without it, nothing happens.
+   */
+  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.
+   * @default true
+   */
+  animate?: boolean;
+  /**
+   * Whether the user can open the menu with a gesture. With `false` the gesture doesn't open it, while `visible` and
+   * `openMenu` still do; a menu that is already open stays open and can be closed by a gesture. It holds while the
+   * screen that set it is on top of the center, and a value of the default options counts.
+   * @default true
+   */
+  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.
+   * 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.
+   */
+  height?: number;
+  /**
+   * (iOS) Whether a finger can pull the menu out past its width. With `true` the menu follows the finger at a quarter
+   * of the speed, up to 1.1 times its width, from its outer edge in both open modes; with `false` it stops at its
+   * width. Pulling past the width goes before `animationType`.
+   * @default true
+   */
+  shouldStretchDrawer?: boolean;
+  /**
+   * (iOS) The speed in points per second with which the menu moves to its open or closed place. A menu released
+   * faster than this moves at the speed of the finger, and the move takes 0.1 seconds at the least. A value of `0` or
+   * less counts as the default.
+   * @default 840
+   */
+  animationVelocity?: number;
+  /**
+   * (iOS) Where the menu is relative to the center. `'aboveContent'` slides the menu over the center, which darkens
+   * under it. `'pushContent'` keeps the menu under the center, which moves aside by the width of the menu and casts a
+   * shadow (see `sideMenu.animationType` for how the menu itself appears). An unknown string means `'aboveContent'`. A
+   * change applies at once, to an open menu too. Android always draws the menu over the center.
+   * @default 'aboveContent'
+   */
+  openMode?: 'aboveContent' | 'pushContent';
+  /**
+   * (iOS 26+) Whether a Liquid Glass layer fills the menu's container, under its screen. The glass shows through only
+   * where the screen is transparent, so the screen needs `layout.backgroundColor` and `layout.componentBackgroundColor`
+   * both `'transparent'` and a root view with no background. With `'aboveContent'` the center shows through the glass. Below iOS 26 and on Android it
+   * does nothing. A change applies at once.
+   * @default false
+   */
+  glass?: boolean;
+  /**
+   * The test identifier of this side's container; while the menu is open, the dimming over the center is
+   * `<testID>.scrim`. When it is not set, the identifiers derive from `sideMenu.testID`.
+   */
+  testID?: string;
+}
+
+/**
+ * How a swipe opens a menu (iOS): `'bezel'` from a strip of 20 points along the edge of the side, `'entireScreen'`
+ * from anywhere on the center, where the direction of the move picks the side. An unknown string means `'bezel'`.
+ */
+export type SideMenuOpenGestureMode = 'bezel' | 'entireScreen';
+
+/**
+ * (iOS) How the menu itself moves while the center slides aside in `'pushContent'` mode. `'parallax'` moves it from a
+ * point half its width outside to its place; `'slide'` moves it along with the center; `'slide-and-scale'` fades it in
+ * while it grows from 0.9 to 1 and shifts by 50 points; `'door'` swings it open like a door around the edge next to
+ * the center.
+ */
+export type SideMenuAnimationType = 'parallax' | 'slide' | 'slide-and-scale' | 'door';
+
+/**
+ * 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)
+ * and in the default options; a screen outside a side menu is not affected. A `null` in place of a nested object counts
+ * as an empty object, and a value of the wrong type is skipped without a crash. While a menu is open, the `sideMenu`
+ * options of the center's visible screen still count.
+ */
+export interface OptionsSideMenu {
+  /** The left menu. */
+  left?: SideMenuSide;
+  /** The right menu. */
+  right?: SideMenuSide;
+  /**
+   * (iOS) Where a swipe has to start to open a menu. Closing by a gesture works from anywhere in both modes, and the
+   * swipe back of a stack goes before the menu: on a screen that can go back, the leading edge goes back and doesn't
+   * open a menu. In `'entireScreen'` mode a horizontal scroll in the center goes first while it can still scroll in the
+   * direction of the move; a horizontal pan that isn't a native scroll view, such as a carousel of a gesture library,
+   * doesn't. A change applies at once. Android's edge is the one of the Material drawer, and it doesn't
+   * read this.
+   * @default 'bezel'
+   */
+  openGestureMode?: SideMenuOpenGestureMode;
+  /**
+   * (iOS) How the menu moves in `'pushContent'` mode while the center goes aside. Without it, the menu stands still and
+   * the center moves. It does nothing in `'aboveContent'` mode. A change applies at once. Android doesn't read it.
+   */
+  animationType?: SideMenuAnimationType;
+  /**
+   * 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
+   * center that a tap on closes the menu. Android draws the dimming inside the drawer without a view of its own, and a
+   * tap on `<testID>.center` closes the menu in the same way. The button that opens the menu is an ordinary button of
+   * the top bar with a `testID` of its own.
+   */
+  testID?: string;
+}

package/src/interfaces/options/splitView.ts

@@ -0,0 +1,127 @@
+/**
+ * The width limits of a column of a split view, in points. Each is applied only when it is set; without it the
+ * system chooses the size. The columns this type describes (middle, inspector) exist on iOS only.
+ */
+export interface OptionsSplitViewColumn {
+  /** (iOS) The preferred width of the column. Without it, the width the system gives it. */
+  width?: number;
+  /** (iOS) The smallest width the column may take. Without it, the system's limit. */
+  minWidth?: number;
+  /** (iOS) The largest width the column may take. Without it, the system's limit. */
+  maxWidth?: number;
+}
+
+/**
+ * (iOS, iPadOS 26) The inspector column at the trailing edge: its width limits, and whether it shows. It does
+ * nothing before iPadOS 26 or in a split view without an `inspector` column in its layout.
+ */
+export interface OptionsSplitViewInspector extends OptionsSplitViewColumn {
+  /**
+   * Whether the inspector shows. `true` shows the column and `false` hides it; without a value, nothing changes. It
+   * applies when the split view is created (without animation), after its first appearance (the system shows the
+   * inspector then by itself), and through `mergeOptions` (animated). Showing or hiding it reports a display mode
+   * change with the inspector's state.
+   */
+  visible?: boolean;
+}
+
+/**
+ * Which columns of a split view show. The three-column values need a `supplementary` column in the layout. Android
+ * does not use it.
+ */
+export type SplitViewDisplayMode =
+  | 'automatic'
+  | 'secondaryOnly'
+  | 'oneBesideSecondary'
+  | 'oneOverSecondary'
+  | 'twoBesideSecondary'
+  | 'twoOverSecondary'
+  | 'twoDisplaceSecondary';
+
+/**
+ * The columns of the split view the screen is in: which of them show, their widths, the button and the swipe that
+ * reveal a hidden column, and the column shown on top when the split view collapses. On iOS all of it applies. On
+ * Android only `width`, `presentsWithGesture`, `compactTopColumn` and `testID` apply, and through `mergeOptions` and
+ * the default options as well as the layout.
+ */
+export interface OptionsSplitView {
+  /**
+   * (iOS) Which columns show. `'automatic'` leaves the choice to the system. What the user picks (the button, a swipe)
+   * lasts until the next `mergeOptions`. It applies when the split view is created and through
+   * `mergeOptions`, not when its screens appear. Every change reports a display mode change event. The earlier names
+   * are read too: `'hidden'` is `'secondaryOnly'`, `'visible'` `'oneBesideSecondary'` (`'twoBesideSecondary'` with
+   * three columns), `'overlay'` `'oneOverSecondary'` (`'twoOverSecondary'` with three columns); `'auto'` and any
+   * other string are `'automatic'`.
+   * @default 'automatic'
+   */
+  displayMode?: SplitViewDisplayMode;
+  /**
+   * (iOS) The side of the primary column: `'leading'` or `'trailing'`. Another value counts as `'leading'`. It applies
+   * when the split view is created, whenever a screen inside appears, and through `mergeOptions`.
+   * @default 'leading'
+   */
+  primaryEdge?: 'leading' | 'trailing';
+  /**
+   * The preferred width of the primary column. On iOS in points, applied only when set; without it, the system's
+   * width. On Android in dp, 360 by default: the width of the primary pane, which together with the 360 dp of the
+   * secondary one sets the width at which the panes stand side by side. It applies when the split view is created and
+   * at once through `mergeOptions` or new default options.
+   */
+  width?: number;
+  /** (iOS) The smallest width of the primary column, applied only when set. */
+  minWidth?: number;
+  /** (iOS) The largest width of the primary column, applied only when set. */
+  maxWidth?: number;
+  /**
+   * (iOS) The look behind the primary column: `'sidebar'` gives it the sidebar background (noticeable in a Mac
+   * Catalyst app) and `'none'` the plain one, also after `'sidebar'` was set.
+   * @default 'none'
+   */
+  primaryBackgroundStyle?: 'sidebar' | 'none';
+  /**
+   * (iOS) The widths of the middle column. It does nothing when the layout has no `supplementary` column.
+   */
+  supplementary?: OptionsSplitViewColumn;
+  /** (iOS, iPadOS 26) The inspector column at the trailing edge: its widths and whether it shows. */
+  inspector?: OptionsSplitViewInspector;
+  /**
+   * (iOS) How the columns share the width: `'tile'` puts them side by side, `'overlay'` lays the primary column over
+   * the secondary one, `'displace'` pushes the secondary column aside, and `'automatic'` leaves it to the system.
+   * @default 'automatic'
+   */
+  splitBehavior?: 'automatic' | 'tile' | 'overlay' | 'displace';
+  /**
+   * (iOS) Whether the button that shows and hides the columns appears: `'always'`, `'never'`, or `'automatic'`, which
+   * hides it when `presentsWithGesture` is `false`.
+   * @default 'automatic'
+   */
+  displayModeButton?: 'automatic' | 'never' | 'always';
+  /**
+   * Whether a swipe from the edge reveals a hidden column. On Android the swipe moves the secondary pane over the
+   * primary one and back, when they don't fit side by side; it applies when the split view is created and at once
+   * through `mergeOptions` or new default options.
+   * @default true
+   */
+  presentsWithGesture?: boolean;
+  /**
+   * (iOS) Whether a three-column split view has a button that leaves only the secondary column.
+   * @default false
+   */
+  showsSecondaryOnlyButton?: boolean;
+  /**
+   * The column shown on top when the split view collapses (iPhone, a narrow window, a narrow Android screen) and the
+   * layout has no `compact` content: `'primary'` or `'secondary'`. Without it, the system chooses on iOS (read when it
+   * collapses, from the final options with the defaults) and `'primary'` is on top on Android. On Android `'secondary'`
+   * opens the secondary pane without animation on the first narrow layout, and a new value applies at the next
+   * collapse.
+   */
+  compactTopColumn?: 'primary' | 'secondary';
+  /**
+   * An identifier for tests and accessibility tools. On Android the panes get `<testID>.primary` and
+   * `<testID>.secondary`. The back arrow of the first screen of a sliding pane takes the `topBar.backButton.testID` of
+   * that screen. Without it, the elements have no id. It changes with `mergeOptions`. On iOS the button that shows
+   * the columns gets no id: the system draws it in a column-style split view and gives no way to name it; find it by
+   * its accessibility label.
+   */
+  testID?: string;
+}

package/src/interfaces/options/stack.ts

@@ -0,0 +1,110 @@
+import type { Color, ImageResource } from './common';
+
+/**
+ * (Android) What the system back button and the back gesture do on a screen. The options are read together with
+ * those of the screen's stack, tabs and the default options. iOS has no hardware back button.
+ */
+export interface HardwareBackButtonOptions {
+  /**
+   * What back does on the first screen of a tab, when the tab's stack has nothing to pop. `'exit'` leaves the choice
+   * to what comes next in line, usually leaving the app. `'first'` selects the first tab unless it is already
+   * selected, and then leaves. `'previous'` selects the tab that was selected before this one (the tabs keep the
+   * history of selections made by the user or by code; going back does not add to it), and leaves when the history is
+   * empty. Set it for tabs with the tabs builder's `backBehavior`. The value is read when back is pressed.
+   * @default 'exit'
+   */
+  bottomTabsOnPress?: 'exit' | 'first' | 'previous';
+  /**
+   * Whether back pops the top screen of the stack. With `false` the press goes to the app as an event instead. Set by
+   * the screen hooks that hold back (`usePreventLeave`); apps don't set it.
+   * @internal
+   */
+  popStackOnPress?: boolean;
+  /**
+   * Whether back on the first screen of a modal dismisses the modal. With `false` the press goes to the app as an
+   * event instead. Set by the screen hooks that hold back (`usePreventLeave`); apps don't set it.
+   * @internal
+   */
+  dismissModalOnPress?: 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.
+ */
+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.
+   * For an entry of `actions` it is the id of that entry's own press.
+   */
+  id: string;
+  /**
+   * An identifier for tests and accessibility tools, set on the button (and on the main button of a menu). The
+   * scrim of a menu gets `<testID>.scrim`. Without it, the element has no id. It changes with `mergeOptions`.
+   */
+  testID?: string;
+  /**
+   * The color of the button's container. Without it, the `primaryContainer` of the app's Material 3 theme (the
+   * neutral Material 3 theme of the library if the app theme is not Material 3). A `{ light, dark }` pair follows the
+   * theme. It does not tint the icon: without `iconColor` the icon keeps its own colors. A merge with only this key
+   * keeps the icon color.
+   */
+  backgroundColor?: Color;
+  /**
+   * The color of the container while the button is pressed. Without it, the color doesn't change and only the ripple
+   * shows. It is independent of `backgroundColor`: setting one keeps the other.
+   */
+  clickColor?: Color;
+  /** The color of the press ripple. Without it, the one from the theme's style. It stays on a light/dark switch. */
+  rippleColor?: Color;
+  /**
+   * Whether the button shows. `false` hides it with the Material animation, and closes the actions of a menu; `true`
+   * in a merge shows it again.
+   * @default true
+   */
+  visible?: boolean;
+  /**
+   * The icon: the name of a drawable resource of the app (for example a Material Symbols icon) or an image source
+   * with a `uri`. It loads in the background and takes the color of `iconColor` if there is one. A menu without an icon
+   * shows a plus; with one, the menu's main button shows it.
+   */
+  icon?: ImageResource;
+  /**
+   * The tint of the icon. Without it, the `onPrimaryContainer` of the theme. A merge may set it alone, without a new
+   * icon.
+   */
+  iconColor?: Color;
+  /**
+   * The side of the row where the button stands. `'right'` is the end of the row (the left side in a right-to-left
+   * layout), `'left'` the start (the right side in a right-to-left layout). A merge applies it.
+   * @default 'right'
+   */
+  alignHorizontally?: 'left' | 'right';
+  /**
+   * Whether the button hides after a drag that scrolls the content down and shows after a drag up. Only the vertical
+   * lists of the top screen count. A merge applies it; `false` stops listening.
+   * @default false
+   */
+  hideOnScroll?: boolean;
+  /**
+   * The size of the button: `'mini'` is 40 dp, `'regular'` is 56 dp. It also holds with a Material 3 theme.
+   * @default 'regular'
+   */
+  size?: 'mini' | 'regular';
+  /**
+   * The entries of a menu: the button becomes a menu whose main button opens and closes the entries, each a small
+   * button above it. An entry takes `id`, `testID`, `icon`, `iconColor`, `backgroundColor`, `clickColor`,
+   * `rippleColor` and `size`; its other fields do nothing. Pressing an entry reports its `id` and closes the menu. A
+   * merge with a non-empty list replaces the entries; an empty list takes them away, and the button is a plain button
+   * again.
+   */
+  actions?: OptionsFab[];
+  /**
+   * The color that dims the screen while the menu's entries are open, one with transparency such as
+   * `'rgba(0, 0, 0, 0.32)'`. A press on it closes the menu. Without it, nothing is dimmed. A merge applies it from the
+   * next opening.
+   */
+  scrimColor?: Color;
+}

package/src/interfaces/options/system.ts

@@ -0,0 +1,252 @@
+import type { Color } from './common';
+
+/**
+ * An edge of the screen: `'top'`, `'right'`, `'bottom'` or `'left'`. The edges are physical: in a right-to-left
+ * layout `'left'` stays the left side. A value outside these four is ignored.
+ */
+export type SafeAreaEdge = 'top' | 'right' | 'bottom' | 'left';
+
+/**
+ * An orientation a screen allows. `'all'` and `'sensor'` allow all four sides; `'portrait'` the upright portrait;
+ * `'upsideDown'` the upside-down portrait; `'landscape'` and `'sensorLandscape'` both landscape sides;
+ * `'sensorPortrait'` both portrait sides; `'default'` the orientations the app declares (`Info.plist` on iOS, the
+ * manifest on Android). The screen allows the union of the sides of all its values. An unknown value is dropped.
+ */
+export type LayoutOrientation =
+  | 'all'
+  | 'default'
+  | 'portrait'
+  | 'landscape'
+  | 'upsideDown'
+  | 'sensor'
+  | 'sensorLandscape'
+  | 'sensorPortrait';
+
+/**
+ * The place of a screen in the system: the edges where it keeps its content out of the bars, its background, the
+ * orientations it allows, and how it treats the home indicator, system gestures and the keyboard. The system follows
+ * the screen that shows on top, and moves to the options of the next one when another screen comes on top. Options
+ * given to a stack, tabs or a side menu apply to their screens.
+ */
+export interface OptionsLayout {
+  /**
+   * The edges on which the screen keeps its content out of what covers it: the bars, the status bar, the home
+   * 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.
+   *
+   * 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.
+   */
+  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).
+   */
+  backgroundColor?: Color;
+  /**
+   * The color under the React content only, drawn over `backgroundColor`, for content that should differ from the
+   * screen around it. Without it, `backgroundColor` shows under the content. `null` removes the color.
+   */
+  componentBackgroundColor?: Color;
+  /**
+   * The orientations the screen allows. The screen on top decides. An empty array, or no value in any layer, leaves
+   * the orientations of the app. The array replaces the one from a lower layer. The change applies when the screen
+   * appears and at once through `mergeOptions`; the interface turns by itself if the current orientation is no longer
+   * allowed. On iOS 15 the interface only turns if the device is held in an allowed orientation. On iOS a modal decides
+   * only when it covers the whole screen (`fullScreen`, `overFullScreen`); under a sheet or a popover the screen below
+   * keeps deciding. On Android a sheet decides like any modal. An overlay decides only when its own options set it. The
+   * system does not apply the request on large screens: an iPad that runs in multitasking, and on Android 16 an app
+   * that targets API 36 on a screen at least 600 dp wide.
+   */
+  orientation?: LayoutOrientation[];
+  /**
+   * (iOS 27.1+) Whether the bars and the status bar of the screen may stand in a vertical strip at the side, as on
+   * iPhone Duo. `false` keeps them horizontal; without it, the system decides. Set it once for a screen rather than
+   * switching it by state. With `false` the screen has no vertical strip, so `drawBehindVerticalBar` has no side to
+   * act on. It does nothing before iOS 27.1 or in an app built with an older SDK.
+   * @default true
+   */
+  verticalBars?: boolean;
+  /**
+   * (iOS 27.1+) Whether the screen goes under the vertical bar of iPhone Duo, as it goes under a top bar: a list
+   * draws its blur up to the edge and keeps its rows clear of the bar itself with `useSafeAreaInsets()`. `false` keeps
+   * the content outside the bar like any other safe area edge. Explicit `safeAreaEdges` decide in its place. The side
+   * is the physical side where the bar stands. It updates with every layout and with `mergeOptions`.
+   * @default true
+   */
+  drawBehindVerticalBar?: boolean;
+  /**
+   * (iOS) Whether the system hides the home indicator after the user has not touched the screen for a while and shows
+   * it again on touch, for video, games or photos. The value comes from the screen on top with its containers, read
+   * when the system asks, and `mergeOptions` applies it at once.
+   * @default false
+   */
+  autoHideHomeIndicator?: boolean;
+  /**
+   * (iOS) The edges that give the app the first swipe the system would take (home from the bottom, the notification
+   * and control centers from the top). The system shows a hint, and a second swipe runs its gesture. The edges are
+   * physical and do not swap in a right-to-left layout. Without it, no edge is deferred. It applies after the screen
+   * appears and at once through `mergeOptions`.
+   */
+  deferSystemGestures?: SafeAreaEdge[];
+  /**
+   * (Android) Whether the screen makes room for the keyboard. `true` ends the React content above the keyboard (the
+   * bottom inset is the larger of the keyboard and the navigation bar); `false` keeps the size of the screen and lets
+   * the keyboard cover its bottom, as on iOS, for a screen that handles the keyboard itself. It needs edge-to-edge:
+   * without it the system resizes the window by the manifest's `windowSoftInputMode`, and the option changes nothing.
+   * `mergeOptions` applies it at once, also with the keyboard open. On iOS the keyboard always covers the screen.
+   * @default true
+   */
+  adjustResize?: boolean;
+}
+
+/**
+ * The status bar while the screen shows. The screen on top decides, and each key merges on its own. An overlay
+ * changes the status bar only with values of its own. On iOS a modal takes the status bar only when it shows full
+ * screen; under a sheet, a popover or an `overFullScreen` modal the screen below keeps it. iOS needs
+ * `UIViewControllerBasedStatusBarAppearance` set to `true` in `Info.plist` (the CLI's `setup` does that), so the app
+ * cannot use React Native's own `StatusBar` and sets the status bar through screen options instead.
+ */
+export interface OptionsStatusBar {
+  /**
+   * Whether the status bar shows. It applies when the screen appears and at once through `mergeOptions`. On iOS an
+   * explicit value beats `hideWithTopBar`, the change has no animation, and on iPhone in landscape the system hides
+   * the bar by itself. On Android a hidden bar comes back for a moment on a swipe from the edge, a screen without a top
+   * bar starts at the top of the window, the top bar strip gets the height of the camera cutout, and the default color
+   * is transparent. A screen without the option shows the bar again on Android. A status bar hidden or recolored by
+   * app code (React Native's `StatusBar`) is not undone by the next screen on Android unless that screen's values
+   * differ from the ones the navigation applied last.
+   * @default true
+   */
+  visible?: boolean;
+  /**
+   * The color of the text and icons: `'light'` for a dark background, `'dark'` for a light one. Without it, or with
+   * another value, the color follows the background and the interface style: dark content in the light style and
+   * light content in the dark style on iOS; on Android the contrast with what is under the bar (its own opaque color,
+   * the top bar that reaches under it, the window background). It applies when the screen appears, at once through
+   * `mergeOptions`, and on Android also when the theme or the orientation changes. On iOS a change of the style alone,
+   * through `mergeOptions` or as another screen comes on top, fades over 0.35 s unless `animate` is `false`; with a
+   * change of `visible` it changes at once; along a push, a pop, a tab switch or a modal it changes with the
+   * transition.
+   */
+  style?: 'light' | 'dark';
+  /**
+   * (Android) The color of the status bar. Without it, the color the app theme gave the window when the activity was
+   * created (transparent with edge-to-edge; transparent while the bar is hidden); it doesn't follow a light/dark switch
+   * made without recreating the activity. A screen without a color after one with a color goes back to
+   * the theme's color. The color changes at once, without animation, also between screens and tabs. It lies over the
+   * screens, so an opaque color covers the strip of the top bar under the status bar and a transparent one shows it.
+   * `null` takes the theme's color. iOS draws the status bar transparent over the screen and does not read it.
+   */
+  backgroundColor?: Color;
+  /**
+   * (Android) Whether the screen and its top bar reach under the status bar. Without it, a shown top bar reaches under
+   * the bar as one surface (its color, background component and shadow reach the top of the window, its row of title
+   * 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.
+   */
+  drawBehind?: boolean;
+  /**
+   * (Android) Whether a status bar color that is opaque is drawn at 65% opacity, so the screen shows through. A color
+   * that is already partly transparent stays as it is, and with edge-to-edge the default color is transparent, so
+   * there is nothing to change. It does not blur. It applies when the screen appears and through `mergeOptions`.
+   * @default false
+   */
+  translucent?: boolean;
+  /**
+   * (iOS) Whether a change of `style` animates, over 0.35 s. `false` changes it at once. The visibility never
+   * animates.
+   * @default true
+   */
+  animate?: boolean;
+  /**
+   * (iOS) Whether the status bar hides while the top bar of the screen's stack is hidden. An explicit `visible` wins.
+   * The value is read when the system asks about the status bar, and the system is asked again whenever the stack's
+   * top bar shows or hides, by an option or by scrolling, a tap or the keyboard (not for the bar of a tab opened from
+   * More).
+   * @default false
+   */
+  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.
+   * @default false
+   */
+  blur?: boolean;
+}
+
+/**
+ * (Android) The navigation bar of Android (three buttons or gestures) while the screen shows. The screen on top
+ * decides. A `mergeOptions` call without `navigationBar` leaves the bar as it is. iOS has no such bar; the home
+ * indicator is `layout.autoHideHomeIndicator`.
+ */
+export interface NavigationBarOptions {
+  /**
+   * The color of the navigation bar, one for each appearance when it is `{ light, dark }`. Without it, and with
+   * `null`, and when the screens go under the bar (see `drawBehind`): nothing over the gesture bar, and over the
+   * three buttons a translucent plate, white at 90% with dark buttons in the light theme and `#1B1B1B` at 50% with
+   * light buttons in the dark theme. When the screens stay above the bar (`drawBehind: false`, or without
+   * edge-to-edge): the bottom tabs' color while the screen is in bottom tabs, else the `android:navigationBarColor` of
+   * the app theme if the theme sets its own, otherwise black (black at 80% over three buttons). An opaque color gives
+   * a bar of that color with the screens above it. A color with transparency lets the screens go under the bar and
+   * draws the color over them. The buttons are dark on a light color and light on a dark one. It applies when the
+   * screen appears or comes back on top, at once through `mergeOptions` that contains `navigationBar`, on a theme or
+   * configuration change, and when the user switches between gestures and three buttons. On Android 7 (API 24–25) the
+   * buttons are always light, so a light color there gives light buttons on it.
+   */
+  backgroundColor?: Color;
+  /**
+   * Whether the navigation bar shows. `false` hides it; it comes back for a moment on a swipe from the edge, and the
+   * screen gets the room of the bar (its inset is 0). It applies when the screen appears or comes back on top and, in
+   * `mergeOptions`, at once if the call sets it.
+   * @default true
+   */
+  visible?: boolean;
+  /**
+   * Whether the screens go under a navigation bar that shows. Without it, they go under it when edge-to-edge is on
+   * and the bar has no opaque color of its own; the safe area then keeps the content above the bar (the bottom of
+   * `useSafeAreaInsets()`), the background of the tab row goes under the bar and the tabs themselves stay above it.
+   * Without edge-to-edge the window ends above the bar. `true` always goes under the bar (without edge-to-edge it
+   * changes nothing). `false` keeps the screens above the bar, which then has its own color. It applies when the
+   * screen appears and through `mergeOptions`, which asks for the window insets again.
+   */
+  drawBehind?: boolean;
+}
+
+/** A key held with the key of a shortcut: `'command'`, `'shift'`, `'option'` (also `'alternate'`) or `'control'`. */
+export type OptionsKeyCommandModifier = 'command' | 'shift' | 'option' | 'alternate' | 'control';
+
+/**
+ * (iOS) A keyboard shortcut of a screen, for a hardware keyboard on iPad or iPhone. A press reports the `id` to the
+ * app as a key command event. The shortcuts belong to the screen while it shows, and work as long as no one else holds
+ * the keyboard and also while a text field of the screen has focus. The array of `keyCommands` replaces the one from a
+ * lower layer. The screen's own shortcuts count first and the shortcuts of its stack or tabs apply to its screens that
+ * have none; the default options of the app do not take part. The system lists the shortcuts that have a `title`
+ * when the user holds the Command key on iPad.
+ */
+export interface OptionsKeyCommand {
+  /** The identifier the key command event reports. An item without a string `id` is skipped. */
+  id: string;
+  /**
+   * The key: a character (`'n'`, `'['`) or a name: `'escape'`, `'enter'`, `'tab'`, `'delete'` (backspace), `'up'`,
+   * `'down'`, `'left'` or `'right'` (the arrow keys). An item without a string `input` is skipped.
+   */
+  input: string;
+  /** The keys held together with `input`; unknown names are ignored. Without them, the key alone triggers it. */
+  modifiers?: OptionsKeyCommandModifier[];
+  /**
+   * The name in the list of shortcuts the system shows. Without it, the shortcut works but does not show in the
+   * list.
+   */
+  title?: string;
+}