@momo-kits/native-kits 0.167.1-duo.18-debug → 0.167.1-duo.19

package/CLAUDE.md

@@ -56,11 +56,13 @@ Publishing is automated (`publish.sh` + GitLab CI on `[ci build]` / `main`). Do
 
 ## SwiftUI kit (`ios/`)
 
-- **Layout mirrors Compose:** `ios/Navigation/` follows `navigation/` file for file (`NavigationContainer`, `Navigator`, `Navigation` (options + per-screen `Navigation`), `StackScreen` (incl. `NavigationFooter`), `BottomSheet`, `ModalScreen`, `HostBackGestureBridge`, `BottomTab/`, `Component/`, `Tracking/`); `ios/Layout/ScreenLayout.swift` mirrors `layout/`. `ios/Application/` keeps only context (`ApplicationEnvironment`), `Localize*`, `MaxApi` and the deprecated `Screen` / `LegacyHeader` (Compose `application/`). Change a navigation piece on both sides together.
+- **Layout mirrors Compose:** `ios/Navigation/` follows `navigation/` file for file (`NavigationContainer`, `Navigator`, `Navigation` (options + per-screen `Navigation`), `StackScreen` (incl. `NavigationFooter`), `StackTransition`, `SwipeBackHaptic`, `BottomSheet`, `ModalScreen`, `HostBackGestureBridge`, `BottomTab/`, `Component/`, `Tracking/`); `ios/Layout/ScreenLayout.swift` mirrors `layout/`. `ios/Application/` keeps only context (`ApplicationEnvironment`), `Localize*`, `MaxApi` and the deprecated `Screen` / `LegacyHeader` (Compose `application/`). Change a navigation piece on both sides together.
 - **File basenames must be unique across the pod** — Swift fails with "filename used twice" even in different folders (hence `LegacyHeader.swift` next to `Navigation/Component/Header.swift`). New folders under `ios/` must be added to `source_files` in `ios/native-kits.podspec`.
 - Screens update their own chrome at runtime through `@EnvironmentObject var navigation: Navigation` → `setOptions { $0.title = … }` (Compose `LocalNavigation`); bottom tabs keep one `Navigation` per tab. The host back bridge is `HostBackGestureBridge.shared` (`NavigatorManager` is a deprecated alias); a bottom tab off its first tab routes back to the first tab (`Navigator.tabBackHandler`, keyed by the hosting screen).
