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

package/src/interfaces/options/buttons.ts

@@ -0,0 +1,364 @@
+import type { Color, FontFamily, FontStyle, FontWeight, ImageResource } from './common';
+
+/**
+ * The system button a button shows. On iOS it is the system item of the same name, with the text of the user's
+ * language; a name the system doesn't know shows `'done'`. On Android only `'close'` is read: it draws the library's
+ * close icon when the button has no `icon` of its own, and every other name is ignored.
+ */
+export type SystemItemIcon =
+  | 'done'
+  | 'cancel'
+  | 'edit'
+  | 'save'
+  | 'add'
+  | 'flexibleSpace'
+  | 'fixedSpace'
+  | 'compose'
+  | 'reply'
+  | 'action'
+  | 'organize'
+  | 'bookmarks'
+  | 'search'
+  | 'refresh'
+  | 'stop'
+  | 'camera'
+  | 'trash'
+  | 'play'
+  | 'pause'
+  | 'rewind'
+  | 'fastForward'
+  | 'undo'
+  | 'redo'
+  | 'close';
+
+/** (iOS) The space around the image of an icon, in points. */
+export interface IconInsets {
+  /**
+   * The space above the image, in points.
+   * @default 0
+   */
+  top?: number;
+  /**
+   * The space left of the image, in points.
+   * @default 0
+   */
+  left?: number;
+  /**
+   * The space below the image, in points.
+   * @default 0
+   */
+  bottom?: number;
+  /**
+   * The space right of the image, in points.
+   * @default 0
+   */
+  right?: number;
+}
+
+/**
+ * A filled shape behind the icon of a button or of the back button. It takes effect only when `color` is set; without
+ * a color the other fields are ignored.
+ *
+ * On iOS the icon is drawn onto the shape and the button becomes a button of its own (the back button keeps its
+ * history menu), without the glass capsule on iOS 26 by default. On Android the icon sits on the shape, mirrored in a
+ * right-to-left layout. Layers merge differently: on iOS an object merges field by field like any other, on Android
+ * an `iconBackground` that has a `color` replaces the earlier one as a whole.
+ */
+export interface IconBackgroundOptions {
+  /** The color of the shape. Without it the whole `iconBackground` has no effect. */
+  color?: Color;
+  /**
+   * The color of the shape while the button is disabled. Without it the shape keeps `color` on iOS and disappears on
+   * Android. The back button is never disabled, so it ignores this field.
+   */
+  disabledColor?: Color;
+  /**
+   * The radius of the corners of the shape, in points (iOS) or dp (Android).
+   * @default 0
+   */
+  cornerRadius?: number;
+  /** The width of the shape, in points or dp. By default the width of the icon; on Android never less than that. */
+  width?: number;
+  /** The height of the shape, in points or dp. By default the height of the icon; on Android never less than that. */
+  height?: number;
+}
+
+/**
+ * An item of a menu. Picking it sends a button press with its `id` to the screen, and the screen runs the `onPress`
+ * of the item that has this id. Item ids and button ids of one screen must not repeat.
+ */
+export interface OptionsTopBarButtonMenuItem {
+  /**
+   * The id of the item, sent as `buttonId` when the item is picked. An item without an id sends nothing on iOS.
+   */
+  id?: string;
+  /** The text of the item. Without it the item shows an empty string. */
+  title?: string;
+  /**
+   * The icon in front of the text. On iOS an SF Symbol or an image; on Android a drawable resource or an image
+   * source. On Android the icons show in the menu as soon as one item has one, tinted like the menu's other icons (the
+   * error color for a destructive item). An icon that fails to load leaves the item without one.
+   */
+  icon?: ImageResource;
+  /** Whether the item is drawn as a destructive action: red on both platforms. */
+  destructive?: boolean;
+  /** Whether the item is shown but can't be picked. */
+  disabled?: boolean;
+  /**
+   * Whether the item carries a check mark. On Android the item is checkable, also outside a `singleSelection` menu.
+   * With `singleSelection` on the menu, picking an item moves the mark to it, and `mergeOptions` with `checked`
+   * moves it from code.
+   */
+  checked?: boolean;
+  /**
+   * The identifier tests find the item by: the accessibility identifier on iOS, the resource id and view tag of the
+   * item on Android. Where the system gives no way to set it, the item is found by its text.
+   */
+  testID?: string;
+}
+
+/** A submenu: an item that opens a menu of its own, of any depth. Submenus carry no check mark. */
+export interface OptionsTopBarButtonSubmenu {
+  /** The text of the submenu item. Without it the item shows an empty string. */
+  title?: string;
+  /** The icon of the submenu item, as for a menu item. */
+  icon?: ImageResource;
+  /** Whether only one item of this submenu can be checked at a time. */
+  singleSelection?: boolean;
+  /** The items and submenus, in order. */
+  items: OptionsTopBarButtonMenuElement[];
+  /** The identifier tests find the submenu item by, as for a menu item. */
+  testID?: string;
+}
+
+/** An item or a submenu of a menu. An element with `items` is a submenu. */
+export type OptionsTopBarButtonMenuElement =
+  OptionsTopBarButtonMenuItem | OptionsTopBarButtonSubmenu;
+
+/**
+ * A menu of the top bar: the menu of a button, the overflow menu, the menu of the title. A list of `items` sent with
+ * `mergeOptions` replaces the earlier list as a whole, and `items: []` removes the menu; `title` and
+ * `singleSelection` merge field by field (iOS). What the user picks in a `singleSelection` menu is written back into
+ * the options of the screen and survives the screen showing again.
+ */
+export interface OptionsTopBarButtonMenu {
+  /** The title above the items. (iOS) Android doesn't show it. */
+  title?: string;
+  /**
+   * Whether only one item of the top level can be checked at a time: picking an item moves the check mark to it. On
+   * iOS this is the system's single-selection menu; on Android the items are checkable.
+   */
+  singleSelection?: boolean;
+  /** The items and submenus, in order. An empty list removes the menu. */
+  items?: OptionsTopBarButtonMenuElement[];
+}
+
+/**
+ * A button of the top bar (`leftButtons`, `rightButtons`, `centerButtons`) or of the toolbar (`toolbar.buttons`). The
+ * kinds are picked by the fields that are set. On iOS, the first that fits wins: a `component`, then an icon with text
+ * and `showText`, then an icon with `iconBackground` or `iconInsets`, then an SF Symbol, an image `icon`, a `text`,
+ * a `systemItem`; a button with none of them is not shown. On Android a button is a menu item of the bar: text, icon
+ * or a component. Lists of buttons are replaced as a whole and take nothing from the lists of lower layers.
+ *
+ * Text, icon, color and similar fields are the same in all four places; where a place or a side differs, the field
+ * says so.
+ */
+export interface OptionsTopBarButton {
+  /**
+   * The id of the button: the `buttonId` of its press, the key of the press handler, of a toggle's state and of a
+   * menu's choice, and the source of a popover (`modal.popover.sourceButtonId`). Required: a button without an id is
+   * not shown on either platform, the error goes to the log, and in development to a red box.
+   */
+  id: string;
+  /** (Android) Whether the text is drawn in capitals. Without it, as the theme says (not in capitals in Material 3). */
+  allCaps?: boolean;
+  /**
+   * The icon: an image, or an icon for each platform (`{ ios: 'SF Symbol', android: 'resource' }`). A platform
+   * without its side shows no icon.
+   *
+   * On iOS an SF Symbol without a `color` is drawn as a template in the color of the bar and fades when disabled
+   * (`disableIconTint` keeps its own colors); an image is drawn as it is, tinted when a color is set. With a `text`,
+   * the text becomes the button's label: the bar shows only the icon, the overflow menu and the customization panel
+   * show the text. An image with `iconBackground` or `iconInsets` makes a button of its own.
+   *
+   * On Android the icon is a drawable resource of the app or an image source, tinted with `color` (`disabledColor`
+   * when disabled), or as it is without one. An icon that fails to load leaves the button without it, with its `text`
+   * if it has one, and reports the error to the log (in development, a red box).
+   */
+  icon?: ImageResource;
+  /**
+   * (iOS) The space around the image of `icon`; the button becomes a button of its own, without a capsule on iOS 26.
+   */
+  iconInsets?: IconInsets;
+  /**
+   * A React component as the button. The component handles its own touches: the bar sends no press for it, and
+   * `menu`, `toggle` and `style` have no effect. It is drawn before the screen shows.
+   */
+  component?: OptionsTopBarButtonComponent;
+  /**
+   * The system button. Only `'close'` works on Android. On the toolbar, spaces and the search field have objects of
+   * their own (`OptionsToolbarSpace`, `OptionsToolbarSearchField`).
+   */
+  systemItem?: SystemItemIcon;
+  /**
+   * The text of the button. A button with an icon keeps it as a label for the overflow menu, the customization panel
+   * and VoiceOver (iOS) or as the text of the menu item (Android, where it also shows when there is room).
+   */
+  text?: string;
+  /** The text a screen reader says for the button. */
+  accessibilityLabel?: string;
+  /**
+   * The font family of the text. On iOS the font is built from all font options together, the size defaulting to 17.
+   */
+  fontFamily?: FontFamily;
+  /** The slant of the text. */
+  fontStyle?: FontStyle;
+  /** The weight of the text. */
+  fontWeight?: FontWeight;
+  /** The size of the text: points on iOS (17 once any font option is set), sp on Android. */
+  fontSize?: number;
+  /**
+   * Whether the button reacts. A disabled button is dimmed (see `disabledColor`) and a press does nothing.
+   * @default true
+   */
+  enabled?: boolean;
+  /**
+   * Whether the icon keeps its own colors instead of being tinted. On iOS an SF Symbol stays multicolor and a side
+   * color from `mergeOptions` doesn't repaint it; on Android the icon gets no tint.
+   */
+  disableIconTint?: boolean;
+  /**
+   * The color of the text and of the icon; it beats the color of the side (`leftButtonColor` and the like). On iOS a
+   * `'prominent'` button uses it only as the tint of its capsule.
+   */
+  color?: Color;
+  /** The color while the button is disabled; it beats the color of the side. Android defaults to light gray. */
+  disabledColor?: Color;
+  /**
+   * A shape behind the icon. It works with an `icon` image and a `color` of the shape; on iOS the button becomes a
+   * button of its own without menu, toggle or style, and without a capsule on iOS 26 by default. The color of a whole
+   * side is `leftButtonBackgroundColor` / `rightButtonBackgroundColor`.
+   */
+  iconBackground?: IconBackgroundOptions;
+  /**
+   * (iOS) `'plain'` or `'prominent'`, the main action of the bar (Done, Send). On iOS 26 a prominent button is a
+   * capsule in the button's tint with bold text or icon on it (the tint is `color`, the bar's tint without it);
+   * before iOS 26 it is the system's done style with bold text. Not for component buttons, buttons with
+   * `iconBackground`, and `showText` buttons.
+   * @default 'plain'
+   */
+  style?: 'plain' | 'prominent';
+  /**
+   * The identifier tests find the button by: the accessibility identifier on iOS, the resource id and the view tag
+   * on Android (in the bar and in the overflow menu). A component button puts it on its slot; the component sets its
+   * own inside.
+   */
+  testID?: string;
+  /**
+   * (iOS 26+) Whether the button has no glass capsule under it; neighbors keep theirs. By default `true` for
+   * component buttons and for icon buttons with a background or insets, `false` for the rest. In a `group` of several
+   * buttons the capsule is shared and this has no effect. A change by `mergeOptions` builds the buttons anew.
+   */
+  hideSharedBackground?: boolean;
+  /**
+   * (iOS) Whether a button with an `icon` and a `text` shows both side by side, as one button on the bar's glass. The
+   * button is a view of its own; `color`, the side color, fonts, `enabled`, `badge`, `group`, `testID` and
+   * `accessibilityLabel` work, while `menu`, `toggle`, `style` and `iconBackground` don't. In the overflow menu it
+   * is an item with text and icon. For the bar and the toolbar.
+   */
+  showText?: boolean;
+  /**
+   * (iOS 26+) Buttons next to each other with the same group share one capsule; a button without a group has its
+   * own. Before iOS 26 it does nothing, on iOS 15 there are no groups. A side that has a group of several buttons
+   * doesn't animate button changes. The toolbar has no groups: only icons share a capsule there. For center buttons
+   * the group is a section of the overflow menu, and its name is the id the customization is saved under.
+   */
+  group?: string;
+  /**
+   * (iOS 26+) A badge on the button: a number, a short text, or `true` for a dot. `0`, `''`, `false` and `null` show
+   * none. `mergeOptions` changes it on the fly. The toolbar doesn't draw badges.
+   */
+  badge?: number | string | boolean | null;
+  /** (iOS 26+) The color of the badge. Without it, the system red. */
+  badgeColor?: Color;
+  /** (iOS 26+) The color of the number or text of the badge. Without it, white. */
+  badgeTextColor?: Color;
+  /**
+   * (iOS) Whether the button is a toggle: every press flips `selected` and sends a press with the new state. The state
+   * is written into the options of the screen under the button's id, so it survives the screen showing again, and a
+   * button set again without `selected` takes the state of the button with the same id. Not for component buttons,
+   * buttons with `iconBackground`, and `showText` buttons.
+   */
+  toggle?: boolean;
+  /**
+   * (iOS) Whether the button is drawn as switched on: on iOS 26 filled with its color, with the icon or text on it.
+   * For a toggle this is the starting state, and `mergeOptions` flips it from code. Works without `toggle` too.
+   * @default false
+   */
+  selected?: boolean;
+  /**
+   * The menu of the button. It opens on a press, or on a long press with `menuOnLongPress`. A pick sends a press with
+   * the id of the item. On iOS it is the system menu (on the toolbar it opens upward), not for component buttons and
+   * buttons with `iconBackground`; on Android a popup under the button without a title (from the end of the bar for a
+   * button in the overflow), not for component buttons.
+   */
+  menu?: OptionsTopBarButtonMenu;
+  /**
+   * Whether a press does the button's own action (a press event, a toggle) and the menu opens on a long press.
+   * Without it the menu opens on a press.
+   * @default false
+   */
+  menuOnLongPress?: boolean;
+  /**
+   * (iOS 16+) For a center button, when `topBar.customizationId` is set: `'fixed'` stays in place, `'movable'` moves
+   * but can't be removed, `'optional'` moves and can be removed and added back in the customization panel. A group
+   * moves as a whole. Renaming a group or a button resets the saved customization.
+   * @default 'movable'
+   */
+  customization?: 'fixed' | 'movable' | 'optional';
+  /**
+   * (iOS 16+) Whether an `'optional'` center button is in the bar before the user customizes it. With `false` the user
+   * adds it from the customization panel. On iPhone center buttons are in the overflow menu anyway.
+   * @default true
+   */
+  shownByDefault?: boolean;
+  /**
+   * Whether a right button stays out of the overflow menu. On iOS 16+ it goes to the pinned group at the trailing
+   * edge, behind the overflow button, in a capsule of its own (several pinned buttons share it); when space runs
+   * out iOS hides the title first. On Android it stays in the bar while other right buttons move to the overflow when
+   * they don't fit. No effect on left and center buttons.
+   * @default false
+   */
+  pinned?: boolean;
+  /**
+   * Which buttons move to the overflow menu last: `'high'` stays longest, `'low'` goes first. On iOS 27+ it is the
+   * visibility priority of the button (it matters in the narrow vertical bar of iPhone Duo too); before iOS 27 it
+   * does nothing. On Android the bar keeps the right buttons of the highest priority, ties in list order.
+   * @default 'standard'
+   */
+  priority?: 'high' | 'standard' | 'low';
+  /**
+   * (iOS 27.1+) Whether the button may move to the vertical bar of iPhone Duo: `true` allows it, a component button
+   * too, narrowed to the width of the bar; `false` keeps it in the horizontal row. Without it the system decides
+   * and a component button stays in the row.
+   */
+  vertical?: boolean;
+}
+
+/**
+ * The React component of a bar button. The props stay in JavaScript under the id of the component; with the same
+ * `name` and `id` a `mergeOptions` with new `passProps` updates the mounted component, a different `id` or `name`
+ * replaces it.
+ */
+export interface OptionsTopBarButtonComponent {
+  /** The id of the component. Without it, the library gives one. The same `name` and `id` mean the same component. */
+  id?: string;
+  /** The name of the registered component. */
+  name: string;
+  /** The props of the component. They stay in JavaScript; the native side never sees them. */
+  passProps?: object;
+  /** (Android) The width of the component, in dp. The cell around it is wider by its margins. */
+  width?: number;
+  /** (Android) The height of the component, in dp. */
+  height?: number;
+}

