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

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

@@ -0,0 +1,195 @@
+package com.swmansion.rnscreens.stack.header.toolbar
+
+import android.content.res.ColorStateList
+import android.graphics.drawable.Drawable
+import android.os.Build
+import android.util.Log
+import android.view.Menu
+import android.view.MenuItem
+import androidx.core.view.MenuItemCompat
+import com.google.android.material.appbar.MaterialToolbar
+import com.swmansion.rnscreens.stack.header.getResizedDrawable
+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.StackHeaderToolbarMenuModel
+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.valueOrNull
+
+/**
+ * Writes onto the android Menu: builds the toolbar menu from its model and
+ * applies in-place element updates (options, checkability, icon tint).
+ */
+internal object StackHeaderToolbarMenuApplicator {
+    // region Menu build
+
+    internal fun rebuildToolbarMenu(
+        toolbar: MaterialToolbar,
+        model: StackHeaderToolbarMenuModel,
+        groupDividerEnabled: Boolean,
+        optionsForItem: (id: String) -> StackHeaderToolbarMenuElementOptions,
+        onItemClicked: (id: String) -> Unit,
+    ) {
+        toolbar.menu.clear()
+        addElements(toolbar, toolbar.menu, model.config, model.forwardIdMap, model.forwardGroupIdMap, optionsForItem)
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.P) {
+            toolbar.menu.setGroupDividerEnabled(groupDividerEnabled)
+        }
+        toolbar.setOnMenuItemClickListener { menuItem ->
+            model.reverseIdMap[menuItem.itemId]?.let(onItemClicked)
+            true
+        }
+    }
+
+    private fun addElements(
+        toolbar: MaterialToolbar,
+        menu: Menu,
+        menuConfig: StackHeaderToolbarMenuConfig,
+        forwardIdMap: Map<String, Int>,
+        forwardGroupIdMap: Map<String, Int>,
+        optionsForItem: (id: String) -> StackHeaderToolbarMenuElementOptions,
+    ) {
+        menuConfig.children.forEachIndexed { index, element ->
+            val itemId =
+                requireNotNull(forwardIdMap[element.item.id]) {
+                    "[RNScreens] Invalid forwardIdMap received. Missing item: ${element.item}."
+                }
+            val groupIntId =
+                element.item.groupId
+                    ?.let { forwardGroupIdMap[it] ?: Menu.NONE }
+                    ?: Menu.NONE
+            when (element) {
+                is StackHeaderToolbarMenuElementConfig.MenuItem -> {
+                    val menuItem = menu.add(groupIntId, itemId, index, null)
+                    applyMenuElementOptions(toolbar, menuItem, optionsForItem(element.item.id))
+                }
+                is StackHeaderToolbarMenuElementConfig.Submenu -> {
+                    val subMenu = menu.addSubMenu(groupIntId, itemId, index, null)
+                    applyMenuElementOptions(toolbar, subMenu.item, optionsForItem(element.item.id))
+                    addElements(toolbar, subMenu, element.menu, forwardIdMap, forwardGroupIdMap, optionsForItem)
+                }
+            }
+        }
+        configureGroupCheckability(menu, menuConfig.groups, forwardGroupIdMap)
+    }
+
+    // Group membership is the only source of checkability (configs are validated
+    // up front, see StackHeaderToolbarMenuModel); checked state belongs to the
+    // controller, which projects it right after the rebuild.
+    private fun configureGroupCheckability(
+        menu: Menu,
+        groups: List<StackHeaderToolbarMenuGroupConfig>,
+        forwardGroupIdMap: Map<String, Int>,
+    ) {
+        for (group in groups) {
+            val groupIntId = forwardGroupIdMap[group.groupId] ?: continue
+            menu.setGroupCheckable(groupIntId, true, group.singleSelection)
+        }
+    }
+
+    // endregion
+
+    // region Element updates
+
+    internal fun updateToolbarMenuElement(
+        toolbar: MaterialToolbar,
+        forwardIdMap: Map<String, Int>,
+        id: String,
+        options: StackHeaderToolbarMenuElementOptions,
+    ) {
+        val item =
+            forwardIdMap[id]?.let { toolbar.menu.findItem(it) } ?: run {
+                Log.e(TAG, "[RNScreens] Unable to find menu element with id '$id'.")
+                return
+            }
+        applyMenuElementOptions(toolbar, item, options)
+    }
+
+    private fun applyMenuElementOptions(
+        toolbar: MaterialToolbar,
+        menuItem: MenuItem,
+        options: StackHeaderToolbarMenuElementOptions,
+    ) {
+        options.title?.let { menuItem.title = it.valueOrNull() }
+        options.titleCondensed?.let { menuItem.titleCondensed = it.valueOrNull() }
+        options.tooltipText?.let { MenuItemCompat.setTooltipText(menuItem, it.valueOrNull()) }
+        options.accessibilityLabel?.let {
+            // Setting `null` will restore Android's default (`title` for items
+            // in toolbar, `null` otherwise).
+            MenuItemCompat.setContentDescription(menuItem, it.valueOrNull())
+        }
+        options.hidden?.let { menuItem.isVisible = !it }
+        options.disabled?.let { menuItem.isEnabled = !it }
+
+        options.icon?.let {
+            when (it) {
+                StackHeaderToolbarFieldUpdate.Reset -> menuItem.icon = null
+                is StackHeaderToolbarFieldUpdate.Set<Drawable> ->
+                    menuItem.icon = getResizedDrawable(toolbar, it.value)
+            }
+        }
+
+        // The tint list is built absolutely from the given fields, so whenever
+        // this branch runs the caller must pass all four tint slots resolved
+        // (Set/Reset) — see StackHeaderToolbarMenuController.effectiveOptions.
+        if (options.requiresIconTintColorUpdate || options.icon != null) {
+            MenuItemCompat.setIconTintList(menuItem, buildIconTintList(options))
+        }
+
+        options.menuTitle?.let { update ->
+            val subMenu = menuItem.subMenu
+            if (subMenu != null) {
+                // In order to match native behavior, we need to clear the header first and then use
+                // regular title if menuTitle is not provided. If title is also null, there will be
+                // no submenu header at all.
+                subMenu.clearHeader()
+                subMenu.setHeaderTitle(update.valueOrNull() ?: menuItem.title)
+            } else {
+                Log.w(TAG, "[RNScreens] menuTitle ignored: target is not a submenu.")
+            }
+        }
+
+        // Apply showAsAction property after icon is set to ensure correct overflow behavior.
+        options.showAsAction?.let { menuItem.setShowAsAction(it.toNativeShowAsAction()) }
+    }
+
+    // endregion
+
+    // region Icon tint
+
+    private fun buildIconTintList(options: StackHeaderToolbarMenuElementOptions): ColorStateList? {
+        val states = mutableListOf<IntArray>()
+        val colors = mutableListOf<Int>()
+
+        options.iconTintColorDisabled?.valueOrNull()?.let {
+            states.add(intArrayOf(-android.R.attr.state_enabled))
+            colors.add(it)
+        }
+
+        options.iconTintColorPressed?.valueOrNull()?.let {
+            states.add(intArrayOf(android.R.attr.state_pressed))
+            colors.add(it)
+        }
+
+        options.iconTintColorFocused?.valueOrNull()?.let {
+            states.add(intArrayOf(android.R.attr.state_focused))
+            colors.add(it)
+        }
+
+        options.iconTintColorNormal?.valueOrNull()?.let {
+            states.add(intArrayOf())
+            colors.add(it)
+        }
+
+        return if (states.isNotEmpty()) {
+            ColorStateList(states.toTypedArray(), colors.toIntArray())
+        } else {
+            null
+        }
+    }
+
+    // endregion
+
+    private const val TAG = "StackHeaderToolbarMenuApplicator"
+}

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

