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

package/src/interfaces/options/stack.ts

@@ -26,6 +26,15 @@ export interface HardwareBackButtonOptions {
    * @internal
    */
   dismissModalOnPress?: boolean;
+  /**
+   * (Android) Whether back on the first screen of the app, with nothing left to go back to, plays the system's
+   * animation of going home. The system decides it as the gesture starts, so with `false` the navigation keeps the
+   * back on that screen too: the gesture shows no animation, and on release the press goes to `BackHandler` listeners,
+   * then to the activity's own back (`invokeDefaultOnBackPressed` of the app's activity, such as `moveTaskToBack`).
+   * Read from the screen back acts on; set it in the default options for the whole app. iOS ignores it.
+   * @default true
+   */
+  systemAnimation?: boolean;
 }
 
 /**

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[];
   /**

package/android/src/main/java/dev/apexnative/navigation/react/events/NavigationStateReporter.kt

@@ -1,62 +0,0 @@
-package dev.apexnative.navigation.react.events
-
-import android.os.Handler
-import android.os.Looper
-import dev.apexnative.navigation.viewcontrollers.bottomtabs.BottomTabsController
-import dev.apexnative.navigation.viewcontrollers.navigator.Navigators
-import dev.apexnative.navigation.viewcontrollers.parent.ParentController
-import dev.apexnative.navigation.viewcontrollers.viewcontroller.ViewController
-
-/**
- * Tells JavaScript the screen the user sees and the selected tab when they change. Every change of the screen the
- * user sees comes with a screen appearing: a push, a pop, a modal, a tab, a menu. One update after the events of a
- * pass of the main loop, and one at once before a command resolves its promise; each sent only when the state changed.
- */
-object NavigationStateReporter {
-    internal data class State(val screenId: String?, val screenName: String?, val tab: Int?)
-
-    private val handler = Handler(Looper.getMainLooper())
-    private var state: State? = null
-    private var scheduled = false
-
-    /** The new JavaScript has no state yet: the next one goes to it whatever it is. */
-    fun reset() {
-        state = null
-    }
-
-    fun setNeedsUpdate(emitter: EventEmitter) {
-        if (scheduled) return
-        scheduled = true
-        handler.post {
-            scheduled = false
-            updateNow(emitter)
-        }
-    }
-
-    /**
-     * Sends the state at once when it differs from the last one sent. A command calls it right before it resolves its
-     * promise: the event and the resolution reach JavaScript in that order, so the state is new when the `await` of
-     * the command goes on. The update already scheduled then finds nothing new. Main thread only.
-     */
-    fun updateNow(emitter: EventEmitter) {
-        // The navigation of the activity the commands run in (`Navigators.current`).
-        val navigator = Navigators.current()?.navigator ?: return
-        val next = stateOf(navigator.visibleLayout)
-        if (next == state) return
-        state = next
-        emitter.emitNavigationStateChanged(next.screenId, next.screenName, next.tab)
-    }
-
-    // The top modal, or the root ([layout]), down to the screen the user sees; overlays don't count. The tab is the
-    // selected one of the nearest tabs the screen is in, the last met on the way down, in a modal too: the tabs
-    // `selectTab` acts on from it. None for a screen out of tabs.
-    internal fun stateOf(layout: ViewController<*>?): State {
-        var tab: Int? = null
-        var current = layout ?: return State(null, null, null)
-        while (current is ParentController<*>) {
-            if (current is BottomTabsController) tab = current.selectedIndex
-            current = current.currentChild ?: return State(null, null, null)
-        }
-        return State(current.id, current.currentComponentName, tab)
-    }
-}

package/android/src/main/java/dev/apexnative/navigation/react/events/StateHold.kt

@@ -1,62 +0,0 @@
-package dev.apexnative.navigation.react.events
-
-/**
- * The navigation state's posted update and its hold. [setNeedsUpdate] posts one update ([post]), coalesced: the asks of
- * one pass of the main loop make one, which runs [update] in a later pass. While a `setRoot` shows the modals and the
- * overlays of its layout the updates are held: an ask, or a posted update that runs while held (asked before the hold
- * was taken), only marks one as wanted, and the last release posts it. Released right before the answer, that update
- * finds nothing new: the state before the answer is sent at once, never held, and an identical state is never sent
- * twice. Every [hold] has one [release]; a release without a hold does nothing, so the count never goes below zero. An
- * update keeps the JavaScript it was asked for ([generation]): one asked by a JavaScript that went before it runs is
- * dropped; a newer ask of the new JavaScript still goes. Main thread only.
- */
-internal class StateHold(
-    private val post: (() -> Unit) -> Unit,
-    private val generation: () -> Int = { 0 },
-    private val update: () -> Unit,
-) {
-    /** The holds not released yet. */
-    var count = 0
-        private set
-
-    // An update was asked while held.
-    private var wanted = false
-    // An update is posted and hasn't run yet.
-    private var scheduled = false
-    // The JavaScript the last ask was for.
-    private var askedIn = 0
-
-    /** Asks for one update in a later pass of the main loop; while held, once the last hold is released. */
-    fun setNeedsUpdate() {
-        askedIn = generation()
-        if (count > 0) wanted = true else schedule()
-    }
-
-    /** The updates asked from now on, and those posted that run from now on, wait for as many [release]s. */
-    fun hold() {
-        count++
-    }
-
-    /** One hold ends; with the last, the update asked while held is posted now. */
-    fun release() {
-        if (count == 0) return
-        count--
-        if (count > 0 || !wanted) return
-        wanted = false
-        schedule()
-    }
-
-    private fun schedule() {
-        if (scheduled) return
-        scheduled = true
-        post {
-            scheduled = false
-            // A hold taken since it was posted: the update waits for the release. The JavaScript it was asked for
-            // went: nothing goes to the new one, which hears its first state after its own changes.
-            when {
-                count > 0 -> wanted = true
-                askedIn == generation() -> update()
-            }
-        }
-    }
-}