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

package/src/interfaces/contract/commands.json

@@ -0,0 +1,101 @@
+{
+  "description": "Every command with a promise (an async method of src/adapters/NativeANNTurboModule.ts): what it resolves with, whether the navigation state goes before its answer (`state`), and whether `ANN.CommandCompleted` follows the answer (`completed`). scripts/contract.mjs makes ios/Contract/ANNCommandContract.{h,mm} and android/.../react/CommandContract.kt from it, and fails when a command of the spec is missing here or a command here is not in the spec.",
+  "commands": [
+    {
+      "name": "setRoot",
+      "resolves": "the id of the root, once the root and the layout's modals and overlays show",
+      "state": true,
+      "completed": true
+    },
+    {
+      "name": "push",
+      "resolves": "the id of the screen that shows; of a pair, the pair's id",
+      "state": true,
+      "completed": true
+    },
+    {
+      "name": "preparePush",
+      "resolves": "the frame `{ width, height, padding }` of the prepared screen, or null; always null on iOS",
+      "state": false,
+      "completed": false
+    },
+    {
+      "name": "pop",
+      "resolves": "the id of the screen that went",
+      "state": true,
+      "completed": true
+    },
+    {
+      "name": "popTo",
+      "resolves": "the id of the screen it went back to",
+      "state": true,
+      "completed": true
+    },
+    {
+      "name": "popToRoot",
+      "resolves": "the id of the first screen of the stack",
+      "state": true,
+      "completed": true
+    },
+    {
+      "name": "setStackRoot",
+      "resolves": "the id of the new top screen",
+      "state": true,
+      "completed": true
+    },
+    {
+      "name": "showModal",
+      "resolves": "the id of the modal's root",
+      "state": true,
+      "completed": true
+    },
+    {
+      "name": "dismissModal",
+      "resolves": "the id of the modal's root",
+      "state": true,
+      "completed": true
+    },
+    {
+      "name": "dismissAllModals",
+      "resolves": "an empty string",
+      "state": true,
+      "completed": true
+    },
+    {
+      "name": "showOverlay",
+      "resolves": "the id of the overlay's root",
+      "state": true,
+      "completed": true
+    },
+    {
+      "name": "dismissOverlay",
+      "resolves": "the id of the overlay's root",
+      "state": true,
+      "completed": true
+    },
+    {
+      "name": "dismissAllOverlays",
+      "resolves": "an empty string",
+      "state": true,
+      "completed": true
+    },
+    {
+      "name": "showInColumn",
+      "resolves": "the id of the screen that shows",
+      "state": true,
+      "completed": true
+    },
+    {
+      "name": "setColumnShown",
+      "resolves": "nothing once the columns stopped moving (`undefined` on iOS, `null` on Android)",
+      "state": true,
+      "completed": false
+    },
+    {
+      "name": "getLaunchLink",
+      "resolves": "the link that launched the app, or null",
+      "state": false,
+      "completed": false
+    }
+  ]
+}

package/src/interfaces/options/animations.ts

