@apexnative/navigation 0.0.0-stage → 1.0.0-alpha.0

package/android/src/main/java/dev/apexnative/navigation/views/stack/topbar/search/SuggestionList.kt

@@ -0,0 +1,77 @@
+package dev.apexnative.navigation.views.stack.topbar.search
+
+import android.annotation.SuppressLint
+import android.content.Context
+import android.content.res.ColorStateList
+import android.graphics.drawable.Drawable
+import android.util.TypedValue
+import android.view.Gravity
+import android.widget.ImageView
+import android.widget.LinearLayout
+import android.widget.TextView
+import dev.apexnative.navigation.options.SearchBarSuggestion
+import dev.apexnative.navigation.utils.TestIds
+import dev.apexnative.navigation.utils.dp
+
+/**
+ * The suggestions of the search (`topBar.searchBar.suggestions`): rows of an icon and a title, as Material 3 lists
+ * them under a search field. A tap goes to [onPick] with the suggestion's id.
+ */
+@SuppressLint("ViewConstructor")
+class SuggestionList(
+    context: Context,
+    private val loadIcon: (String) -> Drawable?,
+) : LinearLayout(context) {
+    var onPick: ((String) -> Unit)? = null
+
+    private var suggestions: List<SearchBarSuggestion> = emptyList()
+    private var styleContext: Context = context
+
+    init {
+        orientation = VERTICAL
+    }
+
+    fun setSuggestions(suggestions: List<SearchBarSuggestion>) {
+        if (suggestions == this.suggestions) return
+        this.suggestions = suggestions
+        removeAllViews()
+        suggestions.forEach { addView(row(it), LayoutParams(LayoutParams.MATCH_PARENT, ROW_HEIGHT_DP.dp)) }
+    }
+
+    /** Light or dark changed: the rows again, with the theme's colors from [styleContext]. */
+    fun restyle(styleContext: Context) {
+        this.styleContext = styleContext
+        val current = suggestions
+        suggestions = emptyList()
+        setSuggestions(current)
+    }
+
+    private fun row(suggestion: SearchBarSuggestion): LinearLayout = LinearLayout(context).apply {
+        orientation = HORIZONTAL
+        gravity = Gravity.CENTER_VERTICAL
+        setPaddingRelative(16.dp, 0, 16.dp, 0)
+        val ripple = TypedValue()
+        if (context.theme.resolveAttribute(android.R.attr.selectableItemBackground, ripple, true)) {
+            setBackgroundResource(ripple.resourceId)
+        }
+        contentDescription = suggestion.title
+        TestIds.apply(this, suggestion.testID)
+        setOnClickListener { onPick?.invoke(suggestion.id) }
+
+        val icon = ImageView(context)
+        suggestion.icon.get(null)?.let(loadIcon)?.let { icon.setImageDrawable(it.mutate()) }
+        icon.imageTintList = ColorStateList.valueOf(SearchStyle.hintColor(styleContext))
+        addView(icon, LayoutParams(24.dp, 24.dp).apply { marginEnd = 16.dp })
+
+        val title = TextView(context)
+        title.text = suggestion.title
+        title.setTextSize(TypedValue.COMPLEX_UNIT_SP, 16f)
+        title.setTextColor(SearchStyle.textColor(styleContext))
+        title.isSingleLine = true
+        addView(title, LayoutParams(0, LayoutParams.WRAP_CONTENT, 1f))
+    }
+
+    companion object {
+        const val ROW_HEIGHT_DP = 56
+    }
+}

package/android/src/main/java/dev/apexnative/navigation/views/stack/topbar/titlebar/BarButtonComponentCell.kt

