@momo-kits/native-kits 0.167.1-duo.3-debug → 0.167.1-duo.4

package/CLAUDE.md

@@ -35,6 +35,13 @@ No unit-test suite is configured. Validate changes by compiling the relevant tar
 ./gradlew :sample:androidApp:installDebug                 # run demo on device/emulator
 ```
 
+The SwiftUI kit (`ios/`, pod `MoMoUIKits`) compiles on its own through the sample's Pods project (`pod install` in `sample/iosApp` first when files are added):
+
+```bash
+xcodebuild -project sample/iosApp/Pods/Pods.xcodeproj -scheme MoMoUIKits -sdk iphonesimulator \
+  -destination 'generic/platform=iOS Simulator' build
+```
+
 Publishing is automated (`publish.sh` + GitLab CI on `[ci build]` / `main`). Do not publish manually unless asked: `sh publish.sh beta` / `sh publish.sh release` (Maven→GitLab + NPM).
 
 ## Architecture essentials
@@ -47,16 +54,18 @@ Publishing is automated (`publish.sh` + GitLab CI on `[ci build]` / `main`). Do
 - Navigation uses a runtime `DynamicScreenRegistry`; overlays (modal/bottom-sheet/snackbar) go through `Navigator` + `OverplayComponentRegistry`.
 - **iOS swipe-back:** the host owns the only edge-pan recogniser and replays it through `HostBackGestureBridge` (`navigation/HostBackGestureBridge.kt`; the kit framework is never exported, so the host reaches it through its own Koin-provided facade): `checkCanPop` / `canPopInner` / `pop` route the back into the kit stack, `started` / `progressed` / `completed` / `cancelled` seek the NavHost transition, `shouldUseFloatingArrowBack` is set by bottom tabs. `NavigationContainer` attaches itself automatically (`AttachHostBackGesture`, iOS only, detached by identity on dispose) — hosts need no wrapper and no `setNavigator`. `maxApi` is a required parameter of `NavigationContainer` — every container, nested or root, is handed its host bridge explicitly.
 
-## Screen layout / iPhone Duo (port of RN `useScreenLayout`, momo-kits !664)
+## SwiftUI kit (`ios/`)
+
+- The pod's minimum is **iOS 15**, but the navigation shell (`NavigationContainer`, `Navigator`, `NavigatorManager`, `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`).
+- 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`.
+
+## Screen layout / iPhone Duo (port of RN `useScreenLayout`)
 
-- `layout/ScreenLayout.kt`: `getScreenLayout()` returns window size, raw top/bottom + side insets, `contentWidth`, header geometry, the iPhone Duo `sideBar` and `duoTopInset`. `NavigationContainer` computes it once and provides `LocalScreenLayout`; reactive to fold/unfold and rotation (window size + `WindowInsets`). Metrics (`DuoMetrics`, 72pt iPhone header floor, 20pt status-bar threshold) mirror RN `Layout/utils.ts` — change both together.
-- iPhone-only: everything gates on `isPhoneIdiom()` (`platform/`), never on "iOS", so iPad windows keep the regular layout. Two detectors, as in RN: `isIPhoneDuo` (window aspect < 1.6 or asymmetric side insets) drives layout; `isIPhoneDuoDevice` (short side of screen or window > 440, RN `device.ts`) drives popups, modal and bottom sheet.
+- `layout/ScreenLayout.kt`: `getScreenLayout()` returns window size, side safe-area insets, `contentWidth`, header geometry and the iPhone Duo `sideBar`. `NavigationContainer` computes it once and provides `LocalScreenLayout`; reactive to fold/unfold and rotation (window size + `WindowInsets`). Metrics (`DuoMetrics`, 72pt iPhone header floor, 20pt status-bar threshold) mirror RN `Layout/utils.ts` — change both together.
 - Header height is `headerHeight` (not `AppStatusBar + HEADER_HEIGHT`); the bar row is `headerBarHeight`. When the status bar is off the top edge (iPhone landscape, iPhone Duo) `headerStatusBarHeight` is 0 so the title stays centered.
