react-native-screens 5.0.0-alpha.2 → 5.0.0-alpha.3

package/android/src/main/java/com/swmansion/rnscreens/stack/header/StackHeaderCoordinatorLayout.kt

@@ -2,16 +2,18 @@ package com.swmansion.rnscreens.stack.header
 
 import android.annotation.SuppressLint
 import android.content.Context
-import android.util.Log
+import android.content.res.Configuration
+import android.os.Parcelable
+import android.util.SparseArray
 import android.view.ViewGroup.LayoutParams.MATCH_PARENT
 import android.widget.FrameLayout
-import androidx.activity.OnBackPressedDispatcherOwner
 import androidx.appcompat.view.ContextThemeWrapper
 import androidx.coordinatorlayout.widget.CoordinatorLayout
-import com.facebook.react.bridge.ReactContext
 import com.google.android.material.R
 import com.google.android.material.appbar.AppBarLayout
-import com.google.android.material.appbar.MaterialToolbar
+import com.swmansion.rnscreens.common.colorscheme.ColorSchemeCoordinator
+import com.swmansion.rnscreens.common.colorscheme.ColorSchemeListener
+import com.swmansion.rnscreens.common.colorscheme.ColorSchemeProviding
 import com.swmansion.rnscreens.stack.header.appbar.StackHeaderAppBarLayout
 import com.swmansion.rnscreens.stack.header.appbar.StackHeaderScrollingViewBehavior
 import com.swmansion.rnscreens.stack.header.config.OnHeaderConfigurationAttachListener
@@ -19,9 +21,6 @@ import com.swmansion.rnscreens.stack.header.config.StackHeaderConfigurationObser
 import com.swmansion.rnscreens.stack.header.config.StackHeaderConfigurationProviding
 import com.swmansion.rnscreens.stack.header.config.StackHeaderDelegate
 import com.swmansion.rnscreens.stack.header.config.StackHeaderInvalidationFlags
