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

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

@@ -11,30 +11,59 @@ import com.swmansion.rnscreens.helpers.readColor
 import com.swmansion.rnscreens.helpers.readImageUri
 import com.swmansion.rnscreens.helpers.readOptionalString
 import com.swmansion.rnscreens.helpers.requireNotNullString
+import com.swmansion.rnscreens.stack.header.toolbar.model.StackHeaderToolbarMenuConfig
+import com.swmansion.rnscreens.stack.header.toolbar.model.StackHeaderToolbarMenuElementConfig
+import com.swmansion.rnscreens.stack.header.toolbar.model.StackHeaderToolbarMenuGroupConfig
+import com.swmansion.rnscreens.stack.header.toolbar.model.StackHeaderToolbarMenuItemConfig
+import com.swmansion.rnscreens.stack.header.toolbar.model.StackHeaderToolbarMenuItemDefaults
+import com.swmansion.rnscreens.stack.header.toolbar.model.StackHeaderToolbarMenuItemIconSource
+import com.swmansion.rnscreens.stack.header.toolbar.model.StackHeaderToolbarMenuItemShowAsAction
+import com.swmansion.rnscreens.stack.header.toolbar.model.StackHeaderToolbarMenuItemType
+import com.swmansion.rnscreens.stack.header.toolbar.update.StackHeaderToolbarFieldUpdate
+import com.swmansion.rnscreens.stack.header.toolbar.update.StackHeaderToolbarMenuElementOptions
+import com.swmansion.rnscreens.stack.header.toolbar.update.StackHeaderToolbarMenuElementRawUpdate
 
