@apexnative/navigation 1.0.0-alpha.5 → 1.0.0-alpha.7

package/src/engine/refresh.ts

@@ -0,0 +1,97 @@
+// Fast Refresh runs an edited module again, and every component it exports is a new function. React Refresh keeps
+// the versions of one component in a family: Metro registers each export under its module and name, and React renders
+// the newest version of the family in place of the old one. What the library keeps of a screen (its options, its key,
+// its pair) is read through the same family, so an edit reaches it without a reload.
+
+/** The versions of one component React Refresh keeps, `current` the newest. */
+interface Family {
+  current: unknown;
+}
+
+interface ReactRefresh {
+  getFamilyByType?: (type: unknown) => Family | undefined;
+  register?: (type: unknown, id: string) => void;
+  createSignatureFunctionForTransform?: () => (
+    type: unknown,
+    key: string,
+    forceReset?: boolean
+  ) => unknown;
+}
+
+// React Native puts React Refresh where Metro's module system finds it, in development only.
+function reactRefresh(): ReactRefresh | undefined {
+  if (!__DEV__) return undefined;
+  const global = globalThis as { __METRO_GLOBAL_PREFIX__?: string } & Record<string, unknown>;
+  return global[`${global.__METRO_GLOBAL_PREFIX__ ?? ''}__ReactRefresh`] as
+    ReactRefresh | undefined;
+}
+
+/** Whether React Refresh runs: development with Metro. */
+export function refreshRuns(): boolean {
+  return reactRefresh()?.getFamilyByType !== undefined;
+}
+
+/** The family a component's versions are kept in; undefined in a release build or for a value Metro didn't export. */
+export function familyOf(type: unknown): Family | undefined {
+  return reactRefresh()?.getFamilyByType?.(type);
+}
+
+/**
+ * The newest version of a component after Fast Refresh ran its module again; the component itself when there is none
+ * newer, and in a release build.
+ */
+export function newestType<T extends object>(type: T): T {
+  return (familyOf(type)?.current as T | undefined) ?? type;
+}
+
+let redefinedListener: ((screen: object) => void) | undefined;
+
+/** Sets what runs when a module makes a screen again: Fast Refresh ran it after an edit. */
+export function onRedefined(listener: (screen: object) => void): void {
+  redefinedListener = listener;
+}
+
+/**
+ * Tells about a screen a module made, once the module ran: Metro registers its exports after it, so the family of the
+ * screen is known by then, and a new version of a screen that shows is found by it. Development only.
+ */
+export function redefined(screen: object): void {
+  if (!__DEV__ || !redefinedListener) return;
+  const listener = redefinedListener;
+  Promise.resolve().then(() => listener(screen));
+}
+
+// The id each family of screens gives the components they render, so their versions join one family too.
+const innerIds = new WeakMap<Family, string>();
+let innerCount = 0;
+
+/**
+ * Puts a component a screen or the app renders (`owner`: the screen, or the app made by createNavigation; `role`: which
+ * of its components) in a family of its own, once the owner's module ran and Metro has given the owner its family: the
+ * next version of the owner registers its component under the same id, so React Refresh keeps the component's state
+ * when the module runs again, also when the module doesn't export it. A component React Refresh knows already (its
+ * module exports it, or Babel registered it) keeps its own family. Development only.
+ */
+export function keepStateOf(owner: object, component: unknown, role = 'component'): void {
+  const refresh = reactRefresh();
+  if (!refresh?.register || component === undefined) return;
+  const register = refresh.register;
+  Promise.resolve().then(() => {
+    const family = familyOf(owner);
+    if (!family) return;
+    let id = innerIds.get(family);
+    if (id === undefined) {
+      id = `apexnative.navigation#${++innerCount}`;
+      innerIds.set(family, id);
+    }
+    register(component, `${id}.${role}`);
+  });
+}
+
+/**
+ * Makes React Refresh mount a component of the library again, not keep its state, when a new version of it comes: its
+ * hooks are the app's, which may have changed, and the library's code has no signature of them. Development only.
+ */
+export function resetOnEdit(type: object): void {
+  reactRefresh()?.createSignatureFunctionForTransform?.()(type, 'apexnative.navigation', true);
+}

package/src/engine/rememberedOptions.ts

@@ -29,9 +29,77 @@ export function rememberMergedOptions(id: string, options: Options): void {
   remembered.set(id, before ? mergeOptions(before, kept) : kept);
 }
 