-import com.swmansion.rnscreens.stack.header.toolbar.StackHeaderToolbarMenuApplicator
-import com.swmansion.rnscreens.stack.header.toolbar.StackHeaderToolbarMenuSelectionController
-import com.swmansion.rnscreens.stack.header.toolbar.update.StackHeaderToolbarMenuElementUpdate
 import com.swmansion.rnscreens.stack.screen.StackScreen
 
 /**
@@ -34,7 +33,9 @@ internal class StackHeaderCoordinatorLayout(
     context: Context,
     internal val stackScreen: StackScreen,
     private val canNavigateBack: Boolean,
-) : CoordinatorLayout(context) {
+    private val backPressHandler: StackHeaderBackPressHandler,
+) : CoordinatorLayout(context),
+    ColorSchemeProviding {
     // region Config attach / detach
 
     private var currentProvider: StackHeaderConfigurationProviding? = null
@@ -52,7 +53,10 @@ internal class StackHeaderCoordinatorLayout(
         delegate: StackHeaderDelegate?,
     ) {
         // Disconnect old config to prevent spurious updates from a detached config.
-        currentProvider?.setConfigurationObserver(null)
+        currentProvider?.let {
+            it.setConfigurationObserver(null)
+            it.toolbarMenuController.detach()
+        }
 
         currentProvider = provider
         currentDelegate = delegate
@@ -72,34 +76,6 @@ internal class StackHeaderCoordinatorLayout(
     private val configObserver =
         object : StackHeaderConfigurationObserver {
             override fun onConfigChanged(config: StackHeaderConfigurationProviding) = processUpdate(config)
-
-            override fun onMenuElementsUpdated(updates: List<StackHeaderToolbarMenuElementUpdate>) {
-                val toolbar = appBarLayout?.toolbar
-                if (toolbar == null) {
-                    Log.w(
-                        TAG,
-                        "[RNScreens] Dropping ${updates.size} resolved toolbar menu update(s): " +
-                            "the header toolbar is not currently attached (header hidden or detached).",
-                    )
-                    return
-                }
-                // Apply every element first, collecting the groups whose selection changed,
-                // then emit a single coalesced event per affected group.
-                val affectedGroups = LinkedHashSet<String>()
-                for (update in updates) {
-                    StackHeaderToolbarMenuApplicator.updateToolbarMenuElement(
-                        toolbar,
-                        selectionController.forwardIdMap,
-                        update.id,
-                        update.options,
-                    )
-                    val checked = update.options.checked
-                    if (checked != null) {
-                        selectionController.applyGroupItemStateChange(toolbar, update.id, checked)?.let(affectedGroups::add)
-                    }
-                }
-                affectedGroups.forEach { groupId -> emitGroupSelection(toolbar, groupId) }
-            }
         }
 
     // endregion
@@ -107,7 +83,8 @@ internal class StackHeaderCoordinatorLayout(
     // region Layout callbacks
 
     private val appBarOffsetListener =
-        AppBarLayout.OnOffsetChangedListener { _, _ ->
+        AppBarLayout.OnOffsetChangedListener { appBar, verticalOffset ->
+            evaluateCollapseState(appBar, verticalOffset)
             onMaybeHeaderLayoutChanged()
         }
 
@@ -133,6 +110,20 @@ internal class StackHeaderCoordinatorLayout(
         StackHeaderFrameSynchronizer.sync(appBar, provider, delegate)
     }
 
+    // Tracks whether the app bar is currently scrolled to its fully collapsed offset. Used to work
+    // around a Material offset bug when the title/subtitle changes at runtime — see
+    // StackHeaderApplicator.applyTitleAndSubtitle. This should be equivalent to Material's
+    // `collapsingTitleHelper.getExpansionFraction() == 1f` condition.
+    private var isAppBarFullyCollapsed = false
+
+    private fun evaluateCollapseState(
+        appBar: AppBarLayout,
+        verticalOffset: Int,
+    ) {
+        val totalScrollRange = appBar.totalScrollRange
+        isAppBarFullyCollapsed = totalScrollRange > 0 && -verticalOffset >= totalScrollRange
+    }
+
     // endregion
 
     // region Header updates
@@ -145,19 +136,18 @@ internal class StackHeaderCoordinatorLayout(
 
     private val applicator = StackHeaderApplicator(wrappedContext)
 
-    private val selectionController = StackHeaderToolbarMenuSelectionController()
-
     private var appBarLayout: StackHeaderAppBarLayout? = null
 
     private val onNavigationIconClick: () -> Unit = {
-        val activity =
-            (stackScreen.context as? ReactContext)?.currentActivity
-                as? OnBackPressedDispatcherOwner
-        activity?.onBackPressedDispatcher?.onBackPressed()
+        backPressHandler.handleHeaderBackButtonPress(stackScreen)
     }
 
-    private fun processUpdate(provider: StackHeaderConfigurationProviding) {
-        val needsRebuild = provider.invalidationFlags.needsRebuild
+    private fun processUpdate(
+        provider: StackHeaderConfigurationProviding,
+        forcedFlags: StackHeaderInvalidationFlags = StackHeaderInvalidationFlags.NONE,
+    ) {
+        val effectiveFlags = provider.invalidationFlags or forcedFlags
+        val needsRebuild = effectiveFlags.needsRebuild
         if (needsRebuild) {
             resetHeader()
             if (provider.hidden) {
@@ -179,22 +169,42 @@ internal class StackHeaderCoordinatorLayout(
 
         val appBar = appBarLayout
         if (appBar != null) {
-            if (needsRebuild || provider.invalidationFlags.containsAny(StackHeaderInvalidationFlags.TITLE)) {
-                applicator.applyTitle(appBar, provider)
+            if (needsRebuild || effectiveFlags.containsAny(StackHeaderInvalidationFlags.TITLE)) {
+                applicator.applyTitleAndSubtitle(appBar, provider, isAppBarFullyCollapsed)
                 provider.clearInvalidationFlags(StackHeaderInvalidationFlags.TITLE)
             }
 
-            if (needsRebuild || provider.invalidationFlags.containsAny(StackHeaderInvalidationFlags.BACK_BUTTON)) {
+            if (needsRebuild || effectiveFlags.containsAny(StackHeaderInvalidationFlags.TITLE_APPEARANCE)) {
+                applicator.applyTitleAndSubtitleAppearance(appBar, provider)
+                provider.clearInvalidationFlags(StackHeaderInvalidationFlags.TITLE_APPEARANCE)
+            }
+
+            if (needsRebuild || effectiveFlags.containsAny(StackHeaderInvalidationFlags.TITLE_POSITIONING)) {
+                applicator.applyTitlePositioning(appBar, provider)
+                provider.clearInvalidationFlags(StackHeaderInvalidationFlags.TITLE_POSITIONING)
+            }
+
+            if (needsRebuild || effectiveFlags.containsAny(StackHeaderInvalidationFlags.CONTENT_INSETS)) {
+                applicator.applyContentInsets(appBar, provider)
+                provider.clearInvalidationFlags(StackHeaderInvalidationFlags.CONTENT_INSETS)
+            }
+
+            if (needsRebuild || effectiveFlags.containsAny(StackHeaderInvalidationFlags.BACK_BUTTON)) {
                 applicator.applyBackButton(appBar.toolbar, provider, canNavigateBack, onNavigationIconClick)
                 provider.clearInvalidationFlags(StackHeaderInvalidationFlags.BACK_BUTTON)
             }
 
-            if (needsRebuild || provider.invalidationFlags.containsAny(StackHeaderInvalidationFlags.SCROLL_FLAGS)) {
+            if (needsRebuild || effectiveFlags.containsAny(StackHeaderInvalidationFlags.SCROLL_FLAGS)) {
                 applicator.applyScrollFlags(appBar, provider)
                 provider.clearInvalidationFlags(StackHeaderInvalidationFlags.SCROLL_FLAGS)
             }
 
-            if (needsRebuild || provider.invalidationFlags.containsAny(StackHeaderInvalidationFlags.LIFT_ON_SCROLL)) {
+            if (needsRebuild || effectiveFlags.containsAny(StackHeaderInvalidationFlags.BACKGROUND_COLORS)) {
+                applicator.applyBackgroundColors(appBar, provider)
+                provider.clearInvalidationFlags(StackHeaderInvalidationFlags.BACKGROUND_COLORS)
+            }
+
+            if (needsRebuild || effectiveFlags.containsAny(StackHeaderInvalidationFlags.LIFT_ON_SCROLL)) {
                 // Lift-on-scroll is disabled in transparent mode: there is no content
                 // scrolling behavior installed and the app bar overlays the content.
                 applicator.applyLiftOnScroll(
@@ -205,44 +215,15 @@ internal class StackHeaderCoordinatorLayout(
                 provider.clearInvalidationFlags(StackHeaderInvalidationFlags.LIFT_ON_SCROLL)
             }
 
-            if (provider.invalidationFlags.containsAny(StackHeaderInvalidationFlags.TOOLBAR_MENU)) {
-                val (forwardIdMap, reverseIdMap) =
-                    StackHeaderToolbarMenuApplicator.generateToolbarMenuItemMappings(
-                        provider.toolbarMenu,
-                    )
-                val forwardGroupIdMap =
-                    StackHeaderToolbarMenuApplicator.generateToolbarMenuGroupMappings(
-                        provider.toolbarMenu,
-                    )
-                val groupMetadata =
-                    StackHeaderToolbarMenuApplicator.computeGroupMetadata(
-                        provider.toolbarMenu,
-                    )
-
-                StackHeaderToolbarMenuApplicator.validateRadioInitialSelection(provider.toolbarMenu)
-
-                selectionController.setMenuMaps(forwardIdMap, groupMetadata)
-
-                StackHeaderToolbarMenuApplicator.rebuildToolbarMenu(
-                    appBar.toolbar,
-                    provider.toolbarMenu,
-                    forwardIdMap,
-                    reverseIdMap,
-                    forwardGroupIdMap,
-                    groupDividerEnabled = provider.toolbarMenuGroupDividerEnabled,
-                    onItemClicked = { id, menuItem ->
-                        if (menuItem.isCheckable) {
-                            selectionController.applyGroupItemStateChange(appBar.toolbar, id)?.let { groupId ->
-                                emitGroupSelection(appBar.toolbar, groupId)
-                            }
-                        } else {
-                            currentDelegate?.onMenuItemClicked(id)
-                        }
-                    },
-                )
-
+            if (needsRebuild || effectiveFlags.containsAny(StackHeaderInvalidationFlags.TOOLBAR_MENU)) {
+                provider.toolbarMenuController.attach(appBar.toolbar)
                 provider.clearInvalidationFlags(StackHeaderInvalidationFlags.TOOLBAR_MENU)
             }
+
+            if (needsRebuild || effectiveFlags.containsAny(StackHeaderInvalidationFlags.OVERFLOW_ICON)) {
+                applicator.applyOverflowIcon(appBar.toolbar, provider)
+                provider.clearInvalidationFlags(StackHeaderInvalidationFlags.OVERFLOW_ICON)
+            }
         }
 
         onMaybeHeaderLayoutChanged()
@@ -250,13 +231,61 @@ internal class StackHeaderCoordinatorLayout(
 
     // endregion
 
-    // region Group selection
+    // region Color scheme
 
-    private fun emitGroupSelection(
-        toolbar: MaterialToolbar,
-        groupId: String,
-    ) {
-        currentDelegate?.onGroupSelectionChanged(groupId, selectionController.collectSelectedIds(toolbar, groupId))
+    private val colorSchemeCoordinator = ColorSchemeCoordinator()
+
+    // Night mode the header visuals were last applied against. Unlike the coordinator's
+    // internal dedupe (reset on every setup()), this survives detach/reattach, skipping
+    // redundant full re-applies e.g. on tab switches.
+    private var appliedUiNightMode: Int =
+        context.resources.configuration.uiMode and Configuration.UI_MODE_NIGHT_MASK
+
+    override fun getResolvedUiNightMode() = colorSchemeCoordinator.getResolvedUiNightMode()
+
+    override fun addColorSchemeListener(listener: ColorSchemeListener) = colorSchemeCoordinator.addColorSchemeListener(listener)
+
+    override fun removeColorSchemeListener(listener: ColorSchemeListener) = colorSchemeCoordinator.removeColorSchemeListener(listener)
+
+    // No onConfigurationChanged override is needed: this view never sets its own colorScheme,
+    // so resolution always delegates to the parent provider, which does handle system changes.
+
+    override fun onAttachedToWindow() {
+        super.onAttachedToWindow()
+        colorSchemeCoordinator.setup(this) { applyUiNightMode(it) }
+    }
+
+    override fun onDetachedFromWindow() {
+        colorSchemeCoordinator.teardown()
+        super.onDetachedFromWindow()
+    }
+
+    private fun applyUiNightMode(uiNightMode: Int) {
+        wrappedContext.setTheme(
+            when (uiNightMode) {
+                Configuration.UI_MODE_NIGHT_YES -> R.style.Theme_Material3Expressive_Dark_NoActionBar
+                Configuration.UI_MODE_NIGHT_NO -> R.style.Theme_Material3Expressive_Light_NoActionBar
+                else -> R.style.Theme_Material3Expressive_DayNight_NoActionBar
+            },
+        )
+
+        if (uiNightMode == appliedUiNightMode) {
+            return
+        }
+
+        appliedUiNightMode = uiNightMode
+        currentProvider?.let {
+            // A rebuild is forced because MaterialToolbar snapshots its theme at construction:
+            // ripples, the overflow popup and menu item views resolve from that frozen copy, so
+            // only view recreation refreshes them.
+            val wasFullyCollapsed = isAppBarFullyCollapsed
+            processUpdate(it, forcedFlags = StackHeaderInvalidationFlags.STRUCTURE)
+            // The rebuilt app bar starts expanded; restore the fully-collapsed resting state
+            // so a scrolled-down screen doesn't jump. Fractional offsets reset.
+            if (wasFullyCollapsed) {
+                appBarLayout?.setExpanded(false, false)
+            }
+        }
     }
 
     // endregion
@@ -269,7 +298,9 @@ internal class StackHeaderCoordinatorLayout(
             removeView(it)
         }
         appBarLayout = null
-        selectionController.clear()
+        // A rebuilt header starts fully expanded; drop any stale collapsed state from the old one.
+        isAppBarFullyCollapsed = false
+        currentProvider?.toolbarMenuController?.detach()
     }
 
     private fun removeHeader() {
@@ -306,6 +337,22 @@ internal class StackHeaderCoordinatorLayout(
 
     // endregion
 
+    // region Instance state
+
+    override fun dispatchSaveInstanceState(container: SparseArray<Parcelable>) {
+        // Do nothing. This view is the root of a fragment-managed, react-owned hierarchy that
+        // React Native keeps alive, so there is no need to serialize/deserialize native view
+        // state. View ids in this subtree are react tags, which are not stable identities -
+        // restoring state by id can apply state saved by one view type to a different one,
+        // crashing e.g. in CompoundButton (see #4523).
+    }
+
+    override fun dispatchRestoreInstanceState(container: SparseArray<Parcelable>) {
+        // Ignore restoring instance state too, as we are not saving anything anyways.
+    }
+
+    // endregion
+
     // region Init
 
     internal var stackScreenWrapper: FrameLayout
@@ -334,6 +381,8 @@ internal class StackHeaderCoordinatorLayout(
     // region Teardown
 
     internal fun tearDown() {
+        colorSchemeCoordinator.teardown()
+
         removeHeader()
 
         stackScreenWrapper.removeView(stackScreen)
@@ -346,8 +395,4 @@ internal class StackHeaderCoordinatorLayout(
     }
 
     // endregion
-
-    companion object {
-        private const val TAG = "StackHeaderCoordinatorLayout"
-    }
 }

package/android/src/main/java/com/swmansion/rnscreens/stack/header/appbar/StackHeaderAppBarLayout.kt

@@ -2,14 +2,20 @@ package com.swmansion.rnscreens.stack.header.appbar
 
 import android.annotation.SuppressLint
 import android.content.Context
+import android.graphics.Color
+import android.graphics.drawable.PaintDrawable
+import android.view.LayoutInflater
 import android.view.ViewGroup.LayoutParams.MATCH_PARENT
 import android.view.ViewGroup.LayoutParams.WRAP_CONTENT
-import androidx.appcompat.widget.AppCompatTextView
+import android.view.WindowInsets
+import android.widget.TextView
 import androidx.coordinatorlayout.widget.CoordinatorLayout
-import com.google.android.material.R
+import androidx.core.view.WindowInsetsCompat
+import androidx.core.view.children
 import com.google.android.material.appbar.AppBarLayout
 import com.google.android.material.appbar.CollapsingToolbarLayout
 import com.google.android.material.appbar.MaterialToolbar
+import com.swmansion.rnscreens.stack.header.config.StackHeaderCollapsedTitleGravityMode
 import com.swmansion.rnscreens.stack.header.config.StackHeaderType
 import com.swmansion.rnscreens.utils.resolveDimensionAttr
 
@@ -18,6 +24,9 @@ internal sealed class StackHeaderAppBarLayout(
 ) : AppBarLayout(context) {
     abstract val toolbar: MaterialToolbar
 
+    internal abstract val defaultContentInsetStart: Int
+    internal abstract val defaultContentInsetEnd: Int
+
     init {
         layoutParams =
             CoordinatorLayout.LayoutParams(MATCH_PARENT, WRAP_CONTENT).apply {
@@ -38,11 +47,66 @@ internal sealed class StackHeaderAppBarLayout(
                 layoutParams = LayoutParams(MATCH_PARENT, WRAP_CONTENT)
             }
 
-        // We need to manually manage the title to handle leading subview's positioning.
-        internal var managedTitleView: AppCompatTextView? = null
+        override val defaultContentInsetStart: Int = toolbar.contentInsetStart
+        override val defaultContentInsetEnd: Int = toolbar.contentInsetEnd
+
+        // Setting text size and typeface separately (Toolbar exposes only a whole text appearance)
+        // needs the title/subtitle TextViews, and Toolbar has no getter for them. Material locates
+        // them by matching the current text (internal ToolbarUtils.getTitleTextView); we attempt
+        // the same, but since we don't have current text, we use distinct placeholders - they force
+        // both views into existence and tell them apart — and clear the text only after capturing
+        // the references. Toolbar keeps both instances for its lifetime (empty text only detaches
+        // them), so the references stay valid.
+        internal val titleTextView: TextView
+        internal val subtitleTextView: TextView
+
+        // Keeps the status bar strip in sync with the bar's effective color through
+        // the lift animation (same per-frame mixed color Material applies to the
+        // background). Detached when an explicit statusBarScrimColor is set.
+        private var statusBarScrimSyncEnabled = false
+        private val statusBarScrimSync =
+            object : LiftOnScrollProgressListener() {
+                override fun onUpdate(
+                    elevation: Float,
+                    backgroundColor: Int,
+                    progress: Float,
+                ) {
+                    statusBarForeground?.setTint(backgroundColor)
+                }
+            }
 
         init {
             addView(toolbar)
+
+            // PaintDrawable is not color-extractable, so AppBarLayout's built-in
+            // colorSurface-keyed strip tint sync can never activate and fight the
+            // listener above (or an explicit scrim color) — regardless of theme.
+            statusBarForeground = PaintDrawable().apply { setTint(Color.TRANSPARENT) }
+
+            toolbar.title = TITLE_PLACEHOLDER
+            toolbar.subtitle = SUBTITLE_PLACEHOLDER
+            titleTextView = toolbar.findTextViewWithText(TITLE_PLACEHOLDER)
+            subtitleTextView = toolbar.findTextViewWithText(SUBTITLE_PLACEHOLDER)
+            toolbar.title = ""
+            toolbar.subtitle = ""
+        }
+
+        internal fun setStatusBarScrimSyncEnabled(enabled: Boolean) {
+            if (statusBarScrimSyncEnabled == enabled) return
+            statusBarScrimSyncEnabled = enabled
+            if (enabled) {
+                addLiftOnScrollProgressListener(statusBarScrimSync)
+            } else {
+                removeLiftOnScrollProgressListener(statusBarScrimSync)
+            }
+        }
+
+        private fun MaterialToolbar.findTextViewWithText(text: String): TextView =
+            children.filterIsInstance<TextView>().first { it.text?.toString() == text }
+
+        private companion object {
+            private const val TITLE_PLACEHOLDER = "rns_title"
+            private const val SUBTITLE_PLACEHOLDER = "rns_subtitle"
         }
     }
 
@@ -50,6 +114,7 @@ internal sealed class StackHeaderAppBarLayout(
     internal class Collapsing(
         context: Context,
         val type: StackHeaderType,
+        collapsedTitleGravityMode: StackHeaderCollapsedTitleGravityMode,
     ) : StackHeaderAppBarLayout(context) {
         override val toolbar =
             MaterialToolbar(context).apply {
@@ -64,25 +129,21 @@ internal sealed class StackHeaderAppBarLayout(
                         }
             }
 
+        override val defaultContentInsetStart: Int = toolbar.contentInsetStart
+        override val defaultContentInsetEnd: Int = toolbar.contentInsetEnd
+
+        // collapsedTitleGravityMode is a construction-time-only attr (no public setter), so both
+        // gravity modes are inflated from XML — differing only in that attribute — to stay 1:1.
         internal val collapsingToolbarLayout: CollapsingToolbarLayout =
-            run {
-                val (styleAttr, sizeAttr) =
-                    when (type) {
-                        StackHeaderType.MEDIUM ->
-                            Pair(R.attr.collapsingToolbarLayoutMediumStyle, R.attr.collapsingToolbarLayoutMediumSize)
-                        StackHeaderType.LARGE ->
-                            Pair(R.attr.collapsingToolbarLayoutLargeStyle, R.attr.collapsingToolbarLayoutLargeSize)
-                        else -> error("[RNScreens] Invalid header mode.")
-                    }
-                CollapsingToolbarLayout(context, null, styleAttr).apply {
-                    layoutParams =
-                        LayoutParams(
-                            MATCH_PARENT,
-                            resolveDimensionAttr(context, sizeAttr),
-                        )
-                    addView(toolbar)
-                }
-            }
+            (
+                LayoutInflater
+                    .from(context)
+                    .inflate(layoutResFor(type, collapsedTitleGravityMode), this, false)
+                    as CollapsingToolbarLayout
+            ).apply { addView(toolbar) }
+
+        private var trackedTopInset = 0
+        private var currentVerticalOffset = 0
 
         init {
             require(
@@ -92,6 +153,75 @@ internal sealed class StackHeaderAppBarLayout(
                 "[RNScreens] Collapsing StackHeaderAppBarLayout must be MEDIUM or LARGE type."
             }
             addView(collapsingToolbarLayout)
+
+            addOnOffsetChangedListener { _, verticalOffset ->
+                currentVerticalOffset = verticalOffset
+                updateContentScrimExclusion()
+            }
+        }
+
+        // Observed here because both AppBarLayout and CollapsingToolbarLayout
+        // install their own OnApplyWindowInsetsListener in their constructors —
+        // setting ours would silently replace Material's. Reads the same inset
+        // CTL uses for its status bar scrim bounds.
+        override fun dispatchApplyWindowInsets(insets: WindowInsets): WindowInsets {
+            @Suppress("DEPRECATION")
+            trackedTopInset =
+                if (fitsSystemWindows) {
+                    WindowInsetsCompat.toWindowInsetsCompat(insets, this).systemWindowInsetTop
+                } else {
+                    0
+                }
+            updateContentScrimExclusion()
+            return super.dispatchApplyWindowInsets(insets)
+        }
+
+        /**
+         * While a status bar scrim is installed, the content scrim skips the
+         * status-bar strip that the status bar scrim paints alone. Otherwise,
+         * the two scrims stack there while fading (they share the same partial
+         * alpha), showing a darker band during the transition. The strip spans
+         * `[-verticalOffset, -verticalOffset + topInset]` in CTL coordinates,
+         * matching the status bar scrim bounds set in
+         * `CollapsingToolbarLayout.draw`.
+         */
+        internal fun updateContentScrimExclusion() {
+            val contentScrim =
+                collapsingToolbarLayout.contentScrim
+            check(contentScrim is StackHeaderContentScrimDrawable) {
+                "[RNScreens] Unexpected contentScrim class."
+            }
+
+            contentScrim.exclusionBottom =
+                if (collapsingToolbarLayout.statusBarScrim != null && trackedTopInset > 0) {
+                    trackedTopInset - currentVerticalOffset
+                } else {
+                    0
+                }
+        }
+
+        private companion object {
+            fun layoutResFor(
+                type: StackHeaderType,
+                mode: StackHeaderCollapsedTitleGravityMode,
+            ): Int =
+                when (type) {
+                    StackHeaderType.MEDIUM ->
+                        when (mode) {
+                            StackHeaderCollapsedTitleGravityMode.ENTIRE_SPACE ->
+                                com.swmansion.rnscreens.R.layout.rns_collapsing_toolbar_medium_entire_space
+                            StackHeaderCollapsedTitleGravityMode.AVAILABLE_SPACE ->
+                                com.swmansion.rnscreens.R.layout.rns_collapsing_toolbar_medium_available_space
+                        }
+                    StackHeaderType.LARGE ->
+                        when (mode) {
+                            StackHeaderCollapsedTitleGravityMode.ENTIRE_SPACE ->
+                                com.swmansion.rnscreens.R.layout.rns_collapsing_toolbar_large_entire_space
+                            StackHeaderCollapsedTitleGravityMode.AVAILABLE_SPACE ->
+                                com.swmansion.rnscreens.R.layout.rns_collapsing_toolbar_large_available_space
+                        }
+                    else -> error("[RNScreens] Invalid header mode.")
+                }
         }
     }
 
