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

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/FragmentOperation.kt

@@ -14,6 +14,7 @@ internal class AddAndSetAsPrimaryOp(
     val fragment: StackScreenFragment,
     val containerViewId: Int,
     val addToBackStack: Boolean,
+    val coveredFragment: StackScreenFragment?,
     val allowStateLoss: Boolean = true,
 ) : FragmentOperation() {
     override fun execute(

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

@@ -2,7 +2,7 @@ package com.swmansion.rnscreens.stack.host
 
 import androidx.fragment.app.FragmentManager
 import androidx.fragment.app.FragmentTransaction
-import com.swmansion.rnscreens.helpers.createTransactionWithReordering
+import com.swmansion.rnscreens.ext.createTransactionWithReordering
 
 internal class FragmentOperationExecutor {
     internal fun executeOperations(
@@ -26,6 +26,7 @@ internal class FragmentOperationExecutor {
                 tx.addToBackStack(op.fragment.stackScreen.screenKey)
             }
             tx.add(op.containerViewId, op.fragment)
+            op.coveredFragment?.let { tx.detach(it) }
             tx.setPrimaryNavigationFragment(op.fragment)
             commitTransaction(tx, op.allowStateLoss)
         }