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

package/ios/{Application/Navigation → Navigation}/BottomTab/BottomTabBar.swift

@@ -2,7 +2,7 @@
 //  BottomTabBar.swift
 //  MoMoUIKits
 //
-//  SwiftUI mirror of Compose's `BottomTabBar` (navigation/bottomtab/BottomTabBar.kt).
+//  SwiftUI mirror of Compose's `navigation/bottomtab/BottomTabBar.kt`.
 //  Renders the row of tab items, an animated selection indicator, a top shadow,
 //  badges/dots, and an optional center floating button (with the curved notch).
 //
@@ -20,6 +20,7 @@ public struct BottomTabItem: Identifiable {
     public let showDot: Bool
     public let badgeLabel: String?
     public let options: NavigationOptions?
+    public let initialParams: Any?
     public let screen: () -> AnyView
 
     public init(
@@ -29,6 +30,7 @@ public struct BottomTabItem: Identifiable {
         showDot: Bool = false,
         badgeLabel: String? = nil,
         options: NavigationOptions? = nil,
+        initialParams: Any? = nil,
         @ViewBuilder screen: @escaping () -> some View
     ) {
         self.name = name
@@ -37,6 +39,7 @@ public struct BottomTabItem: Identifiable {
         self.showDot = showDot
         self.badgeLabel = badgeLabel
         self.options = options
+        self.initialParams = initialParams
         self.screen = { AnyView(screen()) }
     }
 }
@@ -65,7 +68,11 @@ struct BottomTabBar: View {
     let selectedIndex: Int
     let onTabSelected: (Int) -> Void
 
-    private var screenWidth: CGFloat { UIScreen.main.bounds.width }
+    @Environment(\.screenLayout) private var layout
+    @Environment(\.appTheme) private var theme
+
+    // the bar sits between the side safe areas
+    private var screenWidth: CGFloat { layout.width - layout.insets.leading - layout.insets.trailing }
     private var mid: Int { items.count / 2 }
 
     private var tabWidth: CGFloat {
@@ -95,11 +102,11 @@ struct BottomTabBar: View {
             }
             .frame(maxWidth: .infinity)
             .frame(height: BOTTOM_TAB_BAR_HEIGHT)
-            .background(Colors.black01)
+            .background(theme.colors.background.surface.ignoresSafeArea(edges: .horizontal))
 
             // Animated selection indicator.
             RoundedRectangle(cornerRadius: 2)
-                .fill(Colors.primary)
+                .fill(theme.colors.primary)
                 .frame(width: 44, height: 2)
                 .offset(x: indicatorOffset, y: -BOTTOM_TAB_BAR_HEIGHT + 2)
                 .animation(.easeInOut(duration: 0.25), value: selectedIndex)
@@ -140,7 +147,9 @@ private struct TabBarItem: View {
     let selected: Bool
     let onClick: () -> Void
 
-    private var tintColor: Color { selected ? Colors.primary : Colors.black10 }
+    @Environment(\.appTheme) private var theme
+
+    private var tintColor: Color { selected ? theme.colors.primary : theme.colors.text.hint }
 
     /// Mirrors Compose's `formatLabel`: hide a badge that is the number "0".
     private var badgeLabel: String? {
@@ -192,18 +201,20 @@ private struct TabBarItem: View {
 private struct CenterFloatingButton: View {
     let data: BottomTabFloatingButton
 
+    @Environment(\.appTheme) private var theme
+
     var body: some View {
         VStack(spacing: 0) {
             CurvedContainer()
             Circle()
-                .fill(Colors.primary)
+                .fill(theme.colors.primary)
                 .frame(width: 48, height: 48)
                 .overlay(Icon(source: data.icon, size: 28, color: .white))
             Spacer().frame(height: 4)
             MomoText(data.label, typography: .labelXsMedium, color: Colors.black01, textAlign: .center, maxLines: 1)
                 .frame(maxWidth: .infinity)
                 .frame(height: 14)
-                .background(Colors.primary)
+                .background(theme.colors.primary)
                 .clipShape(RoundedRectangle(cornerRadius: Radius.XL))
         }
         .frame(width: bottomTabFloatingButtonWidth)

package/ios/Navigation/BottomTab/DuoBarCompression.swift

@@ -0,0 +1,104 @@
+//
+//  DuoBarCompression.swift
+//  MoMoUIKits
+//
+//  Port of RN `BottomTab/DuoBarCompression.tsx` (HIG, Designing for iPhone Duo: Vertical controls):
+//  keeps the side bar's toolbar and tab bar clear of each other.
+//
+
+import SwiftUI
+
+/// iPhone Duo: which side bar bar starts compressed when the strip cannot hold both whole.
+public enum DuoBarCompressionBehavior {
+    case toolbar, tabBar
+}
+
+enum DuoBar {
+    case toolbar, tabBar
+}
+
+struct DuoBarCompression {
+    var toolbarCompressed = false
+    var tabBarCompressed = false
+    /// The open rail needs the toolbar button slot too: only Back stays.
+    var toolbarHidden = false
+    var expandToolbar: () -> Void = {}
+    var expandTabBar: () -> Void = {}
+    /// A rail opened from the compressed state closes once a tab is picked.
+    var onTabSelected: () -> Void = {}
+    /// Side bar toolkits report their full height so the tab bar knows what is left.
+    var setToolbarHeight: (CGFloat) -> Void = { _ in }
+
+    /// Space kept between the top and the bottom groups (HIG Vertical controls).
+    static let groupGap = Spacing.M
+    /// Back, then the right toolkit: help + home capsule.
+    static let defaultToolbarHeight = DuoMetrics.controlSize + Spacing.M + 2 * DuoMetrics.itemPitch
+    /// Back, then the single button the toolbar folds into.
+    private static let compressedToolbarHeight = 2 * DuoMetrics.controlSize + Spacing.M
+
+    /// - both fit: both stay whole
+    /// - one fits whole beside the other compressed: one is compressed, tapping it swaps them
+    /// - otherwise both rest compressed; tapping one opens it for a moment (the rail closes
+    ///   again once a tab is picked)
+    static func resolve(
+        layout: ScreenLayout,
+        tabCount: Int,
+        hasQr: Bool,
+        toolbarHeight: CGFloat,
+        expanded: Binding<DuoBar>,
+        opened: Binding<DuoBar?>,
+        setToolbarHeight: @escaping (CGFloat) -> Void
+    ) -> DuoBarCompression {
+        guard let sideBar = layout.sideBar else { return DuoBarCompression() }
+        let room = layout.height - sideBar.bottom - sideBar.top - groupGap
+        let tabBar = duoRailHeight(itemCount: tabCount, hasQr: hasQr)
+        let compressedTabBar = duoRailHeight(itemCount: 1, hasQr: hasQr, compressed: true)
+        func fits(_ toolbar: CGFloat, _ tabs: CGFloat) -> Bool { toolbar + tabs <= room }
+
+        if fits(toolbarHeight, tabBar) {
+            return DuoBarCompression(setToolbarHeight: setToolbarHeight)
+        }
+        if fits(compressedToolbarHeight, tabBar) && fits(toolbarHeight, compressedTabBar) {
+            return DuoBarCompression(
+                toolbarCompressed: expanded.wrappedValue == .tabBar,
+                tabBarCompressed: expanded.wrappedValue == .toolbar,
+                expandToolbar: { expanded.wrappedValue = .toolbar },
+                expandTabBar: { expanded.wrappedValue = .tabBar },
+                setToolbarHeight: setToolbarHeight
+            )
+        }
+
+        let expandToolbar = { opened.wrappedValue = .toolbar }
+        let expandTabBar = { opened.wrappedValue = .tabBar }
+        // an opened rail always shows, even when only the group gap is short: it closes once a tab is picked
+        if opened.wrappedValue == .tabBar {
+            return DuoBarCompression(
+                toolbarCompressed: true,
+                tabBarCompressed: false,
+                toolbarHidden: true,
+                expandToolbar: expandToolbar,
+                expandTabBar: expandTabBar,
+                onTabSelected: { opened.wrappedValue = nil },
+                setToolbarHeight: setToolbarHeight
+            )
+        }
+        return DuoBarCompression(
+            toolbarCompressed: opened.wrappedValue != .toolbar,
+            tabBarCompressed: true,
+            expandToolbar: expandToolbar,
+            expandTabBar: expandTabBar,
+            setToolbarHeight: setToolbarHeight
+        )
+    }
+}
+
+private struct DuoBarCompressionKey: EnvironmentKey {
+    static let defaultValue = DuoBarCompression()
+}
+
+extension EnvironmentValues {
+    var duoBarCompression: DuoBarCompression {
+        get { self[DuoBarCompressionKey.self] }
+        set { self[DuoBarCompressionKey.self] = newValue }
+    }
+}

package/ios/Navigation/BottomTab/DuoTabBar.swift

@@ -0,0 +1,329 @@
+//
+//  DuoTabBar.swift
+//  MoMoUIKits
+//
+//  iPhone Duo tab bar, port of RN `BottomTab/DuoTabBar.tsx` (Figma Fold-Design-System MT1/MT2):
+//  a rail in the side bar, or a floating bar when unfolded portrait.
+//
+
+import SwiftUI
+
+private let itemSize = DuoMetrics.controlSize
+private let iconSize: CGFloat = 28
+private let qrIconSize: CGFloat = 24
+private let railPadding: CGFloat = 6
+private let railGap = Spacing.XXS
+// selection bubble overflows the 48 rail cell by 5 above and below (Figma MT2)
+private let railBubbleWidth: CGFloat = 44
+private let railBubbleHeight: CGFloat = 58
+private let floatingHeight = DuoMetrics.floatingTabBarHeight
+private let floatingPadding = Spacing.XS
+// the system bar sizes its pill to the tabs instead of stretching it across the display
+private let floatingItemWidth: CGFloat = 80
+// while pressed the selection bubble grows into a lens past the pill's edges
+private let lensScaleX: CGFloat = 1.2
+private let lensScaleY: CGFloat = 1.3
+// Figma Home-2026 tab bar "Selection": brand pink at 8%
+private let selectionTintOpacity: Double = 0x14 / 255
+private let tabSpring = Animation.interpolatingSpring(mass: 0.8, stiffness: 220, damping: 18)
+
+/// Room tab screens leave for the Duo tab bar, provided by BottomTab to its tab StackScreens.
+struct DuoTabBarInsets: Equatable {
+    /// Floating bar overlays the content: scroll content, footer and FAB keep clear of it.
+    var overlay: CGFloat = 0
+    /// Rail sits at the bottom of the side strip: the header side bar stays this far above the window bottom.
+    var sideBarReserve: CGFloat = 0
+}
+
+private struct DuoTabBarInsetsKey: EnvironmentKey {
+    static let defaultValue = DuoTabBarInsets()
+}
+
+extension EnvironmentValues {
+    var duoTabBarInsets: DuoTabBarInsets {
+        get { self[DuoTabBarInsetsKey.self] }
+        set { self[DuoTabBarInsetsKey.self] = newValue }
+    }
+}
+
+/// Rail plus the QR button under it; compressed, the rail is a single button.
+func duoRailHeight(itemCount: Int, hasQr: Bool, compressed: Bool = false) -> CGFloat {
+    let count = CGFloat(itemCount)
+    let rail = compressed ? itemSize : railPadding * 2 + count * itemSize + max(count - 1, 0) * railGap
+    return rail + (hasQr ? Spacing.M + itemSize : 0)
+}
+
+extension ScreenLayout {
+    /// Overlaps the home indicator inset like the system tab bar (21pt above the bottom with a 34pt inset).
+    var duoFloatingTabBarBottom: CGFloat {
+        max(insets.bottom - DuoMetrics.floatingTabBarInsetOverlap, Spacing.S)
+    }
+
+    func duoTabBarInsets(itemCount: Int, hasFloatingButton: Bool, tabBarCompressed: Bool = false) -> DuoTabBarInsets {
+        guard isIPhoneDuo else { return DuoTabBarInsets() }
+        guard let sideBar else {
+            // overlay is measured from the bottom safe area, the bar reaches into it
+            return DuoTabBarInsets(overlay: floatingHeight + duoFloatingTabBarBottom - insets.bottom)
+        }
+        let rail = duoRailHeight(itemCount: itemCount, hasQr: hasFloatingButton, compressed: tabBarCompressed)
+        return DuoTabBarInsets(sideBarReserve: sideBar.bottom + rail + DuoBarCompression.groupGap)
+    }
+}
+
+/// RN `BarMaterial`: surface with a 1pt border.
+struct DuoBarMaterial<S: InsettableShape>: ViewModifier {
+    let shape: S
+
+    @Environment(\.appTheme) private var theme
+
+    func body(content: Content) -> some View {
+        content.background(
+            shape.fill(theme.colors.background.surface)
+                .overlay(shape.strokeBorder(theme.colors.border.default, lineWidth: 1))
+                .allowsHitTesting(false)
+        )
+    }
+}
+
+struct DuoTabBar: View {
+    let items: [BottomTabItem]
+    let floatingButton: BottomTabFloatingButton?
+    let selectedIndex: Int
+    let onTabSelected: (Int) -> Void
+    var compression = DuoBarCompression()
+
+    @Environment(\.screenLayout) private var layout
+
+    var body: some View {
+        if let sideBar = layout.sideBar {
+            DuoRailTabBar(sideBar: sideBar, items: items, floatingButton: floatingButton,
+                          selectedIndex: selectedIndex, onTabSelected: onTabSelected, compression: compression)
+        } else {
+            DuoFloatingTabBar(items: items, floatingButton: floatingButton,
+                              selectedIndex: selectedIndex, onTabSelected: onTabSelected)
+        }
+    }
+}
+
+/// Vertical bar anchored to the bottom of the side bar, QR button below it (Figma MT1-C/E).
+/// When the side bar is short it can shrink to one button showing the current tab
+/// (HIG "Tab bar compressed"); tapping it expands the rail and compresses the toolbar.
+private struct DuoRailTabBar: View {
+    let sideBar: SideBarLayout
+    let items: [BottomTabItem]
+    let floatingButton: BottomTabFloatingButton?
+    let selectedIndex: Int
+    let onTabSelected: (Int) -> Void
+    let compression: DuoBarCompression
+
+    @State private var pressedIndex: Int?
+
+    private var isRight: Bool { sideBar.edge == .right }
+
+    var body: some View {
+        VStack(spacing: Spacing.M) {
+            if compression.tabBarCompressed, items.indices.contains(selectedIndex) {
+                SwiftUI.Button(action: compression.expandTabBar) {
+                    DuoTabIcon(item: items[selectedIndex], selected: true)
+                        .frame(width: itemSize, height: itemSize)
+                        .contentShape(Circle())
+                }
+                .buttonStyle(.plain)
+                .modifier(DuoBarMaterial(shape: Circle()))
+                .accessibilityLabel(items[selectedIndex].label)
+                .accessibilityIdentifier("bottom_tab_bar")
+            } else {
+                rail
+            }
+
+            if let floatingButton {
+                DuoQrButton(data: floatingButton, size: itemSize)
+            }
+        }
+        .padding(isRight ? .leading : .trailing, Spacing.M)
+        .frame(width: sideBar.width, alignment: isRight ? .leading : .trailing)
+        .padding(.bottom, sideBar.bottom)
+        .frame(maxWidth: .infinity, maxHeight: .infinity, alignment: isRight ? .bottomTrailing : .bottomLeading)
+        .ignoresSafeArea()
+    }
+
+    /// Column of icon-only tab items with the sliding selection bubble.
+    private var rail: some View {
+        ZStack(alignment: .top) {
+            DuoSelectionMaterial(lens: pressedIndex != nil)
+                .frame(width: railBubbleWidth, height: railBubbleHeight)
+                .offset(y: railPadding - (railBubbleHeight - itemSize) / 2
+                    + CGFloat(pressedIndex ?? selectedIndex) * (itemSize + railGap))
+                .animation(tabSpring, value: selectedIndex)
+                .animation(tabSpring, value: pressedIndex)
+
+            VStack(spacing: railGap) {
+                ForEach(items.indices, id: \.self) { index in
+                    SwiftUI.Button {
+                        onTabSelected(index)
+                        compression.onTabSelected()
+                    } label: {
+                        DuoTabIcon(item: items[index], selected: index == selectedIndex)
+                            .frame(width: itemSize, height: itemSize)
+                            .contentShape(Rectangle())
+                    }
+                    .buttonStyle(DuoLensPressStyle(index: index, pressedIndex: $pressedIndex))
+                    .accessibilityLabel(items[index].label)
+                }
+            }
+            .padding(.vertical, railPadding)
+        }
+        .frame(width: itemSize)
+        .modifier(DuoBarMaterial(shape: Capsule()))
+        .accessibilityIdentifier("bottom_tab_bar")
+    }
+}
+
+/// Floating labelled bar for the unfolded portrait display, QR pinned in its own platter beside it.
+private struct DuoFloatingTabBar: View {
+    let items: [BottomTabItem]
+    let floatingButton: BottomTabFloatingButton?
+    let selectedIndex: Int
+    let onTabSelected: (Int) -> Void
+
+    @Environment(\.screenLayout) private var layout
+    @Environment(\.appTheme) private var theme
+    @State private var pressedIndex: Int?
+
+    private var barWidth: CGFloat {
+        let margins = layout.insets.leading + layout.insets.trailing + 2 * DuoMetrics.floatingTabBarMargin
+        let qr = floatingButton == nil ? 0 : floatingHeight + Spacing.S
+        let preferred = CGFloat(items.count) * floatingItemWidth + 2 * floatingPadding
+        return max(min(preferred, layout.width - margins - qr), 0)
+    }
+
+    private var cellWidth: CGFloat { (barWidth - floatingPadding * 2) / CGFloat(max(items.count, 1)) }
+
+    var body: some View {
+        HStack(spacing: Spacing.S) {
+            bar
+            if let floatingButton {
+                DuoQrButton(data: floatingButton, size: floatingHeight)
+                    .shadow(color: Color.black.opacity(0.16), radius: 16, x: 0, y: 6)
+            }
+        }
+        .padding(.bottom, layout.duoFloatingTabBarBottom)
+        .frame(maxWidth: .infinity, maxHeight: .infinity, alignment: .bottom)
+        .ignoresSafeArea()
+    }
+
+    private var bar: some View {
+        ZStack(alignment: .leading) {
+            DuoSelectionMaterial(lens: pressedIndex != nil)
+                .frame(width: cellWidth)
+                .offset(x: CGFloat(pressedIndex ?? selectedIndex) * cellWidth)
+                .animation(tabSpring, value: selectedIndex)
+                .animation(tabSpring, value: pressedIndex)
+
+            HStack(spacing: 0) {
+                ForEach(items.indices, id: \.self) { index in
+                    tabCell(index)
+                }
+            }
+        }
+        .padding(floatingPadding)
+        .frame(width: barWidth, height: floatingHeight)
+        .modifier(DuoBarMaterial(shape: Capsule()))
+        .accessibilityIdentifier("bottom_tab_bar")
+    }
+
+    private func tabCell(_ index: Int) -> some View {
+        let selected = index == selectedIndex
+        return SwiftUI.Button { onTabSelected(index) } label: {
+            VStack(spacing: Spacing.XXS) {
+                DuoTabIcon(item: items[index], selected: selected)
+                MomoText(
+                    items[index].label,
+                    typography: .labelXsMedium,
+                    color: selected ? theme.colors.primary : theme.colors.text.hint,
+                    textAlign: .center,
+                    maxLines: 1
+                )
+                // like the system tab bar the label keeps its design size; a constant snapshot, nothing to observe
+                .environment(\.momoFontScale, FontScale(userScaleRate: 1, useOSScaleRate: false))
+            }
+            .frame(width: cellWidth)
+            .frame(maxHeight: .infinity)
+            .contentShape(Rectangle())
+        }
+        .buttonStyle(DuoLensPressStyle(index: index, pressedIndex: $pressedIndex))
+        .accessibilityLabel(items[index].label)
+    }
+}
+
+/// Pink tinted capsule under the selected tab; while pressed it grows into a lens (80x54 to about 96x70).
+private struct DuoSelectionMaterial: View {
+    let lens: Bool
+
+    @Environment(\.appTheme) private var theme
+
+    var body: some View {
+        Capsule()
+            .fill(theme.colors.primary.opacity(selectionTintOpacity))
+            .scaleEffect(x: lens ? lensScaleX : 1, y: lens ? lensScaleY : 1)
+            .allowsHitTesting(false)
+    }
+}
+
+/// Tracks the finger so the selection lens jumps to the pressed tab before it is selected.
+private struct DuoLensPressStyle: ButtonStyle {
+    let index: Int
+    @Binding var pressedIndex: Int?
+
+    func makeBody(configuration: Configuration) -> some View {
+        configuration.label.onChange(of: configuration.isPressed) { pressed in
+            if pressed {
+                pressedIndex = index
+            } else if pressedIndex == index {
+                pressedIndex = nil
+            }
+        }
+    }
+}
+
+private struct DuoTabIcon: View {
+    let item: BottomTabItem
+    let selected: Bool
+
+    @Environment(\.appTheme) private var theme
+
+    private var badgeLabel: String? {
+        guard let label = item.badgeLabel else { return nil }
+        if let n = Int(label), n == 0 { return nil }
+        return label
+    }
+
+    var body: some View {
+        Icon(source: item.icon, size: iconSize, color: selected ? theme.colors.primary : theme.colors.text.hint)
+            .overlay(alignment: .topTrailing) {
+                if let badgeLabel, !badgeLabel.isEmpty {
+                    Badge(label: badgeLabel).offset(x: Spacing.S, y: -Spacing.XS)
+                } else if badgeLabel != nil || item.showDot {
+                    BadgeDot(size: .small)
+                }
+            }
+    }
+}
+
+private struct DuoQrButton: View {
+    let data: BottomTabFloatingButton
+    let size: CGFloat
+
+    @Environment(\.appTheme) private var theme
+
+    var body: some View {
+        SwiftUI.Button(action: data.onPress) {
+            Circle()
+                .fill(theme.colors.primary)
+                .frame(width: size, height: size)
+                .overlay(Icon(source: data.icon, size: qrIconSize, color: Colors.black01))
+        }
+        .buttonStyle(.plain)
+        .accessibilityLabel(data.label)
+    }
+}

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

@@ -1,5 +1,12 @@
+//
+//  FloatingButton.swift
+//  MoMoUIKits
+//
+//  SwiftUI mirror of Compose's `navigation/component/FloatingButton.kt`: the screen FAB, whose
+//  label collapses while the content scrolls down.
+//
+
 import SwiftUI
-import Combine
 
 public enum FABSize {
     case small
@@ -58,14 +65,10 @@ public struct FabProps {
 }
 
 public struct FloatingButton: View {
+    @State private var isExpanded: Bool = true
     @State private var lastScrollOffset: CGFloat = 0
-    @State private var isExpanded: Bool = false
-    @State private var internalScrollOffset: CGFloat = 0
-    @State private var showText: Bool = true
-    @State private var fullWidth: CGFloat? = nil
-    @State private var currentWidth: CGFloat = 0
-    @State private var lastDirection: String? = nil
-    
+    @State private var settleScroll: Task<Void, Never>?
+
     private let props: FabProps
     private var keyboardOffset: CGFloat
     private var scrollOffset: CGFloat
@@ -111,64 +114,50 @@ public struct FloatingButton: View {
                 content
             }
         }
-        .onTapGesture {
-            onClick?()
-        }
         .padding(Spacing.M)
         .frame(height: height + (Spacing.M * 2))
         .background(containerColor)
         .cornerRadius(100)
+        // Compose FloatingActionButton elevation 4dp
+        .shadow(color: Color.black.opacity(0.2), radius: 4, x: 0, y: 2)
+        .contentShape(Capsule())
+        .onTapGesture {
+            onClick?()
+        }
+        .accessibilityElement(children: .combine)
+        .accessibilityAddTraits(.isButton)
         .padding(.bottom, bottomPadding)
         .frame(alignment: position == .center ? .center : .trailing)
-        .onAppear {
-            internalScrollOffset = scrollOffset
-            isExpanded = label != nil
-        }
-        .onReceive(Just(scrollOffset)) { newValue in
-            let direction = newValue > internalScrollOffset ? "down" : "up"
+        .onAppear { lastScrollOffset = scrollOffset }
+        .onChange(of: scrollOffset, perform: updateExpanded)
+        .onDisappear { settleScroll?.cancel() }
+    }
 
-            if direction != lastDirection {
-                lastDirection = direction
-                if direction == "down" {
-                    withAnimation(.easeOut(duration: 0.1)) {
-                        isExpanded = false
-                    }
-                    DispatchQueue.main.asyncAfter(deadline: .now() + 0.1) {
-                        showText = false
-                    }
-                } else {
-                    showText = true
-                    withAnimation(.easeIn(duration: 0.1)) {
-                        isExpanded = true
-                    }
-                    
-                }
-            }
+    /// Compose's `collectLatest { isExpanded = new <= last; delay(100); last = new }`: the label
+    /// shows while the content scrolls back up, and the reference only moves once the scroll pauses.
+    private func updateExpanded(_ offset: CGFloat) {
+        let expanded = offset <= lastScrollOffset
+        if expanded != isExpanded {
+            withAnimation(.linear(duration: 0.1)) { isExpanded = expanded }
+        }
+        settleScroll?.cancel()
+        settleScroll = Task { @MainActor in
+            try? await Task.sleep(nanoseconds: 100_000_000)
+            guard !Task.isCancelled else { return }
+            lastScrollOffset = offset
         }
     }
-    
+
     private var content: some View {
         HStack(spacing: 0) {
-            ImageView(icon ?? "")
-                .scaledToFit()
-                .frame(width: iconSize, height: iconSize)
-                .foregroundColor(iconColor)
-            
-            if let label = label {
-                if showText {
-                    Spacer().frame(width: 8)
-                    MomoText(label, typography: .actionDefaultBold, color: .white, maxLines: 1)
-                        .background(
-                            GeometryReader { geo in
-                                Color.clear.onAppear {
-                                    fullWidth = geo.size.width
-                                }
-                            }
-                        )
-                        .opacity(isExpanded ? 1 : 0)
-                }
-            }
+            // Compose `Icon`: an icon key or an https URL, tinted
+            Icon(source: icon ?? "", size: iconSize ?? defaultIconSize, color: iconColor)
 
+            if let label, isExpanded {
+                MomoText(label, typography: .actionDefaultBold, color: .white, maxLines: 1)
+                    .padding(.leading, 12)
+                    .transition(.opacity.combined(with: .move(edge: .leading)))
+            }
         }
     }
 }