@@ -0,0 +1,80 @@
+package dev.apexnative.navigation.views.stack.topbar.titlebar
+
+import android.annotation.SuppressLint
+import android.content.Context
+import android.view.View
+import android.view.ViewGroup
+import dev.apexnative.navigation.utils.UiUtils
+import kotlin.math.max
+
+/**
+ * The cell of a React button in the bar (`topBar.leftButtons[].component`): the action view of the button's menu item,
+ * as an icon's: 12 dp on each side, at least 48 dp wide, as high as the row, the content in its middle. The content (a
+ * React root, or later a view of the screen's own tree) measures `AT_MOST` — the width at most what the row gives, the
+ * height at most the row's — or exactly its `component.width` / `component.height` when the options give them
+ * ([contentWidth], [contentHeight], pixels). The cell takes the menu's id; the content never gets one (React Native
+ * rejects a root with an id). It never looks inside the content.
+ */
+@SuppressLint("ViewConstructor")
+internal class BarButtonComponentCell(context: Context) : ViewGroup(context) {
+    private val side = UiUtils.dpToPx(context, SIDE_DP)
+    private val minWidth = UiUtils.dpToPx(context, MIN_WIDTH_DP)
+
+    /** The content's width as the options set it, or null for its own. */
+    var contentWidth: Int? = null
+        set(value) {
+            if (field == value) return
+            field = value
+            requestLayout()
+        }
+
+    /** The content's height as the options set it, or null for its own. */
+    var contentHeight: Int? = null
+        set(value) {
+            if (field == value) return
+            field = value
+            requestLayout()
+        }
+
+    /** The view the cell shows; none takes it away. */
+    var content: View? = null
+        set(value) {
+            if (field === value) return
+            field?.let { if (it.parent === this) removeView(it) }
+            field = value
+            if (value != null) {
+                (value.parent as? ViewGroup)?.removeView(value)
+                addView(value, LayoutParams(LayoutParams.WRAP_CONTENT, LayoutParams.WRAP_CONTENT))
+            }
+        }
+
+    override fun onMeasure(widthMeasureSpec: Int, heightMeasureSpec: Int) {
+        val availableWidth = MeasureSpec.getSize(widthMeasureSpec)
+        val widthMode = MeasureSpec.getMode(widthMeasureSpec)
+        val height = MeasureSpec.getSize(heightMeasureSpec)
+        val child = content
+        var childWidth = 0
+        if (child != null) {
+            val maxWidth = if (widthMode == MeasureSpec.UNSPECIFIED) Int.MAX_VALUE / 2 else availableWidth - 2 * side
+            val widthSpec = contentWidth?.let { MeasureSpec.makeMeasureSpec(it, MeasureSpec.EXACTLY) }
+                ?: MeasureSpec.makeMeasureSpec(max(maxWidth, 0), MeasureSpec.AT_MOST)
+            val heightSpec = contentHeight?.let { MeasureSpec.makeMeasureSpec(it, MeasureSpec.EXACTLY) }
+                ?: MeasureSpec.makeMeasureSpec(height, MeasureSpec.AT_MOST)
+            child.measure(widthSpec, heightSpec)
+            childWidth = child.measuredWidth
+        }
+        setMeasuredDimension(max(childWidth + 2 * side, minWidth), height)
+    }
+
+    override fun onLayout(changed: Boolean, l: Int, t: Int, r: Int, b: Int) {
+        val child = content ?: return
+        val left = (r - l - child.measuredWidth) / 2
+        val top = (b - t - child.measuredHeight) / 2
+        child.layout(left, top, left + child.measuredWidth, top + child.measuredHeight)
+    }
+
+    private companion object {
+        const val SIDE_DP = 12
+        const val MIN_WIDTH_DP = 48
+    }
+}

package/android/src/main/java/dev/apexnative/navigation/views/stack/topbar/titlebar/ButtonBar.kt

