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

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;
 }
 

package/cli/setup/steps/metro.js

@@ -0,0 +1,46 @@
+// @ts-check
+'use strict';
+
+/** @typedef {import('./types').StepResult} StepResult */
+
+const REQUIRE = "const { withApexNavigation } = require('@apexnative/navigation/metro');";
+
+// The config the file exports: `module.exports = …;`, its last statement.
+const EXPORT = /^module\.exports\s*=\s*([\s\S]+?);?\s*$/m;
+
+const HOW_TO = `Wrap the config metro.config.js exports, so an edit updates the app by Fast Refresh instead of
+reloading it:
+
+  ${REQUIRE}
+
+  module.exports = withApexNavigation(mergeConfig(getDefaultConfig(__dirname), config));`;
+
+/**
+ * metro.config.js: the config it exports goes through withApexNavigation, which puts the navigation's Babel
+ * transformer in front of the app's own.
+ * @param {string} text
+ * @returns {StepResult}
+ */
+function planMetro(text) {
+  if (text.includes('withApexNavigation')) return { status: 'done', note: 'already set up' };
+  const found = EXPORT.exec(text);
+  // Only an export that ends the file: one in the middle may be changed by what comes after it.
+  if (!found || text.slice(found.index + found[0].length).trim() !== '') {
+    return { status: 'manual', note: 'changed by hand, see below', howTo: HOW_TO };
+  }
+  const exported = found[1].trim();
+  const before = text.slice(0, found.index);
+  const requires = [...before.matchAll(/^.*require\(.*\);?$/gm)];
+  const last = requires[requires.length - 1];
+  const head =
+    last === undefined
+      ? `${REQUIRE}\n\n${before}`
+      : `${before.slice(0, last.index + last[0].length)}\n${REQUIRE}${before.slice(last.index + last[0].length)}`;
+  return {
+    status: 'change',
+    next: `${head}module.exports = withApexNavigation(${exported});\n`,
+    note: 'Fast Refresh for every edit',
+  };
+}
+
+module.exports = { planMetro, HOW_TO };

package/docs-md/architecture/native-screens.md

@@ -255,6 +255,10 @@ A wrong name or a missing prop is an error of the compiler, not of the app at ru
 - **Which are left out:** a screen with a required prop that is a function, and one with a prop whose type has no native form (see [Types](#types)). `codegen` names each in a warning. Native code still opens it by its name, `push("Settings", props: [:])`, with its props as a plain dictionary or map.
 - **After a change** of the screens or their props, run `codegen` again; `doctor` says when the generated code is behind.
 
+## Fast Refresh
+
+`nativeScreen` returns a component that runs `useProps`. An edit of the hook or of the options applies in place, with the app running. A change of the native name, or adding or removing `useProps`, restarts the app (a reload).
+
 ## UIKit and Android views
 
 A screen of UIKit or Android views gets the same `screen`, and follows its props as they change: