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

package/compose/src/commonMain/kotlin/vn/momo/kits/navigation/StackScreen.kt

@@ -0,0 +1,713 @@
+package vn.momo.kits.navigation
+
+import androidx.compose.animation.animateColorAsState
+import androidx.compose.animation.core.Animatable
+import androidx.compose.animation.core.AnimationVector1D
+import androidx.compose.animation.core.tween
+import androidx.compose.foundation.ScrollState
+import androidx.compose.foundation.background
+import androidx.compose.foundation.border
+import androidx.compose.foundation.gestures.ScrollableState
+import androidx.compose.foundation.gestures.animateScrollBy
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.ColumnScope
+import androidx.compose.foundation.layout.Spacer
+import androidx.compose.foundation.layout.WindowInsets
+import androidx.compose.foundation.layout.asPaddingValues
+import androidx.compose.foundation.layout.aspectRatio
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.height
+import androidx.compose.foundation.layout.ime
+import androidx.compose.foundation.layout.imePadding
+import androidx.compose.foundation.layout.offset
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.lazy.LazyListState
+import androidx.compose.foundation.rememberScrollState
+import androidx.compose.foundation.verticalScroll
+import androidx.compose.material.ExperimentalMaterialApi
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.CompositionLocalProvider
+import androidx.compose.runtime.LaunchedEffect
+import androidx.compose.runtime.State
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableIntStateOf
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.rememberUpdatedState
+import androidx.compose.runtime.snapshotFlow
+import androidx.compose.runtime.staticCompositionLocalOf
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.graphics.Brush
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.graphics.graphicsLayer
+import androidx.compose.ui.graphics.lerp
+import androidx.compose.ui.layout.onGloballyPositioned
+import androidx.compose.ui.platform.LocalDensity
+import androidx.compose.ui.unit.Dp
+import androidx.compose.ui.unit.dp
+import androidx.compose.ui.unit.lerp
+import androidx.compose.ui.zIndex
+import kotlinx.coroutines.flow.Flow
+import kotlinx.coroutines.flow.filter
+import kotlinx.coroutines.launch
+import vn.momo.kits.components.InputSearch
+import vn.momo.kits.const.AppNavigationBar
+import vn.momo.kits.const.AppTheme
+import vn.momo.kits.application.IsShowBaseLineDebug
+import vn.momo.kits.const.Colors
+import vn.momo.kits.const.Spacing
+import vn.momo.kits.modifier.conditional
+import vn.momo.kits.modifier.hideKeyboardOnTap
+import vn.momo.kits.navigation.bottomtab.BOTTOM_TAB_BAR_HEIGHT
+import vn.momo.kits.navigation.component.FABPosition
+import vn.momo.kits.navigation.component.FloatingButton
+import vn.momo.kits.navigation.component.HEADER_HEIGHT
+import vn.momo.kits.navigation.component.Header
+import vn.momo.kits.navigation.component.HeaderBackground
+import vn.momo.kits.navigation.component.HeaderRight
+import vn.momo.kits.navigation.component.HeaderSideBar
+import vn.momo.kits.navigation.bottomtab.LocalDuoRailReserve
+import vn.momo.kits.navigation.bottomtab.duoFloatingTabBarInset
+import vn.momo.kits.navigation.component.HeaderType
+import vn.momo.kits.navigation.component.InputSearchType
+import vn.momo.kits.platform.BackHandler
+import vn.momo.kits.platform.supportsImePadding
+import vn.momo.kits.navigation.tracking.ScreenTracker
+import vn.momo.kits.navigation.tracking.ScreenTrackingState
+import kotlinx.coroutines.delay
+import vn.momo.kits.application.LocalContext
+import vn.momo.kits.utils.horizontalSafeAreaPadding
+import vn.momo.kits.layout.LocalScreenLayout
+import vn.momo.kits.layout.ScreenLayout
+import vn.momo.kits.layout.consumeHorizontalInsets
+import vn.momo.kits.layout.DuoMetrics
+import vn.momo.kits.layout.getScreenLayout
+import kotlin.time.Clock
+import kotlin.time.Duration.Companion.milliseconds
+import kotlin.time.ExperimentalTime
+
+internal val LocalFooterHeightPx = staticCompositionLocalOf { mutableIntStateOf(0) }
+internal val LocalHeaderRightWidthPx = staticCompositionLocalOf { mutableIntStateOf(0) }
+
+// Space a tab's content leaves for the tab bar and home indicator. On iPhone Duo the floating bar
+// overlays the content and the rail lives in the side strip, so only their own inset applies.
+@Composable
+private fun bottomTabChildInset(): Dp {
+    val keyboard = keyboardSizeState().value
+    val navigationBar = AppNavigationBar.current
+    val layout = getScreenLayout()
+    return when {
+        layout.isIPhoneDuo && layout.sideBar == null -> (duoFloatingTabBarInset(layout) - keyboard).coerceAtLeast(0.dp)
+        layout.isIPhoneDuo -> (navigationBar - keyboard).coerceAtLeast(0.dp)
+        else -> (BOTTOM_TAB_BAR_HEIGHT.dp + Spacing.S - keyboard).coerceAtLeast(0.dp) +
+            (navigationBar - keyboard).coerceAtLeast(0.dp)
+    }
+}
+
+@OptIn(ExperimentalMaterialApi::class, ExperimentalTime::class)
+@Composable
+internal fun StackScreen(
+    content: @Composable () -> Unit,
+    navigationOptions: NavigationOptions? = null,
+    id: Int = -1,
+    name: String = "",
+    bottomTabIndex: Int = -1,
+    onBackHandler: (() -> Unit)? = null,
+) {
+    val navigator = LocalNavigator.current
+    val maxApi = LocalMaxApi.current
+    val context = LocalContext.current
+    val screenLayout = getScreenLayout()
+    val density = LocalDensity.current
+    val screenRegistry = LocalDynamicScreenRegistry.current
+    val navigation = remember { Navigation(id = id, bottomTabIndex = bottomTabIndex, initOptions = navigationOptions, registry = screenRegistry) }
+
+    val options by navigation.currentOptions
+    val isBottomTabChild = bottomTabIndex != -1
+    val isBottomTabRoot = navigation.isBottomTabRoot
+
+    // Auto tracking state
+    val trackingState = remember {
+        ScreenTrackingState().apply {
+            time = Clock.System.now().toEpochMilliseconds()
+        }
+    }
+
+    // Determine action: push or back
+    val action = remember {
+        if (ScreenTracker.getLastScreenName() != null) "push" else "back"
+    }
+
+    // Auto tracking effects
+    LaunchedEffect(name) {
+        // Track screen navigated immediately
+        ScreenTracker.trackScreenNavigated(
+            maxApi = maxApi,
+            context = context,
+            screenName = name,
+            action = action,
+            state = trackingState
+        )
+
+        // Track screen displayed after 2 seconds (debounce)
+        delay(2000.milliseconds)
+        val loadTime = Clock.System.now().toEpochMilliseconds() - trackingState.time
+        ScreenTracker.trackScreenDisplayed(
+            maxApi = maxApi,
+            context = context,
+            screenName = name,
+            duration = loadTime,
+            state = trackingState
+        )
+
+        // Track screen interacted after displayed
+        val interactionTime = Clock.System.now().toEpochMilliseconds() - trackingState.time
+        ScreenTracker.trackScreenInteracted(
+            maxApi = maxApi,
+            context = context,
+            screenName = name,
+            duration = interactionTime - loadTime,
+            totalDuration = interactionTime,
+            state = trackingState
+        )
+    }
+
+    val limit = with(density) {
+        screenLayout.headerHeight.toPx()
+    }.toInt()
+
+    val lazyListState = options.scrollData.scrollState as? LazyListState
+    val (scrollState, _) = if (lazyListState != null)
+        lazyListState.proxyScrollState(limit, 1)
+    else
+        (options.scrollData.scrollState as? ScrollState ?: rememberScrollState()).proxyLimitedScrollState(limit, 1)
+    val snapState: ScrollableState = lazyListState ?: scrollState
+    val headerHide = rememberQuickReturnHide(
+        enabled = options.usesDuoQuickReturnHeader(screenLayout),
+        scrollState = scrollState,
+        heightPx = with(density) { screenLayout.headerHeight.toPx() },
+    )
+
+    val footerHeightPx = remember { mutableIntStateOf(0) }
+    val headerRightWidthPx = remember { mutableIntStateOf(0) }
+
+    if (navigation.options.scrollData.scrollToTopCallback != null) {
+        RegisterScrollToTop(navigation.options.scrollData.scrollToTopCallback)
+    }
+
+    val canPop = navigator.canPop()
+
+    val hasCustomBackHandling = !SwipeBackConfig.enabled ||
+            OverplayComponentRegistry.isOverplayShowing() ||
+            !canPop
+
+    BackHandler(hasCustomBackHandling) { navigator.onBackSafe() }
+
+    CompositionLocalProvider(
+        StackScreenScrollableState provides options.scrollData.scrollState,
+        LocalNavigation provides navigation,
+        LocalScrollState provides scrollState,
+        LocalOptions provides options,
+        LocalFooterHeightPx provides footerHeightPx,
+        LocalHeaderRightWidthPx provides headerRightWidthPx
+    ) {
+        Box(
+            Modifier
+                .fillMaxSize()
+                .background(options.backgroundColor ?: AppTheme.current.colors.background.default)
+                .conditional(options.keyboardOptions.keyboardShouldPersistTaps) {
+                    hideKeyboardOnTap()
+                }
+                .conditional(options.keyboardOptions.useAvoidKeyboard && supportsImePadding()) {
+                    imePadding()
+                }
+        ) {
+            Box(Modifier.zIndex(1f)) {
+                HeaderBackground()
+            }
+
+            Box(Modifier.zIndex(4f).graphicsLayer { translationY = -headerHide.value }) {
+                Header(onBackHandler)
+            }
+
+            HeaderSideBar(
+                bottomInset = maxOf(
+                    bottomBarsHeight(isBottomTabChild) + Spacing.XL,
+                    if (isBottomTabChild) LocalDuoRailReserve.current else 0.dp,
+                ),
+                modifier = Modifier.zIndex(4f),
+            )
+
+            Column(Modifier.zIndex(5f).horizontalSafeAreaPadding()) {
+                SearchAnimated(snapState = snapState)
+            }
+
+            Column(Modifier.zIndex(2f).fillMaxSize()) {
+                MainContent(content = content, isBottomTabRoot = isBottomTabRoot, isBottomTabChild = isBottomTabChild)
+                FooterContent()
+            }
+
+            Box(Modifier.zIndex(6f).horizontalSafeAreaPadding()) {
+                FloatingContent(isBottomTabChild = isBottomTabChild)
+            }
+
+            OverplayView(isBottomTabChild = isBottomTabChild, id = id)
+        }
+    }
+}
+
+// Height the footer, tab bar or home indicator takes from the bottom of the screen.
+@Composable
+private fun bottomBarsHeight(isBottomTabChild: Boolean): Dp {
+    val options = LocalOptions.current
+    val navigationBar = AppNavigationBar.current
+    return when {
+        options.hasFooter() -> with(LocalDensity.current) { LocalFooterHeightPx.current.intValue.toDp() }
+        isBottomTabChild -> bottomTabChildInset()
+        else -> navigationBar
+    }
+}
+
+@Suppress("FrequentlyChangingValue")
+@Composable
+internal fun FloatingContent(isBottomTabChild: Boolean) {
+    val options = LocalOptions.current
+    val scrollState = LocalScrollState.current
+
+    val fabProps = options.floatingButtonProps ?: return
+    val bottomPadding = fabProps.bottom ?: (Spacing.M + bottomBarsHeight(isBottomTabChild))
+
+    FloatingButton(
+        scrollPosition = fabProps.scrollState?.value ?: scrollState.value,
+        onClick = fabProps.onClick,
+        containerColor = AppTheme.current.colors.primary,
+        bottom = bottomPadding,
+        icon = fabProps.icon,
+        iconColor = fabProps.iconColor,
+        text = fabProps.label,
+        size = fabProps.size,
+        position = fabProps.position ?: FABPosition.END,
+    )
+}
+
+@Composable
+internal fun ColumnScope.MainContent(content: @Composable () -> Unit, isBottomTabRoot: Boolean, isBottomTabChild: Boolean) {
+    val options = LocalOptions.current
+    val inputSearchType = getInputSearchType(options)
+    val density = LocalDensity.current
+    val scrollState = LocalScrollState.current
+    val navigationBar = AppNavigationBar.current
+    val screenLayout = getScreenLayout()
+    val useDuoGlass = options.usesDuoGlassHeader(screenLayout)
+
+    Spacer(
+        Modifier.height(
+            if (!useDuoGlass && (options.headerType is HeaderType.DefaultOrExtended || (options.headerType is HeaderType.Transparent && !options.headerType.isFullScreenContent)))
+                screenLayout.headerHeight else 0.dp
+        )
+    )
+    if (inputSearchType == InputSearchType.Animated) {
+        val scrollDp = with(density) { scrollState.value.toDp() }
+
+        Spacer(Modifier.height((HEADER_HEIGHT.dp - scrollDp).coerceIn(0.dp, HEADER_HEIGHT.dp)))
+    }
+    // a bottom tab root stays full width: the tab bar and each tab's own StackScreen handle the insets
+    val insetContent = !isBottomTabRoot
+    Column(
+        Modifier
+            .fillMaxWidth()
+            .weight(1f)
+            .conditional(insetContent && options.headerType !is HeaderType.Animated) {
+                horizontalSafeAreaPadding()
+            }
+            .conditional(options.scrollData.scrollable && options.scrollData.scrollState is ScrollState) {
+                verticalScroll(scrollState)
+            }
+            .conditional(useDuoGlass) {
+                padding(top = screenLayout.headerHeight)
+            }
+            .padding(
+                bottom = when {
+                    options.hasFooter() || isBottomTabRoot -> 0.dp
+                    isBottomTabChild -> bottomTabChildInset()
+                    !options.scrollData.scrollable && options.scrollData.scrollState == null -> 0.dp
+                    else -> navigationBar
+                }
+            )
+    ) {
+        ScreenContent(content = content, insetContent = insetContent)
+    }
+
+}
+
+@Composable
+internal fun ScreenContent(content: @Composable () -> Unit, insetContent: Boolean) {
+    val scrollState = LocalScrollState.current
+    val options = LocalOptions.current
+    val screenLayout = getScreenLayout()
+    val insetBody: @Composable () -> Unit = {
+        CompositionLocalProvider(
+            LocalScreenLayout provides if (insetContent) screenLayout.consumeHorizontalInsets() else screenLayout,
+            content = content,
+        )
+    }
+
+    if (options.headerType is HeaderType.Animated) {
+        val animatedHeader = options.headerType
+        Box {
+            val bannerModifier = animatedHeader.height
+                ?.let { Modifier.fillMaxWidth().height(it) }
+                ?: Modifier.fillMaxWidth().aspectRatio(animatedHeader.aspectRatio.value)
+            Box(bannerModifier) {
+                animatedHeader.composable.invoke(scrollState.value)
+            }
+            Box(
+                Modifier
+                    .padding(top = screenLayout.headerHeight + animatedHeader.layoutOffSet)
+                    .conditional(insetContent) { horizontalSafeAreaPadding() }
+            ) {
+                insetBody()
+            }
+        }
+    } else {
+        insetBody()
+    }
+}
+
+@Composable
+internal fun FooterContent() {
+    val options = LocalOptions.current
+    if (options.hasFooter()) {
+        val keyboardSize = keyboardSizeState()
+        // the Duo floating tab bar overlays tab content, so a tab's footer sits above it
+        val duoTabInset = if (LocalNavigation.current.bottomTabIndex != -1) duoFloatingTabBarInset(getScreenLayout()) else 0.dp
+        val bottomPadding = (maxOf(AppNavigationBar.current, duoTabInset) - keyboardSize.value).coerceAtLeast(0.dp)
+        Footer(
+            footerComponent = options.footerComponent,
+            bottomPadding = bottomPadding,
+            transparent = options.footerTransparent,
+            useMargin = options.footerUseMargin
+        )
+    }
+}
+
+@Composable
+internal fun keyboardSizeState(): State<Dp> {
+    val bottom = WindowInsets.ime.asPaddingValues()
+    return rememberUpdatedState(bottom.calculateBottomPadding())
+}
+
+@Composable
+internal fun OverplayView(isBottomTabChild: Boolean, id: Int) {
+    val overplayType = OverplayComponentRegistry.getOverplayType()
+
+    if (overplayType != null) {
+        Box(Modifier.zIndex(if (overplayType == OverplayComponentType.SNACK_BAR) 3f else 7f).fillMaxSize()) {
+            if (isBottomTabChild) return@Box
+            if (OverplayComponentRegistry.currentRootId() != id) return@Box
+            OverplayComponentRegistry.OverlayComponent()
+        }
+    }
+}
+
+@Composable
+fun Footer(
+    footerComponent: @Composable (() -> Unit)?,
+    bottomPadding: Dp,
+    transparent: Boolean = false,
+    useMargin: Boolean = true,
+) {
+    if (footerComponent == null) return
+
+    val footerHeightPx = LocalFooterHeightPx.current
+
+    val shadowBrush = remember {
+        Brush.verticalGradient(
+            colors = listOf(Color.Transparent, Color.Black.copy(alpha = 0.05f))
+        )
+    }
+
+    val backgroundColor = if (transparent) Color.Transparent else AppTheme.current.colors.background.surface
+
+    // inset as a whole, not padded inside, so the surface and its shadow stay off the iPhone Duo side bar
+    Box(Modifier.onGloballyPositioned {
+        if (footerHeightPx.intValue != it.size.height) footerHeightPx.intValue = it.size.height
+    }.horizontalSafeAreaPadding()) {
+        Box(
+            Modifier
+                .fillMaxWidth()
+                .background(backgroundColor)
+                .conditional(IsShowBaseLineDebug) {
+                    border(1.dp, Colors.blue_03)
+                }
+                .padding(
+                    top = if (useMargin) Spacing.S else 0.dp,
+                    start = if (useMargin) Spacing.M else 0.dp,
+                    end = if (useMargin) Spacing.M else 0.dp,
+                    bottom = bottomPadding + if (useMargin) Spacing.S else 0.dp,
+                )
+        ) {
+            footerComponent.invoke()
+        }
+
+        if (!transparent) {
+            Box(
+                modifier = Modifier
+                    .fillMaxWidth()
+                    .height(6.dp)
+                    .offset(x = 0.dp, y = (-6).dp)
+                    .background(shadowBrush)
+            )
+        }
+    }
+}
+
+data class InputSearchLayoutParams(
+    val topPadding: Dp,
+    val startPadding: Dp,
+    val endPadding: Dp
+)
+
+@Suppress("FrequentlyChangingValue")
+@Composable
+internal fun SearchAnimated(
+    snapState: ScrollableState
+) {
+    val scrollState = LocalScrollState.current
+    val options = LocalOptions.current
+    val navigator = LocalNavigator.current
+    val density = LocalDensity.current
+
+    val scrollDp = with(density) { scrollState.value.toDp() }
+
+    val inputSearchType = getInputSearchType(options)
+    val headerRightWidthPx = LocalHeaderRightWidthPx.current
+    val headerRightWidthDp = with(density) { headerRightWidthPx.intValue.toDp() }
+
+    if (inputSearchType == InputSearchType.None) return
+    val inputSearchProps = (options.headerType as? HeaderType.DefaultOrExtended)?.inputSearchProps ?: return
+
+    val screenLayout = getScreenLayout()
+    val useSideBar = screenLayout.sideBar != null
+    // collapsed, the search is centered in the bar row
+    val minTopPadding = screenLayout.headerStatusBarHeight + (screenLayout.headerBarHeight - HEADER_HEIGHT.dp) / 2
+    val maxTopPadding = screenLayout.headerHeight
+    // collapsed on the iPhone Duo status bar row, the search stays between its clusters (48pt back there)
+    val clearance = screenLayout.statusBarClearance
+    val backWidth = if (clearance != null && !useSideBar) DuoMetrics.controlSize else 28.dp
+    val minStartPadding = Spacing.M
+    val maxStartPadding = (clearance?.left ?: 0.dp) +
+        if (options.hiddenBack || useSideBar) Spacing.M else backWidth + Spacing.M + Spacing.S
+    val minEndPadding = Spacing.M
+    val maxEndPadding = (clearance?.right ?: 0.dp) + when {
+        options.headerRight is HeaderRight.None -> Spacing.M
+        useSideBar && options.headerRight is HeaderRight.Toolkit -> Spacing.M
+        else -> headerRightWidthDp + Spacing.M * 2
+    }
+
+    val targetColor = lerp(
+        AppTheme.current.colors.background.surface,
+        AppTheme.current.colors.background.default,
+        (scrollDp / minTopPadding.coerceAtLeast(1.dp)).coerceIn(0f, 1f)
+    )
+    val animatedColor by animateColorAsState(targetValue = targetColor, label = "BackgroundColor")
+
+    val layoutParams = when (inputSearchType) {
+        InputSearchType.Header -> {
+            InputSearchLayoutParams(
+                topPadding = minTopPadding,
+                startPadding = maxStartPadding,
+                endPadding = maxEndPadding
+            )
+        }
+
+        InputSearchType.Animated -> {
+            val collapsePx = with(density) { HEADER_HEIGHT.dp.roundToPx() }
+            val progress = (scrollState.value / collapsePx.toFloat()).coerceIn(0f, 1f)
+
+            LaunchedEffect(snapState, collapsePx) {
+                snapshotFlow { snapState.isScrollInProgress }
+                    .filter { !it }
+                    .collect {
+                        val offset = snapState.headerOffsetPx() ?: return@collect
+                        if (offset <= 0 || offset >= collapsePx) return@collect
+                        val target = if (offset < collapsePx / 2) 0 else collapsePx
+                        launch { snapState.animateScrollBy((target - offset).toFloat()) }
+                    }
+            }
+
+            InputSearchLayoutParams(
+                topPadding = lerp(maxTopPadding, minTopPadding, progress),
+                startPadding = lerp(minStartPadding, maxStartPadding, progress),
+                endPadding = lerp(minEndPadding, maxEndPadding, progress)
+            )
+        }
+
+        InputSearchType.None -> return
+    }
+
+    Spacer(Modifier.height(layoutParams.topPadding))
+    Box(
+        modifier = Modifier
+            .height(HEADER_HEIGHT.dp)
+            .fillMaxWidth()
+            .padding(
+                start = layoutParams.startPadding,
+                end = layoutParams.endPadding
+            ),
+        contentAlignment = Alignment.Center
+    ) {
+        InputSearch(
+            inputSearchProps = inputSearchProps.copy(
+                backgroundColor = animatedColor,
+                onPressButtonText = {
+                    navigator.pop()
+                }
+            )
+        )
+    }
+}
+
+private fun ScrollableState.headerOffsetPx(): Int? = when (this) {
+    is LazyListState -> if (firstVisibleItemIndex == 0) firstVisibleItemScrollOffset else null
+    is ScrollState -> value
+    else -> null
+}
+
+private fun quantize(value: Int, stepPx: Int): Int {
+    if (stepPx <= 1) return value
+    return (value / stepPx) * stepPx
+}
+
+@Composable
+internal fun LazyListState.proxyScrollState(
+    thresholdPx: Int = 200,
+    stepPx: Int = 4
+): Pair<ScrollState, Boolean> = proxyScroll(
+    source = this,
+    thresholdPx = thresholdPx,
+    stepPx = stepPx,
+    isScrollInProgress = { isScrollInProgress },
+    rawTargetFlow = {
+        snapshotFlow {
+            if (firstVisibleItemIndex == 0) firstVisibleItemScrollOffset
+            else SCROLLED_PAST_FIRST_ITEM_THRESHOLD
+        }
+    },
+)
+
+@Composable
+internal fun ScrollState.proxyLimitedScrollState(
+    thresholdPx: Int = 200,
+    stepPx: Int = 4
+): Pair<ScrollState, Boolean> = proxyScroll(
+    source = this,
+    thresholdPx = thresholdPx,
+    stepPx = stepPx,
+    isScrollInProgress = { isScrollInProgress },
+    rawTargetFlow = { snapshotFlow { value } },
+)
+
+@Composable
+private fun proxyScroll(
+    source: Any,
+    thresholdPx: Int,
+    stepPx: Int,
+    isScrollInProgress: () -> Boolean,
+    rawTargetFlow: () -> Flow<Int>,
+): Pair<ScrollState, Boolean> {
+    val proxy = rememberScrollState()
+    val locked = remember { mutableStateOf(false) }
+
+    LaunchedEffect(source, proxy, thresholdPx, stepPx) {
+        rawTargetFlow().collect { rawTarget ->
+            val shouldLock = rawTarget > thresholdPx
+            if (locked.value != shouldLock) locked.value = shouldLock
+
+            val desired = if (shouldLock) thresholdPx else quantize(rawTarget, stepPx)
+
+            if (proxy.value != desired) {
+                proxy.scrollTo(desired.coerceAtLeast(0))
+            }
+        }
+    }
+
+    val inProgress = remember { mutableStateOf(false) }
+    LaunchedEffect(source, thresholdPx) {
+        snapshotFlow { isScrollInProgress() }
+            .collect { progressing ->
+                inProgress.value = if (locked.value) false else progressing
+            }
+    }
+
+    return proxy to inProgress.value
+}
+
+private const val SCROLLED_PAST_FIRST_ITEM_THRESHOLD = 10_000
+
+internal val LocalScrollState = staticCompositionLocalOf<ScrollState> { error("No Scroll State provided") }
+internal val LocalOptions = staticCompositionLocalOf<NavigationOptions> { error("No NavigationOptions provided") }
+
+val StackScreenScrollableState = staticCompositionLocalOf<ScrollableState?> { null }
+
+// iPhone Duo side bar: the header leaves with the content and slides back in on a reverse scroll
+// (RN DuoQuickReturnHeader). The side bar is drawn apart from the header, so it stays put.
+@Composable
+private fun rememberQuickReturnHide(
+    enabled: Boolean,
+    scrollState: ScrollState,
+    heightPx: Float,
+): Animatable<Float, AnimationVector1D> {
+    val hide = remember { Animatable(0f) }
+    LaunchedEffect(enabled, scrollState, heightPx) {
+        if (!enabled) {
+            hide.snapTo(0f)
+            return@LaunchedEffect
+        }
+        var last = scrollState.value
+        snapshotFlow { scrollState.value }.collect { y ->
+            val delta = y - last
+            last = y
+            hide.snapTo(if (y <= 0) 0f else (hide.value + delta).coerceIn(0f, heightPx))
+        }
+    }
+    // a half-shown header settles fully in or out once the scroll stops
+    LaunchedEffect(enabled, scrollState, heightPx) {
+        if (!enabled) return@LaunchedEffect
+        snapshotFlow { scrollState.isScrollInProgress }
+            .filter { !it }
+            .collect {
+                val value = hide.value
+                // within the first header height the header still sits on the content
+                if (scrollState.value < heightPx || value <= 0f || value >= heightPx) return@collect
+                launch { hide.animateTo(if (value > heightPx / 2) heightPx else 0f, tween(200)) }
+            }
+    }
+    return hide
+}
+
+internal fun NavigationOptions.usesDuoQuickReturnHeader(layout: ScreenLayout): Boolean =
+    usesDuoGlassHeader(layout) || (layout.sideBar != null && headerType is HeaderType.Animated &&
+        scrollData.scrollable && scrollData.scrollState is ScrollState)
+
+// iPhone Duo side bar: content scrolls under a glass header instead of starting below it (RN Screen).
+internal fun NavigationOptions.usesDuoGlassHeader(layout: ScreenLayout): Boolean =
+    layout.sideBar != null && headerType is HeaderType.DefaultOrExtended &&
+        getInputSearchType(this) == InputSearchType.None &&
+        scrollData.scrollable && scrollData.scrollState is ScrollState
+
+internal fun getInputSearchType(options: NavigationOptions): InputSearchType {
+    return when (val headerType = options.headerType) {
+        is HeaderType.DefaultOrExtended -> when {
+            headerType.inputSearchProps == null -> InputSearchType.None
+            headerType.useAnimated -> InputSearchType.Animated
+            else -> InputSearchType.Header
+        }
+
+        else -> InputSearchType.None
+    }
+}
+