package/src/interfaces/options/common.ts

@@ -0,0 +1,76 @@
+import type { ColorValue, ImageRequireSource, ImageURISource } from 'react-native';
+
+/**
+ * A color for the light and for the dark appearance of the interface. The native side switches between them by
+ * itself when the appearance changes. A side left out shows the platform's own look in that appearance, as if the
+ * option were not set.
+ */
+export interface ThemeColor {
+  /** The color in the light appearance: a color string or a `PlatformColor`. */
+  light?: ColorValue;
+  /** The color in the dark appearance: a color string or a `PlatformColor`. */
+  dark?: ColorValue;
+}
+
+/**
+ * A color of an option: a color string (`'#1E88E5'`, `'rgba(0,0,0,0.5)'`, `'red'`), a `PlatformColor` or
+ * `DynamicColorIOS`, or `{ light, dark }` for each appearance. `null` takes the color away: the element shows as the
+ * platform draws it without the option, also over a color its stack, its tabs or the default options give. A color
+ * string the app can't parse counts as not set.
+ */
+export type Color = ColorValue | ThemeColor | null;
+
+/**
+ * An image of an option: `require('./icon.png')`, a source with a `uri` (a file, an asset of the app's bundle, a
+ * `data:` address on iOS), the name of an Android drawable resource, or a different icon for each platform
+ * (`{ ios, android }`). Remote addresses (`https:`) are not loaded, apart from Metro's assets in development; an
+ * image that doesn't load leaves its element without an icon and reports the error in development.
+ */
+export type ImageResource = ImageRequireSource | ImageURISource | string | PlatformIcon;
+
+/**
+ * A different icon for each platform: `{ ios: 'square.and.arrow.up', android: 'ic_share' }`. A string is the name of
+ * an SF Symbol on iOS and of a drawable resource of the app on Android; an image source works on either side. A
+ * platform without its side shows no icon.
+ */
+export interface PlatformIcon {
+  /** The icon on iOS: the name of an SF Symbol, or an image. */
+  ios?: string | ImageRequireSource | ImageURISource;
+  /** The icon on Android: the name of a drawable resource of the app, or an image. */
+  android?: string | ImageRequireSource | ImageURISource;
+}
+
+/**
+ * The weight of a font: `'normal'`, `'bold'` or `'100'`–`'900'`; on iOS also the names of UIKit's weights. An unknown
+ * value draws the normal weight.
+ */
+export type FontWeight =
+  | 'normal'
+  | 'bold'
+  | '100'
+  | '200'
+  | '300'
+  | '400'
+  | '500'
+  | '600'
+  | '700'
+  | '800'
+  | '900'
+  | 'ultralight'
+  | 'thin'
+  | 'light'
+  | 'regular'
+  | 'medium'
+  | 'semibold'
+  | 'heavy'
+  | 'black';
+
+/** The slant of a font, on both platforms. */
+export type FontStyle = 'normal' | 'italic';
+
+/**
+ * The family of a font: a font the app ships (iOS: listed under `UIAppFonts` in `Info.plist`; Android: in
+ * `assets/fonts/` or a `res/font` resource React Native knows), or a system family by name. A family that isn't found
+ * draws the system font.
+ */
+export type FontFamily = string;

