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

package/ios/{Application/Navigation → Navigation/Component}/HeaderUser.swift

@@ -2,7 +2,7 @@
 //  HeaderUser.swift
 //  MoMoUIKits
 //
-//  SwiftUI mirror of Compose's `HeaderUser` (navigation/component/HeaderUser.kt).
+//  SwiftUI mirror of Compose's `navigation/component/HeaderUser.kt`.
 //  Renders a `HeaderTitle.User`: an avatar group (1..n avatars with overflow),
 //  a title with optional inline icons, and an optional subtitle. Shows a
 //  skeleton shimmer placeholder while `isLoading`.
@@ -10,7 +10,6 @@
 
 import SwiftUI
 
-@available(iOS 16.0, *)
 public struct HeaderUserView: View {
     private let data: HeaderUserData
 
@@ -20,9 +19,7 @@ public struct HeaderUserView: View {
 
     private let avatarSize: CGFloat = Spacing.XXL // 32
 
-    private var maxWidth: CGFloat {
-        UIScreen.main.bounds.width - 172
-    }
+    @Environment(\.screenLayout) private var layout
 
     public var body: some View {
         if data.isLoading {
@@ -33,6 +30,14 @@ public struct HeaderUserView: View {
     }
 
     private var content: some View {
+        SwiftUI.Button(action: { data.onPress?() }) {
+            row
+        }
+        .buttonStyle(ActiveOpacityButtonStyle())
+        .disabled(data.onPress == nil)
+    }
+
+    private var row: some View {
         HStack(spacing: 0) {
             HStack(spacing: 0) {
                 ZStack(alignment: .bottomTrailing) {
@@ -49,8 +54,7 @@ public struct HeaderUserView: View {
 
                 VStack(alignment: .leading, spacing: 0) {
                     HStack(spacing: 0) {
-                        MomoText(data.title, typography: .actionXsBold, color: data.tintColor ?? Colors.black17, maxLines: 1)
-                            .truncationMode(.tail)
+                        MomoText(data.title, typography: .actionXsBold, color: data.tintColor, maxLines: 1, fontFamily: headerFontFamily)
 
                         if !data.icons.isEmpty {
                             Spacer().frame(width: 6)
@@ -66,34 +70,27 @@ public struct HeaderUserView: View {
 
                     if let subTitle = data.subTitle, !subTitle.isEmpty {
                         Spacer().frame(height: 2)
-                        MomoText(subTitle, typography: .descriptionXsRegular, color: data.tintColor ?? Colors.black17, maxLines: 1)
-                            .truncationMode(.tail)
+                        MomoText(subTitle, typography: .descriptionXsRegular, color: data.tintColor, maxLines: 1)
                     }
                 }
             }
-            .frame(maxWidth: maxWidth, alignment: .leading)
+            .frame(maxWidth: headerTitleMaxWidth(layout), alignment: .leading)
 
             Spacer(minLength: 0)
         }
         .frame(maxWidth: .infinity, alignment: .leading)
         .padding(.vertical, Spacing.XS)
         .contentShape(Rectangle())
-        .onTapGesture { data.onPress?() }
-        .allowsHitTesting(data.onPress != nil)
     }
 
     private var shimmer: some View {
         HStack(spacing: Spacing.M / 2) {
-            Circle()
-                .fill(Colors.black05)
+            Skeleton()
                 .frame(width: avatarSize, height: avatarSize)
+                .clipShape(Circle())
             VStack(alignment: .leading, spacing: Spacing.XXS) {
-                RoundedRectangle(cornerRadius: 8)
-                    .fill(Colors.black05)
-                    .frame(width: 120, height: 18)
-                RoundedRectangle(cornerRadius: 8)
-                    .fill(Colors.black05)
-                    .frame(width: 120, height: 12)
+                titleSkeleton(height: 18)
+                titleSkeleton(height: 12)
             }
         }
         .frame(maxWidth: .infinity, alignment: .leading)
@@ -105,8 +102,8 @@ 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 {
+    @Environment(\.appTheme) private var theme
     let urls: [String]
     let title: String
     let size: CGFloat
@@ -176,7 +173,7 @@ private struct AvatarGroup: View {
         ImageView(url)
             .aspectRatio(contentMode: .fill)
             .clipShape(Circle())
-            .overlay(Circle().stroke(Colors.black05, lineWidth: 0.5))
+            .overlay(Circle().stroke(theme.colors.border.default, lineWidth: 0.5))
     }
 
     private func overflowTile(more: Int) -> some View {
@@ -187,8 +184,8 @@ private struct AvatarGroup: View {
     }
 }
 
-@available(iOS 16.0, *)
 private struct InitialsAvatar: View {
+    @Environment(\.appTheme) private var theme
     let name: String
     let size: CGFloat
 
@@ -204,6 +201,6 @@ private struct InitialsAvatar: View {
             .frame(width: size, height: size)
             .background(Colors.pink09)
             .clipShape(Circle())
-            .overlay(Circle().stroke(Colors.black05, lineWidth: 0.5))
+            .overlay(Circle().stroke(theme.colors.border.default, lineWidth: 0.5))
     }
 }

package/ios/Navigation/Component/SideBar.swift

@@ -0,0 +1,183 @@
+//
+//  SideBar.swift
+//  MoMoUIKits
+//
+//  SwiftUI mirror of Compose's `navigation/component/SideBar.kt`. iPhone Duo: back and toolkit
+//  leave the header bar for a column in the side safe area, as the system bars do.
+//  Port of RN `SideBarButton.tsx` + `useSideBarItemStyle`.
+//
+
+import SwiftUI
+
+private let sideBarIconSize: CGFloat = 24
+
+/// The back button and toolkit column, placed in window coordinates over the side strip.
+struct HeaderSideBar: View {
+    let sideBar: SideBarLayout
+    let goBack: (() -> Void)?
+    let toolkit: (data: HeaderRightData?, tintColor: Color?)?
+    let headerColor: HeaderColor
+    /// What footer / tab bar / home indicator take from the bottom, gap included; the column stays above it.
+    let bottomInset: CGFloat
+
+    @Environment(\.screenLayout) private var layout
+    @Environment(\.applicationEnvironment) private var environment
+    @Environment(\.duoBarCompression) private var compression
+    @State private var columnHeight: CGFloat = 0
+
+    private var isRight: Bool { sideBar.edge == .right }
+
+    private var top: CGFloat {
+        let maxY = layout.height - bottomInset - columnHeight
+        return max(min(sideBar.top, maxY), 0)
+    }
+
+    /// Full height, so the tab bar compression decision follows this screen's toolkit.
+    private var fullHeight: CGFloat {
+        let toolkitHeight = toolkit.map {
+            Spacing.M + toolkitColumnHeight($0.data ?? HeaderRightData(), context: environment.applicationContext)
+        }
+        return DuoMetrics.controlSize + (toolkitHeight ?? 0)
+    }
+
+    var body: some View {
+        VStack(alignment: isRight ? .leading : .trailing, spacing: Spacing.M) {
+            if let goBack {
+                SideBarButton(
+                    icon: "arrow-back",
+                    headerColor: headerColor,
+                    accessibilityId: "btn_navigation_back",
+                    action: goBack
+                )
+            } else {
+                // keep the slot so the toolkit does not jump between root and pushed screens
+                Color.clear.frame(width: DuoMetrics.controlSize, height: DuoMetrics.controlSize)
+            }
+            if let toolkit {
+                if compression.toolbarHidden {
+                    // an open tab rail takes this slot for a moment
+                    EmptyView()
+                } else if compression.toolbarCompressed {
+                    // HIG "Toolbar compressed": tools fold into one button, distinct from the useMore icon
+                    SideBarButton(
+                        icon: "navigation_menu",
+                        headerColor: headerColor,
+                        showBadge: toolkit.data?.showBadge ?? false,
+                        accessibilityId: "btn_navigation_toolbar",
+                        action: compression.expandToolbar
+                    )
+                } else {
+                    Toolkit(
+                        headerRight: toolkit.data ?? HeaderRightData(),
+                        tintColor: toolkit.tintColor,
+                        layout: .sideBarColumn
+                    )
+                    .environment(\.headerColor, headerColor)
+                }
+            }
+        }
+        .padding(isRight ? .leading : .trailing, Spacing.M)
+        .frame(width: sideBar.width, alignment: isRight ? .leading : .trailing)
+        .background(
+            GeometryReader { proxy in
+                Color.clear
+                    .onAppear { columnHeight = proxy.size.height }
+                    .onChange(of: proxy.size.height) { columnHeight = $0 }
+            }
+        )
+        .padding(.top, top)
+        .frame(maxWidth: .infinity, maxHeight: .infinity, alignment: isRight ? .topTrailing : .topLeading)
+        .ignoresSafeArea()
+        .onAppear { compression.setToolbarHeight(fullHeight) }
+        .onChange(of: fullHeight) { compression.setToolbarHeight($0) }
+    }
+}
+
+/// Dark glass under light icons (banner headers), light glass otherwise.
+private struct SideBarGlass<S: Shape>: ViewModifier {
+    let headerColor: HeaderColor
+    let shape: S
+
+    private var isDark: Bool { headerColor.tintIconColor == Colors.black01 || headerColor.tintIconColor == .white }
+
+    func body(content: Content) -> some View {
+        if isDark {
+            content
+                .background(shape.fill(Colors.black20.opacity(0.5)))
+                .overlay(shape.stroke(Colors.black01.opacity(0.2), lineWidth: 0.5))
+        } else {
+            content
+                .background(
+                    shape.fill(Colors.black01.opacity(0.85))
+                        .shadow(color: Color.black.opacity(0.12), radius: 4, x: 0, y: 2)
+                )
+                .overlay(shape.stroke(Colors.black20.opacity(0.08), lineWidth: 0.5))
+        }
+    }
+}
+
+/// 48pt glass circle for a single side bar control.
+struct SideBarButton: View {
+    let icon: String
+    let headerColor: HeaderColor
+    var showBadge: Bool = false
+    var disabled: Bool = false
+    var accessibilityId: String?
+    let action: () -> Void
+
+    var body: some View {
+        SwiftUI.Button(action: action) {
+            Icon(source: icon, size: sideBarIconSize, color: headerColor.tintIconColor)
+                .frame(width: DuoMetrics.controlSize, height: DuoMetrics.controlSize)
+                .modifier(SideBarGlass(headerColor: headerColor, shape: Circle()))
+                .overlay(alignment: .topTrailing) {
+                    if showBadge {
+                        BadgeDot(size: .small).offset(x: -Spacing.XXS, y: Spacing.XXS)
+                    }
+                }
+        }
+        .buttonStyle(ActiveOpacityButtonStyle())
+        .disabled(disabled)
+        .accessibilityIdentifier(accessibilityId ?? "")
+    }
+}
+
+/// 48pt glass capsule grouping related controls, one item per 50pt: vertical in the side bar,
+/// horizontal on a header row.
+struct SideBarGroup<Content: View>: View {
+    let headerColor: HeaderColor
+    let itemCount: Int
+    var horizontal: Bool = false
+    @ViewBuilder let content: () -> Content
+
+    var body: some View {
+        let length = itemCount > 1 ? DuoMetrics.itemPitch * CGFloat(itemCount) : DuoMetrics.controlSize
+        Group {
+            if horizontal {
+                HStack(spacing: 0) { content() }
+                    .frame(width: length, height: DuoMetrics.controlSize)
+            } else {
+                VStack(spacing: 0) { content() }
+                    .frame(width: DuoMetrics.controlSize, height: length)
+            }
+        }
+        .modifier(SideBarGlass(headerColor: headerColor, shape: RoundedRectangle(cornerRadius: Radius.XL)))
+    }
+}
+
+struct SideBarGroupItem: View {
+    let icon: String
+    let headerColor: HeaderColor
+    let accessibilityId: String
+    let action: () -> Void
+
+    var body: some View {
+        SwiftUI.Button(action: action) {
+            Icon(source: icon, size: sideBarIconSize, color: headerColor.tintIconColor)
+                .frame(maxWidth: .infinity, maxHeight: .infinity)
+                .contentShape(Rectangle())
+        }
+        .buttonStyle(ActiveOpacityButtonStyle())
+        .accessibilityIdentifier(accessibilityId)
+    }
+}

package/ios/{Application/Navigation/Overplay → Navigation/Component}/SnackBar.swift

@@ -2,9 +2,8 @@
 //  SnackBar.swift
 //  MoMoUIKits
 //
-//  SwiftUI mirror of Compose's `SnackBar` (navigation/component/SnackBar.kt).
-//  A snack bar slides up from the bottom (just above the footer / home
-//  indicator), stays for `duration`, then slides back down and is removed.
+//  SwiftUI mirror of Compose's `navigation/component/SnackBar.kt`: slides up above the screen's
+//  footer (or the home indicator), stays for `duration`, then slides back down.
 //  `Navigator.showSnackBar(_:)` drives it through the overplay host.
 //
 
@@ -50,11 +49,11 @@ 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 overplayId: UUID
     let snackBar: SnackBar
-    /// Bottom inset so the bar sits above the footer / home indicator
-    /// (mirrors Compose's `footerHeight` offset).
+    /// Distance from the window bottom to the top of the screen's footer, or the navigation bar
+    /// inset without one (Compose's `footerHeight` offset).
     let bottomInset: CGFloat
 
     @EnvironmentObject private var navigator: Navigator
@@ -78,6 +77,7 @@ struct SnackBarView: View {
                 .padding(.bottom, bottomInset)
         }
         .frame(maxWidth: .infinity, maxHeight: .infinity)
+        .ignoresSafeArea()
         .onAppear {
             guard !didAppear else { return }
             didAppear = true
@@ -122,7 +122,7 @@ struct SnackBarView: View {
             offsetY = max(contentHeight, 200) + bottomInset
         }
         DispatchQueue.main.asyncAfter(deadline: .now() + 0.2) {
-            navigator.finishOverplayDismiss()
+            navigator.finishOverplayDismiss(id: overplayId)
         }
     }
 
@@ -134,7 +134,7 @@ struct SnackBarView: View {
         guard let duration = snackBar.duration else { return }
         let workItem = DispatchWorkItem {
             // Only auto-dismiss if this snack bar is still the active overplay.
-            if navigator.overplay?.type == .snackBar {
+            if navigator.overplay?.id == overplayId {
                 navigator.hideSnackBar()
             }
         }

package/ios/Navigation/HostBackGestureBridge.swift

@@ -0,0 +1,78 @@
+//
+//  HostBackGestureBridge.swift
+//  MoMoUIKits
+//
+//  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.
+//  `started` / `progressed` / `completed` / `cancelled` scrub the pop transition with the finger;
+//  a host that only calls `pop` gets the regular animated back.
+//
+
+import UIKit
+
+public final class HostBackGestureBridge {
+    public static let shared = HostBackGestureBridge()
+    private init() {}
+
+    // 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
+
+    public func attach(_ navigator: Navigator) {
+        navigators.removeAll { $0.value == nil }
+        guard !navigators.contains(where: { $0.value === navigator }) else { return }
+        navigators.append(WeakNavigator(value: navigator))
+    }
+
+    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.
+    public func checkCanPop() -> Bool { top() != nil }
+
+    /// Whether the top stack pops a screen itself; false means a back dismisses the mini app.
+    public func canPopInner() -> Bool { top()?.canPop() == true }
+
+    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) }
+
+    @available(*, deprecated, renamed: "detach")
+    public func remove(_ navigator: Navigator) { detach(navigator) }
+
+    private func top() -> Navigator? { navigators.last { $0.value != nil }?.value }
+}
+
+@available(*, deprecated, renamed: "HostBackGestureBridge")
+public typealias NavigatorManager = HostBackGestureBridge
+
+private struct WeakNavigator {
+    weak var value: Navigator?
+}

package/ios/{Application/Navigation/Overplay → Navigation}/ModalScreen.swift

@@ -9,13 +9,14 @@
 
 import SwiftUI
 
-@available(iOS 16.0, *)
 struct ModalScreen<Content: View>: View {
+    let overplayId: UUID
     let barrierDismissible: Bool
     let content: () -> Content
 
     @EnvironmentObject private var navigator: Navigator
     @Environment(\.applicationEnvironment) private var appEnv
+    @Environment(\.screenLayout) private var layout
 
     @State private var scrimOpacity: CGFloat = 0
     @State private var contentScale: CGFloat = 0.8
@@ -35,7 +36,13 @@ struct ModalScreen<Content: View>: View {
             content()
                 .scaleEffect(contentScale)
                 .opacity(contentOpacity)
+                // iPhone Duo: center below the side status bar and above the home indicator
+                .padding(.top, layout.isDuoDevice ? layout.duoTopInset : 0)
+                .padding(.bottom, layout.isDuoDevice ? layout.insets.bottom : 0)
         }
+        // Full screen like RN's Modal, so asymmetric landscape insets don't shift the content sideways.
+        .frame(maxWidth: .infinity, maxHeight: .infinity)
+        .ignoresSafeArea(.container)
         .onAppear {
             guard !didAppear else { return }
             didAppear = true
@@ -68,7 +75,7 @@ struct ModalScreen<Content: View>: View {
             contentOpacity = 0
         }
         DispatchQueue.main.asyncAfter(deadline: .now() + 0.2) {
-            navigator.finishOverplayDismiss()
+            navigator.finishOverplayDismiss(id: overplayId)
         }
     }
 }

package/ios/Navigation/Navigation.swift

@@ -0,0 +1,204 @@
+//
+//  Navigation.swift
+//  MoMoUIKits
+//
+//  SwiftUI mirror of Compose's `navigation/Navigation.kt`: a screen's `NavigationOptions` and the
+//  per-screen `Navigation` that updates them at runtime.
+//
+
+import SwiftUI
+
+/// Per-screen handle (Compose `LocalNavigation`). Read it inside a screen with
+/// `@EnvironmentObject var navigation: Navigation` and call `setOptions` to change the header,
+/// footer or back handling after the screen is shown.
+public final class Navigation: ObservableObject {
+    public let id: Int
+    public let bottomTabIndex: Int
+    @Published public private(set) var options: NavigationOptions
+
+    private weak var registry: DynamicScreenRegistry?
+    /// What the footer (or navigation bar) takes from the window bottom; lifts snack bars.
+    var bottomObstruction: CGFloat = 0
+
+    init(
+        id: Int = -1,
+        bottomTabIndex: Int = -1,
+        options: NavigationOptions?,
+        registry: DynamicScreenRegistry? = nil
+    ) {
+        self.id = id
+        self.bottomTabIndex = bottomTabIndex
+        self.options = options ?? NavigationOptions()
+        self.registry = registry
+        if id != -1 { registry?.bind(self) }
+    }
+
+    public func setOptions(_ options: NavigationOptions) {
+        update(options)
+    }
+
+    /// Changes only what the closure touches, like Compose's named-argument `setOptions`.
+    public func setOptions(_ transform: (inout NavigationOptions) -> Void) {
+        var updated = options
+        transform(&updated)
+        update(updated)
+    }
+
+    private func update(_ updated: NavigationOptions) {
+        options = updated
+        // back handling reads the registry copy
+        if id != -1 { registry?.setOptions(id: id, options: updated) }
+    }
+}
+
+public struct NavigationOptions {
+    public var screenName: String?
+    public var title: String
+    /// Rich header title (Compose `headerTitle`); `title` is used when nil.
+    public var headerTitle: HeaderTitle?
+    public var titlePosition: TitlePosition
+    public var headerType: HeaderType
+    /// Compose's `HeaderType.Default/Extended(useAnimated:)`: with `inputSearchProps`, the search
+    /// rises into the header on scroll.
+    public var useAnimated: Bool
+    /// Compose's `HeaderType.Transparent`; with `fullScreenContent` the content starts under it.
+    public var headerTransparent: Bool
+    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.
+    public var scrollToTopCallback: (() -> Void)?
+    public var useAvoidKeyboard: Bool
+    /// Compose's `KeyboardOptions.keyboardShouldPersistTaps`: a tap anywhere hides the keyboard.
+    public var keyboardShouldPersistTaps: Bool
+    public var headerBackProps: HeaderBackProps?
+    /// Toolkit data for the default header right (Compose `HeaderRight.Toolkit`). Use `headerRight`
+    /// for a custom view and nil for none.
+    public var headerRightData: HeaderRightData?
+    public var headerRight: (() -> any View)?
+    public var footer: (() -> AnyView)?
+    public var footerTransparent: Bool
+    public var footerUseMargin: Bool
+    public var animatedHeader: AnimatedHeader?
+    public var layoutOffset: CGFloat
+    public var inputSearchProps: InputSearchProps?
+    public var fabProps: FabProps?
+    public var onBackHandler: (() -> Void)?
+
+    public init(
+        screenName: String? = nil,
+        title: String = "Stack",
+        headerTitle: HeaderTitle? = nil,
+        titlePosition: TitlePosition = .left,
+        headerType: HeaderType = .default,
+        useAnimated: Bool = false,
+        headerTransparent: Bool = false,
+        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,
+        useAvoidKeyboard: Bool = true,
+        keyboardShouldPersistTaps: Bool = false,
+        headerBackProps: HeaderBackProps? = nil,
+        headerRightData: HeaderRightData? = nil,
+        headerRight: (() -> any View)? = { HeaderRight() },
+        footer: (() -> AnyView)? = nil,
+        footerTransparent: Bool = false,
+        footerUseMargin: Bool = true,
+        animatedHeader: AnimatedHeader? = nil,
+        layoutOffset: CGFloat = 56,
+        inputSearchProps: InputSearchProps? = nil,
+        fabProps: FabProps? = nil,
+        onBackHandler: (() -> Void)? = nil
+    ) {
+        self.screenName = screenName
+        self.title = title
+        self.headerTitle = headerTitle
+        self.titlePosition = titlePosition
+        self.headerType = headerType
+        self.useAnimated = useAnimated
+        self.headerTransparent = headerTransparent
+        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
+        self.useAvoidKeyboard = useAvoidKeyboard
+        self.keyboardShouldPersistTaps = keyboardShouldPersistTaps
+        self.headerBackProps = headerBackProps
+        self.headerRightData = headerRightData
+        self.headerRight = headerRight
+        self.footer = footer
+        self.footerTransparent = footerTransparent
+        self.footerUseMargin = footerUseMargin
+        self.animatedHeader = animatedHeader
+        self.layoutOffset = layoutOffset
+        self.inputSearchProps = inputSearchProps
+        self.fabProps = fabProps
+        self.onBackHandler = onBackHandler
+    }
+}
+
+extension NavigationOptions {
+    var resolvedHeaderRight: (() -> any View)? {
+        guard let headerRightData else { return headerRight }
+        return { HeaderRight(headerRight: headerRightData, tintColor: tintColor) }
+    }
+}
+
+/// `StackScreen` built from options, shared by stack screens and bottom-tab screens.
+struct OptionsStackScreen: View {
+    let options: NavigationOptions
+    let screenName: String
+    let goBack: (() -> Void)?
+    let content: () -> AnyView
+
+    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,
+            isBack: !options.hiddenBack,
+            headerType: options.headerType,
+            useAnimated: options.useAnimated,
+            title: options.title,
+            headerTitle: options.headerTitle,
+            titlePosition: options.titlePosition,
+            goBack: options.hiddenBack ? nil : goBack,
+            scrollable: options.scrollable,
+            scrollToTopCallback: options.scrollToTopCallback,
+            useAvoidKeyboard: options.useAvoidKeyboard,
+            keyboardShouldPersistTaps: options.keyboardShouldPersistTaps,
+            footer: options.footer,
+            footerTransparent: options.footerTransparent,
+            footerUseMargin: options.footerUseMargin,
+            headerRight: options.resolvedHeaderRight,
+            animatedHeader: options.animatedHeader,
+            layoutOffset: options.layoutOffset,
+            inputSearchProps: options.inputSearchProps,
+            fabProps: options.fabProps,
+            screenName: screenName,
+            content: content
+        )
+    }
+}