+/**
+ * Parses React toolbar-menu props (Dynamic / ReadableMap) into the native menu
+ * config and element-update models.
+ */
 internal object StackHeaderToolbarMenuMapper {
     // region Menu prop parsing
 
-    fun parseMenu(
+    internal fun parseMenu(
         context: Context,
         value: Dynamic,
-    ): Pair<StackHeaderToolbarMenuConfig, Map<String, StackHeaderToolbarMenuItemIconSource>> {
-        if (value.isNull) return Pair(StackHeaderToolbarMenuConfig(emptyList(), emptyList()), emptyMap())
+    ): StackHeaderToolbarMenuConfig {
+        if (value.isNull) return StackHeaderToolbarMenuConfig(emptyList(), emptyList())
         val map =
             value.asMapOrNull()
                 ?: throw JSApplicationIllegalArgumentException(
                     "[RNScreens] toolbarMenu must be an object.",
                 )
-        val iconSources = mutableMapOf<String, StackHeaderToolbarMenuItemIconSource>()
-        val config = StackHeaderToolbarMenuConfig(parseGroups(map), parseChildren(context, map, iconSources))
-        return Pair(config, iconSources)
+        return StackHeaderToolbarMenuConfig(parseGroups(map), parseChildren(context, map))
     }
 
     // endregion
 
     // region Menu element command parsing
 
-    fun parseMenuElementOptions(
+    internal fun parseElementRawUpdate(
+        context: Context,
+        id: String,
+        map: ReadableMap,
+    ): StackHeaderToolbarMenuElementRawUpdate =
+        StackHeaderToolbarMenuElementRawUpdate(
+            id = id,
+            options = parseMenuElementOptions(context, map),
+            iconSource = parseCommandIconSource(map),
+            checked =
+                map.readNullableBooleanUpdate(
+                    "checked",
+                    StackHeaderToolbarMenuItemDefaults.INITIAL_TOGGLE_STATE,
+                ),
+        )
+
+    private fun parseMenuElementOptions(
         context: Context,
         map: ReadableMap,
     ): StackHeaderToolbarMenuElementOptions =
@@ -50,20 +79,15 @@ internal object StackHeaderToolbarMenuMapper {
                     "showAsAction",
                     StackHeaderToolbarMenuItemDefaults.SHOW_AS_ACTION,
                 ),
-            icon = null,
             iconTintColorNormal = map.readNullableColorUpdate(context, "iconTintColorNormal"),
             iconTintColorPressed = map.readNullableColorUpdate(context, "iconTintColorPressed"),
             iconTintColorFocused = map.readNullableColorUpdate(context, "iconTintColorFocused"),
             iconTintColorDisabled = map.readNullableColorUpdate(context, "iconTintColorDisabled"),
-            checked =
-                map.readNullableBooleanUpdate(
-                    "checked",
-                    StackHeaderToolbarMenuItemDefaults.INITIAL_TOGGLE_STATE,
-                ),
             menuTitle = map.readNullableStringUpdate("menuTitle"),
         )
 
-    fun parseMenuElementIconSource(map: ReadableMap): StackHeaderToolbarMenuItemIconSource? {
+    // Command icons are optional deltas: null when neither key is present.
+    private fun parseCommandIconSource(map: ReadableMap): StackHeaderToolbarMenuItemIconSource? {
         if (!map.hasKey("drawableIconResourceName") && !map.hasKey("imageIconResource")) {
             return null
         }
@@ -98,7 +122,6 @@ internal object StackHeaderToolbarMenuMapper {
     private fun parseChildren(
         context: Context,
         map: ReadableMap,
-        iconSources: MutableMap<String, StackHeaderToolbarMenuItemIconSource>,
     ): List<StackHeaderToolbarMenuElementConfig> {
         val array = map.getArray("children") ?: return emptyList()
         return (0 until array.size()).map { i ->
@@ -106,23 +129,21 @@ internal object StackHeaderToolbarMenuMapper {
                 requireNotNull(array.getMap(i)) {
                     "[RNScreens] Menu children array must contain valid menu element specification objects."
                 }
-            parseElement(context, child, iconSources)
+            parseElement(context, child)
         }
     }
 
     private fun parseElement(
         context: Context,
         map: ReadableMap,
-        iconSources: MutableMap<String, StackHeaderToolbarMenuItemIconSource>,
     ): StackHeaderToolbarMenuElementConfig {
         val item = parseItemConfig(context, map)
-        iconSources[item.id] = parseItemIconSource(map)
         return when (val type = map.readOptionalString("type")) {
             "menuItem" -> StackHeaderToolbarMenuElementConfig.MenuItem(item = item)
             "menu" ->
                 StackHeaderToolbarMenuElementConfig.Submenu(
                     item = item,
-                    menu = StackHeaderToolbarMenuConfig(parseGroups(map), parseChildren(context, map, iconSources)),
+                    menu = StackHeaderToolbarMenuConfig(parseGroups(map), parseChildren(context, map)),
                     menuTitle = map.readOptionalString("menuTitle"),
                 )
 
@@ -133,7 +154,8 @@ internal object StackHeaderToolbarMenuMapper {
         }
     }
 
-    private fun parseItemIconSource(map: ReadableMap): StackHeaderToolbarMenuItemIconSource =
+    // Prop icons are absolute per-item state: absent keys parse to defaults.
+    private fun parsePropIconSource(map: ReadableMap): StackHeaderToolbarMenuItemIconSource =
         StackHeaderToolbarMenuItemIconSource(
             drawableIconResourceName =
                 map.getString("drawableIconResourceName")
@@ -158,7 +180,6 @@ internal object StackHeaderToolbarMenuMapper {
             hidden = map.readBoolean("hidden", StackHeaderToolbarMenuItemDefaults.HIDDEN),
             disabled = map.readBoolean("disabled", StackHeaderToolbarMenuItemDefaults.DISABLED),
             showAsAction = map.readShowAsActionEnum("showAsAction", StackHeaderToolbarMenuItemDefaults.SHOW_AS_ACTION),
-            icon = null,
             iconTintColorNormal =
                 map.readColor(
                     context,
@@ -183,6 +204,7 @@ internal object StackHeaderToolbarMenuMapper {
                     "iconTintColorDisabled",
                     StackHeaderToolbarMenuItemDefaults.ICON_TINT_COLOR_DISABLED,
                 ),
+            iconSource = parsePropIconSource(map),
             groupId = map.readOptionalString("groupId"),
             itemType = map.readItemTypeEnum("itemType", StackHeaderToolbarMenuItemDefaults.ITEM_TYPE),
             initialToggleState =

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

@@ -0,0 +1,8 @@
+package com.swmansion.rnscreens.stack.header.toolbar.model
+
+// Immutable, Drawable-free tree of data classes parsed from the `toolbarMenu`
+// prop, so structural equality is sound (used to detect real prop changes).
+internal data class StackHeaderToolbarMenuConfig(
+    val groups: List<StackHeaderToolbarMenuGroupConfig>,
+    val children: List<StackHeaderToolbarMenuElementConfig>,
+)

package/android/src/main/java/com/swmansion/rnscreens/stack/header/toolbar/{StackHeaderToolbarMenuElementConfig.kt → model/StackHeaderToolbarMenuElementConfig.kt}

@@ -1,4 +1,4 @@
-package com.swmansion.rnscreens.stack.header.toolbar
+package com.swmansion.rnscreens.stack.header.toolbar.model
 
 internal sealed interface StackHeaderToolbarMenuElementConfig {
     val item: StackHeaderToolbarMenuItemConfig

package/android/src/main/java/com/swmansion/rnscreens/stack/header/toolbar/{StackHeaderToolbarMenuGroupConfig.kt → model/StackHeaderToolbarMenuGroupConfig.kt}

@@ -1,4 +1,4 @@
-package com.swmansion.rnscreens.stack.header.toolbar
+package com.swmansion.rnscreens.stack.header.toolbar.model
 
 internal data class StackHeaderToolbarMenuGroupConfig(
     val groupId: String,

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

@@ -0,0 +1,11 @@
+package com.swmansion.rnscreens.stack.header.toolbar.model
+
+/**
+ * Derived group structure for a built menu: item→group, per-group
+ * single-selection, and group membership.
+ */
+internal data class StackHeaderToolbarMenuGroupMetadata(
+    val itemGroupMap: Map<String, String>,
+    val groupSingleSelection: Map<String, Boolean>,
+    val groupMemberItems: Map<String, List<String>>,
+)

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

@@ -1,6 +1,4 @@
-package com.swmansion.rnscreens.stack.header.toolbar
-
-import android.graphics.drawable.Drawable
+package com.swmansion.rnscreens.stack.header.toolbar.model
 
 internal data class StackHeaderToolbarMenuItemConfig(
     val id: 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/{StackHeaderToolbarMenuItemDefaults.kt → model/StackHeaderToolbarMenuItemDefaults.kt}

@@ -1,4 +1,4 @@
-package com.swmansion.rnscreens.stack.header.toolbar
+package com.swmansion.rnscreens.stack.header.toolbar.model
 
 /**
  * Defaults for toolbar menu item fields.

package/android/src/main/java/com/swmansion/rnscreens/stack/header/toolbar/{StackHeaderToolbarMenuItemIconSource.kt → model/StackHeaderToolbarMenuItemIconSource.kt}

@@ -1,4 +1,4 @@
-package com.swmansion.rnscreens.stack.header.toolbar
+package com.swmansion.rnscreens.stack.header.toolbar.model
 
 internal data class StackHeaderToolbarMenuItemIconSource(
     val drawableIconResourceName: String?,

package/android/src/main/java/com/swmansion/rnscreens/stack/header/toolbar/{StackHeaderToolbarMenuItemShowAsAction.kt → model/StackHeaderToolbarMenuItemShowAsAction.kt}

@@ -1,4 +1,4 @@
-package com.swmansion.rnscreens.stack.header.toolbar
+package com.swmansion.rnscreens.stack.header.toolbar.model
 
 import android.view.MenuItem.SHOW_AS_ACTION_ALWAYS
 import android.view.MenuItem.SHOW_AS_ACTION_IF_ROOM

package/android/src/main/java/com/swmansion/rnscreens/stack/header/toolbar/{StackHeaderToolbarMenuItemType.kt → model/StackHeaderToolbarMenuItemType.kt}

@@ -1,4 +1,4 @@
-package com.swmansion.rnscreens.stack.header.toolbar
+package com.swmansion.rnscreens.stack.header.toolbar.model
 
 internal enum class StackHeaderToolbarMenuItemType {
     ACTION,

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/{StackHeaderToolbarFieldUpdate.kt → update/StackHeaderToolbarFieldUpdate.kt}

@@ -1,4 +1,4 @@
-package com.swmansion.rnscreens.stack.header.toolbar
+package com.swmansion.rnscreens.stack.header.toolbar.update
 
 internal sealed interface StackHeaderToolbarFieldUpdate<out T> {
     object Reset : StackHeaderToolbarFieldUpdate<Nothing>

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

@@ -0,0 +1,84 @@
+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
+
+/**
+ * Partial update for a toolbar menu element.
+ *
+ * A `null` field means "leave the current value unchanged".
+ */
+internal data class StackHeaderToolbarMenuElementOptions(
+    val title: StackHeaderToolbarFieldUpdate<String>? = null,
+    val titleCondensed: StackHeaderToolbarFieldUpdate<String>? = null,
+    val tooltipText: StackHeaderToolbarFieldUpdate<String>? = null,
+    val accessibilityLabel: StackHeaderToolbarFieldUpdate<String>? = null,
+    val hidden: Boolean? = null,
+    val disabled: Boolean? = null,
+    val showAsAction: StackHeaderToolbarMenuItemShowAsAction? = 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
+        get() =
+            iconTintColorNormal != null ||
+                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

@@ -0,0 +1,15 @@
+package com.swmansion.rnscreens.stack.header.toolbar.update
+
+import com.swmansion.rnscreens.stack.header.toolbar.model.StackHeaderToolbarMenuItemIconSource
+
+/**
+ * A single toolbar menu element update carried by an `updateToolbarMenuElements`
+ * 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

@@ -0,0 +1,11 @@
+package com.swmansion.rnscreens.stack.header.toolbar.update
+
+/**
+ * A single toolbar menu element update whose icon has already been resolved and merged
+ * into [options], ready to be applied to the toolbar.
+ */
+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

@@ -0,0 +1,18 @@
+package com.swmansion.rnscreens.stack.header.toolbar.update
+
+import android.graphics.drawable.Drawable
+import com.swmansion.rnscreens.stack.header.toolbar.model.StackHeaderToolbarMenuItemIconSource
+
+/**
+ * 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 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: Drawable?) -> Unit,
+    )
+}