@@ -99,10 +229,12 @@ internal sealed class StackHeaderAppBarLayout(
         fun create(
             context: Context,
             type: StackHeaderType,
+            collapsedTitleGravityMode: StackHeaderCollapsedTitleGravityMode,
         ): StackHeaderAppBarLayout =
             when (type) {
                 StackHeaderType.SMALL -> Small(context)
-                StackHeaderType.MEDIUM, StackHeaderType.LARGE -> Collapsing(context, type)
+                StackHeaderType.MEDIUM, StackHeaderType.LARGE ->
+                    Collapsing(context, type, collapsedTitleGravityMode)
             }
     }
 }

package/android/src/main/java/com/swmansion/rnscreens/stack/header/appbar/StackHeaderContentScrimDrawable.kt

@@ -0,0 +1,36 @@
+package com.swmansion.rnscreens.stack.header.appbar
+
+import android.graphics.Canvas
+import android.graphics.drawable.ColorDrawable
+import androidx.core.graphics.withClip
+
+/**
+ * Content scrim that can skip the status-bar strip painted by the
+ * CollapsingToolbarLayout status bar scrim. Both scrims share the same alpha
+ * while fading, so wherever they overlap the strip composites darker than the
+ * rest of the scrim during the transition.
+ */
+internal class StackHeaderContentScrimDrawable(
+    color: Int,
+) : ColorDrawable(color) {
+    // Bottom of the skipped band in CollapsingToolbarLayout coordinates; the
+    // visible top edge of the scrim always aligns with the strip top. Values
+    // <= bounds.top disable the exclusion.
+    internal var exclusionBottom: Int = 0
+        set(value) {
+            if (field != value) {
+                field = value
+                invalidateSelf()
+            }
+        }
+
+    override fun draw(canvas: Canvas) {
+        if (exclusionBottom <= bounds.top) {
+            super.draw(canvas)
+            return
+        }
+        canvas.withClip(bounds.left, exclusionBottom, bounds.right, bounds.bottom) {
+            super.draw(canvas)
+        }
+    }
+}

package/android/src/main/java/com/swmansion/rnscreens/stack/header/config/StackHeaderCollapsedTitleGravityMode.kt

@@ -0,0 +1,6 @@
+package com.swmansion.rnscreens.stack.header.config
+
+internal enum class StackHeaderCollapsedTitleGravityMode {
+    ENTIRE_SPACE,
+    AVAILABLE_SPACE,
+}