+/** Takes the options at the paths, such as `['topBar', 'subtitle']`, out of those remembered for the node with the id. */
+export function forgetMergedPaths(id: string, paths: readonly string[][]): void {
+  const own = ownOptions.get(id);
+  if (own) own.options = withoutPaths(own.options, paths);
+  const options = remembered.get(id);
+  if (options) remembered.set(id, withoutPaths(options, paths));
+}
+
+// A copy of the options without the values at the paths.
+function withoutPaths(options: Options, paths: readonly string[][]): Options {
+  const kept = structuredCopy(options);
+  for (const path of paths) {
+    const parent = path
+      .slice(0, -1)
+      .reduce<Record<string, unknown> | undefined>(
+        (group, key) => group?.[key] as Record<string, unknown> | undefined,
+        kept
+      );
+    if (parent) delete parent[path[path.length - 1]!];
+  }
+  return kept as Options;
+}
+
+// A copy of the plain objects of options, the other values shared.
+function structuredCopy(options: Options): Record<string, unknown> {
+  return Object.fromEntries(
+    Object.entries(options).map(([key, value]) => [
+      key,
+      isGroup(value) ? structuredCopy(value as Options) : value,
+    ])
+  );
+}
+
+function isGroup(value: unknown): boolean {
+  return (
+    typeof value === 'object' && value !== null && Object.getPrototypeOf(value) === Object.prototype
+  );
+}
+
 /** Forgets the merged options of a node that went; a node of the last root keeps them until another root goes out. */
 export function forgetMergedOptions(id: string): void {
   if (!lastRoot?.ids.has(id)) remembered.delete(id);
+  ownOptions.delete(id);
+}
+
+// The own options of each screen as JavaScript sent them, in development: those it showed with, and every merge and
+// clear since. An edit of a screen's options (Fast Refresh) changes only what still has the old definition's value.
+const ownOptions = new Map<string, { name: string; options: Options }>();
+
+/** Notes the own options a screen of the name shows with (development). */
+export function noteOwnOptions(id: string, name: string, options: Options): void {
+  if (__DEV__) ownOptions.set(id, { name, options });
+}
+
+/** Notes a merge into a screen's own options (development). */
+export function noteMergedOwnOptions(id: string, options: Options): void {
+  const noted = __DEV__ ? ownOptions.get(id) : undefined;
+  if (noted) noted.options = mergeOptions(noted.options, options);
+}
+
+/** The own options of a screen as JavaScript sent them (development); undefined for a screen it didn't note. */
+export function ownOptionsOf(id: string): Options | undefined {
+  return ownOptions.get(id)?.options;
+}
+
+/**
+ * The ids of the screens of the name the native side has, mounted in React or not yet (a tab not selected yet), as
+ * development notes them.
+ */
+export function notedScreens(name: string): string[] {
+  return [...ownOptions].filter(([, noted]) => noted.name === name).map(([id]) => id);
 }
 
 /** The options merged into the node with the id, as remembered; undefined without any. */
@@ -55,6 +123,8 @@ export function rootGoesOut(nodes: LayoutNode[], again: SentRoot | undefined): v
   const before = lastRoot;
   lastRoot = { nodes, ids: new Set(nodes.flatMap(idsOf)) };
   if (!before) return;
