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

package/android/src/main/java/com/swmansion/rnscreens/stack/header/toolbar/model/StackHeaderToolbarMenuItemConfig.kt

@@ -1,7 +1,5 @@
 package com.swmansion.rnscreens.stack.header.toolbar.model
 
-import android.graphics.drawable.Drawable
-
 internal data class StackHeaderToolbarMenuItemConfig(
     val id: String,
     val title: String?,
@@ -11,11 +9,11 @@ internal data class StackHeaderToolbarMenuItemConfig(
     val hidden: Boolean,
     val disabled: Boolean,
     val showAsAction: StackHeaderToolbarMenuItemShowAsAction,
-    val icon: Drawable?,
     val iconTintColorNormal: Int?,
     val iconTintColorPressed: Int?,
     val iconTintColorFocused: Int?,
     val iconTintColorDisabled: Int?,
+    val iconSource: StackHeaderToolbarMenuItemIconSource,
     val groupId: String?,
     val itemType: StackHeaderToolbarMenuItemType,
     val initialToggleState: Boolean,

package/android/src/main/java/com/swmansion/rnscreens/stack/header/toolbar/model/StackHeaderToolbarMenuModel.kt

@@ -0,0 +1,180 @@
+package com.swmansion.rnscreens.stack.header.toolbar.model
+
+/**
+ * Immutable snapshot of a parsed toolbar menu: the config tree plus every
+ * derived index the runtime needs. Built and validated in one step by [from],
+ * so a successfully constructed model is always internally consistent.
+ */
+internal class StackHeaderToolbarMenuModel private constructor(
+    val config: StackHeaderToolbarMenuConfig,
+    val elementById: Map<String, StackHeaderToolbarMenuElementConfig>,
+    // Element string id <-> int id expected by Android menus.
+    val forwardIdMap: Map<String, Int>,
+    val reverseIdMap: Map<Int, String>,
+    val forwardGroupIdMap: Map<String, Int>,
+    val groupMetadata: StackHeaderToolbarMenuGroupMetadata,
+) {
+    companion object {
+        val EMPTY = from(StackHeaderToolbarMenuConfig(emptyList(), emptyList()))
+
+        /** Derives all indices and validates [config]; throws on an invalid menu. */
+        fun from(config: StackHeaderToolbarMenuConfig): StackHeaderToolbarMenuModel {
+            val forwardIdMap = mutableMapOf<String, Int>()
+            val reverseIdMap = mutableMapOf<Int, String>()
+            var elementCounter = 1
+            assignElementIds(config.children, forwardIdMap, reverseIdMap) { elementCounter++ }
+
+            val forwardGroupIdMap = mutableMapOf<String, Int>()
+            var groupCounter = 1
+            assignGroupIds(config, forwardGroupIdMap) { groupCounter++ }
+
+            val itemGroupMap = mutableMapOf<String, String>()
+            val groupSingleSelection = mutableMapOf<String, Boolean>()
+            val groupMemberItems = mutableMapOf<String, MutableList<String>>()
+            collectGroupMetadata(config, itemGroupMap, groupSingleSelection, groupMemberItems)
+
+            validateRadioInitialSelection(config)
+            validateItemTypes(config)
+
+            val elementById = mutableMapOf<String, StackHeaderToolbarMenuElementConfig>()
+            collectElements(config, elementById)
+
+            return StackHeaderToolbarMenuModel(
+                config = config,
+                elementById = elementById.toMap(),
+                forwardIdMap = forwardIdMap.toMap(),
+                reverseIdMap = reverseIdMap.toMap(),
+                forwardGroupIdMap = forwardGroupIdMap.toMap(),
+                groupMetadata =
+                    StackHeaderToolbarMenuGroupMetadata(
+                        itemGroupMap.toMap(),
+                        groupSingleSelection.toMap(),
+                        groupMemberItems.mapValues { it.value.toList() },
+                    ),
+            )
+        }
+    }
+}
+
+private fun assignElementIds(
+    elements: List<StackHeaderToolbarMenuElementConfig>,
+    forwardIdMap: MutableMap<String, Int>,
+    reverseIdMap: MutableMap<Int, String>,
+    nextId: () -> Int,
+) {
+    for (element in elements) {
+        require(element.item.id !in forwardIdMap) {
+            "[RNScreens] Duplicate toolbar menu item id: '${element.item.id}'. Item IDs must be unique across the entire menu."
+        }
+        val nativeId = nextId()
+        forwardIdMap[element.item.id] = nativeId
+        reverseIdMap[nativeId] = element.item.id
+        if (element is StackHeaderToolbarMenuElementConfig.Submenu) {
+            assignElementIds(element.menu.children, forwardIdMap, reverseIdMap, nextId)
+        }
+    }
+}
+
+private fun assignGroupIds(
+    menuConfig: StackHeaderToolbarMenuConfig,
+    forwardMap: MutableMap<String, Int>,
+    nextId: () -> Int,
+) {
+    for (group in menuConfig.groups) {
+        require(group.groupId !in forwardMap) {
+            "[RNScreens] Duplicate toolbar menu group id: '${group.groupId}'. Group IDs must be unique across the entire menu."
+        }
+        forwardMap[group.groupId] = nextId()
+    }
+    for (element in menuConfig.children) {
+        if (element is StackHeaderToolbarMenuElementConfig.Submenu) {
+            assignGroupIds(element.menu, forwardMap, nextId)
+        }
+    }
+}
+
+private fun collectGroupMetadata(
+    config: StackHeaderToolbarMenuConfig,
+    itemGroupMap: MutableMap<String, String>,
+    groupSingleSelection: MutableMap<String, Boolean>,
+    groupMemberItems: MutableMap<String, MutableList<String>>,
+) {
+    val localGroupIds = config.groups.map { it.groupId }.toSet()
+    for (group in config.groups) {
+        groupSingleSelection[group.groupId] = group.singleSelection
+        groupMemberItems.getOrPut(group.groupId) { mutableListOf() }
+    }
+    for (element in config.children) {
+        element.item.groupId?.let { gid ->
+            require(element is StackHeaderToolbarMenuElementConfig.MenuItem) {
+                "[RNScreens] Submenu '${element.item.id}' cannot belong to a group. " +
+                    "Only elements of type 'menuItem' can have a groupId."
+            }
+            require(gid in localGroupIds) {
+                "[RNScreens] Menu item '${element.item.id}' references group '$gid' " +
+                    "which is not defined at the same menu level. " +
+                    "Groups cannot span submenus."
+            }
+            itemGroupMap[element.item.id] = gid
+            groupMemberItems[gid]!!.add(element.item.id)
+        }
+        if (element is StackHeaderToolbarMenuElementConfig.Submenu) {
+            collectGroupMetadata(element.menu, itemGroupMap, groupSingleSelection, groupMemberItems)
+        }
+    }
+}
+
+private fun validateRadioInitialSelection(menuConfig: StackHeaderToolbarMenuConfig) {
+    for (group in menuConfig.groups) {
+        if (!group.singleSelection) continue
+        var count = 0
+        for (element in menuConfig.children) {
+            if (element.item.groupId == group.groupId && element.item.initialToggleState) {
+                count++
+            }
+        }
+        require(count <= 1) {
+            "[RNScreens] Radio group '${group.groupId}' has $count items with " +
+                "initialToggleState=true. At most 1 is allowed for single-selection groups."
+        }
+    }
+    for (element in menuConfig.children) {
+        if (element is StackHeaderToolbarMenuElementConfig.Submenu) {
+            validateRadioInitialSelection(element.menu)
+        }
+    }
+}
+
+private fun validateItemTypes(menuConfig: StackHeaderToolbarMenuConfig) {
+    for (element in menuConfig.children) {
+        val item = element.item
+        when (item.itemType) {
+            StackHeaderToolbarMenuItemType.TOGGLE ->
+                require(item.groupId != null) {
+                    "[RNScreens] Menu item '${item.id}' has itemType=TOGGLE but no groupId. " +
+                        "Toggle items must belong to a group."
+                }
+            StackHeaderToolbarMenuItemType.ACTION ->
+                require(item.groupId == null) {
+                    "[RNScreens] Menu item '${item.id}' has itemType=ACTION " +
+                        "and belongs to a group. Action items cannot belong to groups."
+                }
+            StackHeaderToolbarMenuItemType.AUTOMATIC -> Unit
+        }
+        if (element is StackHeaderToolbarMenuElementConfig.Submenu) {
+            validateItemTypes(element.menu)
+        }
+    }
+}
+
+private fun collectElements(
+    config: StackHeaderToolbarMenuConfig,
+    elements: MutableMap<String, StackHeaderToolbarMenuElementConfig>,
+) {
+    for (element in config.children) {
+        elements[element.item.id] = element
+        if (element is StackHeaderToolbarMenuElementConfig.Submenu) {
+            collectElements(element.menu, elements)
+        }
+    }
+}

package/android/src/main/java/com/swmansion/rnscreens/stack/header/toolbar/update/StackHeaderToolbarMenuElementOptions.kt

@@ -1,6 +1,7 @@
 package com.swmansion.rnscreens.stack.header.toolbar.update
 
 import android.graphics.drawable.Drawable
+import com.swmansion.rnscreens.stack.header.toolbar.model.StackHeaderToolbarMenuElementConfig
 import com.swmansion.rnscreens.stack.header.toolbar.model.StackHeaderToolbarMenuItemShowAsAction
 
 /**
@@ -16,12 +17,11 @@ internal data class StackHeaderToolbarMenuElementOptions(
     val hidden: Boolean? = null,
     val disabled: Boolean? = null,
     val showAsAction: StackHeaderToolbarMenuItemShowAsAction? = null,
-    val icon: StackHeaderToolbarFieldUpdate<Drawable>?,
-    val iconTintColorNormal: StackHeaderToolbarFieldUpdate<Int>?,
-    val iconTintColorPressed: StackHeaderToolbarFieldUpdate<Int>?,
-    val iconTintColorFocused: StackHeaderToolbarFieldUpdate<Int>?,
-    val iconTintColorDisabled: StackHeaderToolbarFieldUpdate<Int>?,
-    val checked: Boolean? = null,
+    val icon: StackHeaderToolbarFieldUpdate<Drawable>? = null,
+    val iconTintColorNormal: StackHeaderToolbarFieldUpdate<Int>? = null,
+    val iconTintColorPressed: StackHeaderToolbarFieldUpdate<Int>? = null,
+    val iconTintColorFocused: StackHeaderToolbarFieldUpdate<Int>? = null,
+    val iconTintColorDisabled: StackHeaderToolbarFieldUpdate<Int>? = null,
     val menuTitle: StackHeaderToolbarFieldUpdate<String>? = null,
 ) {
     val requiresIconTintColorUpdate: Boolean
@@ -30,4 +30,55 @@ internal data class StackHeaderToolbarMenuElementOptions(
                 iconTintColorPressed != null ||
                 iconTintColorFocused != null ||
                 iconTintColorDisabled != null
+
+    val isEmpty: Boolean
+        get() = this == DEFAULT
+
+    /** Field-wise merge where [newer]'s non-null fields win. */
+    internal fun mergedWith(newer: StackHeaderToolbarMenuElementOptions) =
+        StackHeaderToolbarMenuElementOptions(
+            title = newer.title ?: title,
+            titleCondensed = newer.titleCondensed ?: titleCondensed,
+            tooltipText = newer.tooltipText ?: tooltipText,
+            accessibilityLabel = newer.accessibilityLabel ?: accessibilityLabel,
+            hidden = newer.hidden ?: hidden,
+            disabled = newer.disabled ?: disabled,
+            showAsAction = newer.showAsAction ?: showAsAction,
+            icon = newer.icon ?: icon,
+            iconTintColorNormal = newer.iconTintColorNormal ?: iconTintColorNormal,
+            iconTintColorPressed = newer.iconTintColorPressed ?: iconTintColorPressed,
+            iconTintColorFocused = newer.iconTintColorFocused ?: iconTintColorFocused,
+            iconTintColorDisabled = newer.iconTintColorDisabled ?: iconTintColorDisabled,
+            menuTitle = newer.menuTitle ?: menuTitle,
+        )
+
+    private companion object {
+        val DEFAULT = StackHeaderToolbarMenuElementOptions()
+    }
 }
+
+/**
+ * The element's declared configuration as absolute options — every field is
+ * Set/Reset, never "leave unchanged". The icon slot is always Reset: parsed
+ * configs carry no Drawables; resolved icons overlay this at application time.
+ * [StackHeaderToolbarMenuElementOptions.menuTitle] stays "unchanged" for a
+ * plain item, which has no submenu header to write.
+ */
+internal fun StackHeaderToolbarMenuElementConfig.toOptions() =
+    StackHeaderToolbarMenuElementOptions(
+        title = StackHeaderToolbarFieldUpdate.from(item.title),
+        titleCondensed = StackHeaderToolbarFieldUpdate.from(item.titleCondensed),
+        tooltipText = StackHeaderToolbarFieldUpdate.from(item.tooltipText),
+        accessibilityLabel = StackHeaderToolbarFieldUpdate.from(item.accessibilityLabel),
+        hidden = item.hidden,
+        disabled = item.disabled,
+        showAsAction = item.showAsAction,
+        icon = StackHeaderToolbarFieldUpdate.Reset,
+        iconTintColorNormal = StackHeaderToolbarFieldUpdate.from(item.iconTintColorNormal),
+        iconTintColorPressed = StackHeaderToolbarFieldUpdate.from(item.iconTintColorPressed),
+        iconTintColorFocused = StackHeaderToolbarFieldUpdate.from(item.iconTintColorFocused),
+        iconTintColorDisabled = StackHeaderToolbarFieldUpdate.from(item.iconTintColorDisabled),
+        menuTitle =
+            (this as? StackHeaderToolbarMenuElementConfig.Submenu)
+                ?.let { StackHeaderToolbarFieldUpdate.from(it.menuTitle) },
+    )

package/android/src/main/java/com/swmansion/rnscreens/stack/header/toolbar/update/StackHeaderToolbarMenuElementRawUpdate.kt

@@ -4,10 +4,12 @@ import com.swmansion.rnscreens.stack.header.toolbar.model.StackHeaderToolbarMenu
 
 /**
  * A single toolbar menu element update carried by an `updateToolbarMenuElements`
- * view command, before its icon (if any) has been resolved.
+ * view command, before its icon (if any) has been resolved. `checked` travels
+ * outside [options]: it mutates group selections rather than the item itself.
  */
 internal data class StackHeaderToolbarMenuElementRawUpdate(
     val id: String,
     val options: StackHeaderToolbarMenuElementOptions,
     val iconSource: StackHeaderToolbarMenuItemIconSource?,
+    val checked: Boolean?,
 )

package/android/src/main/java/com/swmansion/rnscreens/stack/header/toolbar/update/StackHeaderToolbarMenuElementUpdate.kt

@@ -7,4 +7,5 @@ package com.swmansion.rnscreens.stack.header.toolbar.update
 internal data class StackHeaderToolbarMenuElementUpdate(
     val id: String,
     val options: StackHeaderToolbarMenuElementOptions,
+    val checked: Boolean?,
 )

package/android/src/main/java/com/swmansion/rnscreens/stack/header/toolbar/update/StackHeaderToolbarMenuIconResolver.kt

@@ -4,14 +4,15 @@ import android.graphics.drawable.Drawable
 import com.swmansion.rnscreens.stack.header.toolbar.model.StackHeaderToolbarMenuItemIconSource
 
 /**
- * Resolves the icon for a single menu element update.
+ * Loads the icon a menu element's source points at.
  *
  * [onResolved] must be invoked exactly once — synchronously or asynchronously, always on the
- * main thread — with the resolved icon to merge into the element's options.
+ * main thread — with the loaded drawable, or `null` when the source resolves to no icon or
+ * fails to load.
  */
 internal fun interface StackHeaderToolbarMenuIconResolver {
     fun resolve(
         iconSource: StackHeaderToolbarMenuItemIconSource,
-        onResolved: (icon: StackHeaderToolbarFieldUpdate<Drawable>) -> Unit,
+        onResolved: (icon: Drawable?) -> Unit,
     )
 }

package/android/src/main/java/com/swmansion/rnscreens/stack/header/toolbar/update/StackHeaderToolbarMenuUpdateQueue.kt

@@ -23,6 +23,7 @@ internal class StackHeaderToolbarMenuUpdateQueue(
     private val pendingBatches = ArrayDeque<List<StackHeaderToolbarMenuElementRawUpdate>>()
     private var isProcessing = false
     private var isTornDown = false
+    private var generation = 0
 
     internal fun enqueue(batch: List<StackHeaderToolbarMenuElementRawUpdate>) {
         if (batch.isEmpty()) {
@@ -34,6 +35,18 @@ internal class StackHeaderToolbarMenuUpdateQueue(
         }
     }
 
+    /**
+     * Drops every batch that has not been applied yet, including one whose
+     * icons are still resolving — its eventual dispatch becomes a no-op. Used
+     * when the menu configuration is replaced: commands sent against the old
+     * menu must never touch the new one. The queue stays usable.
+     */
+    internal fun clearPending() {
+        pendingBatches.clear()
+        generation++
+        isProcessing = false
+    }
+
     internal fun tearDown() {
         pendingBatches.clear()
         isTornDown = true
@@ -48,11 +61,12 @@ internal class StackHeaderToolbarMenuUpdateQueue(
                 return
             }
             isProcessing = true
+            val batchGeneration = generation
 
             val updates = arrayOfNulls<StackHeaderToolbarMenuElementUpdate>(batch.size)
             var outstanding = batch.size
 
-            var isProcessingBatch = true
+            var inSyncDispatchLoop = true
 
             fun dispatchResolvedBatch() {
                 pendingBatches.removeFirst()
@@ -63,20 +77,20 @@ internal class StackHeaderToolbarMenuUpdateQueue(
                 index: Int,
                 options: StackHeaderToolbarMenuElementOptions,
             ) {
-                check(updates[index] == null) {
-                    "[RNScreens] Unexpected duplicated element resolution."
+                if (isTornDown || batchGeneration != generation) {
+                    return
                 }
 
-                if (isTornDown) {
-                    return
+                check(updates[index] == null) {
+                    "[RNScreens] Unexpected duplicated element resolution."
                 }
 
-                updates[index] = StackHeaderToolbarMenuElementUpdate(batch[index].id, options)
+                updates[index] = StackHeaderToolbarMenuElementUpdate(batch[index].id, options, batch[index].checked)
                 outstanding -= 1
 
                 // A synchronous completion is applied by the loop below; only an asynchronous one
                 // advances the queue processing from here.
-                if (outstanding == 0 && !isProcessingBatch) {
+                if (outstanding == 0 && !inSyncDispatchLoop) {
                     dispatchResolvedBatch()
                     processNext()
                 }
@@ -88,11 +102,11 @@ internal class StackHeaderToolbarMenuUpdateQueue(
                     onElementResolved(index, update.options)
                 } else {
                     iconResolver.resolve(iconSource) { icon ->
-                        onElementResolved(index, update.options.copy(icon = icon))
+                        onElementResolved(index, update.options.copy(icon = StackHeaderToolbarFieldUpdate.from(icon)))
                     }
                 }
             }
-            isProcessingBatch = false
+            inSyncDispatchLoop = false
 
             if (outstanding > 0) {
                 // An icon is still loading asynchronously; its callback will apply the batch

package/android/src/main/java/com/swmansion/rnscreens/stack/host/StackContainer.kt

@@ -2,18 +2,26 @@ package com.swmansion.rnscreens.stack.host
 
 import android.annotation.SuppressLint
 import android.content.Context
+import android.content.res.Configuration
 import android.util.Log
 import android.view.ViewGroup
 import android.widget.FrameLayout
 import androidx.fragment.app.Fragment
 import androidx.fragment.app.FragmentManager
+import com.swmansion.rnscreens.common.colorscheme.ColorScheme
+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.common.container.Container
+import com.swmansion.rnscreens.common.container.ContainerItem
 import com.swmansion.rnscreens.common.container.ParentContainerItemRegistry
 import com.swmansion.rnscreens.ext.isMeasured
 import com.swmansion.rnscreens.helpers.FragmentManagerHelper
 import com.swmansion.rnscreens.helpers.ViewIdGenerator
+import com.swmansion.rnscreens.stack.header.StackHeaderBackPressHandler
 import com.swmansion.rnscreens.stack.screen.StackScreen
 import com.swmansion.rnscreens.stack.screen.StackScreenFragment
+import com.swmansion.rnscreens.stack.screen.StackScreenFragmentDelegate
 import com.swmansion.rnscreens.utils.RNSLog
 import java.lang.ref.WeakReference
 
@@ -23,7 +31,10 @@ internal class StackContainer(
     private val delegate: WeakReference<StackContainerDelegate>,
 ) : FrameLayout(context),
     Container,
-    FragmentManager.OnBackStackChangedListener {
+    FragmentManager.OnBackStackChangedListener,
+    ColorSchemeProviding,
+    StackHeaderBackPressHandler,
+    StackScreenFragmentDelegate {
     private var fragmentManager: FragmentManager? = null
 
     private fun requireFragmentManager(): FragmentManager =
@@ -51,6 +62,20 @@ internal class StackContainer(
     private val fragmentOpExecutor: FragmentOperationExecutor = FragmentOperationExecutor()
     private val fragmentOps: MutableList<FragmentOperation> = arrayListOf()
 
+    // region Color Scheme
+
+    private val colorSchemeCoordinator = ColorSchemeCoordinator()
+
+    internal var colorScheme: ColorScheme by colorSchemeCoordinator::colorScheme
+
+    override fun getResolvedUiNightMode() = colorSchemeCoordinator.getResolvedUiNightMode()
+
+    override fun addColorSchemeListener(listener: ColorSchemeListener) = colorSchemeCoordinator.addColorSchemeListener(listener)
+
+    override fun removeColorSchemeListener(listener: ColorSchemeListener) = colorSchemeCoordinator.removeColorSchemeListener(listener)
+
+    // endregion
+
     init {
         id = ViewIdGenerator.generateViewId()
     }
@@ -62,6 +87,10 @@ internal class StackContainer(
         parentContainerRegistry.attach(this)
         setupFragmentManger()
 
+        // StackContainer only provides container-level color scheme configuration for its screens
+        // but doesn't use any color scheme-dependent views, so we don't need the callback.
+        colorSchemeCoordinator.setup(this, null)
+
         // Following line works with a couple of assumptions.
         // First, that this view is laid out by our parent view, which is a component view.
         // Component views on new architecture receive their first layout after the view hierarchy is
@@ -81,8 +110,16 @@ internal class StackContainer(
         requireFragmentManager().removeOnBackStackChangedListener(this)
         fragmentManager = null
         parentContainerRegistry.detach(this)
+        colorSchemeCoordinator.teardown()
+    }
+
+    override fun onConfigurationChanged(newConfig: Configuration?) {
+        super.onConfigurationChanged(newConfig)
+        colorSchemeCoordinator.onConfigurationChanged(newConfig)
     }
 
+    override fun onFragmentConfigurationChanged(config: Configuration) = onConfigurationChanged(config)
+
     internal fun setupFragmentManger() {
         fragmentManager =
             checkNotNull(FragmentManagerHelper.findFragmentManagerForView(this)) {
@@ -164,7 +201,8 @@ internal class StackContainer(
         }
 
         pendingPushOperations.forEach { operation ->
-            val newFragment = createFragmentForScreen(operation.screen, canNavigateBack = stackModel.isNotEmpty())
+            val newFragment =
+                createFragmentForScreen(operation.screen, canNavigateBack = stackModel.isNotEmpty())
 
             fragmentOps.add(
                 AddAndSetAsPrimaryOp(
@@ -205,7 +243,12 @@ internal class StackContainer(
         screen: StackScreen,
         canNavigateBack: Boolean,
     ): StackScreenFragment =
-        StackScreenFragment(screen, canNavigateBack).also {
+        StackScreenFragment(
+            screen,
+            canNavigateBack,
+            WeakReference(this),
+            backPressHandler = WeakReference(this),
+        ).also {
             Log.d(TAG, "Created Fragment $it for screen ${screen.screenKey}")
         }
 
@@ -290,6 +333,63 @@ internal class StackContainer(
             ?.stackScreen
             ?.findContentScrollView()
 
+    // Asked when this container's whole subtree is about to be dismissed (the screen
+    // hosting this container is popped) - every item gets a vote, back-to-front, so
+    // the deepest preventing screen wins.
+    override fun wantsToPreventStackNativeDismiss(): ContainerItem? =
+        stackModel
+            .asReversed()
+            .firstNotNullOfOrNull { it.stackScreen.wantsToPreventStackNativeDismiss() }
+
+    // endregion
+
+    // region Header back button
+
+    override fun handleHeaderBackButtonPress(pressedScreen: StackScreen) {
+        val fragmentManager = fragmentManager
+        if (fragmentManager == null) {
+            Log.w(TAG, "[RNScreens] Ignoring header back button press - container is detached")
+            return
+        }
+
+        val topScreen = stackModel.lastOrNull()?.stackScreen
+        if (topScreen !== pressedScreen || stackModel.size <= 1) {
+            Log.w(
+                TAG,
+                "[RNScreens] Ignoring header back button press for non-top screen ${pressedScreen.screenKey}",
+            )
+            return
+        }
+
+        // This pop dismisses only the top screen (together with its subtree), therefore
+        // only the top item is asked - screens below the top get no vote at this level.
+        val vetoingItem = topScreen.wantsToPreventStackNativeDismiss()
+        if (vetoingItem != null) {
+            // Only a StackScreen can veto - TabsScreen has no own flag and only forwards.
+            val vetoingScreen = vetoingItem as? StackScreen
+            if (vetoingScreen != null) {
+                vetoingScreen.onNativeDismissPrevented()
+            } else {
+                Log.w(
+                    TAG,
+                    "[RNScreens] Unexpected vetoing item type: ${vetoingItem.javaClass.simpleName}",
+                )
+            }
+            return
+        }
+
+        // Mirrors FragmentManager's internal OnBackPressedCallback, which also runs
+        // popBackStackImmediate. The synchronous pop makes the top-screen guard above
+        // reliable against double taps: onBackStackChangeCommitted -> onNativeFragmentPop
+        // updates stackModel before this call returns.
+        fragmentManager.popBackStackImmediate(
+            // key MUST BE present, otherwise the navigation action will be delegated to child primary navigation
+            // fragment.
+            checkNotNull(pressedScreen.screenKey) { "[RNScreens] Screen key is required" },
+            FragmentManager.POP_BACK_STACK_INCLUSIVE,
+        )
+    }
+
     // endregion
 
     companion object {

package/android/src/main/java/com/swmansion/rnscreens/stack/host/StackHost.kt

@@ -8,6 +8,7 @@ import com.facebook.react.bridge.UIManagerListener
 import com.facebook.react.common.annotations.UnstableReactNativeAPI
 import com.facebook.react.uimanager.ThemedReactContext
 import com.facebook.react.uimanager.UIManagerHelper
+import com.swmansion.rnscreens.common.colorscheme.ColorScheme
 import com.swmansion.rnscreens.helpers.getFabricUIManagerNotNull
 import com.swmansion.rnscreens.stack.screen.StackScreen
 import com.swmansion.rnscreens.utils.RNSLog
@@ -26,6 +27,8 @@ class StackHost(
     private val containerUpdateCoordinator = StackContainerUpdateCoordinator()
     private var isLayoutEnqueued = false
 
+    internal var colorScheme: ColorScheme by container::colorScheme
+
     init {
         addView(container)
 
@@ -119,6 +122,16 @@ class StackHost(
         refreshLayout()
     }
 
+    // On window configuration changes ViewRootImpl calls forceLayout() recursively on every view
+    // in the hierarchy, bypassing requestLayout(). React views never lay out their children during
+    // framework traversals, so nothing would clear the force-layout flags in our subtree — and once
+    // they are set, any subsequent requestLayout() from a descendant short-circuits before reaching
+    // the override above, permanently disabling the manual pass. Schedule it from here as well.
+    override fun forceLayout() {
+        super.forceLayout()
+        refreshLayout()
+    }
+
     private fun refreshLayout() {
         if (!isLayoutEnqueued) {
             isLayoutEnqueued = true

package/android/src/main/java/com/swmansion/rnscreens/stack/host/StackHostViewManager.kt

@@ -1,12 +1,14 @@
 package com.swmansion.rnscreens.stack.host
 
 import android.view.View
+import com.facebook.react.bridge.JSApplicationIllegalArgumentException
 import com.facebook.react.module.annotations.ReactModule
 import com.facebook.react.uimanager.ThemedReactContext
 import com.facebook.react.uimanager.ViewGroupManager
 import com.facebook.react.uimanager.ViewManagerDelegate
 import com.facebook.react.viewmanagers.RNSStackHostManagerDelegate
 import com.facebook.react.viewmanagers.RNSStackHostManagerInterface
+import com.swmansion.rnscreens.common.colorscheme.ColorScheme
 import com.swmansion.rnscreens.stack.screen.StackScreen
 
 @ReactModule(name = StackHostViewManager.REACT_CLASS)
@@ -70,6 +72,18 @@ class StackHostViewManager :
      */
     override fun needsCustomLayoutForChildren() = true
 
+    override fun setColorScheme(
+        view: StackHost,
+        value: String?,
+    ) {
+        when (value) {
+            null, "inherit" -> view.colorScheme = ColorScheme.INHERIT
+            "light" -> view.colorScheme = ColorScheme.LIGHT
+            "dark" -> view.colorScheme = ColorScheme.DARK
+            else -> throw JSApplicationIllegalArgumentException("[RNScreens] Invalid color scheme: $value.")
+        }
+    }
+
     companion object {
         const val REACT_CLASS = "RNSStackHost"
     }

package/android/src/main/java/com/swmansion/rnscreens/stack/screen/StackScreen.kt

@@ -175,4 +175,8 @@ class StackScreen(
     override fun resolveNestedContainer(): Container? = containerItemSupport.resolveNestedContainer()
 
     override fun findContentScrollView(): ViewGroup? = containerItemSupport.findContentScrollView(this)
+
+    override fun wantsToPreventStackNativeDismiss(): ContainerItem? =
+        resolveNestedContainer()?.wantsToPreventStackNativeDismiss()
+            ?: takeIf { isPreventNativeDismissEnabled }
 }