@@ -0,0 +1,334 @@
+package dev.apexnative.navigation.views.stack.topbar.titlebar
+
+import android.annotation.SuppressLint
+import android.content.Context
+import android.graphics.Color
+import android.graphics.Paint
+import android.graphics.Typeface
+import android.graphics.drawable.Drawable
+import android.text.SpannableString
+import android.text.Spanned
+import android.text.TextPaint
+import android.text.style.AbsoluteSizeSpan
+import android.text.style.ForegroundColorSpan
+import android.text.style.MetricAffectingSpan
+import android.transition.AutoTransition
+import android.transition.TransitionManager
+import android.util.TypedValue
+import android.view.Gravity
+import android.view.Menu
+import android.view.MenuItem
+import android.view.View
+import android.view.ViewGroup
+import androidx.appcompat.R as AppCompatR
+import androidx.appcompat.content.res.AppCompatResources
+import androidx.appcompat.view.menu.MenuView
+import androidx.appcompat.widget.ActionMenuView
+import androidx.appcompat.widget.PopupMenu
+import androidx.appcompat.widget.TooltipCompat
+import androidx.core.graphics.drawable.DrawableCompat
+import androidx.core.view.MenuItemCompat
+import com.google.android.material.appbar.MaterialToolbar
+import dev.apexnative.navigation.R
+import dev.apexnative.navigation.options.ButtonMenuOptions
+import dev.apexnative.navigation.options.ButtonOptions
+import dev.apexnative.navigation.options.parsers.TypefaceLoader
+import dev.apexnative.navigation.utils.MaterialTheme
+import dev.apexnative.navigation.utils.TestIds
+import dev.apexnative.navigation.utils.UiUtils
+import java.util.WeakHashMap
+
+/**
+ * The buttons of one side of the bar in its toolbar: each button a menu item — a text, an icon (on its background), or
+ * a React button's cell as the item's action view —, in the bar or in "⋮" as [set] says, with the `overflowMenu` items
+ * first in "⋮". A press sends the button's id; a button with a `menu` opens it under the button (in "⋮" or not laid
+ * out: at the bar's end), or on a long press with `menuOnLongPress`. The views of the items get their `testID`s after
+ * each layout of the toolbar, which makes them again. Main thread only.
+ */
+internal class ButtonBar(
+    private val toolbar: MaterialToolbar,
+    private val left: Boolean,
+    private val loadIcon: (String) -> Drawable?,
+    private val host: Host,
+) {
+    /** What the buttons tell the bar. */
+    interface Host {
+        /** The button [buttonId] was pressed. */
+        fun pressed(buttonId: String)
+
+        /** The item [itemId] of a menu was picked: of the button [buttonId], or of `overflowMenu` without one. */
+        fun picked(buttonId: String?, itemId: String)
+
+        /** The menu of the button [buttonId] as the screen's options give it now; none. */
+        fun menuOf(buttonId: String): ButtonMenuOptions?
+
+        /** The `testID` of an item the side holds besides its buttons (the search's magnifier); none. */
+        fun testIdOf(item: MenuItem): String? = null
+    }
+
+    /** One button as the bar shows it: its options with the side's colors on them, and its React cell if it has one. */
+    class Button(val options: ButtonOptions, val cell: BarButtonComponentCell?)
+
+    private val context: Context = toolbar.context
+    private val typefaces = TypefaceLoader(context)
+    private val itemIds = HashMap<MenuItem, ButtonOptions>()
+    private var overflowTestId: String? = null
+    private var popup: PopupMenu? = null
+    private var watched: ActionMenuView? = null
+    // The item views that have the long press of a menu.
+    private val hooked = WeakHashMap<View, Boolean>()
+
+    init {
+        toolbar.addOnLayoutChangeListener { _, _, _, _, _, _, _, _, _ -> applyViewIds() }
+    }
+
+    /**
+     * The buttons of the side: [inBar] in the bar, [inOverflow] in "⋮" (the right side; the left one keeps all in
+     * the bar), each in the list's order; [overflow], the items of `overflowMenu` (right side). [animated]: the change
+     * goes with an `AutoTransition` (`animateLeftButtons` / `animateRightButtons`).
+     */
+    fun set(inBar: List<Button>, inOverflow: List<Button>, overflow: ButtonMenuOptions?, animated: Boolean) {
+        if (animated && toolbar.isLaidOut) TransitionManager.beginDelayedTransition(toolbar, AutoTransition())
+        val menu = toolbar.menu
+        menu.clear()
+        itemIds.clear()
+        var order = 0
+        overflow?.let {
+            ButtonMenus.fill(context, menu, OVERFLOW_GROUP, 0, it, MenuItem.SHOW_AS_ACTION_NEVER, loadIcon) { id ->
+                host.picked(null, id)
+            }
+            order = it.items.size
+        }
+        overflowTestId = overflow?.testID
+        inOverflow.forEachIndexed { index, button -> add(menu, button, OVERFLOW_ORDER + order + index, false) }
+        inBar.forEachIndexed { index, button ->
+            // The first right button is the last of the line: the menu lays its items out in their order.
+            val place = if (left) index else inBar.size - 1 - index
+            add(menu, button, BAR_ORDER + place, true)
+        }
+        toolbar.post { applyViewIds() }
+    }
+
+    /** The color of "⋮" (`rightButtonColor`, else `colorOnSurfaceVariant`). */
+    fun setOverflowColor(color: Int) {
+        val icon = toolbar.overflowIcon ?: return
+        val tinted = DrawableCompat.wrap(icon.mutate())
+        DrawableCompat.setTint(tinted, color)
+        toolbar.overflowIcon = tinted
+    }
+
+    /** An open menu of the side closes: the bar shows another screen. */
+    fun closeMenus() {
+        popup?.dismiss()
+        popup = null
+        toolbar.dismissPopupMenus()
+    }
+
+    private fun add(menu: Menu, button: Button, order: Int, inBar: Boolean) {
+        val options = button.options
+        val id = options.id.get(null) ?: return
+        val item = menu.add(BUTTONS_GROUP, Menu.NONE, order, titleOf(options))
+        itemIds[item] = options
+        val enabled = !options.enabled.isFalse
+        item.isEnabled = enabled
+        if (inBar) {
+            item.setShowAsAction(MenuItem.SHOW_AS_ACTION_ALWAYS)
+        } else {
+            item.setShowAsAction(MenuItem.SHOW_AS_ACTION_NEVER)
+        }
+        val cell = button.cell
+        if (cell != null) {
+            item.actionView = cell
+            cell.contentDescription = options.accessibilityLabel.get(null)
+        } else {
+            iconOf(options, enabled)?.let { item.icon = it }
+            options.accessibilityLabel.get(null)?.let { MenuItemCompat.setContentDescription(item, it) }
+        }
+        item.setOnMenuItemClickListener {
+            val menuOptions = host.menuOf(id)
+            if (cell == null && menuOptions != null && !options.menuOnLongPress.isTrue) {
+                openMenu(id, menuOptions, viewOf(item))
+            } else if (cell == null) {
+                host.pressed(id)
+            }
+            true
+        }
+    }
+
+    // The text of a button: its font (missing weight or italic made synthetically), its size in sp, its color, its
+    // capitals (`allCaps`; Material 3's own text has none).
+    private fun titleOf(options: ButtonOptions): CharSequence {
+        val raw = options.text.get(null).orEmpty()
+        val text = if (options.allCaps.isTrue) raw.uppercase() else raw
+        if (text.isEmpty()) return text
+        val spannable = SpannableString(text)
+        val enabled = !options.enabled.isFalse
+        val color = if (enabled) options.color.get(context, null) else options.disabledColor.get(context, DISABLED)
+        color?.let { spannable.setSpan(ForegroundColorSpan(it), 0, text.length, Spanned.SPAN_EXCLUSIVE_EXCLUSIVE) }
+        if (options.fontSize.hasValue()) {
+            val size = TypedValue.applyDimension(
+                TypedValue.COMPLEX_UNIT_SP,
+                options.fontSize.get(0.0).toFloat(),
+                context.resources.displayMetrics,
+            )
+            spannable.setSpan(AbsoluteSizeSpan(size.toInt()), 0, text.length, Spanned.SPAN_EXCLUSIVE_EXCLUSIVE)
+        }
+        if (options.font.hasValue()) {
+            val typeface = options.font.getTypeface(typefaces, Typeface.DEFAULT)
+            val weight = options.font.fontWeight.get(null)
+            val bold = weight == "bold" || (weight?.toIntOrNull() ?: 0) >= BOLD_WEIGHT
+            val italic = options.font.fontStyle.get(null) == "italic"
+            spannable.setSpan(FontSpan(typeface, bold, italic), 0, text.length, Spanned.SPAN_EXCLUSIVE_EXCLUSIVE)
+        }
+        return spannable
+    }
+
+    /**
+     * The icon of a button: its own, or the library's close icon for `systemItem: 'close'`; tinted with `color`
+     * (disabled: `disabledColor`, light grey by default) unless `disableIconTint`, as it is without; on its background
+     * with an `iconBackground` color. None when it doesn't load (the button keeps its text).
+     */
+    private fun iconOf(options: ButtonOptions, enabled: Boolean): Drawable? {
+        val icon = when {
+            options.icon.hasValue() -> options.icon.get(null)?.let(loadIcon)
+            options.systemItem.get(null) == CLOSE -> AppCompatResources.getDrawable(context, R.drawable.apex_navigation_ic_close)
+            else -> null
+        }?.mutate() ?: return null
+        if (!options.disableIconTint.isTrue) {
+            val tint = if (enabled) options.color.get(context, null) else options.disabledColor.get(context, DISABLED)
+            tint?.let { DrawableCompat.setTint(icon, it) }
+        }
+        val background = options.iconBackground
+        if (!background.color.hasValue()) return icon
+        val color = (if (enabled) null else background.disabledColor.get(context, null))
+            ?: background.color.get(context, null)
+            ?: return icon
+        return IconBackgroundDrawable(
+            icon,
+            color,
+            UiUtils.dpToPx(context, background.cornerRadius.get(0.0).toFloat()),
+            UiUtils.dpToPx(context, background.width.get(0.0).toFloat()).toInt(),
+            UiUtils.dpToPx(context, background.height.get(0.0).toFloat()).toInt(),
+        )
+    }
+
+    // The menu of a button: Material's popup under the button, or at the bar's end.
+    private fun openMenu(buttonId: String, options: ButtonMenuOptions, anchor: View?) {
+        if (options.items.isEmpty()) return
+        popup?.dismiss()
+        val themed = MaterialTheme.context(context)
+        val menu = if (anchor != null) {
+            PopupMenu(themed, anchor)
+        } else {
+            PopupMenu(themed, toolbar, Gravity.END)
+        }
+        ButtonMenus.fill(themed, menu.menu, Menu.NONE, 0, options, null, loadIcon) { id -> host.picked(buttonId, id) }
+        menu.setOnDismissListener { if (popup === menu) popup = null }
+        popup = menu
+        menu.show()
+    }
+
+    // The view of [item] in the bar; none in "⋮" or before the bar laid it out.
+    private fun viewOf(item: MenuItem): View? {
+        val menuView = actionMenuView() ?: return null
+        for (index in 0 until menuView.childCount) {
+            val child = menuView.getChildAt(index)
+            if (itemOf(child) === item || item.actionView === child) return child
+        }
+        return null
+    }
+
+    private fun actionMenuView(): ActionMenuView? {
+        for (index in 0 until toolbar.childCount) {
+            val child = toolbar.getChildAt(index)
+            if (child is ActionMenuView) return child
+        }
+        return null
+    }
+
+    // AppCompat gives an item's view no public way back to its item: the item view's own interface, which only
+    // AppCompat's own views implement, is read and never changed.
+    @SuppressLint("RestrictedApi")
+    private fun itemOf(view: View): MenuItem? = (view as? MenuView.ItemView)?.itemData
+
+    // The `testID`s of the item views: the bar makes its views again, so after every layout; a view used again without
+    // one loses the one it had. "⋮" by AppCompat's description of it. A long press opens the menu of a button with
+    // `menuOnLongPress`: the handler finds the item by the view pressed.
+    private fun applyViewIds() {
+        val menuView = actionMenuView() ?: return
+        if (watched !== menuView) {
+            watched = menuView
+            menuView.setOnHierarchyChangeListener(object : ViewGroup.OnHierarchyChangeListener {
+                override fun onChildViewAdded(parent: View?, child: View?) {
+                    toolbar.post { applyViewIds() }
+                }
+
+                override fun onChildViewRemoved(parent: View?, child: View?) = Unit
+            })
+        }
+        val overflowDescription = context.getString(AppCompatR.string.abc_action_menu_overflow_description)
+        for (index in 0 until menuView.childCount) {
+            val child = menuView.getChildAt(index)
+            val item = itemOf(child) ?: itemIds.keys.firstOrNull { it.actionView === child }
+            val options = item?.let(itemIds::get)
+            when {
+                options != null -> {
+                    TestIds.apply(child, options.testID.get(null))
+                    if (child !is BarButtonComponentCell) longPressOf(child, options)
+                }
+                child.contentDescription == overflowDescription -> TestIds.apply(child, overflowTestId)
+                item != null -> TestIds.apply(child, host.testIdOf(item))
+                else -> Unit
+            }
+        }
+    }
+
+    // The toolbar uses its item views again for other items: the handler finds the button by the view pressed, at the
+    // press, and a view that no longer needs it gets the toolbar's tooltip back.
+    private fun longPressOf(view: View, options: ButtonOptions) {
+        val id = options.id.get(null)
+        if (id != null && options.menuOnLongPress.isTrue && host.menuOf(id) != null) {
+            hooked[view] = true
+            view.setOnLongClickListener { pressed -> openOnLongPress(pressed) }
+            return
+        }
+        if (hooked.remove(view) == null) return
+        view.setOnLongClickListener(null)
+        itemOf(view)?.let { TooltipCompat.setTooltipText(view, MenuItemCompat.getTooltipText(it) ?: it.title) }
+    }
+
+    private fun openOnLongPress(pressed: View): Boolean {
+        val options = itemOf(pressed)?.let(itemIds::get) ?: return false
+        val id = options.id.get(null) ?: return false
+        if (!options.menuOnLongPress.isTrue) return false
+        val menu = host.menuOf(id) ?: return false
+        openMenu(id, menu, pressed)
+        return true
+    }
+
+    // A font of the options on a button's text, with the weight and the slant the typeface lacks drawn synthetically.
+    private class FontSpan(private val typeface: Typeface?, private val bold: Boolean, private val italic: Boolean) :
+        MetricAffectingSpan() {
+        override fun updateDrawState(paint: TextPaint) = apply(paint)
+
+        override fun updateMeasureState(paint: TextPaint) = apply(paint)
+
+        private fun apply(paint: Paint) {
+            val face = typeface ?: return
+            paint.typeface = face
+            if (bold && !face.isBold) paint.isFakeBoldText = true
+            if (italic && !face.isItalic) paint.textSkewX = ITALIC_SKEW
+        }
+    }
+
+    private companion object {
+        const val BUTTONS_GROUP = 1
+        const val OVERFLOW_GROUP = 2
+        const val OVERFLOW_ORDER = 100
+        const val BAR_ORDER = 1000
+        const val CLOSE = "close"
+        const val BOLD_WEIGHT = 600
+        const val ITALIC_SKEW = -0.25f
+        val DISABLED = Color.LTGRAY
+    }
+}

