@apexnative/navigation 1.0.0-alpha.6 → 1.0.0-alpha.8

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

@@ -1,15 +1,11 @@
 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
@@ -17,78 +13,52 @@ 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.
+ * Turns the items of a bar menu (the overflow menu, the menu of a button) into the entries of a [BarMenu]: their
+ * titles and icons, the destructive ones red, the checked ones with a check mark, the items of a `singleSelection` menu
+ * with radio buttons. Icons take `textColor` (`topBar.menuTextColor`), else the theme's on-surface-variant color. A
+ * pick of an item calls `onPick` with its id; the caller writes a `singleSelection` choice into the screen's options.
  */
-object ButtonMenus {
-    fun fill(
+internal object ButtonMenus {
+    fun entries(
         context: Context,
-        menu: Menu,
-        group: Int,
-        firstOrder: Int,
         options: ButtonMenuOptions,
-        showAsAction: Int?,
+        textColor: Int?,
         loadIcon: (String) -> Drawable?,
         onPick: (String) -> Unit,
-    ) {
-        addElements(context, menu, group, firstOrder, options.items, options.singleSelection, showAsAction, loadIcon, onPick)
-    }
+    ): List<BarMenu.Entry> = entriesOf(context, options.items, options.singleSelection, textColor, loadIcon, onPick)
 
-    private fun addElements(
+    private fun entriesOf(
         context: Context,
-        menu: Menu,
-        group: Int,
-        firstOrder: Int,
         elements: List<ButtonMenuOptions.Element>,
         singleSelection: Boolean,
-        showAsAction: Int?,
+        textColor: 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 }
+    ): List<BarMenu.Entry> = elements.map { element ->
+        val destructive = element is ButtonMenuOptions.Item && element.destructive
+        val tint = if (destructive) errorColor(context) else textColor ?: iconColor(context)
+        val icon = element.icon?.let(loadIcon)?.mutate()?.also { it.setTint(tint) }
+        when (element) {
+            is ButtonMenuOptions.Submenu -> BarMenu.Entry(
+                element.title,
+                icon,
+                submenu = entriesOf(context, element.items, element.singleSelection, textColor, loadIcon, onPick),
+                testId = element.testID,
+            )
+            is ButtonMenuOptions.Item -> BarMenu.Entry(
+                title(context, element),
+                icon,
+                enabled = !element.disabled,
+                check = when {
+                    singleSelection -> BarMenu.Check.Radio
+                    element.checked -> BarMenu.Check.Box
+                    else -> BarMenu.Check.None
+                },
+                checked = element.checked,
+                testId = element.testID,
+                onPick = { onPick(element.id) },
+            )
         }
-        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 {

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

@@ -0,0 +1,216 @@
+package dev.apexnative.navigation.views.stack.topbar.titlebar
+
+import android.annotation.SuppressLint
+import android.content.Context
+import android.content.res.ColorStateList
+import android.graphics.drawable.Drawable
+import android.view.MotionEvent
+import android.view.View
+import android.view.ViewGroup
+import androidx.appcompat.R as AppCompatR
+import androidx.appcompat.widget.AppCompatImageButton
+import androidx.appcompat.widget.AppCompatImageView
+import androidx.appcompat.widget.TooltipCompat
+import androidx.core.graphics.drawable.DrawableCompat
+import androidx.core.widget.ImageViewCompat
+import com.google.android.material.R as MaterialR
+import com.google.android.material.theme.overlay.MaterialThemeOverlay
+import dev.apexnative.navigation.utils.MaterialTheme
+import dev.apexnative.navigation.utils.UiUtils
+import kotlin.math.max
+import kotlin.math.min
+import kotlin.math.roundToInt
+
+/**
+ * The buttons of one side of the bar's row, from the start of the line: the back button ([navigationIcon]), the
+ * buttons ([setButtons]), what the core always puts after them ([setTrailing]: the search's magnifier) and "⋮"
+ * ([overflowButton]). They stand in the middle of the row, at most 56 dp high, as a Material 3 toolbar stands its
+ * buttons, with the toolbar's theme (its ripples); right to left the line mirrors. Main thread only.
+ */
+@SuppressLint("ViewConstructor")
+class ButtonRow(context: Context) : ViewGroup(themed(context)) {
+    private val maxButtonHeight = UiUtils.dpToPx(this.context, MAX_BUTTON_HEIGHT_DP).roundToInt()
+    private var navigation: AppCompatImageButton? = null
+    private var buttons: List<View> = emptyList()
+    private var trailing: View? = null
+    private var overflow: OverflowButton? = null
+    private var overflowColor: Int? = null
+
+    /** The back button's icon; none hides the button. */
+    var navigationIcon: Drawable?
+        get() = navigation?.takeIf { it.visibility == VISIBLE }?.drawable
+        set(value) {
+            if (value == null) {
+                navigation?.let {
+                    it.setImageDrawable(null)
+                    it.visibility = GONE
+                }
+                return
+            }
+            val button = navigation ?: AppCompatImageButton(context, null, AppCompatR.attr.toolbarNavigationButtonStyle)
+                .also {
+                    navigation = it
+                    arrange()
+                }
+            button.setImageDrawable(value)
+            button.visibility = VISIBLE
+        }
+
+    /** The back button's label: its accessibility label and tooltip. */
+    var navigationContentDescription: CharSequence?
+        get() = navigation?.contentDescription
+        set(value) {
+            val button = navigation ?: return
+            button.contentDescription = value
+            TooltipCompat.setTooltipText(button, value)
+        }
+
+    /** The back button's view while it shows; none. */
+    val navigationButton: View?
+        get() = navigation?.takeIf { it.visibility == VISIBLE }
+
+    private var navigationListener: OnClickListener? = null
+
+    /** What a press of the back button does. */
+    fun setNavigationOnClickListener(listener: OnClickListener?) {
+        navigationListener = listener
+        navigation?.setOnClickListener(listener)
+    }
+
+    /** The buttons, in the line's order from its start. A view in another parent moves here. */
+    fun setButtons(views: List<View>) {
+        buttons = views
+        arrange()
+    }
+
+    /** What stands after the buttons, before "⋮"; none. */
+    fun setTrailing(view: View?) {
+        if (trailing === view) return
+        trailing = view
+        arrange()
+    }
+
+    /** What stands after the buttons now. */
+    val trailingView: View?
+        get() = trailing
+
+    /**
+     * "⋮", made the first time it is asked for and shown with [setOverflowShown]: the theme's
+     * `actionOverflowButtonStyle`, labelled "More options" in the user's language.
+     */
+    val overflowButton: View
+        get() = overflow ?: OverflowButton(context).also {
+            it.visibility = GONE
+            overflowColor?.let { color -> ImageViewCompat.setImageTintList(it, ColorStateList.valueOf(color)) }
+            overflow = it
+            arrange()
+        }
+
+    /** "⋮" shows at the end of the line, or not. */
+    fun setOverflowShown(shown: Boolean) {
+        if (!shown && overflow == null) return
+        overflowButton.visibility = if (shown) VISIBLE else GONE
+    }
+
+    /** The color of "⋮", now or once it is made. */
+    fun setOverflowColor(color: Int) {
+        overflowColor = color
+        overflow?.let { ImageViewCompat.setImageTintList(it, ColorStateList.valueOf(color)) }
+    }
+
+    // The children in the line's order, so accessibility reads them in it too; a view that stays where it is isn't
+    // moved, which would detach it.
+    private fun arrange() {
+        val wanted = listOfNotNull(navigation) + buttons + listOfNotNull(trailing, overflow)
+        for (index in childCount - 1 downTo 0) {
+            if (getChildAt(index) !in wanted) removeViewAt(index)
+        }
+        wanted.forEachIndexed { index, view ->
+            if (index < childCount && getChildAt(index) === view) return@forEachIndexed
+            (view.parent as? ViewGroup)?.removeView(view)
+            addView(view, index, LayoutParams(LayoutParams.WRAP_CONTENT, LayoutParams.WRAP_CONTENT))
+        }
+        navigation?.setOnClickListener(navigationListener)
+    }
+
+    // As a toolbar, the row takes the touches around its buttons: they don't reach a screen under the bar.
+    @SuppressLint("ClickableViewAccessibility")
+    override fun onTouchEvent(event: MotionEvent?): Boolean = true
+
+    override fun onMeasure(widthMeasureSpec: Int, heightMeasureSpec: Int) {
+        val height = MeasureSpec.getSize(heightMeasureSpec)
+        val widthMode = MeasureSpec.getMode(widthMeasureSpec)
+        val widthSize = MeasureSpec.getSize(widthMeasureSpec)
+        val buttonHeight = min(height, maxButtonHeight)
+        var used = 0
+        for (index in 0 until childCount) {
+            val child = getChildAt(index)
+            if (child.visibility == GONE) continue
+            val widthSpec = if (widthMode == MeasureSpec.UNSPECIFIED) {
+                MeasureSpec.makeMeasureSpec(0, MeasureSpec.UNSPECIFIED)
+            } else {
+                MeasureSpec.makeMeasureSpec(max(widthSize - used, 0), MeasureSpec.AT_MOST)
+            }
+            // The back button takes the whole height a toolbar gives its buttons; the others as much as they need.
+            val heightMode = if (child === navigation) MeasureSpec.EXACTLY else MeasureSpec.AT_MOST
+            child.measure(widthSpec, MeasureSpec.makeMeasureSpec(buttonHeight, heightMode))
+            used += child.measuredWidth
+        }
+        setMeasuredDimension(resolveSize(used, widthMeasureSpec), height)
+    }
+
+    override fun onLayout(changed: Boolean, l: Int, t: Int, r: Int, b: Int) {
+        val width = r - l
+        val height = b - t
+        val rtl = layoutDirection == LAYOUT_DIRECTION_RTL
+        var start = 0
+        for (index in 0 until childCount) {
+            val child = getChildAt(index)
+            if (child.visibility == GONE) continue
+            val w = child.measuredWidth
+            val x = if (rtl) width - start - w else start
+            val top = (height - child.measuredHeight) / 2
+            child.layout(x, top, x + w, top + child.measuredHeight)
+            start += w
+        }
+    }
+
+    // "⋮" as a toolbar draws it: its ripple a square around the icon, its label as its tooltip.
+    @SuppressLint("ViewConstructor")
+    private class OverflowButton(context: Context) :
+        AppCompatImageView(context, null, AppCompatR.attr.actionOverflowButtonStyle) {
+        init {
+            isClickable = true
+            isFocusable = true
+            TooltipCompat.setTooltipText(this, contentDescription)
+        }
+
+        override fun onSizeChanged(w: Int, h: Int, oldw: Int, oldh: Int) {
+            super.onSizeChanged(w, h, oldw, oldh)
+            val background = background ?: return
+            if (drawable == null) return
+            val half = max(w, h) / 2
+            val centerX = (w + paddingLeft - paddingRight) / 2
+            val centerY = (h + paddingTop - paddingBottom) / 2
+            DrawableCompat.setHotspotBounds(background, centerX - half, centerY - half, centerX + half, centerY + half)
+        }
+    }
+
+    private companion object {
+        // A toolbar's `maxButtonHeight`.
+        const val MAX_BUTTON_HEIGHT_DP = 56f
+
+        // The theme a Material 3 toolbar gives its buttons (`toolbarStyle`'s overlay: its ripples), kept in the
+        // current light or dark mode.
+        fun themed(context: Context): Context {
+            val wrapped = MaterialThemeOverlay.wrap(
+                context,
+                null,
+                AppCompatR.attr.toolbarStyle,
+                MaterialR.style.Widget_Material3_Toolbar,
+            )
+            if (wrapped !== context) MaterialTheme.followOverlay(wrapped)
+            return wrapped
+        }
+    }
+}

package/android/src/main/jni/ANNContentHeights.cpp

@@ -0,0 +1,82 @@
+// The height of React content laid out at a width without a height limit, for the Kotlin side
+// (`dev.apexnative.navigation.react.ContentHeights`): a sheet with the 'content' detent. Fabric lays out a copy of the
+// tree for it, so the shown layout stays as it is: a React root's surface here, a slot's content in the slot's own
+// layout (`ANNSlotShadowNode`), which keeps the height in `ANNSlotContentHeights`.
+
+#include <fbjni/fbjni.h>
+#include <jni.h>
+#include <react/fabric/SurfaceHandlerBinding.h>
+#include <react/renderer/components/ApexNavigationSpec/ANNSlotState.h>
+#include <react/renderer/core/LayoutConstraints.h>
+#include <react/renderer/core/LayoutContext.h>
+
+#include <limits>
+
+using namespace facebook;
+
+namespace {
+
+std::string slotIdOf(jstring slotId) {
+    return slotId ? jni::wrap_alias(slotId)->toStdString() : std::string{};
+}
+
+// A React root's surface: React Native keeps the getter of its surface handler unmangled for the native side.
+struct JReactSurfaceImpl : jni::JavaClass<JReactSurfaceImpl> {
+    static constexpr auto kJavaDescriptor = "Lcom/facebook/react/runtime/ReactSurfaceImpl;";
+
+    const react::SurfaceHandler &surfaceHandler() const {
+        static const auto method =
+            javaClassStatic()->getMethod<react::SurfaceHandlerBinding::javaobject()>("getSurfaceHandler");
+        return method(self())->cthis()->getSurfaceHandler();
+    }
+};
+
+} // namespace
+
+/**
+ * The height of the surface's content at [width] points without a height limit, in points: `SurfaceHandler::measure`,
+ * as iOS's surface measures for `sizeThatFits`. 0 for a surface that doesn't run; -1 on a failure.
+ */
+extern "C" JNIEXPORT jfloat JNICALL Java_dev_apexnative_navigation_react_ContentHeights_nativeSurfaceHeight(
+    JNIEnv * /*env*/, jclass /*type*/, jobject surface, jfloat width, jfloat pointScale, jfloat fontScale, jboolean rtl,
+    jboolean swapLeftAndRight) {
+    try {
+        auto ref = jni::wrap_alias(static_cast<JReactSurfaceImpl::javaobject>(surface));
+        react::LayoutConstraints constraints{};
+        constraints.minimumSize = react::Size{.width = width, .height = 0};
+        constraints.maximumSize = react::Size{.width = width, .height = std::numeric_limits<react::Float>::infinity()};
+        constraints.layoutDirection = rtl ? react::LayoutDirection::RightToLeft : react::LayoutDirection::LeftToRight;
+        react::LayoutContext context{};
+        context.pointScaleFactor = pointScale;
+        context.fontSizeMultiplier = fontScale;
+        context.swapLeftAndRightInRTL = swapLeftAndRight;
+        return ref->surfaceHandler().measure(constraints, context).height;
+    } catch (...) {
+        jni::translatePendingCppExceptionToJavaException();
+        return -1;
+    }
+}
+
+/** The slot's content is measured from its next layout on (`ANNSlotContentHeights::request`). */
+extern "C" JNIEXPORT void JNICALL Java_dev_apexnative_navigation_react_ContentHeights_nativeRequestSlot(
+    JNIEnv * /*env*/, jclass /*type*/, jstring slotId) {
+    react::ANNSlotContentHeights::request(slotIdOf(slotId));
+}
+
+/** Whether the slot's content is measured. */
+extern "C" JNIEXPORT jboolean JNICALL Java_dev_apexnative_navigation_react_ContentHeights_nativeIsSlotRequested(
+    JNIEnv * /*env*/, jclass /*type*/, jstring slotId) {
+    return react::ANNSlotContentHeights::isRequested(slotIdOf(slotId));
+}
+
+/** The height of the slot's content at its last layout, in points; negative before it. */
+extern "C" JNIEXPORT jfloat JNICALL Java_dev_apexnative_navigation_react_ContentHeights_nativeSlotHeight(
+    JNIEnv * /*env*/, jclass /*type*/, jstring slotId) {
+    return react::ANNSlotContentHeights::height(slotIdOf(slotId));
+}
+
+/** The slot's screen went: nothing more is measured for it. */
+extern "C" JNIEXPORT void JNICALL Java_dev_apexnative_navigation_react_ContentHeights_nativeForgetSlot(
+    JNIEnv * /*env*/, jclass /*type*/, jstring slotId) {
+    react::ANNSlotContentHeights::forget(slotIdOf(slotId));
+}

package/android/src/main/res/drawable/apex_navigation_ic_arrow_right.xml

@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Material Icons "arrow_right" (Apache 2.0, android/MATERIAL_SYMBOLS_LICENSE.txt): the arrow of a submenu item in a
+top bar menu, mirrored right to left. -->
+<vector xmlns:android="http://schemas.android.com/apk/res/android"
+    android:width="24dp"
+    android:height="24dp"
+    android:autoMirrored="true"
+    android:tint="?attr/colorControlNormal"
+    android:viewportWidth="24"
+    android:viewportHeight="24">
+    <path
+        android:fillColor="@android:color/white"
+        android:pathData="M10,17l5,-5 -5,-5v10z" />
+</vector>

package/android/src/main/res/layout/apex_navigation_menu_header.xml

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- The title over the items of a submenu of a top bar menu (BarMenu), as AppCompat shows a submenu's title. -->
+<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
+    android:layout_width="match_parent"
+    android:layout_height="?attr/listPreferredItemHeightSmall"
+    android:minWidth="196dp"
+    android:paddingStart="16dp"
+    android:paddingEnd="16dp">
+
+    <TextView
+        android:id="@+id/apex_navigation_menu_title"
+        android:layout_width="match_parent"
+        android:layout_height="wrap_content"
+        android:layout_gravity="center_vertical"
+        android:ellipsize="end"
+        android:singleLine="true"
+        android:textAlignment="viewStart"
+        android:textAppearance="?attr/textAppearancePopupMenuHeader" />
+</FrameLayout>

package/android/src/main/res/layout/apex_navigation_menu_item.xml

@@ -0,0 +1,68 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+An item of a menu of the top bar (BarMenu), as AppCompat lays out a popup menu's item: the icon, the title, the
+submenu's arrow, the check mark of a checkable item. The inflater of the activity turns the check box and the radio
+button into Material ones, as it does for AppCompat's menus.
+-->
+<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
+    android:layout_width="match_parent"
+    android:layout_height="?attr/listPreferredItemHeightSmall"
+    android:gravity="center_vertical"
+    android:minWidth="196dp"
+    android:orientation="horizontal"
+    android:paddingEnd="16dp">
+
+    <ImageView
+        android:id="@+id/apex_navigation_menu_icon"
+        android:layout_width="wrap_content"
+        android:layout_height="wrap_content"
+        android:layout_marginStart="8dp"
+        android:layout_marginTop="8dp"
+        android:layout_marginEnd="-8dp"
+        android:layout_marginBottom="8dp"
+        android:duplicateParentState="true"
+        android:importantForAccessibility="no"
+        android:scaleType="centerInside"
+        android:visibility="gone" />
+
+    <TextView
+        android:id="@+id/apex_navigation_menu_title"
+        android:layout_width="0dp"
+        android:layout_height="wrap_content"
+        android:layout_marginStart="16dp"
+        android:layout_weight="1"
+        android:duplicateParentState="true"
+        android:ellipsize="end"
+        android:singleLine="true"
+        android:textAlignment="viewStart"
+        android:textAppearance="?attr/textAppearanceLargePopupMenu" />
+
+    <ImageView
+        android:id="@+id/apex_navigation_menu_arrow"
+        android:layout_width="wrap_content"
+        android:layout_height="wrap_content"
+        android:layout_marginStart="8dp"
+        android:duplicateParentState="true"
+        android:importantForAccessibility="no"
+        android:scaleType="center"
+        android:src="@drawable/apex_navigation_ic_arrow_right"
+        android:visibility="gone" />
+
+    <CheckBox
+        android:id="@+id/apex_navigation_menu_check"
+        android:layout_width="wrap_content"
+        android:layout_height="wrap_content"
+        android:clickable="false"
+        android:duplicateParentState="true"
+        android:focusable="false"
+        android:visibility="gone" />
+
+    <RadioButton
+        android:id="@+id/apex_navigation_menu_radio"
+        android:layout_width="wrap_content"
+        android:layout_height="wrap_content"
+        android:clickable="false"
+        android:duplicateParentState="true"
+        android:focusable="false"
+        android:visibility="gone" />
+</LinearLayout>

package/android/src/main/res/values/styles.xml

@@ -8,7 +8,7 @@
     <style name="ThemeOverlay.ApexNavigation.TopBar" parent="ThemeOverlay.Material3.Toolbar.Surface" />
 
     <!--
-    The popup theme of the bar's toolbars, for the "⋮" menu, when the app's Material 3 theme is fixed to light or to
+    The popup theme of the bar's "⋮" menu, when the app's Material 3 theme is fixed to light or to
     dark and doesn't follow the device's mode: a day/night overlay that gives the menu Material 3's colors of the
     current mode where the app's theme shows the other one, and leaves the app's colors in the mode it shows
     (values-night has the dark side). An app theme that follows the mode needs none: the menu takes the bar's theme.

package/android/src/main/res/values-night/styles.xml

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <resources>
-    <!-- The popup themes of the bar's toolbars in dark mode: see values/styles.xml. -->
+    <!-- The popup themes of the bar's "⋮" in dark mode: see values/styles.xml. -->
     <style name="ThemeOverlay.ApexNavigation.TopBar.PopupOverLight" parent="ThemeOverlay.Material3.Dark" />
     <style name="ThemeOverlay.ApexNavigation.TopBar.PopupOverDark" parent="" />
 </resources>

package/cli/doctor/checks/app.js

@@ -100,11 +100,12 @@ function appChecks({ root, run }) {
   const project = findProject(root, run);
   const plans = planProject(project);
   const app = plans.find(({ file }) => file !== undefined && file === project.app);
+  const metro = plans.find(({ file }) => file !== undefined && file === project.metroConfig);
   const manifest = plans.find(({ file }) => file !== undefined && file === project.manifest);
   const native = plans.filter((plan) => plan.platform !== 'js' && plan !== manifest);
   const types = plans.filter(({ name }) => name === ENV_FILE || name === 'tsconfig.json');
   const entry = plans.filter(
-    (plan) => plan.platform === 'js' && plan !== app && !types.includes(plan)
+    (plan) => plan.platform === 'js' && plan !== app && plan !== metro && !types.includes(plan)
   );
   checks.push(filesCheck('Native files', native), filesCheck('Entry point', entry));
   const typed = typesCheck(root, types);
@@ -120,6 +121,20 @@ function appChecks({ root, run }) {
     });
   }
 
+  // Without the navigation's Metro setup an edit that isn't a boundary of Fast Refresh reloads the app.
+  if (metro && metro.status !== 'done') {
+    checks.push({
+      group: 'app',
+      title: 'Fast Refresh',
+      status: 'warn',
+      detail: `${metro.name} doesn't use withApexNavigation: some edits reload the app`,
+      fix:
+        metro.status === 'manual'
+          ? { label: 'Wrap the config metro.config.js exports in withApexNavigation' }
+          : SETUP,
+    });
+  }
+
   // Predictive back is optional: without it the navigation works, and Android plays no back animation of its own.
   if (manifest && manifest.status !== 'done') {
     checks.push({

package/cli/project.js

@@ -22,6 +22,7 @@ const { exec } = require('./exec');
  *   infoPlist?: string;
  *   entry?: string;
  *   app?: string;
+ *   metroConfig?: string;
  *   typescript: boolean;
  *   xcodeProject?: string;
  *   androidPackage?: string;
@@ -75,6 +76,9 @@ function findProject(root, run = exec) {
     app: ['App.tsx', 'App.ts', 'App.jsx', 'App.js']
       .map((name) => path.join(root, name))
       .find((file) => fs.existsSync(file)),
+    metroConfig: ['metro.config.js', 'metro.config.cjs']
+      .map((name) => path.join(root, name))
+      .find((file) => fs.existsSync(file)),
     typescript: ['App.tsx', 'App.ts', 'tsconfig.json'].some((name) =>
       fs.existsSync(path.join(root, name))
     ),

package/cli/setup/index.js

@@ -16,6 +16,7 @@ const { planEntry, navigationFile, HOW_TO: ENTRY_HOW_TO } = require('./steps/ent
 const { planEnv, targetOf } = require('./steps/env');
 const { planInfoPlist } = require('./steps/infoPlist');
 const { planMainActivity } = require('./steps/mainActivity');
+const { planMetro } = require('./steps/metro');
 const { planSceneDelegate } = require('./steps/sceneDelegate');
 const { planMainApplication } = require('./steps/mainApplication');
 const { planManifest } = require('./steps/manifest');
@@ -134,6 +135,10 @@ function planProject(project) {
   plans.push(...planEnv(project.root, navigation, ts));
   // The template's App renders React Native's status bar; one moved elsewhere or written anew has nothing to change.
   if (project.app) plans.push(planFile('App.tsx', 'js', project.app, planApp, APP_HOW_TO));
+  // Fast Refresh for every edit; an app without a Metro config of its own has nothing to change.
+  if (project.metroConfig) {
+    plans.push(planFile('metro.config.js', 'js', project.metroConfig, planMetro, ''));
+  }
   return plans;
 }