-- iPhone Duo with a side strip ≥ 60pt: back + toolkit leave the bar for `HeaderSideBar` (`navigation/component/SideBar.kt`, 48pt glass controls); custom header-right stays in the bar. The column starts at 120pt when the inner display is landscape (height ≥ 600), else 170pt, or below the header when the status bar is on top; UIKit's `statusBarFrame` is useless on Duo. Unlike RN it is clamped 24pt above footer / tab bar / rail.
-- Tab bar on Duo is `bottomtab/DuoTabBar.kt`: a rail in the side strip (anchored 24pt from the bottom, QR below it) or, without a side bar, a floating bar spanning 6/8 grid columns. Both overlay the content; `duoFloatingTabBarInset` pads tab content, footer and FAB.
-- Glass header: on Duo with a side bar, Default/Extended headers without search and with a `ScrollState` let content scroll under the bar (`usesDuoGlassHeader`); the bar fades in a translucent surface + hairline over 16pt (Compose has no backdrop blur — RN's fallback look), the gradient scrolls away / collapses.
-- Overlays on Duo: popups cap at 440pt wide and the room between `duoTopInset` and the bottom inset (body scrolls, actions stay); modal centers inside that room; bottom sheet uses the window height, centers at width ≥ 600 and pads by side insets in landscape.
-- Font scale deliberately uses the short side (`min(w, h)`), unlike RN which reads the window width — landscape must not inflate every font.
+- iPhone Duo with a side strip ≥ 60pt: back + toolkit leave the bar for `HeaderSideBar` (`navigation/component/SideBar.kt`, 48pt glass controls); custom header-right stays in the bar. The column starts below the camera / status-bar cluster: 170pt portrait, 120pt in any landscape (folded too — RN still uses 170 there), below the header when the status bar is on top; UIKit's `statusBarFrame` is useless on Duo. Unlike RN it is clamped 24pt above footer / tab bar, so a long toolkit (shortcut + group) never covers the footer.
 - `StackScreen` pads content/footer/search/FAB by the side insets and provides an inset-consumed layout to its content; a bottom-tab root stays full width (tab bar + each tab's StackScreen handle insets). Grid columns use `contentWidth`.
 
 ## i18n / Localize (port of RN `Localize`)

package/ios/Application/ApplicationEnvironment.swift

@@ -41,6 +41,12 @@ public class KitConfig {
     public var trustBanner: TrustBannerData? = nil
     public var headerBar: String? = nil
     public var headerGradient: String? = nil
+
+    public init(trustBanner: TrustBannerData? = nil, headerBar: String? = nil, headerGradient: String? = nil) {
+        self.trustBanner = trustBanner
+        self.headerBar = headerBar
+        self.headerGradient = headerGradient
+    }
 }
 
 public class ApplicationEnvironment: ObservableObject {

package/ios/Application/Components.swift

@@ -248,9 +248,7 @@ public struct Header: View {
                         if let inputProps = inputSearchProps {
                             InputSearch(props: inputProps)
                         } else if case let .user(userData)? = headerTitle {
-                            if #available(iOS 16.0, *) {
-                                HeaderUserView(userData)
-                            }
+                            HeaderUserView(userData)
                         } else {
                             MomoText(headerTitle?.defaultTitle ?? title, typography: .headerDefaultBold, color: tintColor ?? Colors.black17, maxLines: 1)
                                 .opacity(titleOpacity)

package/ios/Application/HeaderRight.swift

@@ -7,31 +7,20 @@ public struct HeaderRightData {
     var tools: [ToolGroup]
     var toolCallback: ((String) -> Void)?
     var useSystemTools: Bool
-    var useCloseIcon: Bool
     
     public init(
         useShortcut: Bool = false,
         useMore: Bool = false,
         tools: [ToolGroup] = [],
         toolCallback: ((String) -> Void)? = nil,
-        useSystemTools: Bool = true,
-        useCloseIcon: Bool = false
+        useSystemTools: Bool = true
     ) {
         self.useShortcut = useShortcut
         self.useMore = useMore
         self.tools = tools
         self.toolCallback = toolCallback
         self.useSystemTools = useSystemTools
-        self.useCloseIcon = useCloseIcon
     }
-
-    /// Close-circle instead of home, as RN `headerRight.useCloseIcon`.
-    var closeIcon: String { useCloseIcon ? "16_navigation_close_circle" : "16_basic_home" }
-}
-
-/// The Help Center mini-app hides its own help-center button.
-func showsHelpCenter(_ context: MiniAppContext?) -> Bool {
-    context?.appId != "vn.momo.helpcenter"
 }
 
 public struct Tool {
@@ -112,8 +101,13 @@ struct ToolkitHeaderRight: View {
     var tintColor: Color?
     @State private var isFavorite: Bool = false
     @State private var isLoading: Bool = false
-    @EnvironmentObject private var environment: ApplicationEnvironment
-    
+    // Legacy hosts inject with `.environmentObject`, containers with the keyed value; outside
+    // both this used to trap, so read the object optionally and fall back to the keyed one.
+    @OptionalEnvironmentObject private var injectedEnvironment: ApplicationEnvironment?
+    @Environment(\.applicationEnvironment) private var keyedEnvironment
+
+    private var environment: ApplicationEnvironment { injectedEnvironment ?? keyedEnvironment }
+
     // MARK: - Actions
     private func onPressShortcut() {
         // onToolAction needs the app context (appId/code) so the host knows which app to (un)favorite;
@@ -249,19 +243,17 @@ struct ToolkitHeaderRight: View {
             }
             
             HStack(alignment: .center, spacing: 0) {
-                if showsHelpCenter(environment.applicationContext) {
-                    Icon(source: "help_center", size: 20, color: tintColor ?? Colors.black17)
-                        .padding(4)
-                        .onTapGesture {
-                            onPressHelpCenter()
-                        }
-
-                    Rectangle()
-                        .fill(tintColor ?? Colors.black20)
-                        .frame(width: 0.5, height: 12)
-                }
-
-                Icon(source: headerRight?.closeIcon ?? "16_basic_home", size: 20, color: tintColor ?? Colors.black17)
+                Icon(source: "help_center", size: 20, color: tintColor ?? Colors.black17)
+                    .padding(4)
+                    .onTapGesture {
+                        onPressHelpCenter()
+                    }
+                
+                Rectangle()
+                    .fill(tintColor ?? Colors.black20)
+                    .frame(width: 0.5, height: 12)
+                
+                Icon(source: "16_basic_home", size: 20, color: tintColor ?? Colors.black17)
                     .padding(4)
                     .onTapGesture {
                         onPressClose()

package/ios/Application/Navigation/BottomTab/BottomTab.swift

@@ -16,7 +16,6 @@ public struct BottomTab: View {
     private let floatingButton: BottomTabFloatingButton?
 
     @EnvironmentObject private var navigator: Navigator
-    @Environment(\.screenLayout) private var layout
     @State private var selectedIndex: Int = 0
 
     public init(items: [BottomTabItem], floatingButton: BottomTabFloatingButton? = nil) {
@@ -25,14 +24,7 @@ public struct BottomTab: View {
     }
 
     private var bottomInset: CGFloat { safeAreaBottomInset() }
-    // the Duo bars overlay the content or sit in the side strip, so only the home indicator is kept clear
-    private var reservedBottom: CGFloat {
-        layout.isIPhoneDuo ? layout.insets.bottom : BOTTOM_TAB_BAR_HEIGHT + bottomInset + Spacing.S
-    }
-
-    private var duoInsets: DuoTabBarInsets {
-        layout.duoTabBarInsets(itemCount: items.count, hasFloatingButton: floatingButton != nil)
-    }
+    private var reservedBottom: CGFloat { BOTTOM_TAB_BAR_HEIGHT + bottomInset + Spacing.S }
 
     public var body: some View {
         ZStack(alignment: .bottom) {
@@ -46,29 +38,20 @@ public struct BottomTab: View {
                 }
             }
             .padding(.bottom, reservedBottom)
-            .environment(\.duoTabBarInsets, duoInsets)
             .animation(.easeInOut(duration: 0.2), value: selectedIndex)
 
-            if layout.isIPhoneDuo {
-                DuoTabBar(
+            // Tab bar + home-indicator filler.
+            VStack(spacing: 0) {
+                BottomTabBar(
                     items: items,
                     floatingButton: floatingButton,
                     selectedIndex: selectedIndex,
-                    onTabSelected: selectTab
+                    onTabSelected: { index in
+                        if index != selectedIndex { selectedIndex = index }
+                    }
                 )
-            } else {
-                // Tab bar + home-indicator filler.
-                VStack(spacing: 0) {
-                    BottomTabBar(
-                        items: items,
-                        floatingButton: floatingButton,
-                        selectedIndex: selectedIndex,
-                        onTabSelected: selectTab
-                    )
-                    Colors.black01
-                        .frame(height: bottomInset + Spacing.S)
-                        .ignoresSafeArea(edges: .horizontal)
-                }
+                Colors.black01
+                    .frame(height: bottomInset + Spacing.S)
             }
         }
         .frame(maxWidth: .infinity, maxHeight: .infinity)
@@ -76,10 +59,6 @@ public struct BottomTab: View {
         .preference(key: IsBottomTabRootKey.self, value: true)
     }
 
-    private func selectTab(_ index: Int) {
-        if index != selectedIndex { selectedIndex = index }
-    }
-
     @ViewBuilder
     private func tabScreen(for index: Int) -> some View {
         let item = items[index]

package/ios/Application/Navigation/BottomTab/BottomTabBar.swift

@@ -65,10 +65,7 @@ struct BottomTabBar: View {
     let selectedIndex: Int
     let onTabSelected: (Int) -> Void
 
-    @Environment(\.screenLayout) private var layout
-
-    // the bar sits between the side safe areas
-    private var screenWidth: CGFloat { layout.width - layout.insets.leading - layout.insets.trailing }
+    private var screenWidth: CGFloat { UIScreen.main.bounds.width }
     private var mid: Int { items.count / 2 }
 
     private var tabWidth: CGFloat {
@@ -98,7 +95,7 @@ struct BottomTabBar: View {
             }
             .frame(maxWidth: .infinity)
             .frame(height: BOTTOM_TAB_BAR_HEIGHT)
-            .background(Colors.black01.ignoresSafeArea(edges: .horizontal))
+            .background(Colors.black01)
 
             // Animated selection indicator.
             RoundedRectangle(cornerRadius: 2)

package/ios/Application/Navigation/HeaderUser.swift

@@ -10,7 +10,6 @@
 
 import SwiftUI
 
-@available(iOS 16.0, *)
 public struct HeaderUserView: View {
     private let data: HeaderUserData
 
@@ -20,11 +19,8 @@ public struct HeaderUserView: View {
 
     private let avatarSize: CGFloat = Spacing.XXL // 32
 
-    @Environment(\.screenLayout) private var layout
-
-    // back button and toolkit share the bar unless the iPhone Duo side bar holds them
     private var maxWidth: CGFloat {
-        layout.sideBar != nil ? layout.contentWidth - Spacing.M * 2 : layout.width - 172
+        UIScreen.main.bounds.width - 172
     }
 
     public var body: some View {
@@ -108,7 +104,6 @@ public struct HeaderUserView: View {
 
 /// Mirrors Compose's `AvatarGroup`: lays out 1..4 avatars in a fixed collage,
 /// falls back to initials when empty, and shows a "+n" overflow tile beyond 4.
-@available(iOS 16.0, *)
 private struct AvatarGroup: View {
     let urls: [String]
     let title: String
@@ -190,7 +185,6 @@ private struct AvatarGroup: View {
     }
 }
 
-@available(iOS 16.0, *)
 private struct InitialsAvatar: View {
     let name: String
     let size: CGFloat

package/ios/Application/Navigation/NavigationContainer.swift

@@ -3,9 +3,8 @@
 //  MoMoUIKits
 //
 //  SwiftUI mirror of Compose's NavigationContainer.
-//  Wraps NavigationStack, injects Navigator into the environment, and renders
-//  every registered screen inside `Screen(options)` chrome — same auto-wrap
-//  behavior as Compose's StackScreen.
+//  Wraps NavigationStack (iOS 16+), injects Navigator into the environment, and renders
+//  every registered screen inside `StackScreen` chrome built from its options.
 //
 
 import SwiftUI
@@ -55,41 +54,23 @@ public struct NavigationContainer<Initial: View>: View {
     }
 
     public var body: some View {
-        NavigationStack(path: $navigator.path) {
-            screenView(for: navigator.rootRoute)
-                .navigationDestination(for: DynamicScreenRoute.self) { route in
-                    screenView(for: route)
-                }
-        }
-        .environmentObject(navigator)
-        .environmentObject(applicationEnvironment)
-        .environment(\.applicationEnvironment, applicationEnvironment)
-        // AI-GENERATED START: route Localize + font-scale injection through the observing modifiers
-        .momoLocalize(localize)
-        .momoFontScale(context: applicationEnvironment.applicationContext)
-        // AI-GENERATED END: route Localize + font-scale injection through the observing modifiers
-        .fullScreenCover(item: $navigator.presented) { route in
-            screenView(forDialog: route)
-                .environmentObject(navigator)
-                .environmentObject(applicationEnvironment)
-                .environment(\.applicationEnvironment, applicationEnvironment)
-                // AI-GENERATED START: route Localize + font-scale injection through the observing modifiers
-                .momoLocalize(localize)
-                .momoFontScale(context: applicationEnvironment.applicationContext)
-                // AI-GENERATED END: route Localize + font-scale injection through the observing modifiers
-        }
-        .overlay {
-            if let item = navigator.overplay {
-                OverplayHost(item: item)
-                    .environmentObject(navigator)
-                    .environmentObject(applicationEnvironment)
-                    .environment(\.applicationEnvironment, applicationEnvironment)
-                    // AI-GENERATED START: route Localize + font-scale injection through the observing modifiers
-                    .momoLocalize(localize)
-                    .momoFontScale(context: applicationEnvironment.applicationContext)
-                    // AI-GENERATED END: route Localize + font-scale injection through the observing modifiers
-                    .momoScreenLayout()
-            }
+        withKitEnvironment(
+            stack(path: $navigator.path, root: navigator.rootRoute)
+                .overlay { overplayLayer(presentedId: nil) }
+        )
+        .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() }
         }
         .onAppear {
             if navigator.composeApi == nil {
@@ -110,10 +91,23 @@ 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 }
             NavigatorManager.shared.remove(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) {
@@ -124,14 +118,22 @@ public struct NavigationContainer<Initial: View>: View {
         }
     }
 
+    /// Each context draws only the overplays shown over it, so one never re-mounts elsewhere.
     @ViewBuilder
-    private func screenView(forDialog route: DynamicDialogRoute) -> some View {
-        if let screen = navigator.registry.getScreen(id: route.id) {
-            ScreenHost(screen: screen, navigator: navigator)
-        } else {
-            EmptyView()
+    private func overplayLayer(presentedId: Int?) -> some View {
+        if let item = navigator.overplay, item.presentedId == presentedId {
+            OverplayHost(item: item)
         }
     }
+
+    private func withKitEnvironment<Content: View>(_ content: Content) -> some View {
+        content
+            .environmentObject(navigator)
+            .environmentObject(applicationEnvironment)
+            .environment(\.applicationEnvironment, applicationEnvironment)
+            .momoLocalize(localize)
+            .momoFontScale(context: applicationEnvironment.applicationContext)
+    }
 }
 
 // MARK: - ScreenHost
@@ -168,8 +170,6 @@ private struct ScreenHost: View {
             screenName: screen.name,
             content: { screen.content() }
         )
-        // Per screen, not around the NavigationStack: a state-driven reader there stops path pushes rendering.
-        .momoScreenLayout()
     }
 }