package/src/interfaces/options/modals.ts

@@ -0,0 +1,217 @@
+/**
+ * How the platform presents a modal: `'pageSheet'`, `'formSheet'`, `'fullScreen'`, `'overFullScreen'`,
+ * `'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.
+ *
+ * - `'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.
+ * - `'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.
+ *
+ * The options of the sheet (`modal.sheet`) apply with `'pageSheet'`, `'formSheet'` and without a style.
+ */
+export type OptionsModalPresentationStyle =
+  | 'pageSheet'
+  | 'formSheet'
+  | 'fullScreen'
+  | 'overFullScreen'
+  | 'overCurrentContext'
+  | 'currentContext'
+  | 'popover';
+
+/**
+ * (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.
+ */
+export type OptionsModalTransitionStyle =
+  'coverVertical' | 'crossDissolve' | 'flipHorizontal' | 'partialCurl';
+
+/**
+ * A stop of a sheet: `'medium'` (about half of the screen), `'large'` (the full height), a number (a height in points
+ * on iOS, in dp on Android) or `'content'` (the height of the screen's content).
+ *
+ * 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.
+ */
+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
+ * 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']`.
+   * @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.
+   * Without it, the lowest stop.
+   */
+  selectedDetent?: OptionsModalSheetDetent;
+  /**
+   * The highest stop on which the screen below the sheet stays bright and takes touches, like the sheet of a map. On
+   * Android the dimming grows from none at this stop to a dark veil at the next higher one, and a tap on the dimmed
+   * part closes the sheet. `null`, or a value that isn't among `detents`, dims at every stop. Without it, the same.
+   */
+  largestUndimmedDetent?: OptionsModalSheetDetent | null;
+  /**
+   * Whether the sheet shows a handle at the top to drag it by: the system handle on iOS, the Material drag handle on
+   * Android.
+   * @default false
+   */
+  grabber?: boolean;
+  /**
+   * Whether a scroll in the content that starts at the top of a list first moves the sheet: a drag up raises the sheet
+   * to a higher stop, a drag down lowers it. With `false` the content scrolls by itself and the sheet is dragged by
+   * its top only (on Android the top 48 dp strip). On Android the sheet turns on nested scrolling for the React Native
+   * scroll views inside it to do this.
+   * @default true
+   */
+  expandsOnScroll?: boolean;
+  /**
+   * The corner radius of the sheet, in points on iOS and dp on Android. On iOS UIKit uses it only when the sheet is
+   * the front one of a pile of sheets; on Android only the top corners are rounded. Without it, the system radius
+   * (28 dp on Android).
+   */
+  cornerRadius?: number;
+  /**
+   * The test identifier of the sheet's container on Android. The handle gets `<testID>.grabber` (below Android 10 as
+   * its tag only, without a resource name) and the dimming under the sheet `<testID>.scrim`. iOS draws the sheet, its
+   * handle and its dimming itself, and gives no public way to name them; there find the sheet by its content, and the
+   * content of the screen carries its own `testID`.
+   */
+  testID?: string;
+}
+
+/** A side of a popover's arrow. */
+export type PopoverArrowDirection = 'up' | 'down' | 'left' | 'right';
+
+/**
+ * (iOS) The size of a modal shown as a form sheet or a popover, where UIKit doesn't stretch it over the screen (iPad,
+ * Mac). It is the preferred content size of the modal's root. It applies when the modal shows, once more just after it
+ * has shown, after the content mounts when the height is `'content'`, after a push or pop in the modal's stack, and
+ * after `mergeOptions` on any screen of the modal. On iPhone a form sheet is a sheet and the size does nothing.
+ */
+export interface OptionsModalContentSize {
+  /** The width in points. Without it, or `0`, the width UIKit gives the style. */
+  width?: number;
+  /**
+   * The height in points, or `'content'` for the height of the content of the screen the modal shows, measured at the
+   * modal's width (`width`, otherwise its current width) and followed as the content changes. Without it, the height
+   * UIKit gives the style.
+   */
+  height?: number | 'content';
+}
+
+/**
+ * (iOS) Where a popover points and how it behaves, for a modal shown with `modalPresentationStyle: 'popover'`. It is
+ * read when the modal shows and doesn't change afterwards. The source is looked up on the presenting layout, the
+ * topmost one shown (the root or the top modal). Without a source, or when the source isn't found, the popover stands
+ * in the middle of the presenting screen without an arrow, and a missing source that was named is reported in the log.
+ * Tapping outside the popover dismisses it, or sends `modalDismissAttempted` while the modal is held. Android has no
+ * popovers and ignores this.
+ */
+export interface OptionsModalPopover {
+  /**
+   * The `id` of a button of the top bar or the toolbar of the presenting screen to point at. It is looked up in every
+   * screen shown by the presenting layout (in a split view, in every visible column), among left and right buttons,
+   * toolbar buttons and button groups. From iOS 16 the popover attaches to the button as a source item, and on iOS 26 it
+   * opens out of the button. It goes before `sourceNativeID`.
+   */
+  sourceButtonId?: string;
+  /**
+   * The `nativeID` of a React view of the presenting layout to point at; the arrow points at the frame of the view.
+   * It is looked up in the whole view hierarchy of the presenting layout.
+   */
+  sourceNativeID?: string;
+  /**
+   * The sides the arrow may point from. Unknown values are skipped. Without it, or with an empty list, any side. With
+   * no source there is no arrow.
+   */
+  arrowDirections?: PopoverArrowDirection[];
+  /**
+   * Whether UIKit may turn the popover into a sheet in a compact width (iPhone, a narrow window of iPad). With
+   * `false` the popover keeps its arrow there too.
+   * @default true
+   */
+  adaptive?: boolean;
+}
+
+/**
+ * The options of a screen shown as a modal. They are read from the final options of the modal when it shows: the
+ * options of its root, over them the options of its visible screen, over them the default options. On a screen that
+ * isn't in a modal they do nothing. A value of the wrong type is skipped without a crash.
+ */
+export interface ModalOptions {
+  /** The settings of a sheet: its stops, dimming, handle, scrolling and corners. */
+  sheet?: OptionsModalSheet;
+  /** (iOS) The size of a form sheet or a popover on iPad and Mac. */
+  contentSize?: OptionsModalContentSize;
+  /** (iOS) The source and the arrow of a popover. */
+  popover?: OptionsModalPopover;
+  /**
+   * The test identifier of the modal's container: on iOS the view of the root of the shown modal, on Android the
+   * modal's view in the layer of modals (for a sheet, the container of the sheet). The identifiers of the sheet's
+   * handle and of the dimming under it are `<testID>.grabber` and `<testID>.scrim`, on Android only: iOS gives no
+   * public way to name the system handle and dimming. The close button and the content of the screens have their own
+   * `testID`.
+   */
+  testID?: string;
+  /**
+   * Whether the user may dismiss the modal by a gesture: a swipe down on a sheet, a tap on the dimming, a tap outside a
+   * popover. With `false` the modal stays and each attempt arrives as `modalDismissAttempted`. A full-screen modal
+   * can't be dismissed by a gesture anyway. The hold belongs to the screen that set it and ends when that screen
+   * leaves the modal or lifts the hold. Set by `usePreventLeave` through `mergeOptions`; apps don't set it.
+   * @default true
+   * @internal
+   */
+  swipeToDismiss?: boolean;
+}
+
+/**
+ * The options of a screen shown as an overlay: a screen over the whole app that takes the place of no screen, such as
+ * a toast, a banner or a mini player. They are read from the final options of the overlay's root with the default
+ * options, and can change through `mergeOptions` while the overlay shows. On a screen that isn't in an overlay they do
+ * nothing.
+ */
+export interface OverlayOptions {
+  /**
+   * Whether the overlay keeps the touches that land outside its own views. With `false` those touches reach the app
+   * under the overlay; with `true` they stop at the overlay. A touch counts as inside when it lands on a view of the
+   * content that takes touches, so a full-screen wrapper with `pointerEvents="box-none"` lets touches through. A
+   * dialog with a dimmed background gets the touches on the background by being a view of its own.
+   * @default false
+   */
+  interceptTouchOutside?: boolean;
+  /**
+   * The test identifier of the overlay's container: on iOS the root view of the overlay's window, on Android the
+   * overlay's view in the layer of overlays. The content of the screen has its own `testID`.
+   */
+  testID?: string;
+}