package/android/src/main/java/dev/apexnative/navigation/views/stack/topbar/titlebar/ButtonMenus.kt

@@ -0,0 +1,106 @@
+package dev.apexnative.navigation.views.stack.topbar.titlebar
+
+import android.annotation.SuppressLint
+import android.content.Context
+import android.graphics.Color
+import android.graphics.drawable.Drawable
+import android.text.SpannableString
+import android.text.Spanned
+import android.text.style.ForegroundColorSpan
+import android.view.Menu
+import android.view.MenuItem
+import androidx.appcompat.view.menu.MenuBuilder
+import com.google.android.material.color.MaterialColors
+import dev.apexnative.navigation.options.ButtonMenuOptions
+import dev.apexnative.navigation.utils.MaterialTheme
+import androidx.appcompat.R as AppCompatR
+import com.google.android.material.R as MaterialR
+
+/**
+ * Puts the items of a bar menu (the overflow menu, the menu of a button) into an Android menu: their titles and icons,
+ * the destructive ones red, the checked ones with a checkmark. A pick of an item calls `onPick` with its id; with
+ * `singleSelection` the checkmark moves to it in the open menu, and the caller writes it into the screen's options.
+ */
+object ButtonMenus {
+    fun fill(
+        context: Context,
+        menu: Menu,
+        group: Int,
+        firstOrder: Int,
+        options: ButtonMenuOptions,
+        showAsAction: Int?,
+        loadIcon: (String) -> Drawable?,
+        onPick: (String) -> Unit,
+    ) {
+        addElements(context, menu, group, firstOrder, options.items, options.singleSelection, showAsAction, loadIcon, onPick)
+    }
+
+    private fun addElements(
+        context: Context,
+        menu: Menu,
+        group: Int,
+        firstOrder: Int,
+        elements: List<ButtonMenuOptions.Element>,
+        singleSelection: Boolean,
+        showAsAction: Int?,
+        loadIcon: (String) -> Drawable?,
+        onPick: (String) -> Unit,
+    ) {
+        val submenus = mutableListOf<MenuItem>()
+        elements.forEachIndexed { index, element ->
+            val order = firstOrder + index
+            val item = when (element) {
+                is ButtonMenuOptions.Submenu -> menu.addSubMenu(group, Menu.NONE, order, element.title).also {
+                    addElements(context, it, group, 0, element.items, element.singleSelection, null, loadIcon, onPick)
+                }.item.also { submenus += it }
+                is ButtonMenuOptions.Item -> menu.add(group, Menu.NONE, order, title(context, element)).apply {
+                    isEnabled = !element.disabled
+                    if (singleSelection || element.checked) {
+                        isCheckable = true
+                        isChecked = element.checked
+                    }
+                    setOnMenuItemClickListener { picked ->
+                        if (singleSelection) picked.isChecked = true
+                        onPick(element.id)
+                        true
+                    }
+                }
+            }
+            val destructive = element is ButtonMenuOptions.Item && element.destructive
+            val tint = if (destructive) errorColor(context) else iconColor(context)
+            element.icon?.let { uri -> item.icon = loadIcon(uri)?.mutate()?.also { it.setTint(tint) } }
+            if (showAsAction != null) item.setShowAsAction(showAsAction)
+        }
+        if (singleSelection) {
+            menu.setGroupCheckable(group, true, true)
+            // The group made the submenus checkable too: they open, and have no checkmark.
+            submenus.forEach { it.isCheckable = false }
+        }
+        if (elements.any { it.icon != null }) showIcons(menu)
+    }
+
+    /** Some item of the menu, or of a submenu, has an icon. */
+    fun hasIcons(options: ButtonMenuOptions): Boolean = hasIcons(options.items)
+
+    private fun hasIcons(elements: List<ButtonMenuOptions.Element>): Boolean =
+        elements.any { it.icon != null || (it is ButtonMenuOptions.Submenu && hasIcons(it.items)) }
+
+    // Material's menus have their icons at the start of the items; the toolbar's menus leave them out by default.
+    @SuppressLint("RestrictedApi")
+    private fun showIcons(menu: Menu) {
+        (menu as? MenuBuilder)?.setOptionalIconsVisible(true)
+    }
+
+    private fun title(context: Context, item: ButtonMenuOptions.Item): CharSequence {
+        if (!item.destructive) return item.title
+        return SpannableString(item.title).apply {
+            setSpan(ForegroundColorSpan(errorColor(context)), 0, length, Spanned.SPAN_EXCLUSIVE_EXCLUSIVE)
+        }
+    }
+
+    private fun errorColor(context: Context) =
+        MaterialColors.getColor(MaterialTheme.context(context), AppCompatR.attr.colorError, Color.RED)
+
+    private fun iconColor(context: Context) =
+        MaterialColors.getColor(MaterialTheme.context(context), MaterialR.attr.colorOnSurfaceVariant, Color.GRAY)
+}