@@ -0,0 +1,448 @@
+package com.swmansion.rnscreens.stack.header.toolbar
+
+import android.graphics.drawable.Drawable
+import android.util.Log
+import android.view.MenuItem
+import com.google.android.material.appbar.MaterialToolbar
+import com.swmansion.rnscreens.helpers.IconResolution
+import com.swmansion.rnscreens.helpers.PropIconResolver
+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.StackHeaderToolbarMenuItemIconSource
+import com.swmansion.rnscreens.stack.header.toolbar.model.StackHeaderToolbarMenuModel
+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
+import com.swmansion.rnscreens.stack.header.toolbar.update.StackHeaderToolbarMenuElementUpdate
+import com.swmansion.rnscreens.stack.header.toolbar.update.StackHeaderToolbarMenuIconResolver
+import com.swmansion.rnscreens.stack.header.toolbar.update.StackHeaderToolbarMenuUpdateQueue
+import com.swmansion.rnscreens.stack.header.toolbar.update.toOptions
+import java.lang.ref.WeakReference
+
+/**
+ * Owns the toolbar menu: the parsed model and the runtime state accumulated on
+ * top of it (imperative element updates, group selections, resolved prop
+ * icons). The state is the source of truth and lives as long as this
+ * controller; an attached toolbar is merely a projection of it, rebuilt from
+ * scratch at every [attach]. Checked-state semantics run on the state, so
+ * updates behave identically whether a toolbar is attached or not.
+ */
+internal class StackHeaderToolbarMenuController(
+    private val iconResolver: StackHeaderToolbarMenuIconResolver,
+) {
+    internal var delegate: WeakReference<StackHeaderToolbarMenuDelegate>? = null
+
+    // region Model
+
+    private var model = StackHeaderToolbarMenuModel.EMPTY
+    private var groupDividerEnabled = false
+
+    // Set by a menu change and cleared by [attach]: until then a live toolbar
+    // still shows the previous menu (with previous int ids), so in-place
+    // application is suspended and updates are recorded only.
+    private var modelDirty = false
+
+    /**
+     * Replaces the menu configuration. Returns `true` when it actually
+     * changed; icon sources are part of the config, so an icon-source-only
+     * prop change counts. A real change validates the new menu, resets all
+     * runtime state, re-initializes group selections from
+     * `initialToggleState` and drops pending command batches. Application to
+     * the toolbar is the caller's responsibility (via [attach]).
+     */
+    internal fun setMenu(menu: StackHeaderToolbarMenuConfig): Boolean {
+        if (menu == model.config) {
+            return false
+        }
+
+        // Throws on an invalid menu before any mutation, so the previous,
+        // valid model stays intact.
+        model = StackHeaderToolbarMenuModel.from(menu)
+
+        commandOverrides.clear()
+        propIcons.keys.retainAll(model.elementById.keys)
+        propIconResolvers.keys.retainAll(model.elementById.keys)
+        groupSelections =
+            model.groupMetadata.groupMemberItems
+                .mapValues { (_, members) ->
+                    members.filterTo(mutableSetOf()) {
+                        model.elementById
+                            .getValue(it)
+                            .item.initialToggleState
+                    }
+                }.toMutableMap()
+
+        // Commands sent against the previous menu must not touch the new one,
+        // even those still waiting for an icon.
+        updateQueue.clearPending()
+
+        modelDirty = true
+        resolvePropIcons()
+        return true
+    }
+
+    /** Returns `true` when the value changed and the menu needs a rebuild. */
+    internal fun setGroupDividerEnabled(enabled: Boolean): Boolean {
+        if (groupDividerEnabled == enabled) {
+            return false
+        }
+        groupDividerEnabled = enabled
+        return true
+    }
+
+    // endregion
+
+    // region State
+
+    // Resolved icons of prop-declared items, and the stateful per-item
+    // resolvers behind them; both pruned in [setMenu].
+    private val propIcons = mutableMapOf<String, Drawable>()
+    private val propIconResolvers = mutableMapOf<String, PropIconResolver>()
+
+    // Accumulated imperative element updates, merged field-wise (newer
+    // non-null wins). `checked` never reaches here — it travels on the update
+    // envelope and group selections are its single home.
+    private val commandOverrides = mutableMapOf<String, StackHeaderToolbarMenuElementOptions>()
+
+    // Fully materialized selection per group. Initialized from
+    // `initialToggleState` at [setMenu], mutated by taps and command `checked`.
+    private var groupSelections = mutableMapOf<String, MutableSet<String>>()
+
+    // endregion
+
+    // region Imperative updates
+
+    // Serial, batch-atomic command ingestion; owned here so a menu change can
+    // drop stale batches locally (see setMenu).
+    private val updateQueue =
+        StackHeaderToolbarMenuUpdateQueue(iconResolver) { applyElementUpdates(it) }
+
+    /**
+     * Enqueues an `updateToolbarMenuElements` batch. Batches apply serially
+     * and atomically, once every icon in the batch has resolved — see
+     * [StackHeaderToolbarMenuUpdateQueue].
+     */
+    internal fun enqueueElementUpdates(batch: List<StackHeaderToolbarMenuElementRawUpdate>) {
+        updateQueue.enqueue(batch)
+    }
+
+    /**
+     * Applies a fully resolved `updateToolbarMenuElements` batch: records it,
+     * runs checked-state transitions on the state, projects onto the live
+     * toolbar when one is attached, and emits one coalesced selection event per
+     * changed group — identically whether attached or not.
+     */
+    private fun applyElementUpdates(updates: List<StackHeaderToolbarMenuElementUpdate>) {
+        val changedGroups = LinkedHashSet<String>()
+        val toolbar = liveToolbar()
+
+        for (update in updates) {
+            val id = update.id
+            if (id !in model.elementById) {
+                Log.w(TAG, "[RNScreens] Ignoring toolbar menu update for unknown item id '$id'.")
+                continue
+            }
+
+            val options = applicableOptions(id, update.options)
+
+            if (!options.isEmpty) {
+                commandOverrides[id] = commandOverrides[id]?.mergedWith(options) ?: options
+            }
+
+            update.checked?.let { checked ->
+                applyCheckedInState(id, checked)?.let(changedGroups::add)
+            }
+
+            if (toolbar != null && !options.isEmpty) {
+                StackHeaderToolbarMenuApplicator.updateToolbarMenuElement(
+                    toolbar,
+                    model.forwardIdMap,
+                    id,
+                    widenWithCoupledFields(id, options),
+                )
+            }
+        }
+
+        if (toolbar != null) {
+            changedGroups.forEach { applySelectionToToolbar(toolbar, it) }
+        }
+        changedGroups.forEach(::emitGroupSelection)
+    }
+
+    /**
+     * Drops options the target element cannot accept. They would otherwise be
+     * recorded in [commandOverrides], which outlive every rebuild, and be
+     * re-applied — and re-warned about — by each of them.
+     */
+    private fun applicableOptions(
+        id: String,
+        options: StackHeaderToolbarMenuElementOptions,
+    ): StackHeaderToolbarMenuElementOptions {
+        val targetsSubmenu = model.elementById[id] is StackHeaderToolbarMenuElementConfig.Submenu
+        if (options.menuTitle == null || targetsSubmenu) {
+            return options
+        }
+        Log.w(TAG, "[RNScreens] Ignoring menuTitle of '$id': the target is not a submenu.")
+        return options.copy(menuTitle = null)
+    }
+
+    // endregion
+
+    // region Prop icons
+
+    /**
+     * Re-resolves every prop-declared icon source; called on a menu change —
+     * the only time sources can change. Results flow through [setItemIcon]:
+     * while the menu is dirty (until the next [attach]) they land in state
+     * only, later async ones also apply to the live toolbar in place.
+     */
+    private fun resolvePropIcons() {
+        model.elementById.forEach { (id, element) ->
+            val source = element.item.iconSource
+            // An escaping exception would leave the menu dirty forever, with
+            // in-place application suspended until the next [attach].
+            try {
+                propIconResolvers
+                    .getOrPut(id) {
+                        PropIconResolver { name, uri, onComplete ->
+                            iconResolver.resolve(
+                                StackHeaderToolbarMenuItemIconSource(name, uri),
+                                onComplete,
+                            )
+                        }
+                    }.resolve(source.drawableIconResourceName, source.imageIconUri) { result ->
+                        when (result) {
+                            IconResolution.Unchanged -> Unit
+                            is IconResolution.Resolved -> setItemIcon(id, source, result.drawable)
+                        }
+                    }
+            } catch (e: Exception) {
+                Log.e(TAG, "[RNScreens] Failed to resolve the icon of toolbar menu item '$id'.", e)
+            }
+        }
+    }
+
+    /**
+     * Sets or clears the resolved icon of a prop-declared item, in place —
+     * never rebuilds the menu and never touches command state. An icon set via
+     * a view command takes precedence until the next real menu change.
+     */
+    private fun setItemIcon(
+        id: String,
+        source: StackHeaderToolbarMenuItemIconSource,
+        icon: Drawable?,
+    ) {
+        // Pruning a resolver in [setMenu] does not cancel its in-flight load,
+        // and the orphan's latest-wins guard still matches the source it was
+        // asked for, so a result must be matched against the current model.
+        if (model.elementById[id]?.item?.iconSource != source) {
+            return
+        }
+        val previous = if (icon != null) propIcons.put(id, icon) else propIcons.remove(id)
+        if (previous === icon || commandOverrides[id]?.icon != null) {
+            return
+        }
+        val toolbar = liveToolbar() ?: return
+        val effective = effectiveOptions(id)
+        StackHeaderToolbarMenuApplicator.updateToolbarMenuElement(
+            toolbar,
+            model.forwardIdMap,
+            id,
+            StackHeaderToolbarMenuElementOptions(
+                // Action-item classification runs when showAsAction is set and
+                // setting an icon alone does not re-run it, so it must
+                // accompany the icon.
+                showAsAction = effective.showAsAction,
+                icon = effective.icon,
+                iconTintColorNormal = effective.iconTintColorNormal,
+                iconTintColorPressed = effective.iconTintColorPressed,
+                iconTintColorFocused = effective.iconTintColorFocused,
+                iconTintColorDisabled = effective.iconTintColorDisabled,
+            ),
+        )
+    }
+
+    // endregion
+
+    // region Attachment & projection
+
+    private var attachedToolbar: WeakReference<MaterialToolbar>? = null
+
+    /**
+     * Projects the menu (model ⊕ prop icons ⊕ command overrides ⊕ selections)
+     * onto [toolbar] and starts applying subsequent updates to it in place.
+     * Emits no events — the projection is semantically a no-change.
+     */
+    internal fun attach(toolbar: MaterialToolbar) {
+        attachedToolbar = WeakReference(toolbar)
+        modelDirty = false
+        StackHeaderToolbarMenuApplicator.rebuildToolbarMenu(
+            toolbar,
+            model,
+            groupDividerEnabled,
+            optionsForItem = ::effectiveOptions,
+            onItemClicked = ::handleItemClick,
+        )
+        model.groupMetadata.groupMemberItems.keys
+            .forEach { applySelectionToToolbar(toolbar, it) }
+    }
+
+    internal fun detach() {
+        attachedToolbar = null
+    }
+
+    internal fun tearDown() {
+        updateQueue.tearDown()
+        detach()
+    }
+
+    private fun liveToolbar(): MaterialToolbar? = if (modelDirty) null else attachedToolbar?.get()
+
+    private fun applySelectionToToolbar(
+        toolbar: MaterialToolbar,
+        groupId: String,
+    ) {
+        val selected = groupSelections[groupId].orEmpty()
+
+        // setChecked(false) on an item of an exclusive group checks it instead
+        // of clearing it, so only the selected member is written and the native
+        // sibling-uncheck does the rest. Such a group is never cleared.
+        if (model.groupMetadata.groupSingleSelection[groupId] == true) {
+            val selectedId = selected.singleOrNull() ?: return
+            menuItemFor(toolbar, selectedId)?.isChecked = true
+            return
+        }
+
+        for (memberId in model.groupMetadata.groupMemberItems[groupId].orEmpty()) {
+            val item = menuItemFor(toolbar, memberId) ?: continue
+            val shouldBeChecked = memberId in selected
+            if (item.isChecked != shouldBeChecked) {
+                item.isChecked = shouldBeChecked
+            }
+        }
+    }
+
+    private fun menuItemFor(
+        toolbar: MaterialToolbar,
+        id: String,
+    ): MenuItem? = model.forwardIdMap[id]?.let { toolbar.menu.findItem(it) }
+
+    // endregion
+
+    // region Checked-state semantics
+
+    /**
+     * Mutates the selection of [itemId]'s group and returns the group id when
+     * it actually changed. [explicitCheckedValue] `null` means a user toggle.
+     */
+    private fun applyCheckedInState(
+        itemId: String,
+        explicitCheckedValue: Boolean?,
+    ): String? {
+        val groupId = model.groupMetadata.itemGroupMap[itemId] ?: return null
+        val singleSelection = model.groupMetadata.groupSingleSelection[groupId] ?: return null
+        val selection = groupSelections.getOrPut(groupId) { mutableSetOf() }
+
+        if (singleSelection) {
+            if (explicitCheckedValue == false) {
+                Log.w(
+                    TAG,
+                    "[RNScreens] Cannot uncheck item '$itemId' in single-selection group '$groupId'. " +
+                        "Check a different item instead.",
+                )
+                return null
+            }
+            if (selection.singleOrNull() == itemId) {
+                return null
+            }
+            selection.clear()
+            selection.add(itemId)
+            return groupId
+        }
+
+        val newChecked = explicitCheckedValue ?: (itemId !in selection)
+        val changed = if (newChecked) selection.add(itemId) else selection.remove(itemId)
+        return groupId.takeIf { changed }
+    }
+
+    private fun handleItemClick(id: String) {
+        if (!isCheckable(id)) {
+            delegate?.get()?.onMenuItemClicked(id)
+            return
+        }
+        val changedGroup = applyCheckedInState(id, explicitCheckedValue = null) ?: return
+        liveToolbar()?.let { applySelectionToToolbar(it, changedGroup) }
+        emitGroupSelection(changedGroup)
+    }
+
+    private fun emitGroupSelection(groupId: String) {
+        val selection = groupSelections[groupId].orEmpty()
+        val selectedIds =
+            model.groupMetadata.groupMemberItems[groupId]
+                .orEmpty()
+                .filter { it in selection }
+        delegate?.get()?.onGroupSelectionChanged(groupId, selectedIds)
+    }
+
+    // Validation guarantees only plain menu items carry a groupId, so
+    // checkability reduces to group membership.
+    private fun isCheckable(id: String): Boolean = model.elementById[id]?.item?.groupId != null
+
+    // endregion
+
+    // region Effective values
+
+    private fun effectiveOptions(id: String): StackHeaderToolbarMenuElementOptions {
+        val base = model.elementById.getValue(id).toOptions()
+        val withPropIcon =
+            propIcons[id]?.let { base.copy(icon = StackHeaderToolbarFieldUpdate.Set(it)) } ?: base
+        return commandOverrides[id]?.let(withPropIcon::mergedWith) ?: withPropIcon
+    }
+
+    /**
+     * The live item already reflects effective state, so applying the delta
+     * keeps it there. Three fields need widening: tint colors resolve as one
+     * complete ColorStateList, so touching any tint slot (or the icon, whose
+     * application re-tints) requires all four; `showAsAction` must accompany a
+     * new icon, because action-item classification runs when it is set and
+     * setting an icon alone does not re-run it; and a submenu header must be
+     * re-asserted on every title change, because `MenuItem.setTitle`
+     * propagates into it and would leave it following the title until the
+     * next rebuild projected the effective `menuTitle` back.
+     */
+    private fun widenWithCoupledFields(
+        id: String,
+        delta: StackHeaderToolbarMenuElementOptions,
+    ): StackHeaderToolbarMenuElementOptions {
+        val effective = effectiveOptions(id)
+        var resolved = delta
+
+        if (delta.icon != null || delta.requiresIconTintColorUpdate) {
+            resolved =
+                resolved.copy(
+                    iconTintColorNormal = effective.iconTintColorNormal,
+                    iconTintColorPressed = effective.iconTintColorPressed,
+                    iconTintColorFocused = effective.iconTintColorFocused,
+                    iconTintColorDisabled = effective.iconTintColorDisabled,
+                )
+            if (delta.icon != null) {
+                resolved = resolved.copy(showAsAction = effective.showAsAction)
+            }
+        }
+
+        if (delta.title != null &&
+            delta.menuTitle == null &&
+            model.elementById[id] is StackHeaderToolbarMenuElementConfig.Submenu
+        ) {
+            resolved = resolved.copy(menuTitle = effective.menuTitle)
+        }
+
+        return resolved
+    }
+
+    // endregion
+
+    companion object {
+        private const val TAG = "StackHeaderToolbarMenuController"
+    }
+}

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

@@ -0,0 +1,10 @@
+package com.swmansion.rnscreens.stack.header.toolbar
+
+internal interface StackHeaderToolbarMenuDelegate {
+    fun onMenuItemClicked(id: String)
+
+    fun onGroupSelectionChanged(
+        groupId: String,
+        selectedIds: List<String>,
+    )
+}