-- The pod's minimum is **iOS 15**, but the navigation shell (`NavigationContainer`, `Navigator`, `HostBackGestureBridge`, `BottomTab`, overplay views) is **iOS 16+** (`@available(iOS 16.0, *)`) because it is built on `NavigationStack`. Keep components outside that shell iOS 15-compatible.
-- `present` opens one `fullScreenCover` that hosts its own `NavigationStack` (`Navigator.presentedPath`): pushes and pops act on the presented flow while it is up, and each overplay (modal / bottom sheet / snackbar) renders in the context it was shown over (`OverplayItem.presentedId`).
+- Everything, navigation shell included, supports the pod's minimum **iOS 15** — no `@available` gates on public types. iOS 16+ APIs only behind `#available` with an iOS 15 path (`Layout`: `BottomSheet` `CapHeight`, `GridFlow` → `_VariadicView` flow row).
+- **Usage is `NavigationContainer` + `Navigator` + `Navigation` only**; the kit owns the stack, transitions, overplays and back gesture. There is no `NavigationStack`: `StackTransition.swift` holds `StackHost` (representable) + `StackController`, the NavHost counterpart. Each entry gets its own `UIHostingController`, kept while on the stack and removed from the window while covered (state kept, onDisappear / onAppear like UINavigationController). Motion is a SwiftUI `offset` per card driven by one `coverage` value on a display link (a UIKit transform would move the safe area); it is Compose `StackTransition` 1:1 (RN `forStackTransitionWithOverlay`: linear 300ms slide, 0.3 parallax, `pink09` scrim to 0.6, 8pt edge shadow to 0.3). Card roots get the container environment via `.environment(\.self, …)` with the kit environment re-applied on top, so host environment objects reach screens.
+- One back stack, root first (`Navigator.entries`, Compose's back stack): `present` appends a dialog entry that rises (FastOutSlowIn 300ms) and later pushes stack on top of it; `dismiss` drops the topmost dialog and everything above it (slides down whole); `popToRoot` returns to the active flow's root. Overplays (modal / bottom sheet / snackbar) render inside the screen they were shown over (`OverplayItem.screenId`, Compose `currentRootId`), so a later push slides over them.
+- Host back gesture: `HostBackGestureBridge.started` / `progressed` / `completed` / `cancelled` scrub the pop (`Navigator.backStarted` …) only for a plain pop; tab back, `onBackHandler`, `preventBack`, an open overplay or a presented top wait for the release and go through `onBackSafe`. `SwipeBackHaptic` ticks at 50pt (`MaxApi.triggerEventVibration`, default = system light impact).
 - Icons are compiled in: `ios/Icon/Icons.swift` is generated from Compose `utils/Icons.kt` by `node scripts/gen-ios-icons.mjs` — don't hand-edit it. A host `icon.json` in the main bundle only adds keys the kit lacks.
 - Bundled assets (colors, Lottie JSON) live in `ios/Resources` and ship in the `MoMoUIKitsResources` bundle; load them through `MoMoUIKitsResources.bundle`, never `Bundle.main`.
 

package/ios/Application/MaxApi.swift

@@ -5,14 +5,23 @@
 //  Swift mirror of the host-app bridge exposed on Kotlin as `vn.momo.maxapi.IMaxApi`
 //  (`LocalMaxApi`). `IMaxApi` itself is an external compiled dependency with no
 //  source in this repo, so this protocol intentionally exposes only the methods
-//  this kit's Kotlin source actually calls (`track`, `dismiss`, `getLanguage`) —
-//  not a full guess at IMaxApi's real surface.
+//  this kit's Kotlin source actually calls (`track`, `dismiss`, `getLanguage`,
+//  `triggerEventVibration`) — not a full guess at IMaxApi's real surface.
 //
 
-import Foundation
+import UIKit
 
 public protocol MaxApi {
     func track(eventName: String, params: [String: Any?])
     func dismiss(completion: (() -> Void)?)
     func getLanguage(callback: @escaping ([String: Any?]?) -> Void)
+    /// `type` is the IMaxApi vibration name (`"light"`, …).
+    func triggerEventVibration(_ type: String)
+}
+
+public extension MaxApi {
+    /// Hosts that don't bridge haptics still get the system light tick.
+    func triggerEventVibration(_ type: String) {
+        UIImpactFeedbackGenerator(style: .light).impactOccurred()
+    }
 }

package/ios/Colors+Radius+Spacing/Radius.swift

@@ -15,6 +15,12 @@ public struct RoundedCorner: Shape {
     var radius: CGFloat = .infinity
     var corners: UIRectCorner = .allCorners
 
+    /// iOS 15 stand-in for `UnevenRoundedRectangle`.
+    public init(radius: CGFloat = .infinity, corners: UIRectCorner = .allCorners) {
+        self.radius = radius
+        self.corners = corners
+    }
+
     public func path(in rect: CGRect) -> Path {
         let path = UIBezierPath(roundedRect: rect, byRoundingCorners: corners, cornerRadii: CGSize(width: radius, height: radius))
         return Path(path.cgPath)

package/ios/Layout/GridContext.swift

@@ -73,9 +73,7 @@ struct GridFlow<Content: View>: View {
         if #available(iOS 16.0, *) {
             FlowRowLayout(gutter: gutter) { content() }
         } else {
-            // No `Layout` protocol before iOS 16: children stack instead of wrapping.
-            // Full-width items — the common case — look identical.
-            VStack(alignment: .leading, spacing: gutter) { content() }
+            _VariadicView.Tree(FlowRowFallback(gutter: gutter, maxWidth: availableWidth)) { content() }
         }
     }
 
@@ -95,6 +93,72 @@ private struct GridWidthKey: PreferenceKey {
     }
 }
 
+/// iOS 15 has no `Layout`: the children are measured, then pinned to the same rows as
+/// `FlowRowLayout` through alignment guides.
+private struct FlowRowFallback: _VariadicView_UnaryViewRoot {
+    let gutter: CGFloat
+    let maxWidth: CGFloat
+
+    func body(children: _VariadicView.Children) -> some View {
+        FlowRowPlacement(children: children, gutter: gutter, maxWidth: maxWidth)
+    }
+}
+
+private struct FlowRowPlacement: View {
+    let children: _VariadicView.Children
+    let gutter: CGFloat
+    let maxWidth: CGFloat
+    @State private var sizes: [AnyHashable: CGSize] = [:]
+
+    var body: some View {
+        let placement = place()
+        ZStack(alignment: .topLeading) {
+            ForEach(children) { child in
+                child
+                    // FlowRowLayout proposes no height
+                    .fixedSize(horizontal: false, vertical: true)
+                    .background(
+                        GeometryReader { proxy in
+                            Color.clear.preference(key: FlowChildSizesKey.self, value: [child.id: proxy.size])
+                        }
+                    )
+                    .alignmentGuide(.leading) { _ in -(placement.origins[child.id]?.x ?? 0) }
+                    .alignmentGuide(.top) { _ in -(placement.origins[child.id]?.y ?? 0) }
+            }
+        }
+        .frame(height: placement.height, alignment: .topLeading)
+        .onPreferenceChange(FlowChildSizesKey.self) { sizes = $0 }
+    }
+
+    private func place() -> (origins: [AnyHashable: CGPoint], height: CGFloat) {
+        var origins: [AnyHashable: CGPoint] = [:]
+        var x: CGFloat = 0
+        var y: CGFloat = 0
+        var rowHeight: CGFloat = 0
+        for child in children {
+            let size = sizes[child.id] ?? .zero
+            // Sub-point tolerance: spans are computed to land exactly on `maxWidth`.
+            if x > 0, x + size.width > maxWidth + 0.5 {
+                x = 0
+                y += rowHeight + gutter
+                rowHeight = 0
+            }
+            origins[child.id] = CGPoint(x: x, y: y)
+            x += size.width + gutter
+            rowHeight = max(rowHeight, size.height)
+        }
+        return (origins, y + rowHeight)
+    }
+}
+
+private struct FlowChildSizesKey: PreferenceKey {
+    static var defaultValue: [AnyHashable: CGSize] = [:]
+
+    static func reduce(value: inout [AnyHashable: CGSize], nextValue: () -> [AnyHashable: CGSize]) {
+        value.merge(nextValue()) { $1 }
+    }
+}
+
 /// Wrapping row with equal horizontal/vertical spacing — the Compose `FlowRow` equivalent.
 @available(iOS 16.0, *)
 private struct FlowRowLayout: Layout {

package/ios/Navigation/BottomSheet.swift

@@ -35,7 +35,6 @@ public struct BottomSheetHeader {
 
 // MARK: - Bottom sheet view
 
-@available(iOS 16.0, *)
 struct BottomSheetView<Content: View>: View {
     let header: BottomSheetHeader
     let isSurface: Bool
@@ -294,12 +293,40 @@ struct BottomSheetView<Content: View>: View {
 /// Compose's `heightIn(max:)`. `.frame(maxHeight:)` grows to the cap whenever the proposal is
 /// larger, leaving a gap above the header; this sizes the sheet to its content and only caps it
 /// when taller.
-@available(iOS 16.0, *)
 private struct CapHeight: ViewModifier {
     let maxHeight: CGFloat
 
     func body(content: Content) -> some View {
-        CapHeightLayout(maxHeight: maxHeight) { content }
+        if #available(iOS 16.0, *) {
+            CapHeightLayout(maxHeight: maxHeight) { content }
+        } else {
+            content.modifier(CapHeightFallback(maxHeight: maxHeight))
+        }
+    }
+}
+
+/// iOS 15 has no `Layout`: the sheet hugs its ideal height until that outgrows the cap, then is
+/// held at the cap (the ideal height can't be read again without a second copy of the content).
+private struct CapHeightFallback: ViewModifier {
+    let maxHeight: CGFloat
+    @State private var capped = false
+
+    func body(content: Content) -> some View {
+        content
+            // both modifiers stay in place whatever `capped` is, so the content keeps its identity
+            .fixedSize(horizontal: false, vertical: !capped)
+            .background(
+                GeometryReader { proxy in
+                    Color.clear
+                        .onAppear { cap(proxy.size.height) }
+                        .onChange(of: proxy.size.height) { cap($0) }
+                }
+            )
+            .frame(height: capped ? maxHeight : nil, alignment: .top)
+    }
+
+    private func cap(_ height: CGFloat) {
+        if !capped, height > maxHeight { capped = true }
     }
 }
 
@@ -340,7 +367,6 @@ private struct BottomSheetFooter: View {
     }
 }
 
-@available(iOS 16.0, *)
 private func safeAreaBottomInset() -> CGFloat {
     let bottomInset = UIApplication.shared.connectedScenes
         .compactMap { ($0 as? UIWindowScene)?.keyWindow?.safeAreaInsets.bottom }

package/ios/Navigation/BottomTab/BottomTab.swift

@@ -9,7 +9,6 @@
 
 import SwiftUI
 
-@available(iOS 16.0, *)
 public struct BottomTab: View {
     private let items: [BottomTabItem]
     private let floatingButton: BottomTabFloatingButton?
@@ -178,7 +177,6 @@ private struct TabScreenHost: View {
 }
 
 /// Bottom safe-area inset (home indicator).
-@available(iOS 16.0, *)
 private func safeAreaBottomInset() -> CGFloat {
     let bottomInset = UIApplication.shared.connectedScenes
         .compactMap { ($0 as? UIWindowScene)?.keyWindow?.safeAreaInsets.bottom }

package/ios/Navigation/Component/SnackBar.swift

@@ -49,7 +49,6 @@ public struct SnackBar {
 
 /// Self-animating container. Slides the content up on appear, schedules an
 /// auto-dismiss after `duration`, and animates out before removing the overplay.
-@available(iOS 16.0, *)
 struct SnackBarView: View {
     let snackBar: SnackBar
     /// Distance from the window bottom to the top of the screen's footer, or the navigation bar

package/ios/Navigation/HostBackGestureBridge.swift

@@ -4,18 +4,19 @@
 //
 //  SwiftUI mirror of Compose's `navigation/HostBackGestureBridge.kt`: the host owns the edge-pan
 //  recogniser and routes a back into the topmost kit stack. NavigationContainer attaches itself.
-//  The kit stack is a NavigationStack, so there is no seekable transition: the host only pops.
+//  `started` / `progressed` / `completed` / `cancelled` scrub the pop transition with the finger;
+//  a host that only calls `pop` gets the regular animated back.
 //
 
-import Foundation
+import UIKit
 
-@available(iOS 16.0, *)
 public final class HostBackGestureBridge {
     public static let shared = HostBackGestureBridge()
     private init() {}
 
-    // Weak: a container torn down while its cover is up never reports its disappearance.
+    // Weak: a container torn down without disappearing must not keep receiving backs.
     private var navigators: [WeakNavigator] = []
+    private weak var gestureTarget: Navigator?
 
     /// Set while a bottom tab other than the first is selected; the host shows its floating arrow.
     public var shouldUseFloatingArrowBack = false
@@ -28,6 +29,7 @@ public final class HostBackGestureBridge {
 
     public func detach(_ navigator: Navigator) {
         navigators.removeAll { $0.value == nil || $0.value === navigator }
+        if gestureTarget === navigator { gestureTarget = nil }
     }
 
     /// Whether a kit stack is on screen at all.
@@ -38,6 +40,27 @@ public final class HostBackGestureBridge {
 
     public func pop() { top()?.onBackSafe() }
 
+    public func started() {
+        guard let target = top() else { return }
+        gestureTarget = target
+        target.backStarted()
+    }
+
+    /// `progress` is the touch travel over the window width, 0...1.
+    public func progressed(_ progress: CGFloat) {
+        gestureTarget?.backProgressed(min(max(progress, 0), 1))
+    }
+
+    public func completed() {
+        (gestureTarget ?? top())?.backCompleted()
+        gestureTarget = nil
+    }
+
+    public func cancelled() {
+        gestureTarget?.backCancelled()
+        gestureTarget = nil
+    }
+
     @available(*, deprecated, renamed: "attach")
     public func push(_ navigator: Navigator) { attach(navigator) }
 
@@ -47,11 +70,9 @@ public final class HostBackGestureBridge {
     private func top() -> Navigator? { navigators.last { $0.value != nil }?.value }
 }
 
-@available(iOS 16.0, *)
 @available(*, deprecated, renamed: "HostBackGestureBridge")
 public typealias NavigatorManager = HostBackGestureBridge
 
-@available(iOS 16.0, *)
 private struct WeakNavigator {
     weak var value: Navigator?
 }

package/ios/Navigation/ModalScreen.swift

@@ -9,7 +9,6 @@
 
 import SwiftUI
 
-@available(iOS 16.0, *)
 struct ModalScreen<Content: View>: View {
     let barrierDismissible: Bool
     let content: () -> Content

package/ios/Navigation/Navigation.swift

@@ -66,6 +66,11 @@ public struct NavigationOptions {
     public var fullScreenContent: Bool
     public var hiddenBack: Bool
     public var backgroundColor: Color?
+    // AI-GENERATED START: custom screen background view (Compose backgroundComponent)
+    /// Drawn instead of `backgroundColor` over the whole window: under the header and the status bar,
+    /// across the iPhone Duo side strips, and not shrunk by the keyboard. Pair with `headerTransparent`.
+    public var background: (() -> AnyView)?
+    // AI-GENERATED END: custom screen background view (Compose backgroundComponent)
     public var tintColor: Color?
     public var scrollable: Bool
     /// Compose's `ScrollData.scrollToTopCallback`, fired on a status-bar tap.
@@ -98,6 +103,9 @@ public struct NavigationOptions {
         fullScreenContent: Bool = false,
         hiddenBack: Bool = false,
         backgroundColor: Color? = nil,
+        // AI-GENERATED START: custom screen background view (Compose backgroundComponent)
+        background: (() -> AnyView)? = nil,
+        // AI-GENERATED END: custom screen background view (Compose backgroundComponent)
         tintColor: Color? = Colors.black17,
         scrollable: Bool = true,
         scrollToTopCallback: (() -> Void)? = nil,
@@ -125,6 +133,9 @@ public struct NavigationOptions {
         self.fullScreenContent = fullScreenContent
         self.hiddenBack = hiddenBack
         self.backgroundColor = backgroundColor
+        // AI-GENERATED START: custom screen background view (Compose backgroundComponent)
+        self.background = background
+        // AI-GENERATED END: custom screen background view (Compose backgroundComponent)
         self.tintColor = tintColor
         self.scrollable = scrollable
         self.scrollToTopCallback = scrollToTopCallback
@@ -161,6 +172,9 @@ struct OptionsStackScreen: View {
     var body: some View {
         StackScreen(
             backgroundColor: options.backgroundColor,
+            // AI-GENERATED START: custom screen background view (Compose backgroundComponent)
+            background: options.background,
+            // AI-GENERATED END: custom screen background view (Compose backgroundComponent)
             headerTransparent: options.headerTransparent,
             fullScreenContent: options.fullScreenContent,
             tintColor: options.tintColor ?? Colors.black17,

package/ios/Navigation/NavigationContainer.swift

@@ -2,14 +2,13 @@
 //  NavigationContainer.swift
 //  MoMoUIKits
 //
-//  SwiftUI mirror of Compose's `navigation/NavigationContainer.kt`: wraps NavigationStack
-//  (iOS 16+), injects Navigator, theme, localize and font scale, and renders every registered
-//  screen inside `StackScreen` chrome built from its options.
+//  SwiftUI mirror of Compose's `navigation/NavigationContainer.kt`: hosts the kit stack
+//  (`StackHost`, the NavHost counterpart), injects Navigator, theme, localize and font scale, and
+//  renders every registered screen inside `StackScreen` chrome built from its options.
 //
 
 import SwiftUI
 
-@available(iOS 16.0, *)
 public struct NavigationContainer<Initial: View>: View {
     @StateObject private var navigator: Navigator
     @StateObject private var applicationEnvironment: ApplicationEnvironment
@@ -71,24 +70,17 @@ public struct NavigationContainer<Initial: View>: View {
     }
 
     public var body: some View {
-        withKitEnvironment(
-            stack(path: $navigator.path, root: navigator.rootRoute)
-                .overlay { overplayLayer(presentedId: nil) }
+        StackHost(
+            navigator: navigator,
+            entries: navigator.entries,
+            screen: { [navigator] entry in
+                guard let screen = navigator.registry.getScreen(id: entry.id) else { return AnyView(EmptyView()) }
+                return AnyView(ScreenHost(screen: screen, navigator: navigator))
+            },
+            decorate: { AnyView(withKitEnvironment($0)) }
         )
-        .fullScreenCover(item: Binding(
-            get: { navigator.coverRoute },
-            // A close that bypasses the navigator (e.g. `dismiss()`) still tears the flow down.
-            // SwiftUI also writes nil after a navigator-driven close; by then a new screen may
-            // already be queued, so only a cover that is still showing counts.
-            set: { if $0 == nil, navigator.coverRoute != nil { navigator.dismiss() } }
-        )) { route in
-            withKitEnvironment(
-                stack(path: $navigator.presentedPath, root: DynamicScreenRoute(id: route.id))
-                    .overlay { overplayLayer(presentedId: route.id) }
-            )
-            .onAppear { navigator.coverDidAppear() }
-            .onDisappear { navigator.coverDidDisappear() }
-        }
+        // edge to edge: each screen's hosting controller takes the safe area and keyboard itself
+        .ignoresSafeArea()
         .onAppear {
             if navigator.composeApi == nil {
                 navigator.composeApi = composeApi
@@ -110,42 +102,10 @@ public struct NavigationContainer<Initial: View>: View {
             // AI-GENERATED END: demote the MaxApi language pull to a seed of last resort
         }
         .onDisappear {
-            // Our own cover hides the stack without leaving it; host back must still reach it.
-            guard navigator.presented == nil else { return }
             HostBackGestureBridge.shared.detach(navigator)
         }
     }
 
-    private func stack(path: Binding<[DynamicScreenRoute]>, root: DynamicScreenRoute) -> some View {
-        NavigationStack(path: path) {
-            screenView(for: root)
-                // A reset swaps the root in place; without the id it would inherit the old root's state.
-                .id(root.id)
-                .navigationDestination(for: DynamicScreenRoute.self) { route in
-                    screenView(for: route)
-                }
-        }
-    }
-
-    @ViewBuilder
-    private func screenView(for route: DynamicScreenRoute) -> some View {
-        if let screen = navigator.registry.getScreen(id: route.id) {
-            ScreenHost(screen: screen, navigator: navigator)
-                .navigationBarBackButtonHidden(true)
-        } else {
-            EmptyView()
-        }
-    }
-
-    /// Each context draws only the overplays shown over it, so one never re-mounts elsewhere.
-    @ViewBuilder
-    private func overplayLayer(presentedId: Int?) -> some View {
-        if let item = navigator.overplay, item.presentedId == presentedId {
-            OverplayHost(item: item)
-                .momoScreenLayout()
-        }
-    }
-
     private func withKitEnvironment<Content: View>(_ content: Content) -> some View {
         content
             .environmentObject(navigator)
@@ -159,7 +119,6 @@ public struct NavigationContainer<Initial: View>: View {
 
 // MARK: - ScreenHost
 
-@available(iOS 16.0, *)
 private struct ScreenHost: View {
     let screen: DynamicScreen
     let navigator: Navigator
@@ -180,15 +139,26 @@ private struct ScreenHost: View {
             goBack: { navigator.onBackSafe() },
             content: screen.content
         )
+        // Compose draws the overplay inside the screen it was shown over, under its LocalNavigation.
+        .overlay { OverplayLayer(screenId: screen.id) }
         .environmentObject(navigation)
-        // Per screen, not around the NavigationStack: a state-driven reader there stops path pushes rendering.
         .momoScreenLayout()
     }
 }
 
+private struct OverplayLayer: View {
+    let screenId: Int
+    @EnvironmentObject private var navigator: Navigator
+
+    var body: some View {
+        if let item = navigator.overplay, item.screenId == screenId {
+            OverplayHost(item: item)
+        }
+    }
+}
+
 // MARK: - Overplay host
 
-@available(iOS 16.0, *)
 private struct OverplayHost: View {
     let item: OverplayItem
     @EnvironmentObject var navigator: Navigator