@@ -354,8 +354,11 @@ export interface StackAnimationOptions {
   enabled?: boolean;
   /**
    * Whether to wait for the new top screen to be drawn before the transition. Without it, the transition waits for the
-   * content of a screen with an animation of its own for half a second at most, `true` waits as long as it takes,
-   * `false` starts at once, also with an animation of its own.
+   * first mount of the new top's content, half a second at most, with the platform's transition as with an animation
+   * of its own; on a push the options the screen sets as it renders for the first time (`useScreenOptions`, such as
+   * its title) are in its bar from the first frame. `true` waits as long as it takes, `false` starts at once, the
+   * content drawing as it comes ((Android) a push with `appProvider` still renders the screen first). (iOS) The
+   * components of the bar are waited for too, each to its own limit.
    */
   waitForRender?: boolean;
   /**

package/src/interfaces/options/buttons.ts

@@ -138,8 +138,10 @@ export type OptionsTopBarButtonMenuElement =
 /**
  * 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.
+ * `singleSelection` merge field by field (iOS). What the user picks in a `singleSelection` menu stays with the screen,
+ * through it showing again, a `mergeOptions` that sends the same items again and `setDefaultOptions`; a `mergeOptions`
+ * into the screen that changes the checks of that menu's level, or takes the item away, replaces it. A merge into the
+ * stack or the tabs around the screen doesn't.
  */
 export interface OptionsTopBarButtonMenu {
   /** The title above the items. (iOS) Android doesn't show it. */
@@ -285,8 +287,10 @@ export interface OptionsTopBarButton {
   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,
+   * stays with the screen under the button's id, through it showing again, a `mergeOptions` that sends the same
+   * buttons again and `setDefaultOptions`; a `mergeOptions` into the screen that changes `selected` replaces it (a merge
+   * into the stack around it doesn't). 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;
@@ -351,7 +355,11 @@ export interface OptionsTopBarButton {
  * 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. */
+  /**
+   * The id of the component. Without it, the library gives one made of the screen, the component's place in the
+   * options and its `name`: it stays the same for every `mergeOptions` of the screen, so the mounted component stays
+   * and only its props change. The same `name` and `id` mean the same component.
+   */
   id?: string;
   /** The name of the registered component. */
   name: string;

package/src/interfaces/options/topBar.ts

@@ -11,7 +11,11 @@ import type { Color, FontFamily, FontStyle, FontWeight, ImageResource } from './
  * `name` replaces it.
  */
 export interface OptionsTopBarTitleComponent {
-  /** The id of the component. Without it, the library gives one. The same `name` and `id` mean the same component. */
+  /**
+   * The id of the component. Without it, the library gives one made of the screen, the component's place in the
+   * options and its `name`: it stays the same for every `mergeOptions` of the screen, so the mounted component stays
+   * and only its props change. The same `name` and `id` mean the same component.
+   */
   id?: string;
   /** The name of the registered component. */
   name: string;
@@ -276,7 +280,11 @@ export interface OptionsTopBarBackground {
 
 /** The React component that is the background of the bar. */
 export interface OptionsTopBarBackgroundComponent {
-  /** The id of the component. Without it, the library gives one. The same `name` and `id` mean the same component. */
+  /**
+   * The id of the component. Without it, the library gives one made of the screen, the component's place in the
+   * options and its `name`: it stays the same for every `mergeOptions` of the screen, so the mounted component stays
+   * and only its props change. The same `name` and `id` mean the same component.
+   */
   id?: string;
   /** The name of the registered component. */
   name: string;
@@ -432,7 +440,11 @@ export interface OptionsSearchBarSuggestion {
  * component; a different `id` or `name` replaces the component, and so the search.
  */
 export interface OptionsSearchBarResultsComponent {
-  /** The id of the component. Without it, the library gives one. The same `name` and `id` mean the same component. */
+  /**
+   * The id of the component. Without it, the library gives one made of the screen, the component's place in the
+   * options and its `name`: it stays the same for every `mergeOptions` of the screen, so the mounted component stays
+   * and only its props change. The same `name` and `id` mean the same component.
+   */
   id?: string;
   /** The name of the registered component. */
   name: string;
@@ -518,8 +530,9 @@ export interface OptionsSearchBar {
    */
   scopes?: OptionsSearchBarScope[];
   /**
-   * The id of the selected scope; without it, or with an unknown id, the first. The user's pick is written into the
-   * options of the screen and stays after coming back. `mergeOptions` switches the scope without an event.
+   * The id of the selected scope; without it, or with an unknown id, the first. The user's pick stays with the screen,
+   * after coming back, through a `mergeOptions` that sends the same value again and `setDefaultOptions`. A
+   * `mergeOptions` into the screen with another value switches the scope without an event.
    */
   selectedScope?: string;
   /**
@@ -531,15 +544,15 @@ export interface OptionsSearchBar {
   scopeBarActivation?: 'automatic' | 'onTextEntry' | 'onSearchActivation';
   /**
    * (iOS) Tokens in front of the text of the field. The search events carry the ids of the tokens in the field as
-   * `tokens`; deleting a token sends a search-updated event, and the deleted tokens (and ones brought back with Undo)
-   * are written to the options of the screen. Closing the search clears the field and its tokens. An empty list removes
+   * `tokens`; deleting a token sends a search-updated event, and what the user deleted (or brought back with Undo)
+   * stays with the screen until a `mergeOptions` gives other tokens. Closing the search clears the field and its tokens. An empty list removes
    * them all.
    */
   tokens?: OptionsSearchBarToken[];
   /**
    * (iOS 16+, Android) The suggestions shown while searching. Picking one sends a suggestion-picked event with its id
-   * to the screen; the text stays and the list goes. They also go when the user types on, and new ones come with
-   * `mergeOptions`, usually on a search-updated event. An empty list removes them.
+   * to the screen; the text stays and the list goes. They also go when the user types on; the list a `mergeOptions`
+   * gives shows again, the same one too, usually on a search-updated event. An empty list removes them.
    */
   suggestions?: OptionsSearchBarSuggestion[];
   /**