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

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

@@ -1 +1 @@
-{"version":3,"file":"sideMenu.d.ts","sourceRoot":"","sources":["../../../../src/interfaces/options/sideMenu.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,cAAc,GAAG,aAAa,CAAC;IAC1C;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,MAAM,uBAAuB,GAAG,OAAO,GAAG,cAAc,CAAC;AAE/D;;;;;GAKG;AACH,MAAM,MAAM,qBAAqB,GAAG,UAAU,GAAG,OAAO,GAAG,iBAAiB,GAAG,MAAM,CAAC;AAEtF;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,qBAAqB;IACrB,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,sBAAsB;IACtB,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB;;;;;;;;OAQG;IACH,eAAe,CAAC,EAAE,uBAAuB,CAAC;IAC1C;;;OAGG;IACH,aAAa,CAAC,EAAE,qBAAqB,CAAC;IACtC;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB"}
+{"version":3,"file":"sideMenu.d.ts","sourceRoot":"","sources":["../../../../src/interfaces/options/sideMenu.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,cAAc,GAAG,aAAa,CAAC;IAC1C;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,MAAM,uBAAuB,GAAG,OAAO,GAAG,cAAc,CAAC;AAE/D;;;;;GAKG;AACH,MAAM,MAAM,qBAAqB,GAAG,UAAU,GAAG,OAAO,GAAG,iBAAiB,GAAG,MAAM,CAAC;AAEtF;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,qBAAqB;IACrB,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,sBAAsB;IACtB,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB;;;;;;;;OAQG;IACH,eAAe,CAAC,EAAE,uBAAuB,CAAC;IAC1C;;;OAGG;IACH,aAAa,CAAC,EAAE,qBAAqB,CAAC;IACtC;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB"}

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

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

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

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

package/package.json

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

package/src/ARCHITECTURE.md

@@ -63,7 +63,8 @@ form of `src/api/events/navigationEvents.ts`. Everything in `src/engine` is inte
   `LinkParams`, `PendingLink`, …). `linkPaths.ts`: a URL into its path and query (`parseLink`), the patterns ordered
   (`compileRoutes`) and matched (`matchLink`). `linking.ts`: the links of the app — the launch link, the `url` events
   of React Native's `Linking`, the routes run, the pending link opened after `setContext`. `pendingLinks.ts`: the one
-  waiting link and its listeners, which `navigation` and `usePendingLink` read.
+  waiting link and its listeners, which `navigation` and `usePendingLink` read. `dispatchedLinks.ts` (iOS): hands
+  `Linking` the links of `ANN.DeepLinkDispatched`.
 - `events/` — `navigationEvents.ts`: the events by name, the native event behind each, `onNavigationEvent`,
   `listeners`. `screenLifecycle.ts`: what goes when a screen unmounts, `whenScreenUnmounts`. `tabPresses.ts`: the
   handlers of `useTabPress`.
@@ -268,7 +269,9 @@ its push, which the hook ignores.
   given once; JS asks only with `linking`) and `getStartInfo` (synchronous: `coldStart`, true for the whole life of
   the first JavaScript runtime of the process, and `splashLogo`, the size of the native splash's logo the CLI wrote,
   or null; `arrangements`, whether it shows pairs). The links that come while the app runs reach JS through React Native's
-  `Linking`, not through `ANN.*` events.
+  `Linking`, not through `ANN.*` events. One exception, iOS only: a link the app dispatched (`dispatchDeepLinkURL`) that
+  `Linking` doesn't take from the native side (React Native 0.88 and newer, with a scene delegate) comes as
+  `ANN.DeepLinkDispatched`, and `src/api/linking/dispatchedLinks.ts` hands it to `Linking` as a `url` event.
 - Events: `ANN.AppLaunched`, `ANN.ComponentWillAppear`, `ANN.ComponentDidAppear`, `ANN.ComponentDidDisappear`,
   `ANN.NavigationButtonPressed`, `ANN.BottomTabSelected`, `ANN.BottomTabPressed`, `ANN.BottomTabLongPressed`,
   `ANN.ModalDismissed`, `ANN.ModalAttemptedToDismiss`, `ANN.ScreenPopped`, `ANN.SearchBarUpdated`,
