@momo-kits/native-kits 0.300.3 → 0.300.4-debug

package/ios/{Application/Navigation → Navigation}/Navigator.swift

@@ -2,9 +2,9 @@
 //  Navigator.swift
 //  MoMoUIKits
 //
-//  SwiftUI mirror of Compose's Navigator + DynamicScreenRegistry.
-//  Screens are registered by Int id; the NavigationStack path stores routes
-//  by id and looks up content from the registry on render.
+//  SwiftUI mirror of Compose's `navigation/Navigator.kt`: Navigator, DynamicScreenRegistry and
+//  the overplay model. Screens are registered by Int id; the stack paths store routes by id and
+//  content is looked up from the registry on render.
 //
 
 import SwiftUI
@@ -31,6 +31,7 @@ public struct DynamicScreen {
 
 public final class DynamicScreenRegistry {
     private var screens: [Int: DynamicScreen] = [:]
+    private var navigations: [Int: WeakNavigation] = [:]
     private var idCounter: Int = 1
 
     public init() {}
@@ -49,12 +50,20 @@ public final class DynamicScreenRegistry {
 
     public func unregister(id: Int) {
         screens.removeValue(forKey: id)
+        navigations.removeValue(forKey: id)
     }
 
     public func unregisterAll() {
         screens.removeAll()
+        navigations.removeAll()
     }
 
+    func bind(_ navigation: Navigation) {
+        navigations[navigation.id] = WeakNavigation(value: navigation)
+    }
+
+    func navigation(id: Int) -> Navigation? { navigations[id]?.value }
+
     public func getScreen(id: Int) -> DynamicScreen? { screens[id] }
 
     public func latest() -> DynamicScreen? {
@@ -66,6 +75,10 @@ public final class DynamicScreenRegistry {
     }
 }
 
+private struct WeakNavigation {
+    weak var value: Navigation?
+}
+
 // MARK: - Overplay
 
 public enum OverplayType {
@@ -81,20 +94,34 @@ public struct OverplayItem: Identifiable {
     // Bottom-sheet params (mirrors Compose's OverplayComponentParams.BottomSheet).
     public var isSurface: Bool = false
     public var header: BottomSheetHeader? = nil
+    public var draggable: Bool = true
+    public var useBottomInset: Bool = true
+    public var footer: (() -> AnyView)? = nil
     // Snack-bar payload (mirrors Compose's SnackBar value).
     public var snackBar: SnackBar? = nil
+    /// The screen it was shown over (Compose's overplay root id): it renders inside that screen,
+    /// so a later push slides over it instead of re-mounting it on the new top.
+    public internal(set) var screenId: Int? = nil
+}
+
+// MARK: - Stack
+
+/// One back-stack entry, root first. A presented screen is an entry like any other (Compose's
+/// `DynamicDialogRoute` in the same NavHost): it rises instead of sliding in, and later pushes
+/// stack on top of it.
+struct StackEntry: Hashable, Identifiable {
+    let id: Int
+    let isDialog: Bool
 }
 
 // MARK: - Navigator
 
-@available(iOS 16.0, *)
 public final class Navigator: ObservableObject {
-    @Published public var path: [DynamicScreenRoute] = [] {
-        // Disposal hangs off the path so every route that leaves the stack — pop,
-        // replace, reset — is released the same way, after its exit transition.
-        didSet { disposeScreens(droppedFrom: oldValue) }
+    @Published private(set) var entries: [StackEntry] = [] {
+        // Disposal hangs off the stack so every entry that leaves it — pop, replace, reset,
+        // dismiss — is released the same way, after its exit transition.
+        didSet { disposeScreens(droppedFrom: oldValue, keeping: entries) }
     }
-    @Published public var presented: DynamicDialogRoute?
     @Published public var overplay: OverplayItem?
 
     /// Owned per-Navigator (mirrors Compose's `remember { DynamicScreenRegistry() }` +
@@ -108,8 +135,20 @@ public final class Navigator: ObservableObject {
     /// actually removed via `finishOverplayDismiss`.
     private var overplayDismissHandler: (() -> Void)?
 
-    public private(set) var rootRoute: DynamicScreenRoute
+    public var rootRoute: DynamicScreenRoute { DynamicScreenRoute(id: entries[0].id) }
     public var composeApi: KitComposeApi?
+    /// Host dismiss fallback when there is no `composeApi` (Compose's `maxApi.dismiss`).
+    public var maxApi: MaxApi?
+
+    /// Set by a bottom tab off its first tab: back on the screen hosting the tabs returns to the
+    /// first tab (Compose `tabBackHandler`). Keyed by that screen, so a screen pushed or presented
+    /// over the tabs still pops normally.
+    var tabBackHandler: (screenId: Int, handler: () -> Void)?
+
+    /// The container's stack view, which plays (and lets the host gesture scrub) the transitions.
+    weak var stackController: StackController?
+    private var isSeekingBack = false
+    private var swipeHaptic = SwipeBackHaptic()
 
     public init(
         initialScreenName: String = "",
@@ -118,22 +157,18 @@ public final class Navigator: ObservableObject {
         composeApi: KitComposeApi? = nil
     ) {
         self.composeApi = composeApi
-        self.rootRoute = registry.register(
+        let root = registry.register(
             screenName: initialScreenName,
             content: initialContent,
             options: options
         )
+        entries = [StackEntry(id: root.id, isDialog: false)]
     }
 
     // MARK: Stack
 
     public func push<V: View>(@ViewBuilder _ content: @escaping () -> V, options: NavigationOptions? = nil) {
-        let route = registry.register(
-            screenName: options?.screenName ?? "",
-            content: { AnyView(content()) },
-            options: options
-        )
-        path.append(route)
+        push(screenName: options?.screenName ?? "", content, options: options)
     }
 
     public func push<V: View>(
@@ -141,40 +176,26 @@ public final class Navigator: ObservableObject {
         @ViewBuilder _ content: @escaping () -> V,
         options: NavigationOptions? = nil
     ) {
-        let route = registry.register(
-            screenName: screenName,
-            content: { AnyView(content()) },
-            options: options
-        )
-        path.append(route)
+        entries.append(register(screenName, content, options, isDialog: false))
     }
 
     public func replace<V: View>(@ViewBuilder _ content: @escaping () -> V, options: NavigationOptions? = nil) {
-        guard !path.isEmpty else { return }
-        path.removeLast()
-        push(content, options: options)
+        replace(screenName: options?.screenName ?? "", content, options: options)
     }
 
+    /// Compose pops the top entry (a presented one included) and navigates, so the replacement
+    /// always lands as a pushed screen; on the root it becomes the new root.
     public func replace<V: View>(
         screenName: String,
         @ViewBuilder _ content: @escaping () -> V,
         options: NavigationOptions? = nil
     ) {
-        guard !path.isEmpty else { return }
-        path.removeLast()
-        push(screenName: screenName, content, options: options)
+        let entry = register(screenName, content, options, isDialog: false)
+        entries = Array(entries.dropLast()) + [entry]
     }
 
     public func reset<V: View>(@ViewBuilder _ content: @escaping () -> V, options: NavigationOptions? = nil) {
-        let previousRoot = rootRoute.id
-        path.removeAll()
-        let route = registry.register(
-            screenName: options?.screenName ?? "",
-            content: { AnyView(content()) },
-            options: options
-        )
-        rootRoute = route
-        disposeScreens([previousRoot])
+        reset(screenName: options?.screenName ?? "", content, options: options)
     }
 
     public func reset<V: View>(
@@ -182,15 +203,21 @@ public final class Navigator: ObservableObject {
         @ViewBuilder _ content: @escaping () -> V,
         options: NavigationOptions? = nil
     ) {
-        let previousRoot = rootRoute.id
-        path.removeAll()
+        entries = [register(screenName, content, options, isDialog: false)]
+    }
+
+    private func register<V: View>(
+        _ screenName: String,
+        _ content: @escaping () -> V,
+        _ options: NavigationOptions?,
+        isDialog: Bool
+    ) -> StackEntry {
         let route = registry.register(
             screenName: screenName,
             content: { AnyView(content()) },
             options: options
         )
-        rootRoute = route
-        disposeScreens([previousRoot])
+        return StackEntry(id: route.id, isDialog: isDialog)
     }
 
     public func pop(_ count: Int = 1, callback: (() -> Void)? = nil) {
@@ -211,20 +238,19 @@ public final class Navigator: ObservableObject {
             // Mirrors Kotlin: a snackbar doesn't block back-navigation, so popping
             // while one is showing pops the screen underneath and clears the
             // snackbar immediately, without playing its dismiss animation.
-            overplayDismissHandler = nil
-            overplay = nil
+            replaceOverplay(with: nil)
             guard popScreen() else {
                 callback?()
                 return
             }
             popStep(remaining: remaining - 1, callback: callback)
-        } else if overplay != nil {
+        } else if let closing = overplay?.id {
             hideOverplay()
             DispatchQueue.main.asyncAfter(deadline: .now() + Self.overplayDismissDelay) { [weak self] in
                 guard let self else { return }
                 // The component reports back through `finishOverplayDismiss` once its exit
                 // animation ends; clear it here if it never did, so the step is not wasted.
-                if self.overplay != nil { self.finishOverplayDismiss() }
+                self.finishOverplayDismiss(id: closing)
                 self.popStep(remaining: remaining - 1, callback: callback)
             }
         } else {
@@ -236,43 +262,62 @@ public final class Navigator: ObservableObject {
         }
     }
 
-    /// Pops the topmost presented screen or stack entry. Returns `false` (and requests
-    /// a host dismiss) when there is nothing left to pop.
+    /// Pops the top entry. Returns `false` (and requests a host dismiss) on the root.
     @discardableResult
     private func popScreen() -> Bool {
-        if presented != nil {
-            let dismissedId = presented?.id
-            presented = nil
-            if let id = dismissedId { disposeScreens([id]) }
-            return true
-        } else if !path.isEmpty {
-            path.removeLast()
-            return true
-        } else {
-            composeApi?.requestCallback(funcName: "dismiss", params: nil, onResponse: nil)
+        guard canPop() else {
+            requestHostDismiss()
             return false
         }
+        entries.removeLast()
+        return true
     }
 
+    private func requestHostDismiss() {
+        if let composeApi {
+            composeApi.requestCallback(funcName: "dismiss", params: nil, onResponse: nil)
+        } else {
+            maxApi?.dismiss(completion: nil)
+        }
+    }
+
+    /// Whether there is a screen to go back to (Compose's `canPop`); at the root a back
+    /// dismisses the mini app instead.
+    public func canPop() -> Bool {
+        entries.count > 1
+    }
+
+    /// Back to the root of the active flow: the topmost presented screen while one is up,
+    /// the stack root otherwise.
     public func popToRoot() {
-        path.removeAll()
+        let root = entries.lastIndex(where: \.isDialog) ?? 0
+        entries = Array(entries[...root])
     }
 
-    /// The entry a back action applies to — mirrors Compose's `currentScreen()`
-    /// (`navController.currentBackStackEntry`): a presented screen sits on top of
-    /// the stack, otherwise it is the last pushed screen, otherwise the root.
+    /// The entry a back action applies to — Compose's `currentScreen()`
+    /// (`navController.currentBackStackEntry`).
     private func currentScreen() -> DynamicScreen? {
-        registry.getScreen(id: presented?.id ?? path.last?.id ?? rootRoute.id)
+        entries.last.flatMap { registry.getScreen(id: $0.id) }
     }
 
     public func onBackSafe(callback: (() -> Void)? = nil) {
+        // An open modal or bottom sheet takes the back first (their BackHandler in Compose).
+        if let overplay, overplay.type != .snackBar {
+            pop(1, callback: callback)
+            return
+        }
         let latest = currentScreen()
+        if let tabBackHandler, tabBackHandler.screenId == -1 || tabBackHandler.screenId == latest?.id {
+            tabBackHandler.handler()
+            return
+        }
         if let onBack = latest?.options?.onBackHandler {
             onBack()
             return
         }
         if let preventBack = latest?.options?.headerBackProps?.preventBack {
-            showModal {
+            // stored in `overplay`, so a strong self would cycle until the popup closes
+            showModal { [weak self] in
                 PopupNotify(
                     props: PopupNotifyProps(
                         image: preventBack.image,
@@ -281,7 +326,7 @@ public final class Navigator: ObservableObject {
                         error: preventBack.error,
                         primary: PopupAction(
                             title: preventBack.primary?.title ?? "",
-                            onPress: { [weak self] in
+                            onPress: {
                                 preventBack.primary?.onPress?()
                                 // Close the popup, then leave the screen (matches Compose's pop(2)).
                                 self?.pop(2, callback: callback)
@@ -290,14 +335,14 @@ public final class Navigator: ObservableObject {
                         secondary: preventBack.secondary.map { secondary in
                             PopupAction(
                                 title: secondary.title,
-                                onPress: { [weak self] in
+                                onPress: {
                                     secondary.onPress?()
                                     self?.hideOverplay()
                                 }
                             )
                         },
                         buttonDirection: preventBack.buttonDirection,
-                        onIconClose: { [weak self] in
+                        onIconClose: {
                             preventBack.onIconClose?()
                             self?.hideOverplay()
                         },
@@ -313,12 +358,7 @@ public final class Navigator: ObservableObject {
     // MARK: Modal-style screen (vertical slide)
 
     public func present<V: View>(@ViewBuilder _ content: @escaping () -> V, options: NavigationOptions? = nil) {
-        let route = registry.register(
-            screenName: options?.screenName ?? "",
-            content: { AnyView(content()) },
-            options: options
-        )
-        presented = DynamicDialogRoute(id: route.id)
+        present(screenName: options?.screenName ?? "", content, options: options)
     }
 
     public func present<V: View>(
@@ -326,19 +366,55 @@ public final class Navigator: ObservableObject {
         @ViewBuilder _ content: @escaping () -> V,
         options: NavigationOptions? = nil
     ) {
-        let route = registry.register(
-            screenName: screenName,
-            content: { AnyView(content()) },
-            options: options
-        )
-        presented = DynamicDialogRoute(id: route.id)
+        entries.append(register(screenName, content, options, isDialog: true))
     }
 
+    /// Closes the topmost presented screen together with everything pushed over it.
     public func dismiss() {
-        if let id = presented?.id {
-            registry.unregister(id: id)
+        guard let presented = entries.lastIndex(where: \.isDialog) else { return }
+        entries = Array(entries[..<presented])
+    }
+
+    // MARK: Host back gesture (Compose's HostBackTarget)
+
+    /// Only a plain pop is scrubbed. A back the screen handles itself — tab back, custom
+    /// handler, prevent-back popup, an open overplay — or one closing a presented screen
+    /// waits for the release and goes through `onBackSafe`, as RN turns the gesture off there.
+    private var canSeekBack: Bool {
+        guard canPop(), overplay == nil, let top = entries.last, !top.isDialog else { return false }
+        if let tabBackHandler, tabBackHandler.screenId == -1 || tabBackHandler.screenId == top.id {
+            return false
         }
-        presented = nil
+        let options = registry.getScreen(id: top.id)?.options
+        return options?.onBackHandler == nil && options?.headerBackProps?.preventBack == nil
+    }
+
+    func backStarted() {
+        swipeHaptic.reset()
+        isSeekingBack = canSeekBack && stackController?.beginBackSeek() == true
+    }
+
+    func backProgressed(_ progress: CGFloat) {
+        guard isSeekingBack, let stackController else { return }
+        stackController.seekBack(to: progress)
+        swipeHaptic.update(travelled: progress * stackController.view.bounds.width, maxApi: maxApi)
+    }
+
+    func backCompleted() {
+        let wasSeeking = isSeekingBack
+        isSeekingBack = false
+        // A seek cut short by a programmatic change falls back to a regular back.
+        guard wasSeeking, stackController?.finishBackSeek() == true else {
+            onBackSafe()
+            return
+        }
+        entries.removeLast()
+    }
+
+    func backCancelled() {
+        guard isSeekingBack else { return }
+        isSeekingBack = false
+        stackController?.cancelBackSeek()
     }
 
     // MARK: Overplay
@@ -348,13 +424,13 @@ public final class Navigator: ObservableObject {
         barrierDismissible: Bool = true,
         onDismiss: (() -> Void)? = nil
     ) {
-        overplayDismissHandler = nil
-        overplay = OverplayItem(
+        replaceOverplay(with: OverplayItem(
             type: .modal,
             content: { AnyView(content()) },
             barrierDismissible: barrierDismissible,
-            onDismiss: onDismiss
-        )
+            onDismiss: onDismiss,
+            screenId: entries.last?.id
+        ))
     }
 
     public func showBottomSheet<V: View>(
@@ -362,29 +438,35 @@ public final class Navigator: ObservableObject {
         isSurface: Bool = false,
         barrierDismissible: Bool = true,
         header: BottomSheetHeader? = nil,
-        onDismiss: (() -> Void)? = nil
+        onDismiss: (() -> Void)? = nil,
+        draggable: Bool = true,
+        useBottomInset: Bool = true,
+        footer: (() -> AnyView)? = nil
     ) {
-        overplayDismissHandler = nil
-        overplay = OverplayItem(
+        replaceOverplay(with: OverplayItem(
             type: .bottomSheet,
             content: { AnyView(content()) },
             barrierDismissible: barrierDismissible,
             onDismiss: onDismiss,
             isSurface: isSurface,
-            header: header
-        )
+            header: header,
+            draggable: draggable,
+            useBottomInset: useBottomInset,
+            footer: footer,
+            screenId: entries.last?.id
+        ))
     }
 
     /// Mirrors Compose's `showSnackBar(snackBar:)`.
     public func showSnackBar(_ snackBar: SnackBar, onDismiss: (() -> Void)? = nil) {
-        overplayDismissHandler = nil
-        overplay = OverplayItem(
+        replaceOverplay(with: OverplayItem(
             type: .snackBar,
             content: { AnyView(EmptyView()) },
             barrierDismissible: false,
             onDismiss: onDismiss,
-            snackBar: snackBar
-        )
+            snackBar: snackBar,
+            screenId: entries.last?.id
+        ))
     }
 
     // MARK: Overplay dismissal
@@ -399,10 +481,23 @@ public final class Navigator: ObservableObject {
     /// `hardClearAfterDismiss`). Called by a component once its exit animation
     /// has completed.
     public func finishOverplayDismiss() {
-        let dismissCallback = overplay?.onDismiss
+        replaceOverplay(with: nil)
+    }
+
+    /// Same, but only while `id` is still the overplay: an exit that ends after a newer overplay
+    /// took its place must not take that one down.
+    public func finishOverplayDismiss(id: UUID) {
+        guard overplay?.id == id else { return }
+        replaceOverplay(with: nil)
+    }
+
+    /// A replaced overplay counts as dismissed (Compose disposes it), so its `onDismiss` fires once,
+    /// whether it was still closing or not.
+    private func replaceOverplay(with item: OverplayItem?) {
+        let replaced = overplay
         overplayDismissHandler = nil
-        overplay = nil
-        dismissCallback?()
+        overplay = item
+        replaced?.onDismiss?()
     }
 
     public func hideOverplay() {
@@ -419,6 +514,14 @@ public final class Navigator: ObservableObject {
         if overplay?.type == .snackBar { hideOverplay() }
     }
 
+    /// Room the current screen's footer (or navigation bar) takes from the window bottom.
+    func snackBarBottomInset() -> CGFloat {
+        guard let id = currentScreen()?.id, let navigation = registry.navigation(id: id) else {
+            return NavigationFooter.navigationBarInset
+        }
+        return navigation.bottomObstruction
+    }
+
     // MARK: Screen disposal
 
     /// Matches the `delay(300)` Compose waits in `dismissScreen` before unregistering,
@@ -429,22 +532,19 @@ public final class Navigator: ObservableObject {
     /// after the component has taken itself down.
     private static let overplayDismissDelay: TimeInterval = 0.3
 
-    private func disposeScreens(droppedFrom previous: [DynamicScreenRoute]) {
-        let live = Set(path.map(\.id))
-        disposeScreens(previous.map(\.id).filter { !live.contains($0) })
+    private func disposeScreens(droppedFrom previous: [StackEntry], keeping current: [StackEntry]) {
+        let kept = Set(current.map(\.id))
+        disposeScreens(previous.map(\.id).filter { !kept.contains($0) })
     }
 
     /// Screens are released only once the pop transition has played out: the outgoing
-    /// view is still on screen while it animates and the registry is what renders it —
-    /// dropping it right away blanks the screen mid-transition. Liveness is re-checked
-    /// when the timer fires, so a route pushed back before then keeps its screen.
+    /// view is still on screen while it animates. Liveness is re-checked when the timer
+    /// fires, so an entry back on the stack by then keeps its screen.
     private func disposeScreens(_ ids: [Int]) {
         guard !ids.isEmpty else { return }
         DispatchQueue.main.asyncAfter(deadline: .now() + Self.screenDisposeDelay) { [weak self] in
             guard let self else { return }
-            var live = Set(self.path.map(\.id))
-            live.insert(self.rootRoute.id)
-            if let presented = self.presented { live.insert(presented.id) }
+            let live = Set(self.entries.map(\.id))
             for id in ids where !live.contains(id) {
                 self.registry.unregister(id: id)
             }