+  // The screens of the root before go with it, the tabs React never mounted too.
+  for (const id of before.ids) if (!lastRoot.ids.has(id)) ownOptions.delete(id);
   const moved = new Map<string, Options>();
   if (again === before) {
     pairNodes(before.nodes, nodes, (old, node) => {

package/src/engine/screens.tsx

@@ -52,8 +52,15 @@ export type EngineScreen =
 /** What the root of a React screen renders: the screen's id, and the props the command gave it. */
 export type ScreenRootProps = { componentId: string } & Record<string, unknown>;
 
+/**
+ * What React Native gives the root of a React screen: the screen's id, its root tag (none in a slot of the app's one
+ * tree), and the props the native side gives that root, a tab cell's `tabIndex`, `selected`, `badge`, `dot` and
+ * `dotColor`.
+ */
+export type NativeRootProps = { componentId: string; rootTag?: number } & Record<string, unknown>;
+
 const screens = new Map<string, EngineScreen>();
-const roots = new Map<string, ComponentType<{ componentId: string; rootTag?: number }>>();
+const roots = new Map<string, ComponentType<NativeRootProps>>();
 let unmounted: ((screenId: string) => void) | undefined;
 // The React roots mounted under each id, by their root tags. One id can have several: after a JavaScript reload React
 // Native starts the roots of the old screens again in the new runtime, under the ids the new screens get too, and
@@ -61,6 +68,34 @@ let unmounted: ((screenId: string) => void) | undefined;
 // bar of every screen that shows it. The id lets its props go only with the last of them. A slot of the app's one tree
 // has no tag: while the one tree shows a screen with the id, no root of that id lets it go.
 const owners = new Map<string, Set<number>>();
+// The screens that show by their ids: the name, and how many roots or slots of the id are mounted (a component of the
+// options has a root in the bar of every screen that shows it).
+const shown = new Map<string, { name: string; mounts: number }>();
+
+/**
+ * Notes a screen as shown, a React root or slot of it or the controller of a native screen, until the function it
+ * gives is called.
+ */
+export function noteShown(componentId: string, name: string): () => void {
+  const entry = shown.get(componentId);
+  if (entry?.name === name) entry.mounts++;
+  else shown.set(componentId, { name, mounts: 1 });
+  return () => {
+    const current = shown.get(componentId);
+    if (current?.name !== name) return;
+    if (--current.mounts === 0) shown.delete(componentId);
+  };
+}
+
+/** The ids of the screens with the name that show now. */
+export function shownScreens(name: string): string[] {
+  return [...shown].filter(([, entry]) => entry.name === name).map(([id]) => id);
+}
+
+/** Whether a React root of the screen with the id is mounted now (a slot of the app's one tree doesn't count). */
+export function hasRoot(componentId: string): boolean {
+  return owners.has(componentId);
+}
 
 /** What runs when the root of a screen unmounts: the screen is gone. */
 export function onScreenUnmounted(listener: (screenId: string) => void): void {
@@ -193,20 +228,29 @@ export function isReactScreen(name: string): boolean {
   return screen !== undefined && 'component' in screen;
 }
 
+/**
+ * The props a screen's component renders with: those a command left under its id ([stored]), the props the native side
+ * gave its root over them ([root]: a tab cell's state, which the docs promise arrives on top of `passProps`), and its
+ * id. The root tag stays with the root.
+ */
+export function screenProps(stored: object, root: NativeRootProps): ScreenRootProps {
+  const props: ScreenRootProps = { ...stored, ...root, componentId: root.componentId };
+  delete props.rootTag;
+  return props;
+}
+
 /**
  * The root a React screen runs in: the screen with the props a command left for it under its id, and the new ones when
- * options give its id new props. React Native gives a root only its id (and its own root props, which stay here); the
- * slot of the app's one tree renders the same root.
+ * options give its id new props, under the props the native side gives the root ([screenProps]). The slot of the app's
+ * one tree renders the same root.
  */
-export function screenRoot(
-  name: string
-): ComponentType<{ componentId: string; rootTag?: number }> | undefined {
+export function screenRoot(name: string): ComponentType<NativeRootProps> | undefined {
   const screen = screens.get(name);
   if (!screen || !('component' in screen)) return undefined;
   let root = roots.get(name);
   if (!root) {
     const Screen = screen.component();
-    root = function ScreenRoot(rootProps: { componentId: string; rootTag?: number }) {
+    root = function ScreenRoot(rootProps: NativeRootProps) {
       // In the app's one tree the slot renders the root, without a tag of its own.
       const { componentId, rootTag } = rootProps;
       const watch = useCallback(
@@ -214,6 +258,7 @@ export function screenRoot(
         [componentId]
       );
       const props = useSyncExternalStore(watch, () => propsOf(componentId));
+      useEffect(() => noteShown(componentId, name), [componentId]);
       useEffect(() => {
         if (rootTag !== undefined) {
           const tags = owners.get(componentId) ?? new Set<number>();
@@ -240,7 +285,7 @@ export function screenRoot(
           unmounted?.(componentId);
         };
       }, [componentId, rootTag]);
-      return <Screen {...props} componentId={componentId} />;
+      return <Screen {...screenProps(props, rootProps)} />;
     };
     root.displayName = `ScreenRoot(${name})`;
     roots.set(name, root);

package/src/interfaces/ComponentEvents.ts

@@ -95,8 +95,8 @@ export interface SheetDetentChangedEvent {
   /** The id of the visible screen of the modal. */
   componentId: string;
   /**
-   * The detent the sheet stopped at: `'medium'`, `'large'`, or a height (points on iOS, dp on Android). `'content'`
-   * is sent on iOS for a detent that fits the content; Android names such a detent `'medium'`.
+   * The detent the sheet stopped at: `'medium'`, `'large'`, `'content'` (the detent that fits the content), or a
+   * height (points on iOS, dp on Android).
    */
   detent: 'medium' | 'large' | 'content' | number;
 }

package/src/interfaces/options/animations.ts

@@ -258,10 +258,12 @@ export type ElementAnimation = AppearingElementAnimation | DisappearingElementAn
  * the way (an error in its animation) is skipped too, with a warning in the log: it shows and hides with its screen,
  * and the transition and its command go on. Without an animation of the screens of its own, the screen that comes fades
  * in (or the one that goes fades out) in 300 ms around the elements. When the transition ends or is cancelled, the
- * element gets its own values back. `x` and `y` are the position in the parent of the element on both platforms. As on
- * a side of a screen, don't set `x` with `translationX` or `y` with `translationY` on one element: the translation
- * plays and the position doesn't. (Android) A view whose parent is a React view with `removeClippedSubviews` turned on,
- * such as a child of a clipping list, is not moved: it counts as not found.
+ * element gets its own values back. The element's own `transform` counts: a property that doesn't animate keeps the
+ * element's value, and a missing end is that value (a turn read from −180° to 180°, as React Native draws it). `x`
+ * and `y` are the position in the parent of the element on both platforms. As on a side of a screen, don't set `x`
+ * with `translationX` or `y` with `translationY` on one element: the translation plays and the position doesn't.
+ * The element plays where it is, in its screen: it moves with its screen, its parents clip it, and the views drawn
+ * after it in its screen stay over it.
  */
 export interface ElementTransition {
   /** The `nativeID` of the view to animate. */
@@ -292,12 +294,20 @@ export interface ElementTransition {
  * A view that flies from the screen that goes to the screen that comes, changing its place, size, corners and look on
  * the way. A pair whose view is not found on either screen is skipped while the rest plays, and the transition waits
  * until the views are found. A pair that fails on the way (an error in its start or its flight) is skipped too, with a
- * warning in the log: its views show and hide with their screens, and the transition and its command go on. (iOS) So is
- * a pair with a view without a size, or one whose picture can't be taken. Without an animation of the screens of its
- * own, the screen that comes fades in (or the one that goes fades out) in 300 ms around the pair. Text keeps its
- * proportions and changes its picture within a quarter of the flight. (Android) A picture that doesn't load within a
- * second drops out of the transition, and so does a pair with a view whose parent is a React view with
- * `removeClippedSubviews` turned on: it counts as not found.
+ * warning in the log: its views show and hide with their screens, and the transition and its command go on. So is a
+ * pair with a view without a size, or one whose picture can't be taken. Without an animation of the screens of its
+ * own, the screen that comes fades in (or the one that goes fades out) in 300 ms around the pair. What flies is a copy:
+ * pictures of the two views taken as the transition starts, while the views stay hidden in their places; what changes
+ * in them meanwhile shows when they are back. A view its parents cut (`overflow: hidden`, a scroll view, the edge of
+ * its screen) shows only the part they leave visible, and that part goes to the one of the other view on the way.
+ * Text keeps its proportions, flies whole and changes its picture within a quarter of the flight. A view turned or
+ * scaled by its own `transform` or by a parent's flies from where it shows, and its angle goes to the other view's
+ * along the shorter arc. The angle is the one React Native draws, from −180° to 180°:
+ * `rotate: '270deg'` turns back a quarter, and no pair spins a full turn. (Android) An image without a background or a
+ * border flies as the image of the view that comes, from the part and place the fit (`resizeMode`) shows in one view
+ * to those in the other, and an animated image plays on; images of other proportions fly as pictures. An image that
+ * doesn't load within a second drops out of the transition. A skew and a tilt (`skewX`, `rotateX`, …) don't fly: the
+ * view flies without them and has them again at the end.
  */
 export interface SharedElementTransition {
   /** The `nativeID` of the view on the screen that goes. */
@@ -406,14 +416,27 @@ export interface StackPushAnimationOptions extends StackAnimationOptions {
 }
 
 /**
- * The animation of a pop, read from the screen that goes. As {@link StackAnimationOptions}, with the preview of the
- * back gesture on Android.
+ * The animation of a pop, read from the screen that goes. As {@link StackAnimationOptions}, with the swipe back of iOS
+ * and the preview of the back gesture on Android.
  */
 export interface StackPopAnimationOptions extends StackAnimationOptions {
+  /**
+   * (iOS) Whether the swipe back plays this pop under the finger. Without it, the swipe back plays UIKit's slide, and
+   * the pop's own animation plays only for the back button and `pop`. With `true`, the swipe from the edge plays the
+   * pop's own animation as far as the finger has gone across the screen: the user can stop halfway, and letting go
+   * finishes the pop or puts the screen back, the rest playing faster after a quick flick. It applies only when the pop
+   * has an animation of its own (`content`, `elementTransitions`, `sharedElementTransitions`). The top bar shows the
+   * screen under from the start of the swipe, as UIKit does in a transition of its own, and comes back when the swipe
+   * is given up. On iOS 26 the swipe from the content stays off for a screen with an own pop.
+   * Android ignores it: a pop with an animation of its own plays when the back gesture ends.
+   * @default false
+   */
+  interactive?: boolean;
   /**
    * (Android 14+) Whether the back gesture on a pushed screen previews its pop as the user swipes: the screen shrinks
    * and follows the finger, the screen under it shows behind. `false` pops the screen when the gesture is released,
-   * as on Android 13 and older; back still pops it. iOS ignores it: its swipe back is UIKit's.
+   * as on Android 13 and older; back still pops it. iOS ignores it: its swipe back is UIKit's, or the pop's own
+   * animation with `interactive`.
    * @default true
    */
   preview?: boolean;
@@ -469,6 +492,12 @@ export interface ModalAnimationOptions extends EnterExitAnimationOptions {
  * options of the command. A change by `mergeOptions` is for the next command and animates nothing itself. A theme
  * switch or a rotation does not change an animation. Without a key, the transition is the platform's own.
  *
+ * The system's setting to reduce motion is respected, with no option to turn that off. (iOS) With Reduce Motion on, a
+ * transition of these keys is a fade of the same length: the screen that comes fades in (a push, `setStackRoot`, a
+ * modal's show, `setRoot`), the screen that goes fades out (a pop, a dismissal); no element moves. (Android) With
+ * Remove animations on (or the animator duration scale at 0), the transitions end at once, no element moves and none
+ * is waited for, a side menu opens and closes without its slide, and a sheet shows and closes without it.
+ *
  * ```ts
  * const options: Options = {
  *   animations: {
@@ -484,7 +513,8 @@ export interface AnimationOptions {
   push?: StackPushAnimationOptions;
   /**
    * The pop of a screen, also `popTo` and `popToRoot`, read from the screen that goes. The swipe back of iOS is
-   * UIKit's; the back gesture of Android previews the pop (`preview`).
+   * UIKit's, or the pop's own animation under the finger (`interactive`); the back gesture of Android previews the pop
+   * (`preview`).
    */
   pop?: StackPopAnimationOptions;
   /** The replacing of the screens of a stack, read from the new top screen. */

package/src/interfaces/options/bottomTabs.ts

@@ -73,8 +73,10 @@ export interface OptionsBottomTabsAccessoryComponent {
 /**
  * (iOS 26+) The accessory above the tab bar, like the mini player of a music app. The system sizes it (48 points high)
  * and the component fills that size. It is placed above the bar, or beside the bar when the bar is minimized; on an
- * iPad with the bar at the top it sits at the bottom over the full width, always above the bar. The accessory stops
- * together with the tabs. Android has no accessory.
+ * iPad with the bar at the top it sits at the bottom over the full width, always above the bar. A hidden accessory
+ * (`visible: false`, or no name) keeps its React root and its state, and shows again with them. When another accessory
+ * (another `componentId`) shows, the replaced one stops once it has left the window and its state is gone. The last
+ * accessory stops together with the tabs. Android has no accessory.
  */
 export interface OptionsBottomTabsAccessory {
   /**
@@ -155,6 +157,16 @@ export interface OptionsBottomTabs {
    * @default true
    */
   animate?: boolean;
+  /**
+   * How the content changes when another tab is selected on screen, by a press, by back or from code. `'platform'`
+   * does what the platform does: on Android the tab that goes fades out and the new one fades in and grows (Material's
+   * fade through, 300 ms), on iOS the content changes at once. `'none'` changes it at once on both platforms. The
+   * appear events of a switch and `ANN.BottomTabSelected` come at its end, so with `'none'` right away. The tab that is
+   * selected decides: the value of the screen it shows, over its own, the tabs' and the default options. A
+   * `mergeOptions` applies from the next switch. Off screen the content always changes at once.
+   * @default 'platform'
+   */
+  switchAnimation?: 'platform' | 'none';
   /**
    * The tab to select, as an index from 0. It selects once, when the options arrive, at creation (the first tab to
    * show) or in `mergeOptions`; it is not kept. An index out of range selects nothing (or the first tab at creation)
@@ -187,9 +199,10 @@ export interface OptionsBottomTabs {
    */
   drawBehind?: boolean;
   /**
-   * The background color of the bar; `null` gives the default one. On Android the default is the surface color of the
-   * Material 3 theme. Before iOS 26 (and with `UIDesignRequiresCompatibility`) the bar is opaque with the color, or
-   * system opaque without it, and a transparent color makes it transparent. On iOS 26 with glass the color is ignored
+   * The background color of the bar; `null` gives the default one. On Android the default is the surface container color
+   * (`colorSurfaceContainer`) of the Material 3 theme. Before iOS 26, and in the compatibility mode (`UIDesignRequiresCompatibility` in Info.plist: iOS 26, and iOS 27
+   * only for an app built with an SDK before iOS 27), the bar is opaque with the color, or system opaque without it,
+   * and a transparent color makes it transparent. On iOS 26 and later with glass the color is ignored
    * with one warning, since the system has no color for glass, while a transparent color gives a transparent bar. The
    * theme color `bar` is its default option.
    */
@@ -396,7 +409,7 @@ export interface OptionsBottomTab {
   selectedFontSize?: number;
   /**
    * (iOS) The insets of the icon. Each side is independent. They apply before iOS 26 only; iOS 26 and the compatibility
-   * mode ignore them, and so does a system role before iOS 18.
+   * mode (see `backgroundColor`) ignore them, and so does a system role before iOS 18.
    */
   iconInsets?: IconInsets;
   /**

package/src/interfaces/options/buttons.ts

@@ -60,7 +60,7 @@ export interface IconInsets {
  * 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
+ * history menu), without the glass capsule (glass design, 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.
  */
@@ -159,7 +159,7 @@ export interface OptionsTopBarButtonMenu {
  * 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
+ * a `systemItem`; a button with none of them is not shown. On Android a button is a button of the bar's row: 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
@@ -189,7 +189,7 @@ export interface OptionsTopBarButton {
    */
   icon?: ImageResource;
   /**
-   * (iOS) The space around the image of `icon`; the button becomes a button of its own, without a capsule on iOS 26.
+   * (iOS) The space around the image of `icon`; the button becomes a button of its own, without a capsule with the glass design (iOS 26+, see `UIDesignRequiresCompatibility`).
    */
   iconInsets?: IconInsets;
   /**
@@ -204,7 +204,7 @@ export interface OptionsTopBarButton {
   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).
+   * and VoiceOver (iOS), or for TalkBack, the tooltip of a long press and the overflow menu (Android).
    */
   text?: string;
   /** The text a screen reader says for the button. */
@@ -238,14 +238,14 @@ export interface OptionsTopBarButton {
   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
+   * button of its own without menu, toggle or style, and without a capsule with the glass design 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
+   * (iOS) `'plain'` or `'prominent'`, the main action of the bar (Done, Send). With the glass design (iOS 26+, see `UIDesignRequiresCompatibility`) 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
+   * without it, it is the system's done style with bold text. Not for component buttons, buttons with
    * `iconBackground`, and `showText` buttons.
    * @default 'plain'
    */
@@ -257,7 +257,7 @@ export interface OptionsTopBarButton {
    */
   testID?: string;
   /**
-   * (iOS 26+) Whether the button has no glass capsule under it; neighbors keep theirs. By default `true` for
+   * (iOS 26+, glass design) 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.
    */
@@ -270,8 +270,8 @@ export interface OptionsTopBarButton {
    */
   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
+   * (iOS 26+, glass design) Buttons next to each other with the same group share one capsule; a button without a group has its
+   * own. Without the glass design 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.
    */

package/src/interfaces/options/modals.ts

@@ -51,8 +51,7 @@ export type OptionsModalTransitionStyle =
  *
  * On iOS `'medium'` and `'large'` are the system stops; a number and `'content'` need iOS 16 and are left out below it
  * with a warning in the log. On Android `'medium'` is half of the window, `'large'` the full height under the status
- * bar, a number is capped at `'large'`, and `'content'` stands in as `'medium'` because the Material sheet has no
- * height by content.
+ * bar, a number is capped at `'large'`, and `'content'` is the height of the content, measured as on iOS.
  */
 export type OptionsModalSheetDetent = 'medium' | 'large' | 'content' | number;
 
@@ -67,11 +66,11 @@ export type OptionsModalSheetDetent = 'medium' | 'large' | 'content' | number;
 export interface OptionsModalSheet {
   /**
    * 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.
+   * height and repeats dropped. On iOS `'medium'` counts as half of `'large'` there, and on both `'content'` takes its
+   * place by the height of the content, again whenever that changes; on iOS a list left empty by unsupported values
+   * gives `['large']`. On Android the Material sheet has three resting places at most: the lowest stop of the list, the
+   * highest, and one between them, `selectedDetent` when it stands there, else the lowest of the others; the rest are
+   * dropped. Stops of the same height there are one.
    * @default ['large']
    */
   detents?: OptionsModalSheetDetent[];

package/src/interfaces/options/stack.ts

@@ -39,13 +39,18 @@ export interface HardwareBackButtonOptions {
 
 /**
  * (Android) A floating action button over the screen, or an entry of its menu. The button shows while its screen is
- * on top of the stack; without the option there is none. `mergeOptions` and the default options of the app apply, and
- * the colors of the theme are read again when the theme changes.
+ * on top of the stack; without the option there is none. It changes as a push or a pop starts and moves with its
+ * screen, as the tab bar does: the new screen's button comes in with it, the old one goes out with the screen it
+ * belongs to, and an open menu closes. With an animation of the screens' own the old button shrinks away and the new
+ * one grows as it starts; during the back gesture the button of the screen under the top shows with that screen.
+ * `mergeOptions` and the default options of the app apply, and the colors of the theme are read again when the theme
+ * changes.
  */
 export interface OptionsFab {
   /**
    * The identifier of the button. A press reports it, and the app finds the `onPress` of the button by it. A button
-   * without an `id` doesn't show. The same `id` on a later show or merge updates the button; another `id` replaces it.
+   * without an `id` doesn't show. The same `id` on a later show or merge updates the button, which stays in place
+   * while the screens move; another `id` replaces it.
    * For an entry of `actions` it is the id of that entry's own press.
    */
   id: string;

package/src/interfaces/options/system.ts

@@ -34,12 +34,15 @@ export interface OptionsLayout {
    * indicator or navigation bar, the camera cutout. `[]` lets the content reach every edge. The array replaces the
    * one from a lower layer. The screen adds the padding itself; `useSafeAreaInsets()` returns what is still covered,
    * which is 0 on an edge the screen keeps and the whole covered size on an edge where the content goes under a bar.
-   * Edges listed here always win, also for a screen with a large title.
+   * Edges listed here win, but the top under a large title: there the list keeps its first rows clear of the bar
+   * itself and scrolls under it, which collapses the title, so a `'top'` listed here counts for nothing.
    *
-   * Without it, on iOS: every edge except those where the content goes under a bar that shows (the top bar, a tab
-   * bar or toolbar at the bottom, the side of a vertical bar); a screen with a large title keeps the top free so its
-   * list can scroll under the bar. On Android: all four edges, except the top under a top bar that hides on scroll
-   * or under a large title, and the bottom under tabs that hide on scroll.
+   * Without it the screen keeps the top and the sides, and its content goes down to the bottom: under the home
+   * indicator or the navigation bar, and under a tab bar or toolbar it goes under. A list keeps its last rows clear
+   * with `useSafeAreaInsets().bottom`. The top is free where the content goes under a top bar: on iOS under a bar
+   * that shows, on Android under a bar that hides on scroll; on both under a large title, so the list scrolls under
+   * the bar. On iOS the side of a vertical bar is free too. To have the screen keep the bottom, list every edge it
+   * keeps: listed edges replace the default.
    */
   safeAreaEdges?: SafeAreaEdge[];
   /**

package/src/interfaces/options/toolbar.ts

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