@@ -276,8 +279,8 @@ its push, which the hook ignores.
   `ANN.NavigationStateChanged`, `ANN.SlotDestroyed`, `ANN.ScreenInsetsChanged`, `ANN.TitleRenamed`,
   `ANN.BottomAccessoryPlacementChanged`, `ANN.SheetDetentChanged`, `ANN.SplitViewDisplayModeChanged`,
   `ANN.KeyCommandPressed`, `ANN.NativeScreenCall`, `ANN.NativeScreenReleased`, `ANN.ScreenRegionsChanged`,
-  `ANN.ArrangementChanged`, `ANN.HingeChanged`, `ANN.SplitViewColumnsStacked`. Their payloads are typed in
-  `src/interfaces/ComponentEvents.ts` and `Events.ts`. Both platforms also send `ANN.CommandCompleted`
+  `ANN.ArrangementChanged`, `ANN.HingeChanged`, `ANN.SplitViewColumnsStacked`, `ANN.DeepLinkDispatched` (iOS). Their
+  payloads are typed in `src/interfaces/ComponentEvents.ts` and `Events.ts`. Both platforms also send `ANN.CommandCompleted`
   (`CommandCompletedEvent`), which nothing in JS listens to.
 - Native components: `ANNSlot` (`src/api/slots`) and `ANNSafeAreaView` (`src/api/safeArea`), with C++ of their own in
   `ios/cpp`, which Android builds too (their states hold a size and a padding; the first one comes from the props

package/src/api/app/createNavigation.ts

@@ -43,6 +43,7 @@ import {
 import { launchState } from '../../engine/launchState';
 import { watchBackListeners } from '../../engine/backListeners';
 import { resolveRoot, type RootsMap, type RootTarget, type UsesOfRootValue } from './roots';
+import { listenToDispatchedLinks } from '../linking/dispatchedLinks';
 import {
   launchLink,
   launchRoot,
@@ -501,6 +502,7 @@ export function createNavigation<
       if (config.context !== undefined) setAppContext(config.context);
       if (config.appProvider) enableSlots(config.appProvider);
       listenToNavigationState();
+      listenToDispatchedLinks();
       watchSideMenus();
       listenToNativeScreens();
       listenToSplitViews();

package/src/api/hooks/useNavigation.ts

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

package/src/api/linking/dispatchedLinks.ts

@@ -0,0 +1,18 @@
+import { DeviceEventEmitter, Platform } from 'react-native';
+import { onNativeEvent } from '../../engine/native';
+import type { DeepLinkDispatchedEvent } from '../../interfaces/Events';
+
+let listening = false;
+
+/**
+ * (iOS) Hands `Linking` the links the app dispatched that it didn't take from the native side: on React Native 0.88
+ * and newer, in an app with a scene delegate, it takes only the links a scene opened. `Linking` listens to its `url`
+ * events through `DeviceEventEmitter`, so every listener of the app gets them, the navigation's links too.
+ */
+export function listenToDispatchedLinks() {
+  if (listening || Platform.OS !== 'ios') return;
+  listening = true;
+  onNativeEvent<DeepLinkDispatchedEvent>('DeepLinkDispatched', ({ url }) => {
+    DeviceEventEmitter.emit('url', { url });
+  });
+}

package/src/interfaces/Events.ts

@@ -105,6 +105,16 @@ export interface SplitViewColumnsStackedEvent {
   stacked: boolean;
 }
 
+/**
+ * (iOS) A link the app dispatched (`dispatchDeepLinkURL`) that React Native's `Linking` doesn't take from the native
+ * side: on React Native 0.88 and newer, in an app whose Info.plist names a scene delegate, it takes only the links a
+ * scene opened. JavaScript hands it to `Linking` as a `url` event.
+ */
+export interface DeepLinkDispatchedEvent {
+  /** The link. */
+  url: string;
+}
+
 /**
  * A screen of the single React tree was destroyed and the slot still belongs to it: JavaScript removes the slot from
  * its tree. It is not sent for a prepared screen that was never pushed, nor when JavaScript reloads.

package/src/interfaces/contract/errors.json

@@ -0,0 +1,275 @@
+{
+  "description": "Every text the native side rejects a command with, or logs for a command without a promise: one sentence per case, the values in single quotes, {name} for a parameter. scripts/contract.mjs makes ios/Contract/ANNErrorTexts.{h,mm} and android/.../react/ErrorTexts.kt from it; `platforms` limits a text to one platform.",
+  "groups": [
+    {
+      "title": "Where the screen is",
+      "texts": [
+        {
+          "name": "screenNotShown",
+          "params": ["componentId"],
+          "text": "the screen '{componentId}' is not shown"
+        },
+        {
+          "name": "notInStack",
+          "params": ["componentId"],
+          "text": "the screen '{componentId}' is not in a stack"
+        },
+        {
+          "name": "firstScreenOfStack",
+          "params": ["componentId"],
+          "text": "the screen '{componentId}' is the first screen of its stack"
+        },
+        {
+          "name": "notInThisStack",
+          "params": ["componentId"],
+          "text": "the screen '{componentId}' is not in this stack"
+        },
+        {
+          "name": "notInModal",
+          "params": ["componentId"],
+          "text": "the screen '{componentId}' is not in a modal"
+        },
+        {
+          "name": "notInOverlay",
+          "params": ["componentId"],
+          "text": "the screen '{componentId}' is not in an overlay"
+        },
+        {
+          "name": "notInSplitView",
+          "params": ["componentId"],
+          "text": "the screen '{componentId}' is not in a split view"
+        },
+        {
+          "name": "neitherSplitViewNorStack",
+          "params": ["componentId"],
+          "text": "the screen '{componentId}' is neither in a split view nor in a stack"
+        },
+        {
+          "name": "noSuchColumn",
+          "params": ["componentId", "column"],
+          "text": "the split view of the screen '{componentId}' has no '{column}' column"
+        },
+        {
+          "name": "columnIsStack",
+          "params": ["componentId", "column"],
+          "text": "the '{column}' column of the split view of the screen '{componentId}' is a stack: it takes a screen, not a stack"
+        },
+        {
+          "name": "columnNotStack",
+          "params": ["componentId", "column"],
+          "text": "the '{column}' column of the split view of the screen '{componentId}' is not a stack"
+        },
+        {
+          "name": "noScreensForStack",
+          "params": ["componentId"],
+          "text": "there are no screens to put in the stack of the screen '{componentId}'"
+        },
+        {
+          "name": "alreadyShown",
+          "params": ["componentId"],
+          "text": "the screen '{componentId}' shows already: an id goes to one screen"
+        }
+      ]
+    },
+    {
+      "title": "Root, modals, the app",
+      "texts": [
+        {
+          "name": "setRootReplaced",
+          "params": ["rootId"],
+          "text": "setRoot was replaced by a newer setRoot before the root '{rootId}' finished showing"
+        },
+        {
+          "name": "rootDestroyed",
+          "params": ["rootId"],
+          "text": "the root '{rootId}' was destroyed before it showed"
+        },
+        {
+          "name": "modalWithoutRoot",
+          "params": ["componentId"],
+          "text": "the modal '{componentId}' can't be dismissed: there is no root under it"
+        },
+        {
+          "name": "nowhereToShow",
+          "params": [],
+          "text": "the navigation has nowhere to show screens: the app has no activity or window"
+        }
+      ]
+    },
+    {
+      "title": "Native screens",
+      "texts": [
+        {
+          "name": "nativeScreenNotRegistered",
+          "params": ["name"],
+          "text": "no native screen is registered as '{name}'"
+        },
+        {
+          "name": "nativeScreenNotCreated",
+          "params": ["name"],
+          "text": "the native screen '{name}' could not be created: its creator returned nothing"
+        },
+        {
+          "name": "nativeCallReloaded",
+          "params": ["name", "componentId"],
+          "text": "JavaScript reloaded before the call '{name}' of the screen '{componentId}' was answered",
+          "doc": "The error of a call of a native screen whose JavaScript reloaded before it answered."
+        },
+        {
+          "name": "nativeCallNotRunning",
+          "params": ["name", "componentId"],
+          "text": "the navigation is not running: the call '{name}' of the screen '{componentId}' can't be answered",
+          "doc": "The error of a call of a native screen while no JavaScript can answer it."
+        }
+      ]
+    },
+    {
+      "title": "The layout",
+      "texts": [
+        {
+          "name": "unknownNodeType",
+          "params": ["type"],
+          "text": "the layout has a node of unknown type '{type}'"
+        },
+        {
+          "name": "nodeWithoutId",
+          "params": ["type"],
+          "text": "the layout has a node of type '{type}' without an id"
+        },
+        {
+          "name": "sideMenuChild",
+          "params": ["menuId", "type"],
+          "text": "the side menu '{menuId}' has a child of type '{type}': it takes SideMenuLeft, SideMenuCenter and SideMenuRight"
+        },
+        {
+          "name": "stackTakesScreens",
+          "params": ["stackId", "type"],
+          "text": "the stack '{stackId}' takes screens, not a '{type}'"
+        },
+        {
+          "name": "emptyStack",
+          "params": ["stackId"],
+          "text": "the stack '{stackId}' has no screens"
+        },
+        {
+          "name": "emptyTabs",
+          "params": ["tabsId"],
+          "text": "the tabs '{tabsId}' have no tabs"
+        },
+        {
+          "name": "tooManyTabs",
+          "params": [
+            "tabsId",
+            {
+              "name": "count",
+              "type": "int"
+            }
+          ],
+          "text": "the tabs '{tabsId}' have {count} tabs: Android shows at most 5",
+          "doc": "Only Android checks it: its tab bar shows at most 5 tabs."
+        },
+        {
+          "name": "splitViewColumns",
+          "params": ["splitViewId"],
+          "text": "the split view '{splitViewId}' needs its primary and its secondary column"
+        },
+        {
+          "name": "pairUnsupported",
+          "params": ["pairId"],
+          "text": "the pair '{pairId}' needs iOS 27.1 and an app built with its SDK",
+          "doc": "Only iOS checks it: Android has pairs on every version."
+        },
+        {
+          "name": "pairNeedsTwoScreens",
+          "params": ["pairId"],
+          "text": "the pair '{pairId}' needs two screens: its primary and its secondary"
+        },
+        {
+          "name": "nodeWithoutName",
+          "params": ["type", "nodeId"],
+          "text": "the layout has a node '{nodeId}' of type '{type}' without a name"
+        },
+        {
+          "name": "rootMissing",
+          "params": [],
+          "text": "the layout of setRoot has no root"
+        },
+        {
+          "name": "tabsInTabs",
+          "params": ["tabsId"],
+          "text": "the tabs '{tabsId}' have a tab of type 'BottomTabs': tabs don't go inside tabs"
+        },
+        {
+          "name": "sideMenuSides",
+          "params": ["menuId"],
+          "text": "the side menu '{menuId}' takes one SideMenuCenter and at most one SideMenuLeft and one SideMenuRight"
+        },
+        {
+          "name": "sideChildCount",
+          "params": ["sideId", "menuId"],
+          "text": "the side '{sideId}' of the side menu '{menuId}' needs exactly one child"
+        },
+        {
+          "name": "sideMenuInSide",
+          "params": ["menuId"],
+          "text": "the side menu '{menuId}' has a side menu in a side: a side menu doesn't go inside a side menu"
+        },
+        {
+          "name": "sideOutsideMenu",
+          "params": ["nodeId", "type"],
+          "text": "the layout has a node '{nodeId}' of type '{type}' outside a side menu"
+        },
+        {
+          "name": "splitViewInColumn",
+          "params": ["splitViewId"],
+          "text": "the split view '{splitViewId}' has a column of type 'SplitView': a split view doesn't go inside a split view"
+        },
+        {
+          "name": "idGivenTwice",
+          "params": ["nodeId"],
+          "text": "the layout gives the id '{nodeId}' to two nodes"
+        }
+      ]
+    },
+    {
+      "title": "Options, previews, any other failure",
+      "texts": [
+        {
+          "name": "unreadableOption",
+          "params": ["path", "componentId"],
+          "text": "the option '{path}' of the screen '{componentId}' has a value the navigation can't read"
+        },
+        {
+          "name": "unreadableDefaultOption",
+          "params": ["path"],
+          "text": "the option '{path}' of the default options has a value the navigation can't read",
+          "doc": "An unreadable value of `setDefaultOptions`: the default options belong to no screen."
+        },
+        {
+          "name": "previewGone",
+          "params": ["previewId"],
+          "text": "the preview '{previewId}' went without being opened"
+        },
+        {
+          "name": "couldNot",
+          "params": ["what", "reason"],
+          "text": "could not {what}: {reason}",
+          "doc": "Any other failure: what could not be done and why, `could not <what>: <reason>`."
+        },
+        {
+          "name": "notDoneYet",
+          "params": ["method"],
+          "text": "could not run '{method}': the native core doesn't do it yet",
+          "doc": "A command whose part of the native core is not written yet."
+        },
+        {
+          "name": "notAnswered",
+          "params": ["method"],
+          "text": "could not run '{method}': the native core let it go without an answer",
+          "doc": "A command that nothing in the native core answered: what took it let it go, or nothing took it.",
+          "platforms": ["ios"]
+        }
+      ]
+    }
+  ]
+}

package/src/